@atbash/cli 0.5.15-dev.6 → 0.5.15

package/dist/commands/mcp-cmd.js

@@ -1,216 +0,0 @@
-"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;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveLauncherKey = resolveLauncherKey;
-exports.registerMcpCommand = registerMcpCommand;
-const fs = __importStar(require("fs"));
-const child_process_1 = require("child_process");
-const sdk_1 = require("@atbash/sdk");
-/**
- * `atbash mcp` — run the Atbash MCP server without putting a private key in a
- * config file.
- *
- * THE PROBLEM THIS SOLVES
- *
- * `@atbash/mcp` reads its agent identity from `ATBASH_AGENT_PRIVKEY` and has no
- * key-file fallback (verified against the published 0.1.3). The documented wiring
- * therefore asks the operator to paste a raw private key into their MCP client's
- * own config:
- *
- *   { "mcpServers": { "atbash": { "command": "npx", "args": ["-y", "@atbash/mcp"],
- *                                 "env": { "ATBASH_AGENT_PRIVKEY": "<the key>" } } } }
- *
- * That file is `claude_desktop_config.json` and its equivalents — files people
- * sync between machines, paste into issues, and screenshot when asking for help.
- * It made "wire up MCP for me" impossible to automate honestly: the automation's
- * whole job would have been to plant a secret somewhere worse than where it
- * already was.
- *
- * This command is the indirection that removes the problem. The client spawns
- * `atbash mcp`, which reads the key from the 0600 file Atbash already manages and
- * passes it to the server through the CHILD PROCESS ENVIRONMENT ONLY. Nothing
- * secret is ever written to a config file, so the client entry is:
- *
- *   { "mcpServers": { "atbash": { "command": "npx", "args": ["-y", "@atbash/cli", "mcp"] } } }
- *
- * — which contains no credential at all, and is safe for `atbash setup` to write.
- *
- * STDOUT IS THE PROTOCOL. MCP speaks JSON-RPC over stdio, so a single stray
- * `console.log` here corrupts the stream and the client reports a broken server.
- * Every diagnostic in this file goes to stderr. Do not change that.
- */
-/**
- * The server this launcher runs, and the SDK it is run WITH.
- *
- * ⚠️ BOTH PINS ARE LOAD-BEARING. DO NOT LOOSEN THEM.
- *
- * `@atbash/mcp` declares `@atbash/sdk: ^0.3.19` and imports `getOrgTierInfo` as a
- * named export. `@atbash/sdk@0.3.24` REMOVED that export, so `^0.3.19` now
- * resolves to 0.3.25 and the server dies at import time:
- *
- *   SyntaxError: The requested module '@atbash/sdk' does not provide an
- *                export named 'getOrgTierInfo'
- *
- * That breaks EVERY published `@atbash/mcp` (0.1.0 through 0.1.3) — a plain
- * `npm install @atbash/mcp` cannot start at all, which is why the documented
- * hand-wiring produces a client reporting a failed server. Naming an SDK version
- * from before the removal is what makes it run; 0.3.23 is the newest that works.
- *
- * ⚠️ AND THE PIN ITSELF IS A STOPGAP. `@atbash/sdk@0.3.23` is DEPRECATED:
- *
- *   npm warn deprecated @atbash/sdk@0.3.23: Old architecture with legacy chain
- *   structure. Please upgrade to stable version @atbash/sdk@^0.5.0
- *
- * So this runs the MCP server on a legacy chain architecture. It is verified to
- * work — a real `atbash_check_agent` tool call round-trips against the live
- * deployment and returns the correct answer — but it is the newest thing that
- * works, not a thing that is right.
- *
- * THE REAL FIX is republishing `@atbash/mcp` against `@atbash/sdk@^0.7`, which
- * moves `getOrgTierInfo` onto the `Atbash` class rather than exporting it. Until
- * that ships, this pin is the only thing between an operator and a dead MCP
- * server, so treat a "dependency update" here as a regression unless the
- * republished package is verified to both START and serve a tool call.
- *
- * Cold start is ~12s while npx populates its cache, ~1s warm. A client with a
- * short startup timeout may fail its very first launch and succeed on retry.
- */
-const MCP_PKG = "@atbash/mcp";
-const MCP_VERSION = "0.1.3";
-const MCP_SDK_VERSION = "0.3.23";
-/** Read `privkey=` out of the agent key file, or null if it is not usable. */
-function privkeyFromKeyFile(keyPath) {
-    let text;
-    try {
-        text = fs.readFileSync(keyPath, "utf8");
-    }
-    catch {
-        return null;
-    }
-    if (text.trim().startsWith("{")) {
-        try {
-            const o = JSON.parse(text);
-            const value = String(o.privKey ?? o.privkey ?? o.privateKey ?? "").replace(/^0x/i, "").trim();
-            return /^[0-9a-fA-F]{64}$/.test(value) ? value.toLowerCase() : null;
-        }
-        catch {
-            return null;
-        }
-    }
-    for (const line of text.split(/\r?\n/)) {
-        const match = line.trim().match(/^privkey\s*[:=]\s*(.+)$/i);
-        if (match) {
-            const value = match[1].replace(/^0x/i, "").trim();
-            if (/^[0-9a-fA-F]{64}$/.test(value))
-                return value.toLowerCase();
-        }
-    }
-    return null;
-}
-/**
- * Where the launcher gets the key, in order.
- *
- * An `ATBASH_AGENT_PRIVKEY` already in the environment wins, so an operator who
- * deliberately injects the key at launch time keeps working exactly as before —
- * this command adds a safer default, it does not take the existing path away.
- */
-function resolveLauncherKey(keyPathOverride) {
-    const fromEnv = process.env.ATBASH_AGENT_PRIVKEY?.replace(/^0x/i, "").trim();
-    if (fromEnv && /^[0-9a-fA-F]{64}$/.test(fromEnv))
-        return { privkey: fromEnv.toLowerCase(), from: "ATBASH_AGENT_PRIVKEY" };
-    const keyPath = (0, sdk_1.resolveKeyPath)(keyPathOverride);
-    const fromFile = privkeyFromKeyFile(keyPath);
-    if (fromFile)
-        return { privkey: fromFile, from: keyPath };
-    const fromConfig = (0, sdk_1.loadUserConfig)().agentKey?.replace(/^0x/i, "").trim();
-    if (fromConfig && /^[0-9a-fA-F]{64}$/.test(fromConfig))
-        return { privkey: fromConfig.toLowerCase(), from: "atbash config" };
-    return null;
-}
-function registerMcpCommand(program) {
-    program
-        .command("mcp")
-        .description("Run the Atbash MCP server, reading the agent key from ~/.config/atbash/guard-client-key instead of a config file (used as the `command` in an MCP client's server list)")
-        .option("--key-file <path>", "Agent key file to read (default: ~/.config/atbash/guard-client-key)")
-        .option("--endpoint <url>", "Atbash endpoint the server should use")
-        .action((opts) => {
-        const resolved = resolveLauncherKey(opts.keyFile);
-        if (!resolved) {
-            // stderr: stdout belongs to the JSON-RPC stream.
-            process.stderr.write("atbash mcp: no agent key found.\n" +
-                `Looked at ATBASH_AGENT_PRIVKEY, ${(0, sdk_1.resolveKeyPath)(opts.keyFile)}, and the atbash config.\n` +
-                "Run `atbash setup` on this machine first, or pass --key-file.\n");
-            process.exit(1);
-        }
-        const endpoint = opts.endpoint || process.env.ATBASH_ENDPOINT;
-        // The key goes to the CHILD ONLY. It is never written to disk here and
-        // never echoed — the parent's own environment is left untouched.
-        const env = {
-            ...process.env,
-            ATBASH_AGENT_PRIVKEY: resolved.privkey,
-            ...(endpoint ? { ATBASH_ENDPOINT: endpoint } : {}),
-        };
-        // Both packages are placed in ONE npx tree so the compatible SDK sits at its
-        // root and satisfies @atbash/mcp's own `^0.3.19` range — which is what stops
-        // npm installing the broken 0.3.25 underneath it. Installing @atbash/mcp
-        // alone (as a dependency of this CLI, or via a bare npx) reintroduces the
-        // crash, so this shape is deliberate, not incidental.
-        const command = "npx";
-        const args = [
-            "--yes",
-            "-p", `${MCP_PKG}@${MCP_VERSION}`,
-            "-p", `@atbash/sdk@${MCP_SDK_VERSION}`,
-            "atbash-mcp",
-        ];
-        process.stderr.write(`atbash mcp: starting ${MCP_PKG}@${MCP_VERSION} with @atbash/sdk@${MCP_SDK_VERSION} (key from ${resolved.from})\n`);
-        // stdio inherit: the server talks JSON-RPC directly to the client that
-        // spawned us. Proxying it through here would add a failure point for no gain.
-        const child = (0, child_process_1.spawn)(command, args, { env, stdio: "inherit", shell: false });
-        child.on("error", (err) => {
-            process.stderr.write(`atbash mcp: could not start ${MCP_PKG}: ${err.message}\n`);
-            process.exit(1);
-        });
-        // Forward termination so the client's own shutdown reaches the server
-        // rather than orphaning it.
-        for (const signal of ["SIGINT", "SIGTERM"]) {
-            process.on(signal, () => { if (!child.killed)
-                child.kill(signal); });
-        }
-        child.on("exit", (code, signal) => {
-            process.exit(signal ? 1 : (code ?? 0));
-        });
-    });
-}
-//# sourceMappingURL=mcp-cmd.js.map

package/dist/commands/mcp-cmd.js.map

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

package/dist/commands/setup.d.ts

@@ -1,359 +0,0 @@
-import { Command } from "commander";
-interface KeyMaterial {
-    privkey: string;
-    /** Present when the source stated one; always re-derived and cross-checked. */
-    statedPubkey?: string;
-}
-/**
- * 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.
- */
-export declare function parseKeyMaterial(raw: string): KeyMaterial | null;
-/** Normalize to the lowercase 64-hex the SDK validates, or "" if it is not one. */
-export declare function normalizePrivkey(raw: string): string;
-/**
- * Files in a directory that plausibly hold an Atbash agent key, newest first.
- *
- * TWO PASSES, and the second one is the point.
- *
- * By name first — `guard-client-key`, `agent-keys-*.txt` and friends — because
- * matching the name is cheap and unambiguous. But a name-only match is a cliff:
- * rename the download, or export from a wallet UI that picks its own filename,
- * and the operator gets "no key file found" while the key sits right there in the
- * directory they explicitly pointed at.
- *
- * So if no name matches, read the small files and keep the ones that actually
- * PARSE as key material. That is a narrow test — `privkey=`, the documented JSON
- * shape, or a file that is nothing but a 64-hex key — not "contains something
- * hex-looking", so an unrelated file does not get mistaken for an identity.
- *
- * Reading files the operator did not name individually is justified by the flag
- * itself: `--keys-dir` is an explicit instruction to look in that directory. It
- * is bounded to small regular files and a file count, nothing is transmitted, and
- * the caller prints WHICH file it used before doing anything with it.
- */
-export declare function keyCandidatesInDir(dir: string): string[];
-interface KeySource {
-    material: KeyMaterial;
-    /** Human description of WHERE it came from. Never contains the key. */
-    from: string;
-}
-/**
- * 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.
- */
-export declare function resolveKeySource(opts: {
-    key?: string;
-    keyFile?: string;
-    keysDir?: string;
-    home: string;
-    /** Set for non-interactive runs (CI, an AI assistant with no TTY). */
-    allowPrompt: boolean;
-}): Promise<KeySource | {
-    error: string;
-}>;
-/**
- * One thing setup will do. Building the whole plan BEFORE touching anything is
- * what makes `--dry-run` truthful: the preview and the run are the same objects,
- * so the preview cannot describe a merge the apply step then performs
- * differently. Every `write` carries its exact final bytes.
- */
-export type Step = {
-    kind: "write";
-    label: string;
-    file: string;
-    mode?: number;
-    before: string | null;
-    after: string;
-    secret?: boolean;
-} | {
-    kind: "exec";
-    label: string;
-    command: string;
-    args: string[];
-    optionalWhy?: string;
-} | {
-    kind: "manual";
-    label: string;
-    detail: string;
-    snippet?: string;
-};
-export interface Plan {
-    steps: Step[];
-    /** Things the owner must know, printed whether or not anything was written. */
-    notes: string[];
-    /** Runtimes found on this machine, for the summary line. */
-    found: string[];
-}
-/** The key file, in the `key=value` form the plugin and the SDK both parse. */
-export declare function keyFileContents(privkey: string, pubkey: string): string;
-/**
- * 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.
- */
-export declare function isJsonc(text: string): boolean;
-/**
- * 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.
- */
-export declare function mergeOpenclawConfig(config: Record<string, unknown>, home: string): Record<string, unknown>;
-/**
- * Detect the indentation a JSON file already uses, so a merge does not reformat
- * the parts it did not touch.
- *
- * Without this, `JSON.stringify(obj, null, 2)` re-indents a tab-indented or
- * 4-space config from top to bottom. The RESULT is still correct, but the diff
- * shown for approval becomes every line in the file, which buries the two lines
- * that actually changed — and the operator's own formatting choice is collateral
- * damage in a file we were asked to make one addition to.
- *
- * Falls back to two spaces, which is what the published docs show.
- */
-export declare function detectIndent(text: string | null): string | number;
-/**
- * Serialize a merged config the way the file was already written: same
- * indentation, and a trailing newline only if the original had one.
- */
-export declare function serializeLike(original: string | null, value: unknown): string;
-interface McpClient {
-    label: string;
-    file: string;
-    format: "json" | "toml";
-    /** Which key holds the server map — VS Code and some others use `servers`. */
-    serversKey: "mcpServers" | "servers";
-}
-/**
- * MCP client configs present under this home directory.
- *
- * Paths come from the shared MCP_CONFIGS so the writer and the scanner cannot
- * drift: a client the scan reports but setup cannot find would look like a bug in
- * whichever of the two the operator happened to trust.
- */
-export declare function detectMcpClients(home: string): McpClient[];
-/**
- * Find the Python interpreter that actually runs Hermes.
- *
- * This is the difference between installing the plugin and only appearing to.
- * `pip install atbash-hermes-plugin` puts the package wherever the *shell's*
- * `pip` points — commonly a system or conda Python — while Hermes typically runs
- * from its own virtualenv. The install succeeds, prints nothing alarming, and the
- * plugin is invisible to Hermes forever. Nobody can debug that from the output.
- *
- * The launcher knows the answer. A pip-installed console script begins with a
- * shebang naming the interpreter that created it:
- *
- *   $ head -1 $(command -v hermes)
- *   #!/Users/me/.hermes/hermes-agent/venv/bin/python3
- *
- * So resolve `hermes`, read its first line, and use that interpreter directly via
- * `-m pip`. Falls back to the conventional venv location under ~/.hermes, then to
- * null — and a null becomes a printed command rather than a guess, because a
- * wrong guess here is the silent failure this whole function exists to avoid.
- */
-export declare function findHermesPython(home: string): {
-    python: string;
-    how: string;
-} | null;
-/** Same rule as buildPlan's `wanted`: an empty --runtime list means everything. */
-export declare function wantedRuntime(id: string, only: string[]): boolean;
-/**
- * Add the plugin to Hermes' opt-in allow-list at `plugins.enabled` in
- * `~/.hermes/config.yaml`.
- *
- * WHY NOT `hermes plugins enable`: that command cannot accept this plugin, on
- * this version, ever. `_plugin_exists` (hermes_cli/plugins_cmd.py) looks only for
- * a DIRECTORY in the user plugins dir or a bundled dir — it never consults entry
- * points. Meanwhile the runtime loader (`plugins.py:_scan_entry_points`) does
- * discover them. So Hermes will happily LOAD a pip-installed plugin but refuses
- * to put one on the allow-list it requires, and since plugins are opt-in, a
- * package that cannot get onto the list can never load. Running that command
- * exits 1 with "not installed or bundled". Writing the list entry directly is the
- * only route that works.
- *
- * A LINE MERGE, not a parse-and-reserialize. config.yaml is tens of kilobytes of
- * heavily commented configuration; round-tripping it through a YAML emitter would
- * strip every comment and reflow the file. So this inserts the one line needed and
- * leaves every other byte alone — the same discipline as the .env merge.
- */
-export declare function mergeHermesEnabledPlugins(existing: string | null, plugin?: string): string;
-/**
- * Whether Hermes has actually picked the plugin up.
- *
- * Installing the package is NOT the same as governing the agent. Hermes requires
- * plugins to be enabled explicitly — a real run installed `atbash-hermes-plugin`
- * into the right interpreter, with the right `hermes_agent.plugins` entry point,
- * and `hermes plugins list` still showed only the bundled plugins, all "not
- * enabled". The machine looked wired and enforced nothing, which is the exact
- * failure this command exists to prevent.
- *
- * Parsing a rendered table is inherently fragile, so an unreadable result is
- * reported as "unknown" and treated as "probably needs enabling" rather than as
- * success. Claiming enforcement we have not observed is the one wrong answer.
- */
-export type HermesPluginState = "configured" | "not-enabled" | "not-installed" | "unknown";
-/**
- * Is a Hermes gateway service running, and therefore restartable?
- *
- * "Restart Hermes" only means something when there is a service to bounce.
- * Hermes has two shapes: `hermes` starts an interactive chat session, and
- * `hermes gateway install` registers a launchd/systemd background service. A
- * setup command must not conflate them —
- *
- *  - with a service running, `hermes gateway restart` picks up the new config and
- *    is worth doing for the operator;
- *  - without one, there is nothing to restart. The plugin loads the next time
- *    they run `hermes`, and anything we "restarted" would either be a no-op or,
- *    worse, an interactive session someone is in the middle of using.
- *
- * `gateway status` exits 0 either way, so the state comes from its text.
- */
-export declare function hermesGatewayRunning(): boolean;
-/**
- * Is Hermes CONFIGURED to load the plugin?
- *
- * This used to shell out to `hermes plugins list` and look for an atbash row —
- * a signal that can never be true. `_discover_all_plugins` (plugins_cmd.py) walks
- * plugin DIRECTORIES only: bundled, user, project. It never scans entry points,
- * exactly like the `_plugin_exists` gate behind `plugins enable`. So a
- * pip-installed plugin is invisible to both, and the check reported "not picked
- * up" while everything was in fact correct — then told the operator to run the
- * enable command that cannot work. Advising a known-impossible fix is worse than
- * saying nothing.
- *
- * The two facts that actually decide it are both on disk:
- *
- *   1. the package is importable by the interpreter that runs Hermes, and
- *   2. its name is on the `plugins.enabled` allow-list in config.yaml, which is
- *      what the RUNTIME loader (`plugins.py:_scan_entry_points`) honours.
- *
- * "configured" is as far as a setup command can honestly go. Proof of loading is
- * a line in the agent log after Hermes next starts, which is why the caller points
- * at that rather than claiming enforcement.
- */
-export declare function hermesPluginState(home: string): HermesPluginState;
-/**
- * How to install a Python package into a specific interpreter on THIS machine.
- *
- * `<python> -m pip install` is the obvious answer and it is frequently wrong: a
- * venv created by `uv venv` has no pip at all (that is uv's default), so the
- * command fails with
- *
- *   /path/venv/bin/python3: No module named pip
- *
- * after setup has already written every config file — which is exactly what
- * happened on a real Hermes box. So probe, in order of what suits the venv:
- *
- *  1. `uv pip install --python <python>` when uv is present. Correct for a
- *     uv-created venv and fast; uv is also what created most pip-less venvs.
- *  2. `<python> -m pip install` when pip actually answers.
- *  3. Neither — hand it over, with `ensurepip` named, rather than planning a
- *     command that is known in advance to fail.
- */
-export declare function pythonInstallStrategy(python: string, pkg: string): {
-    kind: "exec";
-    command: string;
-    args: string[];
-    how: string;
-} | {
-    kind: "manual";
-    why: string;
-    snippet: string;
-};
-/**
- * The env vars the Hermes plugin documents, merged into an existing `.env`.
- *
- * A `.env` is line-oriented and hand-maintained, so this is a line merge rather
- * than a parse-and-reserialize: keys Atbash owns are replaced in place (keeping
- * their position), keys it does not own are never touched, and anything else in
- * the file — comments, blank lines, unrelated settings, ordering — survives
- * exactly as written. Reformatting someone's .env to add four lines would be a
- * poor trade.
- *
- * Values are from the published plugin README (PyPI atbash-hermes-plugin 0.4.5).
- * `ATBASH_ORG_NAME` is deliberately NOT written: its value is the operator's org,
- * which this command has no reliable way to know, and a wrong org sends the SDK
- * at the wrong chain. It is called out in the manual step instead.
- */
-export declare function mergeHermesEnv(existing: string | null): string;
-/**
- * Does this config's existing Atbash entry carry a key in its `env` block?
- *
- * True means the operator hand-wired it from the published docs and their private
- * key is sitting in that file today. Setup takes it out, but the backup it writes
- * first still has it — so this exists to make that sayable rather than silently
- * relocating the leak.
- */
-export declare function hadInlineKey(config: Record<string, unknown>, serversKey?: "mcpServers" | "servers"): boolean;
-export declare function mergeMcpServer(config: Record<string, unknown>, serversKey?: "mcpServers" | "servers"): Record<string, unknown>;
-/**
- * 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.
- */
-export declare function buildPlan(args: {
-    home: string;
-    privkey: string;
-    pubkey: string;
-    /** Skip package installation; write config and the key file only. */
-    noInstall: boolean;
-    /** Restrict to these runtime ids; empty means "everything detected". */
-    only: string[];
-}): 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.
- */
-export declare function lineDiff(before: string, after: string): string[];
-/**
- * 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.
- */
-export declare function renderPlan(plan: Plan, pubkey: string): void;
-/**
- * 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.
- */
-export declare function backupFile(file: string): string | null;
-export interface ApplyResult {
-    written: string[];
-    backups: string[];
-    ran: string[];
-    failures: string[];
-}
-/** Execute the plan. Writes first, then commands, so a failed install still
- *  leaves a correct config and key file behind for a manual retry. */
-export declare function applyPlan(plan: Plan): ApplyResult;
-export declare function registerSetupCommand(program: Command): void;
-export {};