spawnfile 0.1.13 → 0.1.17

package/dist/cli/authCommands.js

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { buildProvisionedWorldBindings, disposeProvisionedMaterials, finalizeCredentialProvisioningReceipt, readCredentialProvisioningRequestFile, writeProvisionedEnvFile } from "../auth/index.js";
+import { createCanonicalTargetSecretSourceJson } from "../auth/targetSecretSourceRecordCommon.js";
+import { renderSimfileWorldBindings } from "../compiler/worldBindings.js";
+import { MAX_TARGET_SECRET_SOURCE_SECRET_BYTES, TARGET_SECRET_SOURCE_ERROR } from "../auth/targetSecretSourceRecordCommon.js";
+import { createTargetSecretSourceReceiptBytes, readBoundedTargetSecretStdin, readTargetSecretSourceGrantRequestFile, readTargetSecretSourceRequestFile } from "./targetSecretSourceInput.js";
+const formatAuthProfileSummary = (profile) => {
+    const envKeys = Object.keys(profile.env).sort();
+    const importedKinds = Object.keys(profile.imports).sort();
+    return [
+        `profile: ${profile.name}`,
+        `env: ${envKeys.length > 0 ? envKeys.join(", ") : "none"}`,
+        `imports: ${importedKinds.length > 0 ? importedKinds.join(", ") : "none"}`
+    ];
+};
+const emitLines = (streams, lines) => lines.forEach((line) => streams.stdout(line));
+const emitTargetSecretReceipt = (streams, kind, sourceHandle) => {
+    const bytes = createTargetSecretSourceReceiptBytes({ kind, source_handle: sourceHandle });
+    try {
+        streams.stdout(new TextDecoder().decode(bytes));
+    }
+    finally {
+        bytes.fill(0);
+    }
+};
+const targetSecretAction = async (work) => {
+    try {
+        await work();
+    }
+    catch {
+        throw new Error(TARGET_SECRET_SOURCE_ERROR);
+    }
+};
+const emitCredentialProvisioningReceipt = (streams, receipt) => {
+    const bytes = createCanonicalTargetSecretSourceJson(receipt);
+    try {
+        streams.stdout(new TextDecoder().decode(bytes));
+    }
+    finally {
+        bytes.fill(0);
+    }
+};
+const readResolvedGrantsFile = async (filePath) => {
+    let bytes;
+    try {
+        bytes = await readFile(filePath);
+        if (bytes.length < 1 || bytes.length > 65_536)
+            throw new Error();
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new Error(TARGET_SECRET_SOURCE_ERROR);
+    }
+    finally {
+        bytes?.fill(0);
+    }
+};
+const writeWorldBindingsFile = async (filePath, artifact) => {
+    const bytes = new TextEncoder().encode(renderSimfileWorldBindings(artifact));
+    try {
+        await writeFile(filePath, bytes, { flag: "wx", mode: 0o600 });
+        return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    }
+    finally {
+        bytes.fill(0);
+    }
+};
+export const registerAuthCommands = (program, handlers, streams, stdin) => {
+    const authCommand = program.command("auth").description("Manage local Spawnfile auth profiles");
+    const authImportCommand = authCommand
+        .command("import")
+        .description("Import auth material into a local auth profile");
+    authImportCommand
+        .command("env")
+        .description("Import secrets from an env file into a profile")
+        .argument("<file>", "Path to an env file")
+        .option("-p, --profile <name>", "Auth profile name", "default")
+        .action(async (filePath, options) => {
+        const profile = await handlers.importEnvFile(options.profile, filePath);
+        emitLines(streams, formatAuthProfileSummary(profile));
+    });
+    authImportCommand
+        .command("claude-code")
+        .description("Import Claude Code subscription credentials into a profile")
+        .option("-p, --profile <name>", "Auth profile name", "default")
+        .option("--from <directory>", "Source Claude Code config directory")
+        .action(async (options) => {
+        const profile = await handlers.importClaudeCodeAuth(options.profile, options.from);
+        emitLines(streams, formatAuthProfileSummary(profile));
+    });
+    authImportCommand
+        .command("grok")
+        .description("Import a dedicated training Grok login into a profile")
+        .option("-p, --profile <name>", "Auth profile name", "default")
+        .requiredOption("--from <directory>", "Source Grok config directory holding the dedicated login")
+        .action(async (options) => {
+        const profile = await handlers.importGrokAuth(options.profile, options.from);
+        emitLines(streams, formatAuthProfileSummary(profile));
+    });
+    authImportCommand
+        .command("codex")
+        .description("Import Codex subscription credentials into a profile")
+        .option("-p, --profile <name>", "Auth profile name", "default")
+        .option("--from <directory>", "Source Codex config directory")
+        .action(async (options) => {
+        const profile = await handlers.importCodexAuth(options.profile, options.from);
+        emitLines(streams, formatAuthProfileSummary(profile));
+    });
+    authCommand
+        .command("sync")
+        .description("Provision auth material a project requires into a profile")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("-p, --profile <name>", "Auth profile name", "default")
+        .option("--env-file <file>", "Path to an env file with model keys and runtime secrets")
+        .option("--claude-from <directory>", "Source Claude Code config directory")
+        .option("--codex-from <directory>", "Source Codex config directory")
+        .action(async (inputPath, options) => {
+        const profile = await handlers.syncProjectAuth(inputPath, {
+            claudeCodeDirectory: options.claudeFrom,
+            codexDirectory: options.codexFrom,
+            envFilePath: options.envFile,
+            profileName: options.profile
+        });
+        emitLines(streams, formatAuthProfileSummary(profile));
+    });
+    authCommand
+        .command("show")
+        .description("Show the contents of a local auth profile")
+        .option("-p, --profile <name>", "Auth profile name", "default")
+        .action(async (options) => {
+        const profile = await handlers.requireAuthProfile(options.profile);
+        emitLines(streams, formatAuthProfileSummary(profile));
+    });
+    authCommand
+        .command("provision")
+        .description("Provision a declarative batch of target credentials")
+        .argument("<request-file>", "Secret-free credential provisioning request JSON")
+        .option("--env-file <path>", "Create a 0600 environment file")
+        .option("--world-bindings <path>", "Create a resolved world-bindings artifact")
+        .option("--resolved-grants <path>", "Resolved world grants used to derive world bindings")
+        .action((requestFile, options) => targetSecretAction(async () => {
+        let materials;
+        try {
+            const request = await readCredentialProvisioningRequestFile(requestFile);
+            if ((options.worldBindings === undefined) !== (options.resolvedGrants === undefined)) {
+                throw new Error(TARGET_SECRET_SOURCE_ERROR);
+            }
+            const provisioned = await handlers.provisionCredentials(request);
+            materials = provisioned.materials;
+            let modelEngineAuth = false;
+            if (request.model_engine_auth) {
+                await handlers.importCodexAuth(request.model_engine_auth.profile, request.model_engine_auth.from);
+                modelEngineAuth = true;
+            }
+            const envFile = options.envFile === undefined
+                ? undefined
+                : await writeProvisionedEnvFile({
+                    materials,
+                    path: options.envFile,
+                    receipt: provisioned.receipt
+                });
+            let worldBindingsDigest;
+            if (options.worldBindings !== undefined && options.resolvedGrants !== undefined) {
+                const resolved = await readResolvedGrantsFile(options.resolvedGrants);
+                const artifact = buildProvisionedWorldBindings({
+                    receipt: provisioned.receipt,
+                    request,
+                    resolved
+                });
+                worldBindingsDigest = await writeWorldBindingsFile(options.worldBindings, artifact);
+            }
+            emitCredentialProvisioningReceipt(streams, finalizeCredentialProvisioningReceipt(provisioned.receipt, {
+                ...(envFile === undefined ? {} : { env_file_digest: envFile.digest }),
+                model_engine_auth: modelEngineAuth,
+                ...(worldBindingsDigest === undefined ? {} : { world_bindings_digest: worldBindingsDigest })
+            }));
+        }
+        finally {
+            if (materials)
+                disposeProvisionedMaterials(materials);
+        }
+    }));
+    const targetSecret = authCommand.command("target-secret").description("Manage opaque target secret sources");
+    targetSecret.command("author").description("Author a secret read only from stdin").action(() => targetSecretAction(async () => {
+        const secret = await readBoundedTargetSecretStdin(stdin, MAX_TARGET_SECRET_SOURCE_SECRET_BYTES);
+        try {
+            const lifecycle = await handlers.initializeTargetSecretSourceLifecycle();
+            const result = await lifecycle.author(secret);
+            emitTargetSecretReceipt(streams, "author", result.source_handle);
+        }
+        finally {
+            secret.fill(0);
+        }
+    }));
+    targetSecret.command("grant").description("Grant one exact public source capability")
+        .argument("<request-file>", "Canonical secret-free grant request JSON")
+        .action((filePath) => targetSecretAction(async () => {
+        const request = await readTargetSecretSourceGrantRequestFile(filePath);
+        const lifecycle = await handlers.initializeTargetSecretSourceLifecycle();
+        const result = await lifecycle.grant(request);
+        emitTargetSecretReceipt(streams, "grant", result.source_handle);
+    }));
+    targetSecret.command("rotate").description("Author a replacement from stdin without revoking the old source")
+        .argument("<request-file>", "Canonical old-source request JSON")
+        .action((filePath) => targetSecretAction(async () => {
+        const request = await readTargetSecretSourceRequestFile(filePath);
+        const secret = await readBoundedTargetSecretStdin(stdin, MAX_TARGET_SECRET_SOURCE_SECRET_BYTES);
+        try {
+            const lifecycle = await handlers.initializeTargetSecretSourceLifecycle();
+            const result = await lifecycle.rotate(request.source_handle, secret);
+            emitTargetSecretReceipt(streams, "rotate", result.source_handle);
+        }
+        finally {
+            secret.fill(0);
+        }
+    }));
+    for (const [command, kind] of [["revoke-grant", "grant"], ["revoke-version", "version"]]) {
+        targetSecret.command(command).description(`Revoke one ${kind} capability`)
+            .argument("<request-file>", "Canonical source request JSON")
+            .action((filePath) => targetSecretAction(async () => {
+            const request = await readTargetSecretSourceRequestFile(filePath);
+            const lifecycle = await handlers.initializeTargetSecretSourceLifecycle();
+            const result = kind === "grant"
+                ? await lifecycle.revokeGrant(request.source_handle)
+                : await lifecycle.revokeVersion(request.source_handle);
+            emitTargetSecretReceipt(streams, command, result.source_handle);
+        }));
+    }
+};

package/dist/cli/canaryCutoverCommand.d.ts

@@ -0,0 +1,2 @@
+export declare const isCanaryCutoverInvocation: (argv: readonly string[]) => boolean;
+export declare const runCanaryCutoverCommand: (argv: readonly string[]) => Promise<number>;

package/dist/cli/canaryCutoverCommand.js

@@ -0,0 +1,30 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { issueDeploymentIdentity, runCanaryCutover, verifyEquivalentRollbackReadiness } from "../deployment/canaryCutover.js";
+const boundedArgs = z.array(z.string().max(4096)).max(32);
+const request = z.object({ version: z.literal("spawnfile.canary-cutover-request.v1"), live_report_path: z.string().min(1), candidate_report_path: z.string().min(1), readiness_path: z.string().min(1), expected_identity: z.unknown(), docker_command: z.string().min(1), nonce: z.string().regex(/^[a-f0-9]{32}$/u), transaction_path: z.string().min(1), ingress_command: z.string().min(1), ingress_args: boundedArgs, ingress_receipt_path: z.string().min(1), teardown_command: z.string().min(1), teardown_args: boundedArgs, teardown_policy: z.enum(["export", "force"]), teardown_project_path: z.string().min(1), teardown_compiled_path: z.string().min(1), decision_receipt_path: z.string().min(1), from_deployment: z.string().min(1), to_deployment: z.string().min(1) }).strict();
+const rollback = z.object({ version: z.literal("spawnfile.canary-rollback-readiness-request.v1"), rollback_readiness_path: z.string().min(1), expected_identity: z.unknown() }).strict();
+const identity = z.object({ version: z.literal("spawnfile.deployment-identity-request.v1"), readiness_path: z.string().min(1), deployment_mode: z.enum(["project", "image"]), docker_command: z.string().min(1), receipt_path: z.string().min(1) }).strict();
+export const isCanaryCutoverInvocation = (argv) => argv[0] === "canary" && ["identity", "cutover", "verify-rollback"].includes(argv[1] ?? "");
+export const runCanaryCutoverCommand = async (argv) => {
+    try {
+        const bytes = await readFile(argv[2] ?? "", "utf8");
+        if (argv[1] === "identity") {
+            const value = identity.parse(JSON.parse(bytes)), receipt = await issueDeploymentIdentity(value.readiness_path, value.deployment_mode, value.docker_command);
+            await writeFile(value.receipt_path, `${JSON.stringify(receipt)}\n`, { flag: "wx", mode: 0o600 });
+        }
+        else if (argv[1] === "verify-rollback") {
+            const value = rollback.parse(JSON.parse(bytes));
+            await verifyEquivalentRollbackReadiness(value.rollback_readiness_path, value.expected_identity);
+        }
+        else {
+            const value = request.parse(JSON.parse(bytes));
+            await runCanaryCutover({ liveReportPath: value.live_report_path, candidateReportPath: value.candidate_report_path, readinessPath: value.readiness_path, expectedIdentity: value.expected_identity, dockerCommand: value.docker_command, nonce: value.nonce, transactionPath: value.transaction_path, ingressCommand: value.ingress_command, ingressArgs: value.ingress_args, ingressReceiptPath: value.ingress_receipt_path, teardownCommand: value.teardown_command, teardownArgs: value.teardown_args, teardownPolicy: value.teardown_policy, teardownProjectPath: value.teardown_project_path, teardownCompiledPath: value.teardown_compiled_path, decisionReceiptPath: value.decision_receipt_path, fromDeployment: value.from_deployment, toDeployment: value.to_deployment });
+        }
+        return 0;
+    }
+    catch {
+        process.stderr.write("error: Canary operation failed\n");
+        return 1;
+    }
+};

package/dist/cli/capabilitiesCommand.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { CliStreams } from "./runCli.js";
+export declare const registerCapabilitiesCommand: (program: Command, streams: CliStreams, packageVersion: string) => void;

package/dist/cli/capabilitiesCommand.js

@@ -0,0 +1,12 @@
+import { SpawnfileError } from "../shared/index.js";
+import { createCapabilitiesReceipt, createCapabilitiesReceiptBytes, } from "./capabilitiesReceipt.js";
+export const registerCapabilitiesCommand = (program, streams, packageVersion) => {
+    program.command("capabilities")
+        .description("Report supported public CLI contracts")
+        .requiredOption("--json", "Emit one strict versioned JSON receipt")
+        .action((options) => {
+        if (options.json !== true)
+            throw new SpawnfileError("validation_error", "`capabilities` requires --json");
+        streams.stdout(createCapabilitiesReceiptBytes(createCapabilitiesReceipt(packageVersion)));
+    });
+};

package/dist/cli/capabilitiesReceipt.d.ts

@@ -0,0 +1,56 @@
+import { CREDENTIAL_PROVISIONING_REQUEST_VERSION } from "../auth/index.js";
+import { PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION } from "../evidenceExportHelper/index.js";
+import { TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION, TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION, TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION } from "../target/publicArtifactSnapshot.js";
+import { COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION, type ComposedLifecycleCommandContract } from "./composedLifecycleContractSet.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION } from "./targetDefaultConfigStdin.js";
+import { TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION } from "./targetConfigResolver.js";
+import { TARGET_CONFIG_RESOLVER_COMMAND } from "./targetConfigResolverCommand.js";
+export { COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION } from "./composedLifecycleContractSet.js";
+export declare const CAPABILITIES_RECEIPT_VERSION: "spawnfile.capabilities.v1";
+export interface CapabilitiesReceipt {
+    readonly capabilities: {
+        readonly evidence_export_helper: {
+            readonly identity: "docker-image-config-digest";
+            readonly local_context_only: true;
+            readonly prepare_command: readonly [
+                "helper",
+                "prepare-evidence-export",
+                "--context",
+                "<name>",
+                "--json"
+            ];
+            readonly receipt_version: typeof PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION;
+            readonly resolver_option: "--prepare-evidence-helper";
+            readonly provisioning: "spawnfile-owned-target-local";
+        };
+        readonly composed_lifecycle: {
+            readonly command_set_version: typeof COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION;
+            readonly commands: readonly ComposedLifecycleCommandContract[];
+            readonly complete: true;
+        };
+        readonly optional_model_auth: {
+            readonly request_version: typeof CREDENTIAL_PROVISIONING_REQUEST_VERSION;
+            readonly required: false;
+        };
+        readonly target_config_resolver: {
+            readonly command: readonly ["target", typeof TARGET_CONFIG_RESOLVER_COMMAND];
+            readonly output_version: typeof TARGET_CONFIG_RESOLUTION_VERSION;
+            readonly prepared_plan_version: typeof TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION;
+            readonly target_config_digest_version: typeof TARGET_CONFIG_DIGEST_VERSION;
+            readonly target_config_version: typeof TARGET_DEFAULT_CONFIG_STDIN_VERSION;
+        };
+        readonly terminal_public_artifact: {
+            readonly not_present_version: typeof TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION;
+            readonly request_version: typeof TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION;
+            readonly snapshot_version: typeof TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION;
+        };
+    };
+    readonly implementation: {
+        readonly cli: "spawnfile";
+        readonly package: "spawnfile";
+        readonly version: string;
+    };
+    readonly version: typeof CAPABILITIES_RECEIPT_VERSION;
+}
+export declare const createCapabilitiesReceipt: (packageVersion: string) => CapabilitiesReceipt;
+export declare const createCapabilitiesReceiptBytes: (receipt: CapabilitiesReceipt) => string;

package/dist/cli/capabilitiesReceipt.js

@@ -0,0 +1,56 @@
+import { CREDENTIAL_PROVISIONING_REQUEST_VERSION } from "../auth/index.js";
+import { PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION } from "../evidenceExportHelper/index.js";
+import { TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION, TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION, TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION, } from "../target/publicArtifactSnapshot.js";
+import { COMPOSED_LIFECYCLE_COMMANDS, COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION, } from "./composedLifecycleContractSet.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION, } from "./targetDefaultConfigStdin.js";
+import { TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION, } from "./targetConfigResolver.js";
+import { TARGET_CONFIG_RESOLVER_COMMAND } from "./targetConfigResolverCommand.js";
+export { COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION } from "./composedLifecycleContractSet.js";
+export const CAPABILITIES_RECEIPT_VERSION = "spawnfile.capabilities.v1";
+const PACKAGE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u;
+export const createCapabilitiesReceipt = (packageVersion) => {
+    if (!PACKAGE_VERSION.test(packageVersion))
+        throw new TypeError("Invalid Spawnfile package version");
+    return Object.freeze({
+        capabilities: Object.freeze({
+            evidence_export_helper: Object.freeze({
+                identity: "docker-image-config-digest",
+                local_context_only: true,
+                prepare_command: Object.freeze([
+                    "helper", "prepare-evidence-export", "--context", "<name>", "--json",
+                ]),
+                receipt_version: PREPARED_EVIDENCE_HELPER_RECEIPT_VERSION,
+                resolver_option: "--prepare-evidence-helper",
+                provisioning: "spawnfile-owned-target-local",
+            }),
+            composed_lifecycle: Object.freeze({
+                command_set_version: COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION,
+                commands: COMPOSED_LIFECYCLE_COMMANDS,
+                complete: true,
+            }),
+            optional_model_auth: Object.freeze({
+                request_version: CREDENTIAL_PROVISIONING_REQUEST_VERSION,
+                required: false,
+            }),
+            target_config_resolver: Object.freeze({
+                command: Object.freeze(["target", TARGET_CONFIG_RESOLVER_COMMAND]),
+                output_version: TARGET_CONFIG_RESOLUTION_VERSION,
+                prepared_plan_version: TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION,
+                target_config_digest_version: TARGET_CONFIG_DIGEST_VERSION,
+                target_config_version: TARGET_DEFAULT_CONFIG_STDIN_VERSION,
+            }),
+            terminal_public_artifact: Object.freeze({
+                not_present_version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION,
+                request_version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION,
+                snapshot_version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION,
+            }),
+        }),
+        implementation: Object.freeze({
+            cli: "spawnfile",
+            package: "spawnfile",
+            version: packageVersion,
+        }),
+        version: CAPABILITIES_RECEIPT_VERSION,
+    });
+};
+export const createCapabilitiesReceiptBytes = (receipt) => JSON.stringify(receipt);

package/dist/cli/compileBuildCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+export declare const registerCompileBuildCommands: (program: Command, handlers: CliHandlers, streams: CliStreams) => void;

package/dist/cli/compileBuildCommands.js

@@ -0,0 +1,48 @@
+import { describeBackedMountRequirement } from "../compiler/containerBackedMountRender.js";
+/**
+ * Durable mounts are only attached by `spawnfile run`/`up`/`deploy`. A
+ * hand-rolled `docker run` of the built image gets none of them and the
+ * entrypoint now refuses to start, so say up front how many the launcher owes.
+ */
+const reportDurableMounts = (report, streams) => {
+    const line = describeBackedMountRequirement(report.container?.persistent_mounts ?? []);
+    if (line)
+        streams.stdout(line);
+};
+export const registerCompileBuildCommands = (program, handlers, streams) => {
+    program
+        .command("compile")
+        .description("Compile a project into runtime-native output under .spawn")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("-o, --out <directory>", "Output directory")
+        .option("--world-bindings <file>", "Path to a versioned world-bindings artifact")
+        .action(async (inputPath, options) => {
+        const result = await handlers.compileProject(inputPath, {
+            outputDirectory: options.out,
+            worldBindingsPath: options.worldBindings
+        });
+        streams.stdout(`compiled to ${result.outputDirectory}`);
+        streams.stdout(`report: ${result.reportPath}`);
+        reportDurableMounts(result.report, streams);
+    });
+    program
+        .command("build")
+        .description("Compile and build the organization Docker image")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("--context <name>", "Docker context for the build target")
+        .option("--docker-command <command>", "Docker command")
+        .option("-o, --out <directory>", "Output directory")
+        .option("-t, --tag <image>", "Docker image tag")
+        .action(async (inputPath, options) => {
+        const result = await handlers.buildProject(inputPath, {
+            dockerContext: options.context,
+            dockerCommand: options.dockerCommand,
+            imageTag: options.tag,
+            outputDirectory: options.out
+        });
+        streams.stdout(`built image ${result.imageTag}`);
+        streams.stdout(`compiled to ${result.outputDirectory}`);
+        streams.stdout(`report: ${result.reportPath}`);
+        reportDurableMounts(result.report, streams);
+    });
+};

package/dist/cli/composedLifecycleContractSet.d.ts

@@ -0,0 +1,21 @@
+export declare const COMPOSED_LIFECYCLE_CONTRACT_SET_VERSION: "spawnfile.composed-lifecycle-contract-set.v1";
+export type LifecycleCommandStdout = "json" | "text";
+/**
+ * One closed machine-facing command surface. Empty version lists are
+ * intentional: they mean the command has no versioned value in that role.
+ */
+export interface ComposedLifecycleCommandContract {
+    readonly argv: readonly string[];
+    readonly invocation_versions: readonly string[];
+    readonly pending_versions: readonly string[];
+    readonly receipt_versions: readonly string[];
+    readonly request_versions: readonly string[];
+    readonly stdin_versions: readonly string[];
+    readonly stdout: LifecycleCommandStdout;
+}
+/**
+ * Closed inventory for consumers that compose only public CLI and receipt
+ * contracts. `argv` records one canonical invocation form, not every
+ * presentation-only optional flag accepted by Commander.
+ */
+export declare const COMPOSED_LIFECYCLE_COMMANDS: readonly ComposedLifecycleCommandContract[];