feat(#172): Implement Herald status updates
Implements status broadcasting via bridge module to chat channels. The Herald service subscribes to job events and broadcasts status updates to Discord threads using PDA-friendly language. Features: - Herald module with HeraldService for status broadcasting - Subscribe to job lifecycle, step lifecycle, and gate events - Format messages with PDA-friendly language (no "FAILED", "URGENT", etc.) - Visual indicators for quick scanning (🟢, 🔵, ✅, ⚠️, ⏸️) - Channel selection logic via workspace settings - Route to Discord threads based on job metadata - Comprehensive unit tests (14 tests passing, 85%+ coverage) Message format examples: - Job created: 🟢 Job created for #42 - Job started: 🔵 Job started for #42 - Job completed: ✅ Job completed for #42 (120s) - Job failed: ⚠️ Job encountered an issue for #42 - Gate passed: ✅ Gate passed: build - Gate failed: ⚠️ Gate needs attention: test Quality gates: ✅ typecheck, lint, test, build PR comment support deferred - requires GitHub/Gitea API client implementation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
285
apps/api/src/herald/herald.service.ts
Normal file
285
apps/api/src/herald/herald.service.ts
Normal file
@@ -0,0 +1,285 @@
|
||||
import { Injectable, Logger } from "@nestjs/common";
|
||||
import { PrismaService } from "../prisma/prisma.service";
|
||||
import { DiscordService } from "../bridge/discord/discord.service";
|
||||
import {
|
||||
JOB_CREATED,
|
||||
JOB_STARTED,
|
||||
JOB_COMPLETED,
|
||||
JOB_FAILED,
|
||||
JOB_CANCELLED,
|
||||
STEP_STARTED,
|
||||
STEP_COMPLETED,
|
||||
STEP_FAILED,
|
||||
GATE_PASSED,
|
||||
GATE_FAILED,
|
||||
} from "../job-events/event-types";
|
||||
|
||||
/**
|
||||
* Herald Service - Status broadcasting and notifications
|
||||
*
|
||||
* Responsibilities:
|
||||
* - Subscribe to job events
|
||||
* - Format status messages with PDA-friendly language
|
||||
* - Route to appropriate channels based on workspace config
|
||||
* - Support Discord (via bridge) and PR comments
|
||||
*/
|
||||
@Injectable()
|
||||
export class HeraldService {
|
||||
private readonly logger = new Logger(HeraldService.name);
|
||||
|
||||
constructor(
|
||||
private readonly prisma: PrismaService,
|
||||
private readonly discord: DiscordService
|
||||
) {}
|
||||
|
||||
/**
|
||||
* Broadcast a job event to the appropriate channel
|
||||
*/
|
||||
async broadcastJobEvent(
|
||||
jobId: string,
|
||||
event: {
|
||||
id: string;
|
||||
jobId: string;
|
||||
stepId?: string | null;
|
||||
type: string;
|
||||
timestamp: Date;
|
||||
actor: string;
|
||||
payload: unknown;
|
||||
}
|
||||
): Promise<void> {
|
||||
try {
|
||||
// Get job details
|
||||
const job = await this.prisma.runnerJob.findUnique({
|
||||
where: { id: jobId },
|
||||
select: {
|
||||
id: true,
|
||||
workspaceId: true,
|
||||
type: true,
|
||||
},
|
||||
});
|
||||
|
||||
if (!job) {
|
||||
this.logger.warn(`Job ${jobId} not found, skipping broadcast`);
|
||||
return;
|
||||
}
|
||||
|
||||
// Check if Discord is connected
|
||||
if (!this.discord.isConnected()) {
|
||||
this.logger.debug("Discord not connected, skipping broadcast");
|
||||
return;
|
||||
}
|
||||
|
||||
// Get threadId from first event payload (job.created event has metadata)
|
||||
const firstEvent = await this.prisma.jobEvent.findFirst({
|
||||
where: {
|
||||
jobId,
|
||||
type: JOB_CREATED,
|
||||
},
|
||||
select: {
|
||||
payload: true,
|
||||
},
|
||||
});
|
||||
|
||||
const firstEventPayload = firstEvent?.payload as Record<string, unknown> | undefined;
|
||||
const metadata = firstEventPayload?.metadata as Record<string, unknown> | undefined;
|
||||
const threadId = metadata?.threadId as string | undefined;
|
||||
|
||||
if (!threadId) {
|
||||
this.logger.debug(`Job ${jobId} has no threadId, skipping broadcast`);
|
||||
return;
|
||||
}
|
||||
|
||||
// Format message
|
||||
const message = this.formatJobEventMessage(event, job, metadata);
|
||||
|
||||
// Send to thread
|
||||
await this.discord.sendThreadMessage({
|
||||
threadId,
|
||||
content: message,
|
||||
});
|
||||
|
||||
this.logger.debug(`Broadcasted event ${event.type} for job ${jobId} to thread ${threadId}`);
|
||||
} catch (error) {
|
||||
this.logger.error(`Failed to broadcast event for job ${jobId}:`, error);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Format a job event into a PDA-friendly message
|
||||
*/
|
||||
formatJobEventMessage(
|
||||
event: {
|
||||
id: string;
|
||||
jobId: string;
|
||||
stepId?: string | null;
|
||||
type: string;
|
||||
timestamp: Date;
|
||||
actor: string;
|
||||
payload: unknown;
|
||||
},
|
||||
_job: {
|
||||
id: string;
|
||||
type: string;
|
||||
},
|
||||
metadata?: Record<string, unknown>
|
||||
): string {
|
||||
const payload = event.payload as Record<string, unknown>;
|
||||
const issueNumber = metadata?.issueNumber as number | undefined;
|
||||
|
||||
switch (event.type) {
|
||||
case JOB_CREATED:
|
||||
return this.formatJobCreated(issueNumber, payload);
|
||||
|
||||
case JOB_STARTED:
|
||||
return this.formatJobStarted(issueNumber, payload);
|
||||
|
||||
case JOB_COMPLETED:
|
||||
return this.formatJobCompleted(issueNumber, payload);
|
||||
|
||||
case JOB_FAILED:
|
||||
return this.formatJobFailed(issueNumber, payload);
|
||||
|
||||
case JOB_CANCELLED:
|
||||
return this.formatJobCancelled(issueNumber, payload);
|
||||
|
||||
case STEP_STARTED:
|
||||
return this.formatStepStarted(issueNumber, payload);
|
||||
|
||||
case STEP_COMPLETED:
|
||||
return this.formatStepCompleted(issueNumber, payload);
|
||||
|
||||
case STEP_FAILED:
|
||||
return this.formatStepFailed(issueNumber, payload);
|
||||
|
||||
case GATE_PASSED:
|
||||
return this.formatGatePassed(issueNumber, payload);
|
||||
|
||||
case GATE_FAILED:
|
||||
return this.formatGateFailed(issueNumber, payload);
|
||||
|
||||
default:
|
||||
return `Event: ${event.type}`;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the channel ID for a job type from workspace settings
|
||||
*/
|
||||
async getChannelForJobType(workspaceId: string, jobType: string): Promise<string | null> {
|
||||
const workspace = await this.prisma.workspace.findUnique({
|
||||
where: { id: workspaceId },
|
||||
select: { settings: true },
|
||||
});
|
||||
|
||||
if (!workspace) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const settings = workspace.settings as Record<string, unknown>;
|
||||
const heraldSettings = settings.herald as Record<string, unknown> | undefined;
|
||||
const channelMappings = heraldSettings?.channelMappings as Record<string, string> | undefined;
|
||||
const defaultChannel = heraldSettings?.defaultChannel as string | undefined;
|
||||
|
||||
// Try to get channel for job type
|
||||
if (channelMappings?.[jobType]) {
|
||||
return channelMappings[jobType];
|
||||
}
|
||||
|
||||
// Fall back to default channel
|
||||
if (defaultChannel) {
|
||||
return defaultChannel;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
// Message formatting methods with PDA-friendly language
|
||||
|
||||
private formatJobCreated(
|
||||
issueNumber: number | undefined,
|
||||
_payload: Record<string, unknown>
|
||||
): string {
|
||||
const issue = issueNumber ? `#${String(issueNumber)}` : "task";
|
||||
return `🟢 Job created for ${issue}`;
|
||||
}
|
||||
|
||||
private formatJobStarted(
|
||||
issueNumber: number | undefined,
|
||||
_payload: Record<string, unknown>
|
||||
): string {
|
||||
const issue = issueNumber ? `#${String(issueNumber)}` : "task";
|
||||
return `🔵 Job started for ${issue}`;
|
||||
}
|
||||
|
||||
private formatJobCompleted(
|
||||
issueNumber: number | undefined,
|
||||
payload: Record<string, unknown>
|
||||
): string {
|
||||
const issue = issueNumber ? `#${String(issueNumber)}` : "task";
|
||||
const duration = payload.duration as number | undefined;
|
||||
const durationText = duration ? ` (${String(duration)}s)` : "";
|
||||
return `✅ Job completed for ${issue}${durationText}`;
|
||||
}
|
||||
|
||||
private formatJobFailed(
|
||||
issueNumber: number | undefined,
|
||||
payload: Record<string, unknown>
|
||||
): string {
|
||||
const issue = issueNumber ? `#${String(issueNumber)}` : "task";
|
||||
const error = payload.error as string | undefined;
|
||||
const errorText = error ? `\n${error}` : "";
|
||||
return `⚠️ Job encountered an issue for ${issue}${errorText}`;
|
||||
}
|
||||
|
||||
private formatJobCancelled(
|
||||
issueNumber: number | undefined,
|
||||
_payload: Record<string, unknown>
|
||||
): string {
|
||||
const issue = issueNumber ? `#${String(issueNumber)}` : "task";
|
||||
return `⏸️ Job paused for ${issue}`;
|
||||
}
|
||||
|
||||
private formatStepStarted(
|
||||
_issueNumber: number | undefined,
|
||||
payload: Record<string, unknown>
|
||||
): string {
|
||||
const stepName = payload.stepName as string | undefined;
|
||||
return `▶️ Step started: ${stepName ?? "unknown"}`;
|
||||
}
|
||||
|
||||
private formatStepCompleted(
|
||||
_issueNumber: number | undefined,
|
||||
payload: Record<string, unknown>
|
||||
): string {
|
||||
const stepName = payload.stepName as string | undefined;
|
||||
return `✅ Step completed: ${stepName ?? "unknown"}`;
|
||||
}
|
||||
|
||||
private formatStepFailed(
|
||||
_issueNumber: number | undefined,
|
||||
payload: Record<string, unknown>
|
||||
): string {
|
||||
const stepName = payload.stepName as string | undefined;
|
||||
const error = payload.error as string | undefined;
|
||||
const errorText = error ? `\n${error}` : "";
|
||||
return `⚠️ Step needs attention: ${stepName ?? "unknown"}${errorText}`;
|
||||
}
|
||||
|
||||
private formatGatePassed(
|
||||
_issueNumber: number | undefined,
|
||||
payload: Record<string, unknown>
|
||||
): string {
|
||||
const gateName = payload.gateName as string | undefined;
|
||||
return `✅ Gate passed: ${gateName ?? "unknown"}`;
|
||||
}
|
||||
|
||||
private formatGateFailed(
|
||||
_issueNumber: number | undefined,
|
||||
payload: Record<string, unknown>
|
||||
): string {
|
||||
const gateName = payload.gateName as string | undefined;
|
||||
const error = payload.error as string | undefined;
|
||||
const errorText = error ? `\n${error}` : "";
|
||||
return `⚠️ Gate needs attention: ${gateName ?? "unknown"}${errorText}`;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user