@the-librarian/cli 1.0.0-rc.3

package/dist/config.js

@@ -0,0 +1,65 @@
+// Config core: MCP URL, agent token, and derived server URL.
+//
+// The persisted truth is `~/.librarian/env` (token + MCP URL). The
+// server URL is *derived* by default — it's the origin of the MCP URL —
+// but can be set explicitly. Reading config never exposes the token: the
+// redacted view reports only whether it's *set*, never the value.
+//
+// `home` is injectable everywhere so tests run against a temp dir.
+import { detectShell, readEnvFile, writeEnvFile } from "./env.js";
+import { applyShellBlock } from "./env.js";
+/** Derive the server base URL (origin) from the MCP URL; "" if unparseable. */
+export function deriveServerUrl(mcpUrl) {
+    if (!mcpUrl)
+        return "";
+    try {
+        return new URL(mcpUrl).origin;
+    }
+    catch {
+        return "";
+    }
+}
+/** Load the current config from `~/.librarian/env`, or null if unset. */
+export function readConfig(home) {
+    const env = readEnvFile(home);
+    if (!env)
+        return null;
+    return {
+        mcpUrl: env.mcpUrl,
+        token: env.token,
+        serverUrl: deriveServerUrl(env.mcpUrl),
+    };
+}
+/** A display-safe view: the token is reduced to a boolean, never printed. */
+export function redact(config) {
+    return {
+        mcpUrl: config.mcpUrl,
+        tokenSet: config.token.length > 0,
+        serverUrl: config.serverUrl,
+    };
+}
+/** Render the redacted config as human-readable lines (no token value). */
+export function formatConfig(config) {
+    return [
+        `MCP URL:    ${config.mcpUrl || "(not set)"}`,
+        `Server URL: ${config.serverUrl || "(not set)"}`,
+        `Token:      ${config.tokenSet ? "set (hidden)" : "(not set)"}`,
+    ].join("\n");
+}
+/**
+ * Update config values and persist them to `~/.librarian/env`.
+ *
+ * Merges over whatever is already stored (so setting just the token
+ * keeps the URL). Re-applies the managed shell block so a fresh `config`
+ * on a new shell still wires up sourcing. Returns the new config.
+ */
+export function setConfig(input, options = {}) {
+    const current = readEnvFile(options.home);
+    const mcpUrl = input.mcpUrl ?? current?.mcpUrl ?? "";
+    const token = input.token ?? current?.token ?? "";
+    writeEnvFile({ mcpUrl, token }, options.home);
+    const shell = options.shell ?? detectShell();
+    applyShellBlock(shell, { mcpUrl, token }, options.home);
+    return { mcpUrl, token, serverUrl: deriveServerUrl(mcpUrl) };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,mEAAmE;AACnE,wEAAwE;AACxE,yEAAyE;AACzE,kEAAkE;AAClE,EAAE;AACF,mEAAmE;AAEnE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAc,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAmB3C,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;KACvC,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,MAAM,CAAC,MAAuB;IAC5C,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,YAAY,CAAC,MAAsB;IACjD,OAAO;QACL,eAAe,MAAM,CAAC,MAAM,IAAI,WAAW,EAAE;QAC7C,eAAe,MAAM,CAAC,SAAS,IAAI,WAAW,EAAE;QAChD,eAAe,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,EAAE;KAChE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,KAAqB,EACrB,UAAoE,EAAE;IAEtE,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;IAClD,YAAY,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,EAAE,CAAC;IAC7C,eAAe,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;AAC/D,CAAC"}

package/dist/doctor.d.ts

@@ -0,0 +1,23 @@
+/** Outcome of a server-reachability probe. */
+export interface ProbeResult {
+    ok: boolean;
+    /** A short human detail: the status code, or why it failed. */
+    detail: string;
+}
+/**
+ * Probe whether the configured server is reachable. INJECTABLE so tests never
+ * hit the network; OFFLINE-TOLERANT so a down server is a flagged problem, not
+ * a crash. The token is never sent here — this is an unauthenticated liveness
+ * check against public endpoints.
+ */
+export type ServerProbe = (serverUrl: string) => Promise<ProbeResult>;
+/** Override the server-reachability probe (tests inject a canned one). */
+export declare function setServerProbe(next: ServerProbe): void;
+/** Restore the default (network) server probe (tests). */
+export declare function resetServerProbe(): void;
+/**
+ * Run the diagnostic and render its report. `home` is injectable for tests.
+ * Always resolves (never rejects); the caller exits 0 regardless.
+ */
+export declare function doctor(home?: string): Promise<string>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAeA,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAwBtE,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAEtD;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyC3D"}

package/dist/doctor.js

@@ -0,0 +1,81 @@
+// `librarian doctor` — a read-only diagnostic. Exits 0 ALWAYS (it's a
+// report, not a gate), but clearly flags each problem it finds:
+//   - is the agent token set? (from `readConfig`; shown only as set/not — the
+//     value is NEVER printed);
+//   - is the server reachable? (a GET against `<serverUrl>/healthz`, falling
+//     back to `/primer.md`; INJECTABLE + offline-tolerant);
+//   - which harness CLIs are on PATH? (`which` from exec.ts);
+//   - the machine id + hostname (the dashboard's row key).
+import { readConfig } from "./config.js";
+import { which } from "./exec.js";
+import { HARNESS_CLI } from "./harnesses/cli.js";
+import { allHarnesses } from "./harnesses/index.js";
+import { hostname, machineId } from "./machine.js";
+/** The probe paths we try, in order, against the server origin. */
+const PROBE_PATHS = ["/healthz", "/primer.md"];
+const PROBE_TIMEOUT_MS = 3000;
+const defaultServerProbe = async (serverUrl) => {
+    if (!serverUrl)
+        return { ok: false, detail: "no server URL configured" };
+    let lastDetail = "unreachable";
+    for (const probePath of PROBE_PATHS) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+        try {
+            const url = `${serverUrl.replace(/\/+$/, "")}${probePath}`;
+            const res = await fetch(url, { method: "GET", redirect: "error", signal: controller.signal });
+            if (res.ok)
+                return { ok: true, detail: `HTTP ${res.status} ${probePath}` };
+            lastDetail = `HTTP ${res.status} ${probePath}`;
+        }
+        catch (error) {
+            lastDetail = error instanceof Error ? error.message : "unreachable";
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return { ok: false, detail: lastDetail };
+};
+let serverProbe = defaultServerProbe;
+/** Override the server-reachability probe (tests inject a canned one). */
+export function setServerProbe(next) {
+    serverProbe = next;
+}
+/** Restore the default (network) server probe (tests). */
+export function resetServerProbe() {
+    serverProbe = defaultServerProbe;
+}
+/**
+ * Run the diagnostic and render its report. `home` is injectable for tests.
+ * Always resolves (never rejects); the caller exits 0 regardless.
+ */
+export async function doctor(home) {
+    const cfg = readConfig(home);
+    const lines = ["librarian doctor", ""];
+    // 1) Token + URL config (token shown only as set/not — never the value).
+    const tokenSet = Boolean(cfg && cfg.token.length > 0);
+    lines.push(`Token:       ${tokenSet ? "set" : "NOT SET — run `librarian config --token <token>`"}`);
+    lines.push(`MCP URL:     ${cfg?.mcpUrl || "NOT SET — run `librarian config --mcp-url <url>`"}`);
+    lines.push(`Server URL:  ${cfg?.serverUrl || "(not set)"}`);
+    // 2) Server reachability (injectable + offline-tolerant).
+    const probe = await serverProbe(cfg?.serverUrl ?? "");
+    lines.push(`Server:      ${probe.ok ? `reachable (${probe.detail})` : `UNREACHABLE — ${probe.detail}`}`);
+    // 3) Harness CLIs on PATH.
+    lines.push("", "Harness CLIs on PATH:");
+    for (const harness of allHarnesses) {
+        const cli = HARNESS_CLI[harness.id];
+        if (cli === null) {
+            lines.push(`  ${harness.displayName}: file-based (no CLI)`);
+            continue;
+        }
+        const found = await which(cli);
+        lines.push(`  ${harness.displayName}: ${found ? `\`${cli}\` found` : `\`${cli}\` NOT on PATH`}`);
+    }
+    // 4) Machine identity.
+    lines.push("", `Machine id:  ${machineId(home)}`, `Hostname:    ${hostname()}`);
+    const problems = !tokenSet || !cfg?.mcpUrl || !probe.ok;
+    lines.push("", problems ? "Some checks need attention (see lines flagged above)." : "All checks passed.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,39 @@
+/** The secrets the env file carries. */
+export interface EnvValues {
+    mcpUrl: string;
+    token: string;
+}
+export type Shell = "bash" | "zsh" | "fish";
+/**
+ * Detect the user's shell from `$SHELL`, defaulting to bash.
+ *
+ * `override` (e.g. from a `--shell` flag) wins when it names a supported
+ * shell. An unrecognised `$SHELL` falls back to bash — the POSIX block
+ * is the safe default.
+ */
+export declare function detectShell(override?: string, env?: NodeJS.ProcessEnv): Shell;
+/**
+ * Write `~/.librarian/env` with the two exports, chmod 600.
+ *
+ * The directory is created if missing; the file is (re)written wholesale
+ * so stale values can't linger. Never logs `values.token`.
+ */
+export declare function writeEnvFile(values: EnvValues, home?: string): void;
+/** Read the env file back into structured values, or null if absent. */
+export declare function readEnvFile(home?: string): EnvValues | null;
+/**
+ * Apply (or replace) the managed block in the shell rc.
+ *
+ * For bash/zsh this writes the POSIX source-block into `~/.bashrc` or
+ * `~/.zshrc`. For fish it writes `~/.config/fish/conf.d/librarian.fish`
+ * with `set -gx` reading the values directly (fish can't source POSIX).
+ *
+ * Idempotent: a second call with the rc already containing a block
+ * replaces it in place — never appends a duplicate.
+ *
+ * Returns the path that was written.
+ */
+export declare function applyShellBlock(shell: Shell, values: EnvValues, home?: string): string;
+/** Remove the managed block from the shell rc (or delete the fish conf). */
+export declare function removeShellBlock(shell: Shell, home?: string): void;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAsBA,wCAAwC;AACxC,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAW5C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,KAAK,CAU1F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAanE;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAW3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQtF;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAclE"}

package/dist/env.js

@@ -0,0 +1,208 @@
+// Env-var plumbing: `~/.librarian/env` + the managed shell-rc block.
+//
+// The token and MCP URL never land in a committed or world-readable rc.
+// We write them to `~/.librarian/env` (chmod 600) and add ONE idempotent
+// managed block to the user's shell rc that sources it:
+//
+//   # >>> librarian >>>
+//   [ -f "$HOME/.librarian/env" ] && . "$HOME/.librarian/env"
+//   # <<< librarian <<<
+//
+// Re-running REPLACES the block (matched on the sentinels) — never
+// duplicates. Fish can't source a POSIX env file, so it gets a native
+// `~/.config/fish/conf.d/librarian.fish` with `set -gx` reading the same
+// values. The token is never logged.
+//
+// Every function takes an injectable `home` so tests run against a temp
+// dir; nothing here touches the real `~`.
+import fs from "node:fs";
+import path from "node:path";
+import { bashRcPath, envFilePath, fishConfPath, librarianDir, zshRcPath } from "./paths.js";
+// The exact sentinels the spec pins. The block is matched on these so a
+// re-run replaces it rather than appending a duplicate. Do not reword.
+const BLOCK_OPEN = "# >>> librarian >>>";
+const BLOCK_CLOSE = "# <<< librarian <<<";
+const POSIX_SOURCE_LINE = '[ -f "$HOME/.librarian/env" ] && . "$HOME/.librarian/env"';
+const FISH_OPEN = "# >>> librarian >>>";
+const FISH_CLOSE = "# <<< librarian <<<";
+/**
+ * Detect the user's shell from `$SHELL`, defaulting to bash.
+ *
+ * `override` (e.g. from a `--shell` flag) wins when it names a supported
+ * shell. An unrecognised `$SHELL` falls back to bash — the POSIX block
+ * is the safe default.
+ */
+export function detectShell(override, env = process.env) {
+    const pick = (value) => {
+        if (!value)
+            return undefined;
+        const base = value.toLowerCase();
+        if (base.includes("fish"))
+            return "fish";
+        if (base.includes("zsh"))
+            return "zsh";
+        if (base.includes("bash"))
+            return "bash";
+        return undefined;
+    };
+    return pick(override) ?? pick(env.SHELL) ?? "bash";
+}
+/**
+ * Write `~/.librarian/env` with the two exports, chmod 600.
+ *
+ * The directory is created if missing; the file is (re)written wholesale
+ * so stale values can't linger. Never logs `values.token`.
+ */
+export function writeEnvFile(values, home) {
+    const dir = librarianDir(home);
+    fs.mkdirSync(dir, { recursive: true });
+    const body = [
+        `export LIBRARIAN_MCP_URL=${shellQuote(values.mcpUrl)}`,
+        `export LIBRARIAN_AGENT_TOKEN=${shellQuote(values.token)}`,
+        "",
+    ].join("\n");
+    const file = envFilePath(home);
+    fs.writeFileSync(file, body, { encoding: "utf8", mode: 0o600 });
+    // writeFileSync only applies `mode` on create; chmod unconditionally so a
+    // pre-existing looser file is tightened.
+    fs.chmodSync(file, 0o600);
+}
+/** Read the env file back into structured values, or null if absent. */
+export function readEnvFile(home) {
+    let raw;
+    try {
+        raw = fs.readFileSync(envFilePath(home), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const mcpUrl = parseExport(raw, "LIBRARIAN_MCP_URL");
+    const token = parseExport(raw, "LIBRARIAN_AGENT_TOKEN");
+    if (mcpUrl === undefined && token === undefined)
+        return null;
+    return { mcpUrl: mcpUrl ?? "", token: token ?? "" };
+}
+/**
+ * Apply (or replace) the managed block in the shell rc.
+ *
+ * For bash/zsh this writes the POSIX source-block into `~/.bashrc` or
+ * `~/.zshrc`. For fish it writes `~/.config/fish/conf.d/librarian.fish`
+ * with `set -gx` reading the values directly (fish can't source POSIX).
+ *
+ * Idempotent: a second call with the rc already containing a block
+ * replaces it in place — never appends a duplicate.
+ *
+ * Returns the path that was written.
+ */
+export function applyShellBlock(shell, values, home) {
+    if (shell === "fish")
+        return writeFishConf(values, home);
+    const rcPath = shell === "zsh" ? zshRcPath(home) : bashRcPath(home);
+    const block = [BLOCK_OPEN, POSIX_SOURCE_LINE, BLOCK_CLOSE].join("\n");
+    const next = upsertBlock(readFileOrEmpty(rcPath), block);
+    fs.mkdirSync(path.dirname(rcPath), { recursive: true });
+    fs.writeFileSync(rcPath, next, { encoding: "utf8" });
+    return rcPath;
+}
+/** Remove the managed block from the shell rc (or delete the fish conf). */
+export function removeShellBlock(shell, home) {
+    if (shell === "fish") {
+        try {
+            fs.rmSync(fishConfPath(home));
+        }
+        catch {
+            // already gone
+        }
+        return;
+    }
+    const rcPath = shell === "zsh" ? zshRcPath(home) : bashRcPath(home);
+    const current = readFileOrEmpty(rcPath);
+    if (!current)
+        return;
+    const stripped = stripBlock(current);
+    if (stripped !== current)
+        fs.writeFileSync(rcPath, stripped, { encoding: "utf8" });
+}
+function writeFishConf(values, home) {
+    const confPath = fishConfPath(home);
+    const body = [
+        FISH_OPEN,
+        `set -gx LIBRARIAN_MCP_URL ${fishQuote(values.mcpUrl)}`,
+        `set -gx LIBRARIAN_AGENT_TOKEN ${fishQuote(values.token)}`,
+        FISH_CLOSE,
+        "",
+    ].join("\n");
+    fs.mkdirSync(path.dirname(confPath), { recursive: true });
+    // The fish conf carries the token directly, so tighten it to 600 too.
+    fs.writeFileSync(confPath, body, { encoding: "utf8", mode: 0o600 });
+    fs.chmodSync(confPath, 0o600);
+    return confPath;
+}
+// --- block manipulation (sentinel-matched, idempotent) -------------------
+/** Replace an existing sentinel block, or append a fresh one. */
+function upsertBlock(content, block) {
+    const stripped = stripBlock(content);
+    const base = stripped.length === 0 || stripped.endsWith("\n") ? stripped : `${stripped}\n`;
+    return `${base}${block}\n`;
+}
+/** Remove a sentinel-delimited block (and its surrounding blank lines). */
+function stripBlock(content) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => line.trim() === BLOCK_OPEN);
+    if (start === -1)
+        return content;
+    let end = -1;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (lines[i]?.trim() === BLOCK_CLOSE) {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return content; // unterminated — leave it alone
+    const before = lines.slice(0, start);
+    const after = lines.slice(end + 1);
+    // Drop a single trailing blank line left by the block so repeated
+    // apply/strip cycles don't accumulate whitespace.
+    while (before.length > 0 && before[before.length - 1] === "")
+        before.pop();
+    while (after.length > 0 && after[0] === "")
+        after.shift();
+    const joined = [...before, ...after].join("\n");
+    return joined;
+}
+// --- small helpers -------------------------------------------------------
+function readFileOrEmpty(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function parseExport(raw, name) {
+    // Matches `export NAME=value` (value optionally single/double quoted).
+    const re = new RegExp(`^\\s*export\\s+${name}=(.*)$`, "m");
+    const match = re.exec(raw);
+    if (!match)
+        return undefined;
+    return unquote((match[1] ?? "").trim());
+}
+/** POSIX single-quote a value so the env file is robust to special chars. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Fish single-quote a value (fish escapes `\` and `'` inside single quotes). */
+function fishQuote(value) {
+    return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+function unquote(value) {
+    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+        return value.slice(1, -1).replace(/'\\''/g, "'");
+    }
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"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"}

package/dist/exec.d.ts

@@ -0,0 +1,37 @@
+/** The result of running a command: captured streams + exit code. */
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    /** The process exit code; `null` only if the process was signalled. */
+    code: number | null;
+}
+/** Options for a single command run. */
+export interface RunOptions {
+    /**
+     * Extra environment for the child. Merged over `process.env`. The token
+     * rides here (per a harness's native env-var mechanism) — it is passed
+     * to the child but never logged by this module.
+     */
+    env?: Record<string, string | undefined> | undefined;
+    /** Working directory for the child. */
+    cwd?: string | undefined;
+}
+/**
+ * The runner surface every harness depends on. The default implementation
+ * spawns real processes; tests inject a fake that records calls.
+ */
+export interface Runner {
+    /** Run `cmd args…`, resolving with captured streams + exit code. */
+    run(cmd: string, args: readonly string[], opts?: RunOptions): Promise<RunResult>;
+    /** Resolve `cmd` to its absolute path on PATH, or `null` if absent. */
+    which(cmd: string): Promise<string | null>;
+}
+/** Run a command through the current runner. */
+export declare function run(cmd: string, args: readonly string[], opts?: RunOptions): Promise<RunResult>;
+/** Resolve a command to its PATH location through the current runner. */
+export declare function which(cmd: string): Promise<string | null>;
+/** Swap in a fake runner (tests). Returns the previous runner. */
+export declare function setRunner(runner: Runner): Runner;
+/** Restore the real, process-spawning runner (tests). */
+export declare function resetRunner(): void;
+//# sourceMappingURL=exec.d.ts.map

package/dist/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAkBA,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IACrD,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,oEAAoE;IACpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACjF,uEAAuE;IACvE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC5C;AAmDD,gDAAgD;AAChD,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAE/F;AAED,yEAAyE;AACzE,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEzD;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,yDAAyD;AACzD,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/exec.js

@@ -0,0 +1,81 @@
+// Injectable child-process runner.
+//
+// Every harness that drives a native CLI (`claude`, `codex`, `pi`) goes
+// through this module rather than calling `node:child_process` directly,
+// so tests can stub the runner and assert the exact command + args a
+// harness invokes — WITHOUT spawning real processes or touching PATH.
+//
+// Security (spec §9): a command may *carry* the agent token (e.g. via an
+// env var its native mechanism reads), but the token is NEVER logged,
+// echoed, or placed where this module would print it. The runner returns
+// stdout/stderr to the caller; it deliberately does not log them.
+//
+// Stubbing: `setRunner()` swaps the module-level default for a fake in
+// tests; `resetRunner()` restores the real one. `run`/`which` always go
+// through the current runner, so a single override covers both.
+import { spawn } from "node:child_process";
+// --- the real, process-spawning runner -----------------------------------
+const realRunner = {
+    run(cmd, args, opts = {}) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(cmd, [...args], {
+                cwd: opts.cwd,
+                env: opts.env ? { ...process.env, ...opts.env } : process.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let stdout = "";
+            let stderr = "";
+            child.stdout?.on("data", (chunk) => {
+                stdout += chunk.toString("utf8");
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString("utf8");
+            });
+            // ENOENT (binary not on PATH) surfaces here, not as a non-zero exit.
+            child.on("error", reject);
+            child.on("close", (code) => {
+                resolve({ stdout, stderr, code });
+            });
+        });
+    },
+    async which(cmd) {
+        // Use the platform's own resolver so PATHEXT etc. are honoured. A
+        // non-zero exit (not found) resolves to null; we never throw.
+        const probe = process.platform === "win32" ? "where" : "which";
+        try {
+            const { stdout, code } = await realRunner.run(probe, [cmd]);
+            if (code !== 0)
+                return null;
+            const first = stdout
+                .split("\n")
+                .map((l) => l.trim())
+                .find((l) => l.length > 0);
+            return first ?? null;
+        }
+        catch {
+            // `which`/`where` itself missing, or some other spawn failure.
+            return null;
+        }
+    },
+};
+// --- the swappable module-level runner -----------------------------------
+let current = realRunner;
+/** Run a command through the current runner. */
+export function run(cmd, args, opts) {
+    return current.run(cmd, args, opts);
+}
+/** Resolve a command to its PATH location through the current runner. */
+export function which(cmd) {
+    return current.which(cmd);
+}
+/** Swap in a fake runner (tests). Returns the previous runner. */
+export function setRunner(runner) {
+    const prev = current;
+    current = runner;
+    return prev;
+}
+/** Restore the real, process-spawning runner (tests). */
+export function resetRunner() {
+    current = realRunner;
+}
+//# sourceMappingURL=exec.js.map

package/dist/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"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"}

package/dist/harnesses/claude.d.ts

@@ -0,0 +1,3 @@
+import type { HarnessModule } from "./types.js";
+export declare const claude: HarnessModule;
+//# sourceMappingURL=claude.d.ts.map

package/dist/harnesses/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/harnesses/claude.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAiB,aAAa,EAAE,MAAM,YAAY,CAAC;AAgC/D,eAAO,MAAM,MAAM,EAAE,aAsCpB,CAAC"}