promigence 0.1.0-beta.12

package/dist/devcontainer.js

@@ -0,0 +1,744 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { TIERS } from "./generated.js";
+import { sh } from "./term.js";
+export const DEVCONTAINER_SPEC = "containers.dev json_reference + features, read 2026-09-18";
+export const DEVCONTAINER_NAMES = [".devcontainer/devcontainer.json", ".devcontainer.json"];
+export class DevcontainerError extends Error {
+    kind;
+    fix;
+    file;
+    constructor(kind, message, fix, file) {
+        super(message);
+        this.name = "DevcontainerError";
+        this.kind = kind;
+        this.fix = fix;
+        this.file = file;
+    }
+}
+const refuse = (kind, message, fix, file) => new DevcontainerError(kind, message, fix, file);
+export function parseJsonc(text, file) {
+    let i = 0;
+    const where = (at) => {
+        let line = 1;
+        let column = 1;
+        for (let k = 0; k < at && k < text.length; k++) {
+            if (text[k] === "\n") {
+                line++;
+                column = 1;
+            }
+            else
+                column++;
+        }
+        return { line, column };
+    };
+    const fail = (at, what) => {
+        const p = where(at);
+        throw refuse("parse", `${file ?? "devcontainer.json"}:${p.line}:${p.column}: ${what}`, "Fix the file so it is JSON with comments (JSONC): quoted keys, no unquoted values, " +
+            "comments with // or /* */. Trailing commas are allowed.", file);
+    };
+    const skip = () => {
+        for (;;) {
+            const c = text[i];
+            if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+                i++;
+                continue;
+            }
+            if (c === "/" && text[i + 1] === "/") {
+                while (i < text.length && text[i] !== "\n")
+                    i++;
+                continue;
+            }
+            if (c === "/" && text[i + 1] === "*") {
+                const start = i;
+                i += 2;
+                while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                    i++;
+                if (i >= text.length)
+                    fail(start, "unterminated /* comment");
+                i += 2;
+                continue;
+            }
+            return;
+        }
+    };
+    const string = () => {
+        const start = i;
+        i++;
+        let out = "";
+        for (;;) {
+            if (i >= text.length)
+                fail(start, "unterminated string");
+            const c = text[i];
+            if (c === '"') {
+                i++;
+                return out;
+            }
+            if (c === "\n")
+                fail(i, "a newline inside a string; use \\n");
+            if (c !== "\\") {
+                out += c;
+                i++;
+                continue;
+            }
+            const esc = text[i + 1];
+            i += 2;
+            if (esc === "u") {
+                const hex = text.slice(i, i + 4);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                    fail(i - 2, "a \\u escape that is not four hex digits");
+                out += String.fromCharCode(parseInt(hex, 16));
+                i += 4;
+                continue;
+            }
+            const simple = { '"': '"', "\\": "\\", "/": "/", b: "\b", f: "\f", n: "\n", r: "\r", t: "\t" };
+            const mapped = esc === undefined ? undefined : simple[esc];
+            if (mapped === undefined)
+                fail(i - 2, `an unknown escape \\${esc ?? "<end of file>"}`);
+            out += mapped;
+        }
+    };
+    const value = () => {
+        skip();
+        if (i >= text.length)
+            fail(i, "the file ended where a value was expected");
+        const c = text[i];
+        if (c === '"')
+            return string();
+        if (c === "{") {
+            i++;
+            const out = {};
+            for (;;) {
+                skip();
+                if (text[i] === "}") {
+                    i++;
+                    return out;
+                }
+                if (text[i] !== '"')
+                    fail(i, `a key must be a quoted string, got ${JSON.stringify(text[i] ?? "<end of file>")}`);
+                const key = string();
+                skip();
+                if (text[i] !== ":")
+                    fail(i, `expected ':' after the key ${JSON.stringify(key)}`);
+                i++;
+                out[key] = value();
+                skip();
+                if (text[i] === ",") {
+                    i++;
+                    continue;
+                }
+                if (text[i] === "}") {
+                    i++;
+                    return out;
+                }
+                fail(i, `expected ',' or '}' after the value of ${JSON.stringify(key)}`);
+            }
+        }
+        if (c === "[") {
+            i++;
+            const out = [];
+            for (;;) {
+                skip();
+                if (text[i] === "]") {
+                    i++;
+                    return out;
+                }
+                out.push(value());
+                skip();
+                if (text[i] === ",") {
+                    i++;
+                    continue;
+                }
+                if (text[i] === "]") {
+                    i++;
+                    return out;
+                }
+                fail(i, "expected ',' or ']' in an array");
+            }
+        }
+        if (text.startsWith("true", i)) {
+            i += 4;
+            return true;
+        }
+        if (text.startsWith("false", i)) {
+            i += 5;
+            return false;
+        }
+        if (text.startsWith("null", i)) {
+            i += 4;
+            return null;
+        }
+        const num = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(i));
+        if (num) {
+            i += num[0].length;
+            return Number(num[0]);
+        }
+        return fail(i, `${JSON.stringify(text.slice(i, i + 12))} is not a JSON value`);
+    };
+    const v = value();
+    skip();
+    if (i < text.length)
+        fail(i, "trailing content after the document");
+    return v;
+}
+export function discover(root) {
+    const found = [];
+    for (const name of DEVCONTAINER_NAMES) {
+        const p = join(root, name);
+        if (existsSync(p) && statSync(p).isFile())
+            found.push(p);
+    }
+    const dir = join(root, ".devcontainer");
+    if (existsSync(dir) && statSync(dir).isDirectory()) {
+        for (const entry of readdirSync(dir).sort()) {
+            const nested = join(dir, entry, "devcontainer.json");
+            if (existsSync(nested) && statSync(nested).isFile())
+                found.push(nested);
+        }
+    }
+    return found;
+}
+export function resolveGiven(pathArg) {
+    const p = resolve(pathArg);
+    if (!existsSync(p)) {
+        throw refuse("not_found", `no devcontainer at ${JSON.stringify(pathArg)}`, "Pass --devcontainer with the path to a devcontainer.json, or to the directory holding one.", pathArg);
+    }
+    if (statSync(p).isFile())
+        return p;
+    const direct = join(p, "devcontainer.json");
+    if (existsSync(direct))
+        return direct;
+    const under = discover(p);
+    if (under.length === 1)
+        return under[0];
+    if (under.length > 1) {
+        throw refuse("ambiguous", `${pathArg} holds ${under.length} devcontainer.json files: ${under.join(", ")}`, "Pass --devcontainer with the one you want.", pathArg);
+    }
+    throw refuse("not_found", `no devcontainer.json under ${JSON.stringify(pathArg)}`, "Pass --devcontainer with the path to a devcontainer.json, or to the directory holding one.", pathArg);
+}
+export function detectOne(root, asked = false) {
+    const found = discover(root);
+    if (found.length === 0) {
+        if (asked) {
+            throw refuse("not_found", `no devcontainer.json in ${root}`, `Run this where the repository is, or pass --devcontainer with the path. Looked for ${DEVCONTAINER_NAMES.join(", ")} and .devcontainer/<folder>/devcontainer.json.`);
+        }
+        return undefined;
+    }
+    if (found.length > 1) {
+        throw refuse("ambiguous", `this directory declares ${found.length} devcontainers: ${found.map((f) => f.slice(root.length + 1)).join(", ")}`, "Pass --devcontainer with the one to build, or --no-devcontainer to ignore them.");
+    }
+    return found[0];
+}
+export function workspaceRootFor(file) {
+    const dir = resolve(file, "..");
+    if (basename(dir) === ".devcontainer")
+        return resolve(dir, "..");
+    if (basename(resolve(dir, "..")) === ".devcontainer")
+        return resolve(dir, "..", "..");
+    return dir;
+}
+export function load(file) {
+    const path = resolve(file);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        throw refuse("not_found", `cannot read ${file}: ${e instanceof Error ? e.message : String(e)}`, "Check the path passed to --devcontainer.", file);
+    }
+    const parsed = parseJsonc(text, file);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw refuse("parse", `${file} is not a JSON object`, "A devcontainer.json is an object: { \"image\": \"…\" }.", file);
+    }
+    return { path, dir: resolve(path, ".."), config: parsed };
+}
+const VARIABLE = /\$\{([a-zA-Z]+)(?::([^}]*))?\}/g;
+export function substituteString(input, ctx) {
+    return input.replace(VARIABLE, (whole, name, arg) => {
+        switch (name) {
+            case "localWorkspaceFolder": return ctx.localWorkspaceFolder;
+            case "localWorkspaceFolderBasename": return ctx.localWorkspaceFolderBasename;
+            case "containerWorkspaceFolder": return ctx.containerWorkspaceFolder;
+            case "containerWorkspaceFolderBasename": return ctx.containerWorkspaceFolderBasename;
+            case "devcontainerId": return ctx.devcontainerId;
+            case "localEnv": {
+                const [key, fallback] = splitDefault(arg ?? "");
+                return ctx.localEnv[key] ?? fallback;
+            }
+            case "containerEnv": {
+                if (!ctx.allowContainerEnv) {
+                    throw refuse("container_env_scope", `\${containerEnv:…} in ${ctx.property}: the spec defines it for remoteEnv only`, "Move the value into remoteEnv, or write it out literally.", ctx.file);
+                }
+                const [key] = splitDefault(arg ?? "");
+                return ctx.containerEnv[key] ?? whole;
+            }
+            default: return whole;
+        }
+    });
+}
+function splitDefault(arg) {
+    const cut = arg.indexOf(":");
+    return cut === -1 ? [arg, ""] : [arg.slice(0, cut), arg.slice(cut + 1)];
+}
+export function substituteDeep(value, ctx) {
+    if (typeof value === "string")
+        return substituteString(value, ctx);
+    if (Array.isArray(value))
+        return value.map((v) => substituteDeep(v, ctx));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = substituteDeep(v, ctx);
+        return out;
+    }
+    return value;
+}
+export function devcontainerId(workspaceRoot, file) {
+    const digest = createHash("sha256").update(`${resolve(workspaceRoot)}\0${resolve(file)}`).digest("hex");
+    return digest.slice(0, 16);
+}
+const KNOWN = new Set([
+    "$schema", "name", "image", "build", "dockerComposeFile", "service", "runServices",
+    "containerEnv", "remoteEnv", "containerUser", "remoteUser", "updateRemoteUserUID", "userEnvProbe",
+    "workspaceFolder", "workspaceMount", "mounts", "runArgs", "overrideCommand", "shutdownAction",
+    "init", "privileged", "capAdd", "securityOpt",
+    "forwardPorts", "appPort", "portsAttributes", "otherPortsAttributes",
+    "initializeCommand", "onCreateCommand", "updateContentCommand", "postCreateCommand",
+    "postStartCommand", "postAttachCommand", "waitFor",
+    "features", "overrideFeatureInstallOrder", "customizations", "hostRequirements",
+]);
+const BAKED_LIFECYCLE = ["onCreateCommand", "updateContentCommand", "postCreateCommand", "postStartCommand"];
+export function translate(loaded, opts) {
+    const file = loaded.path;
+    const raw = loaded.config;
+    const hostEnv = opts.localEnv ?? process.env;
+    const readFromHost = new Set();
+    const localEnv = new Proxy({}, {
+        get: (_t, key) => {
+            if (typeof key !== "string")
+                return undefined;
+            const v = hostEnv[key];
+            if (v !== undefined && v !== "")
+                readFromHost.add(key);
+            return v;
+        },
+    });
+    const tiers = opts.tiers ?? TIERS;
+    const ignored = [];
+    const notes = [];
+    if (raw["dockerComposeFile"] !== undefined) {
+        const files = asStringArray(raw["dockerComposeFile"]).join(", ");
+        throw refuse("compose", `this devcontainer is built by Docker Compose (${files || "dockerComposeFile"})`, "A Compose project describes several services started together, and a Promigence snapshot is " +
+            "built from one image. Point Promigence at the service your work runs in — give it an `image` " +
+            "or a `build.dockerfile` in a devcontainer.json of its own — or pass --no-devcontainer and " +
+            "describe the environment with --image / --dockerfile.", file);
+    }
+    refuseFeatures(raw, file);
+    const workspaceRoot = resolve(opts.workspaceRoot);
+    const localWorkspaceFolderBasename = basename(workspaceRoot);
+    const preCtx = {
+        localWorkspaceFolder: workspaceRoot,
+        localWorkspaceFolderBasename,
+        containerWorkspaceFolder: "",
+        containerWorkspaceFolderBasename: "",
+        localEnv,
+        containerEnv: {},
+        devcontainerId: devcontainerId(workspaceRoot, file),
+        allowContainerEnv: false,
+        property: "workspaceFolder",
+        file,
+    };
+    const declaredWorkspace = typeof raw["workspaceFolder"] === "string"
+        ? substituteString(raw["workspaceFolder"], preCtx).trim()
+        : "";
+    const workspaceFolder = declaredWorkspace || `/workspaces/${localWorkspaceFolderBasename}`;
+    if (!workspaceFolder.startsWith("/")) {
+        throw refuse("workspace_folder", `workspaceFolder must be an absolute path, got ${JSON.stringify(workspaceFolder)}`, "Use an absolute path inside the environment, e.g. \"workspaceFolder\": \"/workspaces/app\".", file);
+    }
+    const ctxFor = (property, containerEnv, allowContainerEnv = false) => ({
+        ...preCtx,
+        containerWorkspaceFolder: workspaceFolder,
+        containerWorkspaceFolderBasename: basename(workspaceFolder),
+        containerEnv,
+        allowContainerEnv,
+        property,
+    });
+    const containerEnv = stringMap(raw["containerEnv"], "containerEnv", file, (s, p) => substituteString(s, ctxFor(p, {})));
+    const remoteEnv = stringMap(raw["remoteEnv"], "remoteEnv", file, (s, p) => substituteString(s, ctxFor(p, containerEnv, true)));
+    const env = { ...containerEnv, ...remoteEnv };
+    if (Object.keys(remoteEnv).length) {
+        notes.push("remoteEnv is applied the same way as containerEnv: both are set for every command, terminal and SSH session in the snapshot's sandboxes");
+    }
+    let source;
+    if (opts.imageOverride === undefined) {
+        source = translateSource(raw, loaded.dir, ctxFor("build", containerEnv), file);
+    }
+    else {
+        source = { kind: "image", image: opts.imageOverride };
+        notes.push(`--image replaces the source this devcontainer names${typeof raw["image"] === "string" ? ` (${raw["image"]})` : ""}`);
+    }
+    const containerUser = optionalString(raw["containerUser"], "containerUser", file);
+    const remoteUser = optionalString(raw["remoteUser"], "remoteUser", file);
+    const user = containerUser ?? remoteUser;
+    if (user !== undefined && !/^[a-z_][a-z0-9_-]*$/.test(user)) {
+        throw refuse("user", `containerUser/remoteUser ${JSON.stringify(user)} is not a user name we can use`, "Name an account that exists in the image, e.g. \"remoteUser\": \"vscode\".", file);
+    }
+    if (containerUser !== undefined && remoteUser !== undefined && containerUser !== remoteUser) {
+        notes.push(`containerUser ${containerUser} and remoteUser ${remoteUser} differ; the build steps run as ${containerUser}`);
+    }
+    if (raw["updateRemoteUserUID"] !== undefined) {
+        ignored.push({ field: "updateRemoteUserUID", why: "there is no local user to match ids with" });
+    }
+    if (raw["initializeCommand"] !== undefined) {
+        throw refuse("initialize_command", "initializeCommand runs on your own machine before the environment is created", "Promigence will not run a command on your machine. Run it yourself before `promigence snapshot create`, " +
+            "or move the work into onCreateCommand / postCreateCommand so it is part of the environment.", file);
+    }
+    const lifecycle = [];
+    for (const field of BAKED_LIFECYCLE) {
+        for (const step of lifecycleSteps(raw[field], field, ctxFor(field, containerEnv), file))
+            lifecycle.push(step);
+    }
+    if (raw["postAttachCommand"] !== undefined) {
+        ignored.push({ field: "postAttachCommand", why: "it runs when an editor attaches, and nothing attaches to a snapshot" });
+    }
+    if (raw["postStartCommand"] !== undefined) {
+        notes.push("postStartCommand is run once while the snapshot is built, not on every fork; use --start for a process that must be running");
+    }
+    if (raw["waitFor"] !== undefined) {
+        ignored.push({ field: "waitFor", why: "every setup step must exit 0 before the snapshot is stored, so there is nothing to wait for" });
+    }
+    const unsupported = [];
+    for (const [field, why] of [
+        ["runArgs", "Promigence does not take container run arguments"],
+        ["privileged", "Promigence does not take container run arguments"],
+        ["capAdd", "Promigence does not take container run arguments"],
+        ["securityOpt", "Promigence does not take container run arguments"],
+        ["init", "Promigence does not take container run arguments"],
+        ["workspaceMount", "Promigence does not mount your working tree into the environment; a snapshot holds what the image and the setup steps produced"],
+        ["mounts", "Promigence does not mount paths from your machine into the environment"],
+    ]) {
+        if (raw[field] === undefined || raw[field] === null)
+            continue;
+        if ((field === "privileged" || field === "init") && raw[field] === false)
+            continue;
+        if (Array.isArray(raw[field]) && raw[field].length === 0)
+            continue;
+        unsupported.push(`${field} (${why})`);
+    }
+    if (unsupported.length) {
+        throw refuse("unsupported_property", `this devcontainer sets ${unsupported.length} propert${unsupported.length === 1 ? "y" : "ies"} a snapshot cannot take: ${unsupported.join("; ")}`, "Remove them from the devcontainer, or pass --no-devcontainer and build the environment with --image / --dockerfile and --setup.", file);
+    }
+    const ports = [...portList(raw["forwardPorts"], "forwardPorts", file), ...portList(raw["appPort"], "appPort", file)]
+        .filter((p, idx, all) => all.indexOf(p) === idx);
+    const { tier, tierReason } = chooseTier(raw["hostRequirements"], tiers, file, ignored);
+    for (const [field, why] of [
+        ["customizations", "editor and tool settings do not change what the environment contains"],
+        ["portsAttributes", "labels and auto-forward behaviour belong to an editor"],
+        ["otherPortsAttributes", "labels and auto-forward behaviour belong to an editor"],
+        ["userEnvProbe", "the environment your commands run in is the one the setup steps left"],
+        ["overrideCommand", "a snapshot has no keep-alive command to override"],
+        ["shutdownAction", "a sandbox ends on its own timeout, or when you end it"],
+        ["$schema", "an editor hint"],
+    ]) {
+        if (raw[field] !== undefined)
+            ignored.push({ field, why });
+    }
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN.has(key))
+            ignored.push({ field: key, why: "not a property of the Dev Container specification this version reads" });
+    }
+    if (readFromHost.size > 0 && opts.allowLocalEnv !== true) {
+        const names = [...readFromHost].sort();
+        throw refuse("local_env", `this devcontainer reads ${names.length === 1 ? "a value" : `${names.length} values`} from your environment (\${localEnv:${names.join("}, ${localEnv:")}}), ` +
+            "and a value read here is printed, stored with the build and baked into every sandbox forked from it", "Pass --devcontainer-local-env to bake them in anyway; for a token, store it with `promigence secrets set NAME` " +
+            "and pass it at run time (--secret NAME), or unset the variable for this command.", file);
+    }
+    return {
+        spec: DEVCONTAINER_SPEC,
+        file,
+        name: optionalString(raw["name"], "name", file),
+        source,
+        env,
+        workspaceFolder,
+        user,
+        ...(remoteUser === undefined ? {} : { remoteUser }),
+        lifecycle,
+        ports,
+        tier,
+        tierReason,
+        ignored,
+        notes,
+        ...(readFromHost.size > 0 ? { localEnvBaked: [...readFromHost].sort() } : {}),
+    };
+}
+function refuseFeatures(raw, file) {
+    const features = raw["features"];
+    if (features === undefined || features === null)
+        return;
+    if (typeof features !== "object" || Array.isArray(features)) {
+        throw refuse("features", "features must be an object of Feature ids", "See containers.dev/implementors/features.", file);
+    }
+    const ids = Object.keys(features);
+    if (ids.length === 0)
+        return;
+    throw refuse("features", `this devcontainer installs ${ids.length} Dev Container Feature${ids.length === 1 ? "" : "s"}, which Promigence does not install: ${ids.join(", ")}`, "A Feature that quietly did not install is worse than a refused build, so we refuse. " +
+        "Either use an image that already carries these tools, or write the install commands the " +
+        "Features would have run as `postCreateCommand` (or `promigence snapshot create --setup`), " +
+        "then rebuild. --no-devcontainer ignores the file entirely.", file);
+}
+function translateSource(raw, dir, ctx, file) {
+    const image = optionalString(raw["image"], "image", file);
+    const build = raw["build"];
+    if (image !== undefined && build !== undefined) {
+        throw refuse("source", "this devcontainer sets both image and build", "Keep one of them: an image to pull, or a Dockerfile to build.", file);
+    }
+    if (image !== undefined) {
+        const pinned = substituteString(image, ctx).trim();
+        if (!/^\S+@sha256:[0-9a-f]{64}$/.test(pinned)) {
+            throw refuse("image_unpinned", `the image ${JSON.stringify(pinned)} is not pinned by digest`, "A tag can be moved under you, so a snapshot built from one cannot be rebuilt. Resolve it once " +
+                `with \`${sh `promigence image resolve ${pinned}`}\` (no local docker needed) and either write ` +
+                "the name@sha256:<digest> it prints in the devcontainer.json or pass --image with it.", file);
+        }
+        return { kind: "image", image: pinned };
+    }
+    if (build === undefined) {
+        throw refuse("no_source", "this devcontainer names neither an image nor a Dockerfile", "Add \"image\": \"name@sha256:<digest>\" or \"build\": { \"dockerfile\": \"Dockerfile\" } to the devcontainer.json.", file);
+    }
+    if (typeof build !== "object" || build === null || Array.isArray(build)) {
+        throw refuse("source", "build must be an object", "Use \"build\": { \"dockerfile\": \"Dockerfile\" }.", file);
+    }
+    const b = build;
+    for (const field of ["args", "target", "cacheFrom", "options"]) {
+        const v = b[field];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v) && v.length === 0)
+            continue;
+        if (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0)
+            continue;
+        throw refuse("build_option", `build.${field} is set, and a Promigence Dockerfile build does not take it yet`, `Move the value into the Dockerfile itself (an ARG with a default, or the FROM stage you want), ` +
+            `or pass --no-devcontainer and build with --dockerfile.`, file);
+    }
+    const dockerfile = optionalString(b["dockerfile"], "build.dockerfile", file);
+    if (dockerfile === undefined) {
+        throw refuse("source", "build.dockerfile is required", "Use \"build\": { \"dockerfile\": \"Dockerfile\" }.", file);
+    }
+    const contextRel = optionalString(b["context"], "build.context", file) ?? ".";
+    const dfPath = substituteString(dockerfile, ctx);
+    const ctxPath = substituteString(contextRel, ctx);
+    const out = {
+        kind: "dockerfile",
+        dockerfile: isAbsolute(dfPath) ? dfPath : resolve(dir, dfPath),
+        context: isAbsolute(ctxPath) ? ctxPath : resolve(dir, ctxPath),
+    };
+    const root = resolve(ctx.localWorkspaceFolder);
+    for (const [what, p] of [["build.context", out.context], ["build.dockerfile", out.dockerfile]]) {
+        const rel = relative(root, p);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            throw refuse("context_outside", `${what} ${JSON.stringify(p)} is outside the workspace ${root}, and everything in a build context is uploaded`, "Point it at a directory inside the repository, or pass --no-devcontainer and name --dockerfile/--context yourself.", file);
+        }
+    }
+    return out;
+}
+export const OPT_IN_TIERS = new Set(["xsmall", "large-16"]);
+function chooseTier(value, tiers, file, ignored) {
+    if (value === undefined || value === null)
+        return { tier: undefined, tierReason: undefined };
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw refuse("host_requirements", "hostRequirements must be an object", "Use \"hostRequirements\": { \"cpus\": 4, \"memory\": \"8gb\" }.", file);
+    }
+    const h = value;
+    if (h["gpu"] !== undefined && h["gpu"] !== false && h["gpu"] !== "optional") {
+        throw refuse("gpu", "hostRequirements.gpu asks for a GPU", "Promigence has no GPU shapes. Drop the requirement, or write to support@promigence.ai.", file);
+    }
+    if (h["gpu"] === "optional" || h["gpu"] === false)
+        ignored.push({ field: "hostRequirements.gpu", why: "no GPU was required" });
+    const cpus = h["cpus"] === undefined ? 0 : positiveInt(h["cpus"], "hostRequirements.cpus", file);
+    const memGib = h["memory"] === undefined ? 0 : sizeGib(h["memory"], "hostRequirements.memory", file);
+    const diskGib = h["storage"] === undefined ? 0 : sizeGib(h["storage"], "hostRequirements.storage", file);
+    if (cpus === 0 && memGib === 0 && diskGib === 0)
+        return { tier: undefined, tierReason: undefined };
+    const sellable = tiers.filter((t) => t.sellable && !OPT_IN_TIERS.has(t.name)).sort((a, b) => a.vcpus - b.vcpus || a.mem_gib - b.mem_gib);
+    const fit = sellable.find((t) => t.vcpus >= cpus && t.mem_gib >= memGib && t.disk_gib >= diskGib);
+    const asked = [
+        cpus ? `${cpus} cpus` : "",
+        memGib ? `${trim(memGib)} GiB memory` : "",
+        diskGib ? `${trim(diskGib)} GiB storage` : "",
+    ].filter(Boolean).join(", ");
+    if (!fit) {
+        const biggest = sellable[sellable.length - 1];
+        throw refuse("host_requirements", `hostRequirements asks for ${asked}, and the largest tier is ${biggest ? `${biggest.name} (${biggest.vcpus} vCPU, ${biggest.mem_gib} GiB, ${biggest.disk_gib} GiB disk)` : "smaller"}`, "Lower hostRequirements, or write to support@promigence.ai about a larger shape.", file);
+    }
+    return { tier: fit.name, tierReason: `hostRequirements asks for ${asked}; ${fit.name} is the smallest tier that covers it` };
+}
+function optionalString(v, field, file) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "string") {
+        throw refuse("type", `${field} must be a string, got ${JSON.stringify(v)}`, `Give ${field} a string value.`, file);
+    }
+    const t = v.trim();
+    return t === "" ? undefined : t;
+}
+function asStringArray(v) {
+    if (typeof v === "string")
+        return [v];
+    if (Array.isArray(v))
+        return v.filter((x) => typeof x === "string");
+    return [];
+}
+function stringMap(v, field, file, sub) {
+    if (v === undefined || v === null)
+        return {};
+    if (typeof v !== "object" || Array.isArray(v)) {
+        throw refuse("type", `${field} must be an object of NAME: value`, `Use "${field}": { "NODE_ENV": "test" }.`, file);
+    }
+    const out = {};
+    for (const [k, raw] of Object.entries(v)) {
+        if (typeof raw !== "string") {
+            throw refuse("type", `${field}.${k} must be a string, got ${JSON.stringify(raw)}`, `Quote the value: "${k}": "${String(raw)}".`, file);
+        }
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) {
+            throw refuse("type", `${field}.${k} is not a usable environment variable name`, "Use letters, digits and underscores, not starting with a digit.", file);
+        }
+        out[k] = sub(raw, `${field}.${k}`);
+    }
+    return out;
+}
+function positiveInt(v, field, file) {
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
+        throw refuse("type", `${field} must be a whole number of 1 or more, got ${JSON.stringify(v)}`, `Use "${field}": 4.`, file);
+    }
+    return v;
+}
+export function sizeGib(v, field, file) {
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+        return v / 1024 ** 3;
+    if (typeof v !== "string") {
+        throw refuse("type", `${field} must be a size like "8gb", got ${JSON.stringify(v)}`, `Use "${field}": "8gb" (kb, mb, gb, tb).`, file);
+    }
+    const m = /^(\d+)\s*([tgmk]b)?$/i.exec(v.trim());
+    if (!m) {
+        throw refuse("type", `${field} ${JSON.stringify(v)} is not a size`, `Use a number with kb, mb, gb or tb, e.g. "${field}": "8gb".`, file);
+    }
+    const n = Number(m[1]);
+    const unit = (m[2] ?? "").toLowerCase();
+    const bytes = unit === "kb" ? n * 1024 : unit === "mb" ? n * 1024 ** 2 : unit === "gb" ? n * 1024 ** 3 : unit === "tb" ? n * 1024 ** 4 : n;
+    return bytes / 1024 ** 3;
+}
+const trim = (n) => (Number.isInteger(n) ? String(n) : n.toFixed(2).replace(/0+$/, "").replace(/\.$/, ""));
+function portList(v, field, file) {
+    if (v === undefined || v === null)
+        return [];
+    const items = Array.isArray(v) ? v : [v];
+    const out = [];
+    for (const item of items) {
+        if (typeof item === "number" && Number.isInteger(item) && item >= 0 && item <= 65535) {
+            out.push(item);
+            continue;
+        }
+        if (typeof item === "string") {
+            const m = /^(?:[^:]*:)?(\d{1,5})$/.exec(item.trim());
+            if (m && Number(m[1]) <= 65535) {
+                out.push(Number(m[1]));
+                continue;
+            }
+        }
+        throw refuse("type", `${field} entry ${JSON.stringify(item)} is not a port`, `Use a number, or "host:port", e.g. "${field}": [3000].`, file);
+    }
+    return out;
+}
+export function lifecycleSteps(v, field, ctx, file) {
+    if (v === undefined || v === null)
+        return [];
+    const one = (value, label) => {
+        if (typeof value === "string") {
+            const cmd = substituteString(value, ctx).trim();
+            if (!cmd)
+                throw refuse("type", `${field}${label ? `.${label}` : ""} is empty`, `Give ${field} a command, or remove it.`, file);
+            return label === undefined ? { field, command: cmd } : { field, command: cmd, label };
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 0 || !value.every((x) => typeof x === "string")) {
+                throw refuse("type", `${field}${label ? `.${label}` : ""} must be an array of strings`, `Use ["npm", "install"].`, file);
+            }
+            const cmd = value.map((x) => shellQuote(substituteString(x, ctx))).join(" ");
+            return label === undefined ? { field, command: cmd } : { field, command: cmd, label };
+        }
+        throw refuse("type", `${field}${label ? `.${label}` : ""} must be a string, an array or an object`, "See containers.dev/implementors/json_reference.", file);
+    };
+    if (typeof v === "object" && !Array.isArray(v)) {
+        return Object.entries(v).map(([label, value]) => one(value, label));
+    }
+    return [one(v)];
+}
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export function wrapCommand(plan, command) {
+    const inner = [`cd ${shellQuote(plan.workspaceFolder)}`, command].join(" && ");
+    return plan.user === undefined || plan.user === "root" ? inner : `su ${plan.user} -c ${shellQuote(inner)}`;
+}
+export function snapshotEnv(plan) {
+    return Object.keys(plan.env).length ? { ...plan.env } : undefined;
+}
+export function snapshotUsers(plan) {
+    const user = plan.remoteUser ?? plan.user;
+    return user === undefined ? undefined : { user, setupUser: "root" };
+}
+export function planSetup(plan, opts = {}) {
+    const steps = [];
+    if (opts.repo && opts.commit) {
+        const ws = shellQuote(plan.workspaceFolder);
+        const clone = [
+            `mkdir -p ${shellQuote(resolve(plan.workspaceFolder, ".."))}`,
+            `git clone ${shellQuote(opts.repo)} ${ws}`,
+            `git -C ${ws} checkout -q ${shellQuote(opts.commit)}`,
+            ...(plan.user && plan.user !== "root" ? [`chown -R ${plan.user} ${ws}`] : []),
+        ].join(" && ");
+        steps.push(clone);
+    }
+    for (const step of plan.lifecycle)
+        steps.push(wrapCommand(plan, step.command));
+    for (const step of opts.userSetup ?? [])
+        steps.push(step);
+    return steps;
+}
+export function planJson(plan, setup) {
+    return {
+        spec: plan.spec,
+        file: plan.file,
+        ...(plan.name === undefined ? {} : { name: plan.name }),
+        source: plan.source,
+        workspace_folder: plan.workspaceFolder,
+        ...(plan.user === undefined ? {} : { user: plan.user }),
+        env: plan.env,
+        ports: plan.ports,
+        ...(plan.tier === undefined ? {} : { tier: plan.tier, tier_reason: plan.tierReason }),
+        lifecycle: plan.lifecycle.map((s) => ({ field: s.field, ...(s.label === undefined ? {} : { label: s.label }), command: s.command })),
+        setup,
+        ignored: plan.ignored,
+        notes: plan.notes,
+    };
+}
+export function planLines(plan, setup) {
+    const lines = [`devcontainer: ${plan.file}${plan.name ? ` (${plan.name})` : ""}`];
+    lines.push(plan.source.kind === "image"
+        ? `  image     ${plan.source.image}`
+        : `  build     ${plan.source.dockerfile} (context ${plan.source.context})`);
+    lines.push(`  workspace ${plan.workspaceFolder}${plan.user ? ` · user ${plan.user}` : ""}`);
+    if (plan.tier)
+        lines.push(`  tier      ${plan.tier} — ${plan.tierReason ?? ""}`);
+    const envKeys = Object.keys(plan.env);
+    if (envKeys.length)
+        lines.push(`  env       ${envKeys.join(", ")}`);
+    if (plan.ports.length)
+        lines.push(`  ports     ${plan.ports.join(", ")} (expose one with: promigence port expose PORT --sandbox SID)`);
+    setup.forEach((s, idx) => lines.push(`  setup[${idx}] ${s}`));
+    for (const ig of plan.ignored)
+        lines.push(`  ignored   ${ig.field}: ${ig.why}`);
+    for (const n of plan.notes)
+        lines.push(`  note      ${n}`);
+    return lines;
+}