spawnfile 0.1.11 → 0.1.13

package/dist/status/deploymentLogs.js

@@ -0,0 +1,45 @@
+import { readDockerDeploymentLogs } from "../deployment/index.js";
+const createObservation = (input) => ({
+    ...input,
+    label: `${input.severity.toUpperCase()} ${input.key}`,
+    source: "deployment"
+});
+const secretValuesFor = (loadedReport) => {
+    if (loadedReport.kind !== "loaded") {
+        return [];
+    }
+    return (loadedReport.report.secretsRequired ?? [])
+        .map((secretName) => process.env[secretName])
+        .filter((value) => typeof value === "string" && value.length > 0);
+};
+const normalizeFailureSeverity = (severity) => severity === "error" ? "unknown" : severity;
+export const collectDeploymentLogObservations = async (options) => {
+    const secretValues = secretValuesFor(options.loadedReport);
+    const observations = [];
+    for (const deployment of options.deployments) {
+        const logs = await readDockerDeploymentLogs(deployment, {
+            dockerCommand: options.dockerCommand,
+            execFile: options.execFile,
+            secretValues,
+            tail: options.tail,
+            timeoutMs: options.timeoutMs
+        });
+        for (const unit of deployment.units) {
+            const unitLogs = logs.get(unit.id);
+            if (!unitLogs) {
+                continue;
+            }
+            observations.push(createObservation({
+                details: {
+                    container_ref: unitLogs.containerRef,
+                    log_tail: unitLogs.text
+                },
+                key: "deployment.logs",
+                message: `${deployment.name}/${unit.id}: ${unitLogs.message}`,
+                severity: normalizeFailureSeverity(unitLogs.severity),
+                subject: `deployment-unit:${deployment.name}:${unit.id}`
+            }));
+        }
+    }
+    return observations;
+};

package/dist/status/deployments.d.ts

@@ -0,0 +1,14 @@
+import type { DeploymentRecord, DockerInspectionResult } from "../deployment/index.js";
+import type { StatusDeploymentSummary, StatusObservation } from "./types.js";
+export interface LoadedDeploymentRecord {
+    path: string;
+    record: DeploymentRecord;
+}
+export type StatusDeploymentInspections = Map<string, DockerInspectionResult>;
+export declare const createDeploymentSummaries: (records: LoadedDeploymentRecord[], inspections?: StatusDeploymentInspections) => StatusDeploymentSummary[];
+export declare const createDeploymentObservations: (deployments: StatusDeploymentSummary[], options: {
+    compileFingerprint: string | null;
+    liveRequested: boolean;
+    outputDirectory: string;
+    recover: boolean;
+}) => StatusObservation[];

package/dist/status/deployments.js

@@ -0,0 +1,121 @@
+const createObservation = (input) => ({
+    ...input,
+    label: `${input.severity.toUpperCase()} ${input.key}`
+});
+const targetLabelFor = (record) => record.target.kind === "context"
+    ? `docker context ${record.target.name}`
+    : record.target.kind === "docker-context"
+        ? `docker context ${record.target.context}`
+        : "docker host";
+const liveForInspection = (inspection) => {
+    if (!inspection) {
+        return null;
+    }
+    return {
+        checked: true,
+        containerId: inspection.containerId,
+        drift: [...inspection.drift],
+        exists: inspection.exists,
+        exitCode: inspection.exitCode,
+        finishedAt: inspection.finishedAt,
+        imageId: inspection.imageId,
+        message: inspection.message,
+        restartCount: inspection.restartCount,
+        running: inspection.running,
+        severity: inspection.severity,
+        startedAt: inspection.startedAt,
+        status: inspection.status
+    };
+};
+const unitSeverity = (live) => {
+    if (!live) {
+        return "ok";
+    }
+    if (live.severity !== "ok") {
+        return live.severity;
+    }
+    if (live.running === true) {
+        return "ok";
+    }
+    if (live.exists === false) {
+        return "warn";
+    }
+    if (live.running === false) {
+        return "error";
+    }
+    return "unknown";
+};
+const summarizeUnit = (unit, live) => ({
+    containerId: unit.container_id,
+    containerName: unit.container_name,
+    contains: unit.contains.map((entry) => ({ id: entry.id, kind: entry.kind })),
+    id: unit.id,
+    imageId: unit.image_id,
+    imageTag: unit.image_tag,
+    kind: unit.kind,
+    live,
+    runtimeInstances: [...unit.runtime_instances]
+});
+export const createDeploymentSummaries = (records, inspections = new Map()) => records.map(({ path, record }) => ({
+    authProfile: record.auth_profile,
+    compileFingerprint: record.compile_fingerprint,
+    createdAt: record.created_at,
+    manager: record.manager,
+    name: record.name,
+    recordPath: path,
+    target: targetLabelFor(record),
+    units: record.units.map((unit) => summarizeUnit(unit, liveForInspection(inspections.get(record.name)?.get(unit.id))))
+}));
+export const createDeploymentObservations = (deployments, options) => {
+    const observations = [];
+    if (deployments.length === 0 && options.liveRequested) {
+        observations.push(createObservation({
+            key: options.recover ? "deployment.recover" : "deployment.record",
+            message: options.recover
+                ? `No recoverable deployment labels found for ${options.outputDirectory}`
+                : `No deployment records found under ${options.outputDirectory}`,
+            severity: "warn",
+            source: "deployment",
+            subject: "deployment"
+        }));
+    }
+    for (const deployment of deployments) {
+        observations.push(createObservation({
+            key: "deployment.record",
+            message: `${deployment.name} record exists at ${deployment.recordPath}`,
+            severity: "ok",
+            source: "deployment",
+            subject: `deployment:${deployment.name}`
+        }));
+        if (options.compileFingerprint && deployment.compileFingerprint !== options.compileFingerprint) {
+            observations.push(createObservation({
+                key: "deployment.compile_fingerprint",
+                message: `${deployment.name} was deployed from ${deployment.compileFingerprint}, current compile is ${options.compileFingerprint}`,
+                severity: "warn",
+                source: "deployment",
+                subject: `deployment:${deployment.name}`
+            }));
+        }
+        for (const unit of deployment.units) {
+            const severity = unitSeverity(unit.live);
+            const unitSubject = `deployment-unit:${deployment.name}:${unit.id}`;
+            observations.push(createObservation({
+                key: "deployment.unit",
+                message: unit.live?.message ?? `${unit.id} recorded for ${deployment.target}`,
+                severity,
+                source: "deployment",
+                subject: unitSubject
+            }));
+            for (const entry of unit.contains) {
+                observations.push(createObservation({
+                    key: "deployment.hosting",
+                    message: `${entry.id} is hosted by ${deployment.name}/${unit.id}`,
+                    severity,
+                    source: "deployment",
+                    subject: entry.id
+                }));
+            }
+        }
+    }
+    return observations;
+};

package/dist/status/imageStatusReport.d.ts

@@ -0,0 +1,10 @@
+import type { DistributionReport } from "../distribution/index.js";
+import type { LoadedCompileReport, StatusReport } from "./compileReport.js";
+/**
+ * Maps a cached distribution report (from a sourceless image deployment) into
+ * the StatusReport shape so live status can render the compiled, deployment,
+ * and runtime layers without project source. Moltnet server plans are not part
+ * of the distribution report, so the network layer falls back to `unknown`.
+ */
+export declare const distributionReportToStatusReport: (report: DistributionReport, reportPath: string) => StatusReport;
+export declare const loadedImageCompileReport: (report: DistributionReport, reportPath: string) => LoadedCompileReport;

package/dist/status/imageStatusReport.js

@@ -0,0 +1,73 @@
+/**
+ * Maps a cached distribution report (from a sourceless image deployment) into
+ * the StatusReport shape so live status can render the compiled, deployment,
+ * and runtime layers without project source. Moltnet server plans are not part
+ * of the distribution report, so the network layer falls back to `unknown`.
+ */
+export const distributionReportToStatusReport = (report, reportPath) => ({
+    compileFingerprint: report.compile_fingerprint,
+    generatedAt: report.generated_at,
+    internalPorts: report.internal_ports,
+    moltnetServers: [],
+    nodes: [
+        ...report.organization.agents.map((agent) => ({
+            capabilities: [],
+            diagnostics: [],
+            id: agent.id,
+            kind: "agent",
+            outputDir: null,
+            runtime: agent.runtime
+        })),
+        ...report.organization.teams.map((team) => ({
+            capabilities: [],
+            diagnostics: [],
+            id: team.id,
+            kind: "team",
+            outputDir: null,
+            runtime: null
+        }))
+    ],
+    outputDirectory: null,
+    persistentMounts: report.persistent_mounts.map((mount) => ({
+        id: mount.id,
+        mountPath: mount.target,
+        reason: "image persistent mount",
+        volumeName: ""
+    })),
+    portMappings: report.port_mappings.map((mapping) => ({
+        internalPort: mapping.internal_port,
+        publishedPort: mapping.published_port
+    })),
+    publishedPorts: report.ports,
+    reportPath,
+    root: null,
+    runtimeInstances: report.runtime_instances.map((instance) => ({
+        configPath: instance.config_path,
+        homePath: instance.home_path,
+        id: instance.id,
+        internalPort: instance.internal_port,
+        nodeIds: instance.node_ids,
+        publishedPort: instance.published_port,
+        runtime: instance.runtime,
+        workspacePath: instance.workspace_path
+    })),
+    secretsRequired: [
+        ...new Set(["model", "project", "runtime", "surface"].flatMap((category) => report.secrets[category]
+            .filter((entry) => entry.required && !entry.generated)
+            .map((entry) => entry.name)))
+    ].sort(),
+    workspaceResources: report.resources.map((resource) => ({
+        backingPath: "",
+        id: resource.id,
+        kind: resource.kind,
+        linkPath: resource.link_path,
+        mode: resource.mode,
+        mount: resource.mount,
+        sharing: resource.sharing
+    }))
+});
+export const loadedImageCompileReport = (report, reportPath) => ({
+    kind: "loaded",
+    report: distributionReportToStatusReport(report, reportPath),
+    reportPath
+});

package/dist/status/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./buildStatus.js";
+export * from "./compiledContainerObservations.js";
+export * from "./compileReport.js";
+export * from "./deploymentLogs.js";
+export * from "./deployments.js";
+export * from "./moltnetProbes.js";
+export * from "./renderStatus.js";
+export * from "./runtimeProbes.js";
+export * from "./selectionSubjects.js";
+export * from "./selectors.js";
+export * from "./traversal.js";
+export * from "./types.js";
+export * from "./imageStatusReport.js";
+export * from "./registryDrift.js";

package/dist/status/index.js

@@ -0,0 +1,14 @@
+export * from "./buildStatus.js";
+export * from "./compiledContainerObservations.js";
+export * from "./compileReport.js";
+export * from "./deploymentLogs.js";
+export * from "./deployments.js";
+export * from "./moltnetProbes.js";
+export * from "./renderStatus.js";
+export * from "./runtimeProbes.js";
+export * from "./selectionSubjects.js";
+export * from "./selectors.js";
+export * from "./traversal.js";
+export * from "./types.js";
+export * from "./imageStatusReport.js";
+export * from "./registryDrift.js";

package/dist/status/moltnetProbes.d.ts

@@ -0,0 +1,21 @@
+import type { DeploymentRecord, DockerInspectionResult, DockerProbeExecFile } from "../deployment/index.js";
+import type { LoadedCompileReport } from "./compileReport.js";
+import type { StatusObservation } from "./types.js";
+export type StatusNetworkInspections = Map<string, DockerInspectionResult>;
+export interface CollectMoltnetProbeOptions {
+    authValues?: Record<string, string>;
+    deployments: DeploymentRecord[];
+    execFile?: DockerProbeExecFile;
+    fetchJson?: MoltnetFetchJson;
+    inspections: StatusNetworkInspections;
+    loadedReport: LoadedCompileReport;
+    timeoutMs?: number;
+}
+export type MoltnetFetchJson = (url: string, headers: Record<string, string>, timeoutMs: number) => Promise<MoltnetProbeResponse>;
+interface MoltnetProbeResponse {
+    error?: string;
+    json: unknown;
+    ok: boolean;
+}
+export declare const collectMoltnetProbeObservations: (options: CollectMoltnetProbeOptions) => Promise<StatusObservation[]>;
+export {};

package/dist/status/moltnetProbes.js

@@ -0,0 +1,240 @@
+import { createDockerProbeGateway } from "../deployment/index.js";
+const createObservation = (input) => ({
+    ...input,
+    label: `${input.severity.toUpperCase()} ${input.key}`,
+    source: "network"
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const toString = (value) => typeof value === "string" ? value : null;
+const toStringArray = (value) => Array.isArray(value)
+    ? value.filter((entry) => typeof entry === "string")
+    : [];
+const parseRooms = (value) => {
+    const entries = isRecord(value) && Array.isArray(value.rooms) ? value.rooms : [];
+    return entries.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const id = toString(entry.id);
+        return id ? [{ id, members: toStringArray(entry.members) }] : [];
+    });
+};
+const parseAgents = (value) => {
+    const entries = isRecord(value) && Array.isArray(value.agents) ? value.agents : [];
+    return entries.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const id = toString(entry.id);
+        return id
+            ? [{ connected: entry.connected === true, id, rooms: toStringArray(entry.rooms) }]
+            : [];
+    });
+};
+const parseNetwork = (value) => ({
+    directMessages: isRecord(value) && isRecord(value.capabilities) && typeof value.capabilities.direct_messages === "boolean"
+        ? value.capabilities.direct_messages
+        : null,
+    networkId: isRecord(value) ? toString(value.id) : null
+});
+const defaultFetchJson = async (url, headers, timeoutMs) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { headers, signal: controller.signal });
+        if (!response.ok) {
+            return { error: `HTTP ${response.status}`, json: null, ok: false };
+        }
+        return { json: await response.json(), ok: true };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error), json: null, ok: false };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+const authHeadersFor = (server, authValues = {}) => {
+    if (!server.operatorTokenSecret) {
+        return {};
+    }
+    const token = authValues[server.operatorTokenSecret] ?? process.env[server.operatorTokenSecret];
+    return token ? { Authorization: `Bearer ${token}` } : null;
+};
+const readManagedJson = async (gateway, server, path, headers) => {
+    if (!server.port) {
+        return { error: "managed Moltnet server has no internal port", json: null, ok: false };
+    }
+    const response = await gateway.httpGet(server.port, path, headers);
+    if (!response.ok) {
+        return { error: response.error, json: null, ok: false };
+    }
+    try {
+        return { json: JSON.parse(response.body), ok: true };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error), json: null, ok: false };
+    }
+};
+const readExternalJson = async (fetchJson, server, path, headers, timeoutMs) => fetchJson(`${server.baseUrl.replace(/\/$/u, "")}${path}`, headers, timeoutMs);
+const createManagedGateway = (deployments, inspections, options) => {
+    for (const deployment of deployments) {
+        const inspectionMap = inspections.get(deployment.name);
+        const unit = deployment.units[0];
+        if (!unit)
+            continue;
+        const inspection = inspectionMap?.get(unit.id);
+        if (inspection?.running === true) {
+            return createDockerProbeGateway(deployment, unit, {
+                execFile: options.execFile,
+                inspection,
+                timeoutMs: options.timeoutMs
+            });
+        }
+    }
+    return null;
+};
+const readSnapshot = async (server, options, headers) => {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const gateway = server.mode === "managed"
+        ? createManagedGateway(options.deployments, options.inspections, options)
+        : null;
+    if (server.mode === "managed" && !gateway) {
+        return { error: "no running deployment unit hosts the managed Moltnet server", json: null, ok: false };
+    }
+    const readJson = (path) => gateway
+        ? readManagedJson(gateway, server, path, headers)
+        : readExternalJson(options.fetchJson ?? defaultFetchJson, server, path, headers, timeoutMs);
+    const health = await readJson("/healthz");
+    if (!health.ok)
+        return health;
+    const network = await readJson("/v1/network");
+    if (!network.ok)
+        return network;
+    const rooms = await readJson("/v1/rooms");
+    if (!rooms.ok)
+        return rooms;
+    const agents = await readJson("/v1/agents");
+    if (!agents.ok)
+        return agents;
+    const parsedNetwork = parseNetwork(network.json);
+    return {
+        json: null,
+        ok: true,
+        snapshot: {
+            agents: parseAgents(agents.json),
+            directMessages: parsedNetwork.directMessages,
+            networkId: parsedNetwork.networkId,
+            rooms: parseRooms(rooms.json)
+        }
+    };
+};
+const compareSnapshot = (server, snapshot) => {
+    const observations = [];
+    observations.push(createObservation({
+        key: "network.reachable",
+        message: `${server.networkId} Moltnet server is reachable`,
+        severity: "ok",
+        subject: `network:${server.networkId}`
+    }));
+    if (snapshot.networkId && snapshot.networkId !== server.networkId) {
+        observations.push(createObservation({
+            key: "network.id",
+            message: `expected network ${server.networkId}, live network is ${snapshot.networkId}`,
+            severity: "error",
+            subject: `network:${server.networkId}`
+        }));
+    }
+    const liveRooms = new Map(snapshot.rooms.map((room) => [room.id, room]));
+    const liveAgents = new Map(snapshot.agents.map((agent) => [agent.id, agent]));
+    for (const room of server.rooms) {
+        const liveRoom = liveRooms.get(room.id);
+        if (!liveRoom) {
+            observations.push(createObservation({
+                key: "network.room",
+                message: `${server.networkId}/${room.id} is missing from live Moltnet`,
+                severity: "error",
+                subject: `room:${server.networkId}:${room.id}`
+            }));
+            continue;
+        }
+        observations.push(createObservation({
+            key: "network.room",
+            message: `${server.networkId}/${room.id} exists with ${liveRoom.members.length} member(s)`,
+            severity: "ok",
+            subject: `room:${server.networkId}:${room.id}`
+        }));
+        for (const member of room.members) {
+            const liveAgent = liveAgents.get(member);
+            if (!liveAgent) {
+                observations.push(createObservation({
+                    key: "network.member",
+                    message: `${member} is expected in ${room.id} but is not registered`,
+                    severity: "warn",
+                    subject: `agent:${member}`
+                }));
+            }
+            else if (!liveAgent.rooms.includes(room.id)) {
+                observations.push(createObservation({
+                    key: "network.member",
+                    message: `${member} is registered but not attached to ${room.id}`,
+                    severity: "warn",
+                    subject: `agent:${member}`
+                }));
+            }
+            else if (!liveAgent.connected) {
+                observations.push(createObservation({
+                    key: "network.agent.connected",
+                    message: `${member} is attached to ${room.id} but disconnected`,
+                    severity: "warn",
+                    subject: `agent:${member}`
+                }));
+            }
+            else {
+                observations.push(createObservation({
+                    key: "network.agent.connected",
+                    message: `${member} is connected to ${room.id}`,
+                    severity: "ok",
+                    subject: `agent:${member}`
+                }));
+            }
+        }
+    }
+    if (snapshot.directMessages !== null && server.directMessages !== null && snapshot.directMessages !== server.directMessages) {
+        observations.push(createObservation({
+            key: "network.direct_messages",
+            message: `direct messages expected ${server.directMessages}, live value is ${snapshot.directMessages}`,
+            severity: "warn",
+            subject: `network:${server.networkId}`
+        }));
+    }
+    return observations;
+};
+export const collectMoltnetProbeObservations = async (options) => {
+    if (options.loadedReport.kind !== "loaded") {
+        return [];
+    }
+    const observations = [];
+    for (const server of options.loadedReport.report.moltnetServers ?? []) {
+        const headers = authHeadersFor(server, options.authValues);
+        if (headers === null) {
+            observations.push(createObservation({
+                key: "network.auth",
+                message: `${server.networkId} requires operator token ${server.operatorTokenSecret}, but no value is available`,
+                severity: "unknown",
+                subject: `network:${server.networkId}`
+            }));
+            continue;
+        }
+        const response = await readSnapshot(server, options, headers);
+        if (!response.ok || !response.snapshot) {
+            observations.push(createObservation({
+                key: "network.reachable",
+                message: `${server.networkId} Moltnet metadata probe failed: ${response.error ?? "unknown failure"}`,
+                severity: "unknown",
+                subject: `network:${server.networkId}`
+            }));
+            continue;
+        }
+        observations.push(...compareSnapshot(server, response.snapshot));
+    }
+    return observations;
+};

package/dist/status/registryDrift.d.ts

@@ -0,0 +1,28 @@
+import { type DeploymentRecord } from "../deployment/index.js";
+import type { StatusObservation } from "./types.js";
+export type RegistryDigestResolver = (imageRef: string, baseArgs: string[]) => Promise<string | null>;
+export interface RegistryDriftInput {
+    deployments: DeploymentRecord[];
+    dockerCommand?: string;
+    resolveDigest?: RegistryDigestResolver;
+    timeoutMs?: number;
+}
+/**
+ * Extracts the comparable digest from `docker manifest inspect --verbose` output.
+ *
+ * A single-arch tag resolves to one manifest object whose `Descriptor.digest`
+ * equals the digest RepoDigests records at deploy time. A multi-arch tag resolves
+ * to a JSON ARRAY of per-platform manifests; each `Descriptor.digest` is a CHILD
+ * digest, never the manifest-list (index) digest that was recorded — comparing one
+ * would report drift on every check. We cannot derive the index digest from this
+ * command, so multi-arch (and any unparseable output) yields null → "unknown"
+ * rather than a false positive.
+ */
+export declare const parseManifestInspectDigest: (output: string) => string | null;
+/**
+ * Compares each image deployment's recorded source.digest against the digest
+ * the registry tag currently resolves to. Networked: runs only behind the
+ * explicit --pull-check flag. A digest-pinned ref needs no lookup; a null
+ * recorded digest renders unknown.
+ */
+export declare const collectRegistryDriftObservations: (input: RegistryDriftInput) => Promise<StatusObservation[]>;