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

package/dist/src/index.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import { HonuaClient } from "@honua/sdk-js";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { isMainEntrypoint } from "./entrypoint.js";
 import { registerNlMapControlMcpTools } from "./nl-map-control.js";
 import * as layerSchemaResource from "./resources/layer-schema.js";
 import * as servicesResource from "./resources/services.js";
 import * as stylesResource from "./resources/styles.js";
+import * as adminInstallLocal from "./tools/admin-install-local.js";
 import * as applyStylePreset from "./tools/apply-style-preset.js";
+import * as controlPlaneCommand from "./tools/control-plane-command.js";
 import * as countFeatures from "./tools/count-features.js";
 import * as describeLayer from "./tools/describe-layer.js";
+import * as docsSearch from "./tools/docs-search.js";
 import * as explainCapabilityGap from "./tools/explain-capability-gap.js";
 import * as getExtent from "./tools/get-extent.js";
 import * as getStyle from "./tools/get-style.js";
@@ -19,6 +22,7 @@ import * as listSources from "./tools/list-sources.js";
 import * as queryFeatures from "./tools/query-features.js";
 import * as statistics from "./tools/statistics.js";
 export { createNlMapControlMcpHost, registerNlMapControlMcpTools, } from "./nl-map-control.js";
+export { CONTROL_PLANE_COMMAND_TOOL_PREFIX, controlPlaneCommandToolName, controlPlaneCommandToolSchema, registerControlPlaneCommandTools, } from "./tools/control-plane-command.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_SERVER_VERSION = "0.0.3-alpha.0";
@@ -146,6 +150,15 @@ export function createClientFromEnv(env = process.env) {
  * mutation, jobs, and publishing — is a superset reached over streamable-HTTP and
  * mirrored to stdio by `honua-mcp-proxy` ({@link runProxy}); it requires a Honua
  * deployment. Standalone is the front door; the proxy is the upgrade path.
+ * Local installation is intentionally absent from this catalog and is exposed
+ * only by {@link createBootstrapServer}.
+ *
+ * Control-plane MUTATION is likewise absent by default, and when a host does
+ * enable it ({@link CreateServerOptions.controlPlaneCommands}) MCP does not get
+ * a workflow of its own: the tools are generated from the shared command
+ * catalog in `@honua/sdk-js/control-plane`, so an MCP invocation and the
+ * equivalent `honua` CLI, Studio, or direct-JS invocation share one
+ * implementation and one receipt `auditKey`.
  */
 export function createServer(client, options = {}) {
     const server = new McpServer({
@@ -166,6 +179,12 @@ export function createServer(client, options = {}) {
     server.tool("honua_explain_capability_gap", "Explain whether a source/protocol supports a capability and suggest a safe fallback when it does not.", explainCapabilityGap.schema.shape, async (args) => explainCapabilityGap.execute(client, explainCapabilityGap.schema.parse(args)));
     server.tool("honua_get_style", "Resolve a style from a server's OGC API – Styles surface. Pass styleId for the canonical StyleRef (style_id, title, encodings incl. inlined MapLibre); omit it to list available styles. On a plain FeatureServer with no styling surface, reports a structured 'not available on this target' result.", getStyle.schema.shape, async (args) => getStyle.execute(client, getStyle.schema.parse(args)));
     server.tool("honua_apply_style_preset", "Resolve a style preset and its MapLibre stylesheet for client-side application. Read-only: returns the stylesheet to apply locally; it does not mutate server state. Degrades gracefully on a target with no styling surface.", applyStylePreset.schema.shape, async (args) => applyStylePreset.execute(client, applyStylePreset.schema.parse(args)));
+    if (options.controlPlaneCommands) {
+        // Thin adapters generated from the shared command catalog. Registered last
+        // so the platform-free read-only surface keeps its stable tool order.
+        controlPlaneCommand.registerControlPlaneCommandTools(server, options.controlPlaneCommands);
+    }
+    server.tool("honua_docs_search", "Answer a Honua documentation question from the local versioned documentation corpus (llms-full.txt), returning ranked excerpts with a source-file and release-version citation for each hit. Local and offline: reads committed docs, never the network. Use it before guessing at an API, a CLI flag, or a contract. Reports a structured 'not available' result when the corpus is not present in this installation.", docsSearch.schema.shape, { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => docsSearch.execute(client, docsSearch.schema.parse(args)));
     // ── Resources ──────────────────────────────────────────────────
     server.resource("services-catalog", servicesResource.uri, async (_uri) => servicesResource.read(client));
     server.resource("layer-schema", new ResourceTemplate(layerSchemaResource.uriTemplate, { list: undefined }), async (_uri, params) => layerSchemaResource.read(client, params.encodedServiceId, params.layerId));
@@ -173,6 +192,15 @@ export function createServer(client, options = {}) {
     server.resource("style", new ResourceTemplate(stylesResource.uriTemplate, { list: undefined }), async (_uri, params) => stylesResource.read(client, params.styleId));
     return server;
 }
+/** Bootstrap-only MCP surface for a laptop that does not have Honua yet. */
+export function createBootstrapServer() {
+    const server = new McpServer({ name: "honua-bootstrap", version: SERVER_VERSION });
+    registerLocalInstallTool(server);
+    return server;
+}
+function registerLocalInstallTool(server) {
+    server.tool("honua_admin_install_local", "Install the manifest-pinned Honua Server, PostGIS, and Redis on this laptop, wait for readiness, bootstrap a scoped admin key, and write proxy MCP configuration. Requires confirm=true.", adminInstallLocal.schema.shape, { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }, async (args) => adminInstallLocal.execute(adminInstallLocal.schema.parse(args)));
+}
 /* v8 ignore start -- live-process entry: wires the stdio transport to a real
    SDK client against HONUA_BASE_URL; exercised by running the bin, not unit tests.
    The unit-testable logic (option resolution, client construction, server wiring)
@@ -181,14 +209,14 @@ export function createServer(client, options = {}) {
  * Run the platform-free standalone server end-to-end over stdio.
  *
  * Builds a `HonuaClient` from the environment (`HONUA_BASE_URL` + optional
- * transport/auth) and exposes {@link createServer} — the nine read-only tools —
+ * transport/auth) and exposes {@link createServer} — the ten read-only tools —
  * to a stdio MCP client (Claude Desktop / Claude Code / any MCP agent). Point
  * `HONUA_BASE_URL` at any public FeatureServer/OGC endpoint; no Honua server is
  * required. For the Honua-enhanced `/mcp` catalog, use `honua-mcp-proxy` instead.
  */
 export async function runStandalone(env = process.env) {
-    const client = createClientFromEnv(env);
-    const server = createServer(client);
+    const bootstrapOnly = env.HONUA_MCP_BOOTSTRAP === "1" || env.HONUA_MCP_BOOTSTRAP === "true";
+    const server = bootstrapOnly ? createBootstrapServer() : createServer(createClientFromEnv(env));
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
@@ -196,7 +224,7 @@ export async function runStandalone(env = process.env) {
 async function main() {
     await runStandalone();
 }
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (isMainEntrypoint(import.meta.url)) {
     main().catch((err) => {
         process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
         process.exit(1);

package/dist/src/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAiBnE;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAqBtF;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASlF;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+C1D;AAOD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlF"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/proxy.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAmBnE;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAsBD,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAqBtF;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUlF;AAED,oFAAoF;AACpF,wBAAsB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAS5E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+C1D;AAOD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlF"}

package/dist/src/proxy.js

@@ -1,34 +1,48 @@
 #!/usr/bin/env node
-import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, PromptListChangedNotificationSchema, ReadResourceRequestSchema, ResourceListChangedNotificationSchema, ToolListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { requireSecureCredentialEndpoint } from "./credential-endpoint.js";
+import { isMainEntrypoint } from "./entrypoint.js";
 import { SERVER_VERSION } from "./index.js";
+function isConfigured(value) {
+    return value !== undefined && value.length > 0;
+}
+function validateAuthentication(options) {
+    const hasBearer = isConfigured(options.authToken);
+    const hasApiKey = isConfigured(options.apiKey);
+    if (hasBearer && hasApiKey) {
+        throw new Error("Configure exactly one upstream authentication scheme: unset either authToken/HONUA_MCP_AUTH_TOKEN or apiKey/HONUA_ADMIN_KEY/HONUA_API_KEY");
+    }
+    return hasBearer ? "bearer" : hasApiKey ? "api-key" : "anonymous";
+}
+function validateProxyOptions(options) {
+    const authMode = validateAuthentication(options);
+    return requireSecureCredentialEndpoint(options.remoteUrl, "remoteUrl", authMode !== "anonymous");
+}
 export function resolveProxyOptions(env = process.env) {
     const remoteUrl = env.HONUA_MCP_REMOTE_URL ?? env.HONUA_MCP_URL;
     if (!remoteUrl) {
         throw new Error("HONUA_MCP_REMOTE_URL environment variable is required (the remote honua /mcp endpoint to proxy).");
     }
-    let parsed;
-    try {
-        parsed = new URL(remoteUrl);
-    }
-    catch {
-        throw new Error(`HONUA_MCP_REMOTE_URL must be a valid absolute URL: ${remoteUrl}`);
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new Error(`HONUA_MCP_REMOTE_URL must use http or https: ${remoteUrl}`);
+    const hasAdminKey = isConfigured(env.HONUA_ADMIN_KEY);
+    const hasApiKey = isConfigured(env.HONUA_API_KEY);
+    if (hasAdminKey && hasApiKey) {
+        throw new Error("Configure one API-key source: unset either HONUA_ADMIN_KEY or HONUA_API_KEY; credential precedence is not allowed");
     }
-    return {
-        remoteUrl: parsed.toString(),
+    const options = {
+        remoteUrl,
         authToken: env.HONUA_MCP_AUTH_TOKEN,
-        apiKey: env.HONUA_API_KEY,
+        apiKey: hasAdminKey ? env.HONUA_ADMIN_KEY : hasApiKey ? env.HONUA_API_KEY : undefined,
     };
+    const parsed = validateProxyOptions(options);
+    return { ...options, remoteUrl: parsed.toString() };
 }
 /** Build request headers for the upstream connection from the resolved options. */
 export function buildUpstreamHeaders(options) {
+    validateProxyOptions(options);
     const headers = {};
     if (options.authToken) {
         headers.Authorization = `Bearer ${options.authToken}`;
@@ -41,8 +55,9 @@ export function buildUpstreamHeaders(options) {
 /** Connect an upstream MCP client to the remote honua /mcp over streamable HTTP. */
 export async function connectUpstream(options) {
     const headers = buildUpstreamHeaders(options);
-    const transport = new StreamableHTTPClientTransport(new URL(options.remoteUrl), {
-        requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+    const remoteUrl = validateProxyOptions(options);
+    const transport = new StreamableHTTPClientTransport(remoteUrl, {
+        requestInit: { ...(Object.keys(headers).length > 0 ? { headers } : {}), redirect: "manual" },
     });
     const client = new Client({ name: "honua-mcp-stdio-proxy", version: SERVER_VERSION });
     await client.connect(transport);
@@ -115,7 +130,7 @@ export async function runProxy(env = process.env) {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+if (isMainEntrypoint(import.meta.url)) {
     runProxy().catch((err) => {
         process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
         process.exit(1);

package/dist/src/release/zero-to-map-checkpoint.d.ts

@@ -0,0 +1,34 @@
+import { type JourneyPauseSnapshot, type JourneyReceiptRequest, type JourneyResumeState } from "./zero-to-map.js";
+export declare const ZERO_TO_MAP_CHECKPOINT_SCHEMA: "honua.zero-to-map.checkpoint/v1";
+export declare const ZERO_TO_MAP_CHECKPOINT_MAX_AGE_MS: number;
+export interface ZeroToMapCheckpointBindings {
+    readonly journeyId: string;
+    readonly releaseContract: string;
+    readonly target: "local-docker" | "aws-ecs";
+    readonly planSha256: string;
+    readonly sourceRevision: string;
+    readonly mcpEndpointSha256: string;
+    readonly candidateId: string;
+    readonly releaseId: string;
+    readonly provisionReceiptSha256?: string;
+}
+export interface ZeroToMapCheckpoint extends ZeroToMapCheckpointBindings {
+    readonly schemaVersion: typeof ZERO_TO_MAP_CHECKPOINT_SCHEMA;
+    readonly state: "paused" | "consumed";
+    readonly createdAt: string;
+    readonly resume: JourneyResumeState;
+    readonly consoleReceiptRequest: JourneyReceiptRequest;
+    readonly consumedAt?: string;
+    readonly finalReceiptSha256?: string;
+    readonly integrity: {
+        readonly algorithm: "sha256";
+        readonly digest: string;
+    };
+}
+export declare function createZeroToMapCheckpoint(bindings: ZeroToMapCheckpointBindings, snapshot: JourneyPauseSnapshot, createdAt?: string): ZeroToMapCheckpoint;
+export declare function consumeZeroToMapCheckpoint(checkpoint: ZeroToMapCheckpoint, finalReceiptSha256: string, consumedAt?: string): ZeroToMapCheckpoint;
+export declare function parseZeroToMapCheckpoint(value: unknown): ZeroToMapCheckpoint;
+export declare function assertZeroToMapCheckpointFresh(checkpoint: ZeroToMapCheckpoint, now?: Date): void;
+export declare function assertZeroToMapCheckpointDigest(checkpoint: ZeroToMapCheckpoint, expectedDigest: string): void;
+export declare function assertZeroToMapCheckpointBindings(checkpoint: ZeroToMapCheckpoint, expected: ZeroToMapCheckpointBindings): void;
+//# sourceMappingURL=zero-to-map-checkpoint.d.ts.map

package/dist/src/release/zero-to-map-checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zero-to-map-checkpoint.d.ts","sourceRoot":"","sources":["../../../src/release/zero-to-map-checkpoint.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE1B,KAAK,kBAAkB,EAMxB,MAAM,kBAAkB,CAAC;AAE1B,eAAO,MAAM,6BAA6B,EAAG,iCAA0C,CAAC;AACxF,eAAO,MAAM,iCAAiC,QAAuB,CAAC;AAEtE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,mBAAoB,SAAQ,2BAA2B;IACtE,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;QAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAID,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,2BAA2B,EACrC,QAAQ,EAAE,oBAAoB,EAC9B,SAAS,SAA2B,GACnC,mBAAmB,CAqBrB;AAED,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,mBAAmB,EAC/B,kBAAkB,EAAE,MAAM,EAC1B,UAAU,SAA2B,GACpC,mBAAmB,CAIrB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAkF5E;AAED,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,mBAAmB,EAAE,GAAG,OAAa,GAAG,IAAI,CAKtG;AAED,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAI7G;AAED,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,mBAAmB,EAC/B,QAAQ,EAAE,2BAA2B,GACpC,IAAI,CAIN"}

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

@@ -0,0 +1,369 @@
+import { createHash } from "node:crypto";
+import { ZERO_TO_MAP_CATALOG_RECEIPT_SCHEMA, ZERO_TO_MAP_CONSOLE_RECEIPT_REQUEST_SCHEMA, } from "./zero-to-map.js";
+export const ZERO_TO_MAP_CHECKPOINT_SCHEMA = "honua.zero-to-map.checkpoint/v1";
+export const ZERO_TO_MAP_CHECKPOINT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+export function createZeroToMapCheckpoint(bindings, snapshot, createdAt = new Date().toISOString()) {
+    assertTargetBinding(bindings);
+    const payload = {
+        schemaVersion: ZERO_TO_MAP_CHECKPOINT_SCHEMA,
+        state: "paused",
+        createdAt,
+        ...bindings,
+        resume: {
+            startedAt: snapshot.startedAt,
+            capturedVariables: snapshot.capturedVariables,
+            completedStages: snapshot.completedStages,
+            resumeAt: snapshot.resumeAt,
+            // Carried across the Console boundary because no post-checkpoint stage
+            // can re-derive it; the resumed run's final receipt would otherwise
+            // overwrite the pre-pause receipt with one that has no catalog evidence.
+            ...(snapshot.catalog ? { catalog: snapshot.catalog } : {}),
+        },
+        consoleReceiptRequest: snapshot.consoleReceiptRequest,
+    };
+    assertSecretFree(payload);
+    return seal(payload);
+}
+export function consumeZeroToMapCheckpoint(checkpoint, finalReceiptSha256, consumedAt = new Date().toISOString()) {
+    if (checkpoint.state !== "paused")
+        throw new Error("checkpoint has already been consumed");
+    const { integrity: _integrity, ...prior } = checkpoint;
+    return seal({ ...prior, state: "consumed", consumedAt, finalReceiptSha256 });
+}
+export function parseZeroToMapCheckpoint(value) {
+    const checkpoint = object(value, "checkpoint");
+    exactKeys(checkpoint, [
+        "schemaVersion",
+        "state",
+        "createdAt",
+        "journeyId",
+        "releaseContract",
+        "target",
+        "planSha256",
+        "sourceRevision",
+        "mcpEndpointSha256",
+        "candidateId",
+        "releaseId",
+        "provisionReceiptSha256",
+        "resume",
+        "consoleReceiptRequest",
+        "consumedAt",
+        "finalReceiptSha256",
+        "integrity",
+    ], "checkpoint");
+    if (checkpoint.schemaVersion !== ZERO_TO_MAP_CHECKPOINT_SCHEMA) {
+        throw new Error(`checkpoint.schemaVersion must be ${ZERO_TO_MAP_CHECKPOINT_SCHEMA}`);
+    }
+    if (checkpoint.state !== "paused" && checkpoint.state !== "consumed") {
+        throw new Error("checkpoint.state must be paused or consumed");
+    }
+    const createdAt = timestamp(checkpoint.createdAt, "checkpoint.createdAt");
+    const bindings = {
+        journeyId: text(checkpoint.journeyId, "checkpoint.journeyId"),
+        releaseContract: text(checkpoint.releaseContract, "checkpoint.releaseContract"),
+        target: target(checkpoint.target),
+        planSha256: sha256(checkpoint.planSha256, "checkpoint.planSha256"),
+        sourceRevision: revision(checkpoint.sourceRevision, "checkpoint.sourceRevision"),
+        mcpEndpointSha256: sha256(checkpoint.mcpEndpointSha256, "checkpoint.mcpEndpointSha256"),
+        candidateId: text(checkpoint.candidateId, "checkpoint.candidateId"),
+        releaseId: text(checkpoint.releaseId, "checkpoint.releaseId"),
+        ...(checkpoint.provisionReceiptSha256 === undefined
+            ? {}
+            : {
+                provisionReceiptSha256: sha256(checkpoint.provisionReceiptSha256, "checkpoint.provisionReceiptSha256"),
+            }),
+    };
+    assertTargetBinding(bindings);
+    const resume = parseResume(checkpoint.resume);
+    const consoleReceiptRequest = parseReceiptRequest(checkpoint.consoleReceiptRequest);
+    const integrity = object(checkpoint.integrity, "checkpoint.integrity");
+    exactKeys(integrity, ["algorithm", "digest"], "checkpoint.integrity");
+    if (integrity.algorithm !== "sha256")
+        throw new Error("checkpoint.integrity.algorithm must be sha256");
+    const digest = sha256(integrity.digest, "checkpoint.integrity.digest");
+    const state = checkpoint.state;
+    const consumedAt = checkpoint.consumedAt;
+    const finalReceiptSha256 = checkpoint.finalReceiptSha256;
+    if (state === "paused" && (consumedAt !== undefined || finalReceiptSha256 !== undefined)) {
+        throw new Error("paused checkpoint cannot carry consumed receipt fields");
+    }
+    if (state === "consumed" && (consumedAt === undefined || finalReceiptSha256 === undefined)) {
+        throw new Error("consumed checkpoint must carry consumedAt and finalReceiptSha256");
+    }
+    const payload = {
+        schemaVersion: ZERO_TO_MAP_CHECKPOINT_SCHEMA,
+        state,
+        createdAt,
+        ...bindings,
+        resume,
+        consoleReceiptRequest,
+        ...(state === "consumed"
+            ? {
+                consumedAt: timestamp(consumedAt, "checkpoint.consumedAt"),
+                finalReceiptSha256: sha256(finalReceiptSha256, "checkpoint.finalReceiptSha256"),
+            }
+            : {}),
+    };
+    assertSecretFree(payload);
+    const expected = digestPayload(payload);
+    if (digest !== expected)
+        throw new Error("checkpoint integrity digest does not match its canonical payload");
+    return { ...payload, integrity: { algorithm: "sha256", digest } };
+}
+export function assertZeroToMapCheckpointFresh(checkpoint, now = new Date()) {
+    const age = now.getTime() - Date.parse(checkpoint.createdAt);
+    if (age < 0 || age > ZERO_TO_MAP_CHECKPOINT_MAX_AGE_MS) {
+        throw new Error("checkpoint is stale or has a future creation time");
+    }
+}
+export function assertZeroToMapCheckpointDigest(checkpoint, expectedDigest) {
+    if (!/^[0-9a-f]{64}$/.test(expectedDigest) || checkpoint.integrity.digest !== expectedDigest) {
+        throw new Error("externally carried checkpoint digest does not match");
+    }
+}
+export function assertZeroToMapCheckpointBindings(checkpoint, expected) {
+    for (const key of Object.keys(expected)) {
+        if (checkpoint[key] !== expected[key])
+            throw new Error(`checkpoint binding mismatch: ${key}`);
+    }
+}
+function assertTargetBinding(bindings) {
+    if (bindings.target === "aws-ecs" && bindings.provisionReceiptSha256 === undefined) {
+        throw new Error("AWS ECS checkpoint must bind provisionReceiptSha256");
+    }
+    if (bindings.target === "local-docker" && bindings.provisionReceiptSha256 !== undefined) {
+        throw new Error("local Docker checkpoint cannot bind an AWS provision receipt");
+    }
+}
+function seal(payload) {
+    return { ...payload, integrity: { algorithm: "sha256", digest: digestPayload(payload) } };
+}
+function digestPayload(payload) {
+    return createHash("sha256").update(canonicalJson(payload)).digest("hex");
+}
+/** Checkpoints are an allowlisted release handoff, never a credential transport. */
+function assertSecretFree(value, path = "checkpoint") {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => assertSecretFree(item, `${path}[${index}]`));
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, item] of Object.entries(value)) {
+        if (/(?:password|authorization|api[-_]?key|access[-_]?key|secret(?:[-_]?key)?|bearer|token|material)/i.test(key)) {
+            throw new Error(`checkpoint contains a forbidden credential field at ${path}.${key}`);
+        }
+        assertSecretFree(item, `${path}.${key}`);
+    }
+}
+function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value === "object") {
+        const candidate = value;
+        return `{${Object.keys(candidate)
+            .filter((key) => candidate[key] !== undefined)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(candidate[key])}`)
+            .join(",")}}`;
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new Error("checkpoint contains a non-JSON value");
+    return encoded;
+}
+function parseResume(value) {
+    const resume = object(value, "checkpoint.resume");
+    exactKeys(resume, ["startedAt", "capturedVariables", "completedStages", "resumeAt", "catalog"], "checkpoint.resume");
+    const capturedVariables = object(resume.capturedVariables, "checkpoint.resume.capturedVariables");
+    if (!Array.isArray(resume.completedStages))
+        throw new Error("checkpoint.resume.completedStages must be an array");
+    return {
+        startedAt: timestamp(resume.startedAt, "checkpoint.resume.startedAt"),
+        capturedVariables,
+        completedStages: resume.completedStages.map(parseStageReceipt),
+        resumeAt: parseResumePoint(resume.resumeAt),
+        ...(resume.catalog === undefined ? {} : { catalog: parseCatalogReceipt(resume.catalog) }),
+    };
+}
+/**
+ * Catalog preflight evidence restored from the checkpoint. Validated as
+ * strictly as the rest of the payload: it is re-emitted onto the final release
+ * receipt, so a malformed or padded catalog block must not survive the parse.
+ */
+function parseCatalogReceipt(value) {
+    const path = "checkpoint.resume.catalog";
+    const catalog = object(value, path);
+    exactKeys(catalog, [
+        "schemaVersion",
+        "activeProfiles",
+        "expectedTotalTools",
+        "advertisedTotalTools",
+        "baseStaticTools",
+        "baseAdminTools",
+        "auditedExclusions",
+        "profiles",
+        "catalogSha256",
+        "adminRosterSha256",
+        "staticRosterSha256",
+        "exclusionRosterSha256",
+    ], path);
+    if (catalog.schemaVersion !== ZERO_TO_MAP_CATALOG_RECEIPT_SCHEMA) {
+        throw new Error(`${path}.schemaVersion must be ${ZERO_TO_MAP_CATALOG_RECEIPT_SCHEMA}`);
+    }
+    if (!Array.isArray(catalog.profiles))
+        throw new Error(`${path}.profiles must be an array`);
+    return {
+        schemaVersion: ZERO_TO_MAP_CATALOG_RECEIPT_SCHEMA,
+        activeProfiles: stringList(catalog.activeProfiles, `${path}.activeProfiles`),
+        expectedTotalTools: count(catalog.expectedTotalTools, `${path}.expectedTotalTools`),
+        advertisedTotalTools: count(catalog.advertisedTotalTools, `${path}.advertisedTotalTools`),
+        baseStaticTools: count(catalog.baseStaticTools, `${path}.baseStaticTools`),
+        baseAdminTools: count(catalog.baseAdminTools, `${path}.baseAdminTools`),
+        auditedExclusions: count(catalog.auditedExclusions, `${path}.auditedExclusions`),
+        profiles: catalog.profiles.map((profile, index) => parseProfileReceipt(profile, `${path}.profiles[${index}]`)),
+        catalogSha256: sha256(catalog.catalogSha256, `${path}.catalogSha256`),
+        adminRosterSha256: sha256(catalog.adminRosterSha256, `${path}.adminRosterSha256`),
+        staticRosterSha256: sha256(catalog.staticRosterSha256, `${path}.staticRosterSha256`),
+        exclusionRosterSha256: sha256(catalog.exclusionRosterSha256, `${path}.exclusionRosterSha256`),
+    };
+}
+function parseProfileReceipt(value, path) {
+    const profile = object(value, path);
+    exactKeys(profile, ["id", "expectedMembers", "advertisedMembers", "confirmedMembers", "nameResolvedMembers", "rosterSha256"], path);
+    return {
+        id: text(profile.id, `${path}.id`),
+        expectedMembers: count(profile.expectedMembers, `${path}.expectedMembers`),
+        advertisedMembers: count(profile.advertisedMembers, `${path}.advertisedMembers`),
+        confirmedMembers: stringList(profile.confirmedMembers, `${path}.confirmedMembers`),
+        nameResolvedMembers: stringList(profile.nameResolvedMembers, `${path}.nameResolvedMembers`),
+        rosterSha256: sha256(profile.rosterSha256, `${path}.rosterSha256`),
+    };
+}
+function parseResumePoint(value) {
+    const point = object(value, "checkpoint.resume.resumeAt");
+    exactKeys(point, ["stageId", "actionId"], "checkpoint.resume.resumeAt");
+    return {
+        stageId: text(point.stageId, "checkpoint.resume.resumeAt.stageId"),
+        actionId: text(point.actionId, "checkpoint.resume.resumeAt.actionId"),
+    };
+}
+function parseReceiptRequest(value) {
+    const request = object(value, "checkpoint.consoleReceiptRequest");
+    exactKeys(request, ["schemaVersion", "actionId", "receiptSchema", "matches", "requiredPointers", "equalPointers"], "checkpoint.consoleReceiptRequest");
+    if (request.schemaVersion !== ZERO_TO_MAP_CONSOLE_RECEIPT_REQUEST_SCHEMA) {
+        throw new Error(`checkpoint.consoleReceiptRequest.schemaVersion must be ${ZERO_TO_MAP_CONSOLE_RECEIPT_REQUEST_SCHEMA}`);
+    }
+    const matches = object(request.matches, "checkpoint.consoleReceiptRequest.matches");
+    const requiredPointers = stringList(request.requiredPointers, "checkpoint.consoleReceiptRequest.requiredPointers");
+    if (!Array.isArray(request.equalPointers)) {
+        throw new Error("checkpoint.consoleReceiptRequest.equalPointers must be an array");
+    }
+    const equalPointers = request.equalPointers.map((value, index) => {
+        if (!Array.isArray(value) || value.length !== 2 || value.some((item) => typeof item !== "string" || !item)) {
+            throw new Error(`checkpoint.consoleReceiptRequest.equalPointers[${index}] must be a pointer pair`);
+        }
+        return [value[0], value[1]];
+    });
+    return {
+        schemaVersion: ZERO_TO_MAP_CONSOLE_RECEIPT_REQUEST_SCHEMA,
+        actionId: text(request.actionId, "checkpoint.consoleReceiptRequest.actionId"),
+        receiptSchema: text(request.receiptSchema, "checkpoint.consoleReceiptRequest.receiptSchema"),
+        matches,
+        requiredPointers,
+        equalPointers,
+    };
+}
+function parseStageReceipt(value, index) {
+    const path = `checkpoint.resume.completedStages[${index}]`;
+    const stage = object(value, path);
+    exactKeys(stage, ["number", "id", "title", "status", "actions"], path);
+    if (!Number.isInteger(stage.number) || stage.number < 1)
+        throw new Error(`${path}.number must be positive`);
+    if (!Array.isArray(stage.actions))
+        throw new Error(`${path}.actions must be an array`);
+    return {
+        number: stage.number,
+        id: text(stage.id, `${path}.id`),
+        title: text(stage.title, `${path}.title`),
+        status: actionStatus(stage.status, `${path}.status`),
+        actions: stage.actions.map((action, actionIndex) => parseActionReceipt(action, `${path}.actions[${actionIndex}]`)),
+    };
+}
+function parseActionReceipt(value, path) {
+    const action = object(value, path);
+    exactKeys(action, ["id", "kind", "status", "startedAt", "finishedAt", "code", "message", "evidence", "captures"], path);
+    const kind = action.kind;
+    if (!["cli", "mcp", "mcp-resource", "gpserver", "receipt", "http"].includes(String(kind))) {
+        throw new Error(`${path}.kind is invalid`);
+    }
+    return {
+        id: text(action.id, `${path}.id`),
+        kind: kind,
+        status: actionStatus(action.status, `${path}.status`),
+        startedAt: timestamp(action.startedAt, `${path}.startedAt`),
+        finishedAt: timestamp(action.finishedAt, `${path}.finishedAt`),
+        ...(action.code === undefined ? {} : { code: text(action.code, `${path}.code`) }),
+        ...(action.message === undefined ? {} : { message: text(action.message, `${path}.message`) }),
+        ...(action.evidence === undefined ? {} : { evidence: object(action.evidence, `${path}.evidence`) }),
+        ...(action.captures === undefined ? {} : { captures: object(action.captures, `${path}.captures`) }),
+    };
+}
+function actionStatus(value, path) {
+    if (value !== "passed" && value !== "blocked" && value !== "failed" && value !== "skipped") {
+        throw new Error(`${path} is invalid`);
+    }
+    return value;
+}
+function object(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${path} must be an object`);
+    return value;
+}
+function exactKeys(value, allowed, path) {
+    const extras = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (extras.length > 0)
+        throw new Error(`${path} has unknown fields: ${extras.join(", ")}`);
+}
+function text(value, path) {
+    if (typeof value !== "string" || !value)
+        throw new Error(`${path} must be a non-empty string`);
+    return value;
+}
+function timestamp(value, path) {
+    const result = text(value, path);
+    if (!Number.isFinite(Date.parse(result)))
+        throw new Error(`${path} must be an ISO timestamp`);
+    return result;
+}
+function sha256(value, path) {
+    const result = text(value, path);
+    if (!/^[0-9a-f]{64}$/.test(result))
+        throw new Error(`${path} must be a lowercase SHA-256 digest`);
+    return result;
+}
+function revision(value, path) {
+    const result = text(value, path);
+    if (!/^[0-9a-f]{40}$/.test(result))
+        throw new Error(`${path} must be a full lowercase git SHA`);
+    return result;
+}
+function target(value) {
+    if (value !== "local-docker" && value !== "aws-ecs") {
+        throw new Error("checkpoint.target must be local-docker or aws-ecs");
+    }
+    return value;
+}
+function count(value, path) {
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error(`${path} must be a non-negative integer`);
+    return value;
+}
+function stringList(value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item)) {
+        throw new Error(`${path} must be an array of non-empty strings`);
+    }
+    return value;
+}

package/dist/src/release/zero-to-map-cli.d.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { type AwsEcsProvisionBinding } from "./zero-to-map-provision.js";
+import { type JourneyExecutionResult, type JourneyMcpResourceAction } from "./zero-to-map.js";
+type JourneyTarget = "local-docker" | "aws-ecs";
+export interface CliOptions {
+    readonly execute: boolean;
+    readonly confirmed: boolean;
+    readonly planPath: string;
+    readonly outputPath: string;
+    readonly honuaCommand: string;
+    readonly target: JourneyTarget;
+    readonly mcpUrl?: string;
+    readonly checkpointPath?: string;
+    readonly checkpointDigest?: string;
+    readonly provisionReceiptPath?: string;
+    readonly consoleReceiptPath?: string;
+    readonly provisionBinding?: AwsEcsProvisionBinding;
+    readonly provisionReceiptSha256?: string;
+    readonly sourceRevision?: string;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly receiptPaths: Readonly<Record<string, string>>;
+}
+export declare function runZeroToMapCli(argv?: readonly string[], env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function parseZeroToMapCliArgs(argv: readonly string[], env: NodeJS.ProcessEnv): CliOptions;
+/** Resolve the live mutating CLI without permitting Windows' cwd-first executable search. */
+export declare function resolveLiveExecutable(command: string, env: NodeJS.ProcessEnv, excludedDirectory: string): Promise<string>;
+/** Atomically transfer one paused checkpoint to a single resume owner. */
+export declare function claimZeroToMapCheckpoint(path: string, digest: string): Promise<string>;
+export declare function parseInstallAccessCredential(stdout: string): {
+    readonly id: string;
+    readonly name: string;
+    readonly status: "active";
+    readonly requestedGrants: readonly string[];
+    readonly effectiveGrants: readonly string[];
+    readonly canAuthenticate: true;
+    readonly referenceType: "private-env-file";
+    readonly referenceDigestSha256: string;
+    readonly provisioned: boolean;
+};
+/** Poll one MCP job resource to its declared successful terminal state. */
+export declare function readJourneyMcpResource(action: JourneyMcpResourceAction, read: (uri: string) => Promise<unknown>): Promise<JourneyExecutionResult>;
+export declare function requireCompletedPublishedOperation(tool: string, value: unknown): {
+    operationId: string;
+    status: string;
+    handleId?: string;
+    approvalLane?: string;
+    jobId?: string;
+    metadataRevision?: number;
+} | undefined;
+export {};
+//# sourceMappingURL=zero-to-map-cli.d.ts.map