spawnfile 0.1.14 → 0.1.17

package/dist/cli/paideiaDelegation.js

@@ -0,0 +1,210 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { trainingContextSchema } from "../compiler/training/index.js";
+import { launchTrainingContainer } from "../compiler/training/container/index.js";
+import { runTrainingDocker } from "../compiler/training/container/process.js";
+import { prepareTraining } from "../compiler/training/preparation/index.js";
+import { readBoundedJson } from "../compiler/training/preparation/inputs.js";
+import { SpawnfileError } from "../shared/index.js";
+const MAX_LINE_BYTES = 1024 * 1024;
+const validReceipt = (line, dryRun) => {
+    try {
+        const value = JSON.parse(line);
+        if (typeof value !== "object" || value === null)
+            return false;
+        const receipt = value;
+        return dryRun
+            ? receipt.schema === "paideia.training-cost-plan.v1" && receipt.modelCallsMade === 0
+            : receipt.status === "completed" && typeof receipt.index === "string" && receipt.index.length > 0;
+    }
+    catch {
+        return false;
+    }
+};
+const failure = (message) => new SpawnfileError("runtime_error", message);
+const runChild = (options, contextPath) => new Promise((resolve, reject) => {
+    if (options.signal?.aborted) {
+        resolve(130);
+        return;
+    }
+    // Node strips types in a source checkout; the packaged build selects its emitted JS.
+    const extension = path.extname(fileURLToPath(import.meta.url));
+    const supervisor = fileURLToPath(new URL(`./paideiaSupervisor${extension}`, import.meta.url));
+    const child = spawn(process.execPath, ["--experimental-strip-types", supervisor, options.command,
+        "train", "--spawnfile-context", contextPath, ...options.args], {
+        shell: false, detached: true, stdio: ["ignore", "pipe", "pipe", "ipc"]
+    });
+    const pid = child.pid;
+    let stdout = "", stderr = "", lastLine = "";
+    let stopCode, error, outcome;
+    let reaped = false, closed = false, finished = false;
+    let killTimer;
+    const kill = (signal) => {
+        if (pid === undefined || reaped)
+            return;
+        try {
+            process.kill(-pid, signal);
+        }
+        catch (caught) {
+            if (caught.code !== "ESRCH")
+                error = failure("Could not signal the owned Paideia process group");
+        }
+    };
+    const groupExists = () => {
+        if (pid === undefined)
+            return false;
+        try {
+            process.kill(-pid, 0);
+            return true;
+        }
+        catch (caught) {
+            return caught.code !== "ESRCH";
+        }
+    };
+    const stop = (code, cause) => {
+        if (stopCode !== undefined)
+            return;
+        stopCode = code;
+        error = cause;
+        kill("SIGTERM");
+        killTimer = setTimeout(() => kill("SIGKILL"), 1000);
+        killTimer.unref();
+    };
+    const interrupt = () => stop(130), terminate = () => stop(143), abort = () => stop(130);
+    const timer = setTimeout(() => stop(1, failure("Paideia training exceeded its command deadline")), options.timeoutMs);
+    timer.unref();
+    process.once("SIGINT", interrupt);
+    process.once("SIGTERM", terminate);
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    const consume = (chunk, channel) => {
+        const lines = ((channel === "stdout" ? stdout : stderr) + chunk).split("\n");
+        const remainder = lines.pop();
+        if ([remainder, ...lines].some((line) => Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES)) {
+            stop(1, failure("Paideia output exceeded the bounded JSON-line contract"));
+            return;
+        }
+        for (const raw of lines) {
+            const line = raw.replace(/\r$/u, "");
+            if (!line.trim())
+                continue;
+            if (channel === "stdout")
+                lastLine = line;
+            options.streams[channel](line);
+        }
+        if (channel === "stdout")
+            stdout = remainder;
+        else
+            stderr = remainder;
+    };
+    child.stdout.setEncoding("utf8").on("data", (chunk) => consume(chunk, "stdout"));
+    child.stderr.setEncoding("utf8").on("data", (chunk) => consume(chunk, "stderr"));
+    child.once("message", (message) => {
+        outcome = message;
+        if (message.type === "paideia.process.launch-error")
+            error = failure(`Could not start Paideia: ${message.message}`);
+        // The native child exited, but our supervisor still holds the group identity.
+        // Stop stragglers before permitting its leader to disappear or reporting completion.
+        kill("SIGKILL");
+    });
+    const finish = async () => {
+        if (finished)
+            return;
+        finished = true;
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        process.removeListener("SIGINT", interrupt);
+        process.removeListener("SIGTERM", terminate);
+        options.signal?.removeEventListener("abort", abort);
+        const deadline = Date.now() + 1500;
+        // Check only: never signal a numeric group identity after its supervisor was reaped.
+        while ((groupExists() || !closed) && Date.now() < deadline)
+            await delay(20);
+        if (groupExists() || !closed) {
+            error = failure("Paideia process cleanup is incomplete; group or output quiescence is unknown");
+            child.stdout.destroy();
+            child.stderr.destroy();
+        }
+        if (stdout.trim()) {
+            lastLine = stdout;
+            options.streams.stdout(stdout);
+        }
+        if (stderr.trim())
+            options.streams.stderr(stderr);
+        if (error) {
+            reject(error);
+            return;
+        }
+        if (stopCode !== undefined) {
+            resolve(stopCode);
+            return;
+        }
+        if (outcome?.type !== "paideia.process.exited") {
+            reject(failure("Paideia supervisor exited without a native outcome"));
+            return;
+        }
+        if (outcome.signal) {
+            resolve(outcome.signal === "SIGINT" ? 130 : outcome.signal === "SIGTERM" ? 143 : 1);
+            return;
+        }
+        const exitCode = outcome.code ?? 1;
+        if ((exitCode === 0 || exitCode === 1) && !validReceipt(lastLine, options.dryRun)) {
+            reject(failure("Paideia exited without the required final training receipt"));
+            return;
+        }
+        resolve(exitCode);
+    };
+    child.once("error", (caught) => { error = failure(`Could not start Paideia supervisor: ${caught.message}`); });
+    child.once("exit", () => { reaped = true; void finish(); });
+    child.once("close", () => { closed = true; void finish(); });
+});
+/** Delegates through the public CLI, never importing Paideia or selecting a fallback adapter. */
+export const delegatePaideiaTraining = async (options) => {
+    if (options.signal?.aborted)
+        return 130;
+    if (options.repairWitness && !options.repairMeasurements)
+        throw failure("--repair-witness requires --repair-measurements");
+    if (options.trainingConfig) {
+        const config = await readBoundedJson(options.trainingConfig);
+        // v2 and v3 are both declarative preparations; a v3 *launch* config (already lowered, with `inputs`) goes straight to Docker.
+        if (config.version === "spawnfile.training-container.v2" || (config.version === "spawnfile.training-container.v3" && config.image !== undefined)) {
+            if (options.trainingImage)
+                throw failure("V2 owns its image declaration; --training-image is only for v1");
+            const prepared = await prepareTraining({ configPath: options.trainingConfig, context: options.context, args: options.args,
+                repairMeasurements: options.repairMeasurements, repairWitness: options.repairWitness,
+                dryRun: options.dryRun, process: runTrainingDocker, timeoutMs: options.timeoutMs, signal: options.signal, streams: options.streams });
+            if (!("dryRun" in prepared))
+                return launchTrainingContainer({ ...prepared,
+                    timeoutMs: options.timeoutMs, signal: options.signal, streams: options.streams });
+            options.streams.stderr(`Training preparation plan ${prepared.digest}; no Docker, auth or filesystem mutations`);
+            options = { ...options, repairMeasurements: undefined, repairWitness: undefined };
+        }
+    }
+    if (options.repairMeasurements)
+        throw failure("Measurement repair requires the v2 preparation declaration");
+    if (!options.dryRun) {
+        if (!options.trainingImage || !options.trainingConfig)
+            throw failure("Actual training requires --training-image and --training-config; host execution is disabled");
+        return launchTrainingContainer({ image: options.trainingImage, configPath: options.trainingConfig,
+            context: options.context, args: options.args, timeoutMs: options.timeoutMs, streams: options.streams, signal: options.signal });
+    }
+    if (process.platform === "win32")
+        throw failure("Paideia delegation requires POSIX process-group supervision");
+    const bytes = JSON.stringify(trainingContextSchema.parse(options.context));
+    if (Buffer.byteLength(bytes, "utf8") > MAX_LINE_BYTES)
+        throw new SpawnfileError("validation_error", "Training context exceeds 1 MiB");
+    const temporary = await mkdtemp(path.join(os.tmpdir(), "spawnfile-training-"));
+    const contextPath = path.join(temporary, "context.json");
+    try {
+        await writeFile(contextPath, bytes, { mode: 0o600, flag: "wx" });
+        return await runChild(options, contextPath);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+};

package/dist/cli/paideiaSupervisor.d.ts

@@ -0,0 +1,17 @@
+import { type ChildProcess } from "node:child_process";
+export type PaideiaProcessOutcome = {
+    type: "paideia.process.exited";
+    code: number | null;
+    signal: NodeJS.Signals | null;
+} | {
+    type: "paideia.process.launch-error";
+    message: string;
+};
+type SupervisorProcess = Pick<NodeJS.Process, "send" | "pid" | "on" | "removeListener" | "kill" | "exit">;
+export interface PaideiaSupervisorHost {
+    process: SupervisorProcess;
+    launch(command: string, args: string[]): ChildProcess;
+}
+/** Remains the owned group leader until the parent closes the entire group. */
+export declare const supervisePaideia: (argv: readonly string[], host?: PaideiaSupervisorHost) => (() => void);
+export {};

package/dist/cli/paideiaSupervisor.js

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const defaultHost = {
+    process,
+    launch: (command, args) => spawn(command, args, { shell: false, stdio: ["ignore", "inherit", "inherit"] })
+};
+/** Remains the owned group leader until the parent closes the entire group. */
+export const supervisePaideia = (argv, host = defaultHost) => {
+    const [command, ...args] = argv;
+    if (!command || !host.process.send)
+        throw new Error("Paideia supervisor requires an executable and private IPC");
+    const hold = setInterval(() => undefined, 1000);
+    const ignore = () => undefined;
+    const disconnect = () => {
+        // This process is still alive: its own group identity cannot have been recycled.
+        try {
+            host.process.kill(-host.process.pid, "SIGKILL");
+        }
+        finally {
+            host.process.exit(1);
+        }
+    };
+    host.process.on("SIGINT", ignore).on("SIGTERM", ignore).on("disconnect", disconnect);
+    let reported = false;
+    const report = (outcome) => {
+        if (reported)
+            return;
+        reported = true;
+        host.process.send(outcome);
+    };
+    const child = host.launch(command, args);
+    child.once("error", (error) => report({ type: "paideia.process.launch-error", message: error.message }));
+    child.once("exit", (code, signal) => report({ type: "paideia.process.exited", code, signal }));
+    return () => {
+        clearInterval(hold);
+        host.process.removeListener("SIGINT", ignore).removeListener("SIGTERM", ignore).removeListener("disconnect", disconnect);
+    };
+};
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        supervisePaideia(process.argv.slice(2));
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/cli/productStateCloneCommand.d.ts

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

package/dist/cli/productStateCloneCommand.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { issueProductStateSourceSnapshot, runProductStateCloneWorkflow } from "../deployment/productStateClone.js";
+const requestSchema = z.object({ version: z.literal("spawnfile.product-state-clone-request.v1"), authority_receipt_path: z.string().min(1).max(4096), docker_command: z.string().min(1).max(4096), destination: z.string().min(1).max(4096), proof_path: z.string().min(1).max(4096), receipt_path: z.string().min(1).max(4096), candidate_run_id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u) }).strict();
+const authorityRequestSchema = z.object({ version: z.literal("spawnfile.product-state-source-authority-request.v1"), docker_command: z.string().min(1).max(4096), container: z.string().min(1).max(255), source_run_id: z.string().min(1).max(128), mount_path: z.string().min(1).max(4096), candidate_volume_name: z.string().min(1).max(255), candidate_resource_identity: z.string().regex(/^sha256:[a-f0-9]{64}$/u), receipt_path: z.string().min(1).max(4096), proof_path: z.string().min(1).max(4096) }).strict();
+export const isProductStateCloneInvocation = (argv) => argv[0] === "product-state" && ["authority", "clone"].includes(argv[1] ?? "");
+export const runProductStateCloneCommand = async (argv) => {
+    try {
+        if (argv.length !== 3)
+            throw new Error("usage");
+        const bytes = await readFile(argv[2]);
+        if (bytes.length > 65_536)
+            throw new Error("oversized");
+        if (argv[1] === "authority") {
+            const request = authorityRequestSchema.parse(JSON.parse(bytes.toString("utf8"))), snapshot = await issueProductStateSourceSnapshot({ dockerCommand: request.docker_command, container: request.container, sourceRunId: request.source_run_id, mountPath: request.mount_path, candidateVolumeName: request.candidate_volume_name, candidateResourceIdentity: request.candidate_resource_identity });
+            await mkdir(path.dirname(request.receipt_path), { recursive: true, mode: 0o700 });
+            await writeFile(request.proof_path, `${JSON.stringify(snapshot.proof)}\n`, { flag: "wx", mode: 0o600 });
+            await writeFile(request.receipt_path, `${JSON.stringify(snapshot.authority)}\n`, { flag: "wx", mode: 0o600 });
+            process.stdout.write(`${JSON.stringify(snapshot.authority)}\n`);
+            return 0;
+        }
+        const request = requestSchema.parse(JSON.parse(bytes.toString("utf8")));
+        process.stdout.write(`${JSON.stringify(await runProductStateCloneWorkflow({ authorityReceiptPath: request.authority_receipt_path, dockerCommand: request.docker_command, destination: request.destination, proofPath: request.proof_path, receiptPath: request.receipt_path, candidateRunId: request.candidate_run_id }))}\n`);
+        return 0;
+    }
+    catch (error) {
+        // Carry the cause. A bare "failed" is undiagnosable in CI, where this runs
+        // against a different Docker and architecture than any developer machine.
+        const detail = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`error: Product-state clone failed: ${detail}\n`);
+        return 1;
+    }
+};

package/dist/cli/runCli.d.ts

@@ -1,9 +1,10 @@
-import { importClaudeCodeAuth, importCodexAuth, importEnvFile, initializeTargetSecretSourceLifecycle, provisionCredentials, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, initProject, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
+import { importClaudeCodeAuth, importCodexAuth, importGrokAuth, importEnvFile, initializeTargetSecretSourceLifecycle, provisionCredentials, requireAuthProfile } from "../auth/index.js";
+import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, createTrainingContext, initProject, listInitTemplates, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
 import { devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject } from "../dev/index.js";
 import { consumeImageUp } from "../distribution/index.js";
-import { downDeployment, exportRunArtifacts } from "../deployment/index.js";
+import { createDockerProbeGateway, downDeployment, exportRunArtifacts, inspectDockerDeployment, listDeploymentRecords, listHomeDeploymentRecords } from "../deployment/index.js";
 import { listRuntimeAdapters } from "../runtime/index.js";
+import { delegatePaideiaTraining } from "./paideiaDelegation.js";
 export interface CliStreams {
     stderr: (message: string) => void;
     stdout: (message: string) => void;
@@ -14,6 +15,8 @@ export interface CliRenderEnvironment {
     stdoutIsTty: boolean;
 }
 export interface CliHandlers {
+    createTrainingContext: typeof createTrainingContext;
+    delegatePaideiaTraining: typeof delegatePaideiaTraining;
     buildCompilePlan: typeof buildCompilePlan;
     buildOrganizationView: typeof buildOrganizationView;
     buildProject: typeof buildProject;
@@ -27,12 +30,18 @@ export interface CliHandlers {
     clearProjectModelFallbacks: typeof clearProjectModelFallbacks;
     importClaudeCodeAuth: typeof importClaudeCodeAuth;
     importCodexAuth: typeof importCodexAuth;
+    importGrokAuth: typeof importGrokAuth;
     importEnvFile: typeof importEnvFile;
     initProject: typeof initProject;
+    listInitTemplates: typeof listInitTemplates;
     initializeTargetSecretSourceLifecycle: typeof initializeTargetSecretSourceLifecycle;
     provisionCredentials: typeof provisionCredentials;
     exportRunArtifacts: typeof exportRunArtifacts;
     downDeployment: typeof downDeployment;
+    createDockerProbeGateway: typeof createDockerProbeGateway;
+    inspectDockerDeployment: typeof inspectDockerDeployment;
+    listDeploymentRecords: typeof listDeploymentRecords;
+    listHomeDeploymentRecords: typeof listHomeDeploymentRecords;
     listRuntimeAdapters: typeof listRuntimeAdapters;
     removeProjectSurface: typeof removeProjectSurface;
     requireAuthProfile: typeof requireAuthProfile;
@@ -56,6 +65,7 @@ export interface RunCliOptions {
     renderEnvironment?: CliRenderEnvironment;
     stdin?: AsyncIterable<unknown>;
     streams?: CliStreams;
+    signal?: AbortSignal;
 }
 type RunCli = {
     (argv: string[], options?: RunCliOptions): Promise<number>;

package/dist/cli/runCli.js

@@ -1,22 +1,27 @@
 import { readFileSync } from "node:fs";
 import { Command } from "commander";
-import { importClaudeCodeAuth, importCodexAuth, importEnvFile, initializeTargetSecretSourceLifecycle, provisionCredentials, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, initProject, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
+import { importClaudeCodeAuth, importCodexAuth, importGrokAuth, importEnvFile, initializeTargetSecretSourceLifecycle, provisionCredentials, requireAuthProfile } from "../auth/index.js";
+import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, buildUpReceipt, clearProjectModelFallbacks, compileProject, createTrainingContext, initProject, listInitTemplates, publishProject, upProject, removeProjectSurface, runProject, setProjectPrimaryModel, setProjectRuntime, setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth } from "../compiler/index.js";
 import { devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject } from "../dev/index.js";
 import { consumeImageUp } from "../distribution/index.js";
-import { downDeployment, exportRunArtifacts } from "../deployment/index.js";
+import { createDockerProbeGateway, downDeployment, exportRunArtifacts, inspectDockerDeployment, listDeploymentRecords, listHomeDeploymentRecords } from "../deployment/index.js";
 import { errorExitCode, isSpawnfileError } from "../shared/index.js";
 import { listRuntimeAdapters } from "../runtime/index.js";
 import { registerArtifactsCommands } from "./artifactsCommands.js";
 import { registerAuthCommands } from "./authCommands.js";
+import { registerCapabilitiesCommand } from "./capabilitiesCommand.js";
 import { registerDevCommands } from "./devCommands.js";
+import { registerEvidenceExportHelperCommand } from "./evidenceExportHelperCommand.js";
 import { registerLifecycleCommands } from "./lifecycleCommands.js";
 import { registerModelCommands } from "./modelCommands.js";
 import { registerRuntimeCommands } from "./runtimeCommands.js";
 import { registerSurfaceCommands } from "./surfaceCommands.js";
 import { registerStatusCommand } from "./statusCommand.js";
-import { registerProductionTargetCommands } from "./targetCommands.js";
+import { registerUsageCommand } from "./usageCommand.js";
+import { registerProductionTargetCommands } from "./targetProductionCommands.js";
 import { registerViewCommand } from "./viewCommand.js";
+import { registerTrainCommand } from "./trainCommand.js";
+import { delegatePaideiaTraining } from "./paideiaDelegation.js";
 const packageJsonPath = new URL("../../package.json", import.meta.url);
 const readPackageVersion = () => {
     const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
@@ -32,13 +37,15 @@ const createDefaultRenderEnvironment = () => ({
     stdoutIsTty: process.stdout.isTTY === true
 });
 const createDefaultHandlers = () => ({
+    createTrainingContext, delegatePaideiaTraining,
     buildCompilePlan, buildOrganizationView, buildProject, compileProject, publishProject,
     addAgentProject, addProjectModelFallback, addProjectSurface,
     addSubagentProject, addTeamProject, clearProjectModelFallbacks,
-    importClaudeCodeAuth, importCodexAuth, importEnvFile, initializeTargetSecretSourceLifecycle,
+    importClaudeCodeAuth, importCodexAuth, importGrokAuth, importEnvFile, initializeTargetSecretSourceLifecycle,
     provisionCredentials,
-    exportRunArtifacts, downDeployment,
-    initProject, listRuntimeAdapters, removeProjectSurface, requireAuthProfile,
+    createDockerProbeGateway, exportRunArtifacts, downDeployment, inspectDockerDeployment,
+    listDeploymentRecords, listHomeDeploymentRecords,
+    initProject, listInitTemplates, listRuntimeAdapters, removeProjectSurface, requireAuthProfile,
     runProject, setProjectPrimaryModel, setProjectRuntime, upProject, buildUpReceipt, consumeImageUp,
     devActivityProject, devApplyProject, devRestartProject, devStopProject, devUpProject,
     setProjectSurfaceAccess, showProjectSurfaces, syncProjectAuth
@@ -58,7 +65,8 @@ const normalizeRunCliOptions = (optionsOrStreams, handlerOverrides = {}) => isCl
         handlers: optionsOrStreams?.handlers ?? handlerOverrides,
         renderEnvironment: optionsOrStreams?.renderEnvironment ?? createDefaultRenderEnvironment(),
         stdin: optionsOrStreams?.stdin ?? process.stdin,
-        streams: optionsOrStreams?.streams ?? createDefaultStreams()
+        streams: optionsOrStreams?.streams ?? createDefaultStreams(),
+        signal: optionsOrStreams?.signal
     };
 const writeCommanderOutput = (write, message) => {
     const normalized = message.replace(/\n$/, "");
@@ -113,17 +121,31 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     registerLifecycleCommands(program, handlers, streams, cliOptions.stdin);
     registerDevCommands(program, handlers, streams);
     registerArtifactsCommands(program, handlers, streams);
+    registerCapabilitiesCommand(program, streams, readPackageVersion());
+    registerEvidenceExportHelperCommand(program, streams, (exitCode) => {
+        commandExitCode = exitCode;
+    });
     program
         .command("init")
         .description("Scaffold a new Spawnfile project or team in a directory")
         .argument("[path]", "Directory to initialize", process.cwd())
         .option("--team", "Initialize a team project")
         .option("--runtime <name>", "Runtime for agent scaffolds")
+        .option("--template <name>", "Scaffold from a bundled example template")
+        .option("--list-templates", "List available example templates and exit")
         .action(async (inputPath, options) => {
+        if (options.listTemplates) {
+            const templates = await handlers.listInitTemplates();
+            for (const template of templates) {
+                streams.stdout(template);
+            }
+            return;
+        }
         const result = await handlers.initProject({
             directory: inputPath,
             runtime: options.runtime,
-            team: options.team
+            team: options.team,
+            template: options.template
         });
         streams.stdout(`initialized ${result.directory}`);
         emitFileLines(streams, "created", result.createdFiles);
@@ -176,7 +198,13 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     registerStatusCommand(program, handlers, streams, (exitCode) => {
         commandExitCode = exitCode;
     });
+    registerUsageCommand(program, streams, (exitCode) => {
+        commandExitCode = exitCode;
+    }, handlers);
     registerViewCommand(program, handlers, streams, cliOptions.renderEnvironment);
+    registerTrainCommand(program, handlers, streams, readPackageVersion(), (code) => {
+        commandExitCode = code;
+    }, cliOptions.signal);
     registerProductionTargetCommands(program, streams, cliOptions.stdin, (exitCode) => {
         commandExitCode = exitCode;
     });

package/dist/cli/targetCommands.d.ts

@@ -1,10 +1,9 @@
 import type { Command } from "commander";
-import { type TargetPublicArtifactSnapshot, type TargetPublicArtifactSnapshotRequest } from "../target/publicArtifactSnapshot.js";
+import { type TargetPublicArtifactSnapshotRequest, type TargetPublicArtifactSnapshotResult } from "../target/publicArtifactSnapshot.js";
 import { type TargetTopologyActivationResult } from "../target/topologyActivation.js";
 import { type SelectedTargetReceipt, type TargetResourceRequest, type TargetTopologyAttestationRequest } from "../target/contracts.js";
 import { type TargetOperation } from "./targetOperationDispatch.js";
 import { type TargetMutationResult } from "./targetReceiptOutput.js";
-import type { TargetDefaultConfig } from "./targetDefaultConfig.js";
 import { type TargetOperationLookupLoader } from "./targetLookupCommands.js";
 import type { TargetTopologyAttestationResult } from "../target/topologyAttestation.js";
 import { type TargetWorldClockSession } from "./targetWorldClockCommand.js";
@@ -20,14 +19,12 @@ export interface TargetCommandHandlerSession extends TargetWorldReadinessSession
     run<Result>(invoke: (handlers: TargetCommandHandlers) => Promise<Result>): Promise<Result>;
     activateTopology?(request: TargetTopologyAttestationRequest): Promise<TargetTopologyActivationResult>;
     attestTopology?(request: TargetTopologyAttestationRequest): Promise<TargetTopologyAttestationResult>;
-    snapshotPublicArtifact?(request: TargetPublicArtifactSnapshotRequest): Promise<TargetPublicArtifactSnapshot>;
+    snapshotPublicArtifact?(request: TargetPublicArtifactSnapshotRequest): Promise<TargetPublicArtifactSnapshotResult>;
 }
 export interface TargetCommandStreams {
     stderr(message: string): void;
     stdout(message: string): void;
 }
-type SetTargetCommandExitCode = (exitCode: 1 | 2) => void;
-export declare const registerTargetCommands: (program: Command, session: TargetCommandHandlerSession | TargetCommandSessionLoader, streams: TargetCommandStreams, setExitCode: SetTargetCommandExitCode, lookupLoader?: TargetOperationLookupLoader, worldReadinessSession?: (configInput: unknown) => Promise<TargetWorldReadinessSession & TargetWorldClockSession>) => Command;
-export declare const createProductionTargetCommandSession: (config: TargetDefaultConfig) => TargetCommandHandlerSession;
-export declare const registerProductionTargetCommands: (program: Command, streams: TargetCommandStreams, stdin: AsyncIterable<unknown>, setExitCode: SetTargetCommandExitCode) => void;
+export type SetTargetCommandExitCode = (exitCode: 1 | 2) => void;
+export declare const registerTargetCommands: (program: Command, session: TargetCommandHandlerSession | TargetCommandSessionLoader, streams: TargetCommandStreams, setExitCode: SetTargetCommandExitCode, lookupLoader?: TargetOperationLookupLoader, worldReadinessSession?: (configInput: unknown) => Promise<TargetWorldReadinessSession & TargetWorldClockSession>, configFreeCommands?: readonly string[]) => Command;
 export {};

package/dist/cli/targetCommands.js

@@ -1,17 +1,14 @@
 import { createCanonicalTargetTopologyReceiptBytes, createCanonicalSelectedTargetReceiptBytes, createTargetTopologyReceiptDigest } from "../target/handles.js";
-import { createCanonicalTargetPublicArtifactSnapshotBytes } from "../target/publicArtifactSnapshot.js";
+import { createCanonicalTargetPublicArtifactSnapshotResultBytes } from "../target/publicArtifactSnapshot.js";
 import { createCanonicalTargetTopologyActivationReceiptBytes, createTargetTopologyActivationReceiptDigest, parseTargetTopologyActivationReceipt } from "../target/topologyActivation.js";
 import { parseSelectedTargetReceipt, parseTargetTopologyReceipt } from "../target/contracts.js";
 import { TARGET_OPERATION_DISPATCH } from "./targetOperationDispatch.js";
 import { emitCanonicalTargetMutationReceipt, formatCaughtTargetCliError, formatTargetCliError } from "./targetReceiptOutput.js";
 import { readTargetRequestFile, readTargetPublicArtifactSnapshotRequestFile, readTargetTopologyAttestationRequestFile } from "./targetRequestFile.js";
-import { readTargetDefaultConfigStdin, readTargetWorldReadinessConfigStdin } from "./targetDefaultConfigStdin.js";
-import { createProductionTargetLookupLoader, registerTargetOperationLookup } from "./targetLookupCommands.js";
-import { registerContainerBundleCommand } from "./containerBundleCommand.js";
+import { registerTargetOperationLookup } from "./targetLookupCommands.js";
 import { registerTargetWorldClockCommand } from "./targetWorldClockCommand.js";
 import { registerTargetWorldReadinessCommand, } from "./targetWorldReadinessCommand.js";
 import { registerTargetComposedPreparationCommand } from "./targetComposedPreparationCommand.js";
-import { createProductionTargetWorldQuerySession } from "./targetDefaultWorldQueries.js";
 const operations = Object.keys(TARGET_OPERATION_DISPATCH);
 const invoke = async (handlers, request) => {
     const handler = handlers[request.operation];
@@ -181,7 +178,7 @@ const registerPublicArtifactSnapshot = (target, session, streams, setExitCode) =
             return;
         }
         try {
-            streams.stdout(createCanonicalTargetPublicArtifactSnapshotBytes(await activeSession.snapshotPublicArtifact(request)));
+            streams.stdout(createCanonicalTargetPublicArtifactSnapshotResultBytes(await activeSession.snapshotPublicArtifact(request)));
         }
         catch (error) {
             streams.stderr(formatCaughtTargetCliError(error, "Target public artifact snapshot crashed"));
@@ -189,10 +186,21 @@ const registerPublicArtifactSnapshot = (target, session, streams, setExitCode) =
         }
     });
 };
-export const registerTargetCommands = (program, session, streams, setExitCode, lookupLoader, worldReadinessSession) => {
+export const registerTargetCommands = (program, session, streams, setExitCode, lookupLoader, worldReadinessSession, configFreeCommands = []) => {
     const target = program.command("target").description("Execute target-resource operations");
     if (typeof session === "function") {
-        target.requiredOption("--config <config-input>", "Strict target configuration JSON stdin; use -");
+        if (configFreeCommands.length === 0) {
+            target.requiredOption("--config <config-input>", "Strict target configuration JSON stdin; use -");
+        }
+        else {
+            target.option("--config <config-input>", "Strict target configuration JSON stdin; use -");
+            target.hook("preAction", (_command, actionCommand) => {
+                if (!configFreeCommands.includes(actionCommand.name())
+                    && target.opts().config === undefined) {
+                    target.error("required option '--config <config-input>' not specified");
+                }
+            });
+        }
     }
     for (const operation of operations) {
         registerOperation(target, operation, session, streams, setExitCode);
@@ -217,41 +225,3 @@ export const registerTargetCommands = (program, session, streams, setExitCode, l
         registerTargetOperationLookup(target, lookupLoader, streams, setExitCode);
     return target;
 };
-export const createProductionTargetCommandSession = (config) => Object.freeze({
-    activateTopology: async (request) => {
-        const { activateTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
-        return activateTargetDefaultTopology(config, request);
-    },
-    run: async (invokeHandlers) => {
-        const { withTargetDefaultHandlerSession } = await import("./targetDefaultHandlers.js");
-        return withTargetDefaultHandlerSession(config, invokeHandlers);
-    },
-    attestTopology: async (request) => {
-        const { attestTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
-        return attestTargetDefaultTopology(config, request);
-    },
-    queryWorldReadiness: async (request) => {
-        const { queryTargetDefaultWorldReadiness } = await import("./targetDefaultWorldReadiness.js");
-        return queryTargetDefaultWorldReadiness(config, request);
-    },
-    queryWorldClock: async (request) => {
-        const { queryTargetDefaultWorldClock } = await import("./targetDefaultWorldClock.js");
-        return queryTargetDefaultWorldClock(config, request);
-    },
-    snapshotPublicArtifact: async (request) => {
-        const { snapshotTargetDefaultPublicArtifact } = await import("./targetDefaultHandlers.js");
-        return snapshotTargetDefaultPublicArtifact(config, request);
-    }
-});
-export const registerProductionTargetCommands = (program, streams, stdin, setExitCode) => {
-    const target = registerTargetCommands(program, async (configInput) => {
-        if (configInput !== "-")
-            throw new TypeError("Invalid target configuration");
-        return createProductionTargetCommandSession(await readTargetDefaultConfigStdin(stdin));
-    }, streams, setExitCode, createProductionTargetLookupLoader(stdin), async (configInput) => {
-        if (configInput !== "-")
-            throw new TypeError("Invalid target configuration");
-        return createProductionTargetWorldQuerySession(await readTargetWorldReadinessConfigStdin(stdin));
-    });
-    registerContainerBundleCommand(target, stdin, streams, setExitCode);
-};

package/dist/cli/targetConfigPreparedPlan.d.ts

@@ -0,0 +1,3 @@
+import { type PreparedArtifactMapping } from "./targetDefaultConfig.js";
+export declare const TARGET_CONFIG_PREPARED_PLAN_VERSION: "spawnfile.target-config-prepared-plan.v1";
+export declare const readTargetConfigPreparedPlan: (rawPath: string | undefined, evidenceDestination: string) => Promise<readonly PreparedArtifactMapping[] | undefined>;