spawnfile 0.1.11 → 0.1.13

package/dist/deployment/dockerInspect.js

@@ -0,0 +1,130 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { dockerContextNameForTarget, verifyDockerDeploymentTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const toStringOrNull = (value) => typeof value === "string" && value.length > 0 ? value : null;
+const toNumberOrNull = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
+const argsForInspect = (record, targetRef) => {
+    const context = dockerContextNameForTarget(record.target);
+    if (context) {
+        return ["--context", context, "inspect", targetRef];
+    }
+    if (record.target.kind === "host") {
+        return ["--host", record.target.value, "inspect", targetRef];
+    }
+    return ["inspect", targetRef];
+};
+const matchesDockerId = (recorded, live) => !recorded
+    || !live
+    || recorded === live
+    || live.startsWith(recorded)
+    || recorded.startsWith(live);
+const createDriftMessages = (unit, inspected) => {
+    const containerId = toStringOrNull(inspected.Id);
+    const imageId = toStringOrNull(inspected.Image);
+    const drift = [];
+    if (!matchesDockerId(unit.container_id, containerId)) {
+        drift.push(`container id drift: recorded ${unit.container_id}, live ${containerId}`);
+    }
+    if (!matchesDockerId(unit.image_id, imageId)) {
+        drift.push(`image id drift: recorded ${unit.image_id}, live ${imageId}`);
+    }
+    return { containerId, drift, imageId };
+};
+const inspectionFromState = (unitId, unit, inspected, state) => {
+    const running = typeof state.Running === "boolean" ? state.Running : null;
+    const status = toStringOrNull(state.Status);
+    const { containerId, drift, imageId } = createDriftMessages(unit, inspected);
+    const baseMessage = running === true
+        ? `container is running (${status ?? "running"})`
+        : `container is not running (${status ?? "unknown"})`;
+    return {
+        containerId,
+        drift,
+        exists: true,
+        exitCode: toNumberOrNull(state.ExitCode),
+        finishedAt: toStringOrNull(state.FinishedAt),
+        imageId,
+        message: drift.length > 0 ? `${baseMessage}; ${drift.join("; ")}` : baseMessage,
+        restartCount: toNumberOrNull(state.RestartCount),
+        running,
+        severity: drift.length > 0 ? "warn" : running === false ? "error" : "ok",
+        startedAt: toStringOrNull(state.StartedAt),
+        status,
+        unitId
+    };
+};
+const missingInspection = (unitId, message) => ({
+    containerId: null,
+    drift: [],
+    exists: false,
+    exitCode: null,
+    finishedAt: null,
+    imageId: null,
+    message,
+    restartCount: null,
+    running: false,
+    severity: "warn",
+    startedAt: null,
+    status: null,
+    unitId
+});
+const unknownInspection = (unitId, message, severity = "unknown") => ({
+    containerId: null,
+    drift: [],
+    exists: null,
+    exitCode: null,
+    finishedAt: null,
+    imageId: null,
+    message,
+    restartCount: null,
+    running: null,
+    severity,
+    startedAt: null,
+    status: null,
+    unitId
+});
+const inspectUnit = async (record, unit, options) => {
+    const targetRef = targetRefForUnit(unit);
+    if (!targetRef) {
+        return unknownInspection(unit.id, "deployment unit has no recorded container id or name");
+    }
+    try {
+        const { stdout } = await options.execFile(options.dockerCommand, argsForInspect(record, targetRef), { timeout: options.timeoutMs });
+        const parsed = JSON.parse(stdout);
+        const [first] = Array.isArray(parsed) ? parsed : [];
+        const state = isRecord(first) && isRecord(first.State) ? first.State : null;
+        return state
+            ? inspectionFromState(unit.id, unit, first, state)
+            : unknownInspection(unit.id, `docker inspect returned no state for ${targetRef}`);
+    }
+    catch (error) {
+        const stderr = isRecord(error) ? toStringOrNull(error.stderr) : null;
+        const message = stderr ?? (error instanceof Error ? error.message : String(error));
+        if (/No such object/i.test(message)) {
+            return missingInspection(unit.id, `recorded container ${targetRef} is missing`);
+        }
+        return unknownInspection(unit.id, `unable to inspect container ${targetRef}: ${message}`, "error");
+    }
+};
+export const inspectDockerDeployment = async (record, options = {}) => {
+    const resolvedOptions = {
+        dockerCommand: options.dockerCommand ?? "docker",
+        execFile: options.execFile ?? execFile,
+        timeoutMs: options.timeoutMs ?? 10_000
+    };
+    try {
+        await verifyDockerDeploymentTarget(record.target, resolvedOptions);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return new Map(record.units.map((unit) => [
+            unit.id,
+            unknownInspection(unit.id, `unable to verify recorded Docker target: ${message}`, "error")
+        ]));
+    }
+    const inspections = await Promise.all(record.units.map(async (unit) => inspectUnit(record, unit, resolvedOptions)));
+    return new Map(inspections.map((inspection) => [inspection.unitId, inspection]));
+};

package/dist/deployment/dockerLabels.d.ts

@@ -0,0 +1,16 @@
+export declare const dockerDeploymentLabelKeys: {
+    readonly compileFingerprint: "com.spawnfile.compile_fingerprint";
+    readonly deployment: "com.spawnfile.deployment";
+    readonly project: "com.spawnfile.project";
+    readonly unit: "com.spawnfile.unit";
+    readonly version: "com.spawnfile.version";
+};
+export interface DockerDeploymentLabelInput {
+    compileFingerprint: string;
+    deployment: string;
+    project: string;
+    unit: string;
+    version: string;
+}
+export declare const createDockerDeploymentLabels: (input: DockerDeploymentLabelInput) => Record<string, string>;
+export declare const appendDockerLabelArgs: (args: string[], labels: Record<string, string>) => void;

package/dist/deployment/dockerLabels.js

@@ -0,0 +1,32 @@
+import { SpawnfileError } from "../shared/index.js";
+export const dockerDeploymentLabelKeys = {
+    compileFingerprint: "com.spawnfile.compile_fingerprint",
+    deployment: "com.spawnfile.deployment",
+    project: "com.spawnfile.project",
+    unit: "com.spawnfile.unit",
+    version: "com.spawnfile.version"
+};
+const dockerLabelValuePattern = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+const assertIdentifierLabelValue = (key, value) => {
+    if (!dockerLabelValuePattern.test(value)) {
+        throw new SpawnfileError("validation_error", `Docker deployment label ${key} must be an identifier`);
+    }
+};
+export const createDockerDeploymentLabels = (input) => {
+    const labels = {
+        [dockerDeploymentLabelKeys.compileFingerprint]: input.compileFingerprint,
+        [dockerDeploymentLabelKeys.deployment]: input.deployment,
+        [dockerDeploymentLabelKeys.project]: input.project,
+        [dockerDeploymentLabelKeys.unit]: input.unit,
+        [dockerDeploymentLabelKeys.version]: input.version
+    };
+    for (const [key, value] of Object.entries(labels)) {
+        assertIdentifierLabelValue(key, value);
+    }
+    return labels;
+};
+export const appendDockerLabelArgs = (args, labels) => {
+    for (const [key, value] of Object.entries(labels).sort(([left], [right]) => left.localeCompare(right))) {
+        args.push("--label", `${key}=${value}`);
+    }
+};

package/dist/deployment/dockerLogs.d.ts

@@ -0,0 +1,24 @@
+import type { DeploymentRecord } from "./record.js";
+export type DockerLogsExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface DockerUnitLogs {
+    containerRef: string | null;
+    message: string;
+    severity: "error" | "ok" | "unknown" | "warn";
+    text: string;
+    unitId: string;
+}
+export type DockerLogsResult = Map<string, DockerUnitLogs>;
+export interface DockerLogsOptions {
+    dockerCommand?: string;
+    execFile?: DockerLogsExecFile;
+    secretValues?: string[];
+    tail?: number;
+    timeoutMs?: number;
+}
+export declare const redactDockerLogText: (text: string, secretValues?: string[]) => string;
+export declare const readDockerDeploymentLogs: (record: DeploymentRecord, options?: DockerLogsOptions) => Promise<DockerLogsResult>;

package/dist/deployment/dockerLogs.js

@@ -0,0 +1,96 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { dockerContextNameForTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
+const withDockerTarget = (record, args) => {
+    const context = dockerContextNameForTarget(record.target);
+    if (context) {
+        return ["--context", context, ...args];
+    }
+    if (record.target.kind === "host") {
+        return ["--host", record.target.value, ...args];
+    }
+    return args;
+};
+const normalizeTail = (tail) => typeof tail === "number" && Number.isInteger(tail) && tail > 0 ? tail : 100;
+const redactKnownSecrets = (text, secretValues) => secretValues
+    .filter((secret) => secret.length > 0)
+    .reduce((redacted, secret) => redacted.replaceAll(secret, "[REDACTED]"), text);
+const redactTokenLikeText = (text) => {
+    let redacted = text;
+    redacted = redacted.replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, "Bearer [REDACTED]");
+    redacted = redacted.replace(/\bmagt_v1_[A-Za-z0-9_-]{16,}\b/g, "[REDACTED]");
+    redacted = redacted.replace(/\b(?:sk|sk-proj)-[A-Za-z0-9_-]{20,}\b/g, "[REDACTED]");
+    redacted = redacted.replace(/\b([A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*=)([^\s"'`]+)/gi, "$1[REDACTED]");
+    redacted = redacted.replace(/("([^"]*(?:api[_-]?key|token|secret|password)[^"]*)"\s*:\s*")([^"]+)(")/gi, "$1[REDACTED]$4");
+    return redacted;
+};
+export const redactDockerLogText = (text, secretValues = []) => redactTokenLikeText(redactKnownSecrets(text, secretValues));
+const combineLogStreams = (stdout, stderr) => {
+    if (!stdout) {
+        return stderr;
+    }
+    if (!stderr) {
+        return stdout;
+    }
+    return `${stdout}${stdout.endsWith("\n") ? "" : "\n"}${stderr}`;
+};
+const missingUnitLogs = (unitId, message) => ({
+    containerRef: null,
+    message,
+    severity: "unknown",
+    text: "",
+    unitId
+});
+const failedUnitLogs = (unitId, containerRef, message, severity = "error") => ({
+    containerRef,
+    message,
+    severity,
+    text: "",
+    unitId
+});
+const unitLogs = (unitId, containerRef, text) => ({
+    containerRef,
+    message: text.length > 0 ? "logs collected" : "logs collected; no output",
+    severity: "ok",
+    text,
+    unitId
+});
+const toErrorMessage = (error) => {
+    if (typeof error === "object" && error !== null && "stderr" in error) {
+        const stderr = error.stderr;
+        if (typeof stderr === "string" && stderr.length > 0) {
+            return stderr.trim();
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+};
+const readUnitLogs = async (record, unit, options) => {
+    const containerRef = targetRefForUnit(unit);
+    if (!containerRef) {
+        return missingUnitLogs(unit.id, "deployment unit has no recorded container id or name");
+    }
+    try {
+        const result = await options.execFile(options.dockerCommand, withDockerTarget(record, ["logs", "--tail", String(options.tail), containerRef]), { timeout: options.timeoutMs });
+        return unitLogs(unit.id, containerRef, redactDockerLogText(combineLogStreams(result.stdout, result.stderr), options.secretValues));
+    }
+    catch (error) {
+        const message = redactDockerLogText(toErrorMessage(error), options.secretValues);
+        if (/No such (?:object|container)/i.test(message)) {
+            return failedUnitLogs(unit.id, containerRef, `recorded container ${containerRef} is missing`, "warn");
+        }
+        return failedUnitLogs(unit.id, containerRef, `unable to collect logs for ${containerRef}: ${message}`);
+    }
+};
+export const readDockerDeploymentLogs = async (record, options = {}) => {
+    const resolvedOptions = {
+        dockerCommand: options.dockerCommand ?? "docker",
+        execFile: options.execFile ?? execFile,
+        secretValues: options.secretValues ?? [],
+        tail: normalizeTail(options.tail),
+        timeoutMs: options.timeoutMs ?? 10_000
+    };
+    const results = await Promise.all(record.units.map(async (unit) => readUnitLogs(record, unit, resolvedOptions)));
+    return new Map(results.map((result) => [result.unitId, result]));
+};

package/dist/deployment/dockerManager.d.ts

@@ -0,0 +1,59 @@
+import type { DeploymentRecordSource } from "./record.js";
+import { type DockerDeploymentTarget, type DockerTargetExecFile } from "./target.js";
+import { type DeploymentRecord } from "./record.js";
+export interface DockerDeploymentNodeInput {
+    id: string;
+    kind: "agent" | "team";
+}
+export interface DockerDeploymentRunMetadata {
+    containerId?: string;
+    imageId?: string;
+}
+export interface DockerDeploymentRunInvocationInput {
+    command: string;
+    containerName: string | null;
+    deploymentName?: string | null;
+    detach: boolean;
+    dockerContext?: string | null;
+    dockerHost?: string | null;
+}
+export interface DockerDeploymentReportInput {
+    compile_fingerprint?: string;
+    container?: {
+        runtime_instances: Array<{
+            id: string;
+        }>;
+    };
+    nodes: DockerDeploymentNodeInput[];
+    root: string;
+}
+export interface WriteDockerDeploymentRecordInput {
+    authProfileName: string | null;
+    compileFingerprint: string;
+    containerName: string | null;
+    deploymentName?: string;
+    envFilePath?: string;
+    imageTag: string;
+    nodes: DockerDeploymentNodeInput[];
+    outputDirectory: string;
+    projectRoot: string;
+    runMetadata?: DockerDeploymentRunMetadata;
+    runtimeInstanceIds: string[];
+    source?: DeploymentRecordSource;
+    target: DockerDeploymentTarget;
+}
+export declare const createDockerDeploymentUnitId: (deploymentName: string) => string;
+export declare const createDockerDeploymentRecord: (input: WriteDockerDeploymentRecordInput) => DeploymentRecord;
+export declare const createDockerProjectLabel: (projectRoot: string, projectName?: string) => string;
+export declare const writeDockerDeploymentRecord: (input: WriteDockerDeploymentRecordInput) => Promise<string>;
+export declare const writeDockerDeploymentRecordForRun: (input: {
+    authProfileName: string | null;
+    envFilePath?: string;
+    imageTag: string;
+    invocation: DockerDeploymentRunInvocationInput;
+    outputDirectory: string;
+    report: DockerDeploymentReportInput;
+    runMetadata?: DockerDeploymentRunMetadata;
+    targetExecFile?: DockerTargetExecFile;
+    targetTimeoutMs?: number;
+}) => Promise<string | null>;

package/dist/deployment/dockerManager.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { normalizeProjectLabelSlug } from "../distribution/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { normalizeDeploymentName } from "./names.js";
+import { resolveDockerDeploymentTarget } from "./target.js";
+import { writeDeploymentRecord } from "./record.js";
+const resolveProjectSlug = (projectRoot) => {
+    const base = path.basename(projectRoot).toLowerCase() === "spawnfile"
+        ? path.basename(path.dirname(projectRoot))
+        : path.basename(projectRoot);
+    return base
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "project";
+};
+export const createDockerDeploymentUnitId = (deploymentName) => `${deploymentName}-container`;
+export const createDockerDeploymentRecord = (input) => {
+    const name = normalizeDeploymentName(input.deploymentName);
+    return {
+        auth_profile: input.authProfileName,
+        compile_fingerprint: input.compileFingerprint,
+        created_at: new Date().toISOString(),
+        ...(input.envFilePath ? { env_file: path.resolve(input.envFilePath) } : {}),
+        manager: "docker",
+        name,
+        output_directory: path.resolve(input.outputDirectory),
+        source: input.source ?? { kind: "project", root: path.resolve(input.projectRoot) },
+        target: input.target,
+        units: [
+            {
+                container_id: input.runMetadata?.containerId ?? null,
+                container_name: input.containerName,
+                contains: input.nodes.map((node) => ({ id: node.id, kind: node.kind })),
+                id: createDockerDeploymentUnitId(name),
+                image_id: input.runMetadata?.imageId ?? null,
+                image_tag: input.imageTag,
+                kind: "container",
+                runtime_instances: [...input.runtimeInstanceIds].sort()
+            }
+        ],
+        version: "spawnfile.deployment.v2"
+    };
+};
+export const createDockerProjectLabel = (projectRoot, projectName) => projectName ? normalizeProjectLabelSlug(projectName) : resolveProjectSlug(projectRoot);
+const requireCompileFingerprint = (fingerprint) => {
+    if (!fingerprint) {
+        throw new SpawnfileError("validation_error", "Detached deployment records require compile_fingerprint in the compile report");
+    }
+    return fingerprint;
+};
+export const writeDockerDeploymentRecord = async (input) => writeDeploymentRecord(input.outputDirectory, createDockerDeploymentRecord(input));
+export const writeDockerDeploymentRecordForRun = async (input) => {
+    if (!input.invocation.detach || !input.invocation.deploymentName) {
+        return null;
+    }
+    return writeDockerDeploymentRecord({
+        authProfileName: input.authProfileName,
+        compileFingerprint: requireCompileFingerprint(input.report.compile_fingerprint),
+        containerName: input.invocation.containerName,
+        deploymentName: input.invocation.deploymentName,
+        envFilePath: input.envFilePath,
+        imageTag: input.imageTag,
+        nodes: input.report.nodes,
+        outputDirectory: input.outputDirectory,
+        projectRoot: input.report.root,
+        runMetadata: input.runMetadata,
+        runtimeInstanceIds: input.report.container?.runtime_instances.map((instance) => instance.id) ?? [],
+        target: await resolveDockerDeploymentTarget({
+            context: input.invocation.dockerContext ?? undefined,
+            dockerCommand: input.invocation.command,
+            dockerHost: input.invocation.dockerHost ?? undefined,
+            execFile: input.targetExecFile,
+            timeoutMs: input.targetTimeoutMs
+        })
+    });
+};

package/dist/deployment/dockerProbeGateway.d.ts

@@ -0,0 +1,16 @@
+import type { RuntimeProbeGateway } from "../runtime/index.js";
+import type { DeploymentRecord } from "./record.js";
+import type { DockerUnitInspection } from "./dockerInspect.js";
+export type DockerProbeExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface DockerProbeGatewayOptions {
+    dockerCommand?: string;
+    execFile?: DockerProbeExecFile;
+    inspection: DockerUnitInspection;
+    timeoutMs?: number;
+}
+export declare const createDockerProbeGateway: (record: DeploymentRecord, unit: DeploymentRecord["units"][number], options: DockerProbeGatewayOptions) => RuntimeProbeGateway;

package/dist/deployment/dockerProbeGateway.js

@@ -0,0 +1,48 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { dockerContextNameForTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const targetRefForUnit = (unit) => {
+    const targetRef = unit.container_id ?? unit.container_name;
+    if (!targetRef) {
+        throw new Error(`deployment unit ${unit.id} has no recorded container id or name`);
+    }
+    return targetRef;
+};
+const withDockerTarget = (record, args) => {
+    const context = dockerContextNameForTarget(record.target);
+    if (context) {
+        return ["--context", context, ...args];
+    }
+    if (record.target.kind === "host") {
+        return ["--host", record.target.value, ...args];
+    }
+    return args;
+};
+export const createDockerProbeGateway = (record, unit, options) => {
+    const dockerCommand = options.dockerCommand ?? "docker";
+    const runExec = options.execFile ?? execFile;
+    const timeout = options.timeoutMs ?? 10_000;
+    const exec = async (command) => {
+        const targetRef = targetRefForUnit(unit);
+        return runExec(dockerCommand, withDockerTarget(record, ["exec", targetRef, ...command]), { timeout });
+    };
+    return {
+        exec,
+        async httpGet(port, requestPath, headers = {}) {
+            const url = `http://127.0.0.1:${port}${requestPath.startsWith("/") ? requestPath : `/${requestPath}`}`;
+            try {
+                const headerArgs = Object.entries(headers).flatMap(([name, value]) => ["-H", `${name}: ${value}`]);
+                const result = await exec(["curl", "-fsS", ...headerArgs, url]);
+                return { body: result.stdout, ok: true };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { body: "", error: message, ok: false };
+            }
+        },
+        async inspectUnit() {
+            return options.inspection;
+        }
+    };
+};

package/dist/deployment/dockerRecover.d.ts

@@ -0,0 +1,17 @@
+import type { DeploymentRecord } from "./record.js";
+import { type DockerTargetExecFile } from "./target.js";
+export interface RecoverDockerDeploymentRecordsOptions {
+    contains?: DeploymentRecord["units"][number]["contains"];
+    context: string;
+    dockerCommand?: string;
+    execFile?: DockerTargetExecFile;
+    outputDirectory: string;
+    projectLabel: string;
+    runtimeInstanceIds?: string[];
+    sourceRoot: string;
+    timeoutMs?: number;
+}
+export declare const recoverDockerDeploymentRecords: (options: RecoverDockerDeploymentRecordsOptions) => Promise<Array<{
+    path: string;
+    record: DeploymentRecord;
+}>>;

package/dist/deployment/dockerRecover.js

@@ -0,0 +1,129 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+import { dockerDeploymentLabelKeys } from "./dockerLabels.js";
+import { resolveDockerDeploymentTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const toStringOrNull = (value) => typeof value === "string" && value.length > 0 ? value : null;
+const labelsFrom = (inspection) => {
+    const labels = inspection.Config?.Labels;
+    if (!isRecord(labels)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(labels).filter((entry) => typeof entry[1] === "string"));
+};
+const withContext = (context, args) => [
+    "--context",
+    context,
+    ...args
+];
+const containerNameFrom = (inspection) => {
+    const name = toStringOrNull(inspection.Name);
+    return name ? name.replace(/^\//u, "") : null;
+};
+const parseInspections = (stdout) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        throw new SpawnfileError("runtime_error", `Unable to parse recovered Docker container inspection: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return Array.isArray(parsed) ? parsed.filter(isRecord) : [];
+};
+const deploymentNameFor = (labels) => labels[dockerDeploymentLabelKeys.deployment] ?? null;
+const buildUnit = (inspection, labels, contains, runtimeInstanceIds) => {
+    const unitId = labels[dockerDeploymentLabelKeys.unit];
+    const imageTag = toStringOrNull(inspection.Config?.Image);
+    if (!unitId || !imageTag) {
+        return null;
+    }
+    return {
+        container_id: toStringOrNull(inspection.Id),
+        container_name: containerNameFrom(inspection),
+        contains,
+        id: unitId,
+        image_id: toStringOrNull(inspection.Image),
+        image_tag: imageTag,
+        kind: "container",
+        runtime_instances: runtimeInstanceIds
+    };
+};
+const groupByDeployment = (inspections, options, target) => {
+    const records = new Map();
+    const unitsByDeployment = new Map();
+    const contains = options.contains ?? [];
+    const runtimeInstanceIds = options.runtimeInstanceIds ?? [];
+    for (const inspection of inspections) {
+        const labels = labelsFrom(inspection);
+        if (labels[dockerDeploymentLabelKeys.project] !== options.projectLabel) {
+            continue;
+        }
+        const name = deploymentNameFor(labels);
+        const compileFingerprint = labels[dockerDeploymentLabelKeys.compileFingerprint];
+        if (!name || !compileFingerprint) {
+            continue;
+        }
+        const unit = buildUnit(inspection, labels, contains, runtimeInstanceIds);
+        if (!unit) {
+            continue;
+        }
+        const seenUnits = unitsByDeployment.get(name) ?? new Set();
+        if (seenUnits.has(unit.id)) {
+            throw new SpawnfileError("validation_error", `Recovered deployment "${name}" has multiple containers for unit "${unit.id}"`);
+        }
+        seenUnits.add(unit.id);
+        unitsByDeployment.set(name, seenUnits);
+        const record = records.get(name) ?? {
+            auth_profile: null,
+            compile_fingerprint: compileFingerprint,
+            created_at: toStringOrNull(inspection.Created) ?? new Date().toISOString(),
+            manager: "docker",
+            name,
+            output_directory: options.outputDirectory,
+            source: { kind: "project", root: options.sourceRoot },
+            target,
+            units: [],
+            version: "spawnfile.deployment.v2"
+        };
+        record.units.push(unit);
+        records.set(name, record);
+    }
+    return [...records.values()]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((record) => ({
+        path: `docker-context://${options.context}/${record.name}`,
+        record: {
+            ...record,
+            units: [...record.units].sort((left, right) => left.id.localeCompare(right.id))
+        }
+    }));
+};
+export const recoverDockerDeploymentRecords = async (options) => {
+    const resolved = {
+        dockerCommand: options.dockerCommand ?? "docker",
+        execFile: options.execFile ?? execFile,
+        timeoutMs: options.timeoutMs ?? 10_000
+    };
+    const target = await resolveDockerDeploymentTarget({
+        context: options.context,
+        dockerCommand: resolved.dockerCommand,
+        execFile: resolved.execFile,
+        timeoutMs: resolved.timeoutMs
+    });
+    const { stdout: listStdout } = await resolved.execFile(resolved.dockerCommand, withContext(options.context, [
+        "ps",
+        "-a",
+        "--filter",
+        `label=${dockerDeploymentLabelKeys.version}`,
+        "--format",
+        "{{.ID}}"
+    ]), { timeout: resolved.timeoutMs });
+    const ids = listStdout.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
+    if (ids.length === 0) {
+        return [];
+    }
+    const { stdout } = await resolved.execFile(resolved.dockerCommand, withContext(options.context, ["inspect", ...ids]), { timeout: resolved.timeoutMs });
+    return groupByDeployment(parseInspections(stdout), options, target);
+};

package/dist/deployment/homeStore.d.ts

@@ -0,0 +1,19 @@
+import type { DistributionReport } from "../distribution/index.js";
+import { type DeploymentRecord } from "./record.js";
+export declare const resolveHomeDeploymentsDirectory: () => string;
+export declare const resolveHomeDeploymentDirectory: (deploymentName: string) => string;
+export declare const resolveHomeRecordPath: (deploymentName: string) => string;
+export declare const resolveHomeReportPath: (deploymentName: string) => string;
+export declare const acquireHomeDeploymentLock: (deploymentName: string) => Promise<() => Promise<void>>;
+/** Writes the record and the cached distribution report together, record last. */
+export declare const writeHomeDeployment: (record: DeploymentRecord, report: DistributionReport) => Promise<{
+    recordPath: string;
+    reportPath: string;
+}>;
+export declare const readHomeDeploymentRecord: (deploymentName: string) => Promise<DeploymentRecord>;
+export declare const readHomeDeploymentReport: (deploymentName: string) => Promise<string>;
+export declare const homeDeploymentExists: (deploymentName: string) => Promise<boolean>;
+export declare const listHomeDeploymentRecords: () => Promise<Array<{
+    path: string;
+    record: DeploymentRecord;
+}>>;