spawnfile 0.1.11 → 0.1.13

package/dist/dev/docker.js

@@ -0,0 +1,71 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { compileProject, normalizeDockerArchitecture } from "../compiler/index.js";
+import { dockerContextNameForTarget, dockerHostValueForTarget } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+export const defaultExecFile = promisify(execFileCallback);
+export const dockerArgsForRecord = (record) => {
+    const context = dockerContextNameForTarget(record.target);
+    if (context) {
+        return ["--context", context];
+    }
+    const host = dockerHostValueForTarget(record.target);
+    return host ? ["--host", host] : [];
+};
+export const firstContainerName = (record) => {
+    const unit = record.units.find((candidate) => candidate.kind === "container") ?? record.units[0];
+    const name = unit?.container_name;
+    if (!name) {
+        throw new SpawnfileError("runtime_error", `Deployment "${record.name}" has no recorded container name`);
+    }
+    return name;
+};
+export const compileForDevApply = async (inputPath, outputDirectory, record, dockerCommand, execFileImpl) => {
+    const dockerContext = dockerContextNameForTarget(record.target) ?? undefined;
+    const architecture = dockerContext
+        ? normalizeDockerArchitecture((await execFileImpl(dockerCommand, ["--context", dockerContext, "info", "--format", "{{.Architecture}}"], { timeout: 10_000 })).stdout)
+        : undefined;
+    return compileProject(inputPath, {
+        clean: false,
+        containerArchitecture: architecture,
+        outputDirectory
+    });
+};
+export const runDocker = async (command, args, execFileImpl, timeout = 30_000) => {
+    const { stdout } = await execFileImpl(command, args, { timeout });
+    return stdout;
+};
+export const copyIntoContainer = async (dockerCommand, dockerPrefix, source, destination, execFileImpl) => {
+    await runDocker(dockerCommand, [...dockerPrefix, "cp", source, destination], execFileImpl, 60_000);
+};
+export const ensureContainerDirectories = async (dockerCommand, dockerPrefix, containerName, paths, execFileImpl) => {
+    if (paths.length === 0) {
+        return;
+    }
+    await runDocker(dockerCommand, [
+        ...dockerPrefix,
+        "exec",
+        "--user",
+        "root",
+        containerName,
+        "mkdir",
+        "-p",
+        ...paths
+    ], execFileImpl);
+};
+export const chownContainerPaths = async (dockerCommand, dockerPrefix, containerName, paths, execFileImpl) => {
+    if (paths.length === 0) {
+        return;
+    }
+    await runDocker(dockerCommand, [
+        ...dockerPrefix,
+        "exec",
+        "--user",
+        "root",
+        containerName,
+        "chown",
+        "-R",
+        "spawnfile:spawnfile",
+        ...paths
+    ], execFileImpl);
+};

package/dist/dev/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./activity.js";
+export * from "./project.js";

package/dist/dev/index.js

@@ -0,0 +1,2 @@
+export * from "./activity.js";
+export * from "./project.js";

package/dist/dev/project.d.ts

@@ -0,0 +1,35 @@
+import { type UpProjectOptions, type UpProjectResult } from "../compiler/index.js";
+import { type DeploymentRecord } from "../deployment/index.js";
+import { type DevExecFile } from "./docker.js";
+export declare const PI_CONTROL_URL = "http://127.0.0.1:19690";
+export interface DevProjectOptions {
+    deploymentName?: string;
+    dockerCommand?: string;
+    outputDirectory?: string;
+}
+export interface DevApplyProjectOptions extends DevProjectOptions {
+    agent: string;
+    execFile?: DevExecFile;
+    restart?: boolean;
+}
+export interface DevApplyProjectResult {
+    agentId: string;
+    bridgeStarted: boolean;
+    containerName: string;
+    deploymentName: string;
+    existingAgent: boolean;
+    outputDirectory: string;
+}
+export interface DevStopProjectResult {
+    containerName: string;
+    deploymentName: string;
+    outputDirectory: string;
+}
+export declare const resolveDevOutputDirectory: (inputPath: string, outputDirectory?: string) => Promise<string>;
+export declare const devUpProject: (inputPath: string, options?: UpProjectOptions) => Promise<UpProjectResult>;
+export declare const selectDeploymentRecord: (outputDirectory: string, deploymentName?: string) => Promise<DeploymentRecord>;
+export declare const devApplyProject: (inputPath: string, options: DevApplyProjectOptions) => Promise<DevApplyProjectResult>;
+export declare const devRestartProject: (inputPath: string, options: DevApplyProjectOptions) => Promise<DevApplyProjectResult>;
+export declare const devStopProject: (inputPath: string, options?: DevProjectOptions & {
+    execFile?: DevExecFile;
+}) => Promise<DevStopProjectResult>;

package/dist/dev/project.js

@@ -0,0 +1,164 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { buildCompilePlan, upProject } from "../compiler/index.js";
+import { listDeploymentRecords, normalizeDeploymentName } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { chownContainerPaths, compileForDevApply, copyIntoContainer, defaultExecFile, dockerArgsForRecord, ensureContainerDirectories, firstContainerName, runDocker } from "./docker.js";
+const DEV_OUTPUT_DIRECTORY = ".spawn-dev";
+const PI_APP_CONFIG_PATH = "/var/lib/spawnfile/instances/pi/pi-app/pi/pi-app.json";
+export const PI_CONTROL_URL = "http://127.0.0.1:19690";
+export const resolveDevOutputDirectory = async (inputPath, outputDirectory) => {
+    if (outputDirectory) {
+        return path.resolve(outputDirectory);
+    }
+    const plan = await buildCompilePlan(inputPath);
+    return path.join(path.dirname(plan.root), DEV_OUTPUT_DIRECTORY);
+};
+export const devUpProject = async (inputPath, options = {}) => upProject(inputPath, {
+    ...options,
+    detach: true,
+    outputDirectory: await resolveDevOutputDirectory(inputPath, options.outputDirectory)
+});
+export const selectDeploymentRecord = async (outputDirectory, deploymentName) => {
+    const records = await listDeploymentRecords(outputDirectory);
+    if (records.length === 0) {
+        throw new SpawnfileError("validation_error", `No dev deployment records found in ${outputDirectory}; run spawnfile dev up first`);
+    }
+    if (deploymentName) {
+        const normalized = normalizeDeploymentName(deploymentName);
+        const selected = records.find((entry) => entry.record.name === normalized);
+        if (!selected) {
+            throw new SpawnfileError("validation_error", `Unknown dev deployment "${normalized}". Valid deployments: ${records.map((entry) => entry.record.name).join(", ")}`);
+        }
+        return selected.record;
+    }
+    if (records.length > 1) {
+        throw new SpawnfileError("validation_error", `--deployment is required: ${records.map((entry) => entry.record.name).join(", ")}`);
+    }
+    return records[0].record;
+};
+const readJson = async (filePath) => JSON.parse(await readFile(filePath, "utf8"));
+const rootfsPath = (outputDirectory, containerPath) => path.join(outputDirectory, "container", "rootfs", containerPath.replace(/^\/+/u, ""));
+const matchesAgent = (agent, input) => agent.slug === input || agent.id === input || agent.name === input || agent.id === `agent:${input}`;
+const selectPiAgent = async (outputDirectory, agentInput) => {
+    const configPath = rootfsPath(outputDirectory, PI_APP_CONFIG_PATH);
+    const config = await readJson(configPath);
+    const agent = (config.agents ?? []).find((candidate) => matchesAgent(candidate, agentInput));
+    if (!agent) {
+        throw new SpawnfileError("validation_error", `Pi agent "${agentInput}" was not found in compiled output`);
+    }
+    return {
+        agent,
+        configPath,
+        workspacePath: rootfsPath(outputDirectory, `/var/lib/spawnfile/instances/pi/pi-app/workspace/agents/${agent.slug}`)
+    };
+};
+const selectMoltnetNodes = async (result, agent) => {
+    const nodePlans = result.report.container?.moltnet?.node_plans ?? [];
+    const matches = [];
+    for (const plan of nodePlans) {
+        const configPath = rootfsPath(result.outputDirectory, plan.config_path);
+        const config = await readJson(configPath);
+        const attachment = (config.attachments ?? []).find((candidate) => {
+            const id = candidate.agent?.id ?? "";
+            const name = candidate.agent?.name ?? "";
+            return id === agent.slug || id === agent.id || name === agent.name;
+        });
+        if (attachment?.agent?.id) {
+            matches.push({
+                configPath,
+                remotePath: plan.config_path,
+                ...(attachment.moltnet?.token_path
+                    ? { tokenDirectory: path.posix.dirname(attachment.moltnet.token_path) }
+                    : {})
+            });
+        }
+    }
+    return matches;
+};
+const selectManagedMoltnetServers = (result) => (result.report.container?.moltnet?.server_plans ?? [])
+    .filter((plan) => plan.mode === "managed" && Boolean(plan.config_path))
+    .map((plan) => ({
+    configPath: rootfsPath(result.outputDirectory, plan.config_path),
+    remotePath: plan.config_path
+}));
+const shellQuote = (value) => `'${value.replaceAll("'", "'\"'\"'")}'`;
+const listRunningPiAgents = async (dockerCommand, dockerPrefix, containerName, execFileImpl) => {
+    const stdout = await runDocker(dockerCommand, [...dockerPrefix, "exec", containerName, "curl", "-fsS", `${PI_CONTROL_URL}/spawnfile/agents`], execFileImpl);
+    const parsed = JSON.parse(stdout);
+    return parsed.agents ?? [];
+};
+const loadPiAgent = async (dockerCommand, dockerPrefix, containerName, slug, action, execFileImpl) => {
+    await runDocker(dockerCommand, [
+        ...dockerPrefix,
+        "exec",
+        containerName,
+        "curl",
+        "-fsS",
+        "-X",
+        "POST",
+        "-H",
+        "content-type: application/json",
+        "--data",
+        JSON.stringify({ slug }),
+        `${PI_CONTROL_URL}/spawnfile/agents/${action}`
+    ], execFileImpl, 120_000);
+};
+export const devApplyProject = async (inputPath, options) => {
+    const outputDirectory = await resolveDevOutputDirectory(inputPath, options.outputDirectory);
+    const record = await selectDeploymentRecord(outputDirectory, options.deploymentName);
+    const dockerCommand = options.dockerCommand ?? "docker";
+    const dockerPrefix = dockerArgsForRecord(record);
+    const containerName = firstContainerName(record);
+    const execFileImpl = options.execFile ?? defaultExecFile;
+    const existingAgents = await listRunningPiAgents(dockerCommand, dockerPrefix, containerName, execFileImpl);
+    const compileResult = await compileForDevApply(inputPath, outputDirectory, record, dockerCommand, execFileImpl);
+    const { agent, configPath, workspacePath } = await selectPiAgent(outputDirectory, options.agent);
+    const nodes = await selectMoltnetNodes(compileResult, agent);
+    const serverConfigs = selectManagedMoltnetServers(compileResult);
+    const existingAgent = existingAgents.some((candidate) => matchesAgent(candidate, agent.slug));
+    await copyIntoContainer(dockerCommand, dockerPrefix, configPath, `${containerName}:${PI_APP_CONFIG_PATH}`, execFileImpl);
+    await copyIntoContainer(dockerCommand, dockerPrefix, workspacePath, `${containerName}:/var/lib/spawnfile/instances/pi/pi-app/workspace/agents`, execFileImpl);
+    for (const node of nodes) {
+        await copyIntoContainer(dockerCommand, dockerPrefix, node.configPath, `${containerName}:${node.remotePath}`, execFileImpl);
+    }
+    for (const serverConfig of serverConfigs) {
+        await copyIntoContainer(dockerCommand, dockerPrefix, serverConfig.configPath, `${containerName}:${serverConfig.remotePath}`, execFileImpl);
+    }
+    const tokenDirectories = nodes
+        .map((node) => node.tokenDirectory)
+        .filter((directory) => Boolean(directory));
+    await ensureContainerDirectories(dockerCommand, dockerPrefix, containerName, tokenDirectories, execFileImpl);
+    await chownContainerPaths(dockerCommand, dockerPrefix, containerName, [
+        "/var/lib/spawnfile/instances/pi/pi-app",
+        ...nodes.flatMap((node) => [
+            node.remotePath,
+            ...(node.tokenDirectory ? [node.tokenDirectory] : [])
+        ]),
+        ...serverConfigs.map((serverConfig) => serverConfig.remotePath)
+    ], execFileImpl);
+    await loadPiAgent(dockerCommand, dockerPrefix, containerName, agent.slug, options.restart === true ? "restart" : "load", execFileImpl);
+    if (!existingAgent) {
+        for (const node of nodes) {
+            const prepare = node.tokenDirectory ? `mkdir -p ${shellQuote(node.tokenDirectory)} && ` : "";
+            const command = `${prepare}/usr/local/bin/moltnet node ${shellQuote(node.remotePath)}`;
+            await runDocker(dockerCommand, [...dockerPrefix, "exec", "-d", "--user", "spawnfile", containerName, "sh", "-lc", command], execFileImpl);
+        }
+    }
+    return {
+        agentId: agent.id,
+        bridgeStarted: !existingAgent && nodes.length > 0,
+        containerName,
+        deploymentName: record.name,
+        existingAgent,
+        outputDirectory
+    };
+};
+export const devRestartProject = async (inputPath, options) => devApplyProject(inputPath, { ...options, restart: true });
+export const devStopProject = async (inputPath, options = {}) => {
+    const outputDirectory = await resolveDevOutputDirectory(inputPath, options.outputDirectory);
+    const record = await selectDeploymentRecord(outputDirectory, options.deploymentName);
+    const containerName = firstContainerName(record);
+    await runDocker(options.dockerCommand ?? "docker", [...dockerArgsForRecord(record), "rm", "-f", containerName], options.execFile ?? defaultExecFile);
+    return { containerName, deploymentName: record.name, outputDirectory };
+};

package/dist/distribution/buildDistributionReport.d.ts

@@ -0,0 +1,22 @@
+import type { DistributionImageLabels, DistributionMoltnetNetwork, DistributionOrganizationSummary, DistributionPersistentMount, DistributionPortMapping, DistributionReport, DistributionRuntimeInstance, DistributionSecretCategory, DistributionWorkspaceResource } from "./types.js";
+export interface DistributionEnvVariableInput {
+    categories: DistributionSecretCategory[];
+    generated: boolean;
+    name: string;
+    required: boolean;
+}
+export interface BuildDistributionReportInput {
+    envVariables: DistributionEnvVariableInput[];
+    generatedAt: string;
+    internalPorts: number[];
+    modelAuthMethods: Record<string, DistributionRuntimeInstance["model_auth_methods"][string]>;
+    moltnetNetworks: DistributionMoltnetNetwork[];
+    organization: DistributionOrganizationSummary;
+    persistentMounts: DistributionPersistentMount[];
+    portMappings: DistributionPortMapping[];
+    publishedPorts: number[];
+    resources: DistributionWorkspaceResource[];
+    runtimeInstances: DistributionRuntimeInstance[];
+}
+export declare const buildDistributionReport: (input: BuildDistributionReportInput) => DistributionReport;
+export declare const createDistributionImageLabels: (projectSlug: string, compileFingerprint: string) => DistributionImageLabels;

package/dist/distribution/buildDistributionReport.js

@@ -0,0 +1,51 @@
+import { createDistributionFingerprint } from "./fingerprint.js";
+import { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION } from "./types.js";
+const createSecretCategoryMap = (envVariables) => {
+    const secrets = {
+        model: [],
+        project: [],
+        runtime: [],
+        surface: []
+    };
+    for (const variable of envVariables) {
+        for (const category of variable.categories) {
+            secrets[category].push({
+                generated: variable.generated,
+                name: variable.name,
+                required: variable.required
+            });
+        }
+    }
+    for (const category of Object.keys(secrets)) {
+        secrets[category].sort((left, right) => left.name.localeCompare(right.name));
+    }
+    return secrets;
+};
+export const buildDistributionReport = (input) => {
+    const body = {
+        internal_ports: [...input.internalPorts].sort((left, right) => left - right),
+        model_auth_methods: input.modelAuthMethods,
+        moltnet: {
+            networks: [...input.moltnetNetworks].sort((left, right) => left.id.localeCompare(right.id))
+        },
+        organization: input.organization,
+        persistent_mounts: [...input.persistentMounts].sort((left, right) => left.id.localeCompare(right.id)),
+        port_mappings: input.portMappings,
+        ports: [...input.publishedPorts].sort((left, right) => left - right),
+        resources: input.resources,
+        runtime_instances: [...input.runtimeInstances].sort((left, right) => left.id.localeCompare(right.id)),
+        secrets: createSecretCategoryMap(input.envVariables),
+        version: DISTRIBUTION_REPORT_VERSION
+    };
+    return {
+        compile_fingerprint: createDistributionFingerprint(body),
+        generated_at: input.generatedAt,
+        ...body
+    };
+};
+export const createDistributionImageLabels = (projectSlug, compileFingerprint) => ({
+    "com.spawnfile.compile_fingerprint": compileFingerprint,
+    "com.spawnfile.image_contract": IMAGE_CONTRACT_VERSION,
+    "com.spawnfile.project": projectSlug,
+    "com.spawnfile.report": DISTRIBUTION_REPORT_IMAGE_PATH
+});

package/dist/distribution/consumeImage.d.ts

@@ -0,0 +1,29 @@
+import { type DeploymentRecord } from "../deployment/index.js";
+import type { DockerCommandRunner } from "./dockerRunner.js";
+import type { ResolvedAuthProfile } from "../auth/index.js";
+export interface ConsumeImageUpOptions {
+    authProfile?: ResolvedAuthProfile | null;
+    authValues?: Record<string, string>;
+    authProfileName?: string | null;
+    deploymentName?: string;
+    dockerCommand?: string;
+    dockerContext?: string;
+    dockerHost?: string;
+    envFileEnv?: Record<string, string>;
+    envFilePath?: string | null;
+    pull?: boolean;
+    runDocker?: DockerCommandRunner;
+}
+export interface ConsumeImageUpResult {
+    containerName: string;
+    deploymentName: string;
+    imageRef: string;
+    /** The ref/digest this redeploy replaced, or null for a first deploy. */
+    previous: {
+        digest: string | null;
+        ref: string;
+    } | null;
+    record: DeploymentRecord;
+    recordPath: string;
+}
+export declare const consumeImageUp: (imageRef: string, options?: ConsumeImageUpOptions) => Promise<ConsumeImageUpResult>;

package/dist/distribution/consumeImage.js

@@ -0,0 +1,254 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { acquireHomeDeploymentLock, createDockerDeploymentLabels, homeDeploymentExists, normalizeDeploymentName, readHomeDeploymentRecord, resolveDockerDeploymentTarget, verifyDockerDeploymentTarget, writeHomeDeployment } from "../deployment/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+import { createConsumerDockerRunner } from "./dockerRunner.js";
+import { extractImageReport, resolveDockerBaseArgs } from "./extractImage.js";
+import { parseImageReference } from "./imageRef.js";
+import { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
+import { runImagePreflight } from "./preflight.js";
+import { normalizeProjectLabelSlug } from "./projectName.js";
+const containerNameFor = (deploymentName) => `spawnfile-${deploymentName}`;
+const unitIdFor = (deploymentName) => `${deploymentName}-container`;
+const resolveRegistryDigest = async (imageRef, runDocker) => {
+    const fromRef = imageRef.includes("@") ? imageRef.slice(imageRef.indexOf("@") + 1) : null;
+    if (fromRef) {
+        return fromRef;
+    }
+    try {
+        const raw = (await runDocker([
+            "image",
+            "inspect",
+            "--format",
+            "{{json .RepoDigests}}",
+            imageRef
+        ])).toString("utf8").trim();
+        const digests = JSON.parse(raw);
+        const match = digests
+            .map((entry) => (entry.includes("@") ? entry.slice(entry.indexOf("@") + 1) : null))
+            .find((entry) => Boolean(entry));
+        return match ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+const containerExists = async (runDocker, containerName) => {
+    try {
+        await runDocker(["container", "inspect", containerName]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const resolveLocalImageId = async (imageRef, runDocker) => {
+    try {
+        const raw = (await runDocker([
+            "image",
+            "inspect",
+            "--format",
+            "{{.Id}}",
+            imageRef
+        ])).toString("utf8").trim();
+        return raw.length > 0 ? raw : null;
+    }
+    catch {
+        return null;
+    }
+};
+const networkIdsFrom = (report) => report.moltnet.networks.map((network) => network.id).sort();
+const buildContainsEntries = (report) => [
+    ...report.organization.agents.map((agent) => ({ id: agent.id, kind: "agent" })),
+    ...report.organization.teams.map((team) => ({ id: team.id, kind: "team" })),
+    ...networkIdsFrom(report).map((id) => ({ id, kind: "network" }))
+];
+export const consumeImageUp = async (imageRef, options = {}) => {
+    const parsedRef = parseImageReference(imageRef);
+    if (!parsedRef) {
+        throw new SpawnfileError("validation_error", `Invalid image reference: ${imageRef}`);
+    }
+    const deploymentName = normalizeDeploymentName(options.deploymentName ?? deriveDeploymentName(parsedRef));
+    const isExplicitName = Boolean(options.deploymentName);
+    // Hold an exclusive lock for the whole operation so a concurrent `up` for the
+    // same deployment cannot race on the record or orphan a container.
+    const releaseLock = await acquireHomeDeploymentLock(deploymentName);
+    try {
+        return await consumeImageUpLocked(imageRef, parsedRef, deploymentName, isExplicitName, options);
+    }
+    finally {
+        await releaseLock();
+    }
+};
+const consumeImageUpLocked = async (imageRef, parsedRef, deploymentName, isExplicitName, options) => {
+    void parsedRef;
+    const alreadyExists = await homeDeploymentExists(deploymentName);
+    if (alreadyExists && !isExplicitName) {
+        throw new SpawnfileError("validation_error", `Deployment "${deploymentName}" already exists (derived from image ${imageRef}). ` +
+            `To redeploy it, re-run with --deployment ${deploymentName}; ` +
+            "to create a separate one, pass a different --deployment <name>.");
+    }
+    const dockerCommand = options.dockerCommand ?? "docker";
+    const baseArgs = resolveDockerBaseArgs({
+        dockerContext: options.dockerContext,
+        dockerHost: options.dockerHost
+    });
+    const inspection = await extractImageReport(imageRef, {
+        dockerCommand,
+        dockerContext: options.dockerContext,
+        dockerHost: options.dockerHost,
+        pull: options.pull,
+        runDocker: options.runDocker
+    });
+    const report = inspection.report;
+    // Resolve the full environment first (auth profile, env file, process-env
+    // overrides, and generated runtime tokens), then preflight against it so
+    // required secrets supplied via any of those sources satisfy the check.
+    const env = resolveImageEnvironment({
+        authValues: options.authValues ?? {},
+        envFileEnv: options.envFileEnv,
+        report
+    });
+    const availableImports = options.authProfile
+        ? ["claude-code", "codex"].filter((kind) => options.authProfile.imports[kind])
+        : [];
+    runImagePreflight({ authValues: env, availableImports, report });
+    const target = await resolveExistingOrNewTarget(deploymentName, alreadyExists, options);
+    // Capture what this redeploy replaces so the caller can show previous → new
+    // ref/digest, per specs/DISTRIBUTION.md. Null on a first deploy.
+    const previous = alreadyExists ? await readPreviousSource(deploymentName) : null;
+    const runDocker = options.runDocker ?? createConsumerDockerRunner(dockerCommand, baseArgs);
+    const containerName = containerNameFor(deploymentName);
+    const projectSlug = normalizeProjectLabelSlug(report.organization.project);
+    const workDir = await mkdtemp(path.join(os.tmpdir(), "spawnfile-consume-"));
+    const envFilePath = path.join(workDir, "container.env");
+    // A redeploy reuses the live container's published host ports, and Docker
+    // cannot bind a host port twice. So when a live container exists we move it
+    // aside (rename + stop) to free its name and ports, start the new container,
+    // and on failure restore the old one — non-destructive without needing a free
+    // port for two containers at once. There is a brief restart gap, unavoidable
+    // when reusing host ports without a proxy.
+    const backupName = `${containerName}-previous-${Date.now().toString(36)}`;
+    try {
+        await writeFile(envFilePath, renderEnvFileContent(env), "utf8");
+        // Prepare import-based model auth (the consumer's Claude/Codex login) and
+        // validate its credentials BEFORE the destructive swap below. The OAuth-mode
+        // config is already baked into the image; this only resolves the credential
+        // mounts. Doing it first guarantees an unusable import fails while the live
+        // container is still untouched, never mid-swap.
+        const authMountArgs = options.authProfile && availableImports.length > 0
+            ? (await prepareImageRuntimeAuthMounts({
+                authProfile: options.authProfile,
+                report,
+                tempRoot: workDir
+            })).mountArgs
+            : [];
+        const liveExists = await containerExists(runDocker, containerName);
+        if (liveExists) {
+            await runDocker(["rename", containerName, backupName]);
+            await runDocker(["stop", backupName]).catch(() => undefined);
+        }
+        const runArgs = ["run", "-d", "--name", containerName, "--env-file", envFilePath];
+        for (const port of report.ports) {
+            runArgs.push("-p", `${port}:${port}`);
+        }
+        for (const mount of report.persistent_mounts) {
+            runArgs.push("-v", `${deriveVolumeName(deploymentName, mount.id)}:${mount.target}`);
+        }
+        runArgs.push(...authMountArgs);
+        const labels = createDockerDeploymentLabels({
+            compileFingerprint: inspection.compileFingerprint,
+            deployment: deploymentName,
+            project: projectSlug,
+            unit: unitIdFor(deploymentName),
+            version: "0.1"
+        });
+        for (const [name, value] of Object.entries(labels)) {
+            runArgs.push("--label", `${name}=${value}`);
+        }
+        runArgs.push(imageRef);
+        let runOutput;
+        try {
+            runOutput = (await runDocker(runArgs)).toString("utf8").trim();
+        }
+        catch (error) {
+            // The new container failed to start; remove the failed attempt and restore
+            // the previous deployment so a failed redeploy never loses the live one.
+            await runDocker(["rm", "-f", containerName]).catch(() => undefined);
+            if (liveExists) {
+                await runDocker(["rename", backupName, containerName]).catch(() => undefined);
+                await runDocker(["start", containerName]).catch(() => undefined);
+            }
+            throw error;
+        }
+        // The new container is up — discard the previous one.
+        if (liveExists) {
+            await runDocker(["rm", "-f", backupName]).catch(() => undefined);
+        }
+        const containerId = runOutput.split("\n").pop()?.trim() || null;
+        const imageId = await resolveLocalImageId(imageRef, runDocker);
+        const digest = await resolveRegistryDigest(imageRef, runDocker);
+        const record = {
+            auth_profile: options.authProfileName ?? null,
+            compile_fingerprint: inspection.compileFingerprint,
+            created_at: new Date().toISOString(),
+            ...(options.envFilePath ? { env_file: path.resolve(options.envFilePath) } : {}),
+            manager: "docker",
+            name: deploymentName,
+            output_directory: null,
+            source: { digest, kind: "image", ref: imageRef },
+            target,
+            units: [
+                {
+                    container_id: containerId,
+                    container_name: containerName,
+                    contains: buildContainsEntries(report),
+                    id: unitIdFor(deploymentName),
+                    image_id: imageId,
+                    image_tag: imageRef,
+                    kind: "container",
+                    runtime_instances: report.runtime_instances.map((instance) => instance.id).sort()
+                }
+            ],
+            version: "spawnfile.deployment.v2"
+        };
+        const written = await writeHomeDeployment(record, report);
+        return {
+            containerName,
+            deploymentName,
+            imageRef,
+            previous,
+            record,
+            recordPath: written.recordPath
+        };
+    }
+    finally {
+        await rm(workDir, { force: true, recursive: true }).catch(() => undefined);
+    }
+};
+const readPreviousSource = async (deploymentName) => {
+    try {
+        const existing = await readHomeDeploymentRecord(deploymentName);
+        if (existing.source.kind !== "image") {
+            return null;
+        }
+        return { digest: existing.source.digest, ref: existing.source.ref };
+    }
+    catch {
+        return null;
+    }
+};
+const resolveExistingOrNewTarget = async (deploymentName, alreadyExists, options) => {
+    if (alreadyExists && !options.dockerContext && !options.dockerHost) {
+        const existing = await readHomeDeploymentRecord(deploymentName);
+        await verifyDockerDeploymentTarget(existing.target, { dockerCommand: options.dockerCommand });
+        return existing.target;
+    }
+    return resolveDockerDeploymentTarget({
+        context: options.dockerContext ?? null,
+        dockerCommand: options.dockerCommand,
+        dockerHost: options.dockerHost ?? null
+    });
+};

package/dist/distribution/consumeImageSupport.d.ts

@@ -0,0 +1,18 @@
+import type { ParsedImageReference } from "./imageRef.js";
+import type { DistributionReport } from "./types.js";
+/** Derives a kebab-case deployment name from the image repository component. */
+export declare const deriveDeploymentName: (ref: ParsedImageReference) => string;
+/** Per-deployment volume name so two deployments never share a store. */
+export declare const deriveVolumeName: (deploymentName: string, mountId: string) => string;
+export interface ResolveImageEnvironmentInput {
+    authValues: Record<string, string>;
+    envFileEnv?: Record<string, string>;
+    report: DistributionReport;
+}
+/**
+ * Builds the container environment for a sourceless deployment: auth-profile
+ * and env-file values, process-env overrides for declared secrets, and
+ * generated runtime tokens that the user must never supply.
+ */
+export declare const resolveImageEnvironment: (input: ResolveImageEnvironmentInput) => Record<string, string>;
+export declare const renderEnvFileContent: (env: Record<string, string>) => string;