spawnfile 0.1.11 → 0.1.12

package/dist/status/buildStatus.js

@@ -0,0 +1,266 @@
+import path from "node:path";
+import { createCompiledContainerObservations } from "./compiledContainerObservations.js";
+import { createDeploymentObservations } from "./deployments.js";
+import { expandStatusSelectionSubjects } from "./selectionSubjects.js";
+import { countNodesByKind, flattenOrganizationNodes } from "./traversal.js";
+export const countObservations = (observations) => ({
+    error: observations.filter((observation) => observation.severity === "error").length,
+    ok: observations.filter((observation) => observation.severity === "ok").length,
+    unknown: observations.filter((observation) => observation.severity === "unknown").length,
+    warn: observations.filter((observation) => observation.severity === "warn").length
+});
+export const getVisibleObservations = (status) => {
+    if (!status.selection) {
+        return status.observations;
+    }
+    const subjects = new Set(["compile", "status", ...status.selection.subjectKeys]);
+    return status.observations.filter((observation) => subjects.has(observation.subject));
+};
+export const exitCodeForStatus = (status) => getVisibleObservations(status).some((observation) => observation.severity === "error")
+    ? 1
+    : 0;
+const severityForDiagnostic = (diagnostic) => diagnostic.level === "error" ? "error" : diagnostic.level === "warn" ? "warn" : "ok";
+const severityForCapability = (capability) => capability.outcome === "unsupported"
+    ? "error"
+    : capability.outcome === "degraded"
+        ? "warn"
+        : "ok";
+const createNodeReportObservations = (node) => {
+    const observations = [];
+    for (const diagnostic of node.diagnostics) {
+        observations.push({
+            key: `diagnostic.${diagnostic.level}`,
+            label: node.id,
+            message: diagnostic.message,
+            severity: severityForDiagnostic(diagnostic),
+            source: "compile_report",
+            subject: node.id
+        });
+    }
+    for (const capability of node.capabilities) {
+        const severity = severityForCapability(capability);
+        if (severity === "ok") {
+            continue;
+        }
+        observations.push({
+            key: `capability.${capability.key}`,
+            label: node.id,
+            message: capability.message,
+            severity,
+            source: "compile_report",
+            subject: node.id
+        });
+    }
+    return observations;
+};
+const createObservation = (input) => ({
+    ...input,
+    label: `${input.severity.toUpperCase()} ${input.key}`
+});
+const compileInfoFor = (loaded) => {
+    if (loaded.kind !== "loaded") {
+        return {
+            compileFingerprint: null,
+            generatedAt: null,
+            outputDirectory: null,
+            path: loaded.reportPath,
+            present: false,
+            root: null
+        };
+    }
+    return {
+        compileFingerprint: loaded.report.compileFingerprint,
+        generatedAt: loaded.report.generatedAt,
+        outputDirectory: loaded.report.outputDirectory,
+        path: loaded.reportPath,
+        present: true,
+        root: loaded.report.root
+    };
+};
+const addDeclaredObservations = (observations, view, nodes) => {
+    observations.push(createObservation({
+        key: "source.valid",
+        message: `Loaded organization graph from ${view.root.source}`,
+        severity: "ok",
+        source: "declared",
+        subject: "status"
+    }));
+    for (const node of nodes) {
+        observations.push(createObservation({
+            key: `${node.kind}.declared`,
+            message: `${node.displayName} is declared`,
+            severity: "ok",
+            source: "declared",
+            subject: node.id
+        }));
+    }
+    for (const network of view.networks) {
+        observations.push(createObservation({
+            key: "network.declared",
+            message: `${network.id} declares ${network.rooms.length} room(s)`,
+            severity: "ok",
+            source: "declared",
+            subject: `network:${network.id}`
+        }));
+    }
+    for (const runtime of view.runtimes) {
+        observations.push(createObservation({
+            key: "runtime.declared",
+            message: `${runtime.name} serves ${runtime.nodeIds.length} node(s)`,
+            severity: "ok",
+            source: "declared",
+            subject: `runtime:${runtime.name}`
+        }));
+    }
+};
+const addCompiledObservations = (observations, loaded, view, nodes) => {
+    if (loaded.kind === "missing") {
+        observations.push(createObservation({
+            key: "compile.report",
+            message: `Compile report not found at ${loaded.reportPath}`,
+            severity: "unknown",
+            source: "compile_report",
+            subject: "compile"
+        }));
+        return;
+    }
+    if (loaded.kind === "failure") {
+        observations.push(createObservation({
+            key: "compile.report",
+            message: loaded.failure.message,
+            severity: "error",
+            source: "input",
+            subject: "compile"
+        }));
+        return;
+    }
+    observations.push(createObservation({
+        key: "compile.report",
+        message: `Loaded compile report ${loaded.report.reportPath}`,
+        severity: "ok",
+        source: "compile_report",
+        subject: "compile"
+    }));
+    observations.push(createObservation({
+        key: "compile.fingerprint",
+        message: loaded.report.compileFingerprint
+            ? `Compile fingerprint ${loaded.report.compileFingerprint}`
+            : "Compile report has no compile_fingerprint yet",
+        severity: loaded.report.compileFingerprint ? "ok" : "unknown",
+        source: "compile_report",
+        subject: "compile"
+    }));
+    observations.push(...createCompiledContainerObservations(loaded));
+    if (loaded.report.root && path.resolve(loaded.report.root) !== path.resolve(view.root.source)) {
+        observations.push(createObservation({
+            key: "compile.root",
+            message: `Compile report root ${loaded.report.root} differs from source ${view.root.source}`,
+            severity: "warn",
+            source: "compile_report",
+            subject: "compile"
+        }));
+    }
+    const reportNodes = new Map(loaded.report.nodes.map((node) => [node.id, node]));
+    const declaredIds = new Set(nodes.map((node) => node.id));
+    for (const node of nodes) {
+        const reportNode = reportNodes.get(node.id);
+        observations.push(createObservation({
+            key: `${node.kind}.compiled`,
+            message: reportNode
+                ? `${node.displayName} is present in the compile report`
+                : `${node.displayName} is missing from the compile report`,
+            severity: reportNode ? "ok" : "warn",
+            source: "compile_report",
+            subject: node.id
+        }));
+        if (reportNode) {
+            observations.push(...createNodeReportObservations(reportNode));
+        }
+    }
+    for (const reportNode of loaded.report.nodes) {
+        if (!declaredIds.has(reportNode.id)) {
+            observations.push(createObservation({
+                key: "compile.extra_node",
+                message: `${reportNode.id} appears in the compile report but not in source`,
+                severity: "warn",
+                source: "compile_report",
+                subject: reportNode.id
+            }));
+        }
+    }
+};
+const defaultLiveRequest = () => ({
+    context: null,
+    deploymentName: null,
+    logs: false,
+    recover: false,
+    requested: false
+});
+const addLivePlaceholderObservations = (observations, view, live, providedLiveObservations) => {
+    if (!live.requested) {
+        return;
+    }
+    if (!providedLiveObservations.some((observation) => observation.source === "runtime")) {
+        for (const runtime of view.runtimes) {
+            observations.push(createObservation({
+                key: "runtime.probe",
+                message: `${runtime.name} live runtime probe is not available for this status request`,
+                severity: "unknown",
+                source: "runtime",
+                subject: `runtime:${runtime.name}`
+            }));
+        }
+    }
+    if (!providedLiveObservations.some((observation) => observation.source === "network")) {
+        for (const network of view.networks) {
+            observations.push(createObservation({
+                key: "network.probe",
+                message: `${network.id} live network probe is not available for this status request`,
+                severity: "unknown",
+                source: "network",
+                subject: `network:${network.id}`
+            }));
+        }
+    }
+};
+export const createStaticStatus = (view, loadedReport, input) => {
+    const nodes = flattenOrganizationNodes(view);
+    const observations = [];
+    const nodeCounts = countNodesByKind(nodes);
+    const deployments = input.deployments ?? [];
+    const live = input.live ?? defaultLiveRequest();
+    const liveObservations = input.liveObservations ?? [];
+    const selection = expandStatusSelectionSubjects(input.selection, {
+        deployments,
+        loadedReport,
+        view
+    });
+    addDeclaredObservations(observations, view, nodes);
+    addCompiledObservations(observations, loadedReport, view, nodes);
+    observations.push(...createDeploymentObservations(deployments, {
+        compileFingerprint: compileInfoFor(loadedReport).compileFingerprint,
+        liveRequested: live.requested,
+        outputDirectory: input.outputDirectory,
+        recover: live.recover
+    }));
+    observations.push(...liveObservations);
+    addLivePlaceholderObservations(observations, view, live, liveObservations);
+    return {
+        compile: compileInfoFor(loadedReport),
+        deployments,
+        inputPath: input.inputPath,
+        live,
+        observations,
+        outputDirectory: input.outputDirectory,
+        projectRoot: view.projectRoot ?? null,
+        selection,
+        summary: {
+            ...nodeCounts,
+            deployments: deployments.length,
+            networks: view.networks.length,
+            runtimes: view.runtimes.length
+        },
+        view,
+        version: "spawnfile.status.v1"
+    };
+};

package/dist/status/compileReport.d.ts

@@ -0,0 +1,96 @@
+import type { StatusInputFailure } from "./types.js";
+export interface StatusReportCapability {
+    key: string;
+    message: string;
+    outcome: "degraded" | "supported" | "unsupported";
+}
+export interface StatusReportDiagnostic {
+    level: "error" | "info" | "warn";
+    message: string;
+}
+export interface StatusReportNode {
+    capabilities: StatusReportCapability[];
+    diagnostics: StatusReportDiagnostic[];
+    id: string;
+    kind: "agent" | "team";
+    outputDir: string | null;
+    runtime: string | null;
+}
+export interface StatusReportRuntimeInstance {
+    configPath: string | null;
+    homePath: string | null;
+    id: string;
+    internalPort: number | null;
+    nodeIds: string[];
+    publishedPort: number | null;
+    runtime: string;
+    workspacePath: string | null;
+}
+export interface StatusReportMoltnetRoom {
+    id: string;
+    members: string[];
+    visibility: string | null;
+    writePolicy: string | null;
+}
+export interface StatusReportMoltnetServerPlan {
+    authMode: string | null;
+    baseUrl: string;
+    directMessages: boolean | null;
+    id: string;
+    mode: "external" | "managed";
+    networkId: string;
+    operatorTokenSecret: string | null;
+    port: number | null;
+    publicRead: boolean | null;
+    rooms: StatusReportMoltnetRoom[];
+    storeKind: string | null;
+}
+export interface StatusReportContainerPortMapping {
+    internalPort: number;
+    publishedPort: number;
+}
+export interface StatusReportPersistentMount {
+    id: string;
+    mountPath: string;
+    reason: string;
+    volumeName: string;
+}
+export interface StatusReportWorkspaceResource {
+    backingPath: string;
+    id: string;
+    kind: string;
+    linkPath: string;
+    mode: string;
+    mount: string;
+    sharing: string;
+}
+export interface StatusReport {
+    compileFingerprint: string | null;
+    generatedAt: string | null;
+    internalPorts?: number[];
+    moltnetServers?: StatusReportMoltnetServerPlan[];
+    nodes: StatusReportNode[];
+    outputDirectory: string | null;
+    persistentMounts?: StatusReportPersistentMount[];
+    portMappings?: StatusReportContainerPortMapping[];
+    publishedPorts?: number[];
+    reportPath: string;
+    root: string | null;
+    runtimeInstances: StatusReportRuntimeInstance[];
+    secretsRequired?: string[];
+    workspaceResources?: StatusReportWorkspaceResource[];
+}
+export type LoadedCompileReport = {
+    kind: "failure";
+    failure: StatusInputFailure;
+    reportPath: string;
+} | {
+    kind: "loaded";
+    report: StatusReport;
+    reportPath: string;
+} | {
+    kind: "missing";
+    reportPath: string;
+};
+export declare const resolveCompileReportPath: (outputDirectory: string) => string;
+export declare const loadCompileReport: (outputDirectory: string) => Promise<LoadedCompileReport>;

package/dist/status/compileReport.js

@@ -0,0 +1,230 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { REPORT_FILENAME } from "../shared/index.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const toStringOrNull = (value) => typeof value === "string" ? value : null;
+const toStringArray = (value) => Array.isArray(value)
+    ? value.filter((entry) => typeof entry === "string")
+    : [];
+const toNumberOrNull = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
+const toBooleanOrNull = (value) => typeof value === "boolean" ? value : null;
+const toNumberArray = (value) => Array.isArray(value)
+    ? value.filter((entry) => typeof entry === "number" && Number.isFinite(entry))
+    : [];
+const normalizeCapability = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const key = toStringOrNull(value.key);
+    const message = toStringOrNull(value.message);
+    const outcome = toStringOrNull(value.outcome);
+    if (!key || !message || !["degraded", "supported", "unsupported"].includes(outcome ?? "")) {
+        return null;
+    }
+    return { key, message, outcome: outcome };
+};
+const normalizeDiagnostic = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const level = toStringOrNull(value.level);
+    const message = toStringOrNull(value.message);
+    if (!message || !["error", "info", "warn"].includes(level ?? "")) {
+        return null;
+    }
+    return { level: level, message };
+};
+const normalizeNode = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const id = toStringOrNull(value.id);
+    const kind = toStringOrNull(value.kind);
+    if (!id || !["agent", "team"].includes(kind ?? "")) {
+        return null;
+    }
+    return {
+        capabilities: (Array.isArray(value.capabilities) ? value.capabilities : [])
+            .map(normalizeCapability)
+            .filter((entry) => entry !== null),
+        diagnostics: (Array.isArray(value.diagnostics) ? value.diagnostics : [])
+            .map(normalizeDiagnostic)
+            .filter((entry) => entry !== null),
+        id,
+        kind: kind,
+        outputDir: toStringOrNull(value.output_dir),
+        runtime: toStringOrNull(value.runtime)
+    };
+};
+const normalizeRuntimeInstance = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const id = toStringOrNull(value.id);
+    const runtime = toStringOrNull(value.runtime);
+    if (!id || !runtime) {
+        return null;
+    }
+    return {
+        configPath: toStringOrNull(value.config_path),
+        homePath: toStringOrNull(value.home_path),
+        id,
+        internalPort: toNumberOrNull(value.internal_port),
+        nodeIds: toStringArray(value.node_ids),
+        publishedPort: toNumberOrNull(value.published_port),
+        runtime,
+        workspacePath: toStringOrNull(value.workspace_path)
+    };
+};
+const normalizeMoltnetRoom = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const id = toStringOrNull(value.id);
+    if (!id) {
+        return null;
+    }
+    return {
+        id,
+        members: toStringArray(value.members),
+        visibility: toStringOrNull(value.visibility),
+        writePolicy: toStringOrNull(value.write_policy)
+    };
+};
+const normalizeMoltnetServer = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const id = toStringOrNull(value.id);
+    const mode = toStringOrNull(value.mode);
+    const networkId = toStringOrNull(value.network_id);
+    const baseUrl = toStringOrNull(value.base_url);
+    if (!id || !baseUrl || !networkId || (mode !== "managed" && mode !== "external")) {
+        return null;
+    }
+    return {
+        authMode: toStringOrNull(value.auth_mode),
+        baseUrl,
+        directMessages: toBooleanOrNull(value.direct_messages),
+        id,
+        mode,
+        networkId,
+        operatorTokenSecret: toStringOrNull(value.operator_token_secret),
+        port: toNumberOrNull(value.port),
+        publicRead: toBooleanOrNull(value.public_read),
+        rooms: (Array.isArray(value.rooms) ? value.rooms : [])
+            .map(normalizeMoltnetRoom)
+            .filter((entry) => entry !== null),
+        storeKind: toStringOrNull(value.store_kind)
+    };
+};
+const normalizePortMapping = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const internalPort = toNumberOrNull(value.internal_port);
+    const publishedPort = toNumberOrNull(value.published_port);
+    return internalPort && publishedPort ? { internalPort, publishedPort } : null;
+};
+const normalizePersistentMount = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const id = toStringOrNull(value.id);
+    const mountPath = toStringOrNull(value.mount_path);
+    const reason = toStringOrNull(value.reason);
+    const volumeName = toStringOrNull(value.volume_name);
+    return id && mountPath && reason && volumeName
+        ? { id, mountPath, reason, volumeName }
+        : null;
+};
+const normalizeWorkspaceResource = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const backingPath = toStringOrNull(value.backing_path);
+    const id = toStringOrNull(value.id);
+    const kind = toStringOrNull(value.kind);
+    const linkPath = toStringOrNull(value.link_path);
+    const mode = toStringOrNull(value.mode);
+    const mount = toStringOrNull(value.mount);
+    const sharing = toStringOrNull(value.sharing);
+    return backingPath && id && kind && linkPath && mode && mount && sharing
+        ? { backingPath, id, kind, linkPath, mode, mount, sharing }
+        : null;
+};
+const normalizeReport = (value, reportPath) => {
+    if (!isRecord(value) || !Array.isArray(value.nodes)) {
+        return null;
+    }
+    const container = isRecord(value.container) ? value.container : {};
+    const runtimeInstances = Array.isArray(container.runtime_instances)
+        ? container.runtime_instances
+        : [];
+    const moltnet = isRecord(container.moltnet) ? container.moltnet : {};
+    const moltnetServers = Array.isArray(moltnet.server_plans) ? moltnet.server_plans : [];
+    return {
+        compileFingerprint: toStringOrNull(value.compile_fingerprint),
+        generatedAt: toStringOrNull(value.generated_at),
+        internalPorts: toNumberArray(container.internal_ports),
+        moltnetServers: moltnetServers
+            .map(normalizeMoltnetServer)
+            .filter((entry) => entry !== null),
+        nodes: value.nodes
+            .map(normalizeNode)
+            .filter((entry) => entry !== null),
+        outputDirectory: toStringOrNull(value.output_directory),
+        persistentMounts: (Array.isArray(container.persistent_mounts) ? container.persistent_mounts : [])
+            .map(normalizePersistentMount)
+            .filter((entry) => entry !== null),
+        portMappings: (Array.isArray(container.port_mappings) ? container.port_mappings : [])
+            .map(normalizePortMapping)
+            .filter((entry) => entry !== null),
+        publishedPorts: toNumberArray(container.published_ports ?? container.ports),
+        reportPath,
+        root: toStringOrNull(value.root),
+        runtimeInstances: runtimeInstances
+            .map(normalizeRuntimeInstance)
+            .filter((entry) => entry !== null),
+        secretsRequired: toStringArray(container.secrets_required),
+        workspaceResources: (Array.isArray(container.workspace_resources) ? container.workspace_resources : [])
+            .map(normalizeWorkspaceResource)
+            .filter((entry) => entry !== null)
+    };
+};
+export const resolveCompileReportPath = (outputDirectory) => path.join(outputDirectory, REPORT_FILENAME);
+export const loadCompileReport = async (outputDirectory) => {
+    const reportPath = resolveCompileReportPath(outputDirectory);
+    try {
+        await stat(reportPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { kind: "missing", reportPath };
+        }
+        return {
+            failure: { exitCode: 2, message: `Unable to stat compile report ${reportPath}` },
+            kind: "failure",
+            reportPath
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(reportPath, "utf8"));
+    }
+    catch {
+        return {
+            failure: { exitCode: 2, message: `Unable to read compile report ${reportPath}` },
+            kind: "failure",
+            reportPath
+        };
+    }
+    const report = normalizeReport(parsed, reportPath);
+    return report
+        ? { kind: "loaded", report, reportPath }
+        : {
+            failure: { exitCode: 2, message: `Malformed compile report ${reportPath}` },
+            kind: "failure",
+            reportPath
+        };
+};

package/dist/status/compiledContainerObservations.d.ts

@@ -0,0 +1,5 @@
+import type { LoadedCompileReport } from "./compileReport.js";
+import type { StatusObservation } from "./types.js";
+export declare const createCompiledContainerObservations: (loaded: Extract<LoadedCompileReport, {
+    kind: "loaded";
+}>) => StatusObservation[];

package/dist/status/compiledContainerObservations.js

@@ -0,0 +1,63 @@
+const createObservation = (input) => ({
+    ...input,
+    label: `${input.severity.toUpperCase()} ${input.key}`
+});
+export const createCompiledContainerObservations = (loaded) => {
+    const observations = [];
+    const report = loaded.report;
+    for (const instance of report.runtimeInstances) {
+        observations.push(createObservation({
+            key: "runtime.instance",
+            message: `${instance.id} emits ${instance.runtime} workspace ${instance.workspacePath ?? "unknown"}`,
+            severity: "ok",
+            source: "compile_report",
+            subject: `runtime-instance:${instance.id}`
+        }));
+    }
+    for (const server of report.moltnetServers ?? []) {
+        observations.push(createObservation({
+            key: "network.compiled",
+            message: `${server.networkId} Moltnet ${server.mode} server at ${server.baseUrl}`,
+            severity: "ok",
+            source: "compile_report",
+            subject: `network:${server.networkId}`
+        }));
+        for (const room of server.rooms) {
+            observations.push(createObservation({
+                key: "network.room.compiled",
+                message: `${server.networkId}/${room.id} expects ${room.members.length} member(s)`,
+                severity: "ok",
+                source: "compile_report",
+                subject: `room:${server.networkId}:${room.id}`
+            }));
+        }
+    }
+    for (const mount of report.persistentMounts ?? []) {
+        observations.push(createObservation({
+            key: "container.mount",
+            message: `${mount.id} mounted at ${mount.mountPath} using volume ${mount.volumeName}`,
+            severity: "ok",
+            source: "compile_report",
+            subject: "compile"
+        }));
+    }
+    for (const resource of report.workspaceResources ?? []) {
+        observations.push(createObservation({
+            key: "workspace.resource",
+            message: `${resource.id} linked at ${resource.linkPath} from ${resource.backingPath}`,
+            severity: "ok",
+            source: "compile_report",
+            subject: "compile"
+        }));
+    }
+    if ((report.internalPorts?.length ?? 0) > 0 || (report.publishedPorts?.length ?? 0) > 0) {
+        observations.push(createObservation({
+            key: "container.ports",
+            message: `internal ports: ${(report.internalPorts ?? []).join(", ") || "none"}; published ports: ${(report.publishedPorts ?? []).join(", ") || "none"}`,
+            severity: "ok",
+            source: "compile_report",
+            subject: "compile"
+        }));
+    }
+    return observations;
+};

package/dist/status/deploymentLogs.d.ts

@@ -0,0 +1,12 @@
+import { type DeploymentRecord, type DockerLogsExecFile } from "../deployment/index.js";
+import type { LoadedCompileReport } from "./compileReport.js";
+import type { StatusObservation } from "./types.js";
+export interface CollectDeploymentLogOptions {
+    deployments: DeploymentRecord[];
+    dockerCommand?: string;
+    execFile?: DockerLogsExecFile;
+    loadedReport: LoadedCompileReport;
+    tail?: number;
+    timeoutMs?: number;
+}
+export declare const collectDeploymentLogObservations: (options: CollectDeploymentLogOptions) => Promise<StatusObservation[]>;