@atbash/cli 0.5.15-dev.1 → 0.5.15-dev.3

package/dist/commands/setup.d.ts

@@ -0,0 +1,254 @@
+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;
+/**
+ * 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 {};