@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/queue/scheduled-job.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Orchestrator scheduled-job wrapper.
+ *
+ * Mirrors `packages/platform/src/queue/scheduled-job.ts` in observable
+ * surface (5 Prometheus metrics + structured logs + audit row on
+ * failure) but uses `setInterval` instead of pg-boss — the orchestrator
+ * has no pg-boss dependency and we're not adding one.
+ *
+ * All future orchestrator periodic jobs MUST use this wrapper — per
+ * CLAUDE.md "no workarounds", the legacy setInterval call sites in
+ * queue/cleanup.ts and secrets/cleanup.ts migrate in the same phase
+ * they'd otherwise be updated.
+ *
+ * `triggerNow()` on the returned handle forces one off-cadence tick
+ * (used by the admin `/api/v1/admin/scheduled-jobs/:name/trigger`
+ * endpoint and by E2E harnesses). It does NOT reset the interval
+ * timer — a real tick still fires at the scheduled cadence after.
+ */
+import { z } from 'zod';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/**
+ * All registered orchestrator scheduled-job names. Adding a new
+ * periodic job MUST add its name here before it can register.
+ */
+export declare const OrchestratorScheduledJobName: z.ZodEnum<{
+    cleanup: "cleanup";
+    "orphan-secret-cleanup": "orphan-secret-cleanup";
+    "token-cleanup": "token-cleanup";
+    "cold-store-archive": "cold-store-archive";
+    "cold-store-purge": "cold-store-purge";
+}>;
+export type OrchestratorScheduledJobName = z.infer<typeof OrchestratorScheduledJobName>;
+/** Access-log action for a manually triggered off-cadence tick. */
+export declare const ACCESS_LOG_ACTION_TRIGGER = "scheduled_job.trigger";
+export interface OrchestratorScheduledJobOptions {
+    name: OrchestratorScheduledJobName;
+    /** Tick cadence. Must be > 0. */
+    intervalMs: number;
+    /** Handler called per tick. Exceptions are caught and metered. */
+    handler: () => Promise<void>;
+    /**
+     * Orchestrator instance ID — appears on failure access-log rows as
+     * `actor_id` alongside `actor_type='system'`.
+     */
+    instanceId: string;
+    /** DB used for failure audit rows. If omitted, failures are logs-only. */
+    db?: Kysely<Database>;
+    /** Routing key for failure access-log partitioning (null = not scoped). */
+    routingKey?: string;
+    /** Fire one tick immediately on register. Defaults to false. */
+    runOnStart?: boolean;
+    /** `timer.unref()` — allows process exit while scheduled. Defaults to true. */
+    unref?: boolean;
+}
+export interface OrchestratorScheduledJobHandle {
+    readonly name: OrchestratorScheduledJobName;
+    /** Clears the interval. Safe to call multiple times. */
+    stop(): void;
+    /**
+     * Force one off-cadence tick and await it (success or failure).
+     * Returns the tick's outcome so E2E and admin routes can report it.
+     */
+    triggerNow(): Promise<{
+        ok: boolean;
+        durationMs: number;
+        error?: string;
+    }>;
+}
+/**
+ * Readonly snapshot of per-job metric state. Used by the admin
+ * `/api/v1/admin/scheduled-jobs` route to surface last-run info.
+ */
+export declare function getOrchestratorJobMetricState(): ReadonlyMap<string, {
+    consecutiveFailures: number;
+    lastSuccessAt: Date | null;
+    lastFailureAt: Date | null;
+}>;
+/**
+ * Look up a registered scheduled job's handle by name. Returns
+ * `undefined` if the job isn't registered on this instance. Used by
+ * the admin trigger-now endpoint.
+ */
+export declare function findOrchestratorScheduledJob(name: OrchestratorScheduledJobName): OrchestratorScheduledJobHandle | undefined;
+/**
+ * Clear the scheduled-job registry. Intended for tests only —
+ * production code should keep a stable set of registered jobs.
+ */
+export declare function __resetOrchestratorScheduledJobsForTesting(): void;
+export declare function registerOrchestratorScheduledJob(opts: OrchestratorScheduledJobOptions): OrchestratorScheduledJobHandle;
+//# sourceMappingURL=scheduled-job.d.ts.map

package/dist/registration/extractor.d.ts

@@ -0,0 +1,44 @@
+import type { LockFile, LockTrigger, LockWorkflow } from '@kici-dev/engine';
+/**
+ * Trigger types that cause a workflow to be stored in workflow_registrations.
+ *
+ * Non-Git-provider triggers (kici_event, schedule, webhook, …) live in the
+ * registration table because they have no per-repo lock file pipeline to
+ * fall back to. Git-provider triggers (push, pr, tag, …) ALSO live in the
+ * registration table so that the cross-source dispatch path (phase 28.5)
+ * can resolve them by (customer_id, repo_identifier) when a generic webhook
+ * targets an externally-hosted repo. The per-event lock file pipeline still
+ * handles same-source dispatch for git triggers; registration is an additive
+ * index.
+ */
+declare const REGISTERABLE_TRIGGER_TYPES: ReadonlySet<string>;
+/**
+ * Check whether a trigger has repo patterns, indicating
+ * it is part of a global workflow that matches across repositories.
+ */
+export declare function hasRepoPatterns(trigger: LockTrigger): boolean;
+/**
+ * Extract workflows that have at least one trigger with repo patterns.
+ * These are "global workflows" that match events across repositories.
+ *
+ * @param lockFile - The compiled lock file to extract from
+ * @returns Workflows that have at least one trigger with repo patterns
+ */
+export declare function extractGlobalWorkflows(lockFile: LockFile): LockWorkflow[];
+/**
+ * Extract workflows that have at least one registerable trigger, OR that
+ * have repo patterns (global workflows).
+ *
+ * Since phase 28.5, Git-provider triggers (push, pr, tag, …) are ALSO
+ * registerable so cross-source dispatch can resolve them via the registration
+ * index when a generic webhook targets an externally-hosted repo. The
+ * per-event lock file pipeline remains the primary matching path for
+ * same-source git events; registration is an additive index.
+ *
+ * @param lockFile - The compiled lock file to extract from
+ * @returns Workflows that have at least one registerable trigger or repo patterns
+ */
+export declare function extractRegisterableWorkflows(lockFile: LockFile): LockWorkflow[];
+/** Exposed for testing */
+export { REGISTERABLE_TRIGGER_TYPES };
+//# sourceMappingURL=extractor.d.ts.map

package/dist/registration/registration-index.d.ts

@@ -0,0 +1,162 @@
+import type { LockWorkflow } from '@kici-dev/engine';
+import type { RegistrationStore } from './registration-store.js';
+/**
+ * A registered workflow entry with typed fields for fast in-memory lookup.
+ */
+export interface RegisteredWorkflow {
+    id: string;
+    repoIdentifier: string;
+    workflowName: string;
+    lockEntry: LockWorkflow;
+    triggerTypes: string[];
+    routingKey: string;
+    providerContext: Record<string, unknown>;
+    disabled: boolean;
+    /** Whether this is a global workflow (has repo patterns) */
+    isGlobal: boolean;
+    /**
+     * Customer/org ID that owns this registration. Drives org-scoped lookups
+     * via getByOrgAndEvent — cross-org leakage is structurally impossible
+     * because the byOrgAndEvent key is namespaced by customerId.
+     */
+    customerId: string;
+    commitSha: string | null;
+    sourceFile: string | null;
+}
+/**
+ * In-memory index of workflow registrations with version-based reload.
+ *
+ * Provides fast lookups by trigger type, customer/repo, and event type.
+ * Updates happen only via loadFromDb/refreshIfNeeded -- the index is
+ * read-only from the outside.
+ */
+export declare class RegistrationIndex {
+    private readonly store;
+    /** Current version matching the DB registry_versions counter */
+    private version;
+    /** Primary index: keyed by `{routingKey}:{repoIdentifier}` */
+    private entries;
+    /** Secondary index: keyed by trigger type for fast event routing */
+    private byTriggerType;
+    /** Tertiary index: global workflows keyed by `{routingKey}:{triggerType}` */
+    private globalByTriggerType;
+    /**
+     * Tertiary-b index: global workflows keyed by `{customerId}|{triggerType}`.
+     * Used for cross-provider global workflow dispatch within an org — e.g.
+     * a universal-git Forgejo source authors a global workflow, a GitHub App
+     * source in the same org delivers a push, and the global is dispatched
+     * even though the inbound routing key differs from the registration's.
+     * Cross-org isolation is structurally enforced by the customer_id prefix.
+     */
+    private globalByOrgAndTriggerType;
+    /**
+     * Quaternary index: webhook-trigger registrations keyed by
+     * `${customerId}|${eventName}`. Drives the cross-source webhook lookup
+     * (a generic webhook arriving in org A finds all webhook-trigger
+     * registrations in org A whose lock_entry has a matching event). Cross-org
+     * isolation is structurally enforced by the customer_id-prefixed key.
+     */
+    private byOrgAndEvent;
+    /**
+     * Quinary index: registrations keyed by `${customerId}|${repoIdentifier}`.
+     * Drives the cross-source repo lookup (phase 28.5): when a generic webhook
+     * carries a repository identifier in its payload, the dispatcher looks up
+     * registrations for that (org, repo) pair across ALL routing keys and uses
+     * each registration's stored `providerContext` + `routingKey` to reach the
+     * owning provider bundle (e.g. a github source) for credential minting and
+     * trigger evaluation. Cross-org isolation is structurally enforced by the
+     * customer_id-prefixed key.
+     */
+    private byOrgAndRepo;
+    constructor(store: RegistrationStore);
+    /**
+     * Bulk load all registrations from the DB store.
+     * Rebuilds both in-memory indexes and updates the version.
+     */
+    loadFromDb(): Promise<void>;
+    /**
+     * Reload from DB if the remote version is newer than the local version.
+     * Called when a peer heartbeat reports a higher registryVersion.
+     */
+    refreshIfNeeded(remoteVersion: number): Promise<void>;
+    /**
+     * Get the current in-memory version.
+     */
+    getVersion(): number;
+    /**
+     * Look up a single registration by ID (includes disabled entries).
+     * Used by manual schedule to distinguish "not found" from "disabled".
+     */
+    getById(id: string): RegisteredWorkflow | undefined;
+    /**
+     * Get all workflows registered for a specific trigger type.
+     * Used for event routing (e.g., find all workflows listening for 'kici_event').
+     */
+    getByTriggerType(triggerType: string): RegisteredWorkflow[];
+    /**
+     * Get all workflows registered for a specific routing key and repo.
+     */
+    getByRoutingKeyAndRepo(routingKey: string, repoIdentifier: string): RegisteredWorkflow[];
+    /**
+     * Cross-source webhook lookup: return all webhook-trigger registrations
+     * within a customer/org that listen for `eventName`.
+     *
+     * Used by the cross-source dispatch branch in `processWebhook()` so that an
+     * inbound generic webhook in org A can fan out to webhook-trigger workflows
+     * registered to ANY source in org A. Org isolation is structurally enforced:
+     * the lookup key is `${customerId}|${eventName}`, so registrations in a
+     * different customer's bucket cannot leak through this method even if the
+     * eventName matches.
+     *
+     * Disabled rows are filtered out, mirroring the other typed lookups.
+     */
+    getByOrgAndEvent(customerId: string, eventName: string): RegisteredWorkflow[];
+    /**
+     * Cross-source repo lookup: return all registrations in a given customer/org
+     * that target a specific repo identifier, across all routing keys.
+     *
+     * Used by the cross-source dispatch branch in `processWebhook()` so that a
+     * generic webhook carrying `repository.full_name` (or an equivalent payload
+     * field) can be routed to git-trigger workflows (push, pr, tag, …) owned by
+     * any source in the same org. Each returned registration carries its own
+     * `routingKey` + `providerContext`, which the caller uses to resolve the
+     * correct provider bundle and mint credentials for the owning provider.
+     *
+     * Org isolation is structurally enforced: the lookup key is
+     * `${customerId}|${repoIdentifier}`, so registrations in a different
+     * customer's bucket cannot leak through even if the repo identifier matches.
+     *
+     * Disabled rows are filtered out, mirroring the other typed lookups.
+     */
+    getByOrgAndRepo(customerId: string, repoIdentifier: string): RegisteredWorkflow[];
+    /**
+     * Get global workflows matching a trigger type within a routing key.
+     * Used by the webhook processor for dual-query (per-repo + global).
+     */
+    getGlobalByTriggerType(triggerType: string, routingKey: string): RegisteredWorkflow[];
+    /**
+     * Get global workflows matching a trigger type within an org, across ALL
+     * routing keys. Used by the webhook processor for cross-provider global
+     * workflow dispatch.
+     */
+    getGlobalByOrgAndTriggerType(customerId: string, triggerType: string): RegisteredWorkflow[];
+    /**
+     * Convenience: get all workflows with 'schedule' trigger type.
+     * Used by the cron scheduler to evaluate pending schedules.
+     */
+    getCronSchedules(): RegisteredWorkflow[];
+    /**
+     * Get workflows matching an event type string.
+     * Maps event type strings to trigger type strings for lookup.
+     *
+     * Event type -> trigger type mapping:
+     * - 'kici_event' -> 'kici_event'
+     * - 'workflow_complete' -> 'workflow_complete' or 'lifecycle'
+     * - 'job_complete' -> 'job_complete' or 'lifecycle'
+     * - 'generic_webhook' -> 'generic_webhook'
+     * - 'schedule' -> 'schedule'
+     * - lifecycle event names -> 'lifecycle'
+     */
+    getByEventType(eventType: string): RegisteredWorkflow[];
+}
+//# sourceMappingURL=registration-index.d.ts.map

package/dist/registration/registration-store.d.ts

@@ -0,0 +1,111 @@
+import type { Kysely } from 'kysely';
+import type { LockWorkflow } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+/**
+ * Parsed registration row with typed fields.
+ * DB stores lock_entry as JSON string and trigger_types as TEXT[],
+ * but this interface exposes them as typed objects.
+ */
+export interface RegistrationRow {
+    id: string;
+    repo_identifier: string;
+    workflow_name: string;
+    lock_entry: LockWorkflow;
+    trigger_types: string[];
+    routing_key: string;
+    provider_context: Record<string, unknown>;
+    disabled: boolean;
+    isGlobal: boolean;
+    /**
+     * Customer/org ID that owns this registration. Sourced from the source row
+     * (sources or generic_webhook_sources joined on routing_key) and persisted
+     * by replaceAll. Drives the (customer_id, eventName) lookup in
+     * RegistrationIndex used by cross-source webhook delivery.
+     */
+    customerId: string;
+    commitSha: string | null;
+    sourceFile: string | null;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * Options for replaceAll to pass commit tracking metadata.
+ */
+interface ReplaceAllOptions {
+    /**
+     * Customer/org ID that owns the registrations being written. REQUIRED —
+     * persisted into workflow_registrations.customer_id (NOT NULL since
+     * migration 020) and used by RegistrationIndex.byOrgAndEvent for
+     * cross-source webhook lookup.
+     */
+    customerId: string;
+    commitSha?: string;
+    sourceFile?: string;
+    /** Set of workflow names that should be marked as global */
+    globalWorkflowNames?: Set<string>;
+}
+/**
+ * DB CRUD for workflow_registrations table with atomic upsert-based replace-all.
+ *
+ * The replace-all pattern uses SELECT + UPDATE/INSERT + selective DELETE in a
+ * single transaction. This preserves existing registration UUIDs (and their
+ * cascaded cron_last_fired records) while still being atomic against concurrent
+ * pushes.
+ */
+export declare class RegistrationStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Atomically replace all registrations for a repo (scoped by routing key).
+     *
+     * Uses an upsert pattern that preserves existing registration IDs:
+     * 1. SELECT existing rows for this routing_key + repo
+     * 2. UPDATE rows whose workflow_name still exists in the incoming set
+     * 3. INSERT rows for new workflow_names
+     * 4. DELETE rows whose workflow_name is no longer in the incoming set
+     *
+     * This prevents cascade deletion of cron_last_fired records when workflows
+     * are re-registered on every default-branch push.
+     */
+    replaceAll(repoIdentifier: string, workflows: LockWorkflow[], routingKey: string, providerContext: Record<string, unknown>, options: ReplaceAllOptions): Promise<void>;
+    /**
+     * Toggle the disabled state of a workflow registration.
+     * Returns true if a row was updated, false if the ID was not found.
+     */
+    setDisabled(id: string, disabled: boolean): Promise<boolean>;
+    /**
+     * Get all registrations (for index loading on startup).
+     */
+    getAll(): Promise<RegistrationRow[]>;
+    /**
+     * Get registrations for a specific routing key.
+     */
+    getByRoutingKey(routingKey: string): Promise<RegistrationRow[]>;
+    /**
+     * Get registrations for a specific routing key + repo pair.
+     */
+    getByRoutingKeyAndRepo(routingKey: string, repoIdentifier: string): Promise<RegistrationRow[]>;
+    /**
+     * Get a single registration by ID. Returns null if not found.
+     */
+    getById(id: string): Promise<RegistrationRow | null>;
+    /**
+     * Delete a single registration by ID. Returns true if deleted.
+     */
+    deleteById(id: string): Promise<boolean>;
+    /**
+     * Delete all registrations for a routing key + repo pair.
+     */
+    deleteByRoutingKeyAndRepo(routingKey: string, repoIdentifier: string): Promise<void>;
+    /**
+     * Get the current registry version (for cluster sync).
+     */
+    getVersion(): Promise<number>;
+    /**
+     * Increment the registry version and return the new value.
+     * Called after registration changes to notify peers via heartbeat.
+     */
+    bumpVersion(): Promise<number>;
+}
+export {};
+//# sourceMappingURL=registration-store.d.ts.map

package/dist/reporting/check-run-summary.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Check run summary, annotation, and progress text builders.
+ *
+ * These are pure functions that produce markdown and annotation objects
+ * for the GitHub Checks API. No side effects, no API calls -- just data
+ * transformation from step results + log buffers to GitHub-ready output.
+ *
+ * Per locked decisions:
+ * - Summary headline: "Job '{jobName}' failed (N/M steps passed)" or success equivalent
+ * - Step table with Status | Step | Duration columns
+ * - Failed steps: error + last 20 log lines in code blocks
+ * - Annotations: failure/warning level, capped at 50
+ * - Progress: checklist-style with emoji prefixes
+ * - Size safety: 65535 byte limit with progressive truncation
+ */
+import type { StepLogBuffer } from './step-log-buffer.js';
+/** Step result data as sent by the agent in job.status data.stepResults. */
+export interface StepResultData {
+    name: string;
+    status: 'success' | 'failed' | 'error' | 'skipped' | 'cancelled';
+    durationMs?: number;
+    error?: string;
+    exitCode?: number;
+    timedOut?: boolean;
+    continueOnError?: boolean;
+}
+/** Source location data from the lock file for annotation linking. */
+export interface SourceLocationData {
+    file: string;
+    line: number;
+    column: number;
+}
+/** A GitHub Check annotation object. */
+export interface CheckAnnotation {
+    path: string;
+    start_line: number;
+    end_line: number;
+    annotation_level: 'failure' | 'warning' | 'notice';
+    message: string;
+    title: string;
+    raw_details?: string;
+}
+/** Step progress entry for live updates. */
+export interface StepProgressEntry {
+    name: string;
+    status: 'pending' | 'running' | 'success' | 'failed' | 'error' | 'skipped' | 'cancelled';
+    durationMs?: number;
+}
+interface BuildCheckRunSummaryOptions {
+    jobName: string;
+    stepResults: StepResultData[];
+    logBuffer: StepLogBuffer;
+    runId: string;
+    jobId: string;
+    traceIds: {
+        requestId: string;
+        runId: string;
+    };
+    /** Total job duration in milliseconds. */
+    jobDurationMs?: number;
+}
+interface BuildAnnotationsOptions {
+    stepResults: StepResultData[];
+    /** Source locations indexed by step index. Missing entries are skipped. */
+    sourceLocations: Map<number, SourceLocationData>;
+}
+interface BuildProgressTextOptions {
+    steps: StepProgressEntry[];
+    traceIds: {
+        requestId: string;
+        runId: string;
+    };
+}
+export { formatDuration } from '@kici-dev/shared';
+/**
+ * Build a rich markdown summary for a GitHub Check run output.summary field.
+ *
+ * Includes: headline, step table, failure details with log context, trace footer.
+ * Respects the 65535 byte limit with progressive log truncation.
+ */
+export declare function buildCheckRunSummary(opts: BuildCheckRunSummaryOptions): string;
+/**
+ * Build GitHub Check annotation objects from step results and source locations.
+ *
+ * Returns an object with the annotations array (capped at 50) and the count
+ * of remaining annotations that could not be included.
+ */
+export declare function buildAnnotations(opts: BuildAnnotationsOptions): {
+    annotations: CheckAnnotation[];
+    remainingCount: number;
+};
+/**
+ * Build a checklist-style markdown string for live check run updates.
+ *
+ * Example:
+ *   checkmark Install deps (1.2s)
+ *   checkmark Build (3.4s)
+ *   hourglass Run tests...
+ *   (not yet started) Deploy
+ */
+export declare function buildProgressText(opts: BuildProgressTextOptions): string;
+//# sourceMappingURL=check-run-summary.d.ts.map