@mcsherrylabs/evolver-mcp 0.0.0-stage → 0.8.1

package/dist/bootstrap.js

@@ -0,0 +1,901 @@
+// First-run identity bootstrap (BOOT-01..BOOT-07): mints a BLS+Ed25519 identity locally, PoP-signs
+// the SDK faucet digest, writes the key (0600), seed (0600) and config.json into a 0700 state dir,
+// claims through `NodeClient.claimIdentity`, and exits — WITHOUT ever starting the stdio server.
+//
+// 07-02 hardens this against crash, flaky devnet, squatted-name and re-run hazards. The state dir
+// is a small, crash-safe state machine:
+//   claimed -> nothing happens (`already_bootstrapped`, zero chain calls);
+//   pending (seed present, no marker) -> RESUMES with the seed's exact keys, restores 0600/0700;
+//   fresh   (no seed) -> refuses pre-existing state without `--force`, else mints+persists->claims;
+//   failed  (a claim that did not commit) -> keys kept on disk, marker absent, non-zero exit.
+//
+// Pure planning (`planBootstrap`) beside thin effects (`executeBootstrap`) through structural
+// `BootstrapDeps` seams, mirroring `resolveConfig`/`loadConfig`.
+//
+// SECURITY (T-07-01..T-07-18): private bytes never appear in an error message or output line —
+// refusals name a PATH or a FIELD, never key material. No new dependency, no new MCP tool.
+import { mkdirSync, chmodSync, lstatSync, writeFileSync, renameSync, readdirSync, readFileSync, realpathSync, } from "node:fs";
+import { join, sep, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes as nodeRandomBytes } from "node:crypto";
+import { homedir as nodeHomedir } from "node:os";
+import { newIdentity, faucetClaimDigest, faucetClaimDigestFor, blsSign, edSign, bytesToHex, hexToBytes, edSpkiToRaw, isValidNodeId, NodeClient, } from "@mcsherrylabs/evolver-client";
+import { UNTRUSTED } from "./mcp.js";
+// ── constants ────────────────────────────────────────────────────────────────
+export const BOOTSTRAP_FLAG = "--bootstrap";
+const DEVNET_DEFAULT_URL = "https://devnet.mcsherrylabs.com";
+const LOCAL_DEFAULT_PORT = "8440";
+export const RETRYABLE_CLAIM_ERRORS = ["node_not_ready", "queue_full", "confirmation_timeout", "internal"];
+export const DEFAULT_RETRY_MAX = 3;
+/** The one registration name the bootstrap emits (D-01, A9). */
+export const DEFAULT_REGISTRATION_NAME = "evolver-mcp";
+/** The built entry the registered launch runs, relative to the repo (A7). */
+export const SERVER_ENTRY_REL = join("dist", "index.js");
+export const BOOTSTRAP_USAGE = "usage: node dist/index.js --bootstrap [--target devnet|local] [--identity <name>] [--force]\n" +
+    "env: EVOLVER_TARGET, EVOLVER_FAUCET_URL, EVOLVER_DEVNET_URL, EVOLVER_NODE, LOCAL_CHAIN_PORT,\n" +
+    "     EVOLVER_MCP_STATE_DIR, XDG_STATE_HOME, EVOLVER_CONTENT_URL, EVOLVER_BOOTSTRAP_RETRY_MAX,\n" +
+    "     EVOLVER_BOOTSTRAP_FAUCET_URL (test-only)\n" +
+    "registration is DERIVED only — wave 3 emits it, never applies it.";
+// ── small helpers ────────────────────────────────────────────────────────────
+const optionalEnv = (env, key) => {
+    const v = env[key];
+    if (typeof v !== "string")
+        return undefined;
+    const t = v.trim();
+    return t.length > 0 ? t : undefined;
+};
+const isAbsolutePath = (p) => p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p);
+const containsDotDot = (p) => p.split(sep).includes("..");
+const UNKNOWN_TARGET_ERR = (name) => ({
+    kind: "partial",
+    what: "target",
+    cause: `unknown target "${name}" — the built-in targets are devnet, local`,
+});
+// ── resolveTarget (BOOT-01, T-07-05) ─────────────────────────────────────────
+export function resolveTarget(env, argvTarget, chainName, cwd) {
+    const customChain = optionalEnv(env, "EVOLVER_CHAIN");
+    const customUrl = optionalEnv(env, "EVOLVER_CHAIN_URL");
+    if (customUrl !== undefined && customChain === undefined) {
+        return { ok: false, error: { kind: "partial", what: "EVOLVER_CHAIN_URL", cause: "EVOLVER_CHAIN_URL is set without EVOLVER_CHAIN — name the chain it belongs to" } };
+    }
+    if (customChain !== undefined) {
+        return { ok: false, error: { kind: "partial", what: "EVOLVER_CHAIN", cause: "bootstrap supports only the built-in devnet/local targets, not a custom chain" } };
+    }
+    let name = argvTarget;
+    if (name === undefined || name.trim().length === 0)
+        name = optionalEnv(env, "EVOLVER_TARGET");
+    if (name === undefined)
+        name = chainName ?? readTargetFile(cwd);
+    if (name === undefined || name.trim().length === 0)
+        name = "devnet";
+    name = name.trim();
+    if (name === "devnet") {
+        const chainUrl = optionalEnv(env, "EVOLVER_DEVNET_URL") ?? DEVNET_DEFAULT_URL;
+        const faucetUrl = optionalEnv(env, "EVOLVER_FAUCET_URL") ?? chainUrl;
+        return { ok: true, plan: { target: "devnet", chainUrl, faucetUrl } };
+    }
+    if (name === "local") {
+        const port = optionalEnv(env, "LOCAL_CHAIN_PORT");
+        const chainUrl = optionalEnv(env, "EVOLVER_NODE") ?? `http://localhost:${port ?? LOCAL_DEFAULT_PORT}`;
+        const faucetUrl = optionalEnv(env, "EVOLVER_FAUCET_URL") ?? chainUrl;
+        return { ok: true, plan: { target: "local", chainUrl, faucetUrl } };
+    }
+    return { ok: false, error: UNKNOWN_TARGET_ERR(name) };
+}
+function readTargetFile(cwd) {
+    try {
+        const t = readFileSync(join(cwd, ".target"), "utf8").trim();
+        return t.length > 0 ? t : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── stateDirFor / statePaths ─────────────────────────────────────────────────
+export function stateDirFor(env, target, homedir) {
+    const explicit = optionalEnv(env, "EVOLVER_MCP_STATE_DIR");
+    if (explicit !== undefined) {
+        if (!isAbsolutePath(explicit) || containsDotDot(explicit)) {
+            return { ok: false, reason: "EVOLVER_MCP_STATE_DIR must be an absolute path with no `..` segment" };
+        }
+        return { ok: true, dir: explicit };
+    }
+    const xdg = optionalEnv(env, "XDG_STATE_HOME");
+    const base = xdg ?? join(homedir, ".local", "state");
+    return { ok: true, dir: join(base, "evolver-mcp", target) };
+}
+/** Name the files. `identity` is the identity ACTUALLY in play (seed's name on resume, argv value on
+ *  a fresh run, derived name otherwise). The dir is chosen by `stateDirFor`, never here. */
+export function statePaths(stateDir, identity) {
+    return {
+        dir: stateDir,
+        config: join(stateDir, "config.json"),
+        key: join(stateDir, `${identity}.key`),
+        seed: join(stateDir, `${identity}.keys.json`),
+        registration: join(stateDir, "mcp.json"),
+        claimed: join(stateDir, `${identity}.claimed`),
+    };
+}
+export function parseBootstrapArgs(args) {
+    let target;
+    let identity;
+    let force = false;
+    for (let i = 2; i < args.length; i++) {
+        const a = args[i];
+        if (a === BOOTSTRAP_FLAG)
+            continue;
+        else if (a === "--target") {
+            target = args[++i];
+            if (target === undefined)
+                return { ok: false, error: "--target needs a value" };
+        }
+        else if (a.startsWith("--target="))
+            target = a.slice("--target=".length);
+        else if (a === "--identity") {
+            identity = args[++i];
+            if (identity === undefined)
+                return { ok: false, error: "--identity needs a value" };
+        }
+        else if (a.startsWith("--identity="))
+            identity = a.slice("--identity=".length);
+        else if (a === "--force")
+            force = true;
+        else
+            return { ok: false, error: `unknown argument "${a}" — ${BOOTSTRAP_USAGE}` };
+    }
+    return { ok: true, target, identity, force };
+}
+// ── generateBootstrapIdentity (BOOT-02, T-07-06) ────────────────────────────
+export function generateBootstrapIdentity(name, mint = newIdentity) {
+    if (!isValidNodeId(name)) {
+        return { kind: "err", error: { kind: "partial", what: "identity", cause: `"${name}" is not a valid node id (letters and digits only, 1–50 chars)` } };
+    }
+    const id = mint(name);
+    const digest = faucetClaimDigestFor(id.nodeId, id.bls.pub, id.ed.pub);
+    if (bytesToHex(digest) !== bytesToHex(faucetClaimDigest(id))) {
+        return { kind: "err", error: { kind: "partial", what: "identity", cause: "the SDK's two digest entry points disagree — refusing to persist or sign before resolving the drift" } };
+    }
+    return { kind: "ok", value: { identity: id, digest, blsPop: blsSign(digest, id.bls.priv), edPop: edSign(digest, id.ed.priv) } };
+}
+// ── seed / key / config rendering ───────────────────────────────────────────
+export function seedFor(seed) {
+    return JSON.stringify(seed);
+}
+export function keyFileFor(identity) {
+    return Buffer.from(identity.bls.priv).toString("base64");
+}
+export function configFor(opts) {
+    return JSON.stringify({ identity: opts.name, url: opts.chainUrl }, null, 2) + "\n";
+}
+export function identityFromSeed(seed) {
+    return {
+        nodeId: seed.identity,
+        bls: { priv: Buffer.from(seed.blsPrivBase64, "base64"), pub: Buffer.from(seed.blsPubBase64, "base64") },
+        ed: { priv: Buffer.from(seed.edPrivBase64, "base64"), pub: Buffer.from(seed.edPubBase64, "base64") },
+    };
+}
+const B64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+export function readSeed(fs, seedPath) {
+    let raw;
+    try {
+        raw = fs.readFile(seedPath, "utf8");
+    }
+    catch {
+        return { ok: false, reason: `${seedPath}: the seed file is missing or unreadable` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: `${seedPath}: the seed file is not valid JSON` };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, reason: `${seedPath}: the seed root must be a JSON object` };
+    }
+    const rec = parsed;
+    if (typeof rec.identity !== "string" || rec.identity.length === 0) {
+        return { ok: false, reason: `${seedPath}: the seed's "identity" field is not a string` };
+    }
+    const fields = [
+        { key: "blsPubBase64", len: 48 },
+        { key: "edPubBase64", len: 32 },
+        { key: "blsPrivBase64", len: 32 },
+        { key: "edPrivBase64", len: 32 },
+    ];
+    for (const { key, len } of fields) {
+        const v = rec[key];
+        if (typeof v !== "string" || v.length === 0) {
+            return { ok: false, reason: `${seedPath}: the seed's "${key}" field is missing or not a string` };
+        }
+        if (!B64_RE.test(v)) {
+            return { ok: false, reason: `${seedPath}: the seed's "${key}" field is not valid base64` };
+        }
+        if (Buffer.from(v, "base64").length !== len) {
+            return { ok: false, reason: `${seedPath}: the seed's "${key}" field decodes to ${Buffer.from(v, "base64").length} bytes, expected ${len}` };
+        }
+    }
+    return {
+        ok: true,
+        seed: {
+            identity: rec.identity,
+            blsPubBase64: rec.blsPubBase64,
+            edPubBase64: rec.edPubBase64,
+            blsPrivBase64: rec.blsPrivBase64,
+            edPrivBase64: rec.edPrivBase64,
+            createdAt: typeof rec.createdAt === "string" ? rec.createdAt : "",
+        },
+    };
+}
+// ── listClaimed / listSeeds ──────────────────────────────────────────────────
+export function listClaimed(fs, dir) {
+    let names;
+    try {
+        names = fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const claimed = names
+        .filter((f) => f.endsWith(".claimed") && !f.includes(".tmp"))
+        .map((f) => f.slice(0, -".claimed".length))
+        .filter((id) => id.length > 0);
+    // Only a claimed marker WITH a matching key file gates "done" (T-07-13).
+    return claimed.filter((id) => names.includes(`${id}.key`));
+}
+function listSeeds(fs, dir) {
+    let names;
+    try {
+        names = fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((f) => f.endsWith(".keys.json") && !f.includes(".tmp"))
+        .map((f) => f.slice(0, -".keys.json".length));
+}
+// ── retryMax / backoff ───────────────────────────────────────────────────────
+export function retryMax(env) {
+    const v = optionalEnv(env, "EVOLVER_BOOTSTRAP_RETRY_MAX");
+    if (v === undefined)
+        return DEFAULT_RETRY_MAX;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? Math.min(Math.max(n, 1), 5) : DEFAULT_RETRY_MAX;
+}
+function backoffMs(attempt) {
+    return Math.min(250 * Math.pow(2, attempt - 1), 4000);
+}
+// ── claimWithRetries (T-07-17) ───────────────────────────────────────────────
+export async function claimWithRetries(client, gen, max, sleep) {
+    let attempts = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        attempts++;
+        const result = await client.claimIdentity(gen.identity);
+        if (result.kind !== "failed")
+            return { attempts, result };
+        if (RETRYABLE_CLAIM_ERRORS.includes(result.error) && attempts < max) {
+            await sleep(backoffMs(attempts));
+            continue;
+        }
+        return { attempts, result };
+    }
+}
+// ── exitCodeFor (T-07-16) ────────────────────────────────────────────────────
+// The exit-2 class is "fix your arguments/transport and rerun" (argument/usage/identity/target/
+// unreachable); the exit-1 class is "partial bootstrap, keys touched" (state/claim/claim-retry).
+const EXIT_2_WHATS = new Set(["identity", "target", "usage"]);
+export function exitCodeFor(outcome) {
+    switch (outcome.kind) {
+        case "committed":
+        case "exists":
+        case "already_bootstrapped":
+            return 0;
+        case "partial":
+            return EXIT_2_WHATS.has(outcome.what) ? 2 : 1;
+        case "unreachable":
+            return 2;
+    }
+}
+// ── writeState (BOOT-03) ─────────────────────────────────────────────────────
+export function writeState(fs, paths, configContent, seedContent, keyContent) {
+    try {
+        fs.mkdir(paths.dir, { recursive: true, mode: 0o700 });
+        fs.chmod(paths.dir, 0o700);
+    }
+    catch (e) {
+        return { kind: "partial", what: paths.dir, cause: e instanceof Error ? e.message : String(e) };
+    }
+    const files = [
+        { dest: paths.key, content: keyContent },
+        { dest: paths.seed, content: seedContent },
+        { dest: paths.config, content: configContent },
+    ];
+    for (const { dest, content } of files) {
+        const err = writeOne(fs, dest, content);
+        if (err)
+            return err;
+    }
+    return null;
+}
+function writeOne(fs, dest, content) {
+    try {
+        if (fs.lstat(dest).isSymbolicLink()) {
+            return { kind: "partial", what: dest, cause: "refusing to write through a symlinked path" };
+        }
+    }
+    catch {
+        // not present — proceed
+    }
+    const tmp = `${dest}.tmp-${Math.random().toString(36).slice(2)}`;
+    try {
+        fs.writeFile(tmp, content, { mode: 0o600 });
+        fs.rename(tmp, dest);
+    }
+    catch (e) {
+        return { kind: "partial", what: dest, cause: e instanceof Error ? e.message : String(e) };
+    }
+    return null;
+}
+// ── writeClaimedMarker ───────────────────────────────────────────────────────
+export function writeClaimedMarker(fs, claimedPath, marker) {
+    return writeOne(fs, claimedPath, JSON.stringify(marker));
+}
+export async function adoptExisting(client, name, identity) {
+    let keys;
+    try {
+        keys = await client.getIdentityKeys(name);
+    }
+    catch {
+        return { ok: false, cause: "could not read the name's on-chain keys", transport: true };
+    }
+    if (keys === null) {
+        return { ok: false, cause: "the chain reports the name exists but lists no keys for it" };
+    }
+    const found = new Set();
+    for (const key of keys) {
+        if (key.label !== "")
+            continue; // only label "" is compared
+        if (key.keyType === "BLS12-381-G1" && key.publicKeyHex.toLowerCase() === bytesToHex(identity.bls.pub).toLowerCase()) {
+            found.add("BLS12-381-G1");
+        }
+        else if (key.keyType === "Ed25519" && bytesToHex(edSpkiToRaw(hexToBytes(key.publicKeyHex))).toLowerCase() === bytesToHex(identity.ed.pub).toLowerCase()) {
+            found.add("Ed25519");
+        }
+        else {
+            // A row at label "" that is neither our BLS nor our Ed key (or a duplicate/extra) is foreign.
+            return { ok: false, cause: `the name's existing ${key.keyType} key at label "" is not ours` };
+        }
+    }
+    const haveBoth = found.has("BLS12-381-G1") && found.has("Ed25519");
+    if (!haveBoth) {
+        return { ok: false, cause: "the name's existing keys do not match this state dir's keys" };
+    }
+    // Any additional row at label "" beyond the one BLS + one Ed is a conflict (handled above: same
+    // type would hit the else). Safe to adopt: both required keys are ours and nothing foreign at "".
+    return { ok: true };
+}
+// ── planBootstrap (pure) ─────────────────────────────────────────────────────
+export function planBootstrap(env, argv, cwd, deps) {
+    const parsed = parseBootstrapArgs(argv);
+    if (!parsed.ok)
+        return { ok: false, error: { kind: "partial", what: "usage", cause: parsed.error } };
+    const resolved = resolveTarget(env, parsed.target, undefined, cwd);
+    if (!resolved.ok)
+        return { ok: false, error: resolved.error };
+    const homedir = deps.homedir ?? (() => (process.env.HOME ?? "/tmp"));
+    const dir = stateDirFor(env, resolved.plan.target, homedir());
+    if (!dir.ok)
+        return { ok: false, error: { kind: "partial", what: "state dir", cause: dir.reason } };
+    const name = parsed.identity ?? derivedName(deps.randomBytes ?? nodeRandomBytes);
+    if (!isValidNodeId(name)) {
+        return { ok: false, error: { kind: "partial", what: "identity", cause: `"${name}" is not a valid node id` } };
+    }
+    const gen = generateBootstrapIdentity(name);
+    if (gen.kind === "err")
+        return { ok: false, error: gen.error };
+    const paths = statePaths(dir.dir, name);
+    const contentUrl = optionalEnv(env, "EVOLVER_CONTENT_URL") ?? resolved.plan.chainUrl;
+    // The server entry is canonicalised ONCE here (realpath of the possibly-symlinked built entry);
+    // the state paths are NOT canonicalised (D-04/G2: verbatim). `serverEntryPath`/`realpath` are
+    // injectable so tests never depend on where tsx is invoked from; G7b covers the non-injected path.
+    const entryFn = deps.serverEntryPath ?? defaultServerEntryPath;
+    const realpath = deps.realpath ?? ((p) => realpathSync(p));
+    const serverEntry = realpath(entryFn());
+    // Package-mode entry command (Phase 8): when `EVOLVER_MCP_ENTRY_COMMAND` is set, the registration
+    // names that verbatim command (e.g. `npx -y @mcsherrylabs/evolver-mcp`) instead of the checkout
+    // realpath. Default (unset) keeps Phase 7's `node <realpath dist/index.js>` checkout form.
+    const entryCommandValue = optionalEnv(env, "EVOLVER_MCP_ENTRY_COMMAND");
+    const entryCommand = entryCommandValue !== undefined ? splitEntryCommand(entryCommandValue) : checkoutEntryCommand(serverEntry);
+    return {
+        ok: true,
+        plan: {
+            target: resolved.plan.target,
+            chainUrl: resolved.plan.chainUrl,
+            faucetUrl: resolved.plan.faucetUrl,
+            name,
+            explicitName: parsed.identity ?? false,
+            identitySource: parsed.identity !== undefined ? "explicit" : "derived",
+            force: parsed.force,
+            retryMax: retryMax(env),
+            paths,
+            identity: gen.value,
+            contentUrl,
+            contentWarning: renderWarnings(resolved.plan.target, contentUrl).join("\n"),
+            cwd,
+            serverEntry,
+            entryCommand,
+            registrationEnv: {
+                EVOLVER_KEY_PATH: paths.key,
+                EVOLVER_KEY_TYPE: "bls",
+                EVOLVER_CONTENT_URL: contentUrl,
+            },
+        },
+    };
+}
+function derivedName(randomBytes) {
+    const bytes = randomBytes(6);
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let suffix = "";
+    for (let i = 0; i < 6; i++)
+        suffix += chars[bytes[i] % chars.length];
+    return `evolvermcp${suffix}`;
+}
+/** The content warning (D-03): stated on every state-writing run, never blocks. */
+export function renderWarnings(target, contentUrl) {
+    const sentence = target === "devnet"
+        ? `warning: content tools may be unavailable on ${contentUrl} — devnet appears to serve no content listener, so READ-10..12 may answer unreachable even though the startup probe passes; EVOLVER_CONTENT_URL is still set in the registration.`
+        : `warning: content tools may be unavailable on ${contentUrl} — content is served by the local node's separate listener; EVOLVER_CONTENT_URL is still set in the registration.`;
+    return [`${sentence}${UNTRUSTED}`];
+}
+/** Split the `EVOLVER_MCP_ENTRY_COMMAND` value into `{command, args}` on whitespace, collapsing runs.
+ *  Empty/whitespace-only yields `args: []` (an empty command is invalid and rejected by planBootstrap). */
+export function splitEntryCommand(value) {
+    const parts = value.split(/\s+/).filter((s) => s.length > 0);
+    return { command: parts[0] ?? "", args: parts.slice(1) };
+}
+/** The launch shape for a checkout run: `node <realpath entry>`. */
+export function checkoutEntryCommand(serverEntry) {
+    return { command: "node", args: [serverEntry] };
+}
+/** Derive the one harness registration as data (BOOT-06/D-01). The entry is the REALPATH'd server
+ *  entry (default) OR a package-mode command (`npx -y @mcsherrylabs/evolver-mcp`) from
+ *  `EVOLVER_MCP_ENTRY_COMMAND`. `plan.paths.config`/`key` and the content URL are serialised
+ *  BYTE-FOR-BYTE as given (D-04/G2: verbatim state paths). Never key bytes, never the seed path,
+ *  never the faucet. */
+export function deriveRegistration(plan, entryCommand) {
+    return {
+        mcpServers: {
+            "evolver-mcp": {
+                type: "stdio",
+                command: entryCommand.command,
+                args: [...entryCommand.args, "--config", plan.paths.config],
+                env: { ...plan.registrationEnv },
+            },
+        },
+    };
+}
+/** The `claude mcp add` argv (scope user, transport stdio, env pairs, then the entry command). */
+export function claudeAddCommand(plan, entryCommand) {
+    const env = plan.registrationEnv;
+    return [
+        "claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "evolver-mcp",
+        "--env", `EVOLVER_KEY_PATH=${env.EVOLVER_KEY_PATH}`,
+        "--env", `EVOLVER_KEY_TYPE=${env.EVOLVER_KEY_TYPE}`,
+        "--env", `EVOLVER_CONTENT_URL=${env.EVOLVER_CONTENT_URL}`,
+        "--", entryCommand.command, ...entryCommand.args, "--config", plan.paths.config,
+    ];
+}
+/** The `claude mcp add-json` argv carrying the whole entry object as its JSON payload. */
+export function addJsonCommand(reg) {
+    return ["claude", "mcp", "add-json", "evolver-mcp", JSON.stringify(reg.mcpServers["evolver-mcp"]), "--scope", "user"];
+}
+/** Shell-quote one argv word for display: leave a safe token bare, else single-quote (escaping `'`
+ *  as `'\''`). */
+export function quoteArg(s) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+const quoteLine = (argv) => argv.map(quoteArg).join(" ");
+/** The human-facing registration block: a header, the named artefacts, the two exact commands
+ *  (via-flag and via-json), and the statement that the bootstrap prints them and never runs them. */
+export function registrationLines(plan, entryCommand) {
+    const reg = deriveRegistration(plan, entryCommand);
+    return [
+        "registration (derived, not applied):",
+        `  config:     ${plan.paths.config}`,
+        `  key:        ${plan.paths.key}`,
+        `  mcp.json:   ${plan.paths.registration}`,
+        "",
+        quoteLine(claudeAddCommand(plan, entryCommand)),
+        "",
+        "# generic clients (Codex, Pi-style runtimes, any stdio MCP client):",
+        quoteLine(addJsonCommand(reg)),
+        "",
+        "these commands are printed and never run by the bootstrap — the operator applies them.",
+    ];
+}
+/** The `--target local` refusal scan: a `.target` file in the state dir or the cwd, or a `.env*` file
+ *  in the cwd, would be read into the child's process env by the local chain — refuse before any
+ *  state write or claim. Returns the offending path, or null if clean. */
+function localTargetRefusal(fs, dir, cwd) {
+    const existsAt = (p) => { try {
+        fs.lstat(p);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    const envRe = /^\.env(\..*)?$/;
+    const dirTarget = join(dir, ".target");
+    if (existsAt(dirTarget))
+        return dirTarget;
+    const cwdTarget = join(cwd, ".target");
+    if (existsAt(cwdTarget))
+        return cwdTarget;
+    try {
+        const hit = fs.readdir(cwd).find((f) => envRe.test(f));
+        if (hit !== undefined)
+            return join(cwd, hit);
+    }
+    catch { /* cwd unreadable — not a refusal */ }
+    return null;
+}
+// ── live gate (BOOT-09) ──────────────────────────────────────────────────────
+/** The opt-in live devnet gate: enabled only when `EVOLVER_BOOTSTRAP_LIVE === "1"`; the base URL is
+ *  `EVOLVER_DEVNET_URL` or the devnet default. Never on `npm test` (the var is unset there). */
+export function liveGate(env) {
+    return {
+        enabled: env.EVOLVER_BOOTSTRAP_LIVE === "1",
+        baseUrl: optionalEnv(env, "EVOLVER_DEVNET_URL") ?? DEVNET_DEFAULT_URL,
+    };
+}
+// ── defaultDeps ──────────────────────────────────────────────────────────────
+/** The built entry path, before canonicalisation. From `dist/` (the CLI) `import.meta.url` is
+ *  `<repo>/dist/bootstrap.js`, so the entry is the sibling `index.js`; from `test/` (tsx) the module
+ *  URL lives under `src/`, so the entry is `<cwd>/dist/index.js`. */
+function defaultServerEntryPath() {
+    const p = fileURLToPath(import.meta.url);
+    const inBuild = /(?:^|[\\/])dist[\\/]/.test(p);
+    return inBuild ? join(dirname(p), "index.js") : resolve(process.cwd(), SERVER_ENTRY_REL);
+}
+export function defaultDeps() {
+    return {
+        fs: fullFs({}),
+        randomBytes: (n) => new Uint8Array(nodeRandomBytes(n)),
+        homedir: () => nodeHomedir(),
+        now: () => new Date(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        clientFactory: (baseUrl) => new NodeClient({ baseUrl }),
+        getIdentityBaseUrl: () => undefined,
+        mintIdentity: (name) => newIdentity(name),
+        serverEntryPath: defaultServerEntryPath,
+        realpath: (p) => realpathSync(p),
+    };
+}
+function fullFs(partial) {
+    return {
+        mkdir: partial.mkdir ?? ((p, o) => mkdirSync(p, o)),
+        chmod: partial.chmod ?? ((p, m) => chmodSync(p, m)),
+        lstat: partial.lstat ?? ((p) => lstatSync(p)),
+        writeFile: partial.writeFile ?? ((p, d, o) => writeFileSync(p, d, o)),
+        rename: partial.rename ?? ((f, t) => renameSync(f, t)),
+        readdir: partial.readdir ?? ((p) => readdirSync(p)),
+        readFile: partial.readFile ?? ((p, e) => readFileSync(p, e)),
+        exists: partial.exists ?? ((p) => { try {
+            lstatSync(p);
+            return true;
+        }
+        catch {
+            return false;
+        } }),
+    };
+}
+function mergeDeps(deps) {
+    const d = defaultDeps();
+    return {
+        fs: fullFs(deps.fs ?? {}),
+        randomBytes: deps.randomBytes ?? d.randomBytes,
+        homedir: deps.homedir ?? d.homedir,
+        now: deps.now ?? d.now,
+        sleep: deps.sleep ?? d.sleep,
+        clientFactory: deps.clientFactory ?? d.clientFactory,
+        getIdentityBaseUrl: deps.getIdentityBaseUrl ?? d.getIdentityBaseUrl,
+        mintIdentity: deps.mintIdentity ?? d.mintIdentity,
+        serverEntryPath: deps.serverEntryPath ?? d.serverEntryPath,
+        realpath: deps.realpath ?? d.realpath,
+    };
+}
+// ── executeBootstrap (the step 0–8 spine) ────────────────────────────────────
+export async function executeBootstrap(plan, deps) {
+    const full = mergeDeps(deps);
+    const fs = full.fs;
+    const dir = plan.paths.dir;
+    // Step 0: identity resolution (seed FIRST) before any name-derived path or client. The argv
+    // identity (when one was given) is `plan.name` when `identitySource === "explicit"`; `explicitName`
+    // stays an invocation record (display only) and is never branched on here (T-07-19).
+    const argvIdentity = plan.identitySource === "explicit" ? plan.name : undefined;
+    const res = resolveIdentityStep0(fs, dir, argvIdentity, plan.name);
+    if (!res.ok)
+        return res.error;
+    const { identityName, identitySource } = res.value;
+    const paths = statePaths(dir, identityName);
+    // `--target local` refusal (before ANY state write or claim): the local chain's `fromEnvironment`
+    // reads `.target`/`.env*` into the process, so a child would join a node whose env the operator
+    // never chose. `--target devnet` is unaffected. Placed after identity resolution, before the
+    // claimed short-circuit, so a local resume is refused too.
+    if (plan.target === "local") {
+        const refused = localTargetRefusal(fs, dir, plan.cwd);
+        if (refused !== null) {
+            return {
+                kind: "partial",
+                what: "state",
+                cause: `${refused} exists; the chain reads it into the process env — remove it or bootstrap from a clean directory`,
+            };
+        }
+    }
+    // Step 1: claimed short-circuit (before any client construction).
+    if (identitySource === "explicit" || identitySource === "seed") {
+        if (fs.exists(paths.claimed))
+            return { kind: "already_bootstrapped", identityName };
+    }
+    else {
+        // derived — the ONLY derived case: resolve against the dir's claimed identities.
+        const claimed = listClaimed(fs, dir);
+        if (claimed.length === 1)
+            return { kind: "already_bootstrapped", identityName: claimed[0] };
+        if (claimed.length > 1) {
+            return { kind: "partial", what: "identity", cause: "several bootstrapped identities; pass --identity <name>" };
+        }
+    }
+    // Step 2: resume — a seed exists for <identityUsed>.
+    if (fs.exists(paths.seed)) {
+        return resumePath(full, plan, paths, identityName);
+    }
+    // Step 3: no seed; pre-existing state refusal (stated rule) checks the SAME dir.
+    const preKey = fs.exists(paths.key);
+    const preConfig = fs.exists(paths.config);
+    if (preKey || preConfig) {
+        if (!plan.force) {
+            const which = preKey ? paths.key : paths.config;
+            return { kind: "partial", what: "state", cause: `${which} exists; refusing to overwrite — pass --force to mint a new identity` };
+        }
+        // --force: fall through to fresh mint (the matching identity overwrites atomically; a
+        // different-name --force keeps the old <other>.* untouched).
+    }
+    // Step 4: fresh pre-check on the chain.
+    const preCheckBase = full.getIdentityBaseUrl ? full.getIdentityBaseUrl() : undefined;
+    const preCheckClient = makeClient(full, preCheckBase ?? plan.faucetUrl);
+    try {
+        const existing = await preCheckClient.getIdentity(identityName);
+        if (existing !== null) {
+            return { kind: "partial", what: "identity", cause: `${identityName} is already on this chain; a bootstrap never adopts keys it did not mint — pick another --identity` };
+        }
+    }
+    catch (e) {
+        return { kind: "unreachable", chain: preCheckBase ?? plan.faucetUrl, cause: e instanceof Error ? e.message : String(e) };
+    }
+    // Step 5: mint (via the injected hook — the resume path never reaches here, T-07-13).
+    const gen = generateBootstrapIdentity(identityName, full.mintIdentity);
+    if (gen.kind === "err")
+        return gen.error;
+    const seed = {
+        identity: identityName,
+        blsPubBase64: Buffer.from(gen.value.identity.bls.pub).toString("base64"),
+        edPubBase64: Buffer.from(gen.value.identity.ed.pub).toString("base64"),
+        blsPrivBase64: Buffer.from(gen.value.identity.bls.priv).toString("base64"),
+        edPrivBase64: Buffer.from(gen.value.identity.ed.priv).toString("base64"),
+        createdAt: full.now().toISOString(),
+    };
+    // Step 5b: persist BEFORE claim (T-07-08).
+    const writeErr = writeState(fs, paths, configFor({ name: identityName, chainUrl: plan.chainUrl }), seedFor(seed), keyFileFor(gen.value.identity));
+    if (writeErr)
+        return writeErr;
+    // Step 6: claim with bounded retries.
+    const client = makeClient(full, plan.faucetUrl);
+    let attempt;
+    try {
+        attempt = await claimWithRetries(client, gen.value, plan.retryMax, full.sleep);
+    }
+    catch (e) {
+        return { kind: "unreachable", chain: plan.faucetUrl, cause: e instanceof Error ? e.message : String(e) };
+    }
+    // Step 7: outcome mapping.
+    return mapClaimResult(full, plan, paths, identityName, gen.value.identity, attempt.result);
+}
+function resolveIdentityStep0(fs, dir, argvIdentity, provisionalName) {
+    const seeds = listSeeds(fs, dir);
+    if (seeds.length > 1) {
+        return { ok: false, error: { kind: "partial", what: "identity", cause: `several pending identities (${seeds.join(", ")}); pass --identity <name>` } };
+    }
+    if (seeds.length === 1) {
+        const seedName = seeds[0];
+        if (argvIdentity === undefined) {
+            return { ok: true, value: { identityName: seedName, identitySource: "seed", explicitName: false } };
+        }
+        const explicitName = argvIdentity === seedName ? true : argvIdentity;
+        return { ok: true, value: { identityName: seedName, identitySource: "seed", explicitName } };
+    }
+    // No seed.
+    if (argvIdentity !== undefined) {
+        return { ok: true, value: { identityName: argvIdentity, identitySource: "explicit", explicitName: true } };
+    }
+    return { ok: true, value: { identityName: provisionalName, identitySource: "derived", explicitName: false } };
+}
+/** Step 2: resume a seeded identity with its OWN keys (never mint; never a fresh path). */
+async function resumePath(full, plan, paths, identityName) {
+    const r = readSeed(full.fs, paths.seed);
+    if (!r.ok)
+        return { kind: "partial", what: "state", cause: r.reason };
+    const identity = identityFromSeed(r.seed);
+    // Recompute PoP from the SAME seed bytes (no mint). The mint hook is NOT called here.
+    const gen = generateBootstrapIdentity(identity.nodeId, () => identity);
+    if (gen.kind === "err")
+        return gen.error;
+    // Rewrite identically (restores 0600/0700), persist-before-claim.
+    const writeErr = writeState(full.fs, paths, configFor({ name: identity.nodeId, chainUrl: plan.chainUrl }), seedFor(r.seed), keyFileFor(identity));
+    if (writeErr)
+        return writeErr;
+    const client = makeClient(full, plan.faucetUrl);
+    let attempt;
+    try {
+        attempt = await claimWithRetries(client, gen.value, plan.retryMax, full.sleep);
+    }
+    catch (e) {
+        return { kind: "unreachable", chain: plan.faucetUrl, cause: e instanceof Error ? e.message : String(e) };
+    }
+    return mapClaimResult(full, plan, paths, identity.nodeId, gen.value.identity, attempt.result);
+}
+/** Step 7: map a claim result to an outcome, and write the marker only on a verified success.
+ *  `identity` is the identity ACTUALLY in play — the seed's identity on a resume, the minted
+ *  identity on a fresh run — so the adoption comparison is always against OUR OWN keys. */
+async function mapClaimResult(full, plan, paths, identityName, identity, result) {
+    if (result.kind === "committed") {
+        // chain-verify with getIdentity (throw -> unreachable, null -> partial committing not visible).
+        const verifyBase = full.getIdentityBaseUrl ? full.getIdentityBaseUrl() : undefined;
+        const verifyClient = makeClient(full, verifyBase ?? plan.faucetUrl);
+        let node;
+        try {
+            node = await verifyClient.getIdentity(identityName);
+        }
+        catch (e) {
+            return { kind: "unreachable", chain: verifyBase ?? plan.faucetUrl, cause: e instanceof Error ? e.message : String(e) };
+        }
+        if (node === null) {
+            return { kind: "partial", what: "claim", cause: "committed but the node does not list it yet" };
+        }
+        const markerErr = writeClaimedMarker(full.fs, paths.claimed, {
+            identity: identityName,
+            outcome: "committed",
+            blockHeight: result.blockHeight,
+            claimedAt: full.now().toISOString(),
+        });
+        if (markerErr)
+            return markerErr;
+        const regErr = writeRegistration(full.fs, paths, plan, identityName);
+        if (regErr)
+            return regErr;
+        return { kind: "committed", blockHeight: result.blockHeight, identityName };
+    }
+    if (result.kind === "exists") {
+        // Adoption comparison against OUR identity's own keys (the minted or seeded identity, never
+        // keys read from the chain to decide "ours").
+        const adoptClient = makeClient(full, plan.faucetUrl);
+        const adoption = await adoptExisting(adoptClient, identityName, identity);
+        if (!adoption.ok) {
+            if (adoption.transport) {
+                return { kind: "unreachable", chain: plan.faucetUrl, cause: adoption.cause };
+            }
+            // A foreign-name conflict is a partial-bootstrap (keys already persisted), so it exits 1 —
+            // distinct from the pre-check `partial("identity")` argument error which exits 2.
+            return { kind: "partial", what: "claim", cause: adoption.cause };
+        }
+        const markerErr = writeClaimedMarker(full.fs, paths.claimed, {
+            identity: identityName,
+            outcome: "exists",
+            claimedAt: full.now().toISOString(),
+        });
+        if (markerErr)
+            return markerErr;
+        const regErr = writeRegistration(full.fs, paths, plan, identityName);
+        if (regErr)
+            return regErr;
+        return { kind: "exists", outcome: "exists", identityName };
+    }
+    // failed: verbatim `${error}: ${message}` (digest_mismatch included, never reworded).
+    return { kind: "partial", what: "claim", cause: `${result.error}: ${result.message}` };
+}
+function makeClient(full, baseUrl) {
+    return full.clientFactory(baseUrl);
+}
+/** Write `<stateDir>/mcp.json` (0600, tmp+rename, symlink refused) from the RESOLVED paths — the
+ *  `identityName` actually in play, so a resume under a seed `<Y>` names `<Y>.key`, never the argv
+ *  `<X>`. Shares `deriveRegistration` with the printed lines so the file and the command cannot
+ *  diverge (T-07-22). */
+function writeRegistration(fs, paths, plan, identityName) {
+    const resolved = {
+        paths: { ...paths, key: join(paths.dir, `${identityName}.key`) },
+        registrationEnv: {
+            EVOLVER_KEY_PATH: join(paths.dir, `${identityName}.key`),
+            EVOLVER_KEY_TYPE: "bls",
+            EVOLVER_CONTENT_URL: plan.contentUrl,
+        },
+    };
+    const content = JSON.stringify(deriveRegistration(resolved, plan.entryCommand), null, 2) + "\n";
+    return writeOne(fs, paths.registration, content);
+}
+// ── runBootstrap (BOOT-07): the CLI shell — performs NO termination and NO cwd read ─
+export async function runBootstrap(argv, env, deps = {}) {
+    const cwd = cwdFor(env);
+    // Re-derive the force flag + identity resolution from the state dir in executeBootstrap; plan
+    // carries the argv record. The faucet seam redirects BOTH the pre-check and the claim.
+    const planned = planBootstrap(env, argv, cwd, deps);
+    if (!planned.ok) {
+        return { exitCode: exitCodeFor(planned.error), output: renderOutcome(planned.error) + "\n", toStderr: true };
+    }
+    const plan = planned.plan;
+    const faucetEnv = optionalEnv(env, "EVOLVER_BOOTSTRAP_FAUCET_URL");
+    const execDeps = faucetEnv !== undefined ? { ...deps, getIdentityBaseUrl: () => faucetEnv } : deps;
+    const outcome = await executeBootstrap(plan, execDeps);
+    const code = exitCodeFor(outcome);
+    const lines = [];
+    if (outcome.kind === "committed" || outcome.kind === "exists" || outcome.kind === "already_bootstrapped") {
+        // Render from the RESOLVED identity (.key actually on disk), not the argv-level plan, so the
+        // printed `key:`/`identity:`/`claude mcp add` lines cannot diverge from the written mcp.json
+        // under a different-name resume (--identity X resolving to seed <Y>) (T-07-22 / CR-01).
+        const resolvedPaths = statePaths(plan.paths.dir, outcome.identityName);
+        const resolvedPlan = {
+            name: outcome.identityName,
+            paths: resolvedPaths,
+            registrationEnv: {
+                EVOLVER_KEY_PATH: resolvedPaths.key,
+                EVOLVER_KEY_TYPE: "bls",
+                EVOLVER_CONTENT_URL: plan.contentUrl,
+            },
+        };
+        if (outcome.kind === "committed") {
+            lines.push(`bootstrap committed (block ${outcome.blockHeight})`);
+        }
+        else if (outcome.kind === "exists") {
+            lines.push("bootstrap exists");
+        }
+        else {
+            lines.push("bootstrap already_bootstrapped");
+        }
+        lines.push(`  state dir:  ${resolvedPaths.dir}`);
+        lines.push(`  config:     ${resolvedPaths.config}`);
+        lines.push(`  key:        ${resolvedPaths.key}`);
+        lines.push(`  identity:   ${resolvedPlan.name}`);
+        lines.push(plan.contentWarning);
+        lines.push(...registrationLines(resolvedPlan, plan.entryCommand));
+        return { exitCode: 0, output: lines.join("\n") + "\n", toStderr: false };
+    }
+    return { exitCode: code, output: renderOutcome(outcome) + "\n", toStderr: true };
+}
+function cwdFor(env) {
+    const v = env.EVOLVER_BOOTSTRAP_CWD;
+    return typeof v === "string" && v.length > 0 ? v : "/";
+}
+function renderOutcome(o) {
+    switch (o.kind) {
+        case "partial":
+            return `bootstrap refused: ${o.what}: ${o.cause}`;
+        case "unreachable":
+            return `bootstrap unreachable: ${o.chain}: ${o.cause}`;
+        case "committed":
+            return `bootstrap committed (block ${o.blockHeight})`;
+        case "exists":
+            return "bootstrap exists";
+        case "already_bootstrapped":
+            return "bootstrap already_bootstrapped";
+    }
+}
+// ── hasBootstrapFlag (used by src/index.ts) ──────────────────────────────────
+export function hasBootstrapFlag(args) {
+    for (let i = 2; i < args.length; i++) {
+        if (args[i] === BOOTSTRAP_FLAG)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=bootstrap.js.map