@kici-dev/orchestrator 0.14.2 → 0.16.0

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

@@ -2,56 +2,12 @@
  * Secret management commands for kici-admin.
  *
  * Provides scoped secret operations:
- *   secret scopes, list, set, delete, fix-prefixed-scopes
+ *   secret scopes, list, set, delete
  *   secret scope create|rename|delete
  *
  * Secret values are write-only -- there is no "get value" command.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
-/** One planned rename from a stored qualified scope to its bare path. */
-export interface PrefixedScopeRename {
-    from: string;
-    to: string;
-    backendName: string;
-}
-/** One stored scope that cannot be repaired automatically. */
-export interface PrefixedScopeSkip {
-    scope: string;
-    reason: string;
-}
-/** Outcome of planning the repair of legacy qualifier-bearing scopes. */
-export interface PrefixedScopeFixPlan {
-    renames: PrefixedScopeRename[];
-    skips: PrefixedScopeSkip[];
-}
-/**
- * Plan the repair of scopes stored with a `<backend>:` qualifier still attached.
- *
- * Before backend-qualified routing landed on the HTTP admin plane, a scope
- * written as `pg:production` was stored verbatim, so the stored name carries a
- * qualifier the resolver now strips before it reaches the store. Such a row is
- * unreachable: every read addresses the bare `production`.
- *
- * Only a `pg:` qualifier is repaired. The scopes handed in come out of the PG
- * store, so a row named `vault:foo` is a PG row wearing another backend's
- * name: renaming it to `foo` would turn it into a genuine PG secret, moving it
- * across a backend boundary and past a `pgCustomerSecrets: false` setting that
- * exists to keep customer secrets out of PG. That is the same cross-backend
- * move the rename route refuses, so it is reported as a skip instead.
- *
- * An unregistered head is left alone entirely -- it is an ordinary (if
- * unusual) scope path, not a stale qualifier.
- *
- * A repair whose bare target already exists is SKIPPED, never merged: merging
- * two scopes would silently overwrite whichever key the two share, and there
- * is no way to tell which value the operator meant to keep.
- *
- * Pure -- no I/O, so the decision table is unit-testable without a database.
- *
- * @param scopes - Scope names as currently stored in the PG backend.
- * @param backendNames - Names of the registered secret backends.
- */
-export declare function planPrefixedScopeFixes(scopes: string[], backendNames: string[]): PrefixedScopeFixPlan;
 export declare function registerSecretCommands(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=secret.d.ts.map

package/dist/cli/commands/service-health.d.ts

@@ -30,6 +30,26 @@ export interface LocalEndpoint {
 export declare function readLocalEndpoint(envContent: string, defaultPort: number): LocalEndpoint;
 /** The URL of `pathname` on `endpoint`, with an IPv6 host bracketed. */
 export declare function localUrl(endpoint: LocalEndpoint, pathname: string): string;
+/** What a local JSON request got: a body, a refusing status, or no answer at all. */
+export type LocalJsonResult<T> = {
+    kind: 'ok';
+    status: number;
+    body: T;
+} | {
+    kind: 'http-error';
+    status: number;
+} | {
+    kind: 'no-answer';
+};
+/**
+ * GET a JSON body from a service on this host. `acceptStatuses` names the
+ * non-2xx codes whose body is still an answer; `headers` carries credentials.
+ */
+export declare function requestLocalJson<T>(endpoint: LocalEndpoint, pathname: string, opts?: {
+    acceptStatuses?: readonly number[];
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+}): Promise<LocalJsonResult<T>>;
 /**
  * GET a JSON body from a service on this host. `acceptStatuses` names the
  * non-2xx codes whose body is still an answer: `/ready` returns its checks
@@ -39,22 +59,10 @@ export declare function fetchLocalJson<T>(endpoint: LocalEndpoint, pathname: str
     acceptStatuses?: readonly number[];
     timeoutMs?: number;
 }): Promise<T | null>;
-/**
- * A `/health` body with its deprecated `buildCommit` replaced by its version.
- * A service older than this CLI reports a commit ID from KiCI's private
- * repository there, which a reader cannot resolve; `--json` keeps the key, a
- * string as before, and carries the release version in it. A body that reports
- * no `buildCommit` comes back unchanged.
- */
-export declare function hideBuildCommit<T extends {
-    version?: string;
-    buildCommit?: string;
-}>(health: T): T;
 /**
  * Rows for the build fingerprint and process uptime of a `/health` body. A
  * field the body lacks is skipped, so a service older than this CLI renders
- * the fields it does report. The version line never shows `buildCommit`
- * (see {@link hideBuildCommit}).
+ * the fields it does report.
  */
 export declare function buildInfoRows(health: Partial<LivenessBase & BuildFingerprint & {
     buildDate: string;

package/dist/cli/commands/shared/cli-action.d.ts

@@ -0,0 +1,17 @@
+/** Commander option flag and help text shared by every command that can bypass HTTP. */
+export declare const DIRECT_DB_URL_FLAG = "--database-url <url>";
+export declare const DIRECT_DB_URL_HELP = "Use direct DB access instead of HTTP (offline mode)";
+/** `--database-url`, else `KICI_DATABASE_URL`, else null (null = use the HTTP admin API). */
+export declare function resolveDirectDbUrl(explicit?: string): string | null;
+/** Like {@link resolveDirectDbUrl} but required: throws when neither source is set. */
+export declare function resolveDatabaseUrl(explicit?: string): string;
+/** Parse an optional integer flag; throws naming the flag on a non-integer. */
+export declare function parseIntOption(raw: string | undefined, label: string): number | undefined;
+/**
+ * Wrap a Commander action so any thrown error prints `Error: <message>` to
+ * stderr and exits 1.
+ */
+export declare function cliAction<A extends unknown[]>(fn: (...args: A) => Promise<void> | void): (...args: A) => Promise<void>;
+/** Print `value` as one JSON line when `json` is set, otherwise hand it to `render`. */
+export declare function printJsonOr<T>(json: boolean | undefined, value: T, render: (v: T) => void): void;
+//# sourceMappingURL=cli-action.d.ts.map

package/dist/cli/commands/shared/db.d.ts

@@ -1,16 +1,16 @@
 /**
  * Shared database helper for CLI commands that need direct DB access.
  *
- * Provides a withDb() wrapper that creates a database connection from
- * KICI_DATABASE_URL, runs a callback, and ensures cleanup.
+ * Provides a withDb() wrapper that creates a database connection from the
+ * URL it is given (or KICI_DATABASE_URL when none is passed), runs a callback,
+ * and ensures cleanup.
  */
 import pg from 'pg';
 import { Kysely } from 'kysely';
 /**
  * Execute a callback with a database connection, then clean up.
  *
- * Reads the database URL from KICI_DATABASE_URL.
- * Creates a connection pool, runs the callback, and destroys the pool.
+ * Connects to `databaseUrl`, or to KICI_DATABASE_URL when none is passed.
  */
-export declare function withDb<T>(fn: (db: Kysely<any>, pool: pg.Pool) => Promise<T>): Promise<T>;
+export declare function withDb<T>(fn: (db: Kysely<any>, pool: pg.Pool) => Promise<T>, databaseUrl?: string | undefined): Promise<T>;
 //# sourceMappingURL=db.d.ts.map

package/dist/cli/commands/shared/org-id.d.ts

@@ -0,0 +1,5 @@
+/** Where an operator finds an org id: appended to every org-id input's help. */
+export declare const ORG_LIST_HINT = "kici-admin org list prints the org ids";
+/** Help text of an org-id argument or `--org` option. */
+export declare const ORG_ID_HELP = "Org id (kici-admin org list prints the org ids)";
+//# sourceMappingURL=org-id.d.ts.map

package/dist/cli/commands/shared/service-verbs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The service lifecycle verbs shared by `kici-admin agent` and `kici-admin orchestrator`:
+ * `uninstall`, `start`, `stop`, `restart` and `logs`.
+ *
+ * Target resolution goes through resolveInstanceTarget — the priority chain every
+ * lifecycle command uses (--instance-dir > --name > CWD manifest > refusal with
+ * candidate list). `--name` has no default.
+ */
+import type { Command } from 'commander';
+export type ServiceComponent = 'agent' | 'orchestrator';
+/**
+ * Register `uninstall`, `start`, `stop` and `restart` on a component's command group.
+ * Commander lists subcommands in registration order, so the caller places this
+ * between `install` and `status`.
+ */
+export declare function registerServiceLifecycleVerbs(parent: Command, component: ServiceComponent): void;
+/** Register `logs` on a component's command group (listed after `status`). */
+export declare function registerServiceLogsVerb(parent: Command, component: ServiceComponent): void;
+//# sourceMappingURL=service-verbs.d.ts.map

package/dist/cli/commands/shared/table.d.ts

@@ -0,0 +1,3 @@
+/** Render a left-aligned, two-space-gapped text table with a dashed separator row. */
+export declare function renderTable(headers: string[], rows: string[][]): string;
+//# sourceMappingURL=table.d.ts.map

package/dist/cli/commands/shared/unbound-context-warning.d.ts

@@ -1,23 +1,3 @@
-/**
- * The warning `kici-admin context create` and `kici-admin secret set` print
- * when a context's secrets cannot reach any job.
- *
- * A job that lists a context in its `contexts:` receives the context's
- * secrets only through the context's scope bindings: the secret resolver reads
- * the bindings of the context row the job's declared name matched — a fixed
- * context by its exact name, a glob context by its pattern — and returns
- * nothing when there are none. So such a context with no binding delivers no
- * secret to those jobs, whatever its scopes hold, and nothing fails loudly — a
- * workflow's `ctx.secrets.get()` throws at run time instead. A
- * `<context>:<key>` git-credential or registry reference to a fixed context
- * still reads the scope named after it, through a deprecated fallback; a glob
- * context has no such fallback. The warning names the context, that fallback
- * where it applies, and the `context bind` command that fixes it.
- *
- * Advisory only: the lookup runs after the command's own write succeeded, and
- * a failed lookup prints nothing, so the command's exit code never changes.
- */
-import { ContextType } from '@kici-dev/engine';
 /** The one admin API call the lookup needs, so any client shape satisfies it. */
 export interface ContextLookupClient {
     get<T>(path: string): Promise<T>;
@@ -32,8 +12,8 @@ export interface WarnIfContextUnboundArgs {
     /** Where the warning goes; stderr by default. */
     warn?: (line: string) => void;
 }
-/** The warning line for a context of `type` with no binding. */
-export declare function unboundContextWarning(orgId: string, name: string, type: ContextType): string;
+/** The warning line for a context with no binding. */
+export declare function unboundContextWarning(orgId: string, name: string): string;
 /**
  * Print the unbound-context warning when `name` is a context a job can resolve
  * through (a fixed or glob context, `ContextType`) that has no binding. A

package/dist/cli/commands/source-manifest.d.ts

@@ -19,9 +19,9 @@ export interface ManifestSetupOptions {
     githubOrg?: string;
     /**
      * Self-hosted webhook URL override. When set, it is baked verbatim into the
-     * App manifest's `hook_attributes.url` and the platform-mode webhook-URL
-     * resolution is skipped — so the flow works even where the auto-resolved KiCI
-     * platform URL is unavailable. KiCI adds no ingress at this URL; the operator
+     * App manifest's `hook_attributes.url` instead of the URL the orchestrator
+     * resolves for its mode — so the flow works even where that URL is
+     * unavailable. KiCI adds no ingress at this URL; the operator
      * owns delivery. Advanced/self-hosted only.
      */
     webhookUrl?: string;

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

@@ -21,6 +21,28 @@
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
+/** Structural row a listed generic/local source exposes for text rendering.
+ *  Both the HTTP `GenericSourceResponse` and the DB `GenericWebhookSource`
+ *  satisfy it, so `renderSourceListText` renders either transport's output. */
+interface ListableGenericRow {
+    id: string;
+    name: string;
+    routing_key: string;
+    enabled: boolean;
+    deleted_at?: unknown;
+}
+/** Render the human-readable `source list` output shared by the HTTP and the
+ *  direct-DB branches. `hasOrg` mirrors whether `--org` was passed (generic
+ *  sources are only listed for a specific org). `opts.directDb` marks a direct
+ *  DB read, which has no ingress URLs to print. */
+export declare function renderSourceListText(githubSources: Array<{
+    routingKey: string;
+    name: string;
+    provider: string;
+    ingressUrl?: string | null;
+}>, genericSources: ListableGenericRow[], hasOrg: boolean, opts: {
+    directDb: boolean;
+}): void;
 /** Error shown when both the private key and the webhook secret ask for stdin. */
 export declare const BOTH_STDIN_ERROR = "cannot read both the private key and the webhook secret from stdin \u2014 use @file or --from-env for one of them";
 /**
@@ -34,4 +56,5 @@ export declare function resolveWebhookSecret(opts: {
     privateKeyFromStdin: boolean;
 }, readStdin?: () => Promise<string>): Promise<string | undefined>;
 export declare function registerSourceCommands(program: Command, getClient: () => AdminApiClient): void;
+export {};
 //# sourceMappingURL=source.d.ts.map

package/dist/cli/commands/trust-policy.d.ts

@@ -17,7 +17,7 @@
  *
  * The two directory writers live in this namespace rather than one of their
  * own because they are the same org-trust concept as the policy, gated by the
- * same mode rule against the same `--customer-id`, and reached through the same
+ * same mode rule against the same `--org`, and reached through the same
  * admin route file. Splitting them out would put half of "who may approve" in a
  * second top-level command with its own copy of that story. They are siblings
  * of the `directory` reader rather than subcommands under it, because turning
@@ -40,11 +40,7 @@ import type { AdminApiClient } from '../api-client.js';
 export interface TrustPolicyView {
     customerId: string;
     forkPolicy?: string;
-    approvalExpiryHours?: number;
-    /**
-     * The authoritative hold window. Absent from any orchestrator that predates
-     * it, in which case `approvalExpiryHours` is the only window on offer.
-     */
+    /** The hold window, in seconds. */
     approvalExpirySeconds?: number;
     source: string | null;
     updatedAt: string | null;
@@ -62,21 +58,13 @@ export declare function formatPolicy(policy: TrustPolicyView, format: string): s
  * touched to a policy they never set, so the reader of `trust-policy show`
  * is told outright — with where to look for each individual drop.
  *
- * Returns the lines rather than printing them so the check is unit-testable,
- * matching `policyExpiryWarnings` below.
+ * Returns the lines rather than printing them so the check is unit-testable.
  */
 export declare function forkDropWarnings(policy: TrustPolicyView): string[];
 /**
- * Render the enforced hold window.
- *
- * A whole number of hours still prints as `72 h`, exactly as it always did, so
- * no existing policy's output moves. Anything finer prints in seconds, because
- * the hours spelling cannot express it and rounding would report a window the
- * orchestrator is not applying.
- *
- * A policy carrying neither field is an orchestrator old enough to have
- * resolved no policy at all (see {@link TrustPolicyView}); one carrying only
- * hours is an orchestrator that predates the seconds window.
+ * Render the enforced hold window in the duration spelling `--approval-expiry`
+ * takes (`72h`, `1h30m`). A policy carrying no window is an orchestrator old
+ * enough to have resolved no policy at all (see {@link TrustPolicyView}).
  */
 export declare function formatExpiry(policy: TrustPolicyView): string;
 /**
@@ -86,17 +74,6 @@ export declare function formatExpiry(policy: TrustPolicyView): string;
  * clear local message naming the accepted values instead of a 400 from the API.
  */
 export declare function buildPolicyPatch(opts: Record<string, string | undefined>): Record<string, string | number>;
-/**
- * Warn when a patch names both spellings of the hold window.
- *
- * The route resolves this deterministically — the more specific seconds value
- * wins — but an operator who passed both asked for two different things, so the
- * one that is not applied is named rather than dropped in silence.
- *
- * Returns the lines rather than printing them so the check is unit-testable,
- * matching `forkDropWarnings` above.
- */
-export declare function policyExpiryWarnings(patch: Record<string, string | number>): string[];
 /** One identity link as the directory route reports it. */
 interface DirectoryIdentityLink {
     userId: string;
@@ -154,8 +131,7 @@ export declare function formatDirectoryAge(updatedAt: string, now: number): stri
  * The connected wording is a `Note:` and the disconnected one a `Warning:`,
  * because the two ask for different things: one states a property of the design
  * the reader should know, the other names a condition they should act on. The
- * `Warning:` producers above — `forkDropWarnings` and `policyExpiryWarnings` —
- * are both of the second kind.
+ * `Warning:` producer above, `forkDropWarnings`, is of the second kind.
  *
  * Returns the lines rather than printing them so the check is unit-testable,
  * matching `forkDropWarnings` above.

package/dist/cli/join.d.ts

@@ -2,8 +2,8 @@
  * `kici-admin join` command.
  *
  * Bootstraps a new orchestrator by connecting to an existing cluster via
- * Platform relay or direct peer, receiving an encrypted config bundle, and
- * writing an env file the orchestrator boots from.
+ * Platform relay or direct peer, receiving the configuration bundle sealed to
+ * this host, and writing an env file the orchestrator boots from.
  *
  * Usage:
  *   kici-admin join --token kici_join_v1.xxx.yyy --platform wss://api.kici.dev/ws --api-key KEY

package/dist/cli/kici-admin.d.ts

@@ -6,8 +6,13 @@
  * through the orchestrator's admin HTTP API.
  *
  * Global options:
- *   --url / -u    Orchestrator URL (env: KICI_ADMIN_URL, default: http://localhost:8080)
+ *   --url / -u    Orchestrator URL (env: KICI_ADMIN_URL, default: http://localhost:4000)
  *   --token / -t  Admin API token (env: KICI_ADMIN_TOKEN, required)
+ *   -V / --cli-version / --version  Print the CLI version (--version only before a command)
+ *
+ * A command that declares its own option under one of these flags (for
+ * example `orchestrator upgrade --url`) owns that flag after its name; see
+ * `root-option-routing.ts`.
  */
 import { Command } from 'commander';
 /**

package/dist/cli/local-github-ingress-url.d.ts

@@ -5,4 +5,10 @@
  * KICI_WEBHOOK_PUBLIC_URL" note instead of a fabricated URL).
  */
 export declare function buildLocalGithubIngressUrl(webhookPublicUrl: string | undefined, orgId: string, sourceId: string): string | null;
+/**
+ * Build the orchestrator's OWN org-scoped GitHub App ingress URL
+ * (`<base>/webhook/<orgId>/github`), served by the org-scoped direct route.
+ * Null when no public base is configured.
+ */
+export declare function buildLocalGithubAppIngressUrl(webhookPublicUrl: string | undefined, orgId: string): string | null;
 //# sourceMappingURL=local-github-ingress-url.d.ts.map

package/dist/cli/root-option-routing.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Decide which command each root-option token in a kici-admin argv belongs to.
+ *
+ * Commander matches a program option anywhere in argv: the root's own
+ * `parseOptions` consumes `-u, --url`, `-t, --token` and `-V, --cli-version`
+ * even after a command name. That lets an operator put a global option after
+ * the command (`kici-admin runs list -u <url>`), but on its own it would also
+ * take an option away from any command that declares one with the same flag,
+ * such as `orchestrator upgrade --url <archive-url>` or
+ * `join --token <join-token>`.
+ *
+ * {@link routeRootArgs} prepares the argv for the root's `parseOptions`:
+ *
+ * - A flag that the command being run declares, and that also names a root
+ *   option, belongs to that command when it comes after the command's name. It
+ *   is hidden from the root behind an opaque stand-in token, which the root
+ *   classifies as an unknown option and so hands on to the subcommand; the
+ *   stand-ins are mapped back to the original tokens before the subcommand
+ *   parses them.
+ * - `--version` before the first command name is the root's version flag. The
+ *   root cannot register `--version` itself (`orchestrator upgrade` and
+ *   `agent upgrade` own `--version <version>`), so it is rewritten to the
+ *   registered `--cli-version`. After a command name it is left alone.
+ *
+ * - The value of a command option, when it is shaped like an option (`-uP4ss`,
+ *   `--url`), is hidden from the root the same way, so the root does not read
+ *   it as one of its own flags.
+ *
+ * Every other token reaches the root unchanged, so a root option after a
+ * command that does not declare that flag still sets the global option.
+ */
+import type { Command } from 'commander';
+/** The flag the root registers its version option under. */
+export declare const ROOT_VERSION_FLAG = "--cli-version";
+/** The root's argv, routed, and the map from each stand-in back to its token. */
+export interface RoutedRootArgs {
+    readonly args: string[];
+    /** Map a token from the root's parse result back to the original token. */
+    readonly restore: (token: string) => string;
+}
+/**
+ * Route a kici-admin argv (the user arguments, without `node` and the script)
+ * for the root command's `parseOptions`. See the module comment.
+ */
+export declare function routeRootArgs(root: Command, args: readonly string[]): RoutedRootArgs;
+//# sourceMappingURL=root-option-routing.d.ts.map

package/dist/cli/webhook-url-notes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The text the CLI prints when the orchestrator returns no webhook URL. Shared
+ * by `kici-admin source add` and the manifest setup flow, so each
+ * `WebhookUrlNote` reads the same in both.
+ */
+import { WebhookUrlNote } from '../sources/webhook-url-resolvers.js';
+/**
+ * Short reason shown in `(unavailable — <reason>)` when no webhook URL could be
+ * resolved. Takes a plain string too, because an orchestrator of another
+ * version can send a note this CLI does not know.
+ */
+export declare function webhookNoteReason(note: WebhookUrlNote | string | undefined): string;
+/** Actionable next-step hint paired with {@link webhookNoteReason}. */
+export declare function webhookNoteHint(note: WebhookUrlNote | string | undefined): string;
+//# sourceMappingURL=webhook-url-notes.d.ts.map