spawnfile 0.1.14 → 0.1.18

package/dist/cli/runCli.js

@@ -1,22 +1,29 @@
 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, createTrainingPlan, loadTrainingProject, resolveTrainingPlan, materializeTrainingMoment, lowerTrainingExecution, allocateTrainingOutputParent, initProject, listInitTemplates, preflightCompilePlan, 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 { registerRecordCommands } from "./recordCommands.js";
+import { registerProductionTargetCommands } from "./targetProductionCommands.js";
 import { registerViewCommand } from "./viewCommand.js";
+import { registerVolumeCommands } from "./volumeCommands.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 +39,15 @@ const createDefaultRenderEnvironment = () => ({
     stdoutIsTty: process.stdout.isTTY === true
 });
 const createDefaultHandlers = () => ({
+    createTrainingContext, createTrainingPlan, loadTrainingProject, resolveTrainingPlan, materializeTrainingMoment, lowerTrainingExecution, allocateTrainingOutputParent, 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 +67,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$/, "");
@@ -110,20 +120,34 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
         },
         writeOut: (message) => writeCommanderOutput(streams.stdout, message)
     });
-    registerLifecycleCommands(program, handlers, streams, cliOptions.stdin);
+    registerLifecycleCommands(program, handlers, streams, cliOptions.stdin, (code) => { commandExitCode = code; });
     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,16 +200,25 @@ export const runCli = async (argv, optionsOrStreams, handlerOverrides = {}) => {
     registerStatusCommand(program, handlers, streams, (exitCode) => {
         commandExitCode = exitCode;
     });
+    registerUsageCommand(program, streams, (exitCode) => { commandExitCode = exitCode; }, handlers);
+    registerRecordCommands(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;
     });
+    registerVolumeCommands(program, streams, (exitCode) => {
+        commandExitCode = exitCode;
+    });
     program
         .command("validate")
         .description("Validate a Spawnfile and report the resolved compile plan")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .action(async (inputPath) => {
         const plan = await handlers.buildCompilePlan(inputPath);
+        preflightCompilePlan(plan);
         streams.stdout("validation succeeded");
         streams.stdout(formatPlanSummary(plan));
     });

package/dist/cli/runPublishCommands.js

@@ -1,5 +1,6 @@
 import { SpawnfileError } from "../shared/index.js";
 import { resolveCommandInput } from "./resolveCommandInput.js";
+import { envFileAliasOption, resolveEnvFileOption, runtimeEnvFileOption } from "./envFileOption.js";
 export const registerRunPublishCommands = (program, handlers, streams) => {
     program
         .command("run")
@@ -12,7 +13,8 @@ export const registerRunPublishCommands = (program, handlers, streams) => {
         .option("--deployment <name>", "Detached deployment record name")
         .option("--docker-command <command>", "Docker command")
         .option("--name <container>", "Docker container name")
-        .option("--env-file <file>", "Path to an env file for runtime secrets")
+        .addOption(runtimeEnvFileOption("Path to an env file for runtime secrets"))
+        .addOption(envFileAliasOption())
         .option("--world-bindings <file>", "Path to a versioned world-bindings artifact")
         .option("--image", "Interpret the argument as an image reference")
         .option("-d, --detach", "Run the container in detached mode")
@@ -21,7 +23,7 @@ export const registerRunPublishCommands = (program, handlers, streams) => {
         if (runInput.kind === "image" || (runInput.kind === "invalid" && options.image)) {
             throw new SpawnfileError("validation_error", `Image-mode run is not supported. Deploy the image with: ` +
                 `spawnfile up ${inputPath} --auth-profile <profile> ` +
-                "(add --env-file for any extra secrets; image deployments always detach).");
+                "(add --runtime-env-file for any extra secrets; image deployments always detach).");
         }
         if (runInput.kind === "invalid") {
             throw new SpawnfileError("validation_error", `Cannot resolve "${inputPath}" as a project path or image reference. ` +
@@ -34,7 +36,7 @@ export const registerRunPublishCommands = (program, handlers, streams) => {
             deploymentName: options.deployment,
             dockerCommand: options.dockerCommand,
             dockerContext: options.context,
-            envFilePath: options.envFile,
+            envFilePath: resolveEnvFileOption(options),
             imageTag: options.tag,
             outputDirectory: options.out,
             ...(options.worldBindings !== undefined

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>;

package/dist/cli/targetConfigPreparedPlan.js

@@ -0,0 +1,74 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { parseTargetPreparedArtifactMappings, } from "./targetDefaultConfig.js";
+export const TARGET_CONFIG_PREPARED_PLAN_VERSION = "spawnfile.target-config-prepared-plan.v1";
+const MAX_PATH_BYTES = 4_096;
+const MAX_PREPARED_PLAN_BYTES = 128 * 1_024;
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+const planPath = (value) => {
+    if (typeof value !== "string" || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > MAX_PATH_BYTES
+        || !path.isAbsolute(value) || path.normalize(value) !== value) {
+        return fail("Prepared target plan path must be absolute and normalized");
+    }
+    return value;
+};
+export const readTargetConfigPreparedPlan = async (rawPath, evidenceDestination) => {
+    if (rawPath === undefined)
+        return undefined;
+    const resolved = planPath(rawPath);
+    const owner = process.getuid?.();
+    let handle;
+    try {
+        const before = await lstat(resolved);
+        if (!before.isFile() || before.isSymbolicLink() || before.size < 1
+            || before.size > MAX_PREPARED_PLAN_BYTES || (before.mode & 0o777) !== 0o600
+            || owner !== undefined && before.uid !== owner) {
+            return fail("Prepared target plan must be a private bounded regular file");
+        }
+        handle = await open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (after.dev !== before.dev || after.ino !== before.ino || after.size !== bytes.byteLength) {
+            return fail("Prepared target plan changed while it was read");
+        }
+        let source;
+        try {
+            source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        }
+        catch {
+            return fail("Prepared target plan must be UTF-8 JSON");
+        }
+        const parsed = JSON.parse(source);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+            || Object.keys(parsed).sort().join("\0")
+                !== "evidence_destination\0prepared_artifact_mapping\0version") {
+            return fail("Prepared target plan has an invalid shape");
+        }
+        const value = parsed;
+        if (value.version !== TARGET_CONFIG_PREPARED_PLAN_VERSION) {
+            return fail("Prepared target plan version is invalid");
+        }
+        if (value.evidence_destination !== evidenceDestination) {
+            return fail("Prepared target plan evidence destination does not match");
+        }
+        try {
+            return parseTargetPreparedArtifactMappings([value.prepared_artifact_mapping]);
+        }
+        catch {
+            return fail("Prepared target plan artifact mapping is invalid");
+        }
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        return fail("Prepared target plan is unavailable");
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+};

package/dist/cli/targetConfigResolver.d.ts

@@ -0,0 +1,3 @@
+import { type ResolveTargetConfigDependencies, type ResolveTargetConfigInput, type TargetConfigResolution } from "./targetConfigResolverContracts.js";
+export { createCanonicalTargetConfigBytes, createTargetConfigDigest, createTargetConfigResolutionBytes, STANDARD_WORLD_BASE_IMAGE, TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION, type ResolveTargetConfigDependencies, type ResolveTargetConfigInput, type TargetConfigResolution, } from "./targetConfigResolverContracts.js";
+export declare const resolveTargetConfig: (input: ResolveTargetConfigInput, dependencies?: ResolveTargetConfigDependencies) => Promise<TargetConfigResolution>;

package/dist/cli/targetConfigResolver.js

@@ -0,0 +1,111 @@
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { createPreparedEvidenceHelperExecutor, parsePreparedEvidenceHelperReceipt, prepareEvidenceExportHelper, } from "../evidenceExportHelper/index.js";
+import { defaultDockerTargetExecFile, resolveDockerContextEndpoint } from "../target/dockerTargetBinding.js";
+import { createTargetConfigDigest, STANDARD_WORLD_BASE_IMAGE, TARGET_CONFIG_RESOLUTION_VERSION, } from "./targetConfigResolverContracts.js";
+import { exactJson, executeDocker, resolveCurrentDockerContext } from "./targetConfigResolverDocker.js";
+import { classifyEndpoint, normalizeArchitecture, parseBaseImage, parseContext, parseDockerCommand, parseTimeout, runtimeFailure, validateEvidenceDestination, validationFailure, } from "./targetConfigResolverValidation.js";
+import { readTargetConfigPreparedPlan } from "./targetConfigPreparedPlan.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION } from "./targetDefaultConfigStdin.js";
+export { createCanonicalTargetConfigBytes, createTargetConfigDigest, createTargetConfigResolutionBytes, STANDARD_WORLD_BASE_IMAGE, TARGET_CONFIG_DIGEST_VERSION, TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION, TARGET_CONFIG_RESOLUTION_VERSION, } from "./targetConfigResolverContracts.js";
+export const resolveTargetConfig = async (input, dependencies = {}) => {
+    const baseImage = parseBaseImage(input.baseImage ?? STANDARD_WORLD_BASE_IMAGE);
+    const dockerCommand = parseDockerCommand(input.dockerCommand ?? "docker");
+    const timeoutMs = parseTimeout(input.timeoutMs ?? 10_000);
+    const evidenceDestination = await validateEvidenceDestination(input.evidenceDestination);
+    const preparedArtifactMappings = await readTargetConfigPreparedPlan(input.preparedPlanPath, evidenceDestination);
+    const execFile = input.execFile ?? defaultDockerTargetExecFile;
+    const contextSelection = input.context === undefined ? "auto-local" : "explicit";
+    const context = input.context === undefined
+        ? await resolveCurrentDockerContext(execFile, dockerCommand, timeoutMs, input.signal)
+        : parseContext(input.context);
+    let endpointValue;
+    try {
+        endpointValue = await resolveDockerContextEndpoint(context, {
+            dockerCommand, execFile, signal: input.signal, timeoutMs,
+        });
+    }
+    catch {
+        return runtimeFailure(`Unable to inspect Docker context "${context}"`);
+    }
+    const endpoint = classifyEndpoint(endpointValue);
+    if (contextSelection === "auto-local" && endpoint.class !== "local") {
+        return validationFailure("Current Docker context is remote; pass --context explicitly to select a remote target");
+    }
+    if (input.prepareEvidenceHelper === true
+        && (contextSelection !== "explicit" || endpoint.class !== "local")) {
+        return validationFailure("Evidence helper preparation requires an explicitly selected local Docker context");
+    }
+    if (input.pull === true && endpoint.class === "remote" && input.allowRemotePull !== true) {
+        return validationFailure("Pulling on a remote Docker context requires --allow-remote-pull");
+    }
+    const infoSource = await executeDocker(execFile, dockerCommand, context, ["info", "--format", "{\"Architecture\":{{json .Architecture}},\"OSType\":{{json .OSType}}}"], timeoutMs, input.signal, "Unable to inspect Docker target platform");
+    const info = exactJson(infoSource, ["Architecture", "OSType"], "Docker target platform is invalid");
+    if (info.OSType !== "linux")
+        return runtimeFailure("Docker target operating system is unsupported");
+    const architecture = normalizeArchitecture(info.Architecture);
+    if (input.pull === true) {
+        await executeDocker(execFile, dockerCommand, context, ["image", "pull", "--quiet", baseImage], timeoutMs, input.signal, "Unable to pull the requested base image");
+    }
+    const imageSource = await executeDocker(execFile, dockerCommand, context, ["image", "inspect", baseImage, "--format",
+        "{\"Architecture\":{{json .Architecture}},\"Id\":{{json .Id}},\"Os\":{{json .Os}}}"], timeoutMs, input.signal, input.pull === true
+        ? "Unable to inspect the pulled base image"
+        : "Base image is unavailable in the Docker context; rerun with --pull to fetch it");
+    const image = exactJson(imageSource, ["Architecture", "Id", "Os"], "Docker base image inspection is invalid");
+    const imageArchitecture = normalizeArchitecture(image.Architecture);
+    if (image.Os !== "linux" || imageArchitecture !== architecture) {
+        return runtimeFailure("Docker base image platform does not match the selected target");
+    }
+    if (typeof image.Id !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(image.Id)) {
+        return runtimeFailure("Docker base image config ID is invalid");
+    }
+    let preparedEvidenceHelper;
+    if (input.prepareEvidenceHelper === true) {
+        try {
+            preparedEvidenceHelper = parsePreparedEvidenceHelperReceipt(await (dependencies.prepareEvidenceExportHelper ?? prepareEvidenceExportHelper)({
+                baseImage,
+                context,
+                executor: input.execFile === undefined
+                    ? createPreparedEvidenceHelperExecutor(dockerCommand)
+                    : async (file, args, options) => {
+                        if (file !== "docker")
+                            throw new Error("unexpected helper executable");
+                        return execFile(dockerCommand, args, {
+                            signal: options.signal,
+                            stdin: options.stdin,
+                            timeout: options.timeout,
+                        });
+                    },
+                privateRoot: path.join(resolveSpawnfileHome(), "target", "evidence-helper"),
+                signal: input.signal,
+                timeoutMs,
+            }));
+        }
+        catch {
+            return runtimeFailure("Evidence helper preparation failed for the selected local target");
+        }
+    }
+    const targetConfig = Object.freeze({
+        context, dockerCommand, evidenceDestination,
+        ...(preparedEvidenceHelper === undefined ? {} : {
+            evidenceHelperBaseImage: baseImage, preparedEvidenceHelper,
+        }),
+        ...(preparedArtifactMappings === undefined ? {} : { preparedArtifactMappings }),
+        timeoutMs,
+        version: TARGET_DEFAULT_CONFIG_STDIN_VERSION,
+    });
+    return Object.freeze({
+        base_image: Object.freeze({
+            config_digest: image.Id, reference: baseImage,
+        }),
+        context_selection: contextSelection,
+        endpoint,
+        platform: Object.freeze({ architecture, os: "linux" }),
+        ...(preparedEvidenceHelper === undefined ? {} : {
+            prepared_evidence_helper: preparedEvidenceHelper,
+        }),
+        target_config: targetConfig,
+        target_config_digest: createTargetConfigDigest(targetConfig),
+        version: TARGET_CONFIG_RESOLUTION_VERSION,
+    });
+};

package/dist/cli/targetConfigResolverCommand.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+import { type ResolveTargetConfigInput, type TargetConfigResolution } from "./targetConfigResolver.js";
+import type { SetTargetCommandExitCode, TargetCommandStreams } from "./targetCommands.js";
+export declare const TARGET_CONFIG_RESOLVER_COMMAND = "resolve_config";
+export type TargetConfigResolver = (input: ResolveTargetConfigInput) => Promise<TargetConfigResolution>;
+export declare const registerTargetConfigResolverCommand: (target: Command, streams: TargetCommandStreams, setExitCode: SetTargetCommandExitCode, resolver?: TargetConfigResolver) => void;

package/dist/cli/targetConfigResolverCommand.js

@@ -0,0 +1,43 @@
+import { errorExitCode, SpawnfileError } from "../shared/index.js";
+import { createTargetConfigResolutionBytes, resolveTargetConfig, } from "./targetConfigResolver.js";
+import { formatCaughtTargetCliError } from "./targetReceiptOutput.js";
+export const TARGET_CONFIG_RESOLVER_COMMAND = "resolve_config";
+const timeout = (value) => {
+    if (!/^[1-9][0-9]{0,5}$/u.test(value)) {
+        throw new SpawnfileError("validation_error", "Target timeout must be an integer from 1 to 120000 milliseconds");
+    }
+    return Number(value);
+};
+export const registerTargetConfigResolverCommand = (target, streams, setExitCode, resolver = resolveTargetConfig) => {
+    target.command(TARGET_CONFIG_RESOLVER_COMMAND)
+        .description("Resolve one explicit Docker context and base image into target configuration")
+        .option("--context <name>", "Explicit named Docker context; omitted accepts only the current local context")
+        .option("--base-image <reference>", "Portable base image reference; defaults to Spawnfile's standard world base")
+        .requiredOption("--evidence-destination <path>", "Absolute private evidence archive destination")
+        .option("--docker-command <command>", "Docker-compatible command", "docker")
+        .option("--prepare-evidence-helper", "Prepare the package-owned evidence helper on an explicitly selected local Docker context")
+        .option("--timeout-ms <milliseconds>", "Bounded Docker command timeout", "10000")
+        .option("--prepared-plan <path>", "Absolute private composed target plan containing one prepared artifact mapping")
+        .option("--pull", "Explicitly pull the base image before inspection")
+        .option("--allow-remote-pull", "Allow --pull to mutate the explicitly named remote Docker context")
+        .action(async (options) => {
+        try {
+            const resolution = await resolver({
+                allowRemotePull: options.allowRemotePull,
+                baseImage: options.baseImage,
+                context: options.context,
+                dockerCommand: options.dockerCommand,
+                evidenceDestination: options.evidenceDestination,
+                prepareEvidenceHelper: options.prepareEvidenceHelper,
+                preparedPlanPath: options.preparedPlan,
+                pull: options.pull,
+                timeoutMs: timeout(options.timeoutMs),
+            });
+            streams.stdout(createTargetConfigResolutionBytes(resolution));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target configuration resolution failed"));
+            setExitCode(errorExitCode(error));
+        }
+    });
+};

package/dist/cli/targetConfigResolverContracts.d.ts

@@ -0,0 +1,56 @@
+import type { PreparedEvidenceHelperReceipt, PrepareEvidenceHelperInput } from "../evidenceExportHelper/index.js";
+import type { DockerTargetExecFile } from "../target/dockerTarget.js";
+import type { PreparedArtifactMapping } from "./targetDefaultConfig.js";
+import { TARGET_DEFAULT_CONFIG_STDIN_VERSION } from "./targetDefaultConfigStdin.js";
+export declare const TARGET_CONFIG_RESOLUTION_VERSION: "spawnfile.target-config-resolution.v1";
+export declare const TARGET_CONFIG_DIGEST_VERSION: "spawnfile.target-config-digest.v1";
+/** Exact version for the strict `resolve_config --prepared-plan` document. */
+export declare const TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION: "spawnfile.target-config-prepared-plan.v1";
+export declare const STANDARD_WORLD_BASE_IMAGE = "node:22-bookworm-slim";
+export interface ResolveTargetConfigInput {
+    readonly allowRemotePull?: boolean;
+    readonly baseImage?: string;
+    readonly context?: string;
+    readonly dockerCommand?: string;
+    readonly evidenceDestination: string;
+    readonly prepareEvidenceHelper?: boolean;
+    readonly execFile?: DockerTargetExecFile;
+    readonly preparedPlanPath?: string;
+    readonly pull?: boolean;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+export interface TargetConfigResolution {
+    readonly base_image: {
+        readonly config_digest: `sha256:${string}`;
+        readonly reference: string;
+    };
+    readonly endpoint: {
+        readonly class: "local" | "remote";
+        readonly transport: "fd" | "http" | "https" | "npipe" | "ssh" | "tcp" | "unix";
+    };
+    readonly context_selection: "auto-local" | "explicit";
+    readonly platform: {
+        readonly architecture: "amd64" | "arm64";
+        readonly os: "linux";
+    };
+    readonly prepared_evidence_helper?: PreparedEvidenceHelperReceipt;
+    readonly target_config: {
+        readonly context: string;
+        readonly dockerCommand: string;
+        readonly evidenceDestination: string;
+        readonly evidenceHelperBaseImage?: string;
+        readonly preparedEvidenceHelper?: PreparedEvidenceHelperReceipt;
+        readonly preparedArtifactMappings?: readonly PreparedArtifactMapping[];
+        readonly timeoutMs: number;
+        readonly version: typeof TARGET_DEFAULT_CONFIG_STDIN_VERSION;
+    };
+    readonly target_config_digest: `sha256:${string}`;
+    readonly version: typeof TARGET_CONFIG_RESOLUTION_VERSION;
+}
+export interface ResolveTargetConfigDependencies {
+    readonly prepareEvidenceExportHelper?: (input: PrepareEvidenceHelperInput) => Promise<PreparedEvidenceHelperReceipt>;
+}
+export declare const createCanonicalTargetConfigBytes: (targetConfig: TargetConfigResolution["target_config"]) => string;
+export declare const createTargetConfigDigest: (targetConfig: TargetConfigResolution["target_config"]) => `sha256:${string}`;
+export declare const createTargetConfigResolutionBytes: (resolution: TargetConfigResolution) => string;

package/dist/cli/targetConfigResolverContracts.js

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+import { TARGET_CONFIG_PREPARED_PLAN_VERSION } from "./targetConfigPreparedPlan.js";
+export const TARGET_CONFIG_RESOLUTION_VERSION = "spawnfile.target-config-resolution.v1";
+export const TARGET_CONFIG_DIGEST_VERSION = "spawnfile.target-config-digest.v1";
+/** Exact version for the strict `resolve_config --prepared-plan` document. */
+export const TARGET_CONFIG_PREPARED_PLAN_ABI_VERSION = TARGET_CONFIG_PREPARED_PLAN_VERSION;
+export const STANDARD_WORLD_BASE_IMAGE = "node:22-bookworm-slim";
+const canonicalJson = (value) => {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("Target configuration is not JSON");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (typeof value !== "object")
+        throw new TypeError("Target configuration is not JSON");
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+};
+export const createCanonicalTargetConfigBytes = (targetConfig) => canonicalJson(targetConfig);
+export const createTargetConfigDigest = (targetConfig) => `sha256:${createHash("sha256")
+    .update(`${TARGET_CONFIG_DIGEST_VERSION}\0`, "utf8")
+    .update(createCanonicalTargetConfigBytes(targetConfig), "utf8")
+    .digest("hex")}`;
+export const createTargetConfigResolutionBytes = (resolution) => JSON.stringify(resolution);

package/dist/cli/targetConfigResolverDocker.d.ts

@@ -0,0 +1,4 @@
+import type { DockerTargetExecFile } from "../target/dockerTarget.js";
+export declare const exactJson: (source: string, keys: readonly string[], failureMessage: string) => Record<string, unknown>;
+export declare const executeDocker: (execFile: DockerTargetExecFile, command: string, context: string, args: string[], timeout: number, signal: AbortSignal | undefined, failureMessage: string) => Promise<string>;
+export declare const resolveCurrentDockerContext: (execFile: DockerTargetExecFile, dockerCommand: string, timeoutMs: number, signal: AbortSignal | undefined) => Promise<string>;