@consiliency/agent-board-cli 1.27.1 → 1.29.0

package/dist/setup.d.ts

@@ -1,9 +1,11 @@
 import type { Command } from "commander";
-import { type DeviceAuthorizationPrompt, type EnrollmentIntent, type EnrollmentOutcome } from "@consiliency/agent-board-client";
+import { type DeviceAuthorizationPrompt, type EnrollmentIntent, type EnrollmentOutcome, type IdentityHarness, type ListHarnessProcessesOptions, type ParsedInviteInput } from "@consiliency/agent-board-client";
+import type { SetupAllOptions } from "./setup_all.js";
 import { type BakedAssets } from "./assets.js";
 import { type DoctorOptions, type DoctorReport } from "./doctor.js";
-import { type DepsOutcome, type KeyStorageContext, type KeyStorageSelection } from "./setup_storage.js";
-import { type ChildRunner, type WriterContext } from "./setup_writers.js";
+import { type IdentityDeployment } from "./identity_writer.js";
+import { type DepsOutcome, type KeyStorageContext, type KeyStorageSelection, type PreparedKeyStorage } from "./setup_storage.js";
+import { type ChildRunner, type SetupScope, type WriterContext } from "./setup_writers.js";
 export declare const SETUP_STEPS: readonly ["preflight", "deps", "key", "enroll", "identity", "board", "harness", "doctor"];
 export type SetupStepName = (typeof SETUP_STEPS)[number];
 export type SetupStatus = "done" | "already" | "skipped" | "failed" | "undetermined";
@@ -17,11 +19,24 @@ export interface SetupReport {
     exit: 0 | 1 | 2;
     /** Human text: per-step fixes and the next steps. Never part of `--json`'s stdout. */
     notes: string[];
+    /**
+     * IF-0-ONBOARD-3: this harness's processes that started before setup installed or upgraded its
+     * registration, found by executable. Empty when the harness step installed nothing.
+     */
+    staleSessions: StaleSession[];
+}
+export interface StaleSession {
+    pid: number;
+    /** ISO time the process started. */
+    startedAt: string;
+    cwd: string | null;
 }
 export interface SetupOptions {
     harness: string;
     slug?: string;
     invite?: boolean;
+    /** IF-0-ONBOARD-2: a file holding the invite (a bare code, or the whole invite message). */
+    inviteFile?: string;
     allowUnsealedKey?: boolean;
     agentSocket?: string;
     scope?: string;
@@ -61,7 +76,10 @@ export interface SetupDeps {
     sudoPath?: string;
     hostname?: () => string;
     bakedAssets?: () => BakedAssets;
+    /** A whole selector, scan included; its answer is final (the pre-ONBOARD seam). */
     selectKeyStorage?: (ctx: KeyStorageContext) => Promise<KeyStorageSelection>;
+    /** The key step's preparation (no scan); default `prepareKeyStorage`. */
+    prepareKeyStorage?: (ctx: KeyStorageContext) => Promise<PreparedKeyStorage>;
     /** Seams passed through to the storage selector (probeKeychain, run, keyslotDir, …). */
     storage?: Partial<KeyStorageContext>;
     enroll?: SetupEnroller;
@@ -71,6 +89,8 @@ export interface SetupDeps {
     doctorOptions?: Partial<DoctorOptions>;
     /** Seams passed through to the harness writer (fs, claudeManagedDir). */
     writer?: Partial<Pick<WriterContext, "fs" | "claudeManagedDir">>;
+    /** Seams passed through to the stale-session listing (`/proc` or `ps` readers, uid, platform). */
+    processes?: Omit<ListHarnessProcessesOptions, "startedBefore">;
 }
 export declare const DEFAULT_SUDO = "/usr/bin/sudo";
 export declare const SECRET_SERVICE_NAME = "org.freedesktop.secrets";
@@ -90,7 +110,22 @@ export declare const KEYCHAIN_INSTALL_ARGV: ReadonlyArray<{
 }>;
 /** `<short hostname>-<harness>`, lowercased to `[a-z0-9-]`. */
 export declare function defaultSlug(host: string, harness: string): string;
-export declare function pendingMarkerPath(harness: string, env: NodeJS.ProcessEnv): string;
+type IdentityState = {
+    kind: "present";
+    values: Record<string, string>;
+} | {
+    kind: "absent";
+} | {
+    kind: "unreadable";
+    reason: string;
+};
+declare class Run {
+    readonly steps: SetupStep[];
+    readonly notes: string[];
+    readonly staleSessions: StaleSession[];
+    record(step: SetupStep["step"], status: SetupStatus, reason: string, fix?: string): SetupStep;
+    report(): SetupReport;
+}
 interface DepsContext {
     env: NodeJS.ProcessEnv;
     platform: NodeJS.Platform;
@@ -105,6 +140,74 @@ interface DepsContext {
 export declare function depsStep(ctx: DepsContext): Promise<DepsOutcome & {
     fix?: string;
 }>;
+/**
+ * IF-0-ONBOARD-2: the invite, read ONCE and parsed by the shared parser. `--invite-file` and a
+ * piped stdin may hold the whole invite message; a terminal takes one hidden line that must be a
+ * bare code. The code never reaches argv, a log or any message: a refusal names only its reason.
+ */
+export declare function readSetupInvite(input: {
+    invite?: boolean;
+    inviteFile?: string;
+}, deps: Pick<SetupDeps, "interactive" | "prompt" | "readStdin">): Promise<{
+    invite: ParsedInviteInput | null;
+} | {
+    reason: string;
+    fix: string;
+}>;
+/** IF-0-ONBOARD-2 "Board": reported, never checked (setup has no target board). Never the code. */
+export declare function inviteBoardNote(invite: ParsedInviteInput): string;
+/**
+ * A pair past preflight, deps and its key PREPARATION (ONBOARD SL-4): what the rest of setup
+ * needs, plus the prepared storage, which is scanned before `finishSetupPair` may use it.
+ * `prepared` is null when the identity already exists (no key is chosen).
+ */
+export interface SetupPair {
+    readonly harness: IdentityHarness;
+    readonly slug: string;
+    readonly prepared: PreparedKeyStorage | null;
+    /** @internal */
+    readonly state: PairState;
+}
+interface PairState {
+    out: Run;
+    options: SetupOptions;
+    deps: SetupDeps;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    scope: SetupScope;
+    assets: BakedAssets;
+    identity: IdentityState;
+    deployment: IdentityDeployment | null;
+    invite: ParsedInviteInput | null;
+    identityPath: string;
+    markerPath: string;
+}
+export type SetupPairStart = {
+    kind: "stopped";
+    report: SetupReport;
+} | {
+    kind: "started";
+    pair: SetupPair;
+};
+/** The storage context the key step's scan reads (env, runner, budgets, notices). */
+export declare function setupStorageContext(deps: SetupDeps): Pick<KeyStorageContext, "env" | "run" | "statusBudgets" | "notify">;
+/**
+ * Preflight, deps and the key PREPARATION for one harness. `preset.invite` is an invite the caller
+ * already read and parsed (`setup --all` reads it once for every pair); without it, the invite is
+ * read here.
+ */
+export declare function startSetupPair(options: SetupOptions, deps?: SetupDeps, preset?: {
+    invite: ParsedInviteInput | null;
+}): Promise<SetupPairStart>;
+/**
+ * The rest of one pair, from its FINAL key storage (`finalizeKeyStorage`'s answer for this pair;
+ * null for a pair whose identity exists): enroll, identity, board, harness, doctor.
+ */
+export declare function finishSetupPair(pair: SetupPair, selection: KeyStorageSelection | null): Promise<SetupReport>;
+/**
+ * One harness: start, the key step's one scan (prepare → measure → finalize, as `setup --all` does
+ * over every pair), then the rest.
+ */
 export declare function runSetup(options: SetupOptions, deps?: SetupDeps): Promise<SetupReport>;
 export type SetupRunner = (options: SetupOptions) => Promise<SetupReport>;
 interface SetupIo {
@@ -112,5 +215,9 @@ interface SetupIo {
     writeStderr(message: string): void;
 }
 export declare function formatSetupReport(report: SetupReport): string;
-export declare function addSetupCommand(program: Command, io: SetupIo, setup: SetupRunner): void;
+/** `setup --all`: runs, prints (the table, or `--json` on stdout with notes on stderr), returns the exit. */
+export type SetupAllCommand = (options: SetupAllOptions, output: {
+    json: boolean;
+}) => Promise<0 | 1 | 2>;
+export declare function addSetupCommand(program: Command, io: SetupIo, setup: SetupRunner, setupAll?: SetupAllCommand): void;
 export {};