spawnfile 0.1.13 → 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,8 +1,10 @@
-import { importClaudeCodeAuth, importCodexAuth, importEnvFile, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, 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 { 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;
@@ -13,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;
@@ -26,13 +30,24 @@ 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;
     runProject: typeof runProject;
     upProject: typeof upProject;
+    buildUpReceipt: typeof buildUpReceipt;
     consumeImageUp: typeof consumeImageUp;
     devActivityProject: typeof devActivityProject;
     devApplyProject: typeof devApplyProject;
@@ -48,7 +63,9 @@ export interface CliHandlers {
 export interface RunCliOptions {
     handlers?: Partial<CliHandlers>;
     renderEnvironment?: CliRenderEnvironment;
+    stdin?: AsyncIterable<unknown>;
     streams?: CliStreams;
+    signal?: AbortSignal;
 }
 type RunCli = {
     (argv: string[], options?: RunCliOptions): Promise<number>;

package/dist/cli/runCli.js

@@ -1,18 +1,27 @@
 import { readFileSync } from "node:fs";
 import { Command } from "commander";
-import { importClaudeCodeAuth, importCodexAuth, importEnvFile, requireAuthProfile } from "../auth/index.js";
-import { addAgentProject, addProjectSurface, addProjectModelFallback, addSubagentProject, addTeamProject, buildOrganizationView, buildCompilePlan, buildProject, 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 { 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 { 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"));
@@ -28,12 +37,16 @@ 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,
-    initProject, listRuntimeAdapters, removeProjectSurface, requireAuthProfile,
-    runProject, setProjectPrimaryModel, setProjectRuntime, upProject, consumeImageUp,
+    importClaudeCodeAuth, importCodexAuth, importGrokAuth, importEnvFile, initializeTargetSecretSourceLifecycle,
+    provisionCredentials,
+    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
 });
@@ -45,12 +58,15 @@ const normalizeRunCliOptions = (optionsOrStreams, handlerOverrides = {}) => isCl
     ? {
         handlers: handlerOverrides,
         renderEnvironment: createDefaultRenderEnvironment(),
+        stdin: process.stdin,
         streams: optionsOrStreams
     }
     : {
         handlers: optionsOrStreams?.handlers ?? handlerOverrides,
         renderEnvironment: optionsOrStreams?.renderEnvironment ?? createDefaultRenderEnvironment(),
-        streams: optionsOrStreams?.streams ?? createDefaultStreams()
+        stdin: optionsOrStreams?.stdin ?? process.stdin,
+        streams: optionsOrStreams?.streams ?? createDefaultStreams(),
+        signal: optionsOrStreams?.signal
     };
 const writeCommanderOutput = (write, message) => {
     const normalized = message.replace(/\n$/, "");
@@ -58,6 +74,7 @@ const writeCommanderOutput = (write, message) => {
         write(normalized);
     }
 };
+const TARGET_CLI_USAGE_ERROR = "error: Invalid target command";
 const isCommanderError = (error) => {
     if (typeof error !== "object" || error === null) {
         return false;
@@ -82,43 +99,53 @@ const formatPlanSummary = (plan) => [
     `nodes: ${plan.nodes.length}`,
     `runtimes: ${Object.keys(plan.runtimes).sort().join(", ") || "none"}`
 ].join("\n");
-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 emitFileLines = (streams, label, filePaths) => emitLines(streams, filePaths.map((filePath) => `${label} ${filePath}`));
 export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     const cliOptions = normalizeRunCliOptions(optionsOrStreams, handlerOverrides);
     const streams = cliOptions.streams;
     const handlers = { ...createDefaultHandlers(), ...cliOptions.handlers };
+    const isTargetInvocation = argv[0] === "target";
     let commandExitCode = 0;
     const program = new Command();
     program.name("spawnfile").description("Spawnfile v0.1 compiler").version(readPackageVersion());
     program.exitOverride();
     program.configureOutput({
         outputError: (message, write) => write(message),
-        writeErr: (message) => writeCommanderOutput(streams.stderr, message),
+        writeErr: (message) => {
+            if (!isTargetInvocation)
+                writeCommanderOutput(streams.stderr, message);
+        },
         writeOut: (message) => writeCommanderOutput(streams.stdout, message)
     });
-    registerLifecycleCommands(program, handlers, streams);
+    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);
@@ -171,7 +198,16 @@ 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;
+    });
     program
         .command("validate")
         .description("Validate a Spawnfile and report the resolved compile plan")
@@ -189,68 +225,16 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
             streams.stdout(runtimeName);
         }
     });
-    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));
-    });
+    registerAuthCommands(program, handlers, streams, cliOptions.stdin);
     try {
         await program.parseAsync(argv, { from: "user" });
         return commandExitCode;
     }
     catch (error) {
         if (isCommanderError(error)) {
+            if (isTargetInvocation && error.exitCode !== 0) {
+                streams.stderr(TARGET_CLI_USAGE_ERROR);
+            }
             // Commander prints its own usage message; usage errors exit 2.
             return error.exitCode === 0 ? 0 : 2;
         }

package/dist/cli/runPublishCommands.d.ts

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