@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/reporting/commit-status.d.ts

@@ -0,0 +1,382 @@
+/**
+ * GitHub check run integration module.
+ *
+ * Creates and updates check runs at key lifecycle points using the Checks API.
+ * Per locked decisions:
+ * - Check runs created (queued) at trigger match time (before agent picks up the job)
+ * - Both per-job AND overall workflow check runs: kici/{workflow} and kici/{workflow}/job/{job}
+ * - Success ONLY if ALL jobs pass
+ * - Cancelled/timed-out use 'cancelled' conclusion
+ * - All API calls are fire-and-forget (non-blocking)
+ *
+ * Check run IDs are tracked in-memory after creation so that subsequent
+ * updates (job complete, workflow complete) can reference them via checks.update().
+ *
+ * Enriched output (Phase 14):
+ * - Live step progress with checklist-style updates (debounced at 5s)
+ * - Failed check runs include step names, error messages, exit codes, and log context
+ * - Check run annotations link failures to step source locations in workflow files (.kici/workflows/*.ts)
+ *
+ * Currently GitHub-only. Non-GitHub providers are handled gracefully (no-op with log).
+ *
+ * Note: The engine-level CheckStatusPoster interface (packages/engine/src/provider/check-status-poster.ts)
+ * provides a provider-agnostic API for posting security-related check statuses (holds, approvals,
+ * workflow modifications). The GitHub implementation is at packages/orchestrator/src/providers/github/check-status-poster.ts.
+ * This CommitStatusReporter handles execution lifecycle checks (queued, in_progress, completed per job/workflow).
+ * Future cleanup may unify both under CheckStatusPoster, but they serve different purposes today.
+ */
+import { type GitHubAppConfig } from '../providers/github/auth.js';
+import type { ProviderRegistry } from '../provider-registry.js';
+import type { StepLogBuffer } from './step-log-buffer.js';
+import { type SourceLocationData } from './check-run-summary.js';
+import { ExecutionJobStatus } from '@kici-dev/engine';
+/**
+ * Dependencies for the CommitStatusReporter.
+ */
+interface CommitStatusReporterDeps {
+    /**
+     * Provider registry for per-routing-key credential lookup.
+     * When provided, the reporter resolves GitHub App credentials by routing key
+     * from the registry's CloneTokenProvider config. Takes precedence over githubConfig.
+     */
+    providerRegistry?: ProviderRegistry;
+    /**
+     * GitHub App config for creating Octokit instances.
+     * Fallback for backward compatibility when providerRegistry is not provided
+     * or when no routing key is available.
+     */
+    githubConfig?: GitHubAppConfig;
+    /** Step log buffer for enriched failure summaries. */
+    stepLogBuffer?: StepLogBuffer;
+    /** Resolver for step source locations from the lock file (for annotations). */
+    getStepSourceLocations?: (workflowName: string, jobName: string) => SourceLocationData[] | undefined;
+    /**
+     * Base URL of the user-facing dashboard (e.g.
+     * `https://dashboard.example.com/dashboard`). When set AND
+     * `getOrgPublicAlias()` returns an alias, the reporter populates
+     * `details_url = <dashboardUrl>/r/orgs/<alias>/runs/<runId>` on
+     * every check-run create/update. When unset, no `details_url` is
+     * emitted (preserving today's behavior).
+     */
+    dashboardUrl?: string;
+    /**
+     * Resolver for the orchestrator's owning org public alias. Typically
+     * wired to `PlatformClient.getOrgPublicAlias()`. Returns the
+     * `oal_<12-char>` alias supplied by Platform on `auth.success`, or
+     * `undefined` before auth completes / when running against a
+     * Platform that predates the alias plumbing.
+     */
+    getOrgPublicAlias?: () => string | undefined;
+}
+/**
+ * Options for setPending.
+ */
+interface SetPendingOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    workflowName: string;
+    jobNames: string[];
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    /** Explicit requestId for trace context (falls back to AsyncLocalStorage context). */
+    requestId?: string;
+    /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
+    runId?: string;
+}
+/**
+ * Options for setBuildPending.
+ */
+interface SetBuildPendingOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    workflowName: string;
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    /** Explicit requestId for trace context (falls back to AsyncLocalStorage context). */
+    requestId?: string;
+    /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
+    runId?: string;
+}
+/**
+ * Options for setBuildComplete.
+ */
+interface SetBuildCompleteOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    workflowName: string;
+    status: Extract<ExecutionJobStatus, 'success' | 'failed' | 'cancelled' | 'timed_out_stale'>;
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    description?: string;
+    /** Explicit requestId for trace context (falls back to AsyncLocalStorage context). */
+    requestId?: string;
+    /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
+    runId?: string;
+}
+/**
+ * Options for updateJobStatus.
+ */
+interface UpdateJobStatusOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    workflowName: string;
+    jobName: string;
+    state: Extract<ExecutionJobStatus, 'success' | 'failed' | 'cancelled' | 'timed_out_stale'>;
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    description?: string;
+    /** Explicit requestId for trace context (falls back to AsyncLocalStorage context). */
+    requestId?: string;
+    /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
+    runId?: string;
+    /** Additional data from the agent (e.g., stepResults). */
+    data?: Record<string, unknown>;
+    /** Run ID for StepLogBuffer lookup. */
+    runIdForLogs?: string;
+    /** Job ID for StepLogBuffer lookup. */
+    jobId?: string;
+}
+/**
+ * Options for updateWorkflowStatus.
+ */
+interface UpdateWorkflowStatusOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    workflowName: string;
+    overallStatus: Extract<ExecutionJobStatus, 'success' | 'failed' | 'cancelled' | 'timed_out_stale'>;
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    description?: string;
+    /** Explicit requestId for trace context (falls back to AsyncLocalStorage context). */
+    requestId?: string;
+    /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
+    runId?: string;
+}
+/**
+ * Options for updateStepProgress.
+ */
+interface UpdateStepProgressOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    workflowName: string;
+    jobName: string;
+    stepIndex: number;
+    stepName: string;
+    state: 'running' | 'success' | 'failed' | 'skipped' | 'cancelled' | 'error';
+    durationMs?: number;
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    requestId?: string;
+    runId?: string;
+}
+/**
+ * Reports check run status to Git hosting providers.
+ *
+ * Currently supports GitHub via the Checks API (checks.create / checks.update).
+ * Non-GitHub providers are handled gracefully (no-op with warning log).
+ *
+ * All public methods are fire-and-forget: they return void immediately
+ * and log errors internally without propagating them.
+ */
+export declare class CommitStatusReporter {
+    private deps;
+    /** Map from composite key to check run ID for subsequent updates. */
+    private readonly checkRunIds;
+    /** In-flight build check run creation promises, keyed by composite key. */
+    private readonly pendingBuildCreations;
+    /** Step progress entries per check run key. */
+    private readonly stepProgress;
+    /** Debounce timers for in_progress updates per check run key. */
+    private readonly progressTimers;
+    /** Track whether the first in_progress transition has been sent per check run key. */
+    private readonly inProgressSent;
+    constructor(deps: CommitStatusReporterDeps);
+    /**
+     * Update the provider registry used for per-routing-key credential lookup.
+     * Called after config reload when the provider registry is rebuilt.
+     */
+    updateRegistry(newRegistry: ProviderRegistry): void;
+    /**
+     * Late-bind the public-alias resolver. Called from `server.ts` /
+     * `standalone.ts` after `PlatformClient` is constructed so the reporter
+     * can pull the freshly-authenticated org's alias when building
+     * `details_url`. orchestrator-core can't pass it at construction time
+     * because the platform client is created later (after the HTTP server
+     * starts).
+     */
+    setOrgPublicAliasResolver(resolver: () => string | undefined): void;
+    /**
+     * Set pending (queued) check runs for a workflow and all its jobs.
+     * Called at trigger match time (before agent picks up the job).
+     * Fire-and-forget: errors are logged but don't block the pipeline.
+     *
+     * Creates check runs via checks.create with status 'queued'.
+     * Per locked decision: both per-job AND overall workflow check runs.
+     * Name format: kici/{workflow-name}, kici/{workflow-name}/job/{job-name}
+     */
+    setPending(opts: SetPendingOptions): void;
+    /**
+     * Same as setPending but returns a Promise that resolves when check runs
+     * are created. Used by the RunCoordinator for rerouted jobs where the
+     * check runs MUST exist before job dispatch to ensure updates work.
+     */
+    setPendingAwait(opts: SetPendingOptions): Promise<void>;
+    /**
+     * Update a specific job's check run.
+     * Called when a job reaches a terminal state.
+     * Fire-and-forget: errors are logged but don't block the pipeline.
+     */
+    updateJobStatus(opts: UpdateJobStatusOptions): void;
+    /**
+     * Update the overall workflow check run.
+     * Called when ALL jobs in a workflow reach terminal state.
+     * Per locked decision: success ONLY if ALL jobs pass.
+     * Fire-and-forget: errors are logged but don't block the pipeline.
+     */
+    updateWorkflowStatus(opts: UpdateWorkflowStatusOptions): void;
+    /**
+     * Clean up stale check runs left by a dead orchestrator.
+     *
+     * Unlike updateJobStatus/updateWorkflowStatus (which rely on in-memory checkRunId),
+     * this method discovers check runs via the GitHub API by listing check runs for the
+     * commit SHA and matching on the `kici/` name prefix. This allows a replacement
+     * orchestrator to clean up check runs it didn't create.
+     *
+     * Uses the GitHub App to look up the installation for each repo, then lists and
+     * updates any stuck "in_progress" check runs with a "timed_out" conclusion.
+     *
+     * Fire-and-forget: errors are logged but don't block.
+     */
+    cleanupStaleCheckRuns(opts: {
+        provider: string;
+        routingKey: string;
+        owner: string;
+        repo: string;
+        sha: string;
+        workflowName: string;
+        jobNames: string[];
+    }): void;
+    /**
+     * Update live step progress for a job's check run.
+     * Called each time a step starts, completes, or fails.
+     * The first 'running' step triggers an immediate in_progress transition.
+     * Subsequent updates are debounced (5 seconds) to prevent API rate limiting.
+     * Fire-and-forget: errors are logged but don't block the pipeline.
+     */
+    updateStepProgress(opts: UpdateStepProgressOptions): void;
+    /**
+     * Set a build check run to pending (queued).
+     * Called when a build job is dispatched for dependency installation and/or bundle compilation.
+     * Separate from execution check runs so users see build progress independently.
+     * Fire-and-forget: errors are logged but don't block the pipeline.
+     *
+     * Check run name format: kici/{workflowName}/setup
+     */
+    setBuildPending(opts: SetBuildPendingOptions): void;
+    /**
+     * Update a build check run to completed.
+     * Called when the build job finishes (success, failure, or cancellation).
+     * Fire-and-forget: errors are logged but don't block the pipeline.
+     */
+    setBuildComplete(opts: SetBuildCompleteOptions): void;
+    /**
+     * Clean up step progress entries and pending timers for a completed run.
+     * Called when execution tracker prunes a run from memory.
+     */
+    cleanupRun(runId: string): void;
+    /** Map from runId to check run keys for cleanup. */
+    private readonly runIdToKeys;
+    /** Track a check run key associated with a runId for later cleanup. */
+    private trackRunKey;
+    /**
+     * Resolve GitHub App credentials for a given routing key.
+     *
+     * Resolution order:
+     * 1. If providerRegistry is provided AND routingKey is given, look up the bundle
+     *    by routing key and extract config from the CloneTokenProvider's getAppConfig().
+     * 2. Fall back to the direct githubConfig dep (backward compatible).
+     *
+     * Returns undefined if no config is available.
+     */
+    private resolveGithubConfig;
+    /**
+     * Resolve trace IDs for check run summaries.
+     * Priority: explicit option value > AsyncLocalStorage context > 'N/A'
+     */
+    private resolveTraceIds;
+    /**
+     * Append trace IDs to a check run summary string.
+     */
+    private appendTraceIds;
+    private checkRunKey;
+    /**
+     * Build the `details_url` for a check run pointing at the dashboard's
+     * public-alias resolver (`/r/orgs/<oal_xxx>/runs/<runId>`). Returns
+     * `undefined` when either the dashboard URL or the alias is missing,
+     * or when the runId is the synthetic `'N/A'` sentinel from
+     * `resolveTraceIds` (no real run to link to). Strips any trailing
+     * slash on `dashboardUrl` so the concatenation produces a single
+     * separator.
+     */
+    private buildDetailsUrl;
+    private doSetPending;
+    private doUpdateJobStatus;
+    private doUpdateWorkflowStatus;
+    private doCleanupStaleCheckRuns;
+    private doUpdateStepProgress;
+    /**
+     * Flush pending progress update to GitHub.
+     */
+    private flushProgress;
+    private doSetBuildPending;
+    private doSetBuildComplete;
+    /**
+     * Map internal build status to GitHub Checks conclusion and description.
+     */
+    private mapBuildConclusion;
+    /**
+     * Map internal job state to GitHub Checks conclusion and description.
+     */
+    private mapJobConclusion;
+    /**
+     * Map internal workflow state to GitHub Checks conclusion and description.
+     */
+    private mapWorkflowConclusion;
+    /**
+     * Create a check run via the GitHub Checks API.
+     * Returns the check run ID on success, or undefined on failure.
+     */
+    private createCheckRun;
+    /**
+     * Update an existing check run via the GitHub Checks API.
+     * Supports both 'completed' and 'in_progress' statuses.
+     */
+    private updateCheckRun;
+}
+/**
+ * Build a meaningful failure description from agent job status data.
+ *
+ * Examines `stepResults` for the first failed step, falling back to
+ * `data.error`, and finally to a generic "Job failed" message.
+ */
+export declare function buildJobFailureDescription(data: Record<string, unknown>): string;
+export {};
+//# sourceMappingURL=commit-status.d.ts.map