spawnfile 0.1.10 → 0.1.12

package/dist/distribution/extractImage.js

@@ -0,0 +1,96 @@
+import { SpawnfileError } from "../shared/index.js";
+import { createConsumerDockerRunner } from "./dockerRunner.js";
+import { parseDistributionReport } from "./distributionReportSchema.js";
+import { extractSingleFileFromTar } from "./tarReader.js";
+import { DISTRIBUTION_REPORT_IMAGE_PATH, IMAGE_CONTRACT_VERSION } from "./types.js";
+const REPORT_SIZE_CAP_BYTES = 4 * 1024 * 1024;
+const LABEL_VALUE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+export const resolveDockerBaseArgs = (options) => {
+    if (options.dockerContext) {
+        return ["--context", options.dockerContext];
+    }
+    if (options.dockerHost) {
+        return ["--host", options.dockerHost];
+    }
+    return [];
+};
+const assertContractLabels = (labels) => {
+    const contract = labels["com.spawnfile.image_contract"];
+    if (!contract) {
+        throw new SpawnfileError("validation_error", "Image is not a Spawnfile image: missing com.spawnfile.image_contract label");
+    }
+    if (contract !== IMAGE_CONTRACT_VERSION) {
+        throw new SpawnfileError("validation_error", `Unsupported image contract ${contract}; this CLI supports ${IMAGE_CONTRACT_VERSION}`);
+    }
+    for (const key of ["com.spawnfile.project", "com.spawnfile.compile_fingerprint"]) {
+        const value = labels[key];
+        if (!value || !LABEL_VALUE_PATTERN.test(value)) {
+            throw new SpawnfileError("validation_error", `Image label ${key} is missing or not identifier-only`);
+        }
+    }
+};
+/**
+ * Pulls (optionally), inspects labels, and extracts the embedded distribution
+ * report from an image without starting its entrypoint. Uses a stopped helper
+ * container and guarantees cleanup.
+ */
+export const extractImageReport = async (imageRef, options = {}) => {
+    const dockerCommand = options.dockerCommand ?? "docker";
+    const baseArgs = resolveDockerBaseArgs(options);
+    const runDocker = options.runDocker ?? createConsumerDockerRunner(dockerCommand, baseArgs);
+    if (options.pull) {
+        await runDocker(["pull", imageRef]);
+    }
+    let labelsRaw;
+    try {
+        labelsRaw = (await runDocker([
+            "image",
+            "inspect",
+            "--format",
+            "{{json .Config.Labels}}",
+            imageRef
+        ])).toString("utf8").trim();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/No such image|not found/i.test(message)) {
+            throw new SpawnfileError("validation_error", `Image ${imageRef} is not available locally. Pull it first with --pull, or publish it with 'spawnfile publish'.`);
+        }
+        throw error;
+    }
+    let labels;
+    try {
+        labels = JSON.parse(labelsRaw) ?? {};
+    }
+    catch {
+        throw new SpawnfileError("validation_error", `Unable to read labels for image ${imageRef}`);
+    }
+    assertContractLabels(labels);
+    const reportPath = labels["com.spawnfile.report"] ?? DISTRIBUTION_REPORT_IMAGE_PATH;
+    const helperName = `spawnfile-inspect-${Date.now().toString(36)}-${Math.floor(Number(process.pid)).toString(36)}`;
+    await runDocker(["create", "--name", helperName, imageRef]);
+    let tar;
+    try {
+        tar = await runDocker(["cp", `${helperName}:${reportPath}`, "-"]);
+    }
+    finally {
+        await runDocker(["rm", "-f", helperName]).catch(() => undefined);
+    }
+    const reportBytes = extractSingleFileFromTar(tar, { maxBytes: REPORT_SIZE_CAP_BYTES });
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(reportBytes.toString("utf8"));
+    }
+    catch {
+        throw new SpawnfileError("validation_error", `Embedded report in ${imageRef} is not valid JSON`);
+    }
+    const report = parseDistributionReport(parsedJson, `embedded report in ${imageRef}`);
+    if (report.compile_fingerprint !== labels["com.spawnfile.compile_fingerprint"]) {
+        throw new SpawnfileError("validation_error", `Embedded report fingerprint does not match the image label for ${imageRef}`);
+    }
+    return {
+        compileFingerprint: report.compile_fingerprint,
+        labels,
+        report
+    };
+};

package/dist/distribution/fingerprint.d.ts

@@ -0,0 +1,2 @@
+import type { DistributionReport } from "./types.js";
+export declare const createDistributionFingerprint: (report: Omit<DistributionReport, "compile_fingerprint" | "generated_at">) => string;

package/dist/distribution/fingerprint.js

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+const stableStringify = (value) => {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+export const createDistributionFingerprint = (report) => `sf1:${createHash("sha1").update(stableStringify(report)).digest("hex").slice(0, 12)}`;

package/dist/distribution/imageRef.d.ts

@@ -0,0 +1,9 @@
+export interface ParsedImageReference {
+    digest: string | null;
+    name: string;
+    registry: string | null;
+    tag: string | null;
+}
+export declare const parseImageReference: (value: string) => ParsedImageReference | null;
+export declare const parseImplicitImageReference: (value: string) => ParsedImageReference | null;
+export declare const hasRegistryComponent: (value: string) => boolean;

package/dist/distribution/imageRef.js

@@ -0,0 +1,65 @@
+const NAME_COMPONENT = /^[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*$/;
+const TAG_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
+const REGISTRY_HOST_PATTERN = /^[a-zA-Z0-9.-]+(?::\d{1,5})?$/;
+const isRegistryComponent = (component) => (component.includes(".") || component.includes(":") || component === "localhost")
+    && REGISTRY_HOST_PATTERN.test(component);
+const splitDigest = (value) => {
+    const index = value.indexOf("@");
+    if (index === -1) {
+        return { digest: null, rest: value };
+    }
+    return { digest: value.slice(index + 1), rest: value.slice(0, index) };
+};
+const splitTag = (value) => {
+    const slashIndex = value.lastIndexOf("/");
+    const colonIndex = value.lastIndexOf(":");
+    if (colonIndex === -1 || colonIndex < slashIndex) {
+        return { rest: value, tag: null };
+    }
+    return { rest: value.slice(0, colonIndex), tag: value.slice(colonIndex + 1) };
+};
+export const parseImageReference = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed || /\s/.test(trimmed)) {
+        return null;
+    }
+    const { digest, rest: withoutDigest } = splitDigest(trimmed);
+    if (digest !== null && !DIGEST_PATTERN.test(digest)) {
+        return null;
+    }
+    const { rest: repository, tag } = splitTag(withoutDigest);
+    if (tag !== null && !TAG_PATTERN.test(tag)) {
+        return null;
+    }
+    if (!repository) {
+        return null;
+    }
+    const components = repository.split("/");
+    let registry = null;
+    let nameComponents = components;
+    if (components.length > 1 && isRegistryComponent(components[0])) {
+        registry = components[0];
+        nameComponents = components.slice(1);
+    }
+    if (nameComponents.length === 0 || nameComponents.some((component) => !NAME_COMPONENT.test(component))) {
+        return null;
+    }
+    return {
+        digest,
+        name: nameComponents.join("/"),
+        registry,
+        tag
+    };
+};
+export const parseImplicitImageReference = (value) => {
+    const parsed = parseImageReference(value);
+    if (!parsed) {
+        return null;
+    }
+    if (parsed.digest === null && parsed.tag === null && parsed.registry === null) {
+        return null;
+    }
+    return parsed;
+};
+export const hasRegistryComponent = (value) => parseImageReference(value)?.registry !== null;

package/dist/distribution/imageRuntimeAuth.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedAuthProfile } from "../auth/index.js";
+import type { DistributionReport } from "./types.js";
+export interface ImageRuntimeAuthInput {
+    authProfile: ResolvedAuthProfile;
+    report: DistributionReport;
+    tempRoot: string;
+}
+export interface ImageRuntimeAuthResult {
+    coveredModelSecrets: Set<string>;
+    mountArgs: string[];
+}
+/**
+ * Builds the credential mounts for a sourceless image deployment that uses
+ * import-based model auth. The OAuth-mode config is already baked into the
+ * image, so this only mounts the consumer's credential tokens (per-adapter) and
+ * their raw import directories into each runtime home — the same material a
+ * project deployment provides, without needing the project source.
+ */
+export declare const prepareImageRuntimeAuthMounts: (input: ImageRuntimeAuthInput) => Promise<ImageRuntimeAuthResult>;

package/dist/distribution/imageRuntimeAuth.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { loadImportedClaudeCodeCredential, loadImportedCodexCredential } from "../auth/index.js";
+import { fileExists } from "../filesystem/index.js";
+import { getRuntimeAdapter } from "../runtime/index.js";
+import { SpawnfileError } from "../shared/index.js";
+const importMountTargetName = (kind) => kind === "claude-code" ? ".claude" : ".codex";
+/**
+ * Builds the credential mounts for a sourceless image deployment that uses
+ * import-based model auth. The OAuth-mode config is already baked into the
+ * image, so this only mounts the consumer's credential tokens (per-adapter) and
+ * their raw import directories into each runtime home — the same material a
+ * project deployment provides, without needing the project source.
+ */
+export const prepareImageRuntimeAuthMounts = async (input) => {
+    const coveredModelSecrets = new Set();
+    const mountArgs = [];
+    const runtimeHomes = new Set();
+    for (const instance of input.report.runtime_instances) {
+        if (instance.home_path) {
+            runtimeHomes.add(instance.home_path);
+        }
+        const adapter = getRuntimeAdapter(instance.runtime);
+        if (!adapter.prepareRuntimeAuth) {
+            continue;
+        }
+        const prepared = await adapter.prepareRuntimeAuth({
+            authProfile: input.authProfile,
+            env: {},
+            instance: {
+                config_path: instance.config_path,
+                home_path: instance.home_path,
+                id: instance.id,
+                model_auth_methods: instance.model_auth_methods,
+                model_secrets_required: instance.model_secrets_required,
+                runtime: instance.runtime
+            },
+            outputDirectory: "",
+            tempRoot: input.tempRoot
+        });
+        for (const secret of prepared.coveredModelSecrets) {
+            coveredModelSecrets.add(secret);
+        }
+        mountArgs.push(...prepared.mountArgs);
+    }
+    // Mount the raw credential import directories into each runtime home so the
+    // runtime's OAuth client can read them (e.g. ~/.claude, ~/.codex).
+    for (const kind of ["claude-code", "codex"]) {
+        const entry = input.authProfile.imports[kind];
+        if (!entry) {
+            continue;
+        }
+        if (!(await fileExists(entry.path))) {
+            throw new SpawnfileError("validation_error", `Imported auth path for ${kind} does not exist: ${entry.path}`);
+        }
+        // The directory existing is not enough: a registered import whose credential
+        // file is missing, expired, or malformed would mount cleanly but produce a
+        // container that cannot authenticate. Load it now so the failure surfaces
+        // before the container starts, mirroring the project-deployment path.
+        const credential = kind === "claude-code"
+            ? await loadImportedClaudeCodeCredential(entry.path)
+            : await loadImportedCodexCredential(entry.path);
+        if (!credential) {
+            throw new SpawnfileError("validation_error", `Imported ${kind} auth at ${entry.path} has no usable credential. ` +
+                `Re-run the ${kind} login (or re-import) before deploying this image.`);
+        }
+        for (const home of runtimeHomes) {
+            mountArgs.push("-v", `${entry.path}:${path.posix.join(home, importMountTargetName(kind))}`);
+        }
+    }
+    return { coveredModelSecrets, mountArgs };
+};

package/dist/distribution/index.d.ts

@@ -0,0 +1,24 @@
+export { buildDistributionReport, createDistributionImageLabels } from "./buildDistributionReport.js";
+export type { BuildDistributionReportInput, DistributionEnvVariableInput } from "./buildDistributionReport.js";
+export { createDistributionFingerprint } from "./fingerprint.js";
+export { extractImageReport, resolveDockerBaseArgs } from "./extractImage.js";
+export type { DockerCommandRunner, ExtractImageOptions, ImageInspection } from "./extractImage.js";
+export { parseDistributionReport } from "./distributionReportSchema.js";
+export { consumeImageUp } from "./consumeImage.js";
+export type { ConsumeImageUpOptions, ConsumeImageUpResult } from "./consumeImage.js";
+export { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+export { createConsumerDockerRunner } from "./dockerRunner.js";
+export { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
+export { runImagePreflight } from "./preflight.js";
+export { verifyDistributionReport } from "./verifyDistributionReport.js";
+export type { VerifyDistributionReportInput } from "./verifyDistributionReport.js";
+export { projectImageOrganizationView } from "./projectImageView.js";
+export { buildImageInterfaceSummary, renderImageInterface } from "./renderImageInterface.js";
+export type { ImageInterfaceSummary, RenderImageInterfaceOptions } from "./renderImageInterface.js";
+export type { PreflightInput, PreflightResult } from "./preflight.js";
+export { extractSingleFileFromTar } from "./tarReader.js";
+export { hasRegistryComponent, parseImageReference, parseImplicitImageReference } from "./imageRef.js";
+export type { ParsedImageReference } from "./imageRef.js";
+export { normalizeProjectLabelSlug } from "./projectName.js";
+export { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_OUTPUT_FILE, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION } from "./types.js";
+export type { DistributionAgentSummary, DistributionImageLabels, DistributionMoltnetNetwork, DistributionOrganizationSummary, DistributionPersistentMount, DistributionPortMapping, DistributionReport, DistributionRuntimeInstance, DistributionSecretCategory, DistributionSecretEntry, DistributionTeamSummary, DistributionWorkspaceResource } from "./types.js";

package/dist/distribution/index.js

@@ -0,0 +1,16 @@
+export { buildDistributionReport, createDistributionImageLabels } from "./buildDistributionReport.js";
+export { createDistributionFingerprint } from "./fingerprint.js";
+export { extractImageReport, resolveDockerBaseArgs } from "./extractImage.js";
+export { parseDistributionReport } from "./distributionReportSchema.js";
+export { consumeImageUp } from "./consumeImage.js";
+export { deriveDeploymentName, deriveVolumeName, renderEnvFileContent, resolveImageEnvironment } from "./consumeImageSupport.js";
+export { createConsumerDockerRunner } from "./dockerRunner.js";
+export { prepareImageRuntimeAuthMounts } from "./imageRuntimeAuth.js";
+export { runImagePreflight } from "./preflight.js";
+export { verifyDistributionReport } from "./verifyDistributionReport.js";
+export { projectImageOrganizationView } from "./projectImageView.js";
+export { buildImageInterfaceSummary, renderImageInterface } from "./renderImageInterface.js";
+export { extractSingleFileFromTar } from "./tarReader.js";
+export { hasRegistryComponent, parseImageReference, parseImplicitImageReference } from "./imageRef.js";
+export { normalizeProjectLabelSlug } from "./projectName.js";
+export { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_OUTPUT_FILE, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION } from "./types.js";

package/dist/distribution/preflight.d.ts

@@ -0,0 +1,11 @@
+import type { DistributionReport } from "./types.js";
+export interface PreflightInput {
+    authValues: Record<string, string>;
+    availableImports?: string[];
+    report: DistributionReport;
+}
+export interface PreflightResult {
+    generatedSecrets: string[];
+    requiredSecrets: string[];
+}
+export declare const runImagePreflight: (input: PreflightInput) => PreflightResult;

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;