spawnfile 0.1.11 → 0.1.12

package/dist/compiler/runProjectDocker.d.ts

@@ -0,0 +1,19 @@
+export interface DockerRunInvocation {
+    args: string[];
+    command: string;
+    containerName: string | null;
+    cwd: string;
+    detach: boolean;
+    deploymentName?: string | null;
+    dockerContext?: string | null;
+    dockerHost?: string | null;
+    envFilePath: string;
+    imageTag: string;
+    supportDirectory: string;
+}
+export interface DockerRunResult {
+    containerId?: string;
+    imageId?: string;
+}
+export type DockerRunRunner = (invocation: DockerRunInvocation) => Promise<DockerRunResult | void>;
+export declare const runDockerContainer: DockerRunRunner;

package/dist/compiler/runProjectDocker.js

@@ -0,0 +1,57 @@
+import { execFile as execFileCallback, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const inspectImageArgs = (invocation, containerId) => {
+    const base = invocation.dockerContext
+        ? ["--context", invocation.dockerContext, "inspect"]
+        : invocation.dockerHost
+            ? ["--host", invocation.dockerHost, "inspect"]
+            : ["inspect"];
+    return [...base, "--format", "{{.Image}}", containerId];
+};
+const inspectDetachedImageId = async (invocation, containerId) => {
+    try {
+        const { stdout } = await execFile(invocation.command, inspectImageArgs(invocation, containerId), {
+            cwd: invocation.cwd,
+            timeout: 10_000
+        });
+        return stdout.trim() || undefined;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("runtime_error", `Unable to inspect detached container ${containerId} image id: ${message}`);
+    }
+};
+export const runDockerContainer = async (invocation) => new Promise((resolve, reject) => {
+    let stdout = "";
+    const child = spawn(invocation.command, invocation.args, {
+        cwd: invocation.cwd,
+        stdio: invocation.detach ? ["ignore", "pipe", "inherit"] : "inherit"
+    });
+    if (invocation.detach && child.stdout) {
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+    }
+    child.once("error", (error) => {
+        reject(new SpawnfileError("runtime_error", `Unable to start docker run for ${invocation.imageTag}: ${error.message}`));
+    });
+    child.once("exit", (code, signal) => {
+        if (code === 0) {
+            const containerId = stdout.trim().split(/\s+/)[0];
+            if (!invocation.detach || !containerId) {
+                resolve(undefined);
+                return;
+            }
+            inspectDetachedImageId(invocation, containerId)
+                .then((imageId) => resolve({ containerId, ...(imageId ? { imageId } : {}) }))
+                .catch(reject);
+            return;
+        }
+        reject(new SpawnfileError("runtime_error", signal
+            ? `Docker run for ${invocation.imageTag} exited from signal ${signal}`
+            : `Docker run for ${invocation.imageTag} failed with exit code ${code ?? "unknown"}`));
+    });
+});

package/dist/compiler/types.d.ts

@@ -82,8 +82,7 @@ export interface ResolvedHttpSurface {
     port?: number;
 }
 export interface ResolvedMoltnetRoomPolicy {
-    read?: "all" | "mentions" | "thread_only";
-    reply?: "auto" | "never";
+    wake?: "all" | "mentions" | "thread_only" | "never";
 }
 export interface ResolvedMoltnetDMConfig extends ResolvedMoltnetRoomPolicy {
     enabled: boolean;

package/dist/compiler/upProject.d.ts

@@ -1,3 +1,4 @@
+import { type DockerTargetExecFile } from "../deployment/index.js";
 import { type BuildProjectResult, type DockerBuildRunner } from "./buildProject.js";
 import { type DockerRunRunner } from "./runProject.js";
 import { CompileProjectOptions } from "./compileProject.js";
@@ -6,14 +7,19 @@ export interface UpProjectOptions extends CompileProjectOptions {
     buildRunner?: DockerBuildRunner;
     containerName?: string;
     detach?: boolean;
+    deploymentName?: string;
     dockerCommand?: string;
+    dockerContext?: string;
+    dockerHost?: string;
     envFilePath?: string;
     imageTag?: string;
     runRunner?: DockerRunRunner;
+    targetExecFile?: DockerTargetExecFile;
 }
 export interface UpProjectResult extends BuildProjectResult {
     authProfileName: string | null;
     containerName: string | null;
+    deploymentRecordPath?: string | null;
     supportDirectory: string | null;
 }
 export declare const upProject: (inputPath: string, options?: UpProjectOptions) => Promise<UpProjectResult>;

package/dist/compiler/upProject.js

@@ -1,37 +1,71 @@
+import path from "node:path";
 import { removeDirectory } from "../filesystem/index.js";
+import { writeDockerDeploymentRecordForRun } from "../deployment/index.js";
 import { buildProject } from "./buildProject.js";
-import { createDockerRunInvocation, runDockerContainer } from "./runProject.js";
+import { createDockerRunInvocation, resolveDetachedDeploymentOptions, runDockerContainer } from "./runProject.js";
 import { requireAuthProfile } from "../auth/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY } from "../shared/index.js";
 export const upProject = async (inputPath, options = {}) => {
+    const resolvedOptions = await resolveDetachedDeploymentOptions(path.resolve(options.outputDirectory ?? DEFAULT_OUTPUT_DIRECTORY), {
+        authProfile: options.authProfile,
+        containerName: options.containerName,
+        deploymentName: options.deploymentName,
+        detach: options.detach,
+        dockerCommand: options.dockerCommand,
+        dockerContext: options.dockerContext,
+        dockerHost: options.dockerHost,
+        envFilePath: options.envFilePath,
+        imageTag: options.imageTag,
+        targetExecFile: options.targetExecFile
+    });
     const buildResult = await buildProject(inputPath, {
         buildRunner: options.buildRunner,
         clean: options.clean,
         dockerCommand: options.dockerCommand,
-        imageTag: options.imageTag,
+        imageTag: resolvedOptions.imageTag,
         outputDirectory: options.outputDirectory
     });
-    const authProfile = options.authProfile
-        ? await requireAuthProfile(options.authProfile)
+    const authProfile = resolvedOptions.authProfile
+        ? await requireAuthProfile(resolvedOptions.authProfile)
         : null;
-    const invocation = await createDockerRunInvocation(buildResult, buildResult.imageTag, {
+    const imageTag = resolvedOptions.imageTag ?? buildResult.imageTag;
+    const invocation = await createDockerRunInvocation(buildResult, imageTag, {
         authProfile,
-        containerName: options.containerName,
+        containerName: resolvedOptions.containerName,
         detach: options.detach,
+        deploymentName: resolvedOptions.deploymentName,
         dockerCommand: options.dockerCommand,
-        envFilePath: options.envFilePath
+        dockerContext: resolvedOptions.dockerContext,
+        dockerHost: resolvedOptions.dockerHost,
+        envFilePath: resolvedOptions.envFilePath
     });
+    let runMetadata;
     try {
-        await (options.runRunner ?? runDockerContainer)(invocation);
+        runMetadata = await (options.runRunner ?? runDockerContainer)(invocation);
     }
     finally {
         if (!invocation.detach) {
             await removeDirectory(invocation.supportDirectory);
         }
     }
+    const deploymentRecordPath = invocation.detach && invocation.deploymentName
+        ? await writeDockerDeploymentRecordForRun({
+            authProfileName: authProfile?.name ?? null,
+            envFilePath: resolvedOptions.envFilePath,
+            imageTag,
+            invocation,
+            outputDirectory: buildResult.outputDirectory,
+            report: buildResult.report,
+            runMetadata: runMetadata ?? undefined,
+            targetExecFile: options.targetExecFile
+        })
+        : null;
     return {
         ...buildResult,
         authProfileName: authProfile?.name ?? null,
         containerName: invocation.containerName,
+        deploymentRecordPath,
+        imageTag,
         supportDirectory: invocation.supportDirectory
     };
 };

package/dist/compiler/view/buildOrganizationView.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { SpawnfileError } from "../../shared/index.js";
 import { buildCompilePlan } from "../buildCompilePlan.js";
 import { resolveMoltnetRoomMemberships } from "../moltnetRoomMemberships.js";
+import { buildDeclaredNodeView, buildRuntimeViews } from "./declarations.js";
 const createNameCounts = (plan) => {
     const counts = new Map();
     for (const node of plan.nodes) {
@@ -82,7 +83,9 @@ const buildTreeNode = (node, nodeById, edgesBySource, nameCounts, ancestors = []
         kind: node.kind,
         name: node.value.name,
         networks: buildTreeNetworkSummaries(node),
+        declared: buildDeclaredNodeView(node),
         runtimeName: node.runtimeName,
+        slug: node.slug,
         source: node.value.source
     };
 };
@@ -219,6 +222,6 @@ export const buildOrganizationView = async (inputPath) => {
         networks: buildNetworks(plan),
         projectRoot: path.dirname(plan.root),
         root,
-        runtimes: []
+        runtimes: buildRuntimeViews(plan)
     };
 };

package/dist/compiler/view/declarations.d.ts

@@ -0,0 +1,4 @@
+import type { CompilePlan, CompilePlanNode } from "../types.js";
+import type { OrganizationRuntimeView, OrganizationViewDeclaredSummary } from "./types.js";
+export declare const buildDeclaredNodeView: (node: CompilePlanNode) => OrganizationViewDeclaredSummary;
+export declare const buildRuntimeViews: (plan: CompilePlan) => OrganizationRuntimeView[];

package/dist/compiler/view/declarations.js

@@ -0,0 +1,104 @@
+import { resolveEffectiveModelTarget } from "../modelEnv.js";
+import { listInteractiveSurfaceScopes } from "../interactiveSurfaceScopes.js";
+const summarizeModel = (node) => {
+    if (node.value.kind !== "agent" || !node.value.execution?.model?.primary) {
+        return null;
+    }
+    const target = resolveEffectiveModelTarget(node.value.execution.model.primary, node.value.execution);
+    return {
+        authMethod: target.auth.method,
+        name: target.name,
+        provider: target.provider
+    };
+};
+const summarizeSchedule = (node) => {
+    if (node.value.kind !== "agent" || !node.value.schedule) {
+        return null;
+    }
+    const schedule = node.value.schedule;
+    if (schedule.kind === "cron") {
+        return {
+            expression: schedule.cron,
+            kind: schedule.kind,
+            ...(schedule.timezone ? { timezone: schedule.timezone } : {})
+        };
+    }
+    if (schedule.kind === "every") {
+        return {
+            expression: schedule.every,
+            kind: schedule.kind,
+            ...(schedule.timezone ? { timezone: schedule.timezone } : {})
+        };
+    }
+    return { kind: schedule.kind };
+};
+const surfaceSummaryFor = (name, surfaces) => {
+    if (!surfaces[name]) {
+        return null;
+    }
+    const scopes = name === "moltnet"
+        ? listInteractiveSurfaceScopes(surfaces).filter((scope) => scope.startsWith("moltnet:"))
+        : listInteractiveSurfaceScopes(surfaces).filter((scope) => scope === name);
+    return {
+        name,
+        scopes: scopes.length > 0 ? scopes : [name]
+    };
+};
+const summarizeSurfaces = (node) => {
+    const surfaces = node.value.kind === "agent" ? node.value.surfaces : undefined;
+    if (!surfaces) {
+        return [];
+    }
+    return ["discord", "http", "moltnet", "slack", "telegram", "webhook", "whatsapp"]
+        .map((name) => surfaceSummaryFor(name, surfaces))
+        .filter((surface) => surface !== null);
+};
+const summarizePackages = (node) => {
+    const packages = node.value.kind === "agent"
+        ? node.value.packages ?? []
+        : node.value.shared.packages ?? [];
+    return packages.map((pkg) => ({
+        id: pkg.id,
+        manager: pkg.manager,
+        name: pkg.name,
+        ...(pkg.scope ? { scope: pkg.scope } : {}),
+        ...(pkg.version ? { version: pkg.version } : {})
+    }));
+};
+const summarizeResources = (node) => (node.value.workspaceResources ?? []).map((resource) => ({
+    id: resource.id,
+    kind: resource.kind,
+    mode: resource.mode,
+    mount: resource.mount,
+    sharing: resource.sharing
+}));
+export const buildDeclaredNodeView = (node) => {
+    const skills = node.value.kind === "agent" ? node.value.skills : node.value.shared.skills;
+    const mcpServers = node.value.kind === "agent"
+        ? node.value.mcpServers
+        : node.value.shared.mcpServers;
+    return {
+        docs: node.value.docs.map((doc) => ({ role: doc.role, source: doc.sourcePath })),
+        mcpServers: mcpServers.map((server) => ({
+            name: server.name,
+            transport: server.transport
+        })),
+        model: summarizeModel(node),
+        packages: summarizePackages(node),
+        policy: {
+            mode: node.value.policyMode,
+            onDegrade: node.value.policyOnDegrade
+        },
+        resources: summarizeResources(node),
+        schedule: summarizeSchedule(node),
+        skills: skills.map((skill) => ({
+            name: skill.name,
+            ref: skill.ref,
+            requiresMcp: [...skill.requiresMcp]
+        })),
+        surfaces: summarizeSurfaces(node)
+    };
+};
+export const buildRuntimeViews = (plan) => Object.entries(plan.runtimes)
+    .map(([name, runtime]) => ({ name, nodeIds: [...runtime.nodeIds].sort() }))
+    .sort((left, right) => left.name.localeCompare(right.name));

package/dist/compiler/view/renderNetworks.js

@@ -8,8 +8,7 @@ const formatPolicy = (member) => {
         return [];
     }
     return [
-        member.policy.read ? `read=${member.policy.read}` : undefined,
-        member.policy.reply ? `reply=${member.policy.reply}` : undefined
+        member.policy.wake ? `wake=${member.policy.wake}` : undefined
     ].filter((entry) => entry !== undefined);
 };
 const formatMember = (member, options, projectRoot) => {

package/dist/compiler/view/renderTree.js

@@ -1,5 +1,9 @@
 import { formatSourceMeta } from "./sourcePaths.js";
 const color = (value, code, options) => options.color ? `\u001b[${code}m${value}\u001b[0m` : value;
+const formatAnnotations = (subjectKey, options) => {
+    const annotations = options.annotationFor?.(subjectKey) ?? [];
+    return annotations.length > 0 ? `  ${annotations.join(" ")}` : "";
+};
 const formatNode = (node, options, projectRoot) => {
     const kind = color(node.kind, node.kind === "team" ? "36" : "32", options);
     const metadata = node.kind === "team"
@@ -17,7 +21,7 @@ const formatNode = (node, options, projectRoot) => {
     const details = metadata.filter((entry) => entry !== undefined);
     const source = options.paths ? formatSourceMeta("source", node.source, projectRoot) : "";
     const separator = details[0]?.startsWith("[") ? " " : "  ";
-    return `${kind} ${node.displayName}${details.length > 0 ? `${separator}${details.join(" ")}` : ""}${source}`;
+    return `${kind} ${node.displayName}${details.length > 0 ? `${separator}${details.join(" ")}` : ""}${source}${formatAnnotations(node.id, options)}`;
 };
 const formatEdgeLabel = (edge) => edge.relation === "subagent"
     ? `subagent ${edge.label}`
@@ -44,7 +48,7 @@ const formatNetworkSummary = (network, options) => {
         return `${room.id}${roomMetadata.length > 0 ? ` ${roomMetadata.join(" ")}` : ""} [${room.declaredMembers.join(", ")}]`;
     })
         .join("; ");
-    return `network ${id} "${network.name}"${metadata.length > 0 ? ` ${metadata.join(" ")}` : ""}: ${rooms}`;
+    return `network ${id} "${network.name}"${metadata.length > 0 ? ` ${metadata.join(" ")}` : ""}: ${rooms}${formatAnnotations(`network:${network.id}`, options)}`;
 };
 const renderChildren = (node, options, projectRoot, prefix = "") => {
     const glyphs = options.ascii

package/dist/compiler/view/types.d.ts

@@ -1,6 +1,63 @@
 import type { ResolvedMoltnetRoomPolicy } from "../types.js";
+export interface OrganizationViewDocSummary {
+    role: string;
+    source: string;
+}
+export interface OrganizationViewSkillSummary {
+    name: string;
+    ref: string;
+    requiresMcp: string[];
+}
+export interface OrganizationViewResourceSummary {
+    id: string;
+    kind: "git" | "volume";
+    mode: "mutable" | "readonly";
+    mount: string;
+    sharing: "per_agent" | "team";
+}
+export interface OrganizationViewPackageSummary {
+    id: string;
+    manager: string;
+    name: string;
+    scope?: string;
+    version?: string;
+}
+export interface OrganizationViewMcpSummary {
+    name: string;
+    transport: "sse" | "stdio" | "streamable_http";
+}
+export interface OrganizationViewModelSummary {
+    authMethod: string;
+    name: string;
+    provider: string;
+}
+export interface OrganizationViewScheduleSummary {
+    expression?: string;
+    kind: "cron" | "disabled" | "every";
+    timezone?: string;
+}
+export interface OrganizationViewSurfaceSummary {
+    name: string;
+    scopes: string[];
+}
+export interface OrganizationViewPolicySummary {
+    mode: string | null;
+    onDegrade: string | null;
+}
+export interface OrganizationViewDeclaredSummary {
+    docs: OrganizationViewDocSummary[];
+    mcpServers: OrganizationViewMcpSummary[];
+    model: OrganizationViewModelSummary | null;
+    packages: OrganizationViewPackageSummary[];
+    policy: OrganizationViewPolicySummary;
+    resources: OrganizationViewResourceSummary[];
+    schedule: OrganizationViewScheduleSummary | null;
+    skills: OrganizationViewSkillSummary[];
+    surfaces: OrganizationViewSurfaceSummary[];
+}
 export interface OrganizationViewTreeNode {
     children: OrganizationViewTreeEdge[];
+    declared?: OrganizationViewDeclaredSummary;
     displayName: string;
     external?: string[];
     id: string;
@@ -10,6 +67,7 @@ export interface OrganizationViewTreeNode {
     name: string;
     networks?: OrganizationTreeNetworkSummary[];
     runtimeName: string | null;
+    slug?: string;
     source: string;
 }
 export interface OrganizationTreeNetworkRoomSummary {
@@ -94,6 +152,10 @@ export interface OrganizationNetworkView {
     url?: string;
     declarations?: OrganizationNetworkDeclarationView[];
 }
+export interface OrganizationRuntimeView {
+    name: string;
+    nodeIds: string[];
+}
 export interface OrganizationView {
     contexts: [];
     diagnostics: [];
@@ -101,9 +163,10 @@ export interface OrganizationView {
     networks: OrganizationNetworkView[];
     projectRoot?: string;
     root: OrganizationViewTreeNode;
-    runtimes: [];
+    runtimes: OrganizationRuntimeView[];
 }
 export interface RenderOrganizationViewOptions {
+    annotationFor?: (subjectKey: string) => string[];
     ascii?: boolean;
     color?: boolean;
     declared?: boolean;

package/dist/deployment/dockerInspect.d.ts

@@ -0,0 +1,29 @@
+import type { DeploymentRecord } from "./record.js";
+export type DockerInspectExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface DockerUnitInspection {
+    containerId: string | null;
+    drift: string[];
+    exists: boolean | null;
+    exitCode: number | null;
+    finishedAt: string | null;
+    imageId: string | null;
+    message: string;
+    restartCount: number | null;
+    running: boolean | null;
+    severity: "error" | "ok" | "unknown" | "warn";
+    startedAt: string | null;
+    status: string | null;
+    unitId: string;
+}
+export type DockerInspectionResult = Map<string, DockerUnitInspection>;
+export interface DockerInspectOptions {
+    dockerCommand?: string;
+    execFile?: DockerInspectExecFile;
+    timeoutMs?: number;
+}
+export declare const inspectDockerDeployment: (record: DeploymentRecord, options?: DockerInspectOptions) => Promise<DockerInspectionResult>;

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