spawnfile 0.1.11 → 0.1.13

package/dist/compiler/runProject.d.ts

@@ -1,36 +1,50 @@
 import { type ResolvedAuthProfile } from "../auth/index.js";
+import { type DockerTargetExecFile } from "../deployment/index.js";
 import { type CompileProjectOptions, type CompileProjectResult } from "./compileProject.js";
-export interface DockerRunInvocation {
-    args: string[];
-    command: string;
-    containerName: string | null;
-    cwd: string;
-    detach: boolean;
-    envFilePath: string;
-    imageTag: string;
-    supportDirectory: string;
-}
-export type DockerRunRunner = (invocation: DockerRunInvocation) => Promise<void>;
+import { runDockerContainer, type DockerRunInvocation, type DockerRunResult, type DockerRunRunner } from "./runProjectDocker.js";
+export { runDockerContainer };
+export type { DockerRunInvocation, DockerRunResult, DockerRunRunner };
 export interface RunProjectOptions extends CompileProjectOptions {
     authProfile?: string;
     containerName?: string;
     detach?: boolean;
+    deploymentName?: string;
     dockerCommand?: string;
+    dockerContext?: string;
+    dockerHost?: string;
     envFilePath?: string;
     imageTag?: string;
     runRunner?: DockerRunRunner;
+    targetExecFile?: DockerTargetExecFile;
 }
 export interface RunProjectResult extends CompileProjectResult {
     authProfileName: string | null;
     containerName: string | null;
+    deploymentRecordPath?: string | null;
     imageTag: string;
 }
 export declare const createDockerRunInvocation: (compileResult: CompileProjectResult, imageTag: string, options?: {
     authProfile?: ResolvedAuthProfile | null;
     containerName?: string;
     detach?: boolean;
+    deploymentName?: string;
     dockerCommand?: string;
+    dockerContext?: string;
+    dockerHost?: string;
     envFilePath?: string;
 }) => Promise<DockerRunInvocation>;
-export declare const runDockerContainer: DockerRunRunner;
+interface ResolvedRunDeploymentOptions {
+    authProfile?: string;
+    containerName?: string;
+    deploymentName?: string;
+    dockerCommand?: string;
+    dockerContext?: string;
+    dockerHost?: string;
+    envFilePath?: string;
+    imageTag?: string;
+    targetExecFile?: DockerTargetExecFile;
+}
+export declare const resolveDetachedDeploymentOptions: (outputDirectory: string, options: ResolvedRunDeploymentOptions & {
+    detach?: boolean;
+}) => Promise<ResolvedRunDeploymentOptions>;
 export declare const runProject: (inputPath: string, options?: RunProjectOptions) => Promise<RunProjectResult>;

package/dist/compiler/runProject.js

@@ -1,15 +1,16 @@
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp } from "node:fs/promises";
-import { randomBytes } from "node:crypto";
-import { spawn } from "node:child_process";
-import { parseEnvFile, requireAuthProfile } from "../auth/index.js";
-import { ensureDirectory, fileExists, readUtf8File, removeDirectory, writeUtf8File } from "../filesystem/index.js";
-import { SpawnfileError } from "../shared/index.js";
+import { requireAuthProfile } from "../auth/index.js";
+import { ensureDirectory, fileExists, removeDirectory, writeUtf8File } from "../filesystem/index.js";
+import { appendDockerLabelArgs, createDockerDeploymentLabels, createDockerDeploymentUnitId, createDockerProjectLabel, dockerContextNameForTarget, dockerHostValueForTarget, normalizeDeploymentName, readDeploymentRecordFromOutput, resolveDeploymentRecordPath, verifyDockerDeploymentTarget, writeDockerDeploymentRecordForRun } from "../deployment/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
 import { compileProject } from "./compileProject.js";
-import { createDefaultImageTag } from "./buildProject.js";
+import { createDefaultImageTag, resolveDockerBuildArchitecture } from "./buildProject.js";
 import { slugify } from "./helpers.js";
-import { assertDeclaredModelAuthSatisfied, prepareRuntimeAuthMounts } from "./runProjectAuth.js";
+import { runDockerContainer } from "./runProjectDocker.js";
+import { assertDeclaredModelAuthSatisfied, assertRunEnvironmentSatisfied, prepareRuntimeAuthMounts, readRunEnvFile, renderDockerEnvFile, resolveAuthMountArgs, resolveRunEnvironment } from "./runProjectAuth.js";
+export { runDockerContainer };
 const resolveImageTagRoot = (inputPath) => {
     const resolvedPath = path.resolve(inputPath);
     return path.basename(resolvedPath).toLowerCase() === "spawnfile"
@@ -20,100 +21,6 @@ const createDefaultContainerName = (imageTag) => {
     const containerName = slugify(imageTag.replaceAll("/", "-").replaceAll(":", "-"));
     return containerName || "spawnfile-run";
 };
-const getImportMountTargetName = (kind) => kind === "claude-code" ? ".claude" : ".codex";
-const createGeneratedRuntimeSecret = (secretName) => {
-    if (secretName === "OPENCLAW_GATEWAY_TOKEN" || secretName === "OPENCLAW_HOOKS_TOKEN") {
-        return randomBytes(24).toString("hex");
-    }
-    return null;
-};
-const hasEnvValue = (env, name) => typeof env[name] === "string" && env[name].length > 0;
-const collectMissingRequiredSecrets = (containerReport, env, coveredModelSecrets) => {
-    const missing = new Set();
-    for (const secretName of containerReport.secrets_required) {
-        if (hasEnvValue(env, secretName)) {
-            continue;
-        }
-        if (!containerReport.model_secrets_required.includes(secretName)) {
-            missing.add(secretName);
-            continue;
-        }
-        const requiredInstances = (containerReport.runtime_instances ?? []).filter((instance) => instance.model_secrets_required.includes(secretName));
-        const isCoveredEverywhere = requiredInstances.length > 0 &&
-            requiredInstances.every((instance) => coveredModelSecrets.has(`${instance.id}:${secretName}`));
-        if (!isCoveredEverywhere) {
-            missing.add(secretName);
-        }
-    }
-    return [...missing].sort();
-};
-const resolveRunEnvironment = (containerReport, authProfile, envFileEnv = {}) => {
-    const env = {
-        ...(authProfile?.env ?? {}),
-        ...envFileEnv
-    };
-    for (const name of new Set([...Object.keys(env), ...containerReport.secrets_required])) {
-        const processValue = process.env[name];
-        if (typeof processValue === "string" && processValue.length > 0) {
-            env[name] = processValue;
-        }
-    }
-    for (const name of containerReport.runtime_secrets_required) {
-        if (hasEnvValue(env, name)) {
-            continue;
-        }
-        const generatedValue = createGeneratedRuntimeSecret(name);
-        if (generatedValue) {
-            env[name] = generatedValue;
-        }
-    }
-    for (const [name, value] of Object.entries(env)) {
-        if (value.includes("\n")) {
-            throw new SpawnfileError("validation_error", `Env value for ${name} contains a newline and cannot be written to a Docker env file`);
-        }
-    }
-    return env;
-};
-const assertRunEnvironmentSatisfied = (containerReport, env, coveredModelSecrets) => {
-    const missing = collectMissingRequiredSecrets(containerReport, env, coveredModelSecrets);
-    if (missing.length > 0) {
-        throw new SpawnfileError("validation_error", `Missing required runtime env: ${missing.sort().join(", ")}`);
-    }
-};
-const renderDockerEnvFile = (env) => `${Object.entries(env)
-    .sort(([left], [right]) => left.localeCompare(right))
-    .map(([name, value]) => `${name}=${value}`)
-    .join("\n")}\n`;
-const readRunEnvFile = async (envFilePath) => {
-    if (!envFilePath) {
-        return {};
-    }
-    try {
-        return parseEnvFile(await readUtf8File(envFilePath));
-    }
-    catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        throw new SpawnfileError("validation_error", `Unable to read env file ${envFilePath}: ${reason}`);
-    }
-};
-const resolveAuthMountArgs = async (containerReport, authProfile) => {
-    if (!authProfile || containerReport.runtime_homes.length === 0) {
-        return [];
-    }
-    const args = [];
-    for (const [kind, entry] of Object.entries(authProfile.imports)) {
-        if (!entry) {
-            continue;
-        }
-        if (!(await fileExists(entry.path))) {
-            throw new SpawnfileError("validation_error", `Imported auth path for ${kind} does not exist: ${entry.path}`);
-        }
-        for (const runtimeHome of containerReport.runtime_homes) {
-            args.push("-v", `${entry.path}:${path.posix.join(runtimeHome, getImportMountTargetName(kind))}`);
-        }
-    }
-    return args;
-};
 export const createDockerRunInvocation = async (compileResult, imageTag, options = {}) => {
     const containerReport = compileResult.report.container;
     if (!containerReport) {
@@ -128,8 +35,17 @@ export const createDockerRunInvocation = async (compileResult, imageTag, options
         assertRunEnvironmentSatisfied(containerReport, env, preparedRuntimeAuth.coveredModelSecrets);
         await ensureDirectory(supportDirectory);
         await writeUtf8File(envFilePath, renderDockerEnvFile(env));
+        const deploymentName = options.deploymentName
+            ? normalizeDeploymentName(options.deploymentName)
+            : options.detach
+                ? normalizeDeploymentName(undefined)
+                : null;
         const containerName = options.containerName ?? createDefaultContainerName(imageTag);
-        const args = ["run"];
+        const args = options.dockerContext
+            ? ["--context", options.dockerContext, "run"]
+            : options.dockerHost
+                ? ["--host", options.dockerHost, "run"]
+                : ["run"];
         if (options.detach) {
             args.push("-d");
         }
@@ -143,6 +59,16 @@ export const createDockerRunInvocation = async (compileResult, imageTag, options
         for (const mount of containerReport.persistent_mounts ?? []) {
             args.push("-v", `${mount.volume_name}:${mount.mount_path}`);
         }
+        if (options.detach && deploymentName) {
+            const compileFingerprint = compileResult.report.compile_fingerprint ?? "sf1:unknown";
+            appendDockerLabelArgs(args, createDockerDeploymentLabels({
+                compileFingerprint,
+                deployment: deploymentName,
+                project: createDockerProjectLabel(compileResult.report.root, compileResult.report.project_name),
+                unit: createDockerDeploymentUnitId(deploymentName),
+                version: compileResult.report.spawnfile_version
+            }));
+        }
         args.push("--env-file", envFilePath);
         args.push(...(await resolveAuthMountArgs(containerReport, options.authProfile ?? null)));
         args.push(...preparedRuntimeAuth.mountArgs);
@@ -153,6 +79,9 @@ export const createDockerRunInvocation = async (compileResult, imageTag, options
             containerName,
             cwd: compileResult.outputDirectory,
             detach: options.detach ?? false,
+            deploymentName,
+            dockerContext: options.dockerContext ?? null,
+            dockerHost: options.dockerHost ?? null,
             envFilePath,
             imageTag,
             supportDirectory
@@ -163,52 +92,106 @@ export const createDockerRunInvocation = async (compileResult, imageTag, options
         throw error;
     }
 };
-export const runDockerContainer = async (invocation) => new Promise((resolve, reject) => {
-    const child = spawn(invocation.command, invocation.args, {
-        cwd: invocation.cwd,
-        stdio: "inherit"
-    });
-    child.once("error", (error) => {
-        reject(new SpawnfileError("runtime_error", `Unable to start docker run for ${invocation.imageTag}: ${error.message}`));
-    });
-    child.once("exit", (code, signal) => {
-        if (code === 0) {
-            resolve();
-            return;
-        }
-        reject(new SpawnfileError("runtime_error", signal
-            ? `Docker run for ${invocation.imageTag} exited from signal ${signal}`
-            : `Docker run for ${invocation.imageTag} failed with exit code ${code ?? "unknown"}`));
-    });
-});
+const readExistingDeploymentRecord = async (outputDirectory, deploymentName) => {
+    const recordPath = resolveDeploymentRecordPath(outputDirectory, deploymentName);
+    if (!await fileExists(recordPath)) {
+        return null;
+    }
+    return readDeploymentRecordFromOutput(outputDirectory, deploymentName);
+};
+const firstDeploymentUnit = (record) => record.units[0] ?? null;
+export const resolveDetachedDeploymentOptions = async (outputDirectory, options) => {
+    if (!options.detach) {
+        return options;
+    }
+    const deploymentName = normalizeDeploymentName(options.deploymentName);
+    const record = await readExistingDeploymentRecord(outputDirectory, deploymentName);
+    if (!record) {
+        return {
+            ...options,
+            deploymentName
+        };
+    }
+    const unit = firstDeploymentUnit(record);
+    if (!options.dockerContext && !options.dockerHost) {
+        await verifyDockerDeploymentTarget(record.target, {
+            dockerCommand: options.dockerCommand,
+            execFile: options.targetExecFile
+        });
+    }
+    return {
+        authProfile: options.authProfile ?? record.auth_profile ?? undefined,
+        containerName: options.containerName ?? unit?.container_name ?? undefined,
+        deploymentName,
+        dockerContext: options.dockerContext ?? dockerContextNameForTarget(record.target) ?? undefined,
+        dockerHost: options.dockerHost ?? dockerHostValueForTarget(record.target) ?? undefined,
+        envFilePath: options.envFilePath ?? record.env_file,
+        imageTag: options.imageTag ?? unit?.image_tag
+    };
+};
 export const runProject = async (inputPath, options = {}) => {
+    const resolvedOptions = await resolveDetachedDeploymentOptions(path.resolve(options.outputDirectory ?? DEFAULT_OUTPUT_DIRECTORY), {
+        authProfile: options.authProfile,
+        containerName: options.containerName,
+        deploymentName: options.deploymentName,
+        detach: options.detach,
+        dockerCommand: options.dockerCommand,
+        dockerContext: options.dockerContext,
+        dockerHost: options.dockerHost,
+        envFilePath: options.envFilePath,
+        imageTag: options.imageTag,
+        targetExecFile: options.targetExecFile
+    });
+    const targetArchitecture = options.containerArchitecture ??
+        await resolveDockerBuildArchitecture({
+            dockerCommand: options.dockerCommand,
+            dockerContext: resolvedOptions.dockerContext
+        });
     const compileResult = await compileProject(inputPath, {
         clean: options.clean,
+        containerArchitecture: targetArchitecture,
         outputDirectory: options.outputDirectory
     });
-    const imageTag = options.imageTag ?? createDefaultImageTag(resolveImageTagRoot(inputPath));
-    const authProfile = options.authProfile
-        ? await requireAuthProfile(options.authProfile)
+    const imageTag = resolvedOptions.imageTag ?? createDefaultImageTag(resolveImageTagRoot(inputPath));
+    const authProfile = resolvedOptions.authProfile
+        ? await requireAuthProfile(resolvedOptions.authProfile)
         : null;
     const invocation = await createDockerRunInvocation(compileResult, imageTag, {
         authProfile,
-        containerName: options.containerName,
+        containerName: resolvedOptions.containerName,
         detach: options.detach,
+        deploymentName: resolvedOptions.deploymentName,
         dockerCommand: options.dockerCommand,
-        envFilePath: options.envFilePath
+        dockerContext: resolvedOptions.dockerContext,
+        dockerHost: resolvedOptions.dockerHost,
+        envFilePath: resolvedOptions.envFilePath
     });
+    let runMetadata;
     try {
-        await (options.runRunner ?? runDockerContainer)(invocation);
+        runMetadata = await (options.runRunner ?? runDockerContainer)(invocation);
     }
     finally {
         if (!invocation.detach) {
             await removeDirectory(invocation.supportDirectory);
         }
     }
+    const deploymentRecordPath = invocation.detach && invocation.deploymentName
+        ? await writeDockerDeploymentRecordForRun({
+            authProfileName: authProfile?.name ?? null,
+            envFilePath: resolvedOptions.envFilePath,
+            imageTag,
+            invocation,
+            outputDirectory: compileResult.outputDirectory,
+            report: compileResult.report,
+            runMetadata: runMetadata ?? undefined,
+            targetExecFile: options.targetExecFile
+        })
+        : null;
     return {
         ...compileResult,
         authProfileName: authProfile?.name ?? null,
         containerName: invocation.containerName,
+        deploymentRecordPath,
         imageTag
     };
 };

package/dist/compiler/runProjectAuth.d.ts

@@ -6,4 +6,9 @@ interface PreparedRunAuth {
 }
 export declare const prepareRuntimeAuthMounts: (outputDirectory: string, containerReport: ContainerReport, authProfile: ResolvedAuthProfile | null, env: Record<string, string>, tempRoot: string) => Promise<PreparedRunAuth>;
 export declare const assertDeclaredModelAuthSatisfied: (containerReport: ContainerReport, authProfile: ResolvedAuthProfile | null) => void;
+export declare const resolveRunEnvironment: (containerReport: ContainerReport, authProfile: ResolvedAuthProfile | null, envFileEnv?: Record<string, string>) => Record<string, string>;
+export declare const assertRunEnvironmentSatisfied: (containerReport: ContainerReport, env: Record<string, string>, coveredModelSecrets: Set<string>) => void;
+export declare const renderDockerEnvFile: (env: Record<string, string>) => string;
+export declare const readRunEnvFile: (envFilePath: string | undefined) => Promise<Record<string, string>>;
+export declare const resolveAuthMountArgs: (containerReport: ContainerReport, authProfile: ResolvedAuthProfile | null) => Promise<string[]>;
 export {};

package/dist/compiler/runProjectAuth.js

@@ -1,3 +1,7 @@
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { parseEnvFile } from "../auth/index.js";
+import { fileExists, readUtf8File } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
 import { getRuntimeAdapter } from "../runtime/index.js";
 const MODEL_AUTH_IMPORT_KINDS = {
@@ -57,3 +61,97 @@ export const assertDeclaredModelAuthSatisfied = (containerReport, authProfile) =
         throw new SpawnfileError("validation_error", `Auth profile ${authProfile.name} is missing required auth imports: ${missingImportKinds.join(", ")}`);
     }
 };
+const getImportMountTargetName = (kind) => kind === "claude-code" ? ".claude" : ".codex";
+const createGeneratedRuntimeSecret = (secretName) => {
+    if (secretName === "OPENCLAW_GATEWAY_TOKEN" || secretName === "OPENCLAW_HOOKS_TOKEN") {
+        return randomBytes(24).toString("hex");
+    }
+    return null;
+};
+const hasEnvValue = (env, name) => typeof env[name] === "string" && env[name].length > 0;
+const collectMissingRequiredSecrets = (containerReport, env, coveredModelSecrets) => {
+    const missing = new Set();
+    for (const secretName of containerReport.secrets_required) {
+        if (hasEnvValue(env, secretName)) {
+            continue;
+        }
+        if (!containerReport.model_secrets_required.includes(secretName)) {
+            missing.add(secretName);
+            continue;
+        }
+        const requiredInstances = (containerReport.runtime_instances ?? []).filter((instance) => instance.model_secrets_required.includes(secretName));
+        const isCoveredEverywhere = requiredInstances.length > 0 &&
+            requiredInstances.every((instance) => coveredModelSecrets.has(`${instance.id}:${secretName}`));
+        if (!isCoveredEverywhere) {
+            missing.add(secretName);
+        }
+    }
+    return [...missing].sort();
+};
+export const resolveRunEnvironment = (containerReport, authProfile, envFileEnv = {}) => {
+    const env = {
+        ...(authProfile?.env ?? {}),
+        ...envFileEnv
+    };
+    for (const name of new Set([...Object.keys(env), ...containerReport.secrets_required])) {
+        const processValue = process.env[name];
+        if (typeof processValue === "string" && processValue.length > 0) {
+            env[name] = processValue;
+        }
+    }
+    for (const name of containerReport.runtime_secrets_required) {
+        if (hasEnvValue(env, name)) {
+            continue;
+        }
+        const generatedValue = createGeneratedRuntimeSecret(name);
+        if (generatedValue) {
+            env[name] = generatedValue;
+        }
+    }
+    for (const [name, value] of Object.entries(env)) {
+        if (value.includes("\n")) {
+            throw new SpawnfileError("validation_error", `Env value for ${name} contains a newline and cannot be written to a Docker env file`);
+        }
+    }
+    return env;
+};
+export const assertRunEnvironmentSatisfied = (containerReport, env, coveredModelSecrets) => {
+    const missing = collectMissingRequiredSecrets(containerReport, env, coveredModelSecrets);
+    if (missing.length > 0) {
+        throw new SpawnfileError("validation_error", `Missing required runtime env: ${missing.sort().join(", ")}`);
+    }
+};
+export const renderDockerEnvFile = (env) => `${Object.entries(env)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => `${name}=${value}`)
+    .join("\n")}\n`;
+export const readRunEnvFile = async (envFilePath) => {
+    if (!envFilePath) {
+        return {};
+    }
+    try {
+        return parseEnvFile(await readUtf8File(envFilePath));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("validation_error", `Unable to read env file ${envFilePath}: ${reason}`);
+    }
+};
+export const resolveAuthMountArgs = async (containerReport, authProfile) => {
+    if (!authProfile || containerReport.runtime_homes.length === 0) {
+        return [];
+    }
+    const args = [];
+    for (const [kind, entry] of Object.entries(authProfile.imports)) {
+        if (!entry) {
+            continue;
+        }
+        if (!(await fileExists(entry.path))) {
+            throw new SpawnfileError("validation_error", `Imported auth path for ${kind} does not exist: ${entry.path}`);
+        }
+        for (const runtimeHome of containerReport.runtime_homes) {
+            args.push("-v", `${entry.path}:${path.posix.join(runtimeHome, getImportMountTargetName(kind))}`);
+        }
+    }
+    return args;
+};

package/dist/compiler/runProjectDocker.d.ts

@@ -0,0 +1,19 @@
+export interface DockerRunInvocation {
+    args: string[];
+    command: string;
+    containerName: string | null;
+    cwd: string;
+    detach: boolean;
+    deploymentName?: string | null;
+    dockerContext?: string | null;
+    dockerHost?: string | null;
+    envFilePath: string;
+    imageTag: string;
+    supportDirectory: string;
+}
+export interface DockerRunResult {
+    containerId?: string;
+    imageId?: string;
+}
+export type DockerRunRunner = (invocation: DockerRunInvocation) => Promise<DockerRunResult | void>;
+export declare const runDockerContainer: DockerRunRunner;