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

package/dist/shared/openclaw-runtime.d.ts

@@ -0,0 +1,221 @@
+/** How this OpenClaw got onto the machine — decides the UPDATE command. */
+export type OpenclawChannel = "brew-formula" | "brew-cask" | "npm" | "unknown";
+/**
+ * Config subcommands this build has.
+ *
+ * Probed from `openclaw config --help`, because the boundary is not guessable
+ * from a version number. Observed: 2026.2.1 has only `get set unset`, while both
+ * 2026.6.6 and 2026.7.1 have `file get patch schema set unset validate`.
+ */
+export interface OpenclawCaps {
+    /**
+     * `openclaw config patch` — "Patch config from a JSON5 object in one validated
+     * write. Objects merge recursively, arrays/scalars replace, and null deletes a
+     * path", with `--stdin` and `--dry-run`.
+     *
+     * This is EXACTLY the operation setup needs, performed by OpenClaw itself, so
+     * where it exists we stop hand-merging JSON. That hands OpenClaw responsibility
+     * for its own file format, key names, schema, permissions and migrations — all
+     * the things we kept getting wrong from the outside. It also removes the
+     * clobber hazard: a machine in the field had three
+     * `openclaw.json.clobbered.<timestamp>` files, so OpenClaw rewrites that file
+     * on its own and anything we hand-merge can be discarded without warning.
+     */
+    patch: boolean;
+    /** `openclaw config validate` — schema check without starting the gateway. */
+    validate: boolean;
+    /** `openclaw config schema` — the authoritative key list for THIS build. */
+    schema: boolean;
+    /** `openclaw config file` — where the active config actually lives. */
+    configFile: boolean;
+}
+export interface OpenclawRuntime {
+    /** False when there is no OpenClaw on this machine at all. */
+    present: boolean;
+    /** As reported by `openclaw --version`, e.g. "2026.7.1". Undefined if unparseable. */
+    version?: string;
+    /** Build hash when the version line carries one — pins a build exactly. */
+    build?: string;
+    channel: OpenclawChannel;
+    /** Resolved path to the binary, for diagnostics. */
+    binPath?: string;
+    caps: OpenclawCaps;
+}
+/**
+ * Where the `openclaw` on PATH came from.
+ *
+ * Path-based rather than asked of a package manager, because shelling out to
+ * brew and npm to answer a question we can read off a path is slow and can hang
+ * on a bad network — and this runs before we have written anything, where a
+ * hang looks like the command being broken.
+ *
+ * ⚠️ The npm case is not hypothetical or unusual: the machine that reported the
+ * original failure ran `/Users/m4/.nvm/versions/node/v24.13.0/bin/openclaw`,
+ * so `brew info openclaw-cli` there said "Not installed" while OpenClaw was
+ * plainly running. Telling that user `brew upgrade openclaw-cli` would have been
+ * useless, which is the whole reason this returns a channel at all.
+ */
+export declare function detectChannel(binPath: string | undefined): OpenclawChannel;
+/**
+ * The command that updates THIS install, or undefined when we cannot tell.
+ *
+ * Returning undefined is deliberate and better than a plausible guess: a user
+ * told to run `brew upgrade openclaw-cli` on an npm install gets "No available
+ * formula", concludes our instructions are wrong, and is no closer to an
+ * upgrade. `openclaw update` is the honest fallback where the channel is
+ * unknown — it is OpenClaw's own self-updater, and 2026.6.6's `doctor` already
+ * recommends exactly that ("Run `openclaw update` to update via your package
+ * manager (npm/pnpm)").
+ */
+export declare function updateCommand(channel: OpenclawChannel): string;
+/**
+ * Inspect the OpenClaw on this machine. Read-only: probes `--version` and
+ * `config --help`, writes nothing, and never throws.
+ */
+export declare function detectOpenclaw(binary?: string): OpenclawRuntime;
+/** How setup should write config on this machine. */
+export type WriteStrategy = 
+/** `openclaw config patch --stdin` — OpenClaw merges and validates its own file. */
+"openclaw-patch"
+/** Hand-merge the JSON ourselves. The only option on 2026.2.x. */
+ | "hand-merge";
+export declare function writeStrategy(rt: OpenclawRuntime): WriteStrategy;
+/**
+ * Whether this OpenClaw is one we can wire at all, and what to say if not.
+ *
+ * DELIBERATELY PERMISSIVE. The floor is "there is an OpenClaw here", not "it has
+ * the newest config commands", because 2026.2.x installs are real — the box every
+ * CLI attestation was verified on is one — and the minimal entry-only config we
+ * now write was confirmed to load there with the plugin reporting
+ * `[atbash] plugin loaded` and `guard manager ready`. Narrowing support to the
+ * versions we happen to run is the mistake that produced this whole module.
+ *
+ * So an older build is a DEGRADED path with an offer, never a refusal: it gets
+ * the hand-merge, and the reason to upgrade is stated once, with the command for
+ * its own channel. Refusal is reserved for "no OpenClaw at all", where there is
+ * genuinely nothing to configure.
+ */
+export declare function supportStatus(rt: OpenclawRuntime): {
+    supported: boolean;
+    degraded: boolean;
+    /** Plain-language line for a non-technical operator. */
+    message: string;
+    /** The channel-correct upgrade command, when upgrading would help. */
+    upgrade?: string;
+};
+/**
+ * What OpenClaw says about the Atbash plugin after we have wired it.
+ *
+ * `state` is deliberately not a boolean. "Is this agent governed?" has more than
+ * two answers, and collapsing them is how setup came to print a green summary
+ * over an ungoverned machine.
+ */
+export interface PluginVerdict {
+    state: 
+    /** Present, switched on, and loaded. The only state that means governed. */
+    "loaded"
+    /** On disk but switched off — governs nothing, and is a deliberate act. */
+     | "disabled"
+    /** OpenClaw tried and failed to load it. Worse than missing: it looks wired. */
+     | "load-error"
+    /** OpenClaw does not know about it at all. */
+     | "missing"
+    /** We could not ask. Must never be reported as success. */
+     | "unknown";
+    entry?: string;
+    version?: string;
+    /** Required runtime dependencies OpenClaw reports as absent. */
+    missingDeps?: string[];
+    /** Raw explanation for the operator, in OpenClaw's terms where possible. */
+    detail?: string;
+}
+/**
+ * Ask OpenClaw whether the plugin actually loaded — the check setup never had.
+ *
+ * ⚠️ WHY THIS IS NOT OPTIONAL. Setup used to declare success on the strength of
+ * having written what it meant to write. That is not the same claim: on the
+ * machine that reported the original failure, the config entry existed and the
+ * plugin did not, and OpenClaw said so plainly —
+ *
+ *   plugins.entries.atbash-openclaw: plugin not found: atbash-openclaw
+ *   (stale config entry ignored; remove it from plugins config)
+ *
+ * — while setup reported the run as done. An owner reading that summary believes
+ * their agent is governed. Nothing is more expensive than a false green on a
+ * control boundary, so the last word belongs to OpenClaw, not to us.
+ *
+ * ⚠️ DO NOT check `hookCount` or `hookNames` here. They are 0 and empty for a
+ * perfectly healthy plugin: hooks register when the GATEWAY starts, not when
+ * `plugins list` runs. Verified against a plugin that was demonstrably loaded and
+ * enforcing — it reports `hookCount: 0`. Treating that as a fault would fail
+ * every correct install.
+ */
+export declare function verifyOpenclawPlugin(rt: OpenclawRuntime, opts: {
+    /** Entry ids that count as Atbash, current first. */
+    entryIds: readonly string[];
+    /** Pin the config being inspected, so this cannot read a different one. */
+    configPath?: string;
+    /**
+     * The package spec that was installed, e.g. `@atbash/atbash-openclaw@dev`.
+     * Used to catch the environment mismatch that loads cleanly and then fails
+     * every judge call: the plugin's endpoint and chain ids are compiled in, so a
+     * production build on a dev-onboarded agent is silently useless.
+     */
+    expectedSpec?: string;
+    /**
+     * The home directory being configured, when it is not the process's own.
+     *
+     * ⚠️ REQUIRED FOR A `--home` RUN, AND OMITTING IT PRODUCED A FALSE GREEN.
+     * Pinning `OPENCLAW_CONFIG_PATH` aims OpenClaw at the right CONFIG, but
+     * plugin discovery still walks `$HOME/.openclaw`, so the child process
+     * happily reported the plugin from the operator's real machine while we were
+     * asking about a different one. It printed "OpenClaw loads the plugin" about
+     * a home directory that contained no plugin at all — precisely the false
+     * green this whole check exists to prevent, produced by the check itself.
+     */
+    home?: string;
+    binary?: string;
+}): PluginVerdict;
+/**
+ * Ask OpenClaw whether a config is valid, when it can answer.
+ *
+ * This is the PREFLIGHT the command never had. Setup merged into
+ * `~/.openclaw/openclaw.json` without ever checking whether that file currently
+ * loads — so on a machine whose config was already broken it added its own entry
+ * to an unloadable file, and then its `openclaw plugins install` step died on the
+ * pre-existing breakage. Reported as an Atbash failure; it was not one.
+ *
+ * `undefined` means "cannot tell" (no `validate` on this build) and must be
+ * treated as such — not as a pass and not as a failure.
+ */
+/**
+ * Does THIS build accept `hooks` on a plugin entry?
+ *
+ * Asked of `openclaw config schema`, never inferred from a version number or
+ * correlated with other capabilities — the whole point of this module.
+ *
+ * ⚠️ WHY THIS QUESTION EXISTS. `hooks` was ADDED, not removed: it is unknown on
+ * 2026.2.1 and valid, optional and undeprecated on 2026.6.6 and 2026.7.1, where
+ * an entry accepts `enabled | hooks | subagent | llm | config`. Because the entry
+ * schema is `additionalProperties: false`, the same key is FATAL on the old build
+ * and legitimate on the new one.
+ *
+ * Setup never writes `hooks` — nothing under it is required, and it gates hook
+ * families this plugin does not use (it registers only `before_tool_call`). But
+ * it also used to DELETE an operator's `hooks` block unconditionally, and on a
+ * build that accepts the key that is destroying their configuration:
+ * `hooks.timeoutMs` bounds this plugin's hook latency "without changing plugin
+ * code", which is a deliberate operator choice, not damage to repair.
+ *
+ * `undefined` means "cannot tell" (no `config schema` on this build). The caller
+ * must treat that as NOT supported and strip: keeping an unrecognized key makes
+ * OpenClaw refuse the entire config, and losing a timeout knob is a far smaller
+ * harm than a machine whose config will not load at all.
+ */
+export declare function pluginEntryAcceptsHooks(rt: OpenclawRuntime, binary?: string): boolean | undefined;
+export declare function validateConfig(rt: OpenclawRuntime, configPath: string, binary?: string, 
+/** The home being configured, when not the process's own — see verifyOpenclawPlugin. */
+home?: string): {
+    valid: boolean;
+    problems: string;
+} | undefined;