spawnfile 0.1.13 → 0.1.17

package/dist/cli/statusCommandOptions.d.ts

@@ -0,0 +1,40 @@
+import type { CompiledProbeCollectors, StatusCommandResult, StatusOutputMode, StatusSelectorInput } from "../status/index.js";
+import { collectDeploymentLogObservations, collectMoltnetProbeObservations, collectRuntimeProbeObservations } from "../status/index.js";
+import { inspectDockerDeployment, recoverDockerDeploymentRecords } from "../deployment/index.js";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+export type StatusCommandHandlers = Pick<CliHandlers, "buildOrganizationView"> & Partial<Pick<CliHandlers, "requireAuthProfile">>;
+export interface StatusCommandLiveHandlers {
+    collectDeploymentLogObservations?: typeof collectDeploymentLogObservations;
+    collectMoltnetProbeObservations?: typeof collectMoltnetProbeObservations;
+    collectRuntimeProbeObservations?: typeof collectRuntimeProbeObservations;
+    compiledProbeCollectors?: CompiledProbeCollectors;
+    inspectDockerDeployment?: typeof inspectDockerDeployment;
+    recoverDockerDeploymentRecords?: typeof recoverDockerDeploymentRecords;
+}
+export type StatusCommandHandlersWithLive = StatusCommandHandlers & StatusCommandLiveHandlers;
+export interface StatusCommandOptions {
+    agent?: string;
+    context?: string;
+    deployment?: string;
+    dockerCommand?: string;
+    image?: boolean;
+    json?: boolean;
+    live?: boolean;
+    logs?: boolean;
+    network?: string;
+    out?: string;
+    pretty?: boolean;
+    pull?: boolean;
+    pullCheck?: boolean;
+    quiet?: boolean;
+    recover?: boolean;
+    runtime?: string;
+    team?: string;
+    timeout?: string;
+    watch?: boolean;
+}
+export declare const statusInputFailure: (message: string) => StatusCommandResult;
+export declare const resolveStatusOutputMode: (options: StatusCommandOptions) => StatusOutputMode | StatusCommandResult;
+export declare const resolveStatusSelectorInput: (options: StatusCommandOptions) => StatusSelectorInput | null | StatusCommandResult;
+export declare const resolveStatusTimeoutMs: (options: StatusCommandOptions) => number | undefined | StatusCommandResult;
+export declare const emitStatusOutput: (streams: CliStreams, output: string) => void;

package/dist/cli/statusCommandOptions.js

@@ -0,0 +1,42 @@
+export const statusInputFailure = (message) => ({
+    error: message,
+    exitCode: 2
+});
+export const resolveStatusOutputMode = (options) => {
+    const modes = [
+        ...(options.json ? ["json"] : []),
+        ...(options.pretty ? ["pretty"] : []),
+        ...(options.quiet ? ["quiet"] : [])
+    ];
+    if (modes.length > 1) {
+        return statusInputFailure("Choose only one status output mode: --pretty, --json, or --quiet");
+    }
+    return modes[0] ?? "pretty";
+};
+export const resolveStatusSelectorInput = (options) => {
+    const selectors = [
+        ...(options.agent ? [{ kind: "agent", value: options.agent }] : []),
+        ...(options.team ? [{ kind: "team", value: options.team }] : []),
+        ...(options.network ? [{ kind: "network", value: options.network }] : []),
+        ...(options.runtime ? [{ kind: "runtime", value: options.runtime }] : [])
+    ];
+    if (selectors.length > 1) {
+        return statusInputFailure("Choose only one status selector: --agent, --team, --network, or --runtime");
+    }
+    return selectors[0] ?? null;
+};
+export const resolveStatusTimeoutMs = (options) => {
+    if (!options.timeout) {
+        return undefined;
+    }
+    const parsed = Number(options.timeout);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return statusInputFailure("status --timeout must be a positive integer number of milliseconds");
+    }
+    return parsed;
+};
+export const emitStatusOutput = (streams, output) => {
+    for (const line of output.split("\n")) {
+        streams.stdout(line);
+    }
+};

package/dist/cli/targetCliRoute.d.ts

@@ -0,0 +1,2 @@
+/** Routes only when the first actual target subcommand is lookup_operation. */
+export declare const isTargetLookupInvocation: (raw: readonly unknown[]) => boolean;

package/dist/cli/targetCliRoute.js

@@ -0,0 +1,30 @@
+const MAX_ARGUMENTS = 64;
+const MAX_ARGUMENT_BYTES = 4_096;
+const bounded = (value) => typeof value === "string"
+    && value.length > 0
+    && Buffer.byteLength(value, "utf8") <= MAX_ARGUMENT_BYTES;
+/** Routes only when the first actual target subcommand is lookup_operation. */
+export const isTargetLookupInvocation = (raw) => {
+    if (!Array.isArray(raw) || raw.length < 2 || raw.length > MAX_ARGUMENTS
+        || raw.some((value) => !bounded(value)) || raw[0] !== "target")
+        return false;
+    const argv = raw;
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--config") {
+            if (!bounded(argv[index + 1]))
+                return false;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--config=")) {
+            if (token.length === "--config=".length)
+                return false;
+            continue;
+        }
+        if (token.startsWith("-"))
+            return false;
+        return token === "lookup_operation";
+    }
+    return false;
+};

package/dist/cli/targetCommands.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander";
+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 TargetOperationLookupLoader } from "./targetLookupCommands.js";
+import type { TargetTopologyAttestationResult } from "../target/topologyAttestation.js";
+import { type TargetWorldClockSession } from "./targetWorldClockCommand.js";
+import { type TargetWorldReadinessSession } from "./targetWorldReadinessCommand.js";
+type RequestFor<Operation extends TargetOperation> = Extract<TargetResourceRequest, {
+    operation: Operation;
+}>;
+export type TargetCommandHandlers = {
+    [Operation in TargetOperation]: (request: RequestFor<Operation>) => Promise<Operation extends "select_target" ? SelectedTargetReceipt : TargetMutationResult>;
+};
+export type TargetCommandSessionLoader = (configInput: unknown) => Promise<TargetCommandHandlerSession>;
+export interface TargetCommandHandlerSession extends TargetWorldReadinessSession, TargetWorldClockSession {
+    run<Result>(invoke: (handlers: TargetCommandHandlers) => Promise<Result>): Promise<Result>;
+    activateTopology?(request: TargetTopologyAttestationRequest): Promise<TargetTopologyActivationResult>;
+    attestTopology?(request: TargetTopologyAttestationRequest): Promise<TargetTopologyAttestationResult>;
+    snapshotPublicArtifact?(request: TargetPublicArtifactSnapshotRequest): Promise<TargetPublicArtifactSnapshotResult>;
+}
+export interface TargetCommandStreams {
+    stderr(message: string): void;
+    stdout(message: string): 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

@@ -0,0 +1,227 @@
+import { createCanonicalTargetTopologyReceiptBytes, createCanonicalSelectedTargetReceiptBytes, createTargetTopologyReceiptDigest } from "../target/handles.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 { registerTargetOperationLookup } from "./targetLookupCommands.js";
+import { registerTargetWorldClockCommand } from "./targetWorldClockCommand.js";
+import { registerTargetWorldReadinessCommand, } from "./targetWorldReadinessCommand.js";
+import { registerTargetComposedPreparationCommand } from "./targetComposedPreparationCommand.js";
+const operations = Object.keys(TARGET_OPERATION_DISPATCH);
+const invoke = async (handlers, request) => {
+    const handler = handlers[request.operation];
+    return handler(request);
+};
+const emitSelection = (raw, streams) => {
+    const receipt = parseSelectedTargetReceipt(raw);
+    streams.stdout(createCanonicalSelectedTargetReceiptBytes(receipt));
+};
+const registerOperation = (target, operation, session, streams, setExitCode) => {
+    target.command(operation)
+        .description(`Execute the ${operation} target operation`)
+        .argument("<request-file>", "Strict target-resource request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetRequestFile(requestFile);
+            if (request.operation !== operation)
+                throw new TypeError("operation mismatch");
+        }
+        catch {
+            streams.stderr(formatTargetCliError("request"));
+            setExitCode(2);
+            return;
+        }
+        let activeSession;
+        try {
+            activeSession = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const result = await activeSession.run((handlers) => invoke(handlers, request));
+            if (operation === "select_target") {
+                emitSelection(result, streams);
+            }
+            else {
+                emitCanonicalTargetMutationReceipt(result, streams.stdout);
+            }
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target operation crashed"));
+            setExitCode(1);
+        }
+    });
+};
+const emitTopologyReceipt = (raw, streams) => {
+    const receipt = parseTargetTopologyReceipt(raw.receipt);
+    const bytes = createCanonicalTargetTopologyReceiptBytes(receipt);
+    if (typeof raw.receiptBytes !== "string" || raw.receiptBytes !== bytes
+        || receipt.receipt_digest !== createTargetTopologyReceiptDigest(receipt)) {
+        throw new TypeError("Target attestation returned a non-canonical receipt");
+    }
+    streams.stdout(bytes);
+};
+const emitTopologyActivationReceipt = (raw, streams) => {
+    const receipt = parseTargetTopologyActivationReceipt(raw.receipt);
+    const bytes = createCanonicalTargetTopologyActivationReceiptBytes(receipt);
+    if (typeof raw.receiptBytes !== "string" || raw.receiptBytes !== bytes
+        || receipt.receipt_digest !== createTargetTopologyActivationReceiptDigest(receipt)) {
+        throw new TypeError("Target activation returned a non-canonical receipt");
+    }
+    streams.stdout(bytes);
+};
+const registerTopologyActivation = (target, session, streams, setExitCode) => {
+    target.command("activate_topology")
+        .description("Release one exact attested target topology")
+        .argument("<request-file>", "Strict target topology-attestation request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetTopologyAttestationRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid target activation request");
+            setExitCode(2);
+            return;
+        }
+        let activeSession;
+        try {
+            activeSession = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+            if (typeof activeSession.activateTopology !== "function")
+                throw new TypeError();
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            emitTopologyActivationReceipt(await activeSession.activateTopology(request), streams);
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target topology activation crashed"));
+            setExitCode(1);
+        }
+    });
+};
+const registerTopologyAttestation = (target, session, streams, setExitCode) => {
+    target.command("attest_topology")
+        .description("Attest one exact composed target topology")
+        .argument("<request-file>", "Strict target topology-attestation request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetTopologyAttestationRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid target attestation request");
+            setExitCode(2);
+            return;
+        }
+        let activeSession;
+        try {
+            activeSession = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+            if (typeof activeSession.attestTopology !== "function")
+                throw new TypeError();
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            emitTopologyReceipt(await activeSession.attestTopology(request), streams);
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target topology attestation crashed"));
+            setExitCode(1);
+        }
+    });
+};
+const registerPublicArtifactSnapshot = (target, session, streams, setExitCode) => {
+    target.command("snapshot_public_artifact")
+        .description("Read one exact bounded public artifact from a world service")
+        .argument("<request-file>", "Strict public artifact snapshot request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readTargetPublicArtifactSnapshotRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid public artifact snapshot request");
+            setExitCode(2);
+            return;
+        }
+        let activeSession;
+        try {
+            activeSession = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+            if (typeof activeSession.snapshotPublicArtifact !== "function")
+                throw new TypeError();
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            streams.stdout(createCanonicalTargetPublicArtifactSnapshotResultBytes(await activeSession.snapshotPublicArtifact(request)));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Target public artifact snapshot crashed"));
+            setExitCode(1);
+        }
+    });
+};
+export const registerTargetCommands = (program, session, streams, setExitCode, lookupLoader, worldReadinessSession, configFreeCommands = []) => {
+    const target = program.command("target").description("Execute target-resource operations");
+    if (typeof session === "function") {
+        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);
+    }
+    registerTargetComposedPreparationCommand(target, session, streams, setExitCode);
+    if (typeof session === "function" || typeof session.attestTopology === "function") {
+        registerTopologyAttestation(target, session, streams, setExitCode);
+    }
+    if (typeof session === "function" || typeof session.snapshotPublicArtifact === "function") {
+        registerPublicArtifactSnapshot(target, session, streams, setExitCode);
+    }
+    if (typeof session === "function" || typeof session.queryWorldReadiness === "function") {
+        registerTargetWorldReadinessCommand(target, worldReadinessSession ?? session, streams, setExitCode);
+    }
+    if (typeof session === "function" || typeof session.queryWorldClock === "function") {
+        registerTargetWorldClockCommand(target, worldReadinessSession ?? session, streams, setExitCode);
+    }
+    if (typeof session === "function" || typeof session.activateTopology === "function") {
+        registerTopologyActivation(target, session, streams, setExitCode);
+    }
+    if (lookupLoader)
+        registerTargetOperationLookup(target, lookupLoader, streams, setExitCode);
+    return target;
+};

package/dist/cli/targetComposedPreparationCommand.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+import type { TargetCommandHandlerSession, TargetCommandSessionLoader, TargetCommandStreams } from "./targetCommands.js";
+type SetExitCode = (exitCode: 1 | 2) => void;
+/** Registers the sole aggregate preparation path consumed by Simfile. */
+export declare const registerTargetComposedPreparationCommand: (target: Command, session: TargetCommandHandlerSession | TargetCommandSessionLoader, streams: TargetCommandStreams, setExitCode: SetExitCode) => void;
+export {};

package/dist/cli/targetComposedPreparationCommand.js

@@ -0,0 +1,39 @@
+import { createCanonicalComposedPreparationReceiptBytes, prepareComposedRun, } from "../target/composedPreparation.js";
+import { formatCaughtTargetCliError } from "./targetReceiptOutput.js";
+import { readComposedPreparationRequestFile } from "./targetRequestFile.js";
+/** Registers the sole aggregate preparation path consumed by Simfile. */
+export const registerTargetComposedPreparationCommand = (target, session, streams, setExitCode) => {
+    target.command("prepare_composed_run")
+        .description("Prepare one immutable composed-run target resource set")
+        .argument("<request-file>", "Strict composed-preparation request JSON file")
+        .action(async (requestFile) => {
+        let request;
+        try {
+            request = await readComposedPreparationRequestFile(requestFile);
+        }
+        catch {
+            streams.stderr("error: Invalid composed preparation request");
+            setExitCode(2);
+            return;
+        }
+        let activeSession;
+        try {
+            activeSession = typeof session === "function"
+                ? await session(target.opts().config)
+                : session;
+        }
+        catch {
+            streams.stderr("error: Invalid target configuration");
+            setExitCode(2);
+            return;
+        }
+        try {
+            const receipt = await activeSession.run((handlers) => prepareComposedRun(handlers, request));
+            streams.stdout(createCanonicalComposedPreparationReceiptBytes(receipt));
+        }
+        catch (error) {
+            streams.stderr(formatCaughtTargetCliError(error, "Composed preparation crashed"));
+            setExitCode(1);
+        }
+    });
+};

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;