@atbash/cli 0.5.15 → 0.6.0-dev.1

package/dist/commands/setup.js

@@ -0,0 +1,944 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKeyMaterial = parseKeyMaterial;
+exports.normalizePrivkey = normalizePrivkey;
+exports.keyCandidatesInDir = keyCandidatesInDir;
+exports.resolveKeySource = resolveKeySource;
+exports.keyFileContents = keyFileContents;
+exports.isJsonc = isJsonc;
+exports.mergeOpenclawConfig = mergeOpenclawConfig;
+exports.buildPlan = buildPlan;
+exports.lineDiff = lineDiff;
+exports.renderPlan = renderPlan;
+exports.backupFile = backupFile;
+exports.applyPlan = applyPlan;
+exports.registerSetupCommand = registerSetupCommand;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
+const jsonc = __importStar(require("jsonc-parser"));
+const sdk_1 = require("@atbash/sdk");
+const connect_1 = require("./connect");
+/**
+ * `atbash setup` — the write half of onboarding.
+ *
+ * Onboarding registers an agent on chain and issues its certificate. None of
+ * that governs anything until the runtime on the agent's machine is pointed at
+ * Atbash, and that step used to be four manual operations: move a downloaded
+ * key file, install a plugin, hand-merge a JSON block into an existing config
+ * "without erasing the existing configurations", restart the gateway. The merge
+ * is the one people get wrong, and getting it wrong means an agent that reports
+ * registered while enforcing nothing.
+ *
+ * This command does those steps.
+ *
+ * ── RELATIONSHIP TO `atbash connect` ─────────────────────────────────────────
+ * `connect` is READ-ONLY and must stay that way: the onboarding page promises
+ * "installs nothing, changes nothing", and a cautious agent asked to run it is
+ * right to verify that. `setup` is the separate, explicitly-named command that
+ * writes. Never move write behavior into `connect`, and never describe `setup`
+ * with `connect`'s copy.
+ *
+ * ── WHAT IT WILL NOT DO ──────────────────────────────────────────────────────
+ *  1. It never sends the private key anywhere. The key is read locally, written
+ *     locally, and used locally to derive a public key. The only network call is
+ *     an optional registration check that transmits the PUBLIC key.
+ *  2. It never writes the private key into an MCP client config. The documented
+ *     `@atbash/mcp` wiring passes the key as an `ATBASH_AGENT_PRIVKEY` env value
+ *     inside e.g. `claude_desktop_config.json` — a file people screenshot, sync
+ *     and share. That package has no key-file fallback today (verified against
+ *     the published 0.1.3), so MCP clients are REPORTED with the snippet to add
+ *     by hand rather than silently seeded with a secret.
+ *  3. It never edits application source. Code-level integrations (LangChain,
+ *     LangGraph, AutoGen, Eliza, the SDK boundary) are the owner's to write.
+ *  4. It never rewrites a config file that uses comments or trailing commas.
+ *     Reserializing JSONC as JSON silently deletes the owner's comments, so
+ *     those files fall back to a printed snippet.
+ *
+ * ── NOTHING HERE IS INVENTED ─────────────────────────────────────────────────
+ * The plugin package name, the entry key it registers as, the config field names
+ * and the key-file format are all taken from the published integration docs. A
+ * plausible-looking config for a plugin that does not exist is worse than no
+ * config: it sends someone editing files for a package they cannot install.
+ */
+// ── The canonical resting place for the agent key ───────────────────────────
+// Every Atbash integration reads this path, and `@atbash/sdk`'s resolveKeyPath
+// defaults to it. Whichever way the key arrives — pasted inline, read out of the
+// browser download, already present — it ends up here once, and every runtime
+// config we write REFERENCES this path rather than embedding the secret again.
+const KEY_FILE_REL = [".config", "atbash", "guard-client-key"];
+const OPENCLAW_CONFIG_REL = [".openclaw", "openclaw.json"];
+const OPENCLAW_EXTENSIONS_REL = [".openclaw", "extensions"];
+const HERMES_AGENT_REL = [".hermes", "hermes-agent"];
+/**
+ * The OpenClaw plugin, and the entry key it registers itself as.
+ *
+ * The entry key really is `openclaw` — that is what `@atbash/atbash-openclaw`
+ * registers as, not a copy-paste slip. Installs of the earlier
+ * `@atbash/atbash-plugin` register under `atbash-plugin`, and the dashboard's
+ * capability scan recognizes BOTH. So an existing config carrying the legacy key
+ * is already governed and must not be given a second, duplicate entry.
+ */
+const OPENCLAW_PKG = "@atbash/atbash-openclaw";
+const OPENCLAW_ENTRY = "openclaw";
+const OPENCLAW_LEGACY_ENTRY = "atbash-plugin";
+/** File modes: 0700 for the key directory, 0600 for the key itself. */
+const DIR_MODE = 0o700;
+const KEY_MODE = 0o600;
+// ── small filesystem helpers (best-effort; never throw) ─────────────────────
+const exists = (...segs) => {
+    try {
+        return fs.existsSync(path.join(...segs));
+    }
+    catch {
+        return false;
+    }
+};
+const readTextFile = (file) => {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Expand a leading `~/`. `--key-file ~/Downloads/keys.txt` typed inside quotes
+ * reaches us unexpanded, and failing on it would look like a missing file.
+ */
+function expandHome(p, home) {
+    if (p === "~")
+        return home;
+    if (p.startsWith("~/"))
+        return path.join(home, p.slice(2));
+    return p;
+}
+/**
+ * Pull key material out of whatever the owner pointed us at.
+ *
+ * Accepts every shape Atbash itself produces or documents, so "the file I
+ * downloaded from the modal" always works:
+ *   - `privkey=…` / `pubkey=…` lines (what onboarding downloads, and what the
+ *     plugin parses)
+ *   - `{"privKey":…,"pubKey":…}` JSON (the alternate documented key-file form)
+ *   - a bare 64-hex private key on its own line (someone who copied just the key)
+ *
+ * Returns null rather than throwing: the caller tries several sources in turn and
+ * an unparseable one is a reason to move on, not to abort.
+ */
+function parseKeyMaterial(raw) {
+    const text = raw.trim();
+    if (!text)
+        return null;
+    if (text.startsWith("{")) {
+        try {
+            const o = JSON.parse(text);
+            const priv = String(o.privKey ?? o.privkey ?? o.privateKey ?? "").trim();
+            const pub = String(o.pubKey ?? o.pubkey ?? o.publicKey ?? "").trim();
+            const clean = normalizePrivkey(priv);
+            return clean ? { privkey: clean, statedPubkey: pub || undefined } : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    let priv = "";
+    let pub = "";
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("#") || !trimmed)
+            continue;
+        // Tolerate `privkey = x` and `privkey: x` — hand-edited files drift.
+        const kv = trimmed.match(/^(privkey|private_key|privatekey|pubkey|public_key|publickey)\s*[:=]\s*(.+)$/i);
+        if (kv) {
+            const value = kv[2].trim();
+            if (/^p(riv|rivate)/i.test(kv[1]))
+                priv = value;
+            else
+                pub = value;
+            continue;
+        }
+        // A bare key on its own line — only if we have not already found a labelled one.
+        if (!priv && /^(0x)?[0-9a-fA-F]{64}$/.test(trimmed))
+            priv = trimmed;
+    }
+    const clean = normalizePrivkey(priv);
+    return clean ? { privkey: clean, statedPubkey: pub || undefined } : null;
+}
+/** Normalize to the lowercase 64-hex the SDK validates, or "" if it is not one. */
+function normalizePrivkey(raw) {
+    const clean = raw.replace(/^0x/i, "").trim().toLowerCase();
+    return (0, sdk_1.isValidPrivateKey)(clean) ? clean : "";
+}
+/** Files in a directory that plausibly hold an Atbash agent key, newest first. */
+function keyCandidatesInDir(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const matches = names.filter((n) => n === "guard-client-key" ||
+        /^agent-keys-.*\.txt$/i.test(n) ||
+        /^atbash.*(key|keys).*\.(txt|json)$/i.test(n));
+    return matches
+        .map((n) => path.join(dir, n))
+        .map((file) => {
+        let mtime = 0;
+        try {
+            mtime = fs.statSync(file).mtimeMs;
+        }
+        catch { /* unreadable — sorts last */ }
+        return { file, mtime };
+    })
+        .sort((a, b) => b.mtime - a.mtime)
+        .map((e) => e.file);
+}
+/**
+ * Read a secret from the terminal without echoing it.
+ *
+ * Prompting exists so the key does not have to appear in the command line: an
+ * inline `--key` is convenient (it is what makes a one-line command copied out of
+ * the browser work) but it lands in shell history and in the process list. When
+ * there is a TTY and no key was supplied, ask instead.
+ *
+ * The prompt deliberately accepts a PATH as well as a key, because "where are
+ * your keys?" and "paste your key" are the same question from the owner's side.
+ */
+async function promptForKeyOrPath() {
+    const { createInterface } = await Promise.resolve().then(() => __importStar(require("node:readline")));
+    return new Promise((resolveP) => {
+        const input = process.stdin;
+        const rl = createInterface({ input, output: process.stdout, terminal: true });
+        // Mute the echo so a pasted key does not sit on screen (or in a scrollback
+        // buffer that gets screenshotted). A pasted path is muted too; that is a
+        // small cost against leaving a private key visible.
+        const asMutable = rl;
+        const prompt = "Paste the agent's private key, or the path to its key file: ";
+        asMutable._writeToOutput = function (s) {
+            if (s.includes(prompt))
+                asMutable.output?.write(s);
+            else if (s === "\r\n" || s === "\n")
+                asMutable.output?.write(s);
+            // every other keystroke echo is dropped
+        };
+        rl.question(prompt, (answer) => { rl.close(); resolveP(answer.trim()); });
+    });
+}
+/**
+ * Find the agent key, trying every way an owner could plausibly have it.
+ *
+ * Order is "most explicit first": a flag the owner typed beats a file we guessed
+ * at. The last resort is the interactive prompt, and if there is no TTY the
+ * caller gets a clear error listing the flags rather than a hang.
+ */
+async function resolveKeySource(opts) {
+    const { home } = opts;
+    const fromFile = (file, label) => {
+        const text = readTextFile(file);
+        if (text === null)
+            return { error: `Could not read ${file}` };
+        const material = parseKeyMaterial(text);
+        if (!material)
+            return { error: `${file} does not contain a valid 64-hex agent private key.` };
+        return { material, from: `${label} (${file})` };
+    };
+    // 1. Inline — what a one-line command copied from the onboarding modal uses.
+    if (opts.key) {
+        const material = parseKeyMaterial(opts.key);
+        if (!material)
+            return { error: "--key is not a valid agent private key (expected 64 hex characters)." };
+        return { material, from: "--key on the command line" };
+    }
+    // 2. An explicit file.
+    if (opts.keyFile)
+        return fromFile(expandHome(opts.keyFile, home), "--key-file");
+    // 3. A directory to look in — "the keys are in my Downloads folder".
+    if (opts.keysDir) {
+        const dir = expandHome(opts.keysDir, home);
+        const candidates = keyCandidatesInDir(dir);
+        if (!candidates.length) {
+            return { error: `No agent key file found in ${dir} (looked for guard-client-key and agent-keys-*.txt).` };
+        }
+        return fromFile(candidates[0], "--keys-dir");
+    }
+    // 4. The environment variable the rest of the CLI already honours.
+    const fromEnv = process.env.ATBASH_AGENT_KEY;
+    if (fromEnv) {
+        const material = parseKeyMaterial(fromEnv);
+        if (material)
+            return { material, from: "ATBASH_AGENT_KEY" };
+    }
+    // 5. Already in the canonical place — a re-run, or a machine set up before.
+    const keyFile = path.join(home, ...KEY_FILE_REL);
+    if (exists(keyFile)) {
+        const found = fromFile(keyFile, "existing key file");
+        if (!("error" in found))
+            return found;
+    }
+    // 6. The CLI's own config, populated by `atbash set agent-key`.
+    const fromConfig = (0, sdk_1.resolve)("agentKey");
+    if (fromConfig) {
+        const material = parseKeyMaterial(fromConfig);
+        if (material)
+            return { material, from: "atbash config (agentKey)" };
+    }
+    // 7. Ask.
+    if (opts.allowPrompt) {
+        const answer = await promptForKeyOrPath();
+        if (!answer)
+            return { error: "No key provided." };
+        const direct = parseKeyMaterial(answer);
+        if (direct)
+            return { material: direct, from: "interactive prompt" };
+        const asPath = expandHome(answer, home);
+        if (exists(asPath)) {
+            const stat = fs.statSync(asPath);
+            if (stat.isDirectory()) {
+                const candidates = keyCandidatesInDir(asPath);
+                if (candidates.length)
+                    return fromFile(candidates[0], "directory given at the prompt");
+                return { error: `No agent key file found in ${asPath}.` };
+            }
+            return fromFile(asPath, "file given at the prompt");
+        }
+        return { error: "That is neither a 64-hex private key nor a path that exists." };
+    }
+    return {
+        error: [
+            "No agent key found.",
+            "Provide one with --key <64-hex>, --key-file <path>, or --keys-dir <dir>,",
+            `or place it at ${keyFile} first.`,
+        ].join("\n"),
+    };
+}
+/** The key file, in the `key=value` form the plugin and the SDK both parse. */
+function keyFileContents(privkey, pubkey) {
+    return [
+        "# Atbash agent key",
+        "# Keep this file private (chmod 600). Read locally by every Atbash integration.",
+        `pubkey=${pubkey}`,
+        `privkey=${privkey}`,
+        "",
+    ].join("\n");
+}
+/**
+ * True when a JSON file uses JSONC features (comments, trailing commas).
+ *
+ * We must not auto-merge into one: writing it back with JSON.stringify would
+ * silently delete the owner's comments. Detected by the disagreement between the
+ * strict and tolerant parsers — strict fails, tolerant succeeds.
+ */
+function isJsonc(text) {
+    try {
+        JSON.parse(text);
+        return false;
+    }
+    catch { /* fall through */ }
+    const errors = [];
+    const value = jsonc.parse(text, errors, { allowTrailingComma: true, disallowComments: false });
+    return errors.length === 0 && value !== undefined;
+}
+/**
+ * Merge the Atbash plugin block into an OpenClaw config object, in place.
+ *
+ * A MERGE, not a replacement — that distinction is the whole reason this command
+ * exists. Other plugins already in `allow`, `load.paths` and `entries` are
+ * preserved, and an entry from the legacy `@atbash/atbash-plugin` install is
+ * updated where it stands rather than being shadowed by a duplicate: the
+ * dashboard scan recognizes both keys, so two entries would mean two hooks.
+ *
+ * `load.paths` gets the real absolute extension path. The published docs show a
+ * `<your-username>` placeholder that people paste verbatim, producing a path that
+ * does not exist and a plugin that never loads.
+ */
+function mergeOpenclawConfig(config, home) {
+    const out = { ...config };
+    const plugins = { ...(isRecord(out.plugins) ? out.plugins : {}) };
+    // Which key is this install governed under? Keep an existing legacy entry
+    // where it is instead of adding a second one.
+    const entries = { ...(isRecord(plugins.entries) ? plugins.entries : {}) };
+    const entryKey = OPENCLAW_LEGACY_ENTRY in entries && !(OPENCLAW_ENTRY in entries)
+        ? OPENCLAW_LEGACY_ENTRY
+        : OPENCLAW_ENTRY;
+    const allow = Array.isArray(plugins.allow) ? [...plugins.allow] : [];
+    if (!allow.includes(entryKey))
+        allow.push(entryKey);
+    plugins.allow = allow;
+    const load = { ...(isRecord(plugins.load) ? plugins.load : {}) };
+    const extensionPath = path.join(home, ...OPENCLAW_EXTENSIONS_REL, OPENCLAW_ENTRY);
+    const paths = Array.isArray(load.paths) ? [...load.paths] : [];
+    if (!paths.includes(extensionPath))
+        paths.push(extensionPath);
+    load.paths = paths;
+    plugins.load = load;
+    // Preserve any unrelated fields the owner set on the entry (debug, custom
+    // hooks); only the fields Atbash owns are asserted.
+    const existing = isRecord(entries[entryKey]) ? entries[entryKey] : {};
+    const existingConfig = isRecord(existing.config) ? existing.config : {};
+    const existingHooks = isRecord(existing.hooks) ? existing.hooks : {};
+    entries[entryKey] = {
+        ...existing,
+        enabled: true,
+        config: {
+            ...existingConfig,
+            enabled: true,
+            enforceDecision: true,
+            // The path, not the key. This is the whole point of the canonical location.
+            chromiaSecretPath: `~/${KEY_FILE_REL.join("/")}`,
+        },
+        hooks: {
+            ...existingHooks,
+            allowConversationAccess: true,
+            allowPromptInjection: true,
+        },
+    };
+    plugins.entries = entries;
+    out.plugins = plugins;
+    return out;
+}
+function isRecord(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+/** Is `openclaw` runnable on this machine? Decides install-for-you vs print-it. */
+function hasExecutable(command) {
+    const probe = (0, child_process_1.spawnSync)(process.platform === "win32" ? "where" : "which", [command], { stdio: "ignore" });
+    return probe.status === 0;
+}
+/**
+ * Work out everything that needs doing on this machine, without doing any of it.
+ *
+ * Detection drives the plan rather than a flag the owner picks, for the same
+ * reason the scan does: what is actually installed here is knowable, and asking
+ * someone to identify their own runtime from a list invites a wrong answer that
+ * writes a config for a plugin they do not have.
+ */
+function buildPlan(args) {
+    const { home, privkey, pubkey, noInstall, only } = args;
+    const steps = [];
+    const notes = [];
+    const found = [];
+    const wanted = (id) => only.length === 0 || only.includes(id);
+    // ── 1. The key file. Always, for every runtime: it is the one artifact every
+    // integration reads, and the thing the owner would otherwise move by hand.
+    const keyFile = path.join(home, ...KEY_FILE_REL);
+    const desiredKeyFile = keyFileContents(privkey, pubkey);
+    const currentKeyFile = readTextFile(keyFile);
+    const alreadyThisKey = currentKeyFile !== null && parseKeyMaterial(currentKeyFile)?.privkey === privkey;
+    if (!alreadyThisKey) {
+        if (currentKeyFile !== null) {
+            notes.push(`${keyFile} already holds a DIFFERENT agent key. It will be backed up before being replaced — check that you meant to re-point this machine at another agent.`);
+        }
+        steps.push({
+            kind: "write",
+            label: currentKeyFile === null ? "Save the agent key where every integration looks for it" : "Replace the agent key file",
+            file: keyFile,
+            mode: KEY_MODE,
+            before: currentKeyFile,
+            after: desiredKeyFile,
+            secret: true,
+        });
+    }
+    else {
+        notes.push(`${keyFile} already holds this agent's key — left untouched.`);
+    }
+    // ── 2. OpenClaw: the one runtime governed purely by a config file, so the one
+    // this command can finish end to end.
+    const openclawConfigFile = path.join(home, ...OPENCLAW_CONFIG_REL);
+    if (exists(openclawConfigFile) || exists(home, ".openclaw")) {
+        found.push("OpenClaw");
+        if (wanted("openclaw")) {
+            if (!noInstall) {
+                if (hasExecutable("openclaw")) {
+                    steps.push({ kind: "exec", label: `Install ${OPENCLAW_PKG}`, command: "openclaw", args: ["plugins", "install", OPENCLAW_PKG] });
+                }
+                else {
+                    steps.push({
+                        kind: "manual",
+                        label: "Install the OpenClaw plugin",
+                        detail: "The `openclaw` command is not on this machine's PATH, so the plugin cannot be installed for you. Run this wherever the OpenClaw CLI lives:",
+                        snippet: `openclaw plugins install ${OPENCLAW_PKG}`,
+                    });
+                }
+            }
+            const raw = readTextFile(openclawConfigFile);
+            if (raw !== null && isJsonc(raw)) {
+                // Rewriting this would delete the owner's comments. Print instead.
+                steps.push({
+                    kind: "manual",
+                    label: `Enable the plugin in ${openclawConfigFile}`,
+                    detail: "That file uses comments or trailing commas, and rewriting it as strict JSON would delete them. Merge this into the existing `plugins` object by hand — keep any other plugins already in `allow` and `entries`:",
+                    snippet: JSON.stringify(mergeOpenclawConfig((jsonc.parse(raw, [], { allowTrailingComma: true, disallowComments: false }) ?? {}), home), null, 2),
+                });
+            }
+            else {
+                let current = {};
+                if (raw !== null) {
+                    try {
+                        const parsed = JSON.parse(raw);
+                        if (isRecord(parsed))
+                            current = parsed;
+                    }
+                    catch {
+                        notes.push(`${openclawConfigFile} is not valid JSON — it will be backed up and rewritten from scratch, which loses whatever was in it. Fix the file first if it holds configuration you need.`);
+                    }
+                }
+                const after = JSON.stringify(mergeOpenclawConfig(current, home), null, 2) + "\n";
+                if (raw !== after) {
+                    steps.push({
+                        kind: "write",
+                        label: raw === null
+                            ? "Create ~/.openclaw/openclaw.json with the plugin enabled"
+                            : "Enable the plugin in ~/.openclaw/openclaw.json (a merge — existing plugins are kept)",
+                        file: openclawConfigFile,
+                        before: raw,
+                        after,
+                    });
+                }
+                else {
+                    notes.push(`${openclawConfigFile} already has the plugin enabled — left untouched.`);
+                }
+            }
+            notes.push("Restart the OpenClaw gateway. The hook is registered at startup, so the plugin does nothing until it restarts.");
+        }
+    }
+    // ── 3. Hermes: not a runtime that merely lacks a plugin. It runs the SAME
+    // agent, reads the same skills and the same key — but the Atbash hook lives in
+    // the OpenClaw gateway, so anything driven through the Hermes API is never
+    // judged. Setup places the key file and says so; it does not pretend to wire it.
+    if (exists(home, ...HERMES_AGENT_REL)) {
+        found.push("Hermes");
+        notes.push("Hermes is installed here. It shares this agent's skills and signing key, but the Atbash hook lives in the OpenClaw gateway — actions driven through the Hermes API are NOT judged, even while the OpenClaw side reports enforcing. Route that work through OpenClaw, or guard it in code with @atbash/sdk.");
+    }
+    // ── 4. MCP clients: detected and reported, never seeded.
+    // The documented @atbash/mcp wiring carries the private key as an
+    // ATBASH_AGENT_PRIVKEY env value inside the client's own config file, and that
+    // package has no key-file fallback (checked against the published 0.1.3). We
+    // will not write a private key into a file people share and sync, so this is
+    // the one place setup deliberately stays manual.
+    const mcpClients = [];
+    const seenClients = new Set();
+    for (const { label, segs } of connect_1.MCP_CONFIGS) {
+        if (seenClients.has(label))
+            continue;
+        if (exists(home, ...segs)) {
+            seenClients.add(label);
+            mcpClients.push(`${label} (${path.join(home, ...segs)})`);
+        }
+    }
+    // Claude Code and Codex live outside MCP_CONFIGS in the scanner too — same paths.
+    if (exists(home, ".claude.json"))
+        mcpClients.push(`Claude Code (${path.join(home, ".claude.json")})`);
+    if (exists(home, ".codex", "config.toml"))
+        mcpClients.push(`Codex (${path.join(home, ".codex", "config.toml")})`);
+    if (mcpClients.length) {
+        found.push(`${mcpClients.length} MCP client config${mcpClients.length === 1 ? "" : "s"}`);
+        steps.push({
+            kind: "manual",
+            label: `Optional: expose Atbash as an MCP server to ${mcpClients.length} detected client${mcpClients.length === 1 ? "" : "s"}`,
+            detail: [
+                `Detected: ${mcpClients.join(", ")}.`,
+                "",
+                "This step is NOT done for you, on purpose. The published @atbash/mcp wiring takes the agent's private key as an ATBASH_AGENT_PRIVKEY value inside the client's own config file, and that package has no key-file fallback today. Atbash will not write your private key into a file that gets synced, shared and screenshotted.",
+                "",
+                "If you want it anyway, add this yourself and fill in the key — and treat that config file as a secret from then on:",
+            ].join("\n"),
+            snippet: JSON.stringify({
+                mcpServers: {
+                    atbash: { command: "npx", args: ["-y", "@atbash/mcp"], env: { ATBASH_AGENT_PRIVKEY: "<your agent private key>" } },
+                },
+            }, null, 2),
+        });
+    }
+    if (!found.length) {
+        notes.push("No OpenClaw, Hermes or MCP client configuration was found under this home directory. The key file is still placed, so an SDK-level integration in your own code will find it — but nothing on this machine is wired to a runtime.");
+    }
+    return { steps, notes, found };
+}
+// ── Showing the plan ────────────────────────────────────────────────────────
+/**
+ * A minimal line diff, so the preview shows what CHANGES rather than dumping a
+ * whole config and leaving the owner to spot the difference. Standard LCS; these
+ * files are small enough that the quadratic table is irrelevant.
+ */
+function lineDiff(before, after) {
+    const a = before.split("\n");
+    const b = after.split("\n");
+    const table = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            out.push(`  ${a[i]}`);
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            out.push(`- ${a[i]}`);
+            i++;
+        }
+        else {
+            out.push(`+ ${b[j]}`);
+            j++;
+        }
+    }
+    for (; i < a.length; i++)
+        out.push(`- ${a[i]}`);
+    for (; j < b.length; j++)
+        out.push(`+ ${b[j]}`);
+    return out;
+}
+/** Drop unchanged runs down to a little context, so a long config stays readable. */
+function condense(diff, context = 2) {
+    const keep = new Set();
+    diff.forEach((line, index) => {
+        if (line.startsWith("+") || line.startsWith("-")) {
+            for (let k = index - context; k <= index + context; k++)
+                if (k >= 0 && k < diff.length)
+                    keep.add(k);
+        }
+    });
+    const out = [];
+    let skipping = false;
+    diff.forEach((line, index) => {
+        if (keep.has(index)) {
+            out.push(line);
+            skipping = false;
+        }
+        else if (!skipping) {
+            out.push(chalk_1.default.dim("  …"));
+            skipping = true;
+        }
+    });
+    return out;
+}
+/**
+ * Print the plan. Used for `--dry-run` and for the confirmation prompt, so what
+ * the owner is shown and what they agree to cannot diverge.
+ *
+ * The key file's CONTENTS are never printed — the whole point of the file is that
+ * the private key stays put, and echoing it into a terminal scrollback undoes
+ * that. The path, mode and the public key are shown instead.
+ */
+function renderPlan(plan, pubkey) {
+    console.log();
+    console.log(chalk_1.default.bold("  Atbash setup"));
+    console.log(chalk_1.default.dim(`  Agent public key: ${pubkey}`));
+    console.log(chalk_1.default.dim(`  Detected on this machine: ${plan.found.length ? plan.found.join(", ") : "no supported runtime"}`));
+    console.log();
+    const writes = plan.steps.filter((s) => s.kind === "write");
+    const execs = plan.steps.filter((s) => s.kind === "exec");
+    const manuals = plan.steps.filter((s) => s.kind === "manual");
+    if (!writes.length && !execs.length) {
+        console.log(chalk_1.default.green("  Nothing to change — this machine is already wired.") + "\n");
+    }
+    if (writes.length) {
+        console.log(chalk_1.default.bold(`  Files (${writes.length})`));
+        for (const step of writes) {
+            console.log(`   ${chalk_1.default.cyan(step.file)}${step.mode ? chalk_1.default.dim(`  mode ${step.mode.toString(8)}`) : ""}`);
+            console.log(`     ${step.label}`);
+            if (step.secret) {
+                // Deliberately not the contents.
+                console.log(chalk_1.default.dim(`     Contents: pubkey= and privkey= lines for the agent above. Not printed — it is a private key.`));
+            }
+            else if (step.before === null) {
+                for (const line of step.after.split("\n").slice(0, 40))
+                    console.log(chalk_1.default.dim(`     + ${line}`));
+                if (step.after.split("\n").length > 40)
+                    console.log(chalk_1.default.dim("     …"));
+            }
+            else {
+                for (const line of condense(lineDiff(step.before, step.after))) {
+                    const painted = line.startsWith("+") ? chalk_1.default.green(line) : line.startsWith("-") ? chalk_1.default.red(line) : chalk_1.default.dim(line);
+                    console.log(`     ${painted}`);
+                }
+            }
+            if (step.before !== null)
+                console.log(chalk_1.default.dim("     The existing file is copied to a .atbash-bak alongside it first."));
+            console.log();
+        }
+    }
+    if (execs.length) {
+        console.log(chalk_1.default.bold(`  Commands (${execs.length})`));
+        for (const step of execs)
+            console.log(`   ${chalk_1.default.cyan(`${step.command} ${step.args.join(" ")}`)}\n     ${step.label}`);
+        console.log();
+    }
+    if (manuals.length) {
+        console.log(chalk_1.default.bold(`  For you to do (${manuals.length})`));
+        for (const step of manuals) {
+            console.log(`   ${chalk_1.default.yellow("•")} ${chalk_1.default.bold(step.label)}`);
+            for (const line of step.detail.split("\n"))
+                console.log(`     ${chalk_1.default.dim(line)}`);
+            if (step.snippet)
+                for (const line of step.snippet.split("\n"))
+                    console.log(chalk_1.default.dim(`       ${line}`));
+            console.log();
+        }
+    }
+    if (plan.notes.length) {
+        console.log(chalk_1.default.bold("  Notes"));
+        for (const note of plan.notes)
+            console.log(`   ${chalk_1.default.dim("•")} ${chalk_1.default.dim(note)}`);
+        console.log();
+    }
+}
+// ── Doing it ────────────────────────────────────────────────────────────────
+/**
+ * Copy a file aside before overwriting it, without ever clobbering an existing
+ * backup — a second run must not overwrite the pristine copy from the first.
+ */
+function backupFile(file) {
+    if (!fs.existsSync(file))
+        return null;
+    let target = `${file}.atbash-bak`;
+    let n = 1;
+    while (fs.existsSync(target))
+        target = `${file}.atbash-bak.${n++}`;
+    fs.copyFileSync(file, target);
+    return target;
+}
+/** Execute the plan. Writes first, then commands, so a failed install still
+ *  leaves a correct config and key file behind for a manual retry. */
+function applyPlan(plan) {
+    const result = { written: [], backups: [], ran: [], failures: [] };
+    for (const step of plan.steps) {
+        if (step.kind !== "write")
+            continue;
+        try {
+            const backup = backupFile(step.file);
+            if (backup)
+                result.backups.push(backup);
+            fs.mkdirSync(path.dirname(step.file), { recursive: true, mode: step.mode === KEY_MODE ? DIR_MODE : undefined });
+            fs.writeFileSync(step.file, step.after, step.mode ? { mode: step.mode } : {});
+            // writeFileSync's mode is ignored for a file that already existed, so
+            // assert it explicitly — a key file at 0644 is the failure this guards.
+            if (step.mode)
+                fs.chmodSync(step.file, step.mode);
+            result.written.push(step.file);
+        }
+        catch (err) {
+            result.failures.push(`${step.file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    for (const step of plan.steps) {
+        if (step.kind !== "exec")
+            continue;
+        const label = `${step.command} ${step.args.join(" ")}`;
+        const run = (0, child_process_1.spawnSync)(step.command, step.args, { stdio: "inherit" });
+        if (run.status === 0)
+            result.ran.push(label);
+        else
+            result.failures.push(`${label} exited ${run.status ?? "on a signal"}`);
+    }
+    return result;
+}
+// ── Registration check ──────────────────────────────────────────────────────
+/**
+ * Confirm the agent this key belongs to is actually registered.
+ *
+ * Wiring a runtime to an unregistered agent produces the worst outcome available:
+ * a machine that looks governed, with a plugin that cannot get a verdict. The
+ * check sends only the PUBLIC key (GET /api/ai/exists), never the private one.
+ */
+async function verifyRegistration(privkey, endpoint) {
+    try {
+        const atbash = new sdk_1.Atbash(privkey, {
+            endpoint,
+            blockchainRid: (0, sdk_1.resolve)("blockchainRid") || undefined,
+            orgName: (0, sdk_1.resolve)("orgName") || undefined,
+        });
+        return (await atbash.checkAgentExists()) ? { state: "registered" } : { state: "unregistered" };
+    }
+    catch (err) {
+        return { state: "unknown", reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** y/N confirmation. Anything but an explicit yes is a no. */
+async function confirm(question) {
+    const { createInterface } = await Promise.resolve().then(() => __importStar(require("node:readline")));
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((r) => rl.question(question, (a) => { rl.close(); r(a); }));
+    return /^y(es)?$/i.test(answer.trim());
+}
+// ── The command ─────────────────────────────────────────────────────────────
+function registerSetupCommand(program) {
+    program
+        .command("setup")
+        .description("Wire this machine's runtime to a registered Atbash agent: place the agent key, install the plugin and merge its config (WRITES to your machine — use --dry-run first)")
+        .option("-k, --key <privkey>", "Agent private key (64 hex). Convenient, but it lands in your shell history — prefer the prompt or --key-file")
+        .option("--key-file <path>", "Read the key from a file (the agent-keys-*.txt from onboarding, or an existing guard-client-key)")
+        .option("--keys-dir <dir>", "Directory holding the key file, e.g. ~/Downloads")
+        .option("--host <url>", "Atbash deployment to check the agent's registration against")
+        .option("--runtime <ids...>", "Only configure these runtimes (currently: openclaw)")
+        .option("--dry-run", "Show exactly which files would change, and the diffs, then exit WITHOUT writing anything")
+        .option("-y, --yes", "Do not ask for confirmation before writing")
+        .option("--no-install", "Do not install any package; write the key file and configs only")
+        .option("--skip-verify", "Do not check the agent's registration (no network calls at all)")
+        .option("--allow-unrecognized-host", "Permit a --host that is not a known Atbash deployment")
+        .option("--home <dir>", "Home directory to configure (for testing)")
+        .action(async (opts) => {
+        const home = opts.home || process.env.HOME || os.homedir();
+        const dryRun = !!opts.dryRun;
+        // A key on argv is in the shell history and in `ps` output. Say so once,
+        // rather than silently accepting the convenient-but-leaky path.
+        if (opts.key) {
+            console.log(chalk_1.default.yellow("\n  Note: a key passed with --key is recorded in your shell history.") +
+                chalk_1.default.dim("\n  Clear it afterwards, or re-run without --key and paste it at the hidden prompt."));
+        }
+        const keySource = await resolveKeySource({
+            key: opts.key,
+            keyFile: opts.keyFile,
+            keysDir: opts.keysDir,
+            home,
+            allowPrompt: process.stdin.isTTY === true,
+        });
+        if ("error" in keySource) {
+            console.error(chalk_1.default.red(`\n${keySource.error}\n`));
+            process.exit(1);
+        }
+        const privkey = keySource.material.privkey;
+        const pubkey = (0, sdk_1.derivePublicKey)(privkey);
+        // A key file whose stated pubkey does not match the private key is either
+        // corrupt or two different keypairs spliced together. Either way, wiring a
+        // runtime with it produces signatures nobody can attribute.
+        const stated = keySource.material.statedPubkey?.replace(/^0x/i, "").toLowerCase();
+        if (stated && stated !== pubkey.toLowerCase()) {
+            console.error(chalk_1.default.red("\n  The key file's `pubkey` does not match the key derived from its `privkey`.") +
+                chalk_1.default.dim(`\n  File says:  ${stated}\n  Derived:    ${pubkey}\n  Fix the file (or re-download it) before wiring anything.\n`));
+            process.exit(1);
+        }
+        console.log(chalk_1.default.dim(`\n  Agent key source: ${keySource.from}`));
+        // ── Registration check. Only the public key crosses the network.
+        if (!opts.skipVerify) {
+            const endpoint = (opts.host || (0, sdk_1.resolve)("judgeEndpoint") || connect_1.DEFAULT_HOST || sdk_1.DEFAULT_ENDPOINT).replace(/\/$/, "");
+            let hostname = "";
+            try {
+                hostname = new URL(endpoint).hostname.toLowerCase();
+            }
+            catch {
+                console.error(chalk_1.default.red(`\n  --host is not a valid URL: ${endpoint}\n`));
+                process.exit(1);
+            }
+            // An unrecognized host could answer "registered" for any key, which is
+            // exactly the confirmation this check exists to provide. Exact hostname
+            // match, never a suffix — "atbash.ai.evil.com" must not pass.
+            if (!connect_1.KNOWN_HOSTS.has(hostname) && !opts.allowUnrecognizedHost) {
+                console.error(chalk_1.default.red(`\n  ${hostname} is not a recognized Atbash deployment.`) +
+                    chalk_1.default.dim("\n  Re-run with --allow-unrecognized-host if you meant to point at a self-hosted instance,\n  or with --skip-verify to configure this machine without any network call.\n"));
+                process.exit(1);
+            }
+            const verdict = await verifyRegistration(privkey, endpoint);
+            if (verdict.state === "unregistered") {
+                console.error(chalk_1.default.red("\n  That agent is not registered on this deployment.") +
+                    chalk_1.default.dim(`\n  Public key: ${pubkey}\n  Finish onboarding first — wiring a runtime to an unregistered agent leaves it\n  looking governed while the plugin can never get a verdict.\n`));
+                process.exit(1);
+            }
+            if (verdict.state === "unknown") {
+                console.log(chalk_1.default.yellow(`\n  Could not confirm the agent's registration (${verdict.reason}).`));
+                console.log(chalk_1.default.dim("  The wiring below is still correct, but nothing has verified that this agent exists."));
+                if (!opts.yes && !dryRun && process.stdin.isTTY && !(await confirm("  Continue anyway? [y/N] "))) {
+                    console.log(chalk_1.default.dim("\n  Nothing was changed.\n"));
+                    return;
+                }
+            }
+            else {
+                console.log(chalk_1.default.green(`  Agent is registered on ${hostname}.`));
+            }
+        }
+        // ── Plan, show, then (maybe) apply.
+        const plan = buildPlan({
+            home,
+            privkey,
+            pubkey,
+            noInstall: opts.install === false,
+            only: opts.runtime ?? [],
+        });
+        renderPlan(plan, pubkey);
+        const changes = plan.steps.filter((s) => s.kind === "write" || s.kind === "exec");
+        if (dryRun) {
+            console.log(chalk_1.default.green("  Dry run — nothing was written.") +
+                chalk_1.default.dim(" Re-run without --dry-run to apply.\n"));
+            return;
+        }
+        if (!changes.length) {
+            console.log(chalk_1.default.dim("  Nothing to apply.\n"));
+            return;
+        }
+        if (!opts.yes) {
+            if (!process.stdin.isTTY) {
+                console.error(chalk_1.default.red("  Refusing to write without confirmation.") +
+                    chalk_1.default.dim(" Re-run with --yes (or --dry-run to preview).\n"));
+                process.exit(1);
+            }
+            if (!(await confirm(`  Apply ${changes.length} change${changes.length === 1 ? "" : "s"} to this machine? [y/N] `))) {
+                console.log(chalk_1.default.dim("\n  Nothing was changed.\n"));
+                return;
+            }
+        }
+        const result = applyPlan(plan);
+        console.log();
+        for (const file of result.written)
+            console.log(chalk_1.default.green(`  ✓ wrote ${file}`));
+        for (const file of result.backups)
+            console.log(chalk_1.default.dim(`    backup: ${file}`));
+        for (const cmd of result.ran)
+            console.log(chalk_1.default.green(`  ✓ ran ${cmd}`));
+        for (const failure of result.failures)
+            console.log(chalk_1.default.red(`  ✗ ${failure}`));
+        if (result.failures.length) {
+            console.log(chalk_1.default.yellow("\n  Finished with failures — this machine is NOT fully wired.") +
+                chalk_1.default.dim("\n  Everything that did succeed is listed above; the steps that failed can be re-run.\n"));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(chalk_1.default.green("\n  Done.") + chalk_1.default.dim(" Restart the runtime so it loads the hook, then re-scan this machine"));
+        console.log(chalk_1.default.dim("  from the agent's page in the dashboard to confirm it reports as enforcing.\n"));
+    });
+}
+//# sourceMappingURL=setup.js.map