@honua/mcp-server 0.1.4-beta.0 → 0.1.9-beta.0

package/dist/src/release/zero-to-map-cli.js

@@ -0,0 +1,881 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, lstat, mkdir, open, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import path, { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HonuaClient } from "@honua/sdk-js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { listAllTools } from "../certification/admin-parity.js";
+import { validateAgainstSchema } from "../certification/json-schema.js";
+import { requireSecureCredentialEndpoint } from "../credential-endpoint.js";
+import { isMainEntrypoint } from "../entrypoint.js";
+import { resolveProxyOptions } from "../proxy.js";
+import { assertZeroToMapCheckpointBindings, assertZeroToMapCheckpointDigest, assertZeroToMapCheckpointFresh, consumeZeroToMapCheckpoint, createZeroToMapCheckpoint, parseZeroToMapCheckpoint, } from "./zero-to-map-checkpoint.js";
+import { ZERO_TO_MAP_ACCESS_GRANTS, assertAwsEcsProvisionBindings, parseAwsEcsProvisionBinding, } from "./zero-to-map-provision.js";
+import { JourneyBlockedError, parseZeroToMapPlan, runZeroToMapJourney, } from "./zero-to-map.js";
+class ContractAdapter {
+    runCli() {
+        return Promise.reject(new Error("contract adapter must not execute CLI work"));
+    }
+    listTools() {
+        return Promise.reject(new Error("contract adapter must not connect to MCP"));
+    }
+    callTool() {
+        return Promise.reject(new Error("contract adapter must not call MCP tools"));
+    }
+    readResource() {
+        return Promise.reject(new Error("contract adapter must not read MCP resources"));
+    }
+    runGpServer() {
+        return Promise.reject(new Error("contract adapter must not execute GPServer jobs"));
+    }
+    readReceipt() {
+        return Promise.resolve(undefined);
+    }
+    checkHttp() {
+        return Promise.reject(new Error("contract adapter must not make HTTP requests"));
+    }
+}
+class LiveAdapter {
+    options;
+    env;
+    #client;
+    constructor(options, env) {
+        this.options = options;
+        this.env = env;
+    }
+    async runCli(args) {
+        if (this.options.target === "aws-ecs")
+            return this.awsProvisionEvidence(args);
+        const result = await runProcess(this.options.honuaCommand, args, this.env);
+        if (result.exitCode !== 0) {
+            throw new Error(`honua CLI exited ${result.exitCode}; command output was suppressed`);
+        }
+        if (args[0] === "admin" && args[1] === "install" && args[2] === "local") {
+            const accessCredential = parseInstallAccessCredential(result.stdout);
+            return {
+                value: { accessCredential },
+                evidence: {
+                    command: "honua",
+                    args: redactCliArgs(args),
+                    exitCode: result.exitCode,
+                    accessCredential,
+                },
+            };
+        }
+        return { evidence: { command: "honua", args: redactCliArgs(args), exitCode: result.exitCode } };
+    }
+    awsProvisionEvidence(args) {
+        const binding = this.options.provisionBinding;
+        if (!binding)
+            throw new Error("AWS ECS target has no verified provision binding");
+        if (args[0] !== "admin" || args[1] !== "install") {
+            throw new Error("AWS ECS target can replace only the Stage 1 install actions");
+        }
+        if (args[2] === "local") {
+            return {
+                value: { accessCredential: binding.accessCredential },
+                evidence: {
+                    target: binding.target,
+                    candidateId: binding.candidateId,
+                    releaseId: binding.releaseId,
+                    serverImage: binding.serverImage,
+                    components: binding.components,
+                    terraformPlan: binding.checks["terraform-plan"],
+                    terraformApply: binding.checks["terraform-apply"],
+                    producerEvidenceUrl: binding.evidence.url,
+                    producerEvidenceSha256: binding.evidence.sha256,
+                    accessCredential: binding.accessCredential,
+                },
+            };
+        }
+        if (args[2] === "status") {
+            return {
+                evidence: {
+                    target: binding.target,
+                    endpoint: binding.endpoint,
+                    mcpUrl: this.options.mcpUrl,
+                    readiness: binding.checks.readiness,
+                    adminMcpHandoff: binding.checks["admin-mcp-handoff"],
+                    credentialReferencePresent: binding.adminKeySecretRef.length > 0,
+                },
+            };
+        }
+        throw new Error("AWS ECS target encountered an unknown Stage 1 install action");
+    }
+    async listTools() {
+        const client = await this.client();
+        const tools = await listAllTools(client);
+        return tools.map((tool) => ({ name: tool.name, inputSchema: tool.inputSchema }));
+    }
+    async callTool(tool, args) {
+        const result = await (await this.client()).callTool({ name: tool, arguments: args });
+        if (result.isError === true) {
+            throw new Error(`${tool} returned isError=true: ${toolErrorMessage(result)}`);
+        }
+        const operation = requireCompletedPublishedOperation(tool, result);
+        return {
+            value: result,
+            evidence: {
+                tool,
+                isError: false,
+                ...(operation
+                    ? {
+                        operationId: operation.operationId,
+                        status: operation.status,
+                        handleId: operation.handleId,
+                        metadataRevision: operation.metadataRevision,
+                    }
+                    : {}),
+            },
+        };
+    }
+    async readResource(action) {
+        const client = await this.client();
+        return readJourneyMcpResource(action, (uri) => client.readResource({ uri }));
+    }
+    async runGpServer(action) {
+        const mcpUrl = this.options.mcpUrl;
+        if (!mcpUrl) {
+            throw new JourneyBlockedError("The GPServer run requires --mcp-url to identify the Honua deployment.", "mcp-url-missing");
+        }
+        const proxyOptions = resolveJourneyProxyOptions(mcpUrl, this.env);
+        const endpoint = new URL(proxyOptions.remoteUrl);
+        endpoint.pathname = endpoint.pathname.replace(/\/mcp\/?$/, "") || "/";
+        endpoint.search = "";
+        endpoint.hash = "";
+        const client = new HonuaClient({
+            baseUrl: endpoint.toString(),
+            apiKey: proxyOptions.apiKey,
+            bearerToken: proxyOptions.authToken,
+        });
+        const runner = client.geoprocessingRunner(action.serviceId, action.taskName);
+        const job = await runner.execute({
+            processId: action.processId,
+            parameters: action.parameters,
+            resultNames: action.resultNames,
+        });
+        const result = await job.results({ pollIntervalMs: 500, deadlineMs: 120_000 });
+        return {
+            value: { jobId: job.id, jobType: job.type, status: job.status, outputs: result.outputs },
+            evidence: {
+                protocol: runner.protocol,
+                processId: action.processId,
+                serviceId: action.serviceId,
+                taskName: action.taskName,
+                jobId: job.id,
+                status: job.status,
+                resultNames: Object.keys(result.outputs),
+            },
+        };
+    }
+    async readReceipt(actionId) {
+        const path = this.options.receiptPaths[actionId];
+        if (!path)
+            return undefined;
+        const bytes = await readFile(path);
+        const value = JSON.parse(bytes.toString("utf8"));
+        if (actionId === "console-approval") {
+            const schemaPath = fileURLToPath(new URL("../../../release/zero-to-map/contracts/console-receipt.schema.json", import.meta.url));
+            const schema = JSON.parse(await readFile(schemaPath, "utf8"));
+            const validation = validateAgainstSchema(schema, value);
+            if (!validation.valid) {
+                throw new Error(`Console receipt failed its strict schema: ${validation.errors.join("; ")}`);
+            }
+        }
+        return {
+            value,
+            evidence: {
+                source: "external-receipt",
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+            },
+        };
+    }
+    async checkHttp(url, expectedStatus) {
+        const requested = new URL(url);
+        if (requested.protocol !== "https:" || requested.username || requested.password) {
+            throw new Error("published artifact URL must be HTTPS and must not embed credentials");
+        }
+        const response = await fetch(url, { method: "GET", redirect: "follow" });
+        if (response.status !== expectedStatus) {
+            throw new Error(`GET ${url} returned ${response.status}; expected ${expectedStatus}`);
+        }
+        if (normalizeEndpoint(response.url) !== normalizeEndpoint(url)) {
+            throw new Error(`GET ${url} resolved to a different published identity: ${response.url}`);
+        }
+        const contentType = response.headers.get("content-type");
+        if (!contentType)
+            throw new Error(`GET ${url} returned no content type`);
+        return {
+            evidence: {
+                requestedUrl: url,
+                url: response.url,
+                status: response.status,
+                contentType,
+                identityMatched: true,
+            },
+        };
+    }
+    async close() {
+        await this.#client?.close();
+    }
+    async client() {
+        if (this.#client)
+            return this.#client;
+        const mcpUrl = this.options.mcpUrl;
+        if (!mcpUrl) {
+            throw new JourneyBlockedError("HONUA_MCP_REMOTE_URL (or --mcp-url) is required for a live journey.", "mcp-url-missing");
+        }
+        const proxyEntry = fileURLToPath(new URL("../proxy.js", import.meta.url));
+        const childEnv = {
+            ...this.env,
+            HONUA_MCP_REMOTE_URL: mcpUrl,
+        };
+        resolveProxyOptions(childEnv);
+        const transport = new StdioClientTransport({
+            command: process.execPath,
+            args: [proxyEntry],
+            env: childEnv,
+            stderr: "inherit",
+        });
+        const client = new Client({ name: "honua-zero-to-map-release", version: "1.0.0" });
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            throw new JourneyBlockedError(`Could not connect through honua-mcp-proxy: ${error instanceof Error ? error.message : String(error)}`, "mcp-proxy-unavailable");
+        }
+        this.#client = client;
+        return client;
+    }
+}
+export async function runZeroToMapCli(argv = process.argv.slice(2), env = process.env) {
+    const options = parseZeroToMapCliArgs(argv, env);
+    if (options.execute && !options.confirmed) {
+        throw new Error("--execute requires --yes because the journey creates and publishes server state");
+    }
+    if (options.execute && !options.checkpointPath) {
+        throw new Error("--execute requires --checkpoint so Console approval cannot replay prior mutations");
+    }
+    const planBytes = await readFile(options.planPath);
+    const plan = parseZeroToMapPlan(JSON.parse(planBytes.toString("utf8")));
+    const liveOptions = options.execute ? await prepareLiveOptions(options, env) : options;
+    const bindings = options.execute
+        ? checkpointBindings(liveOptions, plan.journeyId, plan.releaseContract, planBytes)
+        : undefined;
+    let checkpoint;
+    let claimPath;
+    if (options.execute && options.checkpointPath) {
+        checkpoint = await readCheckpointIfPresent(options.checkpointPath);
+        if (checkpoint) {
+            if (!options.consoleReceiptPath)
+                throw new Error("a paused checkpoint requires --console-receipt to resume");
+            if (!options.checkpointDigest)
+                throw new Error("--checkpoint-digest is required to resume");
+            assertZeroToMapCheckpointDigest(checkpoint, options.checkpointDigest);
+            if (checkpoint.state !== "paused")
+                throw new Error("checkpoint has already been consumed");
+            assertZeroToMapCheckpointFresh(checkpoint);
+            if (!bindings)
+                throw new Error("internal checkpoint binding error");
+            assertZeroToMapCheckpointBindings(checkpoint, bindings);
+            claimPath = await claimZeroToMapCheckpoint(options.checkpointPath, checkpoint.integrity.digest);
+        }
+        else if (options.consoleReceiptPath || options.checkpointDigest) {
+            throw new Error("--console-receipt and --checkpoint-digest require an existing paused checkpoint");
+        }
+    }
+    const adapter = options.execute ? new LiveAdapter(liveOptions, env) : new ContractAdapter();
+    const receipt = await runZeroToMapJourney(plan, adapter, {
+        execute: options.execute,
+        target: options.target,
+        variables: options.variables,
+        ...(checkpoint ? { resume: checkpoint.resume } : {}),
+        ...(!checkpoint && bindings && options.checkpointPath
+            ? {
+                onExternalReceiptMissing: async (snapshot) => {
+                    await writeJsonNew(options.checkpointPath, createZeroToMapCheckpoint(bindings, snapshot));
+                },
+            }
+            : {}),
+    });
+    const receiptBytes = `${JSON.stringify(receipt, null, 2)}\n`;
+    await writeFile(options.outputPath, receiptBytes, "utf8");
+    if (checkpoint && claimPath && options.checkpointPath) {
+        if (receipt.status === "passed") {
+            const consumed = consumeZeroToMapCheckpoint(checkpoint, createHash("sha256").update(receiptBytes).digest("hex"));
+            await writeFile(claimPath, `${JSON.stringify(consumed, null, 2)}\n`, "utf8");
+            await rename(claimPath, options.checkpointPath);
+        }
+    }
+    process.stdout.write(`${receipt.mode} journey ${receipt.status}; receipt written to ${options.outputPath}\n`);
+    return receipt.status === "passed" ? 0 : receipt.status === "blocked" ? 2 : 1;
+}
+export function parseZeroToMapCliArgs(argv, env) {
+    let execute = false;
+    let confirmed = false;
+    let planPath = fileURLToPath(new URL("../../../release/zero-to-map/journey.v1.json", import.meta.url));
+    let outputPath = "zero-to-map-receipt.json";
+    let honuaCommand = env.HONUA_CLI_COMMAND ?? "honua";
+    let mcpUrl = env.HONUA_MCP_REMOTE_URL ?? env.HONUA_MCP_URL;
+    let target = "local-docker";
+    let checkpointPath;
+    let checkpointDigest;
+    let provisionReceiptPath;
+    let consoleReceiptPath;
+    const variables = {};
+    const receiptPaths = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        switch (arg) {
+            case "--execute":
+                execute = true;
+                break;
+            case "--yes":
+                confirmed = true;
+                break;
+            case "--plan":
+                planPath = requireNext(argv, ++index, arg);
+                break;
+            case "--output":
+                outputPath = requireNext(argv, ++index, arg);
+                break;
+            case "--honua-command":
+                honuaCommand = requireNext(argv, ++index, arg);
+                break;
+            case "--mcp-url":
+                mcpUrl = requireNext(argv, ++index, arg);
+                break;
+            case "--target": {
+                const value = requireNext(argv, ++index, arg);
+                if (value !== "local-docker" && value !== "aws-ecs") {
+                    throw new Error("--target must be local-docker or aws-ecs");
+                }
+                target = value;
+                break;
+            }
+            case "--checkpoint":
+                checkpointPath = requireNext(argv, ++index, arg);
+                break;
+            case "--checkpoint-digest":
+                checkpointDigest = requireNext(argv, ++index, arg);
+                if (!/^[0-9a-f]{64}$/.test(checkpointDigest)) {
+                    throw new Error("--checkpoint-digest must be a lowercase SHA-256 digest");
+                }
+                break;
+            case "--provision-receipt":
+                provisionReceiptPath = requireNext(argv, ++index, arg);
+                break;
+            case "--var": {
+                const pair = requireNext(argv, ++index, arg);
+                const separator = pair.indexOf("=");
+                if (separator < 1)
+                    throw new Error("--var requires name=value");
+                variables[pair.slice(0, separator)] = parseVariable(pair.slice(separator + 1));
+                break;
+            }
+            case "--var-env": {
+                const pair = requireNext(argv, ++index, arg);
+                const separator = pair.indexOf("=");
+                if (separator < 1)
+                    throw new Error("--var-env requires name=ENV_NAME");
+                const name = pair.slice(0, separator);
+                const envName = pair.slice(separator + 1);
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(envName))
+                    throw new Error("--var-env requires a valid environment name");
+                const value = env[envName];
+                if (!value)
+                    throw new Error(`--var-env ${name} references a missing or empty environment value`);
+                variables[name] = parseVariable(value);
+                break;
+            }
+            case "--console-receipt": {
+                consoleReceiptPath = requireNext(argv, ++index, arg);
+                receiptPaths["console-approval"] = consoleReceiptPath;
+                break;
+            }
+            case "--help":
+                printHelp();
+                throw new HelpRequested();
+            default:
+                throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return {
+        execute,
+        confirmed,
+        planPath,
+        outputPath,
+        honuaCommand,
+        target,
+        ...(mcpUrl ? { mcpUrl } : {}),
+        ...(checkpointPath ? { checkpointPath } : {}),
+        ...(checkpointDigest ? { checkpointDigest } : {}),
+        ...(provisionReceiptPath ? { provisionReceiptPath } : {}),
+        ...(consoleReceiptPath ? { consoleReceiptPath } : {}),
+        ...(env.HONUA_SOURCE_REVISION ? { sourceRevision: env.HONUA_SOURCE_REVISION } : {}),
+        variables,
+        receiptPaths,
+    };
+}
+async function prepareLiveOptions(options, env) {
+    if (!options.sourceRevision || !/^[0-9a-f]{40}$/.test(options.sourceRevision)) {
+        throw new Error("HONUA_SOURCE_REVISION must be the exact 40-character SDK candidate SHA");
+    }
+    if (!options.mcpUrl)
+        throw new Error("--mcp-url is required for live execution");
+    requireSecureCredentialEndpoint(options.mcpUrl, "--mcp-url");
+    resolveJourneyProxyOptions(options.mcpUrl, env);
+    requireBindingVariable(options.variables, "candidateId");
+    requireBindingVariable(options.variables, "releaseId");
+    if (options.target === "local-docker") {
+        if (options.provisionReceiptPath)
+            throw new Error("--provision-receipt is valid only with --target aws-ecs");
+        return { ...options, honuaCommand: await resolveLiveExecutable(options.honuaCommand, env, process.cwd()) };
+    }
+    if (!options.provisionReceiptPath)
+        throw new Error("--target aws-ecs requires --provision-receipt");
+    const provisionBytes = await readFile(options.provisionReceiptPath);
+    const provisionBinding = parseAwsEcsProvisionBinding(JSON.parse(provisionBytes.toString("utf8")));
+    assertAwsEcsProvisionBindings(provisionBinding, {
+        candidateId: requireBindingVariable(options.variables, "candidateId"),
+        releaseId: requireBindingVariable(options.variables, "releaseId"),
+        mcpUrl: options.mcpUrl,
+    });
+    return {
+        ...options,
+        provisionBinding,
+        provisionReceiptSha256: createHash("sha256").update(provisionBytes).digest("hex"),
+    };
+}
+function resolveJourneyProxyOptions(mcpUrl, env) {
+    return resolveProxyOptions({
+        HONUA_MCP_REMOTE_URL: mcpUrl,
+        HONUA_MCP_AUTH_TOKEN: env.HONUA_MCP_AUTH_TOKEN,
+        HONUA_ADMIN_KEY: env.HONUA_ADMIN_KEY,
+        HONUA_API_KEY: env.HONUA_API_KEY,
+    });
+}
+/** Resolve the live mutating CLI without permitting Windows' cwd-first executable search. */
+export async function resolveLiveExecutable(command, env, excludedDirectory) {
+    if (path.isAbsolute(command))
+        return verifyLiveExecutable(command, excludedDirectory);
+    if (command.includes("/") || command.includes("\\")) {
+        throw new Error(`Live Honua CLI path must be absolute: ${command}`);
+    }
+    const names = process.platform === "win32" ? windowsExecutableNames(command, env.PATHEXT) : [command];
+    for (const rawDirectory of (env.PATH ?? "").split(path.delimiter)) {
+        const directory = rawDirectory.trim().replace(/^"|"$/g, "");
+        if (!directory || !path.isAbsolute(directory))
+            continue;
+        for (const name of names) {
+            try {
+                return await verifyLiveExecutable(path.join(directory, name), excludedDirectory);
+            }
+            catch {
+                // Continue through the absolute PATH roster, never the working directory.
+            }
+        }
+    }
+    throw new Error(`Live Honua CLI was not found in an absolute PATH entry: ${command}`);
+}
+function windowsExecutableNames(command, pathExt) {
+    if (path.extname(command))
+        return [command];
+    return [...new Set((pathExt ?? ".COM;.EXE;.BAT;.CMD").split(";").map((value) => value.trim().toLowerCase()))]
+        .filter((extension) => /^\.[a-z0-9]+$/.test(extension))
+        .map((extension) => `${command}${extension}`);
+}
+async function verifyLiveExecutable(candidate, excludedDirectory) {
+    const [resolved, excluded] = await Promise.all([
+        realpath(candidate),
+        realpath(excludedDirectory).catch(() => path.resolve(excludedDirectory)),
+    ]);
+    const relative = path.relative(excluded, resolved);
+    if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+        throw new Error("Refusing to execute the live Honua CLI from the working directory.");
+    }
+    const metadata = await lstat(resolved);
+    if (!metadata.isFile())
+        throw new Error("Live Honua CLI is not a regular file.");
+    if (process.platform !== "win32")
+        await access(resolved, constants.X_OK);
+    return resolved;
+}
+function checkpointBindings(options, journeyId, releaseContract, planBytes) {
+    if (!options.sourceRevision || !options.mcpUrl)
+        throw new Error("live checkpoint bindings are incomplete");
+    return {
+        journeyId,
+        releaseContract,
+        target: options.target,
+        planSha256: createHash("sha256").update(planBytes).digest("hex"),
+        sourceRevision: options.sourceRevision,
+        mcpEndpointSha256: createHash("sha256").update(normalizeEndpoint(options.mcpUrl)).digest("hex"),
+        candidateId: requireBindingVariable(options.variables, "candidateId"),
+        releaseId: requireBindingVariable(options.variables, "releaseId"),
+        ...(options.provisionReceiptSha256 ? { provisionReceiptSha256: options.provisionReceiptSha256 } : {}),
+    };
+}
+function normalizeEndpoint(value) {
+    const url = new URL(value);
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+function requireBindingVariable(variables, name) {
+    const value = variables[name];
+    if (typeof value !== "string" || !value)
+        throw new Error(`--var ${name}=... is required for live execution`);
+    return value;
+}
+async function readCheckpointIfPresent(path) {
+    try {
+        return parseZeroToMapCheckpoint(JSON.parse(await readFile(path, "utf8")));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function writeJsonNew(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+}
+/** Atomically transfer one paused checkpoint to a single resume owner. */
+export async function claimZeroToMapCheckpoint(path, digest) {
+    if (!/^[0-9a-f]{64}$/.test(digest))
+        throw new Error("checkpoint claim digest must be a lowercase SHA-256");
+    const checkpoint = await readCheckpointIfPresent(path);
+    if (!checkpoint)
+        throw new Error("checkpoint is already claimed by another resume");
+    if (checkpoint.state !== "paused")
+        throw new Error("checkpoint has already been consumed");
+    assertZeroToMapCheckpointDigest(checkpoint, digest);
+    const claimPath = `${path}.claimed-${digest}`;
+    const lockPath = `${claimPath}.lock`;
+    let lockCreated = false;
+    try {
+        const lock = await open(lockPath, "wx");
+        await lock.close();
+        lockCreated = true;
+        await rename(path, claimPath);
+        return claimPath;
+    }
+    catch (error) {
+        if (lockCreated)
+            await unlink(lockPath).catch(() => undefined);
+        const code = error.code;
+        throw new Error(code === "ENOENT" || code === "EEXIST"
+            ? "checkpoint is already claimed by another resume"
+            : `could not atomically claim checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function runProcess(command, args, env) {
+    return new Promise((resolve, reject) => {
+        const childEnv = process.platform === "win32" ? { ...env, NoDefaultCurrentDirectoryInExePath: "1" } : env;
+        const isWindowsShim = process.platform === "win32" && [".bat", ".cmd"].includes(path.extname(command).toLowerCase());
+        const child = spawn(isWindowsShim ? "C:\\Windows\\System32\\cmd.exe" : command, isWindowsShim ? ["/d", "/s", "/c", windowsCommandLine([command, ...args])] : [...args], {
+            env: childEnv,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const stdout = [];
+        const stderr = [];
+        let outputBytes = 0;
+        let outputExceeded = false;
+        const collect = (target, chunk) => {
+            outputBytes += chunk.byteLength;
+            if (outputBytes > 1024 * 1024) {
+                outputExceeded = true;
+                child.kill();
+                return;
+            }
+            target.push(chunk);
+        };
+        child.stdout.on("data", (chunk) => collect(stdout, chunk));
+        child.stderr.on("data", (chunk) => collect(stderr, chunk));
+        child.once("error", (error) => {
+            const code = error.code;
+            if (code === "ENOENT") {
+                reject(new JourneyBlockedError(`Control-plane CLI command was not found: ${command}`, "control-plane-cli-missing"));
+            }
+            else {
+                reject(error);
+            }
+        });
+        child.once("close", (code) => {
+            if (outputExceeded) {
+                reject(new Error("honua CLI exceeded the bounded command-output limit; output was suppressed"));
+                return;
+            }
+            resolve({
+                exitCode: code ?? 1,
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+            });
+        });
+    });
+}
+function windowsCommandLine(args) {
+    return args.map((value) => `"${value.replaceAll('"', '\\"')}"`).join(" ");
+}
+export function parseInstallAccessCredential(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error("local installer did not emit a valid secret-free access credential receipt");
+    }
+    const root = releaseRecord(parsed, "local installer receipt");
+    releaseExactKeys(root, [
+        "accessCredential",
+        "adminKeyWritten",
+        "baseUrl",
+        "claudeDesktopConfigFile",
+        "composeFile",
+        "directory",
+        "envFile",
+        "mcpConfigFile",
+        "profile",
+        "readyUrl",
+        "reused",
+        "serverImage",
+        "status",
+    ], "local installer receipt");
+    const credential = releaseRecord(root.accessCredential, "local installer access credential");
+    releaseExactKeys(credential, [
+        "canAuthenticate",
+        "effectiveGrants",
+        "id",
+        "name",
+        "provisioned",
+        "referenceDigestSha256",
+        "referenceType",
+        "requestedGrants",
+        "status",
+    ], "local installer access credential");
+    const id = releaseText(credential.id, "local installer access credential id");
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) {
+        throw new Error("local installer access credential id is invalid");
+    }
+    const requestedGrants = releaseStringList(credential.requestedGrants, "local installer access credential requested grants");
+    const effectiveGrants = releaseStringList(credential.effectiveGrants, "local installer access credential effective grants");
+    if (stableStringSet(requestedGrants) !== stableStringSet(effectiveGrants)) {
+        throw new Error("local installer requested and effective access grants do not match");
+    }
+    if (stableStringSet(requestedGrants) !== stableStringSet(ZERO_TO_MAP_ACCESS_GRANTS)) {
+        throw new Error("local installer access credential is not scoped to the required release grants");
+    }
+    if (credential.status !== "active" ||
+        credential.canAuthenticate !== true ||
+        credential.referenceType !== "private-env-file" ||
+        typeof credential.provisioned !== "boolean") {
+        throw new Error("local installer access credential is not an active private-file handoff");
+    }
+    const referenceDigestSha256 = releaseText(credential.referenceDigestSha256, "local installer access credential reference digest");
+    if (!/^[0-9a-f]{64}$/.test(referenceDigestSha256)) {
+        throw new Error("local installer access credential reference digest is invalid");
+    }
+    return {
+        id,
+        name: releaseText(credential.name, "local installer access credential name"),
+        status: "active",
+        requestedGrants,
+        effectiveGrants,
+        canAuthenticate: true,
+        referenceType: "private-env-file",
+        referenceDigestSha256,
+        provisioned: credential.provisioned,
+    };
+}
+function releaseRecord(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${path} must be an object`);
+    return value;
+}
+function releaseExactKeys(value, expected, path) {
+    const actual = Object.keys(value).sort();
+    const allowed = [...expected].sort();
+    if (actual.length !== allowed.length || actual.some((key, index) => key !== allowed[index])) {
+        throw new Error(`${path} contains unexpected or missing fields`);
+    }
+}
+function releaseText(value, path) {
+    if (typeof value !== "string" || !value)
+        throw new Error(`${path} must be a non-empty string`);
+    return value;
+}
+function releaseStringList(value, path) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || !item)) {
+        throw new Error(`${path} must be a non-empty string array`);
+    }
+    return value;
+}
+function stableStringSet(value) {
+    return [...new Set(value)].sort().join("\n");
+}
+function toolErrorMessage(value) {
+    if (value && typeof value === "object") {
+        const result = value;
+        if (result.structuredContent)
+            return JSON.stringify(result.structuredContent);
+        if (Array.isArray(result.content)) {
+            const text = result.content.find((block) => Boolean(block) && typeof block === "object" && block.type === "text");
+            if (text && typeof text.text === "string")
+                return text.text;
+        }
+    }
+    return "no structured error was returned";
+}
+/** Poll one MCP job resource to its declared successful terminal state. */
+export async function readJourneyMcpResource(action, read) {
+    const startedAt = Date.now();
+    for (;;) {
+        const result = await read(action.uri);
+        const body = readJsonResource(result, action.uri);
+        const wait = action.waitFor;
+        if (!wait)
+            return { value: result, evidence: { uri: action.uri } };
+        const actual = resourceJsonPointer(body, wait.pointer);
+        if (wait.terminal.includes(String(actual))) {
+            if (actual !== wait.equals) {
+                throw new Error(`${action.uri} reached terminal ${String(actual)}; expected ${wait.equals}`);
+            }
+            return {
+                value: result,
+                evidence: { uri: action.uri, [wait.pointer.slice(1) || "value"]: actual },
+            };
+        }
+        if (Date.now() - startedAt >= wait.deadlineMs) {
+            throw new Error(`${action.uri} did not reach ${wait.equals} within ${wait.deadlineMs}ms`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, wait.pollIntervalMs));
+    }
+}
+function readJsonResource(value, uri) {
+    if (!value || typeof value !== "object")
+        throw new Error(`${uri} returned an invalid resources/read response`);
+    const contents = value.contents;
+    if (!Array.isArray(contents))
+        throw new Error(`${uri} returned no resource contents`);
+    const content = contents.find((candidate) => Boolean(candidate) && typeof candidate === "object" && typeof candidate.text === "string");
+    if (!content)
+        throw new Error(`${uri} returned no JSON text content`);
+    try {
+        return JSON.parse(content.text);
+    }
+    catch {
+        throw new Error(`${uri} returned invalid JSON text content`);
+    }
+}
+function resourceJsonPointer(value, pointer) {
+    if (pointer === "")
+        return value;
+    if (!pointer.startsWith("/"))
+        throw new Error(`invalid resource JSON pointer: ${pointer}`);
+    let current = value;
+    for (const raw of pointer.slice(1).split("/")) {
+        const key = raw.replaceAll("~1", "/").replaceAll("~0", "~");
+        if (!current || typeof current !== "object" || Array.isArray(current))
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+export function requireCompletedPublishedOperation(tool, value) {
+    const operation = publishedOperation(value);
+    if (!operation)
+        return undefined;
+    const status = operation.status.toLowerCase();
+    if (status === "requiresapproval" || status === "queued") {
+        throw new JourneyBlockedError(`${tool} returned ${operation.status}; handle=${operation.handleId ?? "unknown"}, approvalLane=${operation.approvalLane ?? "none"}, job=${operation.jobId ?? "none"}.`, status === "requiresapproval" ? "operation-approval-required" : "operation-queued");
+    }
+    if (status !== "completed") {
+        throw new Error(`${tool} operation ${operation.operationId} returned status ${operation.status}`);
+    }
+    return operation;
+}
+function publishedOperation(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const structured = value.structuredContent;
+    if (!structured || typeof structured !== "object" || Array.isArray(structured))
+        return undefined;
+    const body = structured;
+    if (typeof body.operationId !== "string" || !body.operationId.startsWith("admin."))
+        return undefined;
+    if (typeof body.status !== "string")
+        throw new Error(`${body.operationId} omitted its published-operation status`);
+    return {
+        operationId: body.operationId,
+        status: body.status,
+        ...(typeof body.handleId === "string" ? { handleId: body.handleId } : {}),
+        ...(typeof body.approvalLane === "string" ? { approvalLane: body.approvalLane } : {}),
+        ...(typeof body.jobId === "string" ? { jobId: body.jobId } : {}),
+        ...(typeof body.metadataRevision === "number" ? { metadataRevision: body.metadataRevision } : {}),
+    };
+}
+function redactCliArgs(args) {
+    const redacted = [...args];
+    for (let index = 0; index < redacted.length; index += 1) {
+        const argument = redacted[index] ?? "";
+        if (["--api-key", "--admin-key", "--password", "--token"].includes(argument)) {
+            if (index + 1 < redacted.length)
+                redacted[index + 1] = "[REDACTED]";
+        }
+        else if (["--api-key", "--admin-key", "--password", "--token"].some((flag) => argument.startsWith(`${flag}=`))) {
+            redacted[index] = `${argument.slice(0, argument.indexOf("=") + 1)}[REDACTED]`;
+        }
+    }
+    return redacted;
+}
+function parseVariable(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+(?:\.\d+)?$/.test(value))
+        return Number(value);
+    return value;
+}
+function requireNext(argv, index, option) {
+    const value = argv[index];
+    if (!value)
+        throw new Error(`${option} requires a value`);
+    return value;
+}
+function printHelp() {
+    process.stdout.write("Usage: honua-zero-to-map-release [options]\n\n");
+    process.stdout.write("Without --execute, validates the plan and writes an explicitly blocked contract receipt.\n\n");
+    process.stdout.write("  --execute --yes           Run the state-changing candidate journey\n");
+    process.stdout.write("  --plan <path>             Override the checked-in journey plan\n");
+    process.stdout.write("  --output <path>           Receipt output (default zero-to-map-receipt.json)\n");
+    process.stdout.write("  --mcp-url <url>           Server /mcp URL consumed through honua-mcp-proxy\n");
+    process.stdout.write("  --target <name>           local-docker (default) or aws-ecs\n");
+    process.stdout.write("  --provision-receipt <p>   Required pre-teardown binding for aws-ecs\n");
+    process.stdout.write("  --honua-command <path>    Control-plane CLI executable (default honua)\n");
+    process.stdout.write("  --var name=value          Supply a journey variable; repeat as needed\n");
+    process.stdout.write("  --var-env name=ENV_NAME   Read a secret variable from the child environment\n");
+    process.stdout.write("  --checkpoint <path>       Persist the secret-free Console pause/resume boundary\n");
+    process.stdout.write("  --checkpoint-digest <sha> Externally carried digest required to claim a resume\n");
+    process.stdout.write("  --console-receipt <path>  Import the separately captured Console gate receipt\n");
+}
+class HelpRequested extends Error {
+}
+if (isMainEntrypoint(import.meta.url)) {
+    runZeroToMapCli().then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        if (error instanceof HelpRequested) {
+            process.exitCode = 0;
+            return;
+        }
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}