@atbash/cli 0.5.15-dev.13 → 0.5.15-dev.16

package/dist/commands/setup.d.ts

@@ -78,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;
@@ -126,28 +186,31 @@ export declare function isJsonc(text: string): boolean;
  * `<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, orgName?: string, opts?: {
-    installsModern?: boolean;
-}): Record<string, unknown>;
 /**
- * What `openclaw plugins install` would actually do with this spec.
- *
- * ⚠️ That command cannot overwrite. If the extension directory is there it
- * aborts —
+ * WHICH entry this run governs, and whether a legacy one is being stood down.
  *
- *   plugin already exists: ~/.openclaw/extensions/atbash-openclaw
- *   (delete it first)
+ * 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.
  *
- * — and exits 1. A plan that lists the install unconditionally therefore fails
- * on its SECOND run against the same machine, and setup then reports "this
- * machine is NOT fully wired" about a machine that is completely wired. Setup is
- * meant to be re-runnable; a step that can only ever succeed once is not.
- *
- * There is no `plugins uninstall` in OpenClaw 2026.2.1 — the subcommands are
- * list/info/enable/disable/install/update/doctor — so the way to refresh an
- * existing install is `plugins update <id>`, which re-resolves the recorded spec
- * and reports "up to date" when there is nothing to do.
+ * 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;
@@ -341,6 +404,31 @@ export declare function mergeHermesEnv(existing: string | null): string;
  */
 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;
+}): string;
 /**
  * Work out everything that needs doing on this machine, without doing any of it.
  *
@@ -361,6 +449,19 @@ export declare function buildPlan(args: {
     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
@@ -387,9 +488,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 {};