spawnfile 0.1.10 → 0.1.12

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

package/dist/deployment/homeStore.js

@@ -0,0 +1,130 @@
+import path from "node:path";
+import { open, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { normalizeDeploymentName } from "./names.js";
+import { parseDeploymentRecord } from "./record.js";
+export const resolveHomeDeploymentsDirectory = () => path.join(resolveSpawnfileHome(), "deployments");
+export const resolveHomeDeploymentDirectory = (deploymentName) => path.join(resolveHomeDeploymentsDirectory(), normalizeDeploymentName(deploymentName));
+export const resolveHomeRecordPath = (deploymentName) => path.join(resolveHomeDeploymentDirectory(deploymentName), "record.json");
+export const resolveHomeReportPath = (deploymentName) => path.join(resolveHomeDeploymentDirectory(deploymentName), "spawnfile-report.json");
+/**
+ * Acquires an exclusive lock for a home deployment so concurrent `up`
+ * invocations cannot race on the same record (and orphan each other's
+ * containers). Returns a release function. Throws if the deployment is already
+ * locked by another in-flight operation.
+ */
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // ESRCH means no such process (stale); EPERM means it exists but is ours to
+        // not signal — treat as alive to stay safe.
+        return error.code === "EPERM";
+    }
+};
+export const acquireHomeDeploymentLock = async (deploymentName) => {
+    const directory = resolveHomeDeploymentDirectory(deploymentName);
+    await ensureDirectory(directory);
+    const lockPath = path.join(directory, ".lock");
+    const write = async () => {
+        const handle = await open(lockPath, "wx");
+        try {
+            await handle.write(JSON.stringify({ pid: process.pid }));
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    try {
+        await write();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        // A lock exists. Reclaim it only if the owning process is gone (a crashed
+        // deploy must not lock the deployment forever); otherwise it is genuinely busy.
+        let ownerPid = null;
+        try {
+            ownerPid = JSON.parse(await readUtf8File(lockPath)).pid ?? null;
+        }
+        catch {
+            ownerPid = null;
+        }
+        if (ownerPid !== null && isProcessAlive(ownerPid)) {
+            throw new SpawnfileError("runtime_error", `Deployment "${normalizeDeploymentName(deploymentName)}" is already being modified by another operation`);
+        }
+        await rm(lockPath, { force: true });
+        await write();
+    }
+    return async () => {
+        await rm(lockPath, { force: true });
+    };
+};
+const writeAtomic = async (filePath, content) => {
+    const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    await writeFile(temporaryPath, content, "utf8");
+    await rename(temporaryPath, filePath);
+};
+/** Writes the record and the cached distribution report together, record last. */
+export const writeHomeDeployment = async (record, report) => {
+    const parsed = parseDeploymentRecord(record);
+    const directory = resolveHomeDeploymentDirectory(parsed.name);
+    await ensureDirectory(directory);
+    const reportPath = resolveHomeReportPath(parsed.name);
+    const recordPath = resolveHomeRecordPath(parsed.name);
+    await writeAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`);
+    await writeAtomic(recordPath, `${JSON.stringify(parsed, null, 2)}\n`);
+    return { recordPath, reportPath };
+};
+export const readHomeDeploymentRecord = async (deploymentName) => {
+    const recordPath = resolveHomeRecordPath(deploymentName);
+    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 home deployment record ${recordPath}: ${reason}`);
+    }
+    return parseDeploymentRecord(parsed, recordPath);
+};
+export const readHomeDeploymentReport = async (deploymentName) => readUtf8File(resolveHomeReportPath(deploymentName));
+export const homeDeploymentExists = async (deploymentName) => {
+    const records = await listHomeDeploymentRecords();
+    const target = normalizeDeploymentName(deploymentName);
+    return records.some((entry) => entry.record.name === target);
+};
+export const listHomeDeploymentRecords = async () => {
+    const directory = resolveHomeDeploymentsDirectory();
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("validation_error", `Unable to read home deployments directory ${directory}: ${reason}`);
+    }
+    const records = await Promise.all(entries
+        .sort()
+        .map(async (entry) => {
+        const recordPath = path.join(directory, entry, "record.json");
+        try {
+            const parsed = JSON.parse(await readUtf8File(recordPath));
+            return { path: recordPath, record: parseDeploymentRecord(parsed, recordPath) };
+        }
+        catch {
+            return null;
+        }
+    }));
+    return records
+        .filter((entry) => entry !== null)
+        .sort((left, right) => left.record.name.localeCompare(right.record.name));
+};

package/dist/deployment/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./dockerLabels.js";
+export * from "./dockerInspect.js";
+export * from "./dockerLogs.js";
+export * from "./dockerManager.js";
+export * from "./dockerProbeGateway.js";
+export * from "./homeStore.js";
+export * from "./names.js";
+export * from "./record.js";
+export * from "./target.js";