spawnfile 0.1.11 → 0.1.12

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";

package/dist/deployment/index.js

@@ -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";

package/dist/deployment/names.d.ts

@@ -0,0 +1,3 @@
+export declare const normalizeDeploymentName: (name: string | undefined) => string;
+export declare const resolveDeploymentRecordsDirectory: (outputDirectory: string) => string;
+export declare const resolveDeploymentRecordPath: (outputDirectory: string, deploymentName: string) => string;

package/dist/deployment/names.js

@@ -0,0 +1,12 @@
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+const deploymentNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const normalizeDeploymentName = (name) => {
+    const normalized = (name ?? "default").trim();
+    if (!deploymentNamePattern.test(normalized)) {
+        throw new SpawnfileError("validation_error", `Deployment name must be kebab-case: ${name ?? ""}`);
+    }
+    return normalized;
+};
+export const resolveDeploymentRecordsDirectory = (outputDirectory) => path.join(outputDirectory, "deployments");
+export const resolveDeploymentRecordPath = (outputDirectory, deploymentName) => path.join(resolveDeploymentRecordsDirectory(outputDirectory), `${normalizeDeploymentName(deploymentName)}.json`);

package/dist/deployment/record.d.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+declare const recordSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"project">;
+    root: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    digest: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"image">;
+    ref: z.ZodString;
+}, z.core.$strict>]>;
+export type DeploymentRecordSource = z.infer<typeof recordSourceSchema>;
+export declare const deploymentRecordSchema: z.ZodObject<{
+    auth_profile: z.ZodNullable<z.ZodString>;
+    compile_fingerprint: z.ZodString;
+    created_at: z.ZodString;
+    env_file: z.ZodOptional<z.ZodString>;
+    manager: z.ZodString;
+    name: z.ZodString;
+    output_directory: z.ZodNullable<z.ZodString>;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"project">;
+        root: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        digest: z.ZodNullable<z.ZodString>;
+        kind: z.ZodLiteral<"image">;
+        ref: z.ZodString;
+    }, z.core.$strict>]>;
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        endpoint_fingerprint: z.ZodString;
+        kind: z.ZodLiteral<"context">;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        context: z.ZodString;
+        endpoint_fingerprint: z.ZodString;
+        kind: z.ZodLiteral<"docker-context">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"host">;
+        value: z.ZodString;
+    }, z.core.$strict>]>;
+    units: z.ZodArray<z.ZodObject<{
+        container_id: z.ZodNullable<z.ZodString>;
+        container_name: z.ZodNullable<z.ZodString>;
+        contains: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodUnion<readonly [z.ZodLiteral<"agent">, z.ZodLiteral<"network">, z.ZodLiteral<"team">]>;
+        }, z.core.$strict>>;
+        id: z.ZodString;
+        image_id: z.ZodNullable<z.ZodString>;
+        image_tag: z.ZodString;
+        kind: z.ZodLiteral<"container">;
+        manager: z.ZodOptional<z.ZodString>;
+        runtime_instances: z.ZodArray<z.ZodString>;
+        target: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            endpoint_fingerprint: z.ZodString;
+            kind: z.ZodLiteral<"context">;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            context: z.ZodString;
+            endpoint_fingerprint: z.ZodString;
+            kind: z.ZodLiteral<"docker-context">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"host">;
+            value: z.ZodString;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>>;
+    version: z.ZodLiteral<"spawnfile.deployment.v2">;
+}, z.core.$strict>;
+export type DeploymentRecord = z.infer<typeof deploymentRecordSchema>;
+export declare const parseDeploymentRecord: (source: unknown, sourceLabel?: string) => DeploymentRecord;
+export declare const readDeploymentRecord: (recordPath: string) => Promise<DeploymentRecord>;
+export declare const readDeploymentRecordFromOutput: (outputDirectory: string, deploymentName: string) => Promise<DeploymentRecord>;
+export declare const listDeploymentRecords: (outputDirectory: string) => Promise<Array<{
+    path: string;
+    record: DeploymentRecord;
+}>>;
+export declare const writeDeploymentRecord: (outputDirectory: string, record: DeploymentRecord) => Promise<string>;
+export {};