@kici-dev/orchestrator 0.1.20 → 0.1.21

package/dist/lockfile-validate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lock-load shape + compatibility validation.
+ *
+ * A fetched lock must be a valid JSON document whose schemaVersion matches this
+ * orchestrator's engine SCHEMA_VERSION exactly, and whose routing matchers are
+ * well-formed LabelMatcher objects. A lock compiled by an older engine stored
+ * `runsOn` as a plain string array; without this gate those strings would parse
+ * past the dispatch path as an empty label set and mis-route jobs to an
+ * arbitrary scaler. These checks run at the cache choke point and surface as a
+ * `LockFileParseError` (the established corrupt-lock signal).
+ */
+import { type LockFile } from '@kici-dev/engine';
+/** Parse the raw lock JSON and assert the minimal document shape. */
+export declare function parseLockDocument(raw: string, repoIdentifier: string, ref: string): LockFile;
+/** Reject a lock whose schemaVersion does not exactly match this orchestrator. */
+export declare function assertLockFileSchemaCompatible(lockFile: LockFile): void;
+/**
+ * Walk every static job's runsOn / excludeLabels / runsOnAll matchers and throw
+ * if any element is not a valid LabelMatcher. Dynamic job generators carry no
+ * static routing matchers, so only static jobs are checked (mirrors
+ * assertLockFileRegexesSafe).
+ */
+export declare function assertLockFileMatchersValid(lockFile: LockFile): void;
+//# sourceMappingURL=lockfile-validate.d.ts.map

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -14,7 +14,8 @@
  * results through the pipeline.
  */
 import { CacheRefScope } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, SimulatedEvent, WorkflowDecision, MaterializedJob } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, LockJob, SimulatedEvent, WorkflowDecision, MaterializedJob } from '@kici-dev/engine';
+import { type HostRosterStore } from '../agent/host-roster.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
@@ -126,6 +127,25 @@ export declare function runsOnSelectorsForLockJob(lockJob: {
     runsOn?: readonly LabelMatcher[];
     excludeLabels?: readonly LabelMatcher[];
 }): JobRoutingSelectors;
+/**
+ * Resolve a generated job's single bare-`agentId` `runsOn` into a host pin.
+ *
+ * The documented inventory fan-out pattern is `runsOn: [h.agentId]`. A bare
+ * agentId is not a label any agent advertises, so the normal label path leaves
+ * the job `queued-no-backend`. When the single exact label names a known roster
+ * host, resolve it to a `pinnedAgentId` dispatch (+ the host's coordinator for
+ * cross-cluster reroute) — exact parity with how `runsOnAll` children pin. Any
+ * other shape (multi-label, a regex pattern, a non-roster label, or no roster
+ * store) returns null and the caller keeps normal label routing.
+ */
+export declare function resolveRosterAgentPin(args: {
+    runsOnLabels: string[];
+    runsOnPatterns: LabelMatcher[];
+    hostRosterStore: HostRosterStore | undefined;
+}): Promise<{
+    pinnedAgentId: string;
+    connectedInstanceId: string | null;
+} | null>;
 /** Per-child rolling-wave plan: which children are held + the base's wave policy. */
 export interface WavePlan {
     /** `expandedName`s held behind the wave gate (beyond the maxParallel window). */
@@ -149,6 +169,38 @@ export interface WavePlan {
  * job (single child) or one without `maxParallel` contributes nothing.
  */
 export declare function computeWavePlan(materializedJobs: readonly MaterializedJob[]): WavePlan;
+export interface GeneratedJobConfig {
+    /**
+     * The generated lock job with its `name` and `needs` rewritten to expanded
+     * matrix-child names (identical to the base job for non-matrix generated
+     * jobs). Downstream dispatch / needs-edge / tracking code keys on this name.
+     */
+    genJob: LockJob;
+    genJobConfig: Record<string, unknown>;
+    runsOnLabels: string[];
+    /** Regex matchers the agent's labels must satisfy (JS post-filter). */
+    runsOnPatterns: LabelMatcher[];
+    /** Exact labels the dispatched agent must NOT have. */
+    excludeLabels: string[];
+    /** Regex matchers that disqualify an agent (JS post-filter). */
+    excludePatterns: LabelMatcher[];
+    /** Host-fanout pin: when runsOn resolved to a roster host, route only to it. */
+    pinnedAgentId?: string;
+    /** The host's current coordinator (cross-cluster reroute hint); null = not connected. */
+    connectedInstanceId?: string | null;
+    /** The matrix combination for this child; absent for non-matrix generated jobs. */
+    matrixValues?: Record<string, unknown>;
+}
+/**
+ * Split generated configs into pinned (host-pin dispatch) and unpinned (normal
+ * label routing). A pinned config always rides the dispatcher pin path because
+ * the coordinator's `JobToRoute` shape carries no pin field — routing it via the
+ * coordinator would silently drop the pin.
+ */
+export declare function partitionGeneratedConfigsByPin(configs: readonly GeneratedJobConfig[]): {
+    pinnedConfigs: GeneratedJobConfig[];
+    unpinnedConfigs: GeneratedJobConfig[];
+};
 /**
  * Dispatch a single matched workflow.
  *

package/dist/pipeline/test-pipeline.d.ts

@@ -30,6 +30,7 @@ import type { VariableStore } from '../environments/variable-store.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
+import type { CheckMode } from '@kici-dev/engine';
 /**
  * Input for a test trigger request.
  */
@@ -69,6 +70,12 @@ export interface TestTriggerInput {
     inlineLockFile?: string;
     /** When true, repo has no remote -- skip provider lookup, skip clone. */
     fullRepo?: boolean;
+    /**
+     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`).
+     * Threaded onto each dispatched job's config and persisted on the run.
+     * Omitted means `apply`.
+     */
+    checkMode?: CheckMode;
 }
 /**
  * Result of processing a test trigger.

package/dist/providers/github/manifest-form.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GitHub's create-from-manifest flow is an HTML form POST (the `manifest`
+ * JSON cannot ride in a query string). These helpers render the auto-submitting
+ * form and the headless code-display page. Pure string builders — no IO — so
+ * both the CLI loopback server and the static marketing-site page can reuse the
+ * same shapes.
+ */
+export declare function manifestCreateUrl(githubOrg?: string): string;
+export declare function renderManifestFormHtml(opts: {
+    createUrl: string;
+    state: string;
+    manifestJson: string;
+}): string;
+export declare function renderCodeDisplayHtml(code: string): string;
+//# sourceMappingURL=manifest-form.d.ts.map

package/dist/providers/github/manifest.d.ts

@@ -0,0 +1,78 @@
+/**
+ * GitHub App Manifest flow helpers. The manifest encodes KiCI's exact
+ * permissions + events + webhook config so the operator never picks them by
+ * hand — GitHub creates a correctly-configured App from this object in one
+ * click. See docs.github.com "Registering a GitHub App from a manifest".
+ *
+ * The webhook secret is NOT part of the manifest: GitHub generates it during
+ * registration and returns it on the conversion response, so both GitHub and
+ * the Platform end up sharing the same secret with zero operator effort.
+ */
+import { Octokit } from '@octokit/rest';
+export interface GithubManifestInput {
+    /** App name shown on GitHub. */
+    name: string;
+    /** Full https webhook URL (org-scoped) GitHub will POST events to. */
+    webhookUrl: string;
+    /** Loopback or static-page callback GitHub redirects to with the setup code. */
+    redirectUrl: string;
+    /** Optional post-install redirect. */
+    setupUrl?: string;
+}
+/** The JSON object GitHub's create-from-manifest endpoint expects. */
+export interface GithubAppManifest {
+    name: string;
+    url: string;
+    hook_attributes: {
+        url: string;
+        active: boolean;
+    };
+    redirect_url: string;
+    setup_url?: string;
+    public: boolean;
+    default_permissions: Record<string, string>;
+    default_events: string[];
+}
+export declare function buildGithubAppManifest(input: GithubManifestInput): GithubAppManifest;
+/** Credentials returned by GitHub's manifest-conversion endpoint. */
+export interface GithubAppCredentials {
+    appId: string;
+    slug: string;
+    privateKey: string;
+    webhookSecret: string;
+    clientId?: string;
+    clientSecret?: string;
+    htmlUrl?: string;
+}
+/**
+ * Exchange the short-lived manifest `code` for the App's id, private key, and
+ * webhook secret. Runs server-to-server directly against GitHub — the private
+ * key never transits the Platform.
+ */
+export declare function convertManifestCode(code: string, deps?: {
+    octokit?: Pick<Octokit, 'request'>;
+}): Promise<GithubAppCredentials>;
+/**
+ * Poll GitHub (as the App, via a JWT) until at least one installation exists,
+ * returning the first installation's id + account login. Throws on timeout.
+ */
+export declare function waitForInstallation(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, opts: {
+    timeoutMs: number;
+    pollMs: number;
+    now?: () => number;
+    appOctokit?: Pick<Octokit, 'request'>;
+}): Promise<{
+    installationId: number;
+    accountLogin: string;
+}>;
+/**
+ * Mint an installation token from the captured private key and confirm the App
+ * can reach repos — proves the key works end-to-end (the same path the agent's
+ * clone uses at runtime).
+ */
+export declare function verifyRepoAccess(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, installationId: number, deps?: {
+    octokit?: Pick<Octokit, 'request'>;
+}): Promise<{
+    repoCount: number;
+}>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/reporting/execution-tracker.d.ts

@@ -227,7 +227,9 @@ export declare class ExecutionTracker {
         max?: number;
     }, 
     /** Workflow-level wall-clock timeout in ms from the lock file. Sets the run deadline. */
-    workflowTimeoutMs?: number): Promise<void>;
+    workflowTimeoutMs?: number, 
+    /** Run mode for idempotent steps; non-apply labels the run a check-mode preview. */
+    checkMode?: string): Promise<void>;
     /**
      * Add additional jobs to an already-started execution run.
      * Used when build jobs are tracked early and regular jobs are dispatched later.
@@ -250,6 +252,13 @@ export declare class ExecutionTracker {
      * uses, so dispatchEvalJob can swap it for the real eval job id.
      */
     findDynamicEvalSyntheticId(runId: string, evalJobName: string): Promise<string | undefined>;
+    /**
+     * Durably mark the projected `execution_jobs` row so run-recovery sweepers
+     * know this job lives on a remote worker peer and must not be force-failed
+     * while that worker is connected. Called by the owning coordinator right
+     * after a peer ACKs a reroute.
+     */
+    markJobReroutedToPeer(runId: string, jobId: string, peerId: string): Promise<void>;
     /**
      * Run `fn` while holding a per-run lock, serializing the run-mutating methods
      * (`onJobStatus`, `addJobsToRun`) so a status reply cannot interleave with the

package/dist/routes/admin-sources.d.ts

@@ -28,6 +28,17 @@ interface SourceRouteDeps {
         webhookUrl: string | null;
         webhookNote?: string;
     }>;
+    /**
+     * Resolve the org-scoped GitHub webhook URL for the manifest setup flow
+     * BEFORE any App exists. The GitHub webhook URL is org-scoped
+     * (`<base>/webhook/<orgId>/github`), not app-scoped, so it can be computed
+     * up front and baked into the App manifest. Returns null + a note when the
+     * orchestrator cannot yet resolve a public base or its org id.
+     */
+    resolveGithubWebhookUrl?: () => Promise<{
+        webhookUrl: string | null;
+        webhookNote?: string;
+    }>;
 }
 type AdminSourcesEnv = {
     Variables: {

package/dist/routes/admin.d.ts

@@ -77,6 +77,14 @@ export interface AdminRouteDeps {
         webhookUrl: string | null;
         webhookNote?: string;
     }>;
+    /**
+     * Optional -- resolves the org-scoped GitHub webhook URL for the manifest
+     * setup pre-flight (before any App exists). Wired in platform/hybrid mode.
+     */
+    resolveGithubWebhookUrl?: () => Promise<{
+        webhookUrl: string | null;
+        webhookNote?: string;
+    }>;
     /** Optional -- for DB migration endpoints. */
     db?: Kysely<any>;
     /** Optional -- for DB migration endpoints. */

package/dist/secrets/pg-secret-store.d.ts

@@ -10,6 +10,15 @@ import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { SecretStore } from '@kici-dev/engine';
 import type { AuditLogger } from './audit-logger.js';
+/**
+ * Thrown by `renameScope` when the named scope has no secret rows and no
+ * environment binding — i.e. there is nothing to rename. Consumers map this to
+ * a 404 (admin HTTP route) or a structured not-found response (dashboard path).
+ */
+export declare class SecretScopeNotFoundError extends Error {
+    readonly scope: string;
+    constructor(scope: string);
+}
 /**
  * PostgreSQL secret store with AES-256-GCM encryption.
  * Uses scoped_secrets table keyed by (org_id, scope, key).