@kici-dev/orchestrator 0.16.0 → 0.18.0

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

@@ -1,26 +1,17 @@
 /**
- * Shared versioned directory upgrade logic for kici-admin upgrade commands.
- *
- * Implements the versioned directory layout:
- * - Extract new version alongside old versions
- * - Update symlink (Unix) or service registration (Windows) atomically
- * - Preserve old versions for rollback
- * - Optional cleanup of old versions
+ * Versioned-directory upgrade shared by the kici-admin upgrade commands: each
+ * release extracts beside the old ones, the symlink (Unix) or service
+ * registration (Windows) switches atomically, and old releases stay for
+ * rollback until `--cleanup`.
  */
 import { type NpmInstallTarget, type ResolvedInstance, type ServiceManager, type ServicePlatform } from '../../service/index.js';
 import type { LaunchSpec, ServiceConfig } from '../../service/types.js';
 import { type MigrationStatusRow } from './upgrade-safety.js';
-/** Component types that can be upgraded. */
 export type UpgradeComponent = 'orchestrator' | 'agent';
-/** Options for the versioned upgrade command. */
 export interface VersionedUpgradeOptions {
     platform?: ServicePlatform;
-    /**
-     * Service name. No default — targeting flows through {@link resolveInstanceTarget}
-     * which consumes `name`, `instanceDir`, or the CWD manifest in priority order.
-     */
+    /** No default: {@link resolveInstanceTarget} picks the target. */
     name?: string;
-    /** Deploy folder of the instance to upgrade. */
     instanceDir?: string;
     from?: string;
     url?: string;
@@ -30,10 +21,7 @@ export interface VersionedUpgradeOptions {
     rollback?: boolean;
     pick?: boolean;
     force?: boolean;
-    /**
-     * Opt-in escape hatch: restart the already-installed package without
-     * self-driving the npm install (the pre-staged / air-gapped path).
-     */
+    /** Restart the already-installed package without the npm install (pre-staged / air-gapped). */
     restartOnly?: boolean;
     /** Skip the pre-upgrade dump. Loud: printed as a banner and echoed at the end. */
     skipBackup?: boolean;
@@ -48,6 +36,11 @@ export interface VersionedUpgradeOptions {
      * the target's recorded head first, through the still-running newer service.
      */
     migrateDown?: boolean;
+    /**
+     * Upgrade even when a bare-metal scaler's `binaryPath` is not executable or is
+     * a version-manager shim. The check still prints what it found.
+     */
+    skipBinaryPathCheck?: boolean;
 }
 /**
  * The orchestrator-only pre-stop steps, injected so the agent upgrade can pass
@@ -66,11 +59,9 @@ export interface UpgradeHooks {
     /** Revert the schema to `head` through the running service. */
     migrateDown?: (head: string) => Promise<void>;
     /**
-     * Take the pre-upgrade dump, returning where it landed.
-     *
-     * `envFilePath` comes from the instance manifest, so the dump is taken
-     * against exactly the database the running service uses rather than whatever
-     * the operator's shell exports.
+     * Take the pre-upgrade dump. `envFilePath` comes from the instance manifest,
+     * so the dump hits the database the running service uses, not whatever the
+     * operator's shell exports.
      */
     backup?: (args: {
         outputPath: string;
@@ -80,38 +71,25 @@ export interface UpgradeHooks {
         byteSize: number;
     }>;
 }
-/**
- * Resolved upgrade target: the manifest-backed ServiceConfig the upgrade
- * flow operates on, the manifest's installBase (NOT re-derived from name),
- * and the underlying resolved instance for downstream writes.
- */
+/** The manifest-backed target; `installBase` is the manifest's, never re-derived from the name. */
 export interface UpgradeTarget {
     config: ServiceConfig;
     installBase: string;
     resolvedInstance: ResolvedInstance;
-    /** The driver that manages this install — built for {@link UpgradeTarget.platform}. */
+    /** Built for {@link UpgradeTarget.platform}. */
     manager: ServiceManager;
     /**
-     * The install's own platform: `platformOverride ?? manifest.platform`. Every
-     * downstream question the upgrade asks — the root check, the launcher name,
-     * whether the current version reads a symlink or a version file — is about
-     * the layout on disk, so it is answered from the install, not the host.
+     * `platformOverride ?? manifest.platform`. Every downstream question (root
+     * check, launcher name, symlink vs version file) is about the layout on disk,
+     * so it is answered from the install, not the host.
      */
     platform: ServicePlatform;
 }
 /**
- * Resolve the upgrade target via the folder-anchored model and build the
- * ServiceConfig + installBase the rest of the upgrade flow needs.
- *
- * Priority chain (delegated to {@link resolveInstanceTarget}):
- *   1. `opts.instanceDir` — read manifest at that path.
- *   2. `opts.name`        — match against listInstances() output.
- *   3. CWD manifest       — read `./.kici-<component>.json`.
- *   4. otherwise          — refuse with a candidate-list error.
- *
- * The returned `installBase` comes from the manifest, NEVER re-derived from
- * the service name. Instances installed with a non-default base must
- * continue to resolve to that base on upgrade.
+ * Resolve the upgrade target through {@link resolveInstanceTarget}: `instanceDir`,
+ * then `name`, then the CWD `./.kici-<component>.json`, else refuse with a
+ * candidate list. `installBase` comes from the manifest, never re-derived from
+ * the name, so an install with a non-default base keeps it on upgrade.
  */
 export declare function resolveUpgradeTarget(args: {
     component: UpgradeComponent;
@@ -119,25 +97,18 @@ export declare function resolveUpgradeTarget(args: {
         instanceDir?: string;
         name?: string;
     };
-    /** The `--platform` flag. When set it forces the driver, as it always has. */
+    /** The `--platform` flag; forces the driver when set. */
     platformOverride?: ServicePlatform;
     isUserLevel: boolean;
     kiciRoot: string;
-    /** Driver factory. Defaults to the service barrel's createServiceManager. */
+    /** Defaults to the service barrel's createServiceManager. */
     createManager?: (platform: ServicePlatform) => Promise<ServiceManager>;
 }): Promise<UpgradeTarget>;
 /**
- * Install base for a KiCI component instance.
- *
- * Name-scoped so that two instances of the same component (e.g. an org's
- * production orchestrator and a test orchestrator on the same host) own
- * independent versioned trees and symlinks. Per-platform bases:
- *   - systemd / compose: /opt/kici/<name>/
- *   - launchd:           /usr/local/kici/<name>/
- *   - windows:           C:\Program Files\KiCI\<name>\
+ * Name-scoped install base, so two instances of one component on a host own
+ * independent versioned trees and symlinks.
  */
 export declare function getInstallBase(platform: ServicePlatform, name: string): string;
-/** A choice row for the `--pick` interactive select. */
 export interface PickChoice {
     value: string;
     name: string;
@@ -145,23 +116,16 @@ export interface PickChoice {
     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.
+ * `--pick` choices, newest-first (lexicographic, like the rest of the
+ * versioned-directory handling). The active version is disabled: 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.
- */
+/** Every installed version except the active one; empty means "nothing to pick". */
 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.
+ * `--pick` activates an installed version, so it excludes `--from`, `--url`,
+ * `--version`, `--rollback` and `--cleanup`. Returns an error message, or null.
  */
 export declare function checkPickFlagConflicts(opts: {
     pick?: boolean;
@@ -172,17 +136,13 @@ export declare function checkPickFlagConflicts(opts: {
     cleanup?: boolean;
 }): string | null;
 /**
- * Stop the service, register it again on Windows, then start it: the restart
- * every npm-source upgrade ends with.
- *
- * `npm install -g` replaces the package in place, so the launch command the
- * service runs (`spec`, read back from its registration) stays valid. On
- * Windows the registration around that command (the service wrapper's
- * arguments, the description, the recovery settings) is whatever the CLI that
- * installed it wrote, so `install` writes the current one, as the archive
- * upgrade does. A launch command that names a file that does not exist was
- * read back wrong, so it is not registered: the service restarts as it was,
- * with a warning. systemd and launchd keep their unit as it is.
+ * The restart every npm-source upgrade ends with: stop, re-register on
+ * Windows, start. `npm install -g` replaces the package in place, so `spec`
+ * stays valid; on Windows the registration around it (wrapper arguments,
+ * description, recovery settings) is whatever the installing CLI wrote, so
+ * `install` rewrites it. A launch command naming a missing file was read back
+ * wrong and is not registered: the service restarts as it was, with a warning.
+ * systemd and launchd keep their unit.
  */
 export declare function restartOntoInstalledPackage(args: {
     manager: ServiceManager;
@@ -204,11 +164,10 @@ export declare function extractRelease(args: {
     config: ServiceConfig;
 }): string;
 /**
- * Put the release in `archivePath` at `versionedDirPath`. The release is
- * extracted and checked first ({@link extractRelease}); only then is a folder
- * already at `versionedDirPath` removed, which the caller allows with
- * `--force`, and the release copied in. A refused release leaves the install
- * base as it was.
+ * Put the release at `versionedDirPath`. It is extracted and checked first
+ * ({@link extractRelease}); only then is an existing folder there removed
+ * (the caller allows that with `--force`). A refused release leaves the
+ * install base as it was.
  */
 export declare function installRelease(args: {
     archivePath: string;
@@ -221,31 +180,15 @@ export declare function installRelease(args: {
     config: ServiceConfig;
 }): void;
 /**
- * Perform a versioned directory upgrade for a KiCI component.
- *
- * Flow:
- * 1. Parse upgrade source (--from archive or --url)
- * 2. Determine install base by platform
- * 3. Extract new versioned directory
- * 4. Stop service
- * 5. Update symlink (Unix) or service registration (Windows)
- * 6. Start service
- */
-/**
- * Resolve the target version for an npm-source upgrade (no --from/--url).
- *
- * The npm-source flow assumes the operator already ran
- * `npm install -g @kici-dev/<pkg>@<version>`, which overwrites the global
- * package in place. The running `kici-admin` binary is therefore the new
- * version, and `running` is its self-reported version. We default the target
- * to it, or validate an explicitly-passed --version matches — a mismatch means
- * the npm install did not actually update the global binary.
+ * Target version of a restart-only npm-source upgrade. The operator already
+ * ran `npm install -g`, so the running `kici-admin` is the new version: the
+ * target defaults to `running`, and a different `--version` means the install
+ * did not update the global binary.
  */
 export declare function resolveNpmSourceVersion(opts: {
     requested: string | undefined;
     running: string;
 }): string;
-/** Verdict from {@link verifyNpmSourceLaunch}. */
 export type NpmSourceLaunchVerdict = {
     ok: true;
     version: string;
@@ -255,11 +198,10 @@ export type NpmSourceLaunchVerdict = {
     reason: string;
 };
 /**
- * Decide whether an npm-source upgrade may proceed, given the version the
- * invoking CLI is (`invoked`) and the version the installed unit will actually
- * launch (`launched`, or null when unresolvable — e.g. an opaque --binary
- * install). On success `manifestVersion` is the value to persist (null = leave
- * the manifest's kiciVersion unchanged because we couldn't verify it).
+ * Whether an npm-source upgrade may proceed: the invoking CLI's version must
+ * match what the unit will launch (`launched`, null when unresolvable such as
+ * an opaque --binary install). A null `manifestVersion` leaves the manifest's
+ * kiciVersion unchanged because it was not verified.
  */
 export declare function verifyNpmSourceLaunch(opts: {
     component: UpgradeComponent;
@@ -268,12 +210,6 @@ export declare function verifyNpmSourceLaunch(opts: {
     launchedPath: string | null;
     force: boolean;
 }): NpmSourceLaunchVerdict;
-/**
- * An npm-source upgrade proceeds one of three ways: restart the already-installed
- * package (`restart-only`, carrying a {@link NpmSourceLaunchVerdict}), self-drive
- * the install of a resolved target under the unit's own runtime (`self-drive`),
- * or refuse with an operator-facing message (`error`).
- */
 export type NpmSourceUpgradeAction = {
     kind: 'restart-only';
     verdict: NpmSourceLaunchVerdict;
@@ -287,10 +223,9 @@ export type NpmSourceUpgradeAction = {
 };
 /**
  * Decide how an npm-source upgrade proceeds. `restart-only` re-verifies and
- * restarts the already-installed package (the pre-staged / air-gapped path).
- * The default self-drives: it resolves the global package + pinned node from
- * the unit's launch spec so the CLI can install the target itself. Returns an
- * `error` action (not a throw) for the two operator-facing refusals.
+ * restarts the installed package; the default self-drives, resolving the
+ * global package and pinned node from the unit's launch spec. Operator-facing
+ * refusals return an `error` action rather than throwing.
  */
 export declare function planNpmSourceUpgrade(opts: {
     component: UpgradeComponent;
@@ -301,7 +236,7 @@ export declare function planNpmSourceUpgrade(opts: {
     force: boolean;
     windows: boolean;
 }): NpmSourceUpgradeAction;
-/** Injected process runner seam for the npm calls of an npm-source upgrade. */
+/** Process runner for the npm calls; tests inject it. */
 export type SpawnRunner = (cmd: string, args: string[], opts?: {
     env?: NodeJS.ProcessEnv;
 }) => {
@@ -311,18 +246,16 @@ export type SpawnRunner = (cmd: string, args: string[], opts?: {
 };
 /**
  * The cmd.exe command line for npm on Windows. npm is a batch file there, which
- * Node.js starts only through a shell, and Node.js joins the parts of a shell
- * command with spaces and quotes none of them. The standard Node.js install is
- * under `C:\Program Files`, so the npm path is quoted here. An argument with a
- * character outside those of a package name, a version or a flag is refused
- * rather than handed to cmd.exe.
+ * Node.js starts only through a shell, joining the parts with spaces and
+ * quoting none of them; the npm path is quoted here because the standard Node.js
+ * install is under `C:\Program Files`. An argument with a character outside those of a
+ * package name, a version or a flag is refused rather than handed to cmd.exe.
  */
 export declare function windowsShellCommand(cmd: string, args: string[]): string;
 /**
- * Whether `version` of the KiCI packages reads KICI_ENV_FILE, asked of the
- * registry the unit's npm installs from. A release that reads it publishes the
- * env-file loader in `@kici-dev/shared`, which every KiCI package of the same
- * version depends on.
+ * Whether `version` reads KICI_ENV_FILE, asked of the unit's npm registry. Such
+ * a release exports the env-file loader from `@kici-dev/shared`, which every
+ * KiCI package of that version depends on.
  */
 export declare function npmReleaseReadsEnvFile(target: NpmInstallTarget, version: string, run?: SpawnRunner): {
     ok: true;
@@ -332,25 +265,25 @@ export declare function npmReleaseReadsEnvFile(target: NpmInstallTarget, version
     error: string;
 };
 /**
- * Install `<owningPackage>@<version>` globally under the unit's own pinned node,
- * so it lands in exactly the global prefix the unit's ExecStart resolves from.
- *
- * npm derives its global prefix from the node that *runs* npm-cli.js, not from
- * the location of the npm script — and the unit's `<pinned>/bin/npm` is a
- * `#!/usr/bin/env node` shebang (or a version-manager bash wrapper invoking a
- * bare `node`), both of which resolve `node` off PATH. So invoking that npm
- * bare would inherit whatever node the shell has active — exactly the
- * version-manager (mise/nvm/asdf) drift this upgrade exists to fix. We prepend
- * the pinned node's bin dir to PATH so npm always runs under the unit's node
- * and computes the unit's prefix, regardless of the caller's active node. The
- * `run` seam is injected in tests.
+ * Install `<owningPackage>@<version>` globally under the unit's pinned node, so
+ * it lands in the prefix the unit's ExecStart resolves from. npm derives its
+ * global prefix from the node that runs npm-cli.js, and the unit's
+ * `<pinned>/bin/npm` (an `env node` shebang or a version-manager wrapper)
+ * resolves `node` off PATH; run bare it would inherit the shell's active node,
+ * the mise/nvm/asdf drift this upgrade fixes. Hence the pinned bin dir goes
+ * first on PATH ({@link npmEnv}).
  */
 export declare function installGlobalPackage(target: NpmInstallTarget, version: string, run?: SpawnRunner): {
     ok: boolean;
     stderr: string;
 };
+/**
+ * Run `kici-admin <component> upgrade`: `--pick`, `--rollback` and `--cleanup`
+ * act on installed versions, no `--from`/`--url` is an npm-source upgrade, and
+ * an archive installs a new versioned directory, then stops the service,
+ * switches the symlink (Unix) or registration (Windows), and starts it.
+ */
 export declare function performVersionedUpgrade(component: UpgradeComponent, opts: VersionedUpgradeOptions, hooks?: UpgradeHooks): Promise<void>;
-/** The inputs of {@link restartOnlyUpgrade}. */
 export interface RestartOnlyArgs {
     component: UpgradeComponent;
     config: ServiceConfig;
@@ -362,34 +295,24 @@ export interface RestartOnlyArgs {
     /** The launch command read from the registration before the upgrade. */
     spec: LaunchSpec | null;
 }
-/** The inputs of {@link performSelfDrivingInstall}. */
 export interface SelfDriveArgs extends Omit<RestartOnlyArgs, 'verdict'> {
     action: {
         target: NpmInstallTarget;
         version: string;
     };
-    /** Runs npm; tests inject it. */
     run?: SpawnRunner;
 }
 /**
- * Restart-only path: the operator pre-installed `@kici-dev/<pkg>@<version>` (or
- * kici-admin) themselves. Verify the unit will launch the invoking CLI's version,
- * restart onto it, and persist the manifest version.
+ * Restart-only path: the operator pre-installed the package. Verify the unit
+ * launches the invoking CLI's version, restart onto it, persist the version.
  */
 export declare function restartOnlyUpgrade(args: RestartOnlyArgs): Promise<void>;
-/**
- * Self-driving path: install the resolved global package under the unit's own
- * pinned node/npm, restart, and verify the unit now launches the requested
- * version.
- */
+/** Self-driving path: install under the unit's pinned node/npm, restart, verify the version. */
 export declare function performSelfDrivingInstall(args: SelfDriveArgs): Promise<void>;
 /**
- * Stop the service, switch the active version pointer to an already-installed
- * versioned directory (atomic symlink on Unix; re-registration + 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).
+ * Switch to an installed version for `--rollback` and `--pick`: stop, move the
+ * pointer (atomic symlink on Unix; re-registration and version file on
+ * Windows), start, and persist `kiciVersion` into the manifest.
  */
 export declare function switchToInstalledVersion(args: {
     component: UpgradeComponent;
@@ -399,9 +322,8 @@ export declare function switchToInstalledVersion(args: {
     manager: ServiceManager;
     resolvedInstance: ResolvedInstance;
     targetVersion: string;
-    /** Orchestrator-only pre-stop capabilities. Omitted by the agent upgrade. */
+    /** Omitted by the agent upgrade. */
     hooks?: UpgradeHooks;
-    /** Revert the schema to the target's recorded head before switching. */
     migrateDown?: boolean;
     /** Skip the confirmation the unknown-head warning falls through to. */
     yes?: boolean;

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

@@ -1,7 +1,6 @@
 import type { Command } from 'commander';
 import { OrchestratorSigningKeyRepo } from '../../db/repos/signing-keys-repo.js';
 import type { AdminApiClient } from '../api-client.js';
-/** Outcome of {@link generateInitialSigningKey}. */
 export type InitialSigningKeyOutcome = {
     created: true;
     kid: string;
@@ -10,15 +9,11 @@ export type InitialSigningKeyOutcome = {
     activeKid: string;
 };
 /**
- * Generate the initial db-custody key and activate it only while no key is
- * active. Orchestrator nodes create the key on their own, so a node may win the
- * race after the command's check; the node's key then stays active, because the
- * nodes already sign with it, and its kid is returned.
+ * Generate and activate the initial db-custody key only while none is active.
+ * A node may create its own key after the command's check; that key stays
+ * active (nodes already sign with it) and its kid is returned.
  */
 export declare function generateInitialSigningKey(repo: OrchestratorSigningKeyRepo, secretKey: string): Promise<InitialSigningKeyOutcome>;
-/**
- * Register `kici-admin signing-key`. `tryGetClient` returns null when no admin
- * token is configured, so `list` can name both of its data sources.
- */
+/** `tryGetClient` returns null with no admin token, so `list` can name both its sources. */
 export declare function registerSigningKeyCommands(program: Command, tryGetClient: () => AdminApiClient | null): void;
 //# sourceMappingURL=signing-key.d.ts.map

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

@@ -1,14 +1,12 @@
 /**
- * `kici-admin source add github --manifest` — the one-click GitHub App setup
- * flow. Drives GitHub's App Manifest flow end-to-end: builds a pre-configured
- * manifest (KiCI's exact permissions/events/webhook URL), hands it to GitHub via
- * an auto-submitting form, catches the returned short-lived setup code over a
- * localhost loopback (or copy-paste in --no-browser mode), exchanges it for the
- * App's id + private key + webhook secret, then reuses the existing source
- * storage + Platform-registration path.
+ * `kici-admin source add github --manifest`: GitHub's App Manifest flow end to
+ * end. The pre-configured manifest goes to GitHub through an auto-submitting
+ * form; the short-lived setup code comes back over a localhost loopback (or is
+ * pasted with --no-browser) and is exchanged for the App's id, private key and
+ * webhook secret, which take the normal source storage and registration path.
  *
- * The private-key-bearing conversion happens entirely here on the orchestrator
- * host — it never transits the Platform (sovereignty invariant).
+ * The private-key-bearing conversion runs only on the orchestrator host and
+ * never transits the Platform (sovereignty invariant).
  */
 import type { AdminApiClient } from '../api-client.js';
 import { waitForInstallation, verifyRepoAccess, type GithubAppCredentials } from '../../providers/github/manifest.js';
@@ -18,11 +16,10 @@ export interface ManifestSetupOptions {
     noBrowser?: boolean;
     githubOrg?: string;
     /**
-     * Self-hosted webhook URL override. When set, it is baked verbatim into the
-     * 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.
+     * Self-hosted webhook URL override, written verbatim into the manifest's
+     * `hook_attributes.url` instead of the URL the orchestrator resolves for its
+     * mode, so the flow works 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

@@ -1,29 +1,10 @@
 /**
- * Source management commands for kici-admin.
- *
- * Provides subcommands for webhook source CRUD:
- *   source add github         Add a new GitHub App source
- *   source add generic        Add a new generic webhook source
- *   source list               List all configured sources
- *   source get <id>           Get details of a specific generic source
- *   source update <routingKey> Update a GitHub source
- *   source update-generic <id> Update a generic source
- *   source remove <routingKey> Remove a source (GitHub or generic with --generic flag)
- *   source redeliver <routingKey> Replay a window of GitHub webhook deliveries
- *   source enable <id>        Enable a generic source
- *   source disable <id>       Disable a generic source
- *
- * Supports multiple secret input modes:
- *   --private-key <value>      Direct value
- *   --private-key @/path/file  Read from file (@ prefix)
- *   --from-env <VAR_NAME>      Read from environment variable
- *   --stdin                    Read from stdin
+ * `kici-admin source` commands: webhook source CRUD. A secret flag takes a
+ * literal value, `@/path/file`, `--from-env <VAR_NAME>` or `--stdin`.
  */
 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. */
+/** Satisfied by both the HTTP `GenericSourceResponse` and the DB `GenericWebhookSource`. */
 interface ListableGenericRow {
     id: string;
     name: string;
@@ -31,10 +12,8 @@ interface ListableGenericRow {
     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. */
+/** Render `source list` text for both transports. Generic sources list only with
+ *  `--org` (`hasOrg`); a direct DB read (`opts.directDb`) has no ingress URLs. */
 export declare function renderSourceListText(githubSources: Array<{
     routingKey: string;
     name: string;
@@ -45,12 +24,8 @@ export declare function renderSourceListText(githubSources: Array<{
 }): 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";
-/**
- * Resolve the `--webhook-secret` value. A literal value passes through; `-`
- * reads the secret from stdin; absent stays undefined. The private key can also
- * be piped via `--stdin`, and stdin can only be consumed once — so `-` here
- * while the private key also reads stdin is a hard error.
- */
+/** `-` reads stdin. Stdin is consumable once, so `-` while the private key also
+ *  reads `--stdin` is a hard error. */
 export declare function resolveWebhookSecret(opts: {
     value?: string;
     privateKeyFromStdin: boolean;

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

@@ -1,23 +1,12 @@
-/**
- * Token management commands for kici-admin.
- *
- * Provides CRUD operations for admin API tokens:
- *   token create, list, revoke
- */
+/** `kici-admin token create | list | revoke` for admin API tokens. */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 /**
- * Parse a `--expires` value into an absolute expiry Date.
- *
- * Accepts either a duration shorthand relative to now (`<N>d` days,
- * `<N>h` hours, `<N>m` minutes — e.g. `30d`, `12h`, `45m`) or an
- * absolute ISO-8601 datetime (e.g. `2026-12-31T00:00:00Z`). Throws on any
- * other input so a typo never silently creates a non-expiring token.
+ * `--expires` as an absolute Date: `<N>d`, `<N>h` or `<N>m` from now, or an
+ * ISO-8601 datetime. Anything else throws, so a typo never creates a
+ * non-expiring token.
  */
 export declare function parseExpiresAt(input: string, now?: Date): Date;
-/**
- * Format tokens as a table.
- */
 export declare function formatTokenTable(tokens: any[]): string;
 export declare function registerTokenCommands(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=token.d.ts.map