spawnfile 0.1.11 → 0.1.12

package/dist/deployment/record.js

@@ -0,0 +1,174 @@
+import path from "node:path";
+import { readdir, rename, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { normalizeDeploymentName, resolveDeploymentRecordPath, resolveDeploymentRecordsDirectory } from "./names.js";
+const contextTargetSchema = z.object({
+    endpoint_fingerprint: z.string().regex(/^sha256:[a-f0-9]{32}$/),
+    kind: z.literal("context"),
+    name: z.string().min(1)
+}).strict();
+const legacyContextTargetSchema = z.object({
+    context: z.string().min(1),
+    endpoint_fingerprint: z.string().regex(/^sha256:[a-f0-9]{32}$/),
+    kind: z.literal("docker-context")
+}).strict();
+const hostTargetSchema = z.object({
+    kind: z.literal("host"),
+    value: z.string().min(1)
+}).strict();
+const targetSchema = z.union([
+    contextTargetSchema,
+    legacyContextTargetSchema,
+    hostTargetSchema
+]);
+const unitV1Schema = z.object({
+    container_id: z.string().min(1).nullable(),
+    container_name: z.string().min(1).nullable(),
+    contains: z.array(z.object({
+        id: z.string().min(1),
+        kind: z.union([z.literal("agent"), z.literal("team")])
+    }).strict()),
+    id: z.string().min(1),
+    image_id: z.string().min(1).nullable(),
+    image_tag: z.string().min(1),
+    kind: z.literal("container"),
+    runtime_instances: z.array(z.string().min(1))
+}).strict();
+const unitSchema = z.object({
+    container_id: z.string().min(1).nullable(),
+    container_name: z.string().min(1).nullable(),
+    contains: z.array(z.object({
+        id: z.string().min(1),
+        kind: z.union([z.literal("agent"), z.literal("network"), z.literal("team")])
+    }).strict()),
+    id: z.string().min(1),
+    image_id: z.string().min(1).nullable(),
+    image_tag: z.string().min(1),
+    kind: z.literal("container"),
+    manager: z.string().min(1).optional(),
+    runtime_instances: z.array(z.string().min(1)),
+    target: targetSchema.optional()
+}).strict();
+const recordSourceSchema = z.union([
+    z.object({
+        kind: z.literal("project"),
+        root: z.string().min(1)
+    }).strict(),
+    z.object({
+        digest: z.string().min(1).nullable(),
+        kind: z.literal("image"),
+        ref: z.string().min(1)
+    }).strict()
+]);
+const deploymentRecordV1Schema = z.object({
+    auth_profile: z.string().min(1).nullable(),
+    compile_fingerprint: z.string().min(1),
+    created_at: z.string().min(1),
+    env_file: z.string().min(1).optional(),
+    manager: z.literal("docker"),
+    name: z.string().min(1),
+    output_directory: z.string().min(1),
+    project_root: z.string().min(1),
+    target: targetSchema,
+    units: z.array(unitV1Schema).min(1),
+    version: z.literal("spawnfile.deployment.v1")
+}).strict();
+export const deploymentRecordSchema = z.object({
+    auth_profile: z.string().min(1).nullable(),
+    compile_fingerprint: z.string().min(1),
+    created_at: z.string().min(1),
+    env_file: z.string().min(1).optional(),
+    manager: z.string().min(1),
+    name: z.string().min(1),
+    output_directory: z.string().min(1).nullable(),
+    source: recordSourceSchema,
+    target: targetSchema,
+    units: z.array(unitSchema).min(1),
+    version: z.literal("spawnfile.deployment.v2")
+}).strict();
+const upgradeV1Record = (record) => ({
+    auth_profile: record.auth_profile,
+    compile_fingerprint: record.compile_fingerprint,
+    created_at: record.created_at,
+    ...(record.env_file ? { env_file: record.env_file } : {}),
+    manager: record.manager,
+    name: record.name,
+    output_directory: record.output_directory,
+    source: { kind: "project", root: record.project_root },
+    target: record.target,
+    units: record.units,
+    version: "spawnfile.deployment.v2"
+});
+const hasVersion = (source, version) => typeof source === "object"
+    && source !== null
+    && source.version === version;
+export const parseDeploymentRecord = (source, sourceLabel = "deployment record") => {
+    let record;
+    if (hasVersion(source, "spawnfile.deployment.v1")) {
+        const parsed = deploymentRecordV1Schema.safeParse(source);
+        if (!parsed.success) {
+            throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: ${z.prettifyError(parsed.error)}`);
+        }
+        record = upgradeV1Record(parsed.data);
+    }
+    else {
+        const parsed = deploymentRecordSchema.safeParse(source);
+        if (!parsed.success) {
+            throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: ${z.prettifyError(parsed.error)}`);
+        }
+        record = parsed.data;
+    }
+    const normalizedName = normalizeDeploymentName(record.name);
+    if (normalizedName !== record.name) {
+        throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: deployment name must be normalized`);
+    }
+    return record;
+};
+export const readDeploymentRecord = async (recordPath) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readUtf8File(recordPath));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("validation_error", `Unable to read deployment record ${recordPath}: ${reason}`);
+    }
+    return parseDeploymentRecord(parsed, recordPath);
+};
+export const readDeploymentRecordFromOutput = async (outputDirectory, deploymentName) => readDeploymentRecord(resolveDeploymentRecordPath(outputDirectory, deploymentName));
+export const listDeploymentRecords = async (outputDirectory) => {
+    const recordsDirectory = resolveDeploymentRecordsDirectory(outputDirectory);
+    let entries;
+    try {
+        entries = await readdir(recordsDirectory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("validation_error", `Unable to read deployment records directory ${recordsDirectory}: ${reason}`);
+    }
+    const records = await Promise.all(entries
+        .filter((entry) => entry.endsWith(".json"))
+        .sort()
+        .map(async (entry) => {
+        const recordPath = path.join(recordsDirectory, entry);
+        return {
+            path: recordPath,
+            record: await readDeploymentRecord(recordPath)
+        };
+    }));
+    return records.sort((left, right) => left.record.name.localeCompare(right.record.name));
+};
+export const writeDeploymentRecord = async (outputDirectory, record) => {
+    const parsed = parseDeploymentRecord(record);
+    const recordPath = resolveDeploymentRecordPath(outputDirectory, parsed.name);
+    await ensureDirectory(path.dirname(recordPath));
+    const temporaryPath = path.join(path.dirname(recordPath), `.${path.basename(recordPath)}.${process.pid}.${Date.now()}.tmp`);
+    await writeFile(temporaryPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    await rename(temporaryPath, recordPath);
+    return recordPath;
+};

package/dist/deployment/target.d.ts

@@ -0,0 +1,35 @@
+export type DockerDeploymentTarget = {
+    endpoint_fingerprint: string;
+    kind: "context";
+    name: string;
+} | {
+    endpoint_fingerprint: string;
+    kind: "docker-context";
+    context: string;
+} | {
+    kind: "host";
+    value: string;
+};
+export type DockerTargetExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface ResolveDockerDeploymentTargetOptions {
+    context?: string | null;
+    dockerCommand?: string;
+    dockerHost?: string | null;
+    execFile?: DockerTargetExecFile;
+    timeoutMs?: number;
+}
+export declare const createEndpointFingerprint: (endpoint: string) => string;
+export declare const createDockerDeploymentTarget: (input: {
+    context?: string;
+    endpoint?: string;
+    host?: string;
+}) => DockerDeploymentTarget;
+export declare const dockerContextNameForTarget: (target: DockerDeploymentTarget) => string | null;
+export declare const dockerHostValueForTarget: (target: DockerDeploymentTarget) => string | null;
+export declare const resolveDockerDeploymentTarget: (input?: ResolveDockerDeploymentTargetOptions) => Promise<DockerDeploymentTarget>;
+export declare const verifyDockerDeploymentTarget: (target: DockerDeploymentTarget, options?: Omit<ResolveDockerDeploymentTargetOptions, "context" | "dockerHost">) => Promise<string | null>;

package/dist/deployment/target.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+export const createEndpointFingerprint = (endpoint) => {
+    const normalized = endpoint.trim();
+    if (normalized.length === 0) {
+        throw new SpawnfileError("validation_error", "Deployment target endpoint must not be empty");
+    }
+    return `sha256:${createHash("sha256").update(normalized).digest("hex").slice(0, 32)}`;
+};
+const parseDockerEndpoint = (stdout) => {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        throw new SpawnfileError("runtime_error", "Docker context endpoint was empty");
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === "string" && parsed.trim().length > 0) {
+            return parsed.trim();
+        }
+    }
+    catch {
+        // Docker/podman variants may return a plain string instead of JSON.
+    }
+    return trimmed;
+};
+const resolveDockerContextEndpoint = async (context, options) => {
+    try {
+        const { stdout } = await options.execFile(options.dockerCommand, ["context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}"], { timeout: options.timeoutMs });
+        return parseDockerEndpoint(stdout);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("runtime_error", `Unable to resolve Docker context "${context}": ${reason}`);
+    }
+};
+export const createDockerDeploymentTarget = (input) => {
+    const host = input.host?.trim();
+    if (host) {
+        return {
+            kind: "host",
+            value: host
+        };
+    }
+    const context = input.context?.trim();
+    const endpoint = input.endpoint?.trim();
+    if (!context || !endpoint) {
+        throw new SpawnfileError("validation_error", "Docker context deployment targets require both context and endpoint");
+    }
+    return {
+        name: context,
+        endpoint_fingerprint: createEndpointFingerprint(endpoint),
+        kind: "context"
+    };
+};
+export const dockerContextNameForTarget = (target) => target.kind === "context"
+    ? target.name
+    : target.kind === "docker-context"
+        ? target.context
+        : null;
+export const dockerHostValueForTarget = (target) => target.kind === "host" ? target.value : null;
+export const resolveDockerDeploymentTarget = async (input = {}) => {
+    const explicitContext = input.context?.trim();
+    const host = explicitContext ? undefined : input.dockerHost?.trim() ?? process.env.DOCKER_HOST?.trim();
+    if (host) {
+        return createDockerDeploymentTarget({ host });
+    }
+    const resolvedOptions = {
+        dockerCommand: input.dockerCommand ?? "docker",
+        execFile: input.execFile ?? execFile,
+        timeoutMs: input.timeoutMs ?? 10_000
+    };
+    const context = explicitContext || "default";
+    const endpoint = await resolveDockerContextEndpoint(context, resolvedOptions);
+    return createDockerDeploymentTarget({ context, endpoint });
+};
+export const verifyDockerDeploymentTarget = async (target, options = {}) => {
+    if (target.kind === "host") {
+        return null;
+    }
+    const context = dockerContextNameForTarget(target);
+    if (!context) {
+        return null;
+    }
+    const current = await resolveDockerDeploymentTarget({
+        ...options,
+        context
+    });
+    const currentFingerprint = current.kind === "host" ? null : current.endpoint_fingerprint;
+    if (currentFingerprint !== target.endpoint_fingerprint) {
+        throw new SpawnfileError("runtime_error", `Docker context "${context}" endpoint changed since deployment`);
+    }
+    return context;
+};

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
+    });
+};