spawnfile 0.1.10 → 0.1.12

package/dist/deployment/index.js

@@ -0,0 +1,9 @@
+export * from "./dockerLabels.js";
+export * from "./dockerInspect.js";
+export * from "./dockerLogs.js";
+export * from "./dockerManager.js";
+export * from "./dockerProbeGateway.js";
+export * from "./homeStore.js";
+export * from "./names.js";
+export * from "./record.js";
+export * from "./target.js";

package/dist/deployment/names.d.ts

@@ -0,0 +1,3 @@
+export declare const normalizeDeploymentName: (name: string | undefined) => string;
+export declare const resolveDeploymentRecordsDirectory: (outputDirectory: string) => string;
+export declare const resolveDeploymentRecordPath: (outputDirectory: string, deploymentName: string) => string;

package/dist/deployment/names.js

@@ -0,0 +1,12 @@
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+const deploymentNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const normalizeDeploymentName = (name) => {
+    const normalized = (name ?? "default").trim();
+    if (!deploymentNamePattern.test(normalized)) {
+        throw new SpawnfileError("validation_error", `Deployment name must be kebab-case: ${name ?? ""}`);
+    }
+    return normalized;
+};
+export const resolveDeploymentRecordsDirectory = (outputDirectory) => path.join(outputDirectory, "deployments");
+export const resolveDeploymentRecordPath = (outputDirectory, deploymentName) => path.join(resolveDeploymentRecordsDirectory(outputDirectory), `${normalizeDeploymentName(deploymentName)}.json`);

package/dist/deployment/record.d.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+declare const recordSourceSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"project">;
+    root: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    digest: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"image">;
+    ref: z.ZodString;
+}, z.core.$strict>]>;
+export type DeploymentRecordSource = z.infer<typeof recordSourceSchema>;
+export declare const deploymentRecordSchema: z.ZodObject<{
+    auth_profile: z.ZodNullable<z.ZodString>;
+    compile_fingerprint: z.ZodString;
+    created_at: z.ZodString;
+    env_file: z.ZodOptional<z.ZodString>;
+    manager: z.ZodString;
+    name: z.ZodString;
+    output_directory: z.ZodNullable<z.ZodString>;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"project">;
+        root: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        digest: z.ZodNullable<z.ZodString>;
+        kind: z.ZodLiteral<"image">;
+        ref: z.ZodString;
+    }, z.core.$strict>]>;
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        endpoint_fingerprint: z.ZodString;
+        kind: z.ZodLiteral<"context">;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        context: z.ZodString;
+        endpoint_fingerprint: z.ZodString;
+        kind: z.ZodLiteral<"docker-context">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"host">;
+        value: z.ZodString;
+    }, z.core.$strict>]>;
+    units: z.ZodArray<z.ZodObject<{
+        container_id: z.ZodNullable<z.ZodString>;
+        container_name: z.ZodNullable<z.ZodString>;
+        contains: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodUnion<readonly [z.ZodLiteral<"agent">, z.ZodLiteral<"network">, z.ZodLiteral<"team">]>;
+        }, z.core.$strict>>;
+        id: z.ZodString;
+        image_id: z.ZodNullable<z.ZodString>;
+        image_tag: z.ZodString;
+        kind: z.ZodLiteral<"container">;
+        manager: z.ZodOptional<z.ZodString>;
+        runtime_instances: z.ZodArray<z.ZodString>;
+        target: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            endpoint_fingerprint: z.ZodString;
+            kind: z.ZodLiteral<"context">;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            context: z.ZodString;
+            endpoint_fingerprint: z.ZodString;
+            kind: z.ZodLiteral<"docker-context">;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"host">;
+            value: z.ZodString;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>>;
+    version: z.ZodLiteral<"spawnfile.deployment.v2">;
+}, z.core.$strict>;
+export type DeploymentRecord = z.infer<typeof deploymentRecordSchema>;
+export declare const parseDeploymentRecord: (source: unknown, sourceLabel?: string) => DeploymentRecord;
+export declare const readDeploymentRecord: (recordPath: string) => Promise<DeploymentRecord>;
+export declare const readDeploymentRecordFromOutput: (outputDirectory: string, deploymentName: string) => Promise<DeploymentRecord>;
+export declare const listDeploymentRecords: (outputDirectory: string) => Promise<Array<{
+    path: string;
+    record: DeploymentRecord;
+}>>;
+export declare const writeDeploymentRecord: (outputDirectory: string, record: DeploymentRecord) => Promise<string>;
+export {};

package/dist/deployment/record.js

@@ -0,0 +1,174 @@
+import path from "node:path";
+import { readdir, rename, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { ensureDirectory, readUtf8File } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { normalizeDeploymentName, resolveDeploymentRecordPath, resolveDeploymentRecordsDirectory } from "./names.js";
+const contextTargetSchema = z.object({
+    endpoint_fingerprint: z.string().regex(/^sha256:[a-f0-9]{32}$/),
+    kind: z.literal("context"),
+    name: z.string().min(1)
+}).strict();
+const legacyContextTargetSchema = z.object({
+    context: z.string().min(1),
+    endpoint_fingerprint: z.string().regex(/^sha256:[a-f0-9]{32}$/),
+    kind: z.literal("docker-context")
+}).strict();
+const hostTargetSchema = z.object({
+    kind: z.literal("host"),
+    value: z.string().min(1)
+}).strict();
+const targetSchema = z.union([
+    contextTargetSchema,
+    legacyContextTargetSchema,
+    hostTargetSchema
+]);
+const unitV1Schema = z.object({
+    container_id: z.string().min(1).nullable(),
+    container_name: z.string().min(1).nullable(),
+    contains: z.array(z.object({
+        id: z.string().min(1),
+        kind: z.union([z.literal("agent"), z.literal("team")])
+    }).strict()),
+    id: z.string().min(1),
+    image_id: z.string().min(1).nullable(),
+    image_tag: z.string().min(1),
+    kind: z.literal("container"),
+    runtime_instances: z.array(z.string().min(1))
+}).strict();
+const unitSchema = z.object({
+    container_id: z.string().min(1).nullable(),
+    container_name: z.string().min(1).nullable(),
+    contains: z.array(z.object({
+        id: z.string().min(1),
+        kind: z.union([z.literal("agent"), z.literal("network"), z.literal("team")])
+    }).strict()),
+    id: z.string().min(1),
+    image_id: z.string().min(1).nullable(),
+    image_tag: z.string().min(1),
+    kind: z.literal("container"),
+    manager: z.string().min(1).optional(),
+    runtime_instances: z.array(z.string().min(1)),
+    target: targetSchema.optional()
+}).strict();
+const recordSourceSchema = z.union([
+    z.object({
+        kind: z.literal("project"),
+        root: z.string().min(1)
+    }).strict(),
+    z.object({
+        digest: z.string().min(1).nullable(),
+        kind: z.literal("image"),
+        ref: z.string().min(1)
+    }).strict()
+]);
+const deploymentRecordV1Schema = z.object({
+    auth_profile: z.string().min(1).nullable(),
+    compile_fingerprint: z.string().min(1),
+    created_at: z.string().min(1),
+    env_file: z.string().min(1).optional(),
+    manager: z.literal("docker"),
+    name: z.string().min(1),
+    output_directory: z.string().min(1),
+    project_root: z.string().min(1),
+    target: targetSchema,
+    units: z.array(unitV1Schema).min(1),
+    version: z.literal("spawnfile.deployment.v1")
+}).strict();
+export const deploymentRecordSchema = z.object({
+    auth_profile: z.string().min(1).nullable(),
+    compile_fingerprint: z.string().min(1),
+    created_at: z.string().min(1),
+    env_file: z.string().min(1).optional(),
+    manager: z.string().min(1),
+    name: z.string().min(1),
+    output_directory: z.string().min(1).nullable(),
+    source: recordSourceSchema,
+    target: targetSchema,
+    units: z.array(unitSchema).min(1),
+    version: z.literal("spawnfile.deployment.v2")
+}).strict();
+const upgradeV1Record = (record) => ({
+    auth_profile: record.auth_profile,
+    compile_fingerprint: record.compile_fingerprint,
+    created_at: record.created_at,
+    ...(record.env_file ? { env_file: record.env_file } : {}),
+    manager: record.manager,
+    name: record.name,
+    output_directory: record.output_directory,
+    source: { kind: "project", root: record.project_root },
+    target: record.target,
+    units: record.units,
+    version: "spawnfile.deployment.v2"
+});
+const hasVersion = (source, version) => typeof source === "object"
+    && source !== null
+    && source.version === version;
+export const parseDeploymentRecord = (source, sourceLabel = "deployment record") => {
+    let record;
+    if (hasVersion(source, "spawnfile.deployment.v1")) {
+        const parsed = deploymentRecordV1Schema.safeParse(source);
+        if (!parsed.success) {
+            throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: ${z.prettifyError(parsed.error)}`);
+        }
+        record = upgradeV1Record(parsed.data);
+    }
+    else {
+        const parsed = deploymentRecordSchema.safeParse(source);
+        if (!parsed.success) {
+            throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: ${z.prettifyError(parsed.error)}`);
+        }
+        record = parsed.data;
+    }
+    const normalizedName = normalizeDeploymentName(record.name);
+    if (normalizedName !== record.name) {
+        throw new SpawnfileError("validation_error", `Invalid ${sourceLabel}: deployment name must be normalized`);
+    }
+    return record;
+};
+export const readDeploymentRecord = async (recordPath) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readUtf8File(recordPath));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("validation_error", `Unable to read deployment record ${recordPath}: ${reason}`);
+    }
+    return parseDeploymentRecord(parsed, recordPath);
+};
+export const readDeploymentRecordFromOutput = async (outputDirectory, deploymentName) => readDeploymentRecord(resolveDeploymentRecordPath(outputDirectory, deploymentName));
+export const listDeploymentRecords = async (outputDirectory) => {
+    const recordsDirectory = resolveDeploymentRecordsDirectory(outputDirectory);
+    let entries;
+    try {
+        entries = await readdir(recordsDirectory);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("validation_error", `Unable to read deployment records directory ${recordsDirectory}: ${reason}`);
+    }
+    const records = await Promise.all(entries
+        .filter((entry) => entry.endsWith(".json"))
+        .sort()
+        .map(async (entry) => {
+        const recordPath = path.join(recordsDirectory, entry);
+        return {
+            path: recordPath,
+            record: await readDeploymentRecord(recordPath)
+        };
+    }));
+    return records.sort((left, right) => left.record.name.localeCompare(right.record.name));
+};
+export const writeDeploymentRecord = async (outputDirectory, record) => {
+    const parsed = parseDeploymentRecord(record);
+    const recordPath = resolveDeploymentRecordPath(outputDirectory, parsed.name);
+    await ensureDirectory(path.dirname(recordPath));
+    const temporaryPath = path.join(path.dirname(recordPath), `.${path.basename(recordPath)}.${process.pid}.${Date.now()}.tmp`);
+    await writeFile(temporaryPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+    await rename(temporaryPath, recordPath);
+    return recordPath;
+};

package/dist/deployment/target.d.ts

@@ -0,0 +1,35 @@
+export type DockerDeploymentTarget = {
+    endpoint_fingerprint: string;
+    kind: "context";
+    name: string;
+} | {
+    endpoint_fingerprint: string;
+    kind: "docker-context";
+    context: string;
+} | {
+    kind: "host";
+    value: string;
+};
+export type DockerTargetExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface ResolveDockerDeploymentTargetOptions {
+    context?: string | null;
+    dockerCommand?: string;
+    dockerHost?: string | null;
+    execFile?: DockerTargetExecFile;
+    timeoutMs?: number;
+}
+export declare const createEndpointFingerprint: (endpoint: string) => string;
+export declare const createDockerDeploymentTarget: (input: {
+    context?: string;
+    endpoint?: string;
+    host?: string;
+}) => DockerDeploymentTarget;
+export declare const dockerContextNameForTarget: (target: DockerDeploymentTarget) => string | null;
+export declare const dockerHostValueForTarget: (target: DockerDeploymentTarget) => string | null;
+export declare const resolveDockerDeploymentTarget: (input?: ResolveDockerDeploymentTargetOptions) => Promise<DockerDeploymentTarget>;
+export declare const verifyDockerDeploymentTarget: (target: DockerDeploymentTarget, options?: Omit<ResolveDockerDeploymentTargetOptions, "context" | "dockerHost">) => Promise<string | null>;

package/dist/deployment/target.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+export const createEndpointFingerprint = (endpoint) => {
+    const normalized = endpoint.trim();
+    if (normalized.length === 0) {
+        throw new SpawnfileError("validation_error", "Deployment target endpoint must not be empty");
+    }
+    return `sha256:${createHash("sha256").update(normalized).digest("hex").slice(0, 32)}`;
+};
+const parseDockerEndpoint = (stdout) => {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        throw new SpawnfileError("runtime_error", "Docker context endpoint was empty");
+    }
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed === "string" && parsed.trim().length > 0) {
+            return parsed.trim();
+        }
+    }
+    catch {
+        // Docker/podman variants may return a plain string instead of JSON.
+    }
+    return trimmed;
+};
+const resolveDockerContextEndpoint = async (context, options) => {
+    try {
+        const { stdout } = await options.execFile(options.dockerCommand, ["context", "inspect", context, "--format", "{{json .Endpoints.docker.Host}}"], { timeout: options.timeoutMs });
+        return parseDockerEndpoint(stdout);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("runtime_error", `Unable to resolve Docker context "${context}": ${reason}`);
+    }
+};
+export const createDockerDeploymentTarget = (input) => {
+    const host = input.host?.trim();
+    if (host) {
+        return {
+            kind: "host",
+            value: host
+        };
+    }
+    const context = input.context?.trim();
+    const endpoint = input.endpoint?.trim();
+    if (!context || !endpoint) {
+        throw new SpawnfileError("validation_error", "Docker context deployment targets require both context and endpoint");
+    }
+    return {
+        name: context,
+        endpoint_fingerprint: createEndpointFingerprint(endpoint),
+        kind: "context"
+    };
+};
+export const dockerContextNameForTarget = (target) => target.kind === "context"
+    ? target.name
+    : target.kind === "docker-context"
+        ? target.context
+        : null;
+export const dockerHostValueForTarget = (target) => target.kind === "host" ? target.value : null;
+export const resolveDockerDeploymentTarget = async (input = {}) => {
+    const explicitContext = input.context?.trim();
+    const host = explicitContext ? undefined : input.dockerHost?.trim() ?? process.env.DOCKER_HOST?.trim();
+    if (host) {
+        return createDockerDeploymentTarget({ host });
+    }
+    const resolvedOptions = {
+        dockerCommand: input.dockerCommand ?? "docker",
+        execFile: input.execFile ?? execFile,
+        timeoutMs: input.timeoutMs ?? 10_000
+    };
+    const context = explicitContext || "default";
+    const endpoint = await resolveDockerContextEndpoint(context, resolvedOptions);
+    return createDockerDeploymentTarget({ context, endpoint });
+};
+export const verifyDockerDeploymentTarget = async (target, options = {}) => {
+    if (target.kind === "host") {
+        return null;
+    }
+    const context = dockerContextNameForTarget(target);
+    if (!context) {
+        return null;
+    }
+    const current = await resolveDockerDeploymentTarget({
+        ...options,
+        context
+    });
+    const currentFingerprint = current.kind === "host" ? null : current.endpoint_fingerprint;
+    if (currentFingerprint !== target.endpoint_fingerprint) {
+        throw new SpawnfileError("runtime_error", `Docker context "${context}" endpoint changed since deployment`);
+    }
+    return context;
+};

package/dist/distribution/buildDistributionReport.d.ts

@@ -0,0 +1,22 @@
+import type { DistributionImageLabels, DistributionMoltnetNetwork, DistributionOrganizationSummary, DistributionPersistentMount, DistributionPortMapping, DistributionReport, DistributionRuntimeInstance, DistributionSecretCategory, DistributionWorkspaceResource } from "./types.js";
+export interface DistributionEnvVariableInput {
+    categories: DistributionSecretCategory[];
+    generated: boolean;
+    name: string;
+    required: boolean;
+}
+export interface BuildDistributionReportInput {
+    envVariables: DistributionEnvVariableInput[];
+    generatedAt: string;
+    internalPorts: number[];
+    modelAuthMethods: Record<string, DistributionRuntimeInstance["model_auth_methods"][string]>;
+    moltnetNetworks: DistributionMoltnetNetwork[];
+    organization: DistributionOrganizationSummary;
+    persistentMounts: DistributionPersistentMount[];
+    portMappings: DistributionPortMapping[];
+    publishedPorts: number[];
+    resources: DistributionWorkspaceResource[];
+    runtimeInstances: DistributionRuntimeInstance[];
+}
+export declare const buildDistributionReport: (input: BuildDistributionReportInput) => DistributionReport;
+export declare const createDistributionImageLabels: (projectSlug: string, compileFingerprint: string) => DistributionImageLabels;

package/dist/distribution/buildDistributionReport.js

@@ -0,0 +1,51 @@
+import { createDistributionFingerprint } from "./fingerprint.js";
+import { DISTRIBUTION_REPORT_IMAGE_PATH, DISTRIBUTION_REPORT_VERSION, IMAGE_CONTRACT_VERSION } from "./types.js";
+const createSecretCategoryMap = (envVariables) => {
+    const secrets = {
+        model: [],
+        project: [],
+        runtime: [],
+        surface: []
+    };
+    for (const variable of envVariables) {
+        for (const category of variable.categories) {
+            secrets[category].push({
+                generated: variable.generated,
+                name: variable.name,
+                required: variable.required
+            });
+        }
+    }
+    for (const category of Object.keys(secrets)) {
+        secrets[category].sort((left, right) => left.name.localeCompare(right.name));
+    }
+    return secrets;
+};
+export const buildDistributionReport = (input) => {
+    const body = {
+        internal_ports: [...input.internalPorts].sort((left, right) => left - right),
+        model_auth_methods: input.modelAuthMethods,
+        moltnet: {
+            networks: [...input.moltnetNetworks].sort((left, right) => left.id.localeCompare(right.id))
+        },
+        organization: input.organization,
+        persistent_mounts: [...input.persistentMounts].sort((left, right) => left.id.localeCompare(right.id)),
+        port_mappings: input.portMappings,
+        ports: [...input.publishedPorts].sort((left, right) => left - right),
+        resources: input.resources,
+        runtime_instances: [...input.runtimeInstances].sort((left, right) => left.id.localeCompare(right.id)),
+        secrets: createSecretCategoryMap(input.envVariables),
+        version: DISTRIBUTION_REPORT_VERSION
+    };
+    return {
+        compile_fingerprint: createDistributionFingerprint(body),
+        generated_at: input.generatedAt,
+        ...body
+    };
+};
+export const createDistributionImageLabels = (projectSlug, compileFingerprint) => ({
+    "com.spawnfile.compile_fingerprint": compileFingerprint,
+    "com.spawnfile.image_contract": IMAGE_CONTRACT_VERSION,
+    "com.spawnfile.project": projectSlug,
+    "com.spawnfile.report": DISTRIBUTION_REPORT_IMAGE_PATH
+});

package/dist/distribution/consumeImage.d.ts

@@ -0,0 +1,29 @@
+import { type DeploymentRecord } from "../deployment/index.js";
+import type { DockerCommandRunner } from "./dockerRunner.js";
+import type { ResolvedAuthProfile } from "../auth/index.js";
+export interface ConsumeImageUpOptions {
+    authProfile?: ResolvedAuthProfile | null;
+    authValues?: Record<string, string>;
+    authProfileName?: string | null;
+    deploymentName?: string;
+    dockerCommand?: string;
+    dockerContext?: string;
+    dockerHost?: string;
+    envFileEnv?: Record<string, string>;
+    envFilePath?: string | null;
+    pull?: boolean;
+    runDocker?: DockerCommandRunner;
+}
+export interface ConsumeImageUpResult {
+    containerName: string;
+    deploymentName: string;
+    imageRef: string;
+    /** The ref/digest this redeploy replaced, or null for a first deploy. */
+    previous: {
+        digest: string | null;
+        ref: string;
+    } | null;
+    record: DeploymentRecord;
+    recordPath: string;
+}
+export declare const consumeImageUp: (imageRef: string, options?: ConsumeImageUpOptions) => Promise<ConsumeImageUpResult>;