chamba 0.3.0 → 0.4.0

package/dist/lib/dockerfile-builder.js

@@ -0,0 +1,267 @@
+// =========================================================================================================================================
+// src/lib/dockerfile-builder.ts - In-memory Dockerfile assembly and temp-file build
+// Combines base template + profile hook + USER instruction at build time
+// =========================================================================================================================================
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spinner } from "@clack/prompts";
+import { CONTAINER_HOME, CONTAINER_NAME_PREFIX, CONTAINER_STARTUP, CONTAINER_USER, LABEL_BUILD_HASH, LABEL_MANAGED, WEB_KEY_FILE_PATH, } from "./constants.js";
+// --- User shell config appended after USER instruction -----------------------------------------------------------------------------------
+const USER_SHELL_CONFIG = `
+# ---------------------------------------------------------------------------
+# User shell config (PATH, prompt, welcome message, status alias)
+# ---------------------------------------------------------------------------
+ENV PATH="${CONTAINER_HOME}/.cargo/bin:${CONTAINER_HOME}/.bun/bin:${CONTAINER_HOME}/.local/bin:/usr/local/go/bin:\${PATH}"
+# Prompt helper: print the working directory relative to the workspace root, so /workspace shows as
+# "/" and /workspace/src shows as "/src". Paths outside the workspace fall back to their full path.
+RUN echo '__chamba_pwd() { local p="\${PWD#/workspace}"; printf "/%s" "\${p#/}"; }' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '# The web interface URL, key and all. The key is minted by the webterm server at every start and' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '# published to the key file, so the greeting reads it back instead of holding a URL that goes stale.' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '__chamba_web_url() { if [ -r ${WEB_KEY_FILE_PATH} ]; then echo "\${CHAMBA_WEB_URL}/?k=$(head -n 1 ${WEB_KEY_FILE_PATH})"; else echo "\${CHAMBA_WEB_URL}"; fi; }' \\
+        >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'export PS1="\\[\\033[01;32m\\][chamba@\${CHAMBA_WORKSPACE}]\\[\\033[00m\\] \\[\\033[01;34m\\]\\$(__chamba_pwd)\\[\\033[00m\\] \\[\\033[01;32m\\]❯\\[\\033[00m\\] "' \\
+        >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'echo ""' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'echo -e "\\033[32m●\\033[0m  \\033[1mYou'"'"'re now in a chamba sandbox\\033[0m \\033[90m·\\033[0m \\033[1m\${CHAMBA_WORKSPACE}\\033[0m"' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'echo ""' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'echo -e "   \\033[90m▸ Run \\033[38;5;208mclaude\\033[90m, \\033[38;5;208mopencode\\033[90m, or \\033[38;5;208mcodex\\033[90m to start an agent.\\033[0m"' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'echo -e "   \\033[90m▸ Run \\033[97mstatus\\033[90m to see container details & installed versions.\\033[0m"' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'echo -e "   \\033[90m▸ Run \\033[97mexit\\033[90m to end the session and return to the host.\\033[0m"' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'echo ""' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '# The web interface, where the agents usually run. CHAMBA_WEB_URL is injected by docker run whenever' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '# a host port could be published for it, so its absence means this session has no web address.' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '# The URL gets its own line: on a host that could not open a browser, this banner is how it is found.' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'if [ -n "$CHAMBA_WEB_URL" ]; then' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '    echo -e "\\033[32m●\\033[0m  \\033[90mThe web interface for this workspace:\\033[0m"' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '    echo ""' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '    echo -e "   \\033[97m$(__chamba_web_url)\\033[0m"' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo '    echo ""' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'fi' >> ${CONTAINER_HOME}/.bashrc && \\
+    echo 'alias status="node ${CONTAINER_STARTUP}"' >> ${CONTAINER_HOME}/.bashrc
+
+CMD ["/bin/bash"]
+`;
+// --- Build Dockerfile content ------------------------------------------------------------------------------------------------------------
+/**
+ * Assemble a Dockerfile from the base template, optional profile hook, and USER instruction.
+ * The resulting Dockerfile is never persisted - it's written to a temp file at build time.
+ */
+export function buildDockerfile(baseTemplatePath, profileHook) {
+    let content = readFileSync(baseTemplatePath, "utf8");
+    // Append profile hook if provided
+    if (profileHook?.trim()) {
+        content += `\n# ---------------------------------------------------------------------------\n`;
+        content += `# Profile hook (from chamba.yaml)\n`;
+        content += `# ---------------------------------------------------------------------------\n`;
+        content += profileHook.endsWith("\n") ? profileHook : `${profileHook}\n`;
+    }
+    // USER must come after profile hook and before shell config
+    content += `\nUSER ${CONTAINER_USER}\n`;
+    content += USER_SHELL_CONFIG;
+    return content;
+}
+// --- Build hash for image staleness detection --------------------------------------------------------------------------------------------
+// Filenames (relative to the templates dir) of every artifact that the Dockerfile bakes into the image
+// via COPY. Edits to any of these change the build hash and trigger a rebuild prompt at session start.
+// Kept in sync with templates/Dockerfile by the bidirectional test in tests/dockerfile-builder.test.ts.
+export const BAKED_TEMPLATE_FILES = [
+    "claude-statusline.sh",
+    "context-usage.sh",
+    "git-readonly-wrapper.mjs",
+    "npmrc",
+    "pnpm-config.yaml",
+    "runtime-constants.mjs",
+    "startup-git-mode.mjs",
+    "startup.mjs",
+    "webpane.sh",
+    "webterm.sh",
+];
+// Directories (relative to the templates dir) baked into the image via a directory COPY. Hashed
+// recursively by computeBuildHash so editing any file inside triggers a rebuild prompt, with
+// node_modules skipped - a local install there must never flip the hash (it is .dockerignore'd too).
+export const BAKED_TEMPLATE_DIRS = ["webterm"];
+// Relative paths of every regular file under dir (sorted, node_modules subtrees skipped). Missing
+// dirs yield [] for the same reason computeBuildHash tolerates missing files: minimal test contexts.
+function walkTemplateDir(root, prefix = "") {
+    const files = [];
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        if (entry.name === "node_modules")
+            continue;
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            files.push(...walkTemplateDir(join(root, entry.name), rel));
+        else if (entry.isFile())
+            files.push(rel);
+    }
+    return files.sort();
+}
+/**
+ * Fingerprint everything the package contributes to the image: the assembled Dockerfile content
+ * plus every file in BAKED_TEMPLATE_FILES, hashed in deterministic order.
+ *
+ * Tolerates missing files in buildContextDir. In production (real package install) all baked files
+ * exist, so the existsSync branch never fires. In tests that build minimal images from a temp
+ * contextDir, missing files naturally produce a different hash than production - exactly the
+ * contract the staleness tests rely on.
+ */
+export function computeBuildHash(dockerfileContent, buildContextDir) {
+    const h = createHash("sha256");
+    h.update("dockerfile:\n");
+    h.update(dockerfileContent);
+    for (const name of [...BAKED_TEMPLATE_FILES].sort()) {
+        h.update(`\nfile:${name}\n`);
+        const path = join(buildContextDir, name);
+        if (existsSync(path)) {
+            h.update(readFileSync(path));
+        }
+    }
+    for (const dir of [...BAKED_TEMPLATE_DIRS].sort()) {
+        for (const rel of walkTemplateDir(join(buildContextDir, dir))) {
+            h.update(`\nfile:${dir}/${rel}\n`);
+            h.update(readFileSync(join(buildContextDir, dir, rel)));
+        }
+    }
+    return h.digest("hex");
+}
+// --- Image staleness detection -----------------------------------------------------------------------------------------------------------
+//
+// Called at session start; returns true if the running container's image is older than the current
+// package and needs a rebuild prompt.
+//
+// Mechanism: at build time, buildImageWithTempfile below stamps every image with a chamba.build-hash
+// label carrying computeBuildHash's fingerprint of the assembled Dockerfile + every baked template
+// file. At session start we recompute the expected hash from current package sources and compare.
+// Any change to templates/Dockerfile, the active profile hook, or any baked template file produces a
+// different hash -> rebuild prompt fires.
+//
+// When shipping a new bake-time artifact:
+//   - Editing an existing template file or the Dockerfile -> auto-detected. No action.
+//   - Adding a NEW templated COPY -> add the filename to BAKED_TEMPLATE_FILES above. The unit test in
+//     tests/dockerfile-builder.test.ts will fail until you do.
+//
+// Cosmetic Dockerfile edits (comment-only, whitespace) DO trigger a rebuild for users on prior
+// images. This is intentional: the Dockerfile and template files are rarely edited, so any change
+// is treated as meaningful. A cosmetic edit here costs every user a rebuild, so it is worth asking
+// whether the change is worth making at all.
+/** Returns true if the container's stamped chamba.build-hash label does not match the expected hash. */
+export function isImageStale(containerName, expectedBuildHash) {
+    const result = spawnSync("docker", ["inspect", "--format", `{{ index .Config.Labels "${LABEL_BUILD_HASH}" }}`, containerName], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    if (result.status !== 0)
+        return true;
+    return result.stdout.trim() !== expectedBuildHash;
+}
+// --- Build image with temp file ----------------------------------------------------------------------------------------------------------
+// Grey ANSI for the inline build percentage on the spinner line.
+const grey = (s) => `\x1b[90m${s}\x1b[0m`;
+/**
+ * Run docker build behind a single clack spinner for interactive sessions.
+ * All raw buildx output is captured, never streamed. BuildKit "[ n/N ]" step markers (from
+ * --progress=plain) are parsed into a grey percentage on the spinner line when available; if nothing
+ * parses, the spinner just keeps animating with the plain text. The captured log is written to stderr
+ * only on failure, so a broken build stays diagnosable.
+ */
+function runBuildWithSpinner(buildArgs) {
+    return new Promise((resolve) => {
+        const s = spinner();
+        const baseMessage = "Docker rebuilding container..";
+        s.start(baseMessage);
+        let captured = "";
+        let lastStep = 0;
+        let totalSteps = 0;
+        const onData = (chunk) => {
+            const text = chunk.toString();
+            captured += text;
+            try {
+                for (const m of text.matchAll(/\[\s*(\d+)\/(\d+)\]/g)) {
+                    const cur = Number(m[1]);
+                    const total = Number(m[2]);
+                    if (total > 0)
+                        totalSteps = total;
+                    if (cur > lastStep)
+                        lastStep = cur;
+                }
+                if (totalSteps > 0) {
+                    const pct = Math.min(100, Math.round((lastStep / totalSteps) * 100));
+                    s.message(`${baseMessage}  ${grey(`${pct}%`)}`);
+                }
+            }
+            catch {
+                // Parsing must never affect the build; fall back to the plain animated spinner.
+            }
+        };
+        const child = spawn("docker", buildArgs, { stdio: ["ignore", "pipe", "pipe"] });
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.on("error", (err) => {
+            s.stop("Docker build failed");
+            process.stderr.write(`${err.message}\n`);
+            resolve({ status: 1 });
+        });
+        child.on("close", (code) => {
+            const status = code ?? 1;
+            if (status === 0) {
+                s.stop("Container image ready");
+            }
+            else {
+                s.stop("Docker build failed");
+                process.stderr.write(captured);
+            }
+            resolve({ status });
+        });
+    });
+}
+/**
+ * Write Dockerfile content to a temp file, run docker build, then clean up.
+ * Build context is always the templates directory so COPY instructions resolve correctly.
+ * Quiet mode (tests) runs synchronously with captured output; interactive mode shows a spinner.
+ */
+export async function buildImageWithTempfile(dockerfileContent, buildContextDir, imageName, noCache = false, quiet = false) {
+    const tmpFile = join(tmpdir(), `${CONTAINER_NAME_PREFIX}Dockerfile-${randomBytes(8).toString("hex")}`);
+    try {
+        writeFileSync(tmpFile, dockerfileContent);
+        const buildHash = computeBuildHash(dockerfileContent, buildContextDir);
+        const buildArgs = [
+            "build",
+            "--label",
+            `${LABEL_MANAGED}=true`,
+            "--label",
+            `${LABEL_BUILD_HASH}=${buildHash}`,
+            "-f",
+            tmpFile,
+            "-t",
+            imageName,
+        ];
+        if (noCache)
+            buildArgs.push("--no-cache");
+        // Quiet mode (tests): synchronous, output captured, no spinner.
+        if (quiet) {
+            buildArgs.push(buildContextDir);
+            const result = spawnSync("docker", buildArgs, { stdio: "pipe" });
+            return { status: result.status ?? 1 };
+        }
+        // Interactive mode: line-oriented progress so step markers are parseable, hidden behind a spinner.
+        buildArgs.push("--progress=plain", buildContextDir);
+        return await runBuildWithSpinner(buildArgs);
+    }
+    finally {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch {
+            // temp file cleanup is best-effort
+        }
+    }
+}

package/dist/lib/env.js

@@ -0,0 +1,78 @@
+// =========================================================================================================================================
+// src/lib/env.ts - Resolve the `env` field into container environment injection (files + inline vars)
+// An `env` entry is either an env-file path (no '=') loaded via --env-file, or an inline KEY=VALUE injected via -e.
+// Config is the source of truth: a hashed label over inline vars + resolved file contents recreates the container on change.
+// =========================================================================================================================================
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// --- Constants ---------------------------------------------------------------------------------------------------------------------------
+// Inline var keys must be valid shell env identifiers - the same pattern the `ports` env field uses.
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// --- Config validation and normalization -------------------------------------------------------------------------------------------------
+/**
+ * Validate and normalize the raw `env` field into inline vars and file entries. This is the single source of
+ * truth for env semantics (unit-testable without the JSON Schema). A scalar or undefined is normalized to an
+ * array; entries are trimmed and empties dropped. Classification is by presence of '=': an entry with '=' is
+ * an inline KEY=VALUE var; an entry without '=' is an env-file path resolved relative to the workspace dir.
+ * Throws on the first malformed inline entry with a clear message. Missing files never throw - they are
+ * flagged exists:false and warned about at startup rather than failing the session.
+ */
+export function validateEnvConfig(raw, workspaceDir) {
+    const entries = (Array.isArray(raw) ? raw : raw === undefined ? [] : [raw]).map((e) => e.trim()).filter((e) => e.length > 0);
+    const inlineVars = [];
+    const files = [];
+    for (const entry of entries) {
+        const eq = entry.indexOf("=");
+        if (eq === -1) {
+            // No '=' -> file path, resolved relative to the workspace dir.
+            const path = join(workspaceDir, entry);
+            files.push({ path, exists: existsSync(path) });
+        }
+        else {
+            // Has '=' -> inline KEY=VALUE. The key must be a valid env identifier; the value may be empty or contain further '='.
+            const key = entry.slice(0, eq);
+            if (!ENV_KEY_PATTERN.test(key)) {
+                throw new Error(`env: invalid variable "${entry}" - the key must match ${ENV_KEY_PATTERN.source} (e.g. FOO=bar).`);
+            }
+            inlineVars.push(entry);
+        }
+    }
+    return { inlineVars, files };
+}
+// --- Docker argument builders (pure) -----------------------------------------------------------------------------------------------------
+/**
+ * Docker run args for env injection: --env-file for each existing file (missing files omitted), then
+ * -e KEY=VALUE per inline var. Files come first so an inline var wins a duplicate key - docker applies later
+ * -e over an earlier --env-file - which lets a chamba.yaml inline var override a value from an env file.
+ */
+export function envRunArgs(cfg) {
+    const fileArgs = cfg.files.filter((f) => f.exists).flatMap((f) => ["--env-file", f.path]);
+    const inlineArgs = cfg.inlineVars.flatMap((v) => ["-e", v]);
+    return [...fileArgs, ...inlineArgs];
+}
+/** One warning line per missing env file. A missing file is skipped, never fatal. */
+export function envWarnings(cfg) {
+    return cfg.files.filter((f) => !f.exists).map((f) => `env "${f.path}" not found - skipping`);
+}
+// --- Fingerprint -------------------------------------------------------------------------------------------------------------------------
+/**
+ * Deterministic fingerprint over the resolved env config, used as the container LABEL_ENV. Covers each inline
+ * KEY=VALUE and, for each existing file, its path plus contents - so editing an inline var, editing a file's
+ * contents, or repointing at a different file recreates the container on the next session. An empty config
+ * (no inline vars and no existing files) fingerprints to "" so an env-less workspace never recreates on
+ * account of this label. Hashed so no secret values leak into docker labels (which are visible via inspect).
+ */
+export function envLabel(cfg) {
+    if (cfg.inlineVars.length === 0 && cfg.files.every((f) => !f.exists))
+        return "";
+    const parts = [];
+    for (const v of cfg.inlineVars)
+        parts.push(`e:${v}`);
+    for (const f of cfg.files) {
+        if (!f.exists)
+            continue;
+        parts.push(`f:${f.path}\n${readFileSync(f.path, "utf8")}`);
+    }
+    return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 12);
+}

package/dist/lib/global-config.js

@@ -0,0 +1,66 @@
+// =========================================================================================================================================
+// src/lib/global-config.ts - Host-global settings store (not tied to any workspace)
+// Lives at ~/.chamba/global/config as key=value lines, mirroring the per-workspace .lock idiom.
+// Settings live here when they are host-wide rather than per-workspace.
+// =========================================================================================================================================
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CHAMBA_DIR, GLOBAL_CONFIG_FILE, GLOBAL_DIR, WEB_RANGE_DEFAULT } from "./constants.js";
+import { formatWebRange, parseWebRange } from "./ports.js";
+// --- Keys --------------------------------------------------------------------------------------------------------------------------------
+/** Field names mapped to the keys written in the global config file. */
+export const GLOBAL_CONFIG_KEYS = {
+    webRange: "web_range",
+};
+// --- Path --------------------------------------------------------------------------------------------------------------------------------
+/** Absolute path to the global config file - ~/.chamba/global/config */
+export function globalConfigPath() {
+    return join(homedir(), CHAMBA_DIR, GLOBAL_DIR, GLOBAL_CONFIG_FILE);
+}
+// --- Parse / write -----------------------------------------------------------------------------------------------------------------------
+// Parse the config into an ordered map of raw key=value pairs. Returns an empty map when the file is
+// missing or unreadable - absence is not an error, it just means defaults apply. Unknown keys are kept
+// so a newer chamba's settings survive a write by an older one.
+function parseGlobalConfig() {
+    const config = new Map();
+    try {
+        const lines = readFileSync(globalConfigPath(), "utf8")
+            .trimEnd()
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean);
+        for (const line of lines) {
+            const eq = line.indexOf("=");
+            if (eq === -1)
+                continue;
+            config.set(line.slice(0, eq), line.slice(eq + 1));
+        }
+    }
+    catch {
+        // Missing or unreadable - treat as empty.
+    }
+    return config;
+}
+// Write the raw key=value map back to ~/.chamba/global/config, creating ~/.chamba/global/ on demand.
+// Unlike the per-workspace lock (which no-ops when missing), the global config has no init step, so it
+// is created lazily on the first write.
+function writeGlobalConfig(config) {
+    mkdirSync(join(homedir(), CHAMBA_DIR, GLOBAL_DIR), { recursive: true });
+    const content = `${[...config].map(([key, value]) => `${key}=${value}`).join("\n")}\n`;
+    writeFileSync(globalConfigPath(), content);
+}
+// --- Web agent interface -----------------------------------------------------------------------------------------------------------------
+/** Read the web interface host-port range. Falls back to the default when unset, missing, or invalid. */
+export function readWebRange() {
+    const value = parseGlobalConfig().get(GLOBAL_CONFIG_KEYS.webRange);
+    const parsed = value !== undefined ? parseWebRange(value) : null;
+    // The default is a constant that always parses; the assertion just narrows the type.
+    return parsed ?? parseWebRange(WEB_RANGE_DEFAULT);
+}
+/** Write the web interface host-port range. Creates the config file on demand and preserves all other keys. */
+export function writeWebRange(range) {
+    const config = parseGlobalConfig();
+    config.set(GLOBAL_CONFIG_KEYS.webRange, formatWebRange(range));
+    writeGlobalConfig(config);
+}

package/dist/lib/pnpm-store.js

@@ -0,0 +1,19 @@
+// =========================================================================================================================================
+// src/lib/pnpm-store.ts - Per-workspace pnpm global store mount
+// pnpm hardlinks from its global store into node_modules. Hardlinks cannot cross filesystems, so when the global store sits on the
+// container overlay FS while /workspace is a host bind mount, pnpm falls back to creating a per-project .pnpm-store inside the project -
+// which then ends up on the host repo. Mounting a host-side cache dir onto pnpm's default global store path puts the store on the same
+// device as the workspace and node_modules shadow, eliminating the fallback.
+// =========================================================================================================================================
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { CONTAINER_PNPM_STORE, PNPM_STORE_DIR } from "./constants.js";
+/**
+ * Lazily creates the host-side pnpm store directory under the workspace cache dir
+ * and returns -v args mounting it onto pnpm's default global store path in the container.
+ */
+export function buildPnpmStoreMountArgs(workspaceCacheDir) {
+    const hostStore = join(workspaceCacheDir, PNPM_STORE_DIR);
+    mkdirSync(hostStore, { recursive: true });
+    return ["-v", `${hostStore}:${CONTAINER_PNPM_STORE}`];
+}

package/dist/lib/ports.js

@@ -0,0 +1,210 @@
+// =========================================================================================================================================
+// src/lib/ports.ts - Publish static, loopback-only host ports into the container
+// A `ports` entry is either a bare integer (identity map, 127.0.0.1:N:N) or a "HOST:CONTAINER" string. Config is the
+// source of truth: a host port already in use is a clear, hard failure that names the offending entry.
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createServer } from "node:net";
+import { WEB_CONTAINER_PORT } from "./constants.js";
+// --- Constants ---------------------------------------------------------------------------------------------------------------------------
+// The CLI runs as a non-root user, so the availability probe (net bind) cannot bind ports below 1024.
+export const PORT_MIN = 1024;
+export const PORT_MAX = 65535;
+// Publish and probe on loopback only - never 0.0.0.0. Nothing on the LAN may reach these sessions.
+export const PORT_LOOPBACK_HOST = "127.0.0.1";
+// --- Config validation and normalization -------------------------------------------------------------------------------------------------
+/** A single port number is a usable, unprivileged host/container port. */
+export function inRange(port) {
+    return Number.isInteger(port) && port >= PORT_MIN && port <= PORT_MAX;
+}
+/** Human-readable label for an entry, used in error and notice messages. */
+function describe(m) {
+    return m.host === m.container ? `port ${m.host}` : `mapping "${m.host}:${m.container}"`;
+}
+/**
+ * Validate and normalize the raw `ports` entries into host->container mappings. This is the single source of
+ * truth for ports semantics (unit-testable without the JSON Schema). Throws on the first problem with a clear,
+ * actionable message. The JSON Schema enforces coarse structure (types, the env pattern, no unknown keys); the
+ * range and cross-entry rules live here.
+ */
+export function validatePortsConfig(entries) {
+    const mappings = [];
+    const seenHosts = new Set();
+    const seenEnvs = new Set();
+    for (const entry of entries) {
+        let host;
+        let container;
+        if (typeof entry.port === "number") {
+            // Bare integer -> identity map (host === container).
+            if (!inRange(entry.port)) {
+                throw new Error(`ports: port ${entry.port} must be between ${PORT_MIN} and ${PORT_MAX}. ` +
+                    'Did you mean a "HOST:CONTAINER" mapping? Quote it, e.g. "8080:3000".');
+            }
+            host = entry.port;
+            container = entry.port;
+        }
+        else {
+            // "HOST:CONTAINER" string -> explicit map, same order as docker (host first).
+            const match = /^(\d+):(\d+)$/.exec(entry.port);
+            if (!match) {
+                throw new Error(`ports: invalid port "${entry.port}". Use a bare integer (e.g. 4820) or a "HOST:CONTAINER" mapping (e.g. "8080:3000").`);
+            }
+            host = Number(match[1]);
+            container = Number(match[2]);
+            if (!inRange(host) || !inRange(container)) {
+                throw new Error(`ports: mapping "${entry.port}" is out of range - host and container ports must both be between ${PORT_MIN} and ${PORT_MAX}.`);
+            }
+        }
+        // The web agent interface always binds this port inside the container, so a second publisher would
+        // make whichever bound first win and the web URL could front the user's service. Reserved on every
+        // host: the interface comes up with every container, and nothing in chamba.yaml may take its port.
+        if (container === WEB_CONTAINER_PORT) {
+            throw new Error(`ports: container port ${WEB_CONTAINER_PORT} is reserved for the chamba web agent interface. ` +
+                "Publish your service on a different container port.");
+        }
+        if (seenHosts.has(host)) {
+            throw new Error(`ports: duplicate host port ${host}. Each entry must publish a distinct host port.`);
+        }
+        seenHosts.add(host);
+        const mapping = { host, container };
+        if (entry.env !== undefined) {
+            if (host !== container) {
+                throw new Error(`ports: ${describe(mapping)} declares env "${entry.env}", but env is only allowed on identity entries (a bare port number).`);
+            }
+            if (seenEnvs.has(entry.env)) {
+                throw new Error(`ports: duplicate env "${entry.env}". Each entry must inject a distinct env var.`);
+            }
+            seenEnvs.add(entry.env);
+            mapping.env = entry.env;
+        }
+        mappings.push(mapping);
+    }
+    return mappings;
+}
+/**
+ * Parse a "START-END" range string. Returns null when the shape is wrong, either bound is out of the
+ * usable port range, or start is not strictly below end. The settings menu turns each null into a
+ * specific validation message; readWebRange falls back to the default.
+ */
+export function parseWebRange(value) {
+    const match = /^(\d+)-(\d+)$/.exec(value.trim());
+    if (!match)
+        return null;
+    const start = Number(match[1]);
+    const end = Number(match[2]);
+    if (!inRange(start) || !inRange(end))
+        return null;
+    if (start >= end)
+        return null;
+    return { start, end };
+}
+/** Format a range back to its stored "START-END" form. */
+export function formatWebRange(range) {
+    return `${range.start}-${range.end}`;
+}
+// --- Availability probing (host I/O) -----------------------------------------------------------------------------------------------------
+/** True if nothing on the host holds a loopback socket for this port (docker-proxy / userland-proxy=true, or a plain squatter). */
+export function canBind(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => server.close(() => resolve(true)));
+        server.listen(port, PORT_LOOPBACK_HOST);
+    });
+}
+/** Host ports in a `docker ps` {{.Ports}} column: "127.0.0.1:4820->4820/tcp", "[::]:5432->5432/tcp". */
+export function parsePublishedPorts(psOutput) {
+    const ports = new Set();
+    // The host port precedes "->".
+    for (const match of psOutput.matchAll(/:(\d+)->/g)) {
+        const n = Number(match[1]);
+        if (Number.isInteger(n))
+            ports.add(n);
+    }
+    return ports;
+}
+/**
+ * Host ports currently published by any running container. On native Linux with userland-proxy=false no host
+ * socket exists (DNAT), so canBind alone would wrongly report a published port as free - this covers that case.
+ * Returns an empty set when docker is unavailable (the bind probe still applies).
+ */
+export function dockerPublishedPorts() {
+    const result = spawnSync("docker", ["ps", "--format", "{{.Ports}}"], { encoding: "utf8", stdio: "pipe" });
+    if (result.status !== 0 || !result.stdout)
+        return new Set();
+    return parsePublishedPorts(result.stdout);
+}
+/**
+ * Host ports published by one named container, and only while it is running - a stopped container holds no
+ * port even though its config still declares one. Lets a caller tell "this port is taken by my own live
+ * container" (fine) from "taken by something else" (not fine). Empty when docker is unavailable.
+ */
+export function containerPublishedPorts(containerName) {
+    const result = spawnSync("docker", ["ps", "--filter", `name=^${containerName}$`, "--format", "{{.Ports}}"], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    if (result.status !== 0 || !result.stdout)
+        return new Set();
+    return parsePublishedPorts(result.stdout);
+}
+/**
+ * Check that every mapped host port is free before we create the container. Called only on the create path - the
+ * old container has already been removed, so we never probe our own live port. Throws a clear error naming the taken
+ * host port and its entry on the first collision. Doing this here, rather than letting `docker run` fail, buys two
+ * things: the error names the offending entry (docker's raw message does not), and no doomed `created` container is
+ * left behind on a clash.
+ *
+ * `webPort` names the chamba-assigned web interface mapping, which is skipped: chamba picked that port itself, so the
+ * caller drops the mapping and runs the session without the interface rather than failing a session over it. Only chamba.yaml
+ * ports - config the user wrote and expects to be honoured - are hard failures here.
+ */
+export async function assertHostPortsAvailable(mappings, webPort) {
+    if (mappings.length === 0)
+        return;
+    const dockerPorts = dockerPublishedPorts();
+    for (const m of mappings) {
+        // Matched on both sides, so only chamba's own mapping is skipped - never a user entry that happens
+        // to sit on the same host port.
+        if (webPort !== undefined && m.host === webPort && m.container === WEB_CONTAINER_PORT)
+            continue;
+        const free = !dockerPorts.has(m.host) && (await canBind(m.host));
+        if (!free) {
+            const via = m.host === m.container ? "" : ` (from the "${m.host}:${m.container}" mapping)`;
+            throw new Error(`ports: host port ${m.host}${via} is already in use on the host. ` +
+                "Free it, or pick a different host port in chamba.yaml.");
+        }
+    }
+}
+// --- Docker argument builders (pure) -----------------------------------------------------------------------------------------------------
+/** Loopback-only publish flags: 127.0.0.1:HOST:CONTAINER per mapping. */
+export function portPublishArgs(mappings) {
+    return mappings.flatMap((m) => ["-p", `${PORT_LOOPBACK_HOST}:${m.host}:${m.container}`]);
+}
+/** Env injection flags carrying the host port number, only for identity entries that declare an env var. */
+export function portEnvArgs(mappings) {
+    return mappings.flatMap((m) => (m.env ? ["-e", `${m.env}=${m.host}`] : []));
+}
+// --- Fingerprint -------------------------------------------------------------------------------------------------------------------------
+/**
+ * Deterministic fingerprint over the normalized mappings (host, container, env), used as the container LABEL_PORTS.
+ * Editing a port, mapping, or env recreates the container; a workspace with no ports fingerprints to "" so a
+ * container without published ports never recreates on account of this label.
+ */
+export function portsLabel(mappings) {
+    if (mappings.length === 0)
+        return "";
+    const parts = mappings.map((m) => `${m.host}:${m.container}:${m.env ?? ""}`).sort();
+    return createHash("sha256").update(parts.join(",")).digest("hex").slice(0, 12);
+}
+// --- Session notice ----------------------------------------------------------------------------------------------------------------------
+/**
+ * One-line startup notice per mapping. Identity: `port 4820 open` (plus ` (ENV)` when an env is injected).
+ * Mapping: `port 8080 -> 3000 open` (ASCII arrow - a UI string literal, no Unicode).
+ */
+export function formatPortNotice(m) {
+    if (m.host === m.container)
+        return `port ${m.host} open${m.env ? ` (${m.env})` : ""}`;
+    return `port ${m.host} -> ${m.container} open`;
+}