@atbash/cli 0.6.0-dev.1 → 0.6.1-dev.2

package/dist/commands/setup.d.ts

@@ -20,7 +20,27 @@ interface KeyMaterial {
 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. */
+/**
+ * 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;
@@ -58,12 +78,72 @@ export type Step = {
     before: string | null;
     after: string;
     secret?: boolean;
+    /**
+     * Id of an `exec` step this write DEPENDS ON. The write is skipped entirely
+     * when that step did not succeed.
+     *
+     * ⚠️ This exists because the order used to be the other way round, on a
+     * rationale that reads convincingly and is wrong: "writes first, then
+     * commands, so a failed install still leaves a correct config behind for a
+     * manual retry". A plugin config with no plugin is not a head start — it is
+     * a DANGLING REFERENCE, and OpenClaw treats it as one:
+     *
+     *   plugins.entries.atbash-openclaw: plugin not found: atbash-openclaw
+     *   (stale config entry ignored; remove it from plugins config)
+     *   → Run "openclaw doctor --fix" to remove stale plugin ids
+     *
+     * So the leftover config is not merely useless: OpenClaw's own repair
+     * command offers to DELETE it, and an operator who accepts silently
+     * un-governs the agent. On 2026.2.x it was worse still — an entry naming an
+     * absent plugin contributed to the config being refused, which took down
+     * the very `plugins install` that would have created it.
+     *
+     * Not writing is strictly better than writing-then-rolling-back: there is
+     * no window in which a broken state exists on disk at all.
+     */
+    requires?: string;
+    /**
+     * Apply this write by handing the change to the runtime instead of writing
+     * the file ourselves.
+     *
+     * `payload` is piped to `command args` on stdin. Used for
+     * `openclaw config patch --stdin`, which merges recursively and validates
+     * in ONE write — so OpenClaw owns its own file format, key names, schema,
+     * comments, permissions and migrations. Every bug in this thread came from
+     * us asserting that shape from outside.
+     *
+     * It also closes a hazard we cannot otherwise handle: OpenClaw rewrites
+     * `openclaw.json` on its own (a machine in the field carried three
+     * `openclaw.json.clobbered.<timestamp>` files plus an
+     * `openclaw.json.last-good`), so anything we hand-merge can be discarded
+     * without warning. A patch describes INTENT and survives that.
+     *
+     * `before`/`after` are still computed so `--dry-run` shows a real diff —
+     * the preview stays ours, only the application moves.
+     */
+    applyVia?: {
+        command: string;
+        args: string[];
+        payload: string;
+        /**
+         * Extra environment for the child.
+         *
+         * ⚠️ REQUIRED IN PRACTICE, not a nicety. `openclaw config patch` edits
+         * whatever config OpenClaw considers active, which is NOT necessarily
+         * `step.file` — so without pinning `OPENCLAW_CONFIG_PATH` to the file this
+         * step names, a `--home <fixture>` run would patch the operator's REAL
+         * `~/.openclaw/openclaw.json`. A step must only ever change the file it
+         * declares; that is what makes the plan an honest preview.
+         */
+        env?: Record<string, string>;
+    };
 } | {
     kind: "exec";
     label: string;
     command: string;
     args: string[];
     optionalWhy?: string;
+    id?: string;
 } | {
     kind: "manual";
     label: string;
@@ -92,15 +172,269 @@ export declare function isJsonc(text: string): boolean;
  *
  * 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.
+ * preserved.
+ *
+ * WHICH entry is governed depends on what is being installed. When this run
+ * installs `@atbash/atbash-openclaw` — every run that is not `--no-install` —
+ * the plugin that ends up on disk registers as `atbash-openclaw`, so that is the
+ * entry that gets the config, and a legacy `atbash-plugin` entry is STOOD DOWN
+ * rather than configured. Only a `--no-install` run on a box whose sole entry is
+ * the legacy one keeps writing to the legacy key: there, nothing is arriving to
+ * replace it, and switching it off would leave the machine unguarded.
  *
  * `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>;
+/**
+ * WHICH entry this run governs, and whether a legacy one is being stood down.
+ *
+ * Extracted so the hand-merge and the `openclaw config patch` payload cannot
+ * disagree. Two implementations of this decision is exactly how a build ended up
+ * writing the modern plugin's `orgName` onto the LEGACY entry — whose schema is
+ * closed and has no such field — so OpenClaw rejected the whole file and the run
+ * broke its own install step.
+ *
+ * An entry is not the only way the legacy plugin is present: `plugins.installs`
+ * records it independently, and an installed, allowed plugin loads with its
+ * defaults whether or not anyone wrote an entry for it.
+ */
+export declare function openclawEntryDecision(config: Record<string, unknown>, opts?: {
+    installsModern?: boolean;
+}): {
+    entryKey: string;
+    useLegacy: boolean;
+    legacy: boolean;
+    standDownLegacy: boolean;
+};
+export declare function mergeOpenclawConfig(config: Record<string, unknown>, home: string, orgName?: string, opts?: {
+    installsModern?: boolean;
+    hooksSupported?: boolean;
+}): Record<string, unknown>;
+export declare function openclawInstallState(home: string, spec: string): {
+    installed: boolean;
+    sameSpec: boolean;
+    version?: string;
+};
+/**
+ * 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>;
+/**
+ * The change we want, expressed as a PATCH rather than a whole file.
+ *
+ * `openclaw config patch` merges objects recursively and validates in one write,
+ * so this is intent — "this entry should exist and look like this" — instead of
+ * "here are the complete new bytes of your config". That difference is what makes
+ * it survive the things that kept defeating us from outside: OpenClaw's own
+ * format changes, key renames, comment preservation, file permissions, its
+ * migrations, and the fact that it rewrites `openclaw.json` on its own (a machine
+ * in the field carried three `openclaw.json.clobbered.<timestamp>` files).
+ *
+ * ⚠️ DO NOT call `config patch --dry-run` from buildPlan to preview this. It is
+ * NOT side-effect free: running it triggers OpenClaw's state migrations, which
+ * wrote `~/.openclaw/update-check.json.migrated` and moved config-health state
+ * into SQLite on the machine this was developed on. `atbash setup --dry-run`
+ * promises that nothing is written, and that promise has to hold for OpenClaw's
+ * housekeeping too. The preview stays a merge we compute ourselves.
+ */
+export declare function openclawPatchPayload(args: {
+    entryKey: string;
+    orgName?: string;
+    keyPath: string;
+    /** Switch the legacy entry off in the same patch, when one is live. */
+    standDownLegacy: boolean;
+    /**
+     * Whether this build accepts `hooks` on an entry. Only then is the
+     * prompt-mutation denial included — on a build that does not know the key it
+     * is fatal, and `config patch` would rightly refuse the whole patch.
+     */
+    hooksSupported?: boolean;
+}): string;
 /**
  * Work out everything that needs doing on this machine, without doing any of it.
  *
@@ -113,10 +447,27 @@ export declare function buildPlan(args: {
     home: string;
     privkey: string;
     pubkey: string;
+    /** Written into the OpenClaw config; the plugin resolves its chain from it. */
+    orgName?: string;
+    /** The deployment this agent was onboarded on — selects the plugin's npm tag. */
+    endpoint?: string;
     /** Skip package installation; write config and the key file only. */
     noInstall: boolean;
     /** Restrict to these runtime ids; empty means "everything detected". */
     only: string[];
+    /**
+     * What the OpenClaw on this machine can do, probed by detectOpenclaw.
+     *
+     * Optional so tests and callers that only want the file-level merge need not
+     * shell out. Absent means "assume nothing extra" — the hand-merge path, which
+     * works on every version — rather than assuming the newest capabilities.
+     */
+    openclaw?: {
+        caps: {
+            patch: boolean;
+        };
+        hooksSupported?: boolean;
+    };
 }): Plan;
 /**
  * A minimal line diff, so the preview shows what CHANGES rather than dumping a
@@ -143,9 +494,40 @@ export interface ApplyResult {
     backups: string[];
     ran: string[];
     failures: string[];
+    /** Writes deliberately NOT made because a step they depend on failed. */
+    skipped: string[];
+    /** Files restored from backup because the result did not validate. */
+    rolledBack: 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;
+/**
+ * Execute the plan, in the order that cannot leave a half-wired machine.
+ *
+ *   1. Independent writes — the key file above all. Safe on their own, useful
+ *      even if everything after fails, and required by the plugin at load.
+ *   2. Commands — the plugin install, so the plugin id EXISTS on disk.
+ *   3. Dependent writes — the plugin config, now that it refers to something
+ *      real. Skipped outright if its install failed (see Step.requires).
+ *   4. Verify, and roll back anything we broke (see verify).
+ *
+ * ⚠️ THE ORDER IS THE FIX, and it is the reverse of what this function used to
+ * do. "Writes first, then commands, so a failed install still leaves a correct
+ * config behind" sounds prudent and produces the single worst outcome available:
+ * a config entry for a plugin that is not installed, which OpenClaw reports as a
+ * stale reference and offers to delete via `doctor --fix` — silently un-governing
+ * the agent — and which on 2026.2.x helped make the config unloadable, killing
+ * the install that would have fixed it.
+ */
+export declare function applyPlan(plan: Plan, opts?: {
+    /**
+     * Ask the runtime to confirm the result after writing, and restore the
+     * backup if the runtime says WE broke it. Omitted (or a build without
+     * `validate`) means no verification — which must read as "unverified", never
+     * as "verified fine".
+     */
+    verify?: (file: string) => {
+        valid: boolean;
+        problems: string;
+    } | undefined;
+}): ApplyResult;
 export declare function registerSetupCommand(program: Command): void;
 export {};