@consiliency/agent-board-cli 1.24.0 → 1.26.0

package/dist/identity_writer.js

@@ -11,7 +11,7 @@ import { createHash } from "node:crypto";
 import { constants as FS } from "node:fs";
 import * as fs from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { CredentialResolutionError, ENV_ALIAS_FAMILIES, identityConfigRoot, identityFilePath, serializeIdentityFile, walkTrustedDirectory, } from "@consiliency/agent-board-client";
+import { CredentialResolutionError, DEPLOYMENT_ENV_ALIASES, describeMissingDeploymentFields, identityConfigRoot, resolveDeploymentField, identityFilePath, serializeIdentityFile, walkTrustedDirectory, } from "@consiliency/agent-board-client";
 async function syncDirectory(path) {
     const handle = await fs.open(path, "r");
     try {
@@ -50,24 +50,17 @@ export async function writeOwnerOnlyFileAtomic(path, content, options = {}) {
     }
     await sync(dirname(path));
 }
-/** The identity-name alias family containing `canonical`, from the client's one declaration. */
-function identityFamily(canonical) {
-    const family = ENV_ALIAS_FAMILIES.find((members) => members.includes(canonical));
-    if (!family)
-        throw new Error(`identity_writer: no alias family declares ${canonical}`);
-    return family;
-}
 /**
- * Where each deployment value is read, in precedence order: the enrollment's own names first
- * (so the file records the deployment the enrollment used — pinned against the client's
- * enrollment resolvers in the test), then the identity names. The generic Supabase names the
- * enrollment also accepts for the publishable key are NOT read: a generic key never fills an
- * identity field, here or in the loader.
+ * Where each deployment value is read, in precedence order: the client's one alias table
+ * (`DEPLOYMENT_ENV_ALIASES`), which puts the enrollment's own names first (so the file records
+ * the deployment the enrollment used) and then the identity names. The enrollment resolvers read
+ * the same table, so the two cannot disagree. The generic Supabase names are in no list: a
+ * generic key never fills an identity field, here or in the loader.
  */
 export const DEPLOYMENT_ENV_NAMES = Object.freeze({
-    boardUrl: Object.freeze(["MESSAGE_BOARD_ENROLL_BOARD_URL", ...identityFamily("AGENT_BOARD_URL")]),
-    sessionUrl: Object.freeze(["MESSAGE_BOARD_ENROLL_SESSION_URL", "AGENT_BOARD_ENROLL_SESSION_URL", ...identityFamily("AGENT_BOARD_SESSION_URL")]),
-    publishableKey: Object.freeze(["MESSAGE_BOARD_ENROLL_PUBLISHABLE_KEY", "AGENT_BOARD_ENROLL_PUBLISHABLE_KEY", ...identityFamily("AGENT_BOARD_PUBLISHABLE_KEY")]),
+    boardUrl: DEPLOYMENT_ENV_ALIASES.boardUrl,
+    sessionUrl: DEPLOYMENT_ENV_ALIASES.sessionUrl,
+    publishableKey: DEPLOYMENT_ENV_ALIASES.publishableKey,
 });
 const DEPLOYMENT_FILE_KEYS = {
     boardUrl: "AGENT_BOARD_URL",
@@ -89,27 +82,22 @@ const PREFLIGHT_STAND_INS = {
     AGENT_BOARD_SIGNING_PUBLIC_KEY_FINGERPRINT: `sha256:${"A".repeat(43)}`,
     MESSAGE_BOARD_AGENT_AUTH_MODE: "keystore_session",
 };
-function firstPresent(env, names) {
-    for (const name of names) {
-        const value = env[name];
-        if (value !== undefined && value.trim() !== "")
-            return { name, value: value.trim() };
-    }
-    return undefined;
-}
 /**
- * The deployment half of an identity, read and shape-checked before enrollment commits.
- * Absent → `identity_incomplete`; not the non-secret shape its key requires →
+ * The deployment half of an identity, read and shape-checked before enrollment commits. Each
+ * value is the shipped default, or env under the board group's all-or-nothing rule (the
+ * client's `resolveDeploymentField`). Absent from an env-set group → `identity_incomplete`,
+ * naming the variable that switched the group off; not the non-secret shape its key requires →
  * `identity_secret_value`. Both name the variable, never the value.
  */
 export function resolveIdentityDeployment(env) {
     const deployment = {};
     for (const field of Object.keys(DEPLOYMENT_ENV_NAMES)) {
-        const names = DEPLOYMENT_ENV_NAMES[field];
-        const found = firstPresent(env, names);
-        if (!found) {
-            throw new CredentialResolutionError("identity_incomplete", `cannot write an identity file: no ${DEPLOYMENT_FILE_KEYS[field]} for it (set one of: ${names.join(", ")})`);
+        const resolved = resolveDeploymentField(env, field);
+        if (resolved.value === undefined) {
+            throw new CredentialResolutionError("identity_incomplete", `cannot write an identity file: no ${DEPLOYMENT_FILE_KEYS[field]} for it ${describeMissingDeploymentFields([field], resolved.switchedBy)}`);
         }
+        // A default is named by the file key it fills: it came from no variable.
+        const found = { name: resolved.name ?? `the default ${DEPLOYMENT_FILE_KEYS[field]}`, value: resolved.value };
         try {
             serializeIdentityFile({ ...PREFLIGHT_STAND_INS, [DEPLOYMENT_FILE_KEYS[field]]: found.value });
         }

package/dist/setup.d.ts

@@ -0,0 +1,116 @@
+import type { Command } from "commander";
+import { type DeviceAuthorizationPrompt, type EnrollmentIntent, type EnrollmentOutcome } from "@consiliency/agent-board-client";
+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";
+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";
+export interface SetupStep {
+    step: SetupStepName | "clear_pending";
+    status: SetupStatus;
+    reason: string;
+}
+export interface SetupReport {
+    steps: SetupStep[];
+    exit: 0 | 1 | 2;
+    /** Human text: per-step fixes and the next steps. Never part of `--json`'s stdout. */
+    notes: string[];
+}
+export interface SetupOptions {
+    harness: string;
+    slug?: string;
+    invite?: boolean;
+    allowUnsealedKey?: boolean;
+    agentSocket?: string;
+    scope?: string;
+    installDeps?: boolean;
+    clearPending?: boolean;
+    /** Default true; `--no-follow-symlinks` refuses to write through a symlinked config. */
+    followSymlinks?: boolean;
+}
+/** The enrollment setup runs: the device flow, the key reference injected, intent always `none`. */
+export type SetupEnroller = (input: {
+    slug: string;
+    intent: EnrollmentIntent;
+    keyReference: string;
+    env: NodeJS.ProcessEnv;
+    onDeviceAuthorization: (prompt: DeviceAuthorizationPrompt) => void | Promise<void>;
+}) => Promise<EnrollmentOutcome>;
+export interface BoardClient {
+    redeemInviteLink(input: {
+        p_code: string;
+    }): Promise<unknown>;
+}
+export interface SetupDeps {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    platform?: NodeJS.Platform;
+    /** stdin is a terminal. Default `process.stdin.isTTY === true`. */
+    interactive?: boolean;
+    /** One line from the terminal; `secret` hides the echo. */
+    prompt?: (question: string, options: {
+        secret: boolean;
+    }) => Promise<string>;
+    /** All of stdin (non-interactive). */
+    readStdin?: () => Promise<string>;
+    /** Every child (busctl, sudo, the harness CLIs) runs through this, with no stdin. */
+    run?: ChildRunner;
+    /** Default `/usr/bin/sudo`: never a PATH lookup. */
+    sudoPath?: string;
+    hostname?: () => string;
+    bakedAssets?: () => BakedAssets;
+    selectKeyStorage?: (ctx: KeyStorageContext) => Promise<KeyStorageSelection>;
+    /** Seams passed through to the storage selector (probeKeychain, run, keyslotDir, …). */
+    storage?: Partial<KeyStorageContext>;
+    enroll?: SetupEnroller;
+    createBoardClient?: (fileEnv: NodeJS.ProcessEnv) => BoardClient;
+    doctor?: (options: DoctorOptions) => Promise<DoctorReport>;
+    /** Seams passed through to doctor (createClient, probeKeystore, isAlive, …). */
+    doctorOptions?: Partial<DoctorOptions>;
+    /** Seams passed through to the harness writer (fs, claudeManagedDir). */
+    writer?: Partial<Pick<WriterContext, "fs" | "claudeManagedDir">>;
+}
+export declare const DEFAULT_SUDO = "/usr/bin/sudo";
+export declare const SECRET_SERVICE_NAME = "org.freedesktop.secrets";
+/** `busctl --user call … NameHasOwner`: asks the BUS whether the name is owned; never calls the service. */
+export declare const NAME_HAS_OWNER_ARGS: readonly string[];
+/**
+ * The keychain tool's install, one complete argv per package manager, first found wins. Each
+ * package name was re-checked against the distro's own index (throwaway containers, 2026-09-27):
+ * ubuntu 24.04 `libsecret-tools` ships ./usr/bin/secret-tool; fedora 44 `dnf repoquery
+ * --whatprovides /usr/bin/secret-tool` → libsecret; arch `pacman -F usr/bin/secret-tool` →
+ * core/libsecret; opensuse tumbleweed `zypper se --provides /usr/bin/secret-tool` → secret-tool
+ * (NOT libsecret-tools, which the plan text named).
+ */
+export declare const KEYCHAIN_INSTALL_ARGV: ReadonlyArray<{
+    manager: string;
+    argv: readonly string[];
+}>;
+/** `<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;
+interface DepsContext {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    interactive: boolean;
+    installDeps: boolean;
+    run: ChildRunner;
+    sudo: string;
+    prompt: (question: string, options: {
+        secret: boolean;
+    }) => Promise<string>;
+}
+export declare function depsStep(ctx: DepsContext): Promise<DepsOutcome & {
+    fix?: string;
+}>;
+export declare function runSetup(options: SetupOptions, deps?: SetupDeps): Promise<SetupReport>;
+export type SetupRunner = (options: SetupOptions) => Promise<SetupReport>;
+interface SetupIo {
+    writeStdout(message: string): void;
+    writeStderr(message: string): void;
+}
+export declare function formatSetupReport(report: SetupReport): string;
+export declare function addSetupCommand(program: Command, io: SetupIo, setup: SetupRunner): void;
+export {};