spawnfile 0.1.0

package/dist/compiler/compileProject.js

@@ -0,0 +1,182 @@
+import path from "node:path";
+import { chmod } from "node:fs/promises";
+import { ensureDirectory, removeDirectory, writeUtf8File } from "../filesystem/index.js";
+import { createCompileReport, createDiagnostic, writeCompileReport } from "../report/index.js";
+import { DEFAULT_OUTPUT_DIRECTORY } from "../shared/index.js";
+import { assertRuntimeCanCompile, createRuntimeLifecycleDiagnostics, getRuntimeAdapter } from "../runtime/index.js";
+import { buildCompilePlan } from "./buildCompilePlan.js";
+import { createContainerArtifacts } from "./containerArtifacts.js";
+const writeEmittedFiles = async (outputDirectory, files) => {
+    await Promise.all(files.map(async (file) => {
+        const targetPath = path.join(outputDirectory, file.path);
+        await ensureDirectory(path.dirname(targetPath));
+        await writeUtf8File(targetPath, file.content);
+    }));
+};
+const createTeamCapabilities = (outcome, message) => [
+    { key: "team.members", message, outcome },
+    { key: "team.structure.mode", message, outcome },
+    { key: "team.structure.leader", message, outcome },
+    { key: "team.structure.external", message, outcome },
+    { key: "team.shared", message, outcome },
+    { key: "team.nested", message, outcome }
+];
+const createAgentOutputDirectory = (baseDirectory, node) => path.join(baseDirectory, "runtimes", node.runtimeName ?? "unknown", "agents", node.slug);
+const createTeamOutputDirectory = (baseDirectory, runtimeName, node) => path.join(baseDirectory, "runtimes", runtimeName, "teams", node.slug);
+const compileAgentNode = async (baseDirectory, node) => {
+    const runtime = await assertRuntimeCanCompile(node.runtimeName ?? node.value.runtime.name);
+    const adapter = getRuntimeAdapter(runtime.name);
+    const diagnostics = [
+        ...createRuntimeLifecycleDiagnostics(runtime)
+    ];
+    for (const diagnostic of adapter.validateRuntimeOptions?.(node.value.runtime.options) ?? []) {
+        diagnostics.push(diagnostic);
+    }
+    const errorDiagnostic = diagnostics.find((diagnostic) => diagnostic.level === "error");
+    if (errorDiagnostic) {
+        throw new Error(errorDiagnostic.message);
+    }
+    const result = await adapter.compileAgent(node.value);
+    const outputDirectory = createAgentOutputDirectory(baseDirectory, node);
+    await writeEmittedFiles(outputDirectory, result.files);
+    return {
+        emittedFiles: result.files,
+        kind: node.kind,
+        report: {
+            capabilities: result.capabilities,
+            diagnostics: [...diagnostics, ...result.diagnostics],
+            id: node.id,
+            kind: node.kind,
+            output_dir: path.relative(baseDirectory, outputDirectory),
+            runtime: runtime.name,
+            runtime_ref: runtime.ref,
+            runtime_status: runtime.status,
+            source: node.value.source
+        },
+        runtimeName: runtime.name,
+        slug: node.slug,
+        value: node.value
+    };
+};
+const getTeamRuntimeName = (node) => {
+    const runtimeNames = [...new Set(node.members.map((member) => member.runtimeName).filter(Boolean))];
+    return runtimeNames.length === 1 ? (runtimeNames[0] ?? null) : null;
+};
+const compileTeamNode = async (baseDirectory, node) => {
+    const runtimeName = getTeamRuntimeName(node.value);
+    if (!runtimeName) {
+        return {
+            emittedFiles: [],
+            kind: node.kind,
+            report: {
+                capabilities: createTeamCapabilities("degraded", "Team spans multiple runtimes and cannot lower to one native team artifact in v0.1"),
+                diagnostics: [
+                    createDiagnostic("warn", `Team ${node.value.name} spans multiple runtimes and was not emitted as a native team artifact`)
+                ],
+                id: node.id,
+                kind: node.kind,
+                output_dir: null,
+                runtime: null,
+                runtime_ref: null,
+                runtime_status: null,
+                source: node.value.source
+            },
+            runtimeName: null,
+            slug: node.slug,
+            value: node.value
+        };
+    }
+    const runtime = await assertRuntimeCanCompile(runtimeName);
+    const adapter = getRuntimeAdapter(runtime.name);
+    const diagnostics = [...createRuntimeLifecycleDiagnostics(runtime)];
+    if (!adapter.compileTeam) {
+        return {
+            emittedFiles: [],
+            kind: node.kind,
+            report: {
+                capabilities: createTeamCapabilities("degraded", `Runtime ${runtime.name} does not provide native team compilation in v0.1`),
+                diagnostics: [
+                    ...diagnostics,
+                    createDiagnostic("warn", `Runtime ${runtime.name} did not emit a native team artifact for ${node.value.name}`)
+                ],
+                id: node.id,
+                kind: node.kind,
+                output_dir: null,
+                runtime: runtime.name,
+                runtime_ref: runtime.ref,
+                runtime_status: runtime.status,
+                source: node.value.source
+            },
+            runtimeName: runtime.name,
+            slug: node.slug,
+            value: node.value
+        };
+    }
+    const result = await adapter.compileTeam(node.value);
+    const outputDirectory = createTeamOutputDirectory(baseDirectory, runtime.name, node);
+    await writeEmittedFiles(outputDirectory, result.files);
+    return {
+        emittedFiles: result.files,
+        kind: node.kind,
+        report: {
+            capabilities: result.capabilities,
+            diagnostics: [...diagnostics, ...result.diagnostics],
+            id: node.id,
+            kind: node.kind,
+            output_dir: path.relative(baseDirectory, outputDirectory),
+            runtime: runtime.name,
+            runtime_ref: runtime.ref,
+            runtime_status: runtime.status,
+            source: node.value.source
+        },
+        runtimeName: runtime.name,
+        slug: node.slug,
+        value: node.value
+    };
+};
+const enforcePolicy = (nodeReport, policyMode, onDegrade) => {
+    for (const capability of nodeReport.capabilities) {
+        if (capability.outcome === "unsupported") {
+            if (policyMode === "strict") {
+                throw new Error(`Policy violation: ${capability.key} is unsupported for ${nodeReport.id} (strict mode)${capability.message ? `: ${capability.message}` : ""}`);
+            }
+        }
+        if (capability.outcome === "degraded") {
+            if (onDegrade === "error") {
+                throw new Error(`Policy violation: ${capability.key} is degraded for ${nodeReport.id} (on_degrade: error)${capability.message ? `: ${capability.message}` : ""}`);
+            }
+        }
+    }
+};
+export const compileProject = async (inputPath, options = {}) => {
+    const plan = await buildCompilePlan(inputPath);
+    const outputDirectory = path.resolve(options.outputDirectory ?? DEFAULT_OUTPUT_DIRECTORY);
+    if (options.clean ?? true) {
+        await removeDirectory(outputDirectory);
+    }
+    await ensureDirectory(outputDirectory);
+    const nodeReports = [];
+    const compiledNodes = [];
+    for (const node of plan.nodes) {
+        let compiled;
+        if (node.kind === "agent") {
+            compiled = await compileAgentNode(outputDirectory, node);
+        }
+        else {
+            compiled = await compileTeamNode(outputDirectory, node);
+        }
+        enforcePolicy(compiled.report, node.value.policyMode, node.value.policyOnDegrade);
+        nodeReports.push(compiled.report);
+        compiledNodes.push(compiled);
+    }
+    const containerArtifacts = await createContainerArtifacts(plan, compiledNodes);
+    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 {
+        outputDirectory,
+        report,
+        reportPath
+    };
+};

package/dist/compiler/containerArtifacts.d.ts

@@ -0,0 +1,4 @@
+import type { CompiledNodeArtifact, GeneratedContainerArtifacts } from "./containerArtifactsTypes.js";
+import type { CompilePlan } from "./types.js";
+export type { CompiledNodeArtifact, GeneratedContainerArtifacts } from "./containerArtifactsTypes.js";
+export declare const createContainerArtifacts: (plan: CompilePlan, compiledNodes: CompiledNodeArtifact[]) => Promise<GeneratedContainerArtifacts>;

package/dist/compiler/containerArtifacts.js

@@ -0,0 +1,64 @@
+import { createEnvVariableMap, createRuntimeTargetPlans } from "./containerArtifactsPlans.js";
+import { createRootfsFiles, renderDockerfile, renderEntrypoint, renderEnvExample } from "./containerArtifactsRender.js";
+export const createContainerArtifacts = async (plan, compiledNodes) => {
+    const runtimePlans = await createRuntimeTargetPlans(plan, compiledNodes);
+    const envVariables = [...createEnvVariableMap(compiledNodes, runtimePlans).values()].sort((left, right) => left.name.localeCompare(right.name));
+    const requiredSecrets = envVariables
+        .filter((variable) => variable.required)
+        .map((variable) => variable.name)
+        .sort();
+    const modelSecretsRequired = envVariables
+        .filter((variable) => variable.required && variable.categories.includes("model"))
+        .map((variable) => variable.name)
+        .sort();
+    const runtimeSecretsRequired = envVariables
+        .filter((variable) => variable.required && variable.categories.includes("runtime"))
+        .map((variable) => variable.name)
+        .sort();
+    const files = [
+        ...createRootfsFiles(runtimePlans),
+        {
+            content: await renderDockerfile(runtimePlans),
+            path: "Dockerfile"
+        },
+        {
+            content: renderEntrypoint(runtimePlans, requiredSecrets.filter((secretName) => !modelSecretsRequired.includes(secretName))),
+            path: "entrypoint.sh"
+        },
+        {
+            content: renderEnvExample(envVariables),
+            path: ".env.example"
+        }
+    ];
+    const ports = [...new Set(runtimePlans.flatMap((plan) => (plan.port ? [plan.port] : [])))].sort((left, right) => left - right);
+    const runtimeHomes = [
+        ...new Set(runtimePlans.flatMap((plan) => (plan.instancePaths.homePath ? [plan.instancePaths.homePath] : [])))
+    ].sort();
+    const runtimeInstances = runtimePlans
+        .map((plan) => ({
+        config_path: plan.instancePaths.configPath,
+        home_path: plan.instancePaths.homePath ?? null,
+        id: plan.id,
+        model_auth_methods: plan.modelAuthMethods,
+        model_secrets_required: plan.modelSecretsRequired,
+        runtime: plan.runtimeName
+    }))
+        .sort((left, right) => left.id.localeCompare(right.id));
+    const runtimesInstalled = [...new Set(runtimePlans.map((plan) => plan.runtimeName))].sort();
+    return {
+        executablePaths: ["entrypoint.sh"],
+        files,
+        report: {
+            dockerfile: "Dockerfile",
+            entrypoint: "entrypoint.sh",
+            env_example: ".env.example",
+            model_secrets_required: modelSecretsRequired,
+            ports,
+            runtime_instances: runtimeInstances,
+            runtime_homes: runtimeHomes,
+            runtime_secrets_required: runtimeSecretsRequired,
+            runtimes_installed: runtimesInstalled,
+            secrets_required: requiredSecrets
+        }
+    };
+};

package/dist/compiler/containerArtifactsPlans.d.ts

@@ -0,0 +1,4 @@
+import type { CompilePlan } from "./types.js";
+import type { CompiledNodeArtifact, ContainerEnvVariable, RuntimeTargetPlan } from "./containerArtifactsTypes.js";
+export declare const createEnvVariableMap: (compiledNodes: CompiledNodeArtifact[], runtimePlans: RuntimeTargetPlan[]) => Map<string, ContainerEnvVariable>;
+export declare const createRuntimeTargetPlans: (plan: CompilePlan, compiledNodes: CompiledNodeArtifact[]) => Promise<RuntimeTargetPlan[]>;

package/dist/compiler/containerArtifactsPlans.js

@@ -0,0 +1,154 @@
+import path from "node:path";
+import { createRuntimeInstallRecipe, getRuntimeAdapter } from "../runtime/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { listAgentSurfaceSecretNames } from "./agentSurfaces.js";
+import { listExecutionModelSecretNames, resolveExecutionModelAuthMethods } from "./modelEnv.js";
+const CONFIG_FILE_PLACEHOLDER = "<config-file>";
+const INSTANCE_ROOT_PLACEHOLDER = "<instance-root>";
+const createDefaultTargets = (inputs) => inputs.map((input) => ({
+    files: input.emittedFiles,
+    id: `${input.kind}-${input.slug}`,
+    sourceIds: [input.id]
+}));
+const resolveTargetEnvFiles = (configPath, target) => (target.envFiles ?? []).map((binding) => ({
+    envName: binding.envName,
+    filePath: path.posix.join(path.posix.dirname(configPath), binding.relativePath)
+}));
+const resolveTargetConfigEnvBindings = (meta, target) => [...(meta.configEnvBindings ?? []), ...(target.configEnvBindings ?? [])];
+const assertTargetHasConfig = (runtimeName, targetId, meta, files) => {
+    if (!files.some((file) => file.path === meta.configFileName)) {
+        throw new SpawnfileError("runtime_error", `Container target ${targetId} for ${runtimeName} is missing ${meta.configFileName}`);
+    }
+};
+const replaceContainerPathTemplate = (template, instanceRoot, configFileName) => template
+    .replaceAll(INSTANCE_ROOT_PLACEHOLDER, instanceRoot)
+    .replaceAll(CONFIG_FILE_PLACEHOLDER, configFileName);
+const resolveInstancePaths = (runtimeName, targetId, meta) => {
+    const instanceRoot = `/var/lib/spawnfile/instances/${runtimeName}/${targetId}`;
+    return {
+        configPath: replaceContainerPathTemplate(meta.instancePaths.configPathTemplate, instanceRoot, meta.configFileName),
+        homePath: meta.instancePaths.homePathTemplate
+            ? replaceContainerPathTemplate(meta.instancePaths.homePathTemplate, instanceRoot, meta.configFileName)
+            : undefined,
+        workspacePath: replaceContainerPathTemplate(meta.instancePaths.workspacePathTemplate, instanceRoot, meta.configFileName)
+    };
+};
+export const createEnvVariableMap = (compiledNodes, runtimePlans) => {
+    const variables = new Map();
+    const register = (name, required, description, category) => {
+        const current = variables.get(name);
+        if (!current) {
+            variables.set(name, {
+                categories: [category],
+                description,
+                name,
+                required
+            });
+            return;
+        }
+        variables.set(name, {
+            ...current,
+            categories: [...new Set([...current.categories, category])],
+            required: current.required || required
+        });
+    };
+    const registerSecret = (secret) => {
+        register(secret.name, secret.required, "Declared in Spawnfile secrets", "project");
+    };
+    for (const node of compiledNodes) {
+        if (node.value.kind === "agent") {
+            for (const secret of node.value.secrets) {
+                registerSecret(secret);
+            }
+            for (const secretName of listExecutionModelSecretNames(node.value.execution)) {
+                register(secretName, true, `Model provider auth for ${secretName}`, "model");
+            }
+            for (const secretName of listAgentSurfaceSecretNames(node.value.surfaces)) {
+                register(secretName, true, "Bot token for declared agent surfaces", "surface");
+            }
+            continue;
+        }
+        for (const secret of node.value.shared.secrets) {
+            registerSecret(secret);
+        }
+    }
+    for (const runtimePlan of runtimePlans) {
+        for (const variable of runtimePlan.meta.env ?? []) {
+            register(variable.name, variable.required, variable.description, "runtime");
+        }
+    }
+    return variables;
+};
+const resolveTargetModelSecrets = (target, inputs) => {
+    const sourceIds = new Set(target.sourceIds ?? []);
+    if (sourceIds.size === 0) {
+        return [];
+    }
+    const secretNames = new Set();
+    for (const input of inputs) {
+        if (!sourceIds.has(input.id) || input.value.kind !== "agent") {
+            continue;
+        }
+        for (const secretName of listExecutionModelSecretNames(input.value.execution)) {
+            secretNames.add(secretName);
+        }
+    }
+    return [...secretNames].sort();
+};
+const resolveTargetModelAuthMethods = (target, inputs) => {
+    const sourceIds = new Set(target.sourceIds ?? []);
+    if (sourceIds.size === 0) {
+        return {};
+    }
+    const methods = new Map();
+    for (const input of inputs) {
+        if (!sourceIds.has(input.id) || input.value.kind !== "agent") {
+            continue;
+        }
+        for (const [provider, method] of Object.entries(resolveExecutionModelAuthMethods(input.value.execution))) {
+            const existingMethod = methods.get(provider);
+            if (existingMethod && existingMethod !== method) {
+                throw new SpawnfileError("validation_error", `Container target ${target.id} declares conflicting auth methods for provider ${provider}`);
+            }
+            methods.set(provider, method);
+        }
+    }
+    return Object.fromEntries([...methods.entries()].sort(([left], [right]) => left.localeCompare(right)));
+};
+export const createRuntimeTargetPlans = async (plan, compiledNodes) => {
+    const runtimeNames = Object.keys(plan.runtimes).sort();
+    const runtimePlans = [];
+    for (const runtimeName of runtimeNames) {
+        const adapter = getRuntimeAdapter(runtimeName);
+        const recipe = await createRuntimeInstallRecipe(runtimeName);
+        const targetInputs = compiledNodes
+            .filter((node) => node.runtimeName === runtimeName && node.emittedFiles.length > 0)
+            .map((node) => ({
+            emittedFiles: node.emittedFiles,
+            id: `${node.kind}:${node.slug}`,
+            kind: node.kind,
+            slug: node.slug,
+            value: node.value
+        }));
+        const targets = (await adapter.createContainerTargets?.(targetInputs)) ??
+            createDefaultTargets(targetInputs);
+        targets.forEach((target, index) => {
+            assertTargetHasConfig(runtimeName, target.id, adapter.container, target.files);
+            const instancePaths = resolveInstancePaths(runtimeName, target.id, adapter.container);
+            runtimePlans.push({
+                configEnvBindings: resolveTargetConfigEnvBindings(adapter.container, target) ?? [],
+                envFiles: resolveTargetEnvFiles(instancePaths.configPath, target),
+                id: target.id,
+                instancePaths,
+                meta: adapter.container,
+                modelAuthMethods: resolveTargetModelAuthMethods(target, targetInputs),
+                modelSecretsRequired: resolveTargetModelSecrets(target, targetInputs),
+                port: adapter.container.port ? adapter.container.port + index : undefined,
+                runtimeName,
+                runtimeRoot: recipe.runtimeRoot,
+                targetFiles: target.files
+            });
+        });
+    }
+    return runtimePlans;
+};

package/dist/compiler/containerArtifactsRender.d.ts

@@ -0,0 +1,6 @@
+import type { EmittedFile } from "../runtime/index.js";
+import type { ContainerEnvVariable, RuntimeTargetPlan } from "./containerArtifactsTypes.js";
+export declare const renderEnvExample: (variables: ContainerEnvVariable[]) => string;
+export declare const renderDockerfile: (runtimePlans: RuntimeTargetPlan[]) => Promise<string>;
+export declare const createRootfsFiles: (runtimePlans: RuntimeTargetPlan[]) => EmittedFile[];
+export declare const renderEntrypoint: (runtimePlans: RuntimeTargetPlan[], requiredSecrets: string[]) => string;

package/dist/compiler/containerArtifactsRender.js

@@ -0,0 +1,237 @@
+import path from "node:path";
+import { createRuntimeInstallRecipe } from "../runtime/index.js";
+import { SpawnfileError } from "../shared/index.js";
+const CONTAINER_ROOTFS_ROOT = "container/rootfs";
+const GATEWAY_PORT_PLACEHOLDER = "<gateway-port>";
+const WORKSPACE_PLACEHOLDER = "<workspace-path>";
+const shellQuote = (value) => `'${value.replace(/'/g, `'\"'\"'`)}'`;
+const extractNodeMajorVersion = (image) => Number(image.match(/^node:(\d+)/)?.[1] ?? "0");
+const createPackageInstallCommand = (packages) => `RUN apt-get update && apt-get install -y --no-install-recommends ${packages.join(" ")} && rm -rf /var/lib/apt/lists/*`;
+const createNpmPackageInstallCommand = (packages) => `RUN npm install -g --omit=dev --no-fund --no-audit ${packages.join(" ")}`;
+const selectBaseImage = (runtimePlans) => {
+    const firstRuntimeMeta = runtimePlans[0]?.meta;
+    if (runtimePlans.length <= 1) {
+        return firstRuntimeMeta?.standaloneBaseImage ?? "debian:bookworm-slim";
+    }
+    const nodeBaseImages = runtimePlans
+        .map((plan) => plan.meta.standaloneBaseImage)
+        .filter((image) => image.startsWith("node:"))
+        .sort((left, right) => extractNodeMajorVersion(right) - extractNodeMajorVersion(left));
+    return nodeBaseImages[0] ?? "debian:bookworm-slim";
+};
+export const renderEnvExample = (variables) => {
+    if (variables.length === 0) {
+        return "# No environment variables were detected during compile.\n";
+    }
+    const lines = ["# Generated by spawnfile compile", ""];
+    const requiredVariables = variables.filter((variable) => variable.required);
+    const optionalVariables = variables.filter((variable) => !variable.required);
+    if (requiredVariables.length > 0) {
+        lines.push("# Required");
+        for (const variable of requiredVariables) {
+            lines.push(`# ${variable.description}`);
+            lines.push(`${variable.name}=`);
+            lines.push("");
+        }
+    }
+    if (optionalVariables.length > 0) {
+        lines.push("# Optional");
+        for (const variable of optionalVariables) {
+            lines.push(`# ${variable.description}`);
+            lines.push(`${variable.name}=`);
+            lines.push("");
+        }
+    }
+    return `${lines.join("\n").trimEnd()}\n`;
+};
+export const renderDockerfile = async (runtimePlans) => {
+    const runtimeNames = [...new Set(runtimePlans.map((plan) => plan.runtimeName))];
+    const runtimeRecipes = await Promise.all(runtimeNames.map((runtimeName) => createRuntimeInstallRecipe(runtimeName)));
+    const baseImage = selectBaseImage(runtimePlans);
+    const needsJsonEnvWriter = runtimePlans.some((plan) => (plan.configEnvBindings?.length ?? 0) > 0);
+    const systemDeps = [
+        ...new Set([
+            ...runtimePlans.flatMap((plan) => plan.meta.systemDeps),
+            ...(needsJsonEnvWriter ? ["python3"] : [])
+        ])
+    ].sort();
+    const globalNpmPackages = [
+        ...new Set(runtimePlans.flatMap((plan) => plan.meta.globalNpmPackages ?? []))
+    ].sort();
+    const exposedPorts = [...new Set(runtimePlans.flatMap((plan) => (plan.port ? [plan.port] : [])))].sort((left, right) => left - right);
+    const lines = [`FROM ${baseImage}`, "USER root", "", "WORKDIR /opt/spawnfile"];
+    if (systemDeps.length > 0) {
+        lines.push(createPackageInstallCommand(systemDeps), "");
+    }
+    if (globalNpmPackages.length > 0) {
+        lines.push(createNpmPackageInstallCommand(globalNpmPackages), "");
+    }
+    for (const recipe of runtimeRecipes) {
+        for (const copyCommand of recipe.copyCommands) {
+            lines.push(copyCommand);
+        }
+        for (const command of recipe.commands) {
+            lines.push(`RUN ${command}`);
+        }
+        lines.push("");
+    }
+    lines.push('RUN if ! id -u spawnfile >/dev/null 2>&1; then useradd --create-home --home-dir /home/spawnfile --shell /bin/bash spawnfile; fi', "");
+    lines.push("COPY container/rootfs/ /", "COPY .env.example /opt/spawnfile/.env.example", 'COPY entrypoint.sh /opt/spawnfile/entrypoint.sh', "RUN chmod +x /opt/spawnfile/entrypoint.sh", "RUN mkdir -p /var/lib/spawnfile && chown -R spawnfile:spawnfile /var/lib/spawnfile /opt/spawnfile");
+    if (exposedPorts.length > 0) {
+        lines.push(`EXPOSE ${exposedPorts.join(" ")}`);
+    }
+    lines.push("USER spawnfile");
+    lines.push('ENTRYPOINT ["/opt/spawnfile/entrypoint.sh"]');
+    return `${lines.join("\n").trimEnd()}\n`;
+};
+const createEnvironmentAssignments = (plan) => {
+    const envAssignments = [];
+    if (plan.instancePaths.homePath) {
+        envAssignments.push(`HOME=${shellQuote(plan.instancePaths.homePath)}`);
+    }
+    if (plan.meta.homeEnv && plan.instancePaths.homePath) {
+        envAssignments.push(`${plan.meta.homeEnv}=${shellQuote(plan.instancePaths.homePath)}`);
+    }
+    if (plan.meta.configPathEnv) {
+        envAssignments.push(`${plan.meta.configPathEnv}=${shellQuote(plan.instancePaths.configPath)}`);
+    }
+    if (plan.meta.portEnv && plan.port) {
+        envAssignments.push(`${plan.meta.portEnv}=${shellQuote(String(plan.port))}`);
+    }
+    for (const [name, value] of Object.entries(plan.meta.staticEnv ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
+        envAssignments.push(`${name}=${shellQuote(value)}`);
+    }
+    return envAssignments;
+};
+const createEnvFileWrites = (plan) => plan.envFiles.map((binding) => `write_env_file ${shellQuote(binding.envName)} ${shellQuote(binding.filePath)}`);
+const createConfigEnvWrites = (plan) => (plan.configEnvBindings ?? []).map((binding) => `apply_json_env_value ${shellQuote(plan.instancePaths.configPath)} ${shellQuote(binding.envName)} ${shellQuote(binding.jsonPath)}`);
+const resolveStartCommand = (plan) => plan.meta.startCommand
+    .map((token) => token
+    .replaceAll("<runtime-root>", plan.runtimeRoot)
+    .replaceAll("<port>", plan.port ? String(plan.port) : ""))
+    .filter((token) => token.length > 0);
+export const createRootfsFiles = (runtimePlans) => runtimePlans.flatMap((plan) => plan.targetFiles.map((file) => {
+    if (file.path === plan.meta.configFileName) {
+        return {
+            content: file.content
+                .replaceAll(WORKSPACE_PLACEHOLDER, plan.instancePaths.workspacePath)
+                .replaceAll(`"${GATEWAY_PORT_PLACEHOLDER}"`, plan.port ? String(plan.port) : "0")
+                .replaceAll(GATEWAY_PORT_PLACEHOLDER, plan.port ? String(plan.port) : ""),
+            path: `${CONTAINER_ROOTFS_ROOT}${plan.instancePaths.configPath}`
+        };
+    }
+    if (file.path.startsWith("workspace/")) {
+        const relativeWorkspacePath = file.path.slice("workspace/".length);
+        return {
+            content: file.content,
+            path: `${CONTAINER_ROOTFS_ROOT}${path.posix.join(plan.instancePaths.workspacePath, relativeWorkspacePath)}`
+        };
+    }
+    if (file.path.startsWith("home/")) {
+        if (!plan.instancePaths.homePath) {
+            throw new SpawnfileError("runtime_error", `Container target ${plan.id} for ${plan.runtimeName} emitted home-scoped files without a home path`);
+        }
+        const relativeHomePath = file.path.slice("home/".length);
+        return {
+            content: file.content,
+            path: `${CONTAINER_ROOTFS_ROOT}${path.posix.join(plan.instancePaths.homePath, relativeHomePath)}`
+        };
+    }
+    throw new SpawnfileError("runtime_error", `Container target ${plan.id} for ${plan.runtimeName} emitted unsupported path ${file.path}`);
+}));
+export const renderEntrypoint = (runtimePlans, requiredSecrets) => {
+    const lines = [
+        "#!/usr/bin/env bash",
+        "set -euo pipefail",
+        "",
+        "require_env() {",
+        '  local name=\"$1\"',
+        '  if [ -z \"${!name:-}\" ]; then',
+        '    echo \"Missing required env: $name\" >&2',
+        "    exit 1",
+        "  fi",
+        "}",
+        "",
+        "require_file() {",
+        '  local target=\"$1\"',
+        '  if [ ! -f \"$target\" ]; then',
+        '    echo \"Missing required file: $target\" >&2',
+        "    exit 1",
+        "  fi",
+        "}",
+        "",
+        "write_env_file() {",
+        '  local name=\"$1\"',
+        '  local target=\"$2\"',
+        '  if [ -z \"${!name:-}\" ]; then',
+        "    return",
+        "  fi",
+        '  mkdir -p \"$(dirname \"$target\")\"',
+        '  printf %s \"${!name:-}\" > \"$target\"',
+        "}",
+        "",
+        "apply_json_env_value() {",
+        '  local target=\"$1\"',
+        '  local name=\"$2\"',
+        '  local json_path=\"$3\"',
+        '  if [ -z \"${!name:-}\" ]; then',
+        "    return",
+        "  fi",
+        "  python3 - \"$target\" \"$name\" \"$json_path\" <<'PY'",
+        "import json",
+        "import os",
+        "import sys",
+        "",
+        "target_path = sys.argv[1]",
+        "env_name = sys.argv[2]",
+        "json_path = sys.argv[3].split('.')",
+        "value = os.environ.get(env_name)",
+        "if value is None:",
+        "    raise SystemExit(0)",
+        "",
+        "with open(target_path, encoding='utf-8') as handle:",
+        "    data = json.load(handle)",
+        "",
+        "cursor = data",
+        "for part in json_path[:-1]:",
+        "    child = cursor.get(part)",
+        "    if not isinstance(child, dict):",
+        "        child = {}",
+        "        cursor[part] = child",
+        "    cursor = child",
+        "",
+        "cursor[json_path[-1]] = value",
+        "",
+        "with open(target_path, 'w', encoding='utf-8') as handle:",
+        "    json.dump(data, handle, indent=2)",
+        "    handle.write('\\n')",
+        "PY",
+        "}",
+        ""
+    ];
+    for (const secretName of requiredSecrets) {
+        lines.push(`require_env ${shellQuote(secretName)}`);
+    }
+    if (requiredSecrets.length > 0) {
+        lines.push("");
+    }
+    if (runtimePlans.length === 1) {
+        const plan = runtimePlans[0];
+        const commandTokens = resolveStartCommand(plan);
+        const envAssignments = createEnvironmentAssignments(plan);
+        const envFileWrites = createEnvFileWrites(plan);
+        const configEnvWrites = createConfigEnvWrites(plan);
+        lines.push(`mkdir -p ${shellQuote(plan.instancePaths.workspacePath)}`, `require_file ${shellQuote(plan.instancePaths.configPath)}`, ...envFileWrites, ...configEnvWrites, `${envAssignments.join(" ")} exec ${commandTokens.map(shellQuote).join(" ")}`);
+        return `${lines.join("\n").trimEnd()}\n`;
+    }
+    lines.push("PIDS=()", "", "terminate_children() {", '  for pid in "${PIDS[@]:-}"; do', '    kill "$pid" 2>/dev/null || true', "  done", "}", "", "trap terminate_children INT TERM EXIT", "");
+    for (const plan of runtimePlans) {
+        const commandTokens = resolveStartCommand(plan);
+        const envAssignments = createEnvironmentAssignments(plan);
+        const envFileWrites = createEnvFileWrites(plan);
+        const configEnvWrites = createConfigEnvWrites(plan);
+        lines.push(`mkdir -p ${shellQuote(plan.instancePaths.workspacePath)}`, `require_file ${shellQuote(plan.instancePaths.configPath)}`, ...envFileWrites, ...configEnvWrites, `${envAssignments.join(" ")} ${commandTokens.map(shellQuote).join(" ")} &`, 'PIDS+=("$!")', "");
+    }
+    lines.push('if [ "${#PIDS[@]}" -eq 0 ]; then', '  echo "No runtime targets were generated for this compile output" >&2', "  exit 1", "fi", "", "status=0", 'for pid in "${PIDS[@]}"; do', '  if ! wait "$pid"; then', "    status=1", "  fi", "done", "", 'exit "$status"');
+    return `${lines.join("\n").trimEnd()}\n`;
+};