@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/cli/commands/api-key.d.ts

@@ -1,19 +1,12 @@
 /**
- * `kici-admin api-key` — deprecated.
- *
- * The group targeted `/api/v1/api-keys`, which no KiCI server serves, so it
- * never worked. Both subcommands stay registered until v1.0.0 and exit with a
- * message that points at `kici-admin token create`, the per-person
- * orchestrator token a developer passes to `kici connect`.
- *
- *   api-key create, add-routing-key
+ * `kici-admin api-key` — deprecated. It targeted `/api/v1/api-keys`, which no
+ * KiCI server serves, so it never worked. `create` and `add-routing-key` stay
+ * registered until v1.0.0 and exit pointing at `kici-admin token create`, the
+ * per-person orchestrator token a developer passes to `kici connect`.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 export declare const API_KEY_DEPRECATED_MESSAGE: string;
-/**
- * Register the deprecated `api-key` group. `getClient` is accepted for the
- * registration signature every command group shares and is never called.
- */
+/** `_getClient` fits the shared registration signature and is never called. */
 export declare function registerApiKeyCommands(program: Command, _getClient: () => AdminApiClient): void;
 //# sourceMappingURL=api-key.d.ts.map

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

@@ -1,13 +1,11 @@
 /**
- * `kici-admin attestations list` runner — a read-only projection of the
- * orchestrator `attestations` table into a JSON envelope mirroring
- * `runs list --json`'s shape. The DB read is injected so the row→envelope
- * mapping is unit-testable without a Postgres connection (mirrors
- * attestations-retry.ts's injected-transport pattern).
+ * `kici-admin attestations list`: a read-only projection of the `attestations`
+ * table into a `runs list --json`-shaped envelope. The DB read is injected so
+ * the mapping is testable without Postgres (mirrors attestations-retry.ts's
+ * injected-transport pattern).
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../../db/types.js';
-/** One attestation row as read from the orchestrator DB (snake_case columns). */
 export interface AttestationListDbRow {
     id: string;
     run_id: string;
@@ -16,7 +14,6 @@ export interface AttestationListDbRow {
     verify_status: string;
     created_at: Date;
 }
-/** One attestation as rendered in the CLI JSON envelope (camelCase). */
 export interface AttestationListItem {
     id: string;
     runId: string;
@@ -25,7 +22,7 @@ export interface AttestationListItem {
     verifyStatus: string;
     createdAt: string;
 }
-/** Scope + bound for a list read. Filters are applied by the read fn. */
+/** The read fn applies the filters. */
 export interface AttestationListOptions {
     limit: number;
     runId?: string;
@@ -35,15 +32,8 @@ export interface AttestationListOptions {
 export interface AttestationListResult {
     attestations: AttestationListItem[];
 }
-/**
- * Map the injected DB read into the CLI envelope. `limit` / `runId` / `jobId`
- * are honored by the injected `read` fn (the real one is a Kysely query); this
- * runner owns only the row→envelope projection, so it stays pure and testable.
- */
+/** `read` honours the options; this owns only the row→envelope projection. */
 export declare function runAttestationList(read: (opts: AttestationListOptions) => Promise<AttestationListDbRow[]>, opts: AttestationListOptions): Promise<AttestationListResult>;
-/**
- * Build the real DB read: a Kysely query over `attestations`, newest first,
- * with optional run/job filters and a row cap.
- */
+/** The real read, newest first. */
 export declare function readAttestations(db: Kysely<Database>): (opts: AttestationListOptions) => Promise<AttestationListDbRow[]>;
 //# sourceMappingURL=attestations-list.d.ts.map

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

@@ -1,9 +1,8 @@
 /**
- * `kici-admin attestations retry` runner. Triggers an immediate drain of the
- * deferred-attestation outbox on the running orchestrator via the admin API —
- * minting happens in the orchestrator process, which owns the authenticated
- * Platform WebSocket. `--run-id` scopes to one run; otherwise the whole outbox
- * drains (the `--all-pending` flag is the explicit form of the default).
+ * `kici-admin attestations retry`: drains the deferred-attestation outbox now,
+ * through the admin API, because minting runs in the orchestrator process that
+ * owns the Platform WebSocket. `--run-id` scopes to one run; otherwise the whole
+ * outbox drains (`--all-pending` is the explicit form of the default).
  */
 export interface AttestationRetryOptions {
     runId?: string;
@@ -15,12 +14,7 @@ export interface AttestationRetryResult {
     stillPending: number;
     rejected: number;
 }
-/**
- * Post the retry request through the injected transport (the admin API POST)
- * and return the counts. Validates that the scope is unambiguous. When
- * `includeRejected` is set, previously terminally-rejected rows are re-armed
- * and re-attempted in the same drain.
- */
+/** `includeRejected` re-arms terminally-rejected rows and retries them in the same drain. */
 export declare function runAttestationRetry(post: (body: {
     runId?: string;
     includeRejected?: boolean;

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

@@ -3,11 +3,10 @@ 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.
+ * Re-evaluates rows with no usable verdict (`pending` / `unverifiable`), such
+ * as rows recorded before verify-at-ingest or before an org configured
+ * provenance; `--all` covers every row. Idempotent: a verified row recomputes
+ * the same verdict.
  */
 export declare function reverifyAttestations(db: Kysely<Database>, trustRoot: ProvenanceTrustRoot, storage: CacheStorage | undefined, opts: {
     all: boolean;

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

@@ -1,12 +1,7 @@
 /**
- * `kici-admin attestations` — orchestrator-DB-direct provenance maintenance.
- *
- *   attestations reverify [--all]   Recompute stored verdicts (verify-at-ingest
- *                                   backfill). Default scope: pending /
- *                                   unverifiable rows; `--all` re-evaluates
- *                                   every row. Direct DB + object storage.
- *
- * Belongs to `kici-admin`: it works on the orchestrator's database.
+ * `kici-admin attestations`: provenance maintenance on the orchestrator DB.
+ * `reverify` (direct DB + object storage) recomputes pending / unverifiable
+ * verdicts, or every row with `--all`.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

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

@@ -1,8 +1,4 @@
-/**
- * Audit log query command for kici-admin.
- *
- * Queries the secrets audit log with optional filters.
- */
+/** kici-admin query over the secrets audit log. */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 export declare function registerAuditCommands(program: Command, getClient: () => AdminApiClient): void;

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

@@ -1,15 +1,6 @@
 /**
- * Secret backend management commands for kici-admin.
- *
- * Provides subcommands for backend CRUD, connectivity testing, and sync:
- *   backend add <name>    Register a new secret backend
- *   backend remove <name> Remove a backend (with confirmation)
- *   backend list          List all registered backends
- *   backend test [name]   Test backend connectivity
- *   backend sync [name]   Trigger scope discovery sync
- *
- * Credentials are read from environment variables or files (not shell args)
- * per design decision.
+ * `kici-admin backend` commands: secret backend CRUD, connectivity tests and
+ * scope sync. Credentials come from environment variables or files, not shell args.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/check-run.d.ts

@@ -1,25 +1,14 @@
 /**
- * Check-run read CLI command for kici-admin.
- *
- *   check-run list --sha <sha> [--check-name <name>] [--limit <n>] [--json]
- *
- * READ-ONLY. Answers "did we post that check run?" — the question that
- * previously needed raw SQL against `check_run_tracking`.
- *
- * Each column answers a different half of it:
+ * `kici-admin check-run list` (read-only): did we post that check run?
  *   - CHECK_RUN_ID   the check run was created at the provider.
  *   - CREATE_STATE   stamped `pending` BEFORE the create and never reset on
- *                    failure, so `pending` distinguishes an in-flight create
- *                    from a missing one — it does not prove success.
- *   - TERMINAL_SENT  the terminal `completed` update was accepted by the
- *                    provider.
- *
- * Every write on this table is best-effort, so an em dash is "no record", never
- * proof that the call failed.
+ *                    failure: it tells an in-flight create from a missing one,
+ *                    and does not prove success.
+ *   - TERMINAL_SENT  the provider accepted the terminal `completed` update.
+ * Every write on the table is best-effort, so an em dash means "no record",
+ * never proof the call failed.
  *
- * Direct-DB only: there is no admin HTTP route for check-run tracking, so this
- * requires `--database-url` (or `KICI_DATABASE_URL`) the same way `attestations`,
- * `cluster` and `cold-store` do.
+ * Direct-DB only (no admin HTTP route), like `attestations`, `cluster` and `cold-store`.
  */
 import type { Command } from 'commander';
 export declare function registerCheckRunCommands(program: Command): void;

package/dist/cli/commands/cluster-name.d.ts

@@ -1,16 +1,9 @@
 /**
- * Cluster-name management commands for kici-admin.
- *
- * Subcommand namespace: `kici-admin cluster-name {get,set}`.
- *
- * The cluster name is the human-friendly identifier that surfaces on
- * Platform's connection registry and in the dashboard's per-orch URL
- * segment. Mutating it requires admin access (RBAC `secret.write`).
- *
- * Talks to the orchestrator admin API directly (not the Platform
- * dashboard proxy), so the CLI stays operable even when Platform is
- * unavailable. Backed by
- * `packages/orchestrator/src/routes/admin-cluster-name.ts`.
+ * `kici-admin cluster-name {get,set}`: the human-friendly identifier on the
+ * Platform's connection registry and in the dashboard's per-orch URL segment.
+ * `set` needs RBAC `secret.write`. Talks to the orchestrator admin API directly
+ * (`routes/admin-cluster-name.ts`), never the Platform proxy, so it works while
+ * the Platform is down.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/cluster-settings.d.ts

@@ -1,37 +1,30 @@
 /**
- * Cluster-settings management commands for kici-admin.
+ * `kici-admin cluster-settings <show|set|reset>`, against the orchestrator
+ * admin API directly (`routes/admin-cluster-settings.ts`), never the Platform
+ * proxy, so it works while the Platform is down. `show` also lists the settings
+ * version each coordinator and worker applied.
  *
- * Subcommand namespace: `kici-admin cluster-settings <show|set|reset>`.
- *
- * Talks to the orchestrator admin API directly (not the Platform dashboard
- * proxy), so the CLI stays operable even when Platform is unavailable. Backed
- * by `packages/orchestrator/src/routes/admin-cluster-settings.ts`. `show` also
- * lists which settings version each coordinator and worker applied.
- *
- * These knobs are fleet-wide (a single `cluster_settings` row), not per-tenant.
- * For per-tenant knobs use `kici-admin org-settings`.
+ * The knobs are fleet-wide (one `cluster_settings` row); per-tenant knobs live
+ * in `kici-admin org-settings`.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 import { type SettingsPropagationReport } from '../../cluster/settings-propagation.js';
 /**
- * One text knob. Kept separate from {@link KnobSpec} because the value parser,
- * the PATCH body type, and the `show` formatter all differ — a string knob has
- * no `min` floor and is validated by shape, not by magnitude.
+ * One text knob, separate from {@link KnobSpec} because its parser, PATCH type
+ * and `show` formatter differ: it has no `min` and is validated by shape.
  */
 interface StringKnobSpec {
     field: string;
     flag: string;
     label: string;
-    /** Human-facing description of the accepted shape, used in the error message. */
+    /** The accepted shape, as the error message names it. */
     expects: string;
     validate: (value: string) => boolean;
 }
 /**
- * One boolean knob. A third spec type for the same reason {@link StringKnobSpec}
- * is separate from {@link KnobSpec}: the value parser, the PATCH body type, and
- * the `show` formatter all differ. A boolean also has no bounds to validate —
- * only two accepted spellings.
+ * One boolean knob, separate for the same reason as {@link StringKnobSpec}; no
+ * bounds, two spellings.
  */
 interface BooleanKnobSpec {
     field: string;
@@ -52,65 +45,47 @@ export type PropagationFetch = {
     reason: string;
 };
 export declare const PROPAGATION_UNSUPPORTED_NOTE: string;
-/**
- * Fetch the propagation report. A 404 means the orchestrator predates the
- * route; `show` then prints the settings alone, because this CLI may be newer
- * than the orchestrator it talks to.
- */
+/** A 404 means an orchestrator older than this CLI; `show` then prints the settings alone. */
 export declare function fetchPropagation(client: AdminApiClient): Promise<PropagationFetch>;
 /** The table section: one row per orchestrator, lagging ones in upper case. */
 export declare function formatPropagation(report: SettingsPropagationReport): string;
 /**
- * What `show` prints. The JSON keeps the flat settings map exactly as before
- * and adds one `propagation` key, so scripts that read knob keys keep working.
+ * The JSON keeps the flat settings map plus one `propagation` key, so knob-key
+ * scripts keep working.
  */
 export declare function renderShow(settings: ClusterSettings, propagation: PropagationFetch, format: string): {
     stdout: string;
     stderr: string | null;
 };
-/**
- * Parse an integer CLI flag against its knob's bounds, exiting on failure.
- *
- * `max` is optional because most knobs have no meaningful ceiling; the ones
- * that do carry a hard boot-safety bound (see {@link KnobSpec.max}).
- */
+/** Exits on a value outside the bounds; `max` is a boot-safety bound ({@link KnobSpec.max}). */
 export declare function parseKnobValue(flag: string, value: string, min: number, max?: number): number;
 /** Validate a text CLI flag against its knob's shape, exiting on failure. */
 export declare function parseStringKnobValue(knob: StringKnobSpec, value: string): string;
 /**
- * Parse a boolean CLI flag, exiting on failure.
- *
- * Accepts only the exact strings `true` and `false`. A permissive parser (any
- * non-empty string is true) would read `--global-workflows-enabled no` as an
- * enable, which for this knob turns a typo into a security posture change.
+ * Accepts only `true` and `false`, else exits. A permissive parser would read
+ * `--global-workflows-enabled no` as an enable: a typo becomes a security
+ * posture change.
  */
 export declare function parseBooleanKnobValue(knob: BooleanKnobSpec, value: string): boolean;
 /** Assemble the PATCH body from provided `set` flags (exits if none given). */
 export declare function buildClusterPatch(opts: Record<string, string | undefined>): PatchBody;
 /**
- * Warn when only one of the two ordered global-eval timeouts is being set.
+ * Warns when only one of an ordered global-eval timeout pair is set. The wait
+ * ceiling must exceed the round budget, which starts only once the round job
+ * is RUNNING, or every round that waited for an agent fails silently. The
+ * server rejects a bad pair only when both are stored: a NULL column means the
+ * orchestrator's configured default, which the route cannot see.
  *
- * The orchestrator's wait ceiling must exceed the agent's round budget — the
- * agent's budget starts only once the round job is RUNNING, so a lower ceiling
- * fires on every round that merely waited for a free agent, failing every round
- * silently. The server rejects the pair outright when BOTH effective values are
- * stored, but it cannot compare against a column left NULL: NULL means "the
- * orchestrator's configured default applies", and the route does not know that
- * number. Setting one alone is exactly that blind spot, so warn here.
- *
- * Returns the lines rather than printing them so the check is unit-testable.
+ * Returns the lines, unprinted, so the check is unit-testable.
  */
 export declare function unpairedEvalTimeoutWarnings(patch: PatchBody): string[];
 /** Build the reset PATCH body: all knobs → null, or just the flagged ones. */
 export declare function buildClusterReset(opts: Record<string, boolean | undefined>): PatchBody;
 /**
- * Check that `issuer` actually publishes a dashboard-encryption key.
- *
- * Runs after the setting has already been written, so it never throws: a
- * network fault, a non-2xx status and a malformed body all come back as a
- * `reason` the caller prints as a warning. The check is advisory — the CLI may
- * sit in a different network position than the browser that will do the real
- * fetch, so a failure is definitive but a pass is not a guarantee.
+ * Checks that `issuer` publishes a dashboard-encryption key. It runs after the
+ * write, so it never throws: every fault becomes a `reason` warning. Advisory:
+ * the CLI may sit elsewhere on the network than the browser, so a failure is
+ * definitive and a pass is not a guarantee.
  */
 export declare function checkVerifiedIssuerPublishes(issuer: string, fetchImpl?: typeof fetch): Promise<{
     ok: true;

package/dist/cli/commands/cold-store.d.ts

@@ -1,10 +1,7 @@
 /**
- * Cold-store commands for kici-admin (orchestrator side).
- *
- * Every subcommand builds an `OrchestratorColdStore` against the
- * orchestrator Postgres + S3 and delegates to the helpers in
- * `cold-store-impl.ts`. Mirrors
- * `kici-platform-admin cold-store …` on the Platform side.
+ * Cold-store commands for kici-admin, mirroring `kici-platform-admin
+ * cold-store …`. Each builds an `OrchestratorColdStore` and delegates to
+ * `cold-store-impl.ts`.
  *
  *   cold-store archive-now <table>       Run one cycle for a single adapter
  *   cold-store dry-run-archive <table>   Show what would be archived
@@ -17,17 +14,12 @@
  *   cold-store purge-now                 Purge expired chunks (dry-run default)
  *   cold-store peek-chunk <chunkId>      Stream the first N rows of a chunk
  *
- * The CLI talks **directly** to the orchestrator Postgres (and the same
- * S3 bucket the running process uses). It does not go through the
- * orchestrator HTTP admin API — every operation here is a break-glass
- * inspection of bytes that don't belong to the running process.
+ * Talks **directly** to the orchestrator Postgres and the running process's S3
+ * bucket, never the admin API: every operation is a break-glass inspection of
+ * bytes the running process does not own.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
-/**
- * @param _getClient unused — cold-store commands talk to the DB + S3
- *   directly. Retained for signature consistency with other command
- *   group registrations.
- */
+/** @param _getClient unused; kept for a signature consistent with other command groups. */
 export declare function registerColdStoreCommands(program: Command, _getClient: () => AdminApiClient): void;
 //# sourceMappingURL=cold-store.d.ts.map

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

@@ -1,31 +1,20 @@
 /**
- * Config management commands for kici-admin.
- *
- * Provides subcommands for orchestrator configuration management:
- *   config seed, get, set, delete, export, validate, diff, history, rollback, reload, init
- *
- * All commands except `validate --offline` and `init` are thin clients over
- * the admin REST API at /admin/config/*.
- *
- * Provider configuration (GitHub Apps, etc.) is managed via the `sources` table
- * and the `kici-admin source` commands, not through config seed.
+ * `kici-admin config` subcommands. All except `validate --offline` and `init`
+ * are thin clients over the admin REST API at /admin/config/*. Provider
+ * configuration (GitHub Apps, etc.) lives in the `sources` table, managed by
+ * `kici-admin source`, not config seed.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 /**
- * Whether a shared-config path is one a joining orchestrator receives.
- *
- * True for the consumed paths themselves and for anything below them, so
- * `storage.bucket` counts and `storageQuota` does not.
+ * True for a consumed path and anything below it, so `storage.bucket` counts
+ * and `storageQuota` does not.
  */
 export declare function isConsumedSharedConfigPath(path: string): boolean;
 /**
- * Warning text for a `config set` on a path nothing reads back, or null when
- * the path is consumed.
- *
- * The write itself succeeds and is versioned — the operator is told which
- * mechanism actually changes a running orchestrator, so a stored-but-inert
- * value is not mistaken for an applied one.
+ * Null when the path is consumed. The write itself still succeeds and is
+ * versioned; the warning names the mechanism that changes a running
+ * orchestrator, so a stored-but-inert value is not mistaken for an applied one.
  */
 export declare function sharedConfigSetWarning(path: string): string | null;
 export declare function registerConfigCommands(program: Command, getClient: () => AdminApiClient): void;

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

@@ -1,25 +1,13 @@
 /**
- * Context management CLI commands for kici-admin.
+ * `kici-admin context` commands. `context delete` cascades bindings, variables
+ * and overrides; held-run history survives, and a pending held run blocks the
+ * delete (a resolved hold does not).
  *
- *   context create         — upsert a context
- *   context bind           — bind a scope pattern to a context
- *   context set-policy     — update policy fields (branch, repo patterns, reviewers, timers, trust)
- *   context list           — list contexts for an org
- *   context show           — show a single context with variables + bindings
- *   context delete         — delete a context (cascades bindings, variables, overrides; held-run history survives; pending held runs block with a clear error, resolved holds do not)
- *   context create-template — create/update a context template + its seed variables
- *   context source-override list|set|delete — per-source variable overrides (HTTP only)
- *
- * Each command except `source-override` supports two modes, the same split
- * `maintenance.ts` uses:
- *
- *   HTTP mode (default): requires `--url` + `--token`, routes through the
- *   orchestrator admin HTTP API at /api/v1/admin/contexts.
- *
- *   Direct-DB mode: activated when `--database-url` is passed (or
- *   KICI_DATABASE_URL / DATABASE_URL is set). Opens its own pool and runs the
- *   SQL directly via *Direct helpers in @kici-dev/shared, so a setup script can
- *   seed contexts before the orchestrator is up.
+ * Every command except `source-override` has two modes, as in `maintenance.ts`:
+ * HTTP (default; `--url` + `--token`, /api/v1/admin/contexts), and direct-DB
+ * when `--database-url` (or KICI_DATABASE_URL / DATABASE_URL) is set, which runs
+ * the *Direct helpers of @kici-dev/shared so a setup script can seed contexts
+ * before the orchestrator is up.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/dashboard-encryption-key.d.ts

@@ -1,20 +1,15 @@
 /**
- * `kici-admin dashboard-encryption-key` — the orchestrator's X25519
- * dashboard-encryption key: the trust root a browser seals a secret / variable
- * value to under the `encrypted` dashboard-write posture, so the hosted control
- * plane relays only opaque ciphertext.
+ * `kici-admin dashboard-encryption-key show|list|rotate`: the orchestrator's
+ * X25519 key a browser seals secret / variable values to under the `encrypted`
+ * dashboard-write posture, so the hosted control plane relays only ciphertext.
  *
- *   dashboard-encryption-key show     Print the active kid, its public JWK, where
- *                                     the JWKS is published, and the Verified-tier
- *                                     URL (when that tier is opted into).
- *   dashboard-encryption-key list     List every key on record (kid / status / created_at).
- *   dashboard-encryption-key rotate   Mint a new active key; the prior active key
- *                                     is retired from the published JWKS, but its
- *                                     private half stays on record so envelopes
- *                                     already sealed to it still decrypt.
+ * `show` prints the active kid, its public JWK, the JWKS location and the
+ * Verified-tier URL when opted in; `list` prints every key's kid, status and
+ * created_at. `rotate` retires the prior key from the
+ * published JWKS but keeps its private half, so sealed envelopes still decrypt.
  *
- * The PRIVATE half is master-key wrapped (`KICI_SECRET_KEY`) in the orchestrator
- * DB and is never exportable — recovery from a lost key is a routine rotation.
+ * The PRIVATE half is wrapped with `KICI_SECRET_KEY` in the orchestrator DB and
+ * never exportable; a lost key is recovered by rotation.
  */
 import type { Command } from 'commander';
 export declare function registerDashboardEncryptionKeyCommands(program: Command): void;

package/dist/cli/commands/db-backup.d.ts

@@ -21,15 +21,13 @@ export interface BackupManifest {
     hostname: string;
 }
 export interface CreateDbBackupOptions {
-    /** libpq connection URL of the database to dump. */
+    /** libpq connection URL. */
     databaseUrl: string;
-    /** Absolute or relative path the `.dump` archive is written to. */
     outputPath: string;
-    /** Handle used to insert the `backup_runs` row. */
+    /** Inserts the `backup_runs` row. */
     db: Kysely<Database>;
-    /** Pool used to read the server version, key generation, and cluster id. */
+    /** Reads the server version, key generation, and cluster id. */
     pool: import('pg').Pool;
-    /** Timestamp stamped into the manifest. */
     now: Date;
 }
 export interface CreateDbBackupResult {
@@ -49,13 +47,10 @@ export interface PruneIo {
     unlink: (p: string) => Promise<void>;
 }
 /**
- * Keep the newest {@link keep} `.dump` files in {@link dir} and delete the
- * rest, each with its `.manifest.json` sidecar. Newest is decided by
- * modification time, with the filename as a tiebreak because the timestamped
- * names sort chronologically. Returns every path removed.
- *
- * A `keep` of 0 or less disables pruning: retention is opt-in, so a
- * misconfigured value must never empty the directory.
+ * Keep the newest {@link keep} `.dump` files in {@link dir}, deleting the rest
+ * with their `.manifest.json` sidecars; newest by mtime, tiebroken by the
+ * chronologically sorting filename. Returns every path removed. A `keep` of 0
+ * or less disables pruning, so a misconfigured value never empties the directory.
  */
 export declare function pruneBackupDir(dir: string, keep: number, io?: PruneIo): Promise<string[]>;
 export declare function parsePgToolMajor(versionOutput: string): number;
@@ -70,15 +65,10 @@ export declare function readServerAndKeyMeta(pool: import('pg').Pool): Promise<{
     clusterId: string | null;
 }>;
 /**
- * Translate a libpq connection URL into a PG* environment overlay. The
- * connection URL (which embeds the DB password) MUST NOT be passed as a
- * pg_dump/pg_restore argv element: `/proc/<pid>/cmdline` is world-readable, so
- * a URL-in-argv leaks the DB password to every local user for the tool's
- * lifetime. libpq reads PGHOST/PGPORT/PGUSER/PGPASSWORD/PGDATABASE/PGSSLMODE
- * from the environment (`/proc/<pid>/environ`, owner-only 0400) instead — the
- * same credential-off-the-command-line discipline used elsewhere in the repo.
- * Only the components that are actually present are set, so socket / trust
- * connections (no password, no port) are left untouched.
+ * A libpq URL as a PG* environment overlay. The URL embeds the password and
+ * MUST NOT go into pg_dump/pg_restore argv: `/proc/<pid>/cmdline` is
+ * world-readable, while `/proc/<pid>/environ` is owner-only 0400. Only the
+ * components present are set, so socket / trust connections stay untouched.
  */
 export declare function pgEnvFromUrl(url: string): NodeJS.ProcessEnv;
 export declare function runPgDump(url: string, outputPath: string, run?: RunFn): Promise<void>;
@@ -94,20 +84,15 @@ export declare function buildBackupManifest(input: {
     hostname: string;
 }): BackupManifest;
 /**
- * Take one orchestrator database backup: pre-flight the `pg_dump` version,
- * dump to {@link CreateDbBackupOptions.outputPath}, write the sidecar manifest,
- * and record the `backup_runs` row.
- *
- * Prints nothing and never exits the process — every failure surfaces as a
- * thrown Error so the caller decides how to report it. That is what lets both
- * `kici-admin db backup` and the pre-upgrade hook share one implementation.
+ * Check the `pg_dump` version, dump, write the sidecar manifest, and record the
+ * `backup_runs` row. Prints nothing and never exits: failures throw, so
+ * `kici-admin db backup` and the pre-upgrade hook share it.
  */
 export declare function createDbBackup(opts: CreateDbBackupOptions): Promise<CreateDbBackupResult>;
 /**
- * Message to print after a restore about the secret-key requirement. Returns
- * null when the dump carried no encrypted secrets (nothing to warn about),
- * a loud warning when secrets exist but no `KICI_SECRET_KEY` is set on the box,
- * or an informational reminder when a key IS set (it must be the matching one).
+ * The post-restore secret-key note: null when the dump has no encrypted
+ * secrets, a warning when no `KICI_SECRET_KEY` is set, else a reminder that the
+ * set key must be the matching one.
  */
 export declare function restoreKeyWarning(input: {
     secretKeyVersion: number | null;

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

@@ -12,10 +12,9 @@
  *   db reindex                    REINDEX DATABASE CONCURRENTLY (direct DB)
  *   db refresh-collation-version  ALTER DATABASE REFRESH COLLATION VERSION (direct DB)
  *
- * The direct-DB subcommands cannot go through HTTP because the target database
- * may not exist yet or is about to be dropped. They follow the same pattern
- * as `kici-admin peer create-token` — open a pool from KICI_DATABASE_URL /
- * DATABASE_URL / --database-url.
+ * Direct-DB subcommands skip HTTP because the target database may not exist
+ * yet or is about to be dropped; like `kici-admin peer create-token`, they open
+ * a pool from KICI_DATABASE_URL / DATABASE_URL / --database-url.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';