spawnfile 0.1.11 → 0.1.12

package/dist/cli/statusCommand.js

@@ -0,0 +1,394 @@
+import { inspectDockerDeployment, listDeploymentRecords, listHomeDeploymentRecords, readHomeDeploymentRecord, readHomeDeploymentReport } from "../deployment/index.js";
+import { extractImageReport, parseDistributionReport, projectImageOrganizationView, renderImageInterface } from "../distribution/index.js";
+import { collectRegistryDriftObservations } from "../status/index.js";
+import { resolveProjectOutputDirectory } from "../filesystem/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY, errorExitCode, SpawnfileError } from "../shared/index.js";
+import { resolveCommandInput } from "./resolveCommandInput.js";
+import { loadedImageCompileReport } from "../status/index.js";
+import { createStaticStatus, createDeploymentSummaries, collectDeploymentLogObservations, collectMoltnetProbeObservations, collectRuntimeProbeObservations, exitCodeForStatus, loadCompileReport, renderStatus, resolveStatusSelector } from "../status/index.js";
+const inputFailure = (message) => ({
+    error: message,
+    exitCode: 2
+});
+const resolveOutputMode = (options) => {
+    const modes = [
+        ...(options.json ? ["json"] : []),
+        ...(options.pretty ? ["pretty"] : []),
+        ...(options.quiet ? ["quiet"] : [])
+    ];
+    if (modes.length > 1) {
+        return inputFailure("Choose only one status output mode: --pretty, --json, or --quiet");
+    }
+    return modes[0] ?? "pretty";
+};
+const resolveSelectorInput = (options) => {
+    const selectors = [
+        ...(options.agent ? [{ kind: "agent", value: options.agent }] : []),
+        ...(options.team ? [{ kind: "team", value: options.team }] : []),
+        ...(options.network ? [{ kind: "network", value: options.network }] : []),
+        ...(options.runtime ? [{ kind: "runtime", value: options.runtime }] : [])
+    ];
+    if (selectors.length > 1) {
+        return inputFailure("Choose only one status selector: --agent, --team, --network, or --runtime");
+    }
+    return selectors[0] ?? null;
+};
+const resolveTimeoutMs = (options) => {
+    if (!options.timeout) {
+        return undefined;
+    }
+    const parsed = Number(options.timeout);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return inputFailure("status --timeout must be a positive integer number of milliseconds");
+    }
+    return parsed;
+};
+const resolveDeploymentRecords = (records, options) => {
+    if (options.deployment) {
+        const record = records.find((entry) => entry.record.name === options.deployment);
+        return record
+            ? [record]
+            : inputFailure(`Unknown deployment "${options.deployment}". Valid deployments: ${records.map((entry) => entry.record.name).sort().join(", ") || "none"}`);
+    }
+    if (options.live && records.length > 1) {
+        return inputFailure(`status --live requires --deployment when multiple records exist: ${records.map((entry) => entry.record.name).sort().join(", ")}`);
+    }
+    return records;
+};
+const inspectDeployments = async (records, handlers, options, timeoutMs) => {
+    if (!options.live || options.recover) {
+        return new Map();
+    }
+    const inspect = handlers.inspectDockerDeployment ?? inspectDockerDeployment;
+    const inspections = await Promise.all(records.map(async ({ record }) => [
+        record.name,
+        await inspect(record, { timeoutMs })
+    ]));
+    return new Map(inspections);
+};
+const resolveAuthValues = async (records, handlers) => {
+    const values = {};
+    if (!handlers.requireAuthProfile) {
+        return values;
+    }
+    const profileNames = [...new Set(records
+            .map(({ record }) => record.auth_profile)
+            .filter((profileName) => typeof profileName === "string" && profileName.length > 0))];
+    for (const profileName of profileNames) {
+        try {
+            const profile = await handlers.requireAuthProfile(profileName);
+            Object.assign(values, profile.env);
+        }
+        catch {
+            // Missing profile values are reported by the metadata layer as unknown credentials.
+        }
+    }
+    return values;
+};
+const emitOutput = (streams, output) => {
+    for (const line of output.split("\n")) {
+        streams.stdout(line);
+    }
+};
+const wait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+export const executeStatusWatch = async (inputPath, options, handlers, streams, setExitCode, watchOptions = {}) => {
+    const intervalMs = watchOptions.intervalMs ?? 5_000;
+    const sleep = watchOptions.sleep ?? wait;
+    let iteration = 0;
+    while (watchOptions.iterations === undefined || iteration < watchOptions.iterations) {
+        if (iteration > 0) {
+            await sleep(intervalMs);
+            streams.stdout("");
+        }
+        const result = await executeStatusCommand(inputPath, options, handlers);
+        setExitCode(result.exitCode);
+        if (result.error) {
+            streams.stderr(`error: ${result.error}`);
+            return;
+        }
+        if (result.output) {
+            emitOutput(streams, result.output);
+        }
+        iteration += 1;
+    }
+};
+/* v8 ignore start -- docker extraction is covered by distribution E2E */
+const runStaticImageStatus = async (imageRef, options, json) => {
+    try {
+        const inspection = await extractImageReport(imageRef, {
+            dockerCommand: options.dockerCommand,
+            dockerContext: options.context,
+            pull: options.pull
+        });
+        return {
+            exitCode: 0,
+            output: renderImageInterface(inspection.report, { imageRef, json })
+        };
+    }
+    catch (error) {
+        // Input errors (bad labels, non-JSON report, fingerprint mismatch) exit 2;
+        // Docker/runtime failures (daemon down, pull/create failure) exit 1.
+        return {
+            error: error instanceof Error ? error.message : String(error),
+            exitCode: errorExitCode(error)
+        };
+    }
+};
+/* v8 ignore stop */
+const runHomeDeploymentStatus = async (options, handlers, mode, timeoutMs) => {
+    let records;
+    try {
+        records = await listHomeDeploymentRecords();
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error), exitCode: errorExitCode(error) };
+    }
+    if (!options.deployment) {
+        if (records.length === 0) {
+            return inputFailure("No image deployments found in the home store");
+        }
+        if (records.length > 1) {
+            return inputFailure(`status --deployment is required: ${records.map((entry) => entry.record.name).sort().join(", ")}`);
+        }
+    }
+    const targetName = options.deployment ?? records[0].record.name;
+    const match = records.find((entry) => entry.record.name === targetName);
+    if (!match) {
+        return inputFailure(`Unknown deployment "${targetName}". Valid deployments: ${records.map((entry) => entry.record.name).sort().join(", ") || "none"}`);
+    }
+    let report;
+    try {
+        const record = await readHomeDeploymentRecord(targetName);
+        void record;
+        const raw = await readHomeDeploymentReport(targetName);
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            // A corrupt cached report is bad input, not a runtime failure: exit 2.
+            throw new SpawnfileError("validation_error", `Cached report for "${targetName}" is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        report = parseDistributionReport(parsed);
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error), exitCode: errorExitCode(error) };
+    }
+    const view = projectImageOrganizationView(report, match.record.source.kind === "image"
+        ? match.record.source.ref
+        : targetName);
+    const reportPath = match.path.replace(/record\.json$/, "spawnfile-report.json");
+    const loadedReport = loadedImageCompileReport(report, reportPath);
+    const selectedRecords = [match];
+    const deploymentInspections = await inspectDeployments(selectedRecords, handlers, options, timeoutMs);
+    const recordValues = selectedRecords.map(({ record }) => record);
+    const authValues = options.live ? await resolveAuthValues(selectedRecords, handlers) : {};
+    const collectRuntimeProbes = handlers.collectRuntimeProbeObservations ?? collectRuntimeProbeObservations;
+    const collectMoltnetProbes = handlers.collectMoltnetProbeObservations ?? collectMoltnetProbeObservations;
+    const collectDeploymentLogs = handlers.collectDeploymentLogObservations ?? collectDeploymentLogObservations;
+    const liveObservations = options.live && !options.recover
+        ? [
+            ...await collectRuntimeProbes({
+                deployments: recordValues,
+                inspections: deploymentInspections,
+                loadedReport,
+                timeoutMs
+            }),
+            ...await collectMoltnetProbes({
+                authValues,
+                deployments: recordValues,
+                inspections: deploymentInspections,
+                loadedReport,
+                timeoutMs
+            }),
+            ...(options.logs
+                ? await collectDeploymentLogs({ deployments: recordValues, loadedReport, timeoutMs })
+                : []),
+            ...(options.pullCheck
+                ? await collectRegistryDriftObservations({
+                    deployments: recordValues,
+                    dockerCommand: options.dockerCommand,
+                    timeoutMs
+                })
+                : [])
+        ]
+        : [];
+    const status = createStaticStatus(view, loadedReport, {
+        deployments: createDeploymentSummaries(selectedRecords, deploymentInspections),
+        inputPath: view.inputPath,
+        live: {
+            context: null,
+            deploymentName: targetName,
+            logs: options.logs ?? false,
+            recover: false,
+            requested: options.live ?? false
+        },
+        liveObservations,
+        outputDirectory: "",
+        selection: null
+    });
+    return { exitCode: exitCodeForStatus(status), output: renderStatus(status, { mode }), status };
+};
+export const executeStatusCommand = async (inputPath, options, handlers) => {
+    const mode = resolveOutputMode(options);
+    if (typeof mode !== "string") {
+        return mode;
+    }
+    if (options.logs && !options.live) {
+        return inputFailure("status --logs requires --live");
+    }
+    // A positional image reference without --deployment renders the static
+    // interface from the embedded report. Image ref with --deployment, or a bare
+    // --deployment on the default path, reads the home store.
+    // A clear image reference (tag/digest/registry, or forced with --image)
+    // without --deployment renders the static interface; any other positional is
+    // treated as a project path (the view builder reports a missing path).
+    const commandInput = resolveCommandInput(inputPath, { forceImage: options.image });
+    const usedDefaultPath = inputPath === process.cwd();
+    if (commandInput.kind === "image" && !options.deployment) {
+        return runStaticImageStatus(commandInput.ref, options, mode === "json");
+    }
+    if (options.deployment && (commandInput.kind === "image" || usedDefaultPath)) {
+        const timeoutForHome = resolveTimeoutMs(options);
+        if (typeof timeoutForHome !== "number" && timeoutForHome !== undefined) {
+            return timeoutForHome;
+        }
+        return runHomeDeploymentStatus(options, handlers, mode, timeoutForHome);
+    }
+    if (options.context && !options.recover) {
+        return inputFailure("status accepts --context only with --recover");
+    }
+    if (options.logs && !options.live) {
+        return inputFailure("status --logs requires --live");
+    }
+    if (options.logs && options.recover) {
+        return inputFailure("status --logs is not available with --recover");
+    }
+    if (options.recover && !options.context) {
+        return inputFailure("status --recover requires --context");
+    }
+    const timeoutMs = resolveTimeoutMs(options);
+    if (typeof timeoutMs !== "number" && timeoutMs !== undefined) {
+        return timeoutMs;
+    }
+    const selectorInput = resolveSelectorInput(options);
+    if (selectorInput && "exitCode" in selectorInput) {
+        return selectorInput;
+    }
+    const outputDirectory = resolveProjectOutputDirectory(inputPath, options.out, DEFAULT_OUTPUT_DIRECTORY);
+    const view = await handlers.buildOrganizationView(inputPath);
+    const selectorResult = resolveStatusSelector(view, selectorInput);
+    if (selectorResult?.kind === "failure") {
+        return { error: selectorResult.failure.message, exitCode: 2 };
+    }
+    const loadedReport = await loadCompileReport(outputDirectory);
+    if (loadedReport.kind === "failure") {
+        return { error: loadedReport.failure.message, exitCode: 2 };
+    }
+    let deploymentRecords;
+    try {
+        deploymentRecords = await listDeploymentRecords(outputDirectory);
+    }
+    catch (error) {
+        return {
+            error: error instanceof Error ? error.message : String(error),
+            exitCode: 2
+        };
+    }
+    const selectedDeploymentRecords = resolveDeploymentRecords(deploymentRecords, options);
+    if ("exitCode" in selectedDeploymentRecords) {
+        return selectedDeploymentRecords;
+    }
+    const deploymentInspections = await inspectDeployments(selectedDeploymentRecords, handlers, options, timeoutMs);
+    const selectedDeploymentRecordValues = selectedDeploymentRecords.map(({ record }) => record);
+    const authValues = options.live
+        ? await resolveAuthValues(selectedDeploymentRecords, handlers)
+        : {};
+    const collectRuntimeProbes = handlers.collectRuntimeProbeObservations ?? collectRuntimeProbeObservations;
+    const collectMoltnetProbes = handlers.collectMoltnetProbeObservations ?? collectMoltnetProbeObservations;
+    const collectDeploymentLogs = handlers.collectDeploymentLogObservations ?? collectDeploymentLogObservations;
+    const liveObservations = options.live && !options.recover
+        ? [
+            ...await collectRuntimeProbes({
+                deployments: selectedDeploymentRecordValues,
+                inspections: deploymentInspections,
+                loadedReport,
+                timeoutMs
+            }),
+            ...await collectMoltnetProbes({
+                authValues,
+                deployments: selectedDeploymentRecordValues,
+                inspections: deploymentInspections,
+                loadedReport,
+                timeoutMs
+            }),
+            ...(options.logs
+                ? await collectDeploymentLogs({
+                    deployments: selectedDeploymentRecordValues,
+                    loadedReport,
+                    timeoutMs
+                })
+                : [])
+        ]
+        : [];
+    const status = createStaticStatus(view, loadedReport, {
+        deployments: createDeploymentSummaries(selectedDeploymentRecords, deploymentInspections),
+        inputPath,
+        live: {
+            context: options.context ?? null,
+            deploymentName: options.deployment ?? null,
+            logs: options.logs ?? false,
+            recover: options.recover ?? false,
+            requested: options.live ?? false
+        },
+        liveObservations,
+        outputDirectory,
+        selection: selectorResult?.selection ?? null
+    });
+    return {
+        exitCode: exitCodeForStatus(status),
+        output: renderStatus(status, { mode }),
+        status
+    };
+};
+export const registerStatusCommand = (program, handlers, streams, setExitCode) => {
+    program
+        .command("status")
+        .description("Show static Spawnfile organization status")
+        .argument("[path]", "Project directory or Spawnfile path", process.cwd())
+        .option("--out <dir>", "Compile output directory")
+        .option("--json", "Render machine-readable JSON")
+        .option("--pretty", "Render human output")
+        .option("--quiet", "Render only summary and non-ok observations")
+        .option("--live", "Inspect the recorded live deployment")
+        .option("--deployment <name>", "Deployment record name")
+        .option("--image", "Interpret the argument as an image reference")
+        .option("--pull", "Pull the image before inspecting (image references only)")
+        .option("--pull-check", "Check the registry for a newer image digest (networked)")
+        .option("--docker-command <command>", "Docker command")
+        .option("--context <name>", "Docker context for label recovery only")
+        .option("--recover", "Recover live status from labels instead of a deployment record")
+        .option("--logs", "Include redacted logs when supported")
+        .option("--timeout <ms>", "Bound live Docker/runtime checks in milliseconds")
+        .option("--watch", "Refresh status every five seconds until interrupted")
+        .option("--agent <id>", "Show one agent")
+        .option("--team <id>", "Show one team")
+        .option("--network <id>", "Show one network")
+        .option("--runtime <name>", "Show one runtime")
+        .action(async (inputPath, options) => {
+        if (options.watch) {
+            await executeStatusWatch(inputPath, options, handlers, streams, setExitCode);
+            return;
+        }
+        const result = await executeStatusCommand(inputPath, options, handlers);
+        setExitCode(result.exitCode);
+        if (result.error) {
+            streams.stderr(`error: ${result.error}`);
+        }
+        if (result.output) {
+            emitOutput(streams, result.output);
+        }
+    });
+};

package/dist/cli/surfaceCommands.js

@@ -22,6 +22,7 @@ export const registerSurfaceCommands = (program, handlers, streams) => {
         .description("Edit agent surfaces");
     surfaceCommand
         .command("add")
+        .description("Attach a surface to an agent")
         .argument("<surface>", "Surface name")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("--bot-token-secret <env>", "Override the bot token env var name")
@@ -42,6 +43,7 @@ export const registerSurfaceCommands = (program, handlers, streams) => {
     });
     surfaceCommand
         .command("remove")
+        .description("Detach a surface from an agent")
         .argument("<surface>", "Surface name")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("--recursive", "Update the target project and its descendants")
@@ -58,6 +60,7 @@ export const registerSurfaceCommands = (program, handlers, streams) => {
     });
     surfaceCommand
         .command("set-access")
+        .description("Set an agent's access mode for a surface")
         .argument("<surface>", "Surface name")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .requiredOption("--mode <mode>", "Access mode")
@@ -86,6 +89,7 @@ export const registerSurfaceCommands = (program, handlers, streams) => {
     });
     surfaceCommand
         .command("show")
+        .description("Show an agent's resolved surfaces")
         .argument("[path]", "Project directory or Spawnfile path", process.cwd())
         .option("--recursive", "Show descendant agent surfaces too")
         .action(async (inputPath, options) => {

package/dist/compiler/agentSurfaces.js

@@ -27,8 +27,7 @@ export const resolveAgentSurfaces = (surfaces) => {
                 ? {
                     dms: {
                         enabled: attachment.dms.enabled,
-                        ...(attachment.dms.read ? { read: attachment.dms.read } : {}),
-                        ...(attachment.dms.reply ? { reply: attachment.dms.reply } : {})
+                        ...(attachment.dms.wake ? { wake: attachment.dms.wake } : {})
                     }
                 }
                 : {}),
@@ -41,8 +40,7 @@ export const resolveAgentSurfaces = (surfaces) => {
                         .map(([roomId, behavior]) => [
                         roomId,
                         {
-                            ...(behavior.read ? { read: behavior.read } : {}),
-                            ...(behavior.reply ? { reply: behavior.reply } : {})
+                            ...(behavior.wake ? { wake: behavior.wake } : {})
                         }
                     ]))
                 }

package/dist/compiler/compileProject.js

@@ -22,9 +22,7 @@ const createTeamOutputDirectory = (baseDirectory, runtimeName, node) => path.joi
 const compileAgentNode = async (baseDirectory, node) => {
     const runtime = await assertRuntimeCanCompile(node.runtimeName ?? node.value.runtime.name);
     const adapter = getRuntimeAdapter(runtime.name);
-    const diagnostics = [
-        ...createRuntimeLifecycleDiagnostics(runtime)
-    ];
+    const diagnostics = [...createRuntimeLifecycleDiagnostics(runtime)];
     for (const diagnostic of adapter.validateRuntimeOptions?.(node.value.runtime.options) ?? []) {
         diagnostics.push(diagnostic);
     }
@@ -37,6 +35,7 @@ const compileAgentNode = async (baseDirectory, node) => {
     await writeEmittedFiles(outputDirectory, result.files);
     return {
         emittedFiles: result.files,
+        id: node.id,
         kind: node.kind,
         report: {
             capabilities: result.capabilities,
@@ -63,6 +62,7 @@ const compileTeamNode = async (baseDirectory, node) => {
     if (!runtimeName) {
         return {
             emittedFiles: [],
+            id: node.id,
             kind: node.kind,
             report: {
                 capabilities: createTeamCapabilities("degraded", "Team spans multiple runtimes and cannot lower to one native team artifact in v0.1"),
@@ -88,6 +88,7 @@ const compileTeamNode = async (baseDirectory, node) => {
     if (!adapter.compileTeam) {
         return {
             emittedFiles: [],
+            id: node.id,
             kind: node.kind,
             report: {
                 capabilities: createTeamCapabilities("degraded", `Runtime ${runtime.name} does not provide native team compilation in v0.1`),
@@ -113,6 +114,7 @@ const compileTeamNode = async (baseDirectory, node) => {
     await writeEmittedFiles(outputDirectory, result.files);
     return {
         emittedFiles: result.files,
+        id: node.id,
         kind: node.kind,
         report: {
             capabilities: result.capabilities,
@@ -200,7 +202,11 @@ const augmentNodeReports = (compiledNodes, support) => {
 };
 export const compileProject = async (inputPath, options = {}) => {
     const plan = await buildCompilePlan(inputPath);
-    const outputDirectory = path.resolve(options.outputDirectory ?? DEFAULT_OUTPUT_DIRECTORY);
+    // The default output directory lives under the resolved project root, not the
+    // process working directory, so `spawnfile compile ./org` writes ./org/.spawn.
+    const outputDirectory = options.outputDirectory
+        ? path.resolve(options.outputDirectory)
+        : path.join(path.dirname(plan.root), DEFAULT_OUTPUT_DIRECTORY);
     if (options.clean ?? true) {
         await removeDirectory(outputDirectory);
     }
@@ -229,17 +235,20 @@ export const compileProject = async (inputPath, options = {}) => {
         ? await stageMoltnetBinaries(outputDirectory)
         : false;
     await injectMoltnetWorkspaceFiles(outputDirectory, compiledNodes, moltnetArtifacts);
+    const generatedAt = new Date().toISOString();
     const containerArtifacts = await createContainerArtifacts(plan, compiledNodes, {
+        generatedAt,
         hasStagedMoltnetBinaries,
         moltnet: moltnetArtifacts
     });
     await writeEmittedFiles(outputDirectory, containerArtifacts.files);
     await Promise.all(containerArtifacts.executablePaths.map((filePath) => chmod(path.join(outputDirectory, filePath), 0o755)));
-    const report = createCompileReport(plan.root, nodeReports, [], containerArtifacts.report);
-    const reportPath = await writeCompileReport(outputDirectory, report);
-    return {
+    const report = createCompileReport(plan.root, nodeReports, [], containerArtifacts.report, {
+        compileFingerprint: containerArtifacts.distribution.fingerprint,
+        generatedAt,
         outputDirectory,
-        report,
-        reportPath
-    };
+        projectName: containerArtifacts.distribution.report.organization.project
+    });
+    const reportPath = await writeCompileReport(outputDirectory, report);
+    return { outputDirectory, report, reportPath };
 };

package/dist/compiler/containerArtifacts.d.ts

@@ -3,6 +3,7 @@ import type { CompiledNodeArtifact, GeneratedContainerArtifacts } from "./contai
 import type { CompilePlan } from "./types.js";
 export type { CompiledNodeArtifact, GeneratedContainerArtifacts } from "./containerArtifactsTypes.js";
 export interface ContainerArtifactOptions {
+    generatedAt?: string;
     hasStagedMoltnetBinaries?: boolean;
     moltnet?: MoltnetArtifacts | null;
 }