spawnfile 0.1.11 → 0.1.13

package/dist/distribution/preflight.js

@@ -0,0 +1,65 @@
+import { SpawnfileError } from "../shared/index.js";
+const ENV_BASED_AUTH_METHODS = new Set(["api_key", "none"]);
+// Import-based auth methods are satisfiable sourceless when the consumer has the
+// matching local credential import (their logged-in Claude Code / Codex session).
+const IMPORT_AUTH_METHOD_KINDS = {
+    "claude-code": "claude-code",
+    codex: "codex"
+};
+const collectUnsupportedAuth = (report, availableImports) => {
+    const unsupported = [];
+    for (const instance of report.runtime_instances) {
+        for (const [provider, method] of Object.entries(instance.model_auth_methods)) {
+            if (ENV_BASED_AUTH_METHODS.has(method)) {
+                continue;
+            }
+            const importKind = IMPORT_AUTH_METHOD_KINDS[method];
+            if (importKind && availableImports.has(importKind)) {
+                continue;
+            }
+            unsupported.push({ instance: instance.id, method, provider, runtime: instance.runtime });
+        }
+    }
+    return unsupported;
+};
+export const runImagePreflight = (input) => {
+    const { authValues, report } = input;
+    const availableImports = new Set(input.availableImports ?? []);
+    const unsupportedAuth = collectUnsupportedAuth(report, availableImports);
+    if (unsupportedAuth.length > 0) {
+        const detail = unsupportedAuth
+            .map((entry) => `${entry.runtime}/${entry.instance} (${entry.provider}: ${entry.method})`)
+            .sort()
+            .join(", ");
+        throw new SpawnfileError("validation_error", `This image needs model auth this deployment cannot provide: ${detail}. ` +
+            "Provide an api_key secret, or an auth profile with the matching claude-code/codex import.");
+    }
+    const categories = ["model", "project", "runtime", "surface"];
+    const requiredSecrets = new Set();
+    const generatedSecrets = new Set();
+    for (const category of categories) {
+        for (const entry of report.secrets[category]) {
+            if (entry.generated) {
+                generatedSecrets.add(entry.name);
+                continue;
+            }
+            if (entry.required) {
+                requiredSecrets.add(entry.name);
+            }
+        }
+    }
+    const missing = [...requiredSecrets]
+        .filter((name) => {
+        const value = authValues[name];
+        return typeof value !== "string" || value.length === 0;
+    })
+        .sort();
+    if (missing.length > 0) {
+        throw new SpawnfileError("validation_error", `Missing required secrets for this image: ${missing.join(", ")}. ` +
+            "Provide them through the selected auth profile or env file.");
+    }
+    return {
+        generatedSecrets: [...generatedSecrets].sort(),
+        requiredSecrets: [...requiredSecrets].sort()
+    };
+};

package/dist/distribution/projectImageView.d.ts

@@ -0,0 +1,8 @@
+import type { OrganizationView } from "../compiler/index.js";
+import type { DistributionReport } from "./types.js";
+/**
+ * Projects a distribution report into an OrganizationView so sourceless image
+ * status can reuse the existing renderer. There is no source, so the declared
+ * layer is intentionally sparse; node sources use an image placeholder.
+ */
+export declare const projectImageOrganizationView: (report: DistributionReport, inputPath: string) => OrganizationView;

package/dist/distribution/projectImageView.js

@@ -0,0 +1,83 @@
+const IMAGE_SOURCE_PLACEHOLDER = "<image>";
+const buildAgentNode = (agent) => ({
+    children: [],
+    displayName: agent.name,
+    id: agent.id,
+    kind: "agent",
+    name: agent.name,
+    runtimeName: agent.runtime,
+    source: IMAGE_SOURCE_PLACEHOLDER
+});
+/**
+ * Projects a distribution report into an OrganizationView so sourceless image
+ * status can reuse the existing renderer. There is no source, so the declared
+ * layer is intentionally sparse; node sources use an image placeholder.
+ */
+export const projectImageOrganizationView = (report, inputPath) => {
+    const agentsById = new Map(report.organization.agents.map((agent) => [agent.id, agent]));
+    const teams = report.organization.teams;
+    const networks = report.moltnet.networks.map((network) => ({
+        declaringTeamName: report.organization.project,
+        declaringTeamSource: IMAGE_SOURCE_PLACEHOLDER,
+        id: network.id,
+        name: network.id,
+        provider: "moltnet",
+        rooms: [],
+        serverMode: network.server_mode
+    }));
+    const runtimes = [
+        ...new Map(report.runtime_instances.map((instance) => [
+            instance.runtime,
+            {
+                name: instance.runtime,
+                nodeIds: report.runtime_instances
+                    .filter((other) => other.runtime === instance.runtime)
+                    .flatMap((other) => other.node_ids)
+                    .sort()
+            }
+        ])).values()
+    ].sort((left, right) => left.name.localeCompare(right.name));
+    let root;
+    if (teams.length > 0) {
+        const rootTeam = teams[0];
+        const memberEdges = rootTeam.agents
+            .map((agentId) => agentsById.get(agentId))
+            .filter((agent) => agent !== undefined)
+            .map((agent) => ({
+            label: agent.id,
+            node: buildAgentNode(agent),
+            relation: "team_member"
+        }));
+        root = {
+            children: memberEdges,
+            displayName: rootTeam.name,
+            id: rootTeam.id,
+            kind: "team",
+            name: rootTeam.name,
+            runtimeName: null,
+            source: IMAGE_SOURCE_PLACEHOLDER
+        };
+    }
+    else if (report.organization.agents.length > 0) {
+        root = buildAgentNode(report.organization.agents[0]);
+    }
+    else {
+        root = {
+            children: [],
+            displayName: report.organization.project,
+            id: report.organization.project,
+            kind: "team",
+            name: report.organization.project,
+            runtimeName: null,
+            source: IMAGE_SOURCE_PLACEHOLDER
+        };
+    }
+    return {
+        contexts: [],
+        diagnostics: [],
+        inputPath,
+        networks,
+        root,
+        runtimes
+    };
+};

package/dist/distribution/projectName.d.ts

@@ -0,0 +1 @@
+export declare const normalizeProjectLabelSlug: (projectName: string) => string;

package/dist/distribution/projectName.js

@@ -0,0 +1,12 @@
+import { SpawnfileError } from "../shared/index.js";
+const LABEL_VALUE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+export const normalizeProjectLabelSlug = (projectName) => {
+    const slug = projectName
+        .replace(/[^A-Za-z0-9_.:-]+/g, "-")
+        .replace(/^[^A-Za-z0-9]+/, "")
+        .replace(/-+$/, "");
+    if (!slug || !LABEL_VALUE_PATTERN.test(slug)) {
+        throw new SpawnfileError("validation_error", `Project name ${JSON.stringify(projectName)} cannot be normalized into a label-safe slug`);
+    }
+    return slug;
+};

package/dist/distribution/renderImageInterface.d.ts

@@ -0,0 +1,30 @@
+import type { DistributionReport } from "./types.js";
+export interface RenderImageInterfaceOptions {
+    imageRef: string;
+    json?: boolean;
+}
+export interface ImageInterfaceSummary {
+    agents: Array<{
+        id: string;
+        name: string;
+        runtime: string | null;
+        teams: string[];
+    }>;
+    compileFingerprint: string;
+    generatedAt: string;
+    imageRef: string;
+    networks: Array<{
+        id: string;
+        serverMode: string;
+    }>;
+    ports: number[];
+    project: string;
+    requiredSecrets: string[];
+    teams: Array<{
+        agents: string[];
+        id: string;
+        name: string;
+    }>;
+}
+export declare const buildImageInterfaceSummary: (report: DistributionReport, imageRef: string) => ImageInterfaceSummary;
+export declare const renderImageInterface: (report: DistributionReport, options: RenderImageInterfaceOptions) => string;

package/dist/distribution/renderImageInterface.js

@@ -0,0 +1,86 @@
+export const buildImageInterfaceSummary = (report, imageRef) => {
+    const categories = ["model", "project", "runtime", "surface"];
+    const requiredSecrets = new Set();
+    for (const category of categories) {
+        for (const entry of report.secrets[category]) {
+            if (entry.required && !entry.generated) {
+                requiredSecrets.add(entry.name);
+            }
+        }
+    }
+    return {
+        agents: report.organization.agents.map((agent) => ({
+            id: agent.id,
+            name: agent.name,
+            runtime: agent.runtime,
+            teams: agent.teams
+        })),
+        compileFingerprint: report.compile_fingerprint,
+        generatedAt: report.generated_at,
+        imageRef,
+        networks: report.moltnet.networks.map((network) => ({
+            id: network.id,
+            serverMode: network.server_mode
+        })),
+        ports: [...report.ports].sort((left, right) => left - right),
+        project: report.organization.project,
+        requiredSecrets: [...requiredSecrets].sort(),
+        teams: report.organization.teams.map((team) => ({
+            agents: team.agents,
+            id: team.id,
+            name: team.name
+        }))
+    };
+};
+export const renderImageInterface = (report, options) => {
+    const summary = buildImageInterfaceSummary(report, options.imageRef);
+    if (options.json) {
+        return JSON.stringify(summary, null, 2);
+    }
+    const lines = [];
+    lines.push(`Image: ${summary.imageRef}`);
+    lines.push(`Project: ${summary.project}`);
+    lines.push(`Compiled: ${summary.compileFingerprint} (${summary.generatedAt})`);
+    lines.push("Declared status is unavailable for image references (no source).");
+    lines.push("");
+    lines.push("Agents");
+    for (const agent of summary.agents) {
+        const runtime = agent.runtime ?? "unbound";
+        const teams = agent.teams.length > 0 ? ` teams=${agent.teams.join(",")}` : "";
+        lines.push(`  ${agent.id}  ${runtime}${teams}`);
+    }
+    if (summary.teams.length > 0) {
+        lines.push("");
+        lines.push("Teams");
+        for (const team of summary.teams) {
+            lines.push(`  ${team.id}  members=${team.agents.join(",") || "none"}`);
+        }
+    }
+    if (summary.networks.length > 0) {
+        lines.push("");
+        lines.push("Networks");
+        for (const network of summary.networks) {
+            lines.push(`  ${network.id}  ${network.serverMode}`);
+        }
+    }
+    lines.push("");
+    lines.push("Required secrets");
+    if (summary.requiredSecrets.length > 0) {
+        for (const secret of summary.requiredSecrets) {
+            lines.push(`  ${secret}`);
+        }
+    }
+    else {
+        lines.push("  none");
+    }
+    if (summary.ports.length > 0) {
+        lines.push("");
+        lines.push(`Published ports: ${summary.ports.join(", ")}`);
+    }
+    lines.push("");
+    lines.push(`next: spawnfile up ${summary.imageRef} --auth-profile <profile>`);
+    if (summary.requiredSecrets.length > 0) {
+        lines.push("  supply the required secrets above via that profile or --env-file");
+    }
+    return lines.join("\n");
+};

package/dist/distribution/tarReader.d.ts

@@ -0,0 +1,10 @@
+export interface ExtractSingleFileOptions {
+    maxBytes: number;
+}
+/**
+ * Extracts exactly one regular file from a (single-file) tar stream such as the
+ * output of `docker cp <container>:<file> -`. Rejects symlinks, hardlinks,
+ * directories, path traversal, and oversized payloads, because the stream is
+ * untrusted input pulled from a registry.
+ */
+export declare const extractSingleFileFromTar: (tar: Buffer, options: ExtractSingleFileOptions) => Buffer;

package/dist/distribution/tarReader.js

@@ -0,0 +1,69 @@
+import { SpawnfileError } from "../shared/index.js";
+const BLOCK_SIZE = 512;
+const parseOctal = (buffer, offset, length) => {
+    const raw = buffer
+        .subarray(offset, offset + length)
+        .toString("ascii")
+        .replace(/\0.*$/, "")
+        .trim();
+    if (raw === "") {
+        return 0;
+    }
+    const parsed = Number.parseInt(raw, 8);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new SpawnfileError("validation_error", "Malformed tar header: invalid numeric field");
+    }
+    return parsed;
+};
+const isZeroBlock = (block) => block.every((byte) => byte === 0);
+/**
+ * Extracts exactly one regular file from a (single-file) tar stream such as the
+ * output of `docker cp <container>:<file> -`. Rejects symlinks, hardlinks,
+ * directories, path traversal, and oversized payloads, because the stream is
+ * untrusted input pulled from a registry.
+ */
+export const extractSingleFileFromTar = (tar, options) => {
+    let offset = 0;
+    let result = null;
+    while (offset + BLOCK_SIZE <= tar.length) {
+        const header = tar.subarray(offset, offset + BLOCK_SIZE);
+        if (isZeroBlock(header)) {
+            break;
+        }
+        offset += BLOCK_SIZE;
+        const name = header.subarray(0, 100).toString("ascii").replace(/\0.*$/, "");
+        const size = parseOctal(header, 124, 12);
+        const typeFlag = String.fromCharCode(header[156] ?? 0);
+        if (typeFlag === "5") {
+            throw new SpawnfileError("validation_error", `Refusing tar directory entry: ${name}`);
+        }
+        if (typeFlag === "2" || typeFlag === "1") {
+            throw new SpawnfileError("validation_error", `Refusing tar link entry: ${name}`);
+        }
+        if (typeFlag !== "0" && typeFlag !== "\0") {
+            // Skip metadata entries (pax headers, global headers) without treating
+            // them as the payload.
+            offset += Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+            continue;
+        }
+        if (name.includes("..")) {
+            throw new SpawnfileError("validation_error", `Refusing tar entry with traversal: ${name}`);
+        }
+        if (size > options.maxBytes) {
+            throw new SpawnfileError("validation_error", `Embedded report exceeds the ${options.maxBytes}-byte size cap`);
+        }
+        if (result) {
+            throw new SpawnfileError("validation_error", "Expected a single-file tar stream but found multiple file entries");
+        }
+        const contentEnd = offset + size;
+        if (contentEnd > tar.length) {
+            throw new SpawnfileError("validation_error", "Truncated tar stream");
+        }
+        result = Buffer.from(tar.subarray(offset, contentEnd));
+        offset += Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+    }
+    if (!result) {
+        throw new SpawnfileError("validation_error", "No file entry found in tar stream");
+    }
+    return result;
+};

package/dist/distribution/types.d.ts

@@ -0,0 +1,80 @@
+import type { ModelAuthMethod } from "../shared/index.js";
+export type DistributionSecretCategory = "model" | "project" | "runtime" | "surface";
+export interface DistributionSecretEntry {
+    generated: boolean;
+    name: string;
+    required: boolean;
+}
+export interface DistributionAgentSummary {
+    id: string;
+    name: string;
+    runtime: string | null;
+    teams: string[];
+}
+export interface DistributionTeamSummary {
+    agents: string[];
+    id: string;
+    name: string;
+}
+export interface DistributionOrganizationSummary {
+    agents: DistributionAgentSummary[];
+    project: string;
+    teams: DistributionTeamSummary[];
+}
+export interface DistributionPersistentMount {
+    durability: "persistent";
+    id: string;
+    kind: "volume";
+    target: string;
+}
+export interface DistributionWorkspaceResource {
+    id: string;
+    kind: "git" | "volume";
+    link_path: string;
+    mode: "mutable" | "readonly";
+    mount: string;
+    sharing: "per_agent" | "team";
+}
+export interface DistributionRuntimeInstance {
+    config_path: string;
+    home_path: string | null;
+    id: string;
+    internal_port: number | null;
+    model_auth_methods: Record<string, ModelAuthMethod>;
+    model_secrets_required: string[];
+    node_ids: string[];
+    published_port: number | null;
+    runtime: string;
+    workspace_path: string;
+}
+export interface DistributionMoltnetNetwork {
+    binding: "env";
+    id: string;
+    server_mode: "external" | "managed";
+}
+export interface DistributionPortMapping {
+    internal_port: number;
+    published_port: number;
+}
+export interface DistributionReport {
+    compile_fingerprint: string;
+    generated_at: string;
+    internal_ports: number[];
+    model_auth_methods: Record<string, ModelAuthMethod>;
+    moltnet: {
+        networks: DistributionMoltnetNetwork[];
+    };
+    organization: DistributionOrganizationSummary;
+    persistent_mounts: DistributionPersistentMount[];
+    port_mappings: DistributionPortMapping[];
+    ports: number[];
+    resources: DistributionWorkspaceResource[];
+    runtime_instances: DistributionRuntimeInstance[];
+    secrets: Record<DistributionSecretCategory, DistributionSecretEntry[]>;
+    version: "spawnfile.distribution-report.v1";
+}
+export declare const DISTRIBUTION_REPORT_VERSION = "spawnfile.distribution-report.v1";
+export declare const DISTRIBUTION_REPORT_IMAGE_PATH = "/spawnfile/spawnfile-report.json";
+export declare const DISTRIBUTION_REPORT_OUTPUT_FILE = "distribution-report.json";
+export declare const IMAGE_CONTRACT_VERSION = "spawnfile.image.v1";
+export type DistributionImageLabels = Record<"com.spawnfile.compile_fingerprint" | "com.spawnfile.image_contract" | "com.spawnfile.project" | "com.spawnfile.report", string> & Record<string, string>;

package/dist/distribution/types.js

@@ -0,0 +1,4 @@
+export const DISTRIBUTION_REPORT_VERSION = "spawnfile.distribution-report.v1";
+export const DISTRIBUTION_REPORT_IMAGE_PATH = "/spawnfile/spawnfile-report.json";
+export const DISTRIBUTION_REPORT_OUTPUT_FILE = "distribution-report.json";
+export const IMAGE_CONTRACT_VERSION = "spawnfile.image.v1";

package/dist/distribution/verifyDistributionReport.d.ts

@@ -0,0 +1,12 @@
+import type { DistributionReport } from "./types.js";
+export interface VerifyDistributionReportInput {
+    forbiddenPathFragments?: string[];
+    report: unknown;
+}
+/**
+ * Pre-push verification for a published image's distribution report. Confirms
+ * the report parses, is free of creator host-path fragments, and that every
+ * secret entry carries the required/generated markers. Throws on any violation
+ * so publishing refuses to ship a leaky or malformed image.
+ */
+export declare const verifyDistributionReport: (input: VerifyDistributionReportInput) => DistributionReport;

package/dist/distribution/verifyDistributionReport.js

@@ -0,0 +1,29 @@
+import { parseDistributionReport } from "./distributionReportSchema.js";
+import { SpawnfileError } from "../shared/index.js";
+/**
+ * Pre-push verification for a published image's distribution report. Confirms
+ * the report parses, is free of creator host-path fragments, and that every
+ * secret entry carries the required/generated markers. Throws on any violation
+ * so publishing refuses to ship a leaky or malformed image.
+ */
+export const verifyDistributionReport = (input) => {
+    const report = parseDistributionReport(input.report, "distribution report for publish");
+    const serialized = JSON.stringify(report);
+    for (const fragment of input.forbiddenPathFragments ?? []) {
+        const trimmed = fragment.trim();
+        if (trimmed.length > 0 && serialized.includes(trimmed)) {
+            throw new SpawnfileError("validation_error", `Distribution report leaks a creator path fragment and must not be published: ${trimmed}`);
+        }
+    }
+    if (serialized.includes("/Users/") || serialized.includes("\\Users\\")) {
+        throw new SpawnfileError("validation_error", "Distribution report contains an absolute home path and must not be published");
+    }
+    for (const category of ["model", "project", "runtime", "surface"]) {
+        for (const entry of report.secrets[category]) {
+            if (typeof entry.required !== "boolean" || typeof entry.generated !== "boolean") {
+                throw new SpawnfileError("validation_error", `Secret ${entry.name} is missing required/generated markers`);
+            }
+        }
+    }
+    return report;
+};

package/dist/filesystem/paths.d.ts

@@ -2,5 +2,11 @@ export declare const assertPortableRelativePath: (inputPath: string) => void;
 export declare const getCanonicalManifestPath: (filePath: string) => string;
 export declare const getManifestPath: (inputPath: string) => string;
 export declare const getProjectRoot: (manifestPath: string) => string;
+/**
+ * Resolves the output/record directory for a project argument. An explicit
+ * `--out` is honored as given; otherwise the default lives under the resolved
+ * project root, not the process working directory.
+ */
+export declare const resolveProjectOutputDirectory: (inputPath: string, outOption: string | undefined, defaultOutputName: string) => string;
 export declare const resolveProjectPath: (manifestPath: string, relativePath: string) => string;
 export declare const toPosixPath: (value: string) => string;

package/dist/filesystem/paths.js

@@ -13,6 +13,17 @@ export const getManifestPath = (inputPath) => path.basename(inputPath) === "Spaw
     ? path.resolve(inputPath)
     : path.resolve(inputPath, "Spawnfile");
 export const getProjectRoot = (manifestPath) => path.dirname(manifestPath);
+/**
+ * Resolves the output/record directory for a project argument. An explicit
+ * `--out` is honored as given; otherwise the default lives under the resolved
+ * project root, not the process working directory.
+ */
+export const resolveProjectOutputDirectory = (inputPath, outOption, defaultOutputName) => {
+    if (outOption) {
+        return path.resolve(outOption);
+    }
+    return path.join(getProjectRoot(getManifestPath(inputPath)), defaultOutputName);
+};
 export const resolveProjectPath = (manifestPath, relativePath) => {
     assertPortableRelativePath(relativePath);
     const projectRoot = getProjectRoot(manifestPath);

package/dist/manifest/loadManifest.js

@@ -115,8 +115,18 @@ const validateLocalTeamManifest = async (manifestPath, manifest) => {
     }
 };
 const parseManifest = (source) => {
+    let parsed;
     try {
-        return manifestSchema.parse(parseYaml(source));
+        parsed = parseYaml(source);
+    }
+    catch (error) {
+        // A YAML syntax error is a malformed manifest, not a runtime failure — wrap
+        // it so it exits as a usage error instead of leaking the parser's wording.
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("invalid_manifest", `Invalid Spawnfile manifest: ${reason}`);
+    }
+    try {
+        return manifestSchema.parse(parsed);
     }
     catch (error) {
         if (error instanceof z.ZodError) {
@@ -127,7 +137,17 @@ const parseManifest = (source) => {
     }
 };
 export const loadManifest = async (manifestPath) => {
-    const source = await readUtf8File(manifestPath);
+    let source;
+    try {
+        source = await readUtf8File(manifestPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            // A missing Spawnfile is a usage/input error, not a runtime failure.
+            throw new SpawnfileError("validation_error", `No Spawnfile found at ${manifestPath}. Pass a project directory or Spawnfile path, or run 'spawnfile init'.`);
+        }
+        throw error;
+    }
     const manifest = parseManifest(source);
     if (isAgentManifest(manifest)) {
         await validateLocalAgentManifest(manifestPath, manifest);

package/dist/manifest/renderSpawnfile.js

@@ -67,8 +67,7 @@ const orderMoltnetRoomBehavior = (behavior) => {
         return undefined;
     }
     return withDefinedEntries([
-        ["read", behavior.read],
-        ["reply", behavior.reply]
+        ["wake", behavior.wake]
     ]);
 };
 const orderMoltnetDm = (dms) => {
@@ -77,8 +76,7 @@ const orderMoltnetDm = (dms) => {
     }
     return withDefinedEntries([
         ["enabled", dms.enabled],
-        ["read", dms.read],
-        ["reply", dms.reply]
+        ["wake", dms.wake]
     ]);
 };
 const orderMoltnetAttachment = (attachment) => withDefinedEntries([