spawnfile 0.1.10 → 0.1.12

package/dist/runtime/statusProbes.js

@@ -0,0 +1,41 @@
+const observation = (key, severity, message) => ({ key, message, severity });
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+export const createRuntimePathProbe = (input) => ({
+    id: input.id,
+    label: input.label,
+    async run(context) {
+        const targetPath = input.pathFor(context.instance);
+        if (!targetPath) {
+            return [
+                observation(input.key, "unknown", `${input.label} path is not present in the compile report`)
+            ];
+        }
+        try {
+            await context.manager.exec(["test", input.testFlag, targetPath]);
+            return [observation(input.key, "ok", `${input.label} exists at ${targetPath}`)];
+        }
+        catch (error) {
+            return [
+                observation(input.key, "error", `${input.label} missing at ${targetPath}: ${errorMessage(error)}`)
+            ];
+        }
+    }
+});
+export const createRuntimeHttpProbe = (input) => ({
+    id: input.id,
+    label: input.label,
+    async run(context) {
+        const port = input.portFor(context.instance);
+        if (!port) {
+            return [
+                observation(input.key, "unknown", `${input.label} port is not present in the compile report`)
+            ];
+        }
+        const response = await context.manager.httpGet(port, input.path);
+        return [
+            response.ok
+                ? observation(input.key, "ok", `${input.label} responded on ${input.path}`)
+                : observation(input.key, "error", `${input.label} failed on ${input.path}: ${response.error ?? "request failed"}`)
+        ];
+    }
+});

package/dist/runtime/types.d.ts

@@ -3,6 +3,8 @@ import type { ResolvedAuthProfile } from "../auth/index.js";
 import type { AgentManifest } from "../manifest/index.js";
 import type { CapabilityReport, DiagnosticReport } from "../report/index.js";
 import type { ContainerRuntimeInstanceReport } from "../report/index.js";
+import type { DeploymentRecord, DockerUnitInspection } from "../deployment/index.js";
+import type { ModelAuthMethod } from "../shared/index.js";
 export interface EmittedFile {
     content: string;
     mode?: number;
@@ -38,6 +40,7 @@ export interface RuntimeContainerInstancePaths {
 }
 export interface RuntimeContainerConfigEnvBinding {
     envName: string;
+    generated?: boolean;
     jsonPath: string;
 }
 export interface RuntimeContainerMeta {
@@ -46,6 +49,7 @@ export interface RuntimeContainerMeta {
     configPathEnv?: string;
     env?: Array<{
         description: string;
+        generated?: boolean;
         name: string;
         required: boolean;
     }>;
@@ -60,10 +64,24 @@ export interface RuntimeContainerMeta {
     staticEnv?: Record<string, string>;
     systemDeps: string[];
 }
+/**
+ * The minimal runtime-instance shape an auth preparer needs. Both the compile
+ * report's `ContainerRuntimeInstanceReport` and the distribution report's
+ * runtime instances structurally satisfy this, so sourceless image consumption
+ * can reuse the same preparers without casting through compiler-only types.
+ */
+export interface RuntimeAuthInstance {
+    config_path: string;
+    home_path: string | null;
+    id: string;
+    model_auth_methods: Record<string, ModelAuthMethod>;
+    model_secrets_required: string[];
+    runtime: string;
+}
 export interface RuntimeAuthPreparationInput {
     authProfile: ResolvedAuthProfile;
     env: Record<string, string>;
-    instance: ContainerRuntimeInstanceReport;
+    instance: RuntimeAuthInstance;
     outputDirectory: string;
     tempRoot: string;
 }
@@ -71,6 +89,38 @@ export interface RuntimeAuthPreparationResult {
     coveredModelSecrets: string[];
     mountArgs: string[];
 }
+export interface RuntimeProbeExecResult {
+    stderr: string;
+    stdout: string;
+}
+export interface RuntimeProbeHttpResult {
+    body: string;
+    error?: string;
+    ok: boolean;
+}
+export interface RuntimeProbeGateway {
+    exec(command: string[]): Promise<RuntimeProbeExecResult>;
+    httpGet(port: number, requestPath: string, headers?: Record<string, string>): Promise<RuntimeProbeHttpResult>;
+    inspectUnit(): Promise<DockerUnitInspection>;
+}
+export interface RuntimeProbeObservation {
+    details?: Record<string, unknown>;
+    key: string;
+    message: string;
+    severity: "error" | "ok" | "unknown" | "warn";
+}
+export interface RuntimeStatusProbeContext {
+    deployment: DeploymentRecord;
+    instance: ContainerRuntimeInstanceReport;
+    manager: RuntimeProbeGateway;
+    timeoutMs: number;
+    unit: DeploymentRecord["units"][number];
+}
+export interface RuntimeStatusProbe {
+    id: string;
+    label: string;
+    run(context: RuntimeStatusProbeContext): Promise<RuntimeProbeObservation[]>;
+}
 export interface RuntimeSystemInstructionSurfaceInput {
     node: ResolvedAgentNode;
 }
@@ -94,6 +144,7 @@ export interface RuntimeAdapter {
     name: string;
     prepareRuntimeAuth?(input: RuntimeAuthPreparationInput): Promise<RuntimeAuthPreparationResult>;
     scaffoldAgentProject?(): RuntimeAgentScaffold;
+    statusProbes?: RuntimeStatusProbe[];
     systemInstructionSurface?: RuntimeSystemInstructionSurface;
     validateRuntimeOptions?(options: Record<string, unknown>): DiagnosticReport[];
 }

package/dist/shared/errors.d.ts

@@ -4,3 +4,9 @@ export declare class SpawnfileError extends Error {
     constructor(code: SpawnfileErrorCode, message: string);
 }
 export declare const isSpawnfileError: (value: unknown) => value is SpawnfileError;
+/**
+ * Maps an error to the shared CLI exit-code convention: 2 for usage/input
+ * errors, 1 for runtime failures. Used wherever the CLI turns a caught error
+ * into a process exit code, so every path agrees (see specs/SPEC.md §9.1).
+ */
+export declare const errorExitCode: (error: unknown) => 1 | 2;

package/dist/shared/errors.js

@@ -7,3 +7,12 @@ export class SpawnfileError extends Error {
     }
 }
 export const isSpawnfileError = (value) => value instanceof SpawnfileError;
+// Codes that mean the input itself was bad (usage/input errors → exit 2).
+// Everything else is a runtime failure that surfaced after validation (→ exit 1).
+const USAGE_ERROR_CODES = new Set(["validation_error", "invalid_manifest"]);
+/**
+ * Maps an error to the shared CLI exit-code convention: 2 for usage/input
+ * errors, 1 for runtime failures. Used wherever the CLI turns a caught error
+ * into a process exit code, so every path agrees (see specs/SPEC.md §9.1).
+ */
+export const errorExitCode = (error) => isSpawnfileError(error) && USAGE_ERROR_CODES.has(error.code) ? 2 : 1;

package/dist/status/buildStatus.d.ts

@@ -0,0 +1,13 @@
+import { type LoadedCompileReport } from "./compileReport.js";
+import type { StaticStatus, StatusDeploymentSummary, StatusExitCode, StatusLiveRequest, StatusObservation, StatusObservationCounts, StatusSelection } from "./types.js";
+export declare const countObservations: (observations: StatusObservation[]) => StatusObservationCounts;
+export declare const getVisibleObservations: (status: StaticStatus) => StatusObservation[];
+export declare const exitCodeForStatus: (status: StaticStatus) => StatusExitCode;
+export declare const createStaticStatus: (view: StaticStatus["view"], loadedReport: LoadedCompileReport, input: {
+    deployments?: StatusDeploymentSummary[];
+    inputPath: string;
+    liveObservations?: StatusObservation[];
+    live?: StatusLiveRequest;
+    outputDirectory: string;
+    selection: StatusSelection | null;
+}) => StaticStatus;

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