@kici-dev/orchestrator 0.1.22 → 0.1.24

package/dist/agent/host-roster.d.ts

@@ -3,6 +3,19 @@ import { type HostInventoryEntry, type InventorySelector, type LabelMatcher } fr
 import type { Database, HostRosterRow } from '../db/types.js';
 /** Typed host-vars bag carried by roster rows (`string | number | boolean`). */
 export type HostProperties = Record<string, string | number | boolean>;
+/**
+ * Pre-agent reach metadata for a declared host — how to SSH to it for bootstrap
+ * bring-up before it has a KiCI agent. All fields nullable: a host with no reach
+ * metadata cannot be bootstrapped. `sshKeySecret` is a scoped-secret ref
+ * (`scope/key`) the orchestrator resolves server-side; the key never lives here.
+ */
+export interface HostReach {
+    agentId: string;
+    address: string | null;
+    sshUser: string | null;
+    sshPort: number | null;
+    sshKeySecret: string | null;
+}
 /**
  * Derived (read-time) status of a roster host. Never a stored mutable column:
  * status is computed from the shared `last_seen` + `connected_instance_id` so
@@ -96,13 +109,36 @@ export declare class HostRosterStore {
     markDisconnected(agentId: string, instanceId: string): Promise<void>;
     /** Coarse heartbeat stamp — same owner-guard as markDisconnected. */
     stampLastSeen(agentId: string, instanceId: string): Promise<void>;
-    /** Operator pre-declare of a static host before its agent dials in. */
+    /**
+     * Operator pre-declare of a static host. A re-declare of an existing agent_id
+     * converges the operator-owned columns (labels, hostname, reach,
+     * host_properties) to the newly-declared values while preserving the
+     * agent-reported liveness/identity columns (connected_instance_id, last_seen,
+     * platform, arch, lifecycle_class, token_id, reboot_pending_until). The
+     * optional reach fields (`address`/`sshUser`/`sshPort`/`sshKeySecret`) carry
+     * how to SSH to the host for bootstrap bring-up. Each operator field is
+     * preserve-on-omit: an omitted field keeps the existing column value.
+     *
+     * Returns `{ created: true }` when the declare inserted a new row,
+     * `{ created: false }` when it converged an existing one.
+     */
     declareStatic(input: {
         agentId: string;
-        labels: string[];
+        labels?: string[];
         hostname?: string;
         properties?: HostProperties;
-    }): Promise<void>;
+        address?: string;
+        sshUser?: string;
+        sshPort?: number;
+        sshKeySecret?: string;
+    }): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Read a host's pre-agent reach metadata. Returns null when the host is not
+     * in the roster; a host declared without reach fields reads back with nulls.
+     */
+    getReach(agentId: string): Promise<HostReach | null>;
     get(agentId: string): Promise<HostRosterRow | null>;
     listAll(): Promise<HostRosterRow[]>;
     /**

package/dist/agent/token-store.d.ts

@@ -19,11 +19,15 @@ export declare class AgentTokenStore {
      * Static tokens have no expiry and are intended for manually-registered agents.
      *
      * @param opts.labels - Optional agent labels this token is authorized for.
+     * @param opts.mandatoryLabels - Optional taint labels (a Kubernetes-taint-style
+     *   gate): a static agent registering with this token only accepts a job when
+     *   every label here appears in the job's required labels. Undefined = no taint.
      * @param opts.createdBy - Optional creator identifier (e.g. "cli:admin").
      * @returns The plaintext token (shown once) and the DB row ID.
      */
     createStatic(opts: {
         labels?: string[];
+        mandatoryLabels?: string[];
         createdBy?: string;
     }): Promise<{
         token: string;
@@ -41,6 +45,35 @@ export declare class AgentTokenStore {
      * @returns The plaintext token (shown once).
      */
     createEphemeral(agentId: string, labels: string[], ttlMs: number): Promise<string>;
+    /**
+     * Mint a single-use, short-TTL bootstrap token for an init-runner bring-up.
+     *
+     * The token is stored as `agent_type: 'ephemeral'` (so the existing expiry
+     * cleanup reaps it) and is bound to exactly the init-runner label set. It is
+     * single-use: `consumeBootstrapToken` sets `consumed_at` on first
+     * `agent.register`, and a second register is rejected. A leaked token is
+     * therefore inert after enrollment AND after its short TTL elapses.
+     *
+     * @param targetAgentId - The agent id the init-runner will register as.
+     * @param ttlMs - Time-to-live in milliseconds (short, ~10 min).
+     * @param labels - The init-runner labels the token authorizes.
+     * @returns The plaintext token (shown once) and the DB row ID.
+     */
+    mintBootstrapToken(opts: {
+        targetAgentId: string;
+        ttlMs: number;
+        labels: string[];
+    }): Promise<{
+        token: string;
+        id: string;
+    }>;
+    /**
+     * Consume a single-use bootstrap token by id. Sets `consumed_at` only when it
+     * is currently null, so the first register wins and any subsequent attempt
+     * with the same token returns false (already consumed). Returns true when
+     * this call performed the consumption.
+     */
+    consumeBootstrapToken(id: string): Promise<boolean>;
     /**
      * Validate a plaintext token against stored hashes.
      *

package/dist/app.d.ts

@@ -37,6 +37,7 @@ import type { PendingBuildTracker } from './cache/index.js';
 import type { PendingInitTracker } from './cache/index.js';
 import type { PendingDynamicTracker } from './cache/index.js';
 import type { CacheStorage } from './storage/types.js';
+import type { ProvenanceTrustRoot } from './provenance/trust-root.js';
 import { type CheckRunReporter } from './reporting/check-run-reporter.js';
 import type { ExecutionTracker } from './reporting/execution-tracker.js';
 import type { LogWriter } from './reporting/log-writer.js';
@@ -108,6 +109,8 @@ export interface AppDependencies {
     dispatchCacheRefs?: DispatchCacheRefTracker;
     /** Cache storage backend (S3) for metadata operations on upload completion. */
     cacheStorage?: CacheStorage;
+    /** Provenance trust root used to verify build-provenance bundles at ingest. */
+    provenanceTrustRoot?: ProvenanceTrustRoot;
     /**
      * Filesystem cache backend handle. Only set when KICI_STORAGE_TYPE is
      * `filesystem`. Drives the /api/v1/cache/blob/* HTTP route that serves and

package/dist/cache/pending-inits.d.ts

@@ -3,13 +3,14 @@
  *
  * The orchestrator dispatches an init job for dynamic environment resolution
  * and waits for the agent to return the resolved field values
- * (environmentName, env, concurrencyGroup). The underlying tracker logic lives
+ * (environmentNames, env, concurrencyGroup). The underlying tracker logic lives
  * in `PendingTracker<InitResult>`; this subclass wires the init-specific
  * logger prefix and disconnect error.
  */
 import { PendingTracker } from './pending-tracker.js';
 export interface InitResult {
-    environmentName?: string;
+    /** Resolved bound-environment names, in merge order (one per `environments` element). */
+    environmentNames?: string[];
     env?: Record<string, string>;
     concurrencyGroup?: string;
     /**

package/dist/cli/api-client.d.ts

@@ -206,6 +206,7 @@ export declare class AdminApiClient {
     revokeToken(id: string): Promise<void>;
     createAgentToken(opts: {
         labels?: string[];
+        mandatoryLabels?: string[];
     }): Promise<{
         id: string;
         token: string;
@@ -373,6 +374,13 @@ export declare class AdminApiClient {
     }): Promise<{
         jobs: Array<Record<string, unknown>>;
     }>;
+    /**
+     * Fetch the machine-first, provenance-tagged structured run result: typed
+     * job DAG, per-step exit codes / durations / statuses, derived failure
+     * category. Untrusted fields are envelope-tagged; secret values are never
+     * returned (only secret-output key names).
+     */
+    getRunStructured(runId: string): Promise<Record<string, unknown>>;
     /**
      * Fetch the scrub status of the run's ephemeral key. Never returns the
      * key material itself — only `{ exists, createdAt }`.

package/dist/cli/commands/attestations-reverify.d.ts

@@ -0,0 +1,18 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../../db/types.js';
+import type { CacheStorage } from '../../storage/types.js';
+import type { ProvenanceTrustRoot } from '../../provenance/trust-root.js';
+/**
+ * Backfill / refresh attestation verdicts. By default it re-evaluates only rows
+ * that have no usable verdict yet (`pending` / `unverifiable`) — the rollout
+ * path for rows recorded before verify-at-ingest, or before an org configured
+ * provenance. With `--all` it re-evaluates every row. Idempotent: re-running
+ * over already-verified rows (when `--all`) recomputes the same verdict.
+ */
+export declare function reverifyAttestations(db: Kysely<Database>, trustRoot: ProvenanceTrustRoot, storage: CacheStorage | undefined, opts: {
+    all: boolean;
+}): Promise<{
+    updated: number;
+    scanned: number;
+}>;
+//# sourceMappingURL=attestations-reverify.d.ts.map

package/dist/cli/commands/attestations.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerAttestationsCommands(program: Command): void;
+//# sourceMappingURL=attestations.d.ts.map

package/dist/cli/commands/shared/versioned-upgrade.d.ts

@@ -27,6 +27,7 @@ interface VersionedUpgradeOptions {
     yes?: boolean;
     cleanup?: boolean;
     rollback?: boolean;
+    pick?: boolean;
     force?: boolean;
 }
 /**
@@ -74,6 +75,40 @@ export declare function resolveUpgradeTarget(args: {
  *   - windows:           C:\Program Files\KiCI\<name>\
  */
 export declare function getInstallBase(platform: ServicePlatform, name: string): string;
+/** A choice row for the `--pick` interactive select. */
+export interface PickChoice {
+    value: string;
+    name: string;
+    /** `false` when selectable; a reason string when disabled (inquirer renders it). */
+    disabled: boolean | string;
+}
+/**
+ * Build the interactive `--pick` choices, newest-first (lexicographic, matching
+ * the rest of the versioned-directory handling). The currently-active version is
+ * labeled `(current)` and disabled so it cannot be selected — picking it would be
+ * a no-op restart.
+ */
+export declare function buildPickChoices(versions: string[], current: string | null): PickChoice[];
+/**
+ * The versions a `--pick` switch may target: every installed version except the
+ * currently-active one. Empty when only the current version (or nothing) is
+ * installed — the caller turns that into a "nothing to pick" error.
+ */
+export declare function selectablePickTargets(versions: string[], current: string | null): string[];
+/**
+ * Validate that `--pick` is not combined with a source/mode flag it conflicts
+ * with. `--pick` activates an already-installed version, so it never downloads
+ * (`--from`/`--url`), never takes an explicit `--version`, and is its own mode
+ * (not `--rollback`/`--cleanup`). Returns an error message, or null when OK.
+ */
+export declare function checkPickFlagConflicts(opts: {
+    pick?: boolean;
+    from?: string;
+    url?: string;
+    version?: string;
+    rollback?: boolean;
+    cleanup?: boolean;
+}): string | null;
 /**
  * Perform a versioned directory upgrade for a KiCI component.
  *
@@ -123,5 +158,22 @@ export declare function verifyNpmSourceLaunch(opts: {
     force: boolean;
 }): NpmSourceLaunchVerdict;
 export declare function performVersionedUpgrade(component: UpgradeComponent, opts: VersionedUpgradeOptions): Promise<void>;
+/**
+ * Stop the service, switch the active version pointer to an already-installed
+ * versioned directory (atomic symlink on Unix; uninstall→install + version file
+ * on Windows), restart, and persist the new `kiciVersion` into the manifest.
+ *
+ * Shared by `--rollback` (switch to the previous version) and `--pick` (switch
+ * to any chosen installed version).
+ */
+export declare function switchToInstalledVersion(args: {
+    component: UpgradeComponent;
+    platform: ServicePlatform;
+    installBase: string;
+    config: ServiceConfig;
+    manager: ServiceManager;
+    resolvedInstance: ResolvedInstance;
+    targetVersion: string;
+}): Promise<void>;
 export {};
 //# sourceMappingURL=versioned-upgrade.d.ts.map