@atbash/cli 0.5.15-dev.0 → 0.5.15-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;
@@ -101,6 +121,89 @@ export declare function isJsonc(text: string): boolean;
  * 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.
  *