spawnfile 0.1.13 → 0.1.14

package/dist/auth/targetSecretSourceVersionRecords.js

@@ -0,0 +1,166 @@
+import { Buffer } from "node:buffer";
+import { randomBytes } from "node:crypto";
+import { TARGET_SECRET_SOURCE_ERROR, assertOrdinaryJsonGraph, createCanonicalTargetSecretSourceJson, decodeTargetSecretSourceSecret, encodeTargetSecretSourceSecret, parseCanonicalTargetSecretSourceJson, parseTargetSecretSourceOpaqueHandle } from "./targetSecretSourceRecordCommon.js";
+export const TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION = "spawnfile.auth.target-secret.source-version.v1";
+export const TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION = "spawnfile.auth.target-secret.source-alias.v1";
+const VERSION_KEYS = ["publication_handle", "secret", "source_version_handle", "version"];
+const ALIAS_KEYS = ["publication_handle", "source_handle", "source_version_handle", "version"];
+const ALIAS_METADATA_KEYS = ["source_handle", "source_version_handle", "version"];
+const VERSION_METADATA_KEYS = ["source_version_handle", "version"];
+const PRIVATE_VERSION_METADATA_KEYS = ["publication_handle", "source_version_handle", "version"];
+const fail = () => { throw new Error(TARGET_SECRET_SOURCE_ERROR); };
+const normalize = (work) => {
+    try {
+        return work();
+    }
+    catch {
+        return fail();
+    }
+};
+const defaultEntropy = () => {
+    const bytes = randomBytes(16);
+    try {
+        return Uint8Array.from(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+};
+const freeze = (value) => Object.freeze(value);
+const opaqueHandleFromEntropy = (entropy) => normalize(() => {
+    const raw = entropy();
+    if (!(raw instanceof Uint8Array) || raw.length < 8 || raw.length > 32)
+        fail();
+    const copy = Uint8Array.from(raw);
+    const encoded = Buffer.from(copy);
+    try {
+        return parseTargetSecretSourceOpaqueHandle(`opaque_${encoded.toString("hex")}`);
+    }
+    finally {
+        encoded.fill(0);
+        copy.fill(0);
+    }
+});
+const exactRecord = (value, expected) => {
+    assertOrdinaryJsonGraph(value);
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail();
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index]))
+        fail();
+    return record;
+};
+const parseVersionMetadata = (value) => normalize(() => {
+    const record = exactRecord(value, VERSION_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION)
+        fail();
+    return freeze({ source_version_handle: parseTargetSecretSourceOpaqueHandle(record.source_version_handle), version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION });
+});
+const parsePrivateVersionMetadata = (value) => normalize(() => {
+    const record = exactRecord(value, PRIVATE_VERSION_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION)
+        fail();
+    const sourceVersionHandle = parseTargetSecretSourceOpaqueHandle(record.source_version_handle);
+    const publicationHandle = parseTargetSecretSourceOpaqueHandle(record.publication_handle);
+    if (sourceVersionHandle === publicationHandle)
+        fail();
+    return freeze({
+        publication_handle: publicationHandle,
+        source_version_handle: sourceVersionHandle,
+        version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION
+    });
+});
+const parseVersionPayload = (value) => {
+    const record = exactRecord(value, VERSION_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION || typeof record.secret !== "string")
+        fail();
+    return {
+        metadata: parsePrivateVersionMetadata({
+            publication_handle: record.publication_handle,
+            source_version_handle: record.source_version_handle,
+            version: record.version
+        }),
+        secret: record.secret
+    };
+};
+const parseAliasMetadata = (value) => {
+    const record = exactRecord(value, ALIAS_METADATA_KEYS);
+    if (record.version !== TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION)
+        fail();
+    const sourceHandle = parseTargetSecretSourceOpaqueHandle(record.source_handle);
+    const sourceVersionHandle = parseTargetSecretSourceOpaqueHandle(record.source_version_handle);
+    if (sourceHandle === sourceVersionHandle)
+        fail();
+    return freeze({ source_handle: sourceHandle, source_version_handle: sourceVersionHandle, version: TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION });
+};
+const parseAlias = (value) => {
+    const record = exactRecord(value, ALIAS_KEYS);
+    const metadata = parseAliasMetadata({
+        source_handle: record.source_handle,
+        source_version_handle: record.source_version_handle,
+        version: record.version
+    });
+    const publicationHandle = parseTargetSecretSourceOpaqueHandle(record.publication_handle);
+    if (publicationHandle === metadata.source_handle || publicationHandle === metadata.source_version_handle)
+        fail();
+    return freeze({ publication_handle: publicationHandle, ...metadata });
+};
+export const createTargetSecretSourceVersionRecordBytes = (secret, options = {}) => normalize(() => {
+    const sourceVersionHandle = opaqueHandleFromEntropy(options.entropy ?? defaultEntropy);
+    const publicationHandle = opaqueHandleFromEntropy(options.publicationEntropy ?? defaultEntropy);
+    if (sourceVersionHandle === publicationHandle)
+        fail();
+    const metadata = freeze({
+        source_version_handle: sourceVersionHandle,
+        version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION
+    });
+    const privateMetadata = freeze({
+        publication_handle: publicationHandle,
+        ...metadata
+    });
+    const privateBytes = createCanonicalTargetSecretSourceJson({
+        publication_handle: publicationHandle,
+        secret: encodeTargetSecretSourceSecret(secret),
+        source_version_handle: sourceVersionHandle,
+        version: TARGET_SECRET_SOURCE_VERSION_RECORD_VERSION
+    });
+    return { private_bytes: privateBytes, private_metadata: privateMetadata, metadata };
+});
+export const parseTargetSecretSourceVersionRecordBytes = (raw, expectedLeafHandle) => normalize(() => {
+    const expected = parseTargetSecretSourceOpaqueHandle(expectedLeafHandle);
+    const payload = parseVersionPayload(parseCanonicalTargetSecretSourceJson(raw));
+    if (payload.metadata.source_version_handle !== expected)
+        fail();
+    return freeze({ ...payload.metadata, secret: decodeTargetSecretSourceSecret(payload.secret) });
+});
+export const createTargetSecretSourceAliasRecordBytes = (version, options = {}) => normalize(() => {
+    const versionMetadata = parseVersionMetadata(version);
+    const sourceHandle = opaqueHandleFromEntropy(options.entropy ?? defaultEntropy);
+    const publicationHandle = opaqueHandleFromEntropy(options.publicationEntropy ?? defaultEntropy);
+    if (sourceHandle === versionMetadata.source_version_handle
+        || publicationHandle === sourceHandle
+        || publicationHandle === versionMetadata.source_version_handle)
+        fail();
+    const metadata = freeze({ source_handle: sourceHandle, source_version_handle: versionMetadata.source_version_handle, version: TARGET_SECRET_SOURCE_ALIAS_RECORD_VERSION });
+    const privateMetadata = freeze({ publication_handle: publicationHandle, ...metadata });
+    return {
+        private_bytes: createCanonicalTargetSecretSourceJson(privateMetadata),
+        private_metadata: privateMetadata,
+        metadata
+    };
+});
+export const parseTargetSecretSourceAliasRecordBytes = (raw, expectedLeafHandle) => normalize(() => {
+    const expected = parseTargetSecretSourceOpaqueHandle(expectedLeafHandle);
+    const alias = parseTargetSecretSourceAliasRecordBytesForPublication(raw);
+    if (alias.source_handle !== expected)
+        fail();
+    return alias;
+});
+export const parseTargetSecretSourceAliasRecordBytesForPublication = (raw) => normalize(() => parseAlias(parseCanonicalTargetSecretSourceJson(raw)));
+export const assertTargetSecretSourceAliasCorrelation = (alias, version) => normalize(() => {
+    const parsedAlias = parseAliasMetadata(alias);
+    const parsedVersion = parseVersionMetadata(version);
+    if (parsedAlias.source_version_handle !== parsedVersion.source_version_handle)
+        fail();
+});

package/dist/cli/artifactsCommands.d.ts

@@ -0,0 +1,27 @@
+import type { Command } from "commander";
+import { exportRunArtifacts, type DeploymentLifecycleCorrelation, type LifecycleInvocation } from "../deployment/index.js";
+import type { CliStreams } from "./runCli.js";
+export interface ArtifactsExportCommandOptions {
+    compiled?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    includePrivate?: boolean;
+    json?: boolean;
+    lifecycleInvocation?: string;
+    out: string;
+    readerImage?: string;
+    runId?: string;
+    timeout?: string;
+}
+export interface ArtifactsCommandHandlers {
+    exportRunArtifacts: typeof exportRunArtifacts;
+}
+export declare const createArtifactsExportLifecyclePolicy: (options: ArtifactsExportCommandOptions) => {
+    destination_directory: string;
+    docker_command: string | null;
+    include_private: boolean;
+    reader_image: string | null;
+    timeout_ms: number | null;
+};
+export declare const createArtifactsExportLifecycleInvocation: (id: string, options: ArtifactsExportCommandOptions, compiled: string, correlation: DeploymentLifecycleCorrelation) => LifecycleInvocation;
+export declare const registerArtifactsCommands: (program: Command, handlers: ArtifactsCommandHandlers, streams: CliStreams) => void;

package/dist/cli/artifactsCommands.js

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { findLifecycleInvocation, resolveArtifactsExportLifecycleCorrelation, } from "../deployment/index.js";
+import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
+import { canonicalLifecycleJson } from "../deployment/lifecycleCompletionContracts.js";
+import { runMachineLifecycle } from "./lifecycleMachine.js";
+export const createArtifactsExportLifecyclePolicy = (options) => ({
+    destination_directory: path.resolve(options.out),
+    docker_command: options.dockerCommand ?? null,
+    include_private: options.includePrivate === true,
+    reader_image: options.readerImage ?? null,
+    timeout_ms: options.timeout ? Number(options.timeout) : null,
+});
+export const createArtifactsExportLifecycleInvocation = (id, options, compiled, correlation) => ({
+    correlation: {
+        compiled_output_directory: compiled,
+        deployment_selection: options.deployment ?? null,
+        run_id_selection: options.runId ?? null,
+        ...correlation,
+    },
+    id,
+    operation: "artifacts_export",
+    request_policy: createArtifactsExportLifecyclePolicy(options),
+    version: "spawnfile.lifecycle-invocation.v1",
+});
+const correlationFrom = (stored) => {
+    const value = stored.correlation;
+    if (typeof value.compile_fingerprint !== "string" ||
+        typeof value.deployment_instance_digest !== "string" ||
+        typeof value.deployment !== "string" ||
+        (value.run_id !== null && typeof value.run_id !== "string") ||
+        typeof value.target !== "string")
+        throw new SpawnfileError("runtime_error", "Invalid stored export correlation");
+    return {
+        compile_fingerprint: value.compile_fingerprint,
+        deployment: value.deployment,
+        deployment_instance_digest: value.deployment_instance_digest,
+        run_id: value.run_id,
+        target: value.target,
+    };
+};
+const renderJson = (result) => JSON.stringify({
+    deployment: result.deploymentName,
+    failed_files: result.failedFiles,
+    index: result.index,
+    index_path: result.indexPath,
+    missing_optional_files: result.missingOptionalFiles,
+}, null, 2);
+const renderSummary = (result) => [
+    `exported ${result.index.files.length} file(s) to ${result.indexPath.replace(/[/\\]spawnfile[/\\]export-index\.json$/, "")}`,
+    `deployment: ${result.deploymentName}`,
+    `run: ${result.index.run_id}`,
+    `index: ${result.indexPath}`,
+    ...result.missingOptionalFiles.map((file) => `skipped (not present yet): ${file}`),
+    ...result.failedFiles.map((file) => `FAILED to export: ${file}`),
+];
+export const registerArtifactsCommands = (program, handlers, streams) => {
+    program
+        .command("artifacts")
+        .description("Manage a run's durable artifacts")
+        .command("export")
+        .description("Egress a run's durable artifacts")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .requiredOption("--out <directory>", "Destination run directory")
+        .option("--deployment <name>", "Deployment record name")
+        .option("--run-id <id>", "Run id")
+        .option("--compiled <directory>", "Compile output directory")
+        .option("--docker-command <command>", "Docker command")
+        .option("--include-private", "Export unredacted private runtime training artifacts")
+        .option("--reader-image <image>", "Image used to read named volumes")
+        .option("--timeout <ms>", "Bound each Docker call in milliseconds")
+        .option("--json", "Render machine-readable JSON")
+        .option("--lifecycle-invocation <id>", "Bind this exact JSON invocation")
+        .action(async (inputPath, options) => {
+        if (options.lifecycleInvocation && !options.json)
+            throw new SpawnfileError("validation_error", "--lifecycle-invocation is only valid with --json");
+        const compiled = resolveProjectOutputDirectory(inputPath, options.compiled, DEFAULT_OUTPUT_DIRECTORY);
+        const base = {
+            compiledOutputDirectory: compiled,
+            deploymentName: options.deployment,
+            destinationDirectory: options.out,
+            dockerCommand: options.dockerCommand,
+            includePrivate: options.includePrivate,
+            readerImage: options.readerImage,
+            runId: options.runId,
+            timeoutMs: options.timeout ? Number(options.timeout) : undefined,
+        };
+        if (!options.json) {
+            for (const line of renderSummary(await handlers.exportRunArtifacts(base)))
+                streams.stdout(line);
+            return;
+        }
+        const render = async (expected) => renderJson(await handlers.exportRunArtifacts({
+            ...base,
+            ...(expected ? { expectedLifecycleCorrelation: expected } : {}),
+        }));
+        if (!options.lifecycleInvocation) {
+            streams.stdout(await render());
+            return;
+        }
+        const stored = await findLifecycleInvocation(options.lifecycleInvocation);
+        let exact;
+        let correlation;
+        if (stored) {
+            correlation = correlationFrom(stored);
+            exact = createArtifactsExportLifecycleInvocation(options.lifecycleInvocation, options, compiled, correlation);
+            if (canonicalLifecycleJson(exact) !== canonicalLifecycleJson(stored))
+                throw new SpawnfileError("runtime_error", "Lifecycle invocation id drift");
+        }
+        else {
+            correlation = await resolveArtifactsExportLifecycleCorrelation(base);
+            exact = createArtifactsExportLifecycleInvocation(options.lifecycleInvocation, options, compiled, correlation);
+        }
+        streams.stdout(await runMachineLifecycle(exact, () => render(correlation), async () => {
+            try {
+                const current = await resolveArtifactsExportLifecycleCorrelation(base);
+                return JSON.stringify(current) === JSON.stringify(correlation)
+                    ? { status: "resume_safe" }
+                    : {
+                        reason: "deployment_correlation_changed",
+                        status: "ambiguous",
+                    };
+            }
+            catch {
+                return {
+                    reason: "deployment_correlation_unavailable",
+                    status: "ambiguous",
+                };
+            }
+        }));
+    });
+};

package/dist/cli/authCommands.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+type AuthCommandHandlers = Pick<CliHandlers, "importClaudeCodeAuth" | "importCodexAuth" | "importEnvFile" | "initializeTargetSecretSourceLifecycle" | "provisionCredentials" | "requireAuthProfile" | "syncProjectAuth">;
+export declare const registerAuthCommands: (program: Command, handlers: AuthCommandHandlers, streams: CliStreams, stdin: AsyncIterable<unknown>) => void;
+export {};

package/dist/cli/authCommands.js

@@ -0,0 +1,221 @@
+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("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/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,35 @@
+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}`);
+    });
+    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}`);
+    });
+};

package/dist/cli/containerBundleCommand.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/** Production-only command. Its stdout is the secret-free canonical receipt. */
+export declare const registerContainerBundleCommand: (target: Command, stdin: AsyncIterable<unknown>, streams: {
+    stderr(message: string): void;
+    stdout(message: string): void;
+}, setExitCode: (value: 1 | 2) => void) => void;