chamba 0.3.0 → 0.4.0

package/templates/startup-git-mode.mjs

@@ -0,0 +1,145 @@
+// =============================================================================
+// startup-git-mode.mjs -- Git mode application + verification for startup.mjs
+// Baked into the container image alongside startup.mjs at /home/devuser/.
+//
+// Strict / local / unrestricted are read from the CHAMBA_GIT_MODE env var injected by
+// dev.ts. As root we apply the requested state to /etc/gitconfig and the
+// /usr/local/bin/git symlink; as devuser we only verify that the state already
+// matches (the previous root invocation is what put it there).
+// Must use only Node.js built-ins -- no external packages available in container.
+// =============================================================================
+
+import { execSync } from "node:child_process";
+import { lstatSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs";
+import { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE } from "./runtime-constants.mjs";
+
+const VALID_GIT_MODES = Object.values(GIT_MODE);
+
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function isWrapperSymlinkInPlace() {
+    if (!lstatExists(GIT_WRAPPER_PATH)) return false;
+    try {
+        const st = lstatSync(GIT_WRAPPER_PATH);
+        if (!st.isSymbolicLink()) return false;
+        return readlinkSync(GIT_WRAPPER_PATH) === GIT_WRAPPER_SOURCE;
+    } catch {
+        return false;
+    }
+}
+
+function removeWrapperIfPresent() {
+    if (!lstatExists(GIT_WRAPPER_PATH)) return;
+    try {
+        unlinkSync(GIT_WRAPPER_PATH);
+    } catch {
+        // Already gone or inaccessible -- subsequent verification will catch it
+    }
+}
+
+function applyAsRoot(gitMode, protocolValue, fail) {
+    // Use absolute path to bypass /usr/local/bin/git (which may already be the read-only
+    // wrapper from a prior strict-mode session and would block this legitimate setup write).
+    try {
+        execSync(`/usr/bin/git config --system protocol.allow ${protocolValue}`, { stdio: "pipe" });
+    } catch {
+        fail("git mode", `failed to set protocol.allow=${protocolValue}`);
+    }
+
+    if (gitMode === GIT_MODE.strict) {
+        if (!isWrapperSymlinkInPlace()) {
+            // Remove any pre-existing /usr/local/bin/git (stale symlink, leftover binary)
+            // so symlinkSync below doesn't EEXIST.
+            removeWrapperIfPresent();
+            try {
+                symlinkSync(GIT_WRAPPER_SOURCE, GIT_WRAPPER_PATH);
+            } catch {
+                fail("git wrapper", `failed to install ${GIT_WRAPPER_PATH}`);
+            }
+        }
+        return;
+    }
+    removeWrapperIfPresent();
+}
+
+function verifyProtocol(gitMode, protocolValue, run, ok, fail) {
+    const gitProtocol = run("git config --system protocol.allow");
+    if (gitProtocol === protocolValue) {
+        ok("git mode", `${gitMode} (protocol.allow=${protocolValue})`);
+    } else {
+        fail("git mode", `expected protocol.allow=${protocolValue}, found ${gitProtocol ?? "<unset>"}`);
+    }
+}
+
+function verifyWrapper(gitMode, ok, fail, skip) {
+    if (gitMode === GIT_MODE.strict) {
+        if (isWrapperSymlinkInPlace()) {
+            ok("git read-only wrapper", `${GIT_WRAPPER_PATH} -> ${GIT_WRAPPER_SOURCE}`);
+        } else {
+            fail("git read-only wrapper", `not installed at ${GIT_WRAPPER_PATH}`);
+        }
+        return;
+    }
+    if (lstatExists(GIT_WRAPPER_PATH)) {
+        fail("git read-only wrapper", `should be absent in ${gitMode} mode`);
+    } else {
+        skip("git read-only wrapper", `not active in ${gitMode} mode`);
+    }
+}
+
+function verifyStrictWrapperRejects(ok, fail) {
+    // Probe the wrapper with a representative mutating command. The classifier
+    // rejects before forking real git, so we should see our marker on stderr.
+    let probeStderr = "";
+    let probeExit = 0;
+    try {
+        execSync(`${GIT_WRAPPER_PATH} commit -m probe`, { stdio: ["pipe", "pipe", "pipe"] });
+    } catch (err) {
+        probeStderr = (err.stderr ?? "").toString();
+        probeExit = err.status ?? 1;
+    }
+    if (probeExit !== 0 && probeStderr.includes("blocked in strict mode")) {
+        ok("strict wrapper rejects mutation", "'git commit' blocked");
+    } else {
+        fail("strict wrapper rejects mutation", "wrapper did not produce the expected error");
+    }
+}
+
+function verifyRemoteBlocked(gitMode, ok, fail, skip) {
+    if (gitMode === GIT_MODE.unrestricted) {
+        skip("remote push", "allowed in unrestricted mode (network probe skipped)");
+        return;
+    }
+    try {
+        execSync("/usr/bin/git -C /workspace push", { stdio: "pipe" });
+        fail("remote push blocked", "git push succeeded -- remote access is NOT blocked");
+    } catch {
+        ok("remote push blocked", "remote push not possible");
+    }
+}
+
+/**
+ * Apply (when root) and verify the git mode requested via CHAMBA_GIT_MODE.
+ * Reports through the caller-provided ok/fail/skip helpers so all output flows
+ * through the main startup script's section formatting and error counter.
+ */
+export function checkGitMode({ ok, fail, skip, run, isRoot }) {
+    const gitMode = VALID_GIT_MODES.includes(process.env.CHAMBA_GIT_MODE) ? process.env.CHAMBA_GIT_MODE : GIT_MODE.local;
+    const protocolValue = gitMode === GIT_MODE.unrestricted ? "always" : "never";
+
+    if (isRoot) {
+        applyAsRoot(gitMode, protocolValue, fail);
+    }
+
+    verifyProtocol(gitMode, protocolValue, run, ok, fail);
+    verifyWrapper(gitMode, ok, fail, skip);
+    if (gitMode === GIT_MODE.strict) verifyStrictWrapperRejects(ok, fail);
+    verifyRemoteBlocked(gitMode, ok, fail, skip);
+}

package/templates/startup.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+// =============================================================================
+// startup.mjs -- Container startup: AI CLI updates + readiness checks
+// Baked into the container image at /home/devuser/startup.mjs
+// Must run as root (npm global install requires root).
+// Must use only Node.js built-ins -- no external packages available in container.
+// =============================================================================
+
+import { execSync, spawn } from "node:child_process";
+import { readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { checkGitMode } from "./startup-git-mode.mjs";
+
+const run = (cmd) => {
+    try {
+        return execSync(cmd, {
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+    } catch {
+        return null;
+    }
+};
+
+// -- ANSI helpers -------------------------------------------------------------
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const blue = (s) => `\x1b[34m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const grey = (s) => `\x1b[90m${s}\x1b[0m`;
+
+let errors = 0;
+
+// Summary mode (passed by the host at session start): still run every check and side-effect, but stay
+// quiet -- suppress the section dump and surface only failures. The 'status' alias runs without it,
+// so it keeps the full verbose output as the on-demand "details" view.
+const summary = process.argv.includes("--summary");
+
+const ok = summary ? () => {} : (label, detail) => console.log(`${green("✓")} ${label.padEnd(24)}${detail ? dim(detail) : ""}`);
+const skip = summary ? () => {} : (label, detail) => console.log(`${grey("–")} ${grey(label.padEnd(24))}${detail ? grey(detail) : ""}`);
+const fail = (label, detail) => {
+    console.log(`${red("✗")} ${label.padEnd(24)}${detail || ""}`);
+    errors++;
+};
+// Non-fatal notice: always prints (even in summary), but does NOT increment errors, so it never aborts
+// the session. Used for things the user should know about but that must not block connecting (e.g. a
+// transient AI CLI update failure -- the existing versions still work).
+const warn = (label, detail) => console.log(`${yellow("!")} ${label.padEnd(24)}${detail ? yellow(detail) : ""}`);
+const section = summary ? () => {} : (title) => console.log(`\n${bold(title)}`);
+
+// -- Header -------------------------------------------------------------------
+if (!summary) console.log(`\n${bold("chamba - Sandbox for AI Agents")}\n`);
+
+// -- AI CLI update (requires root - skipped when run via 'status' alias as devuser) -
+section("AI CLI update");
+
+const isRoot = process.getuid?.() === 0;
+const TIMESTAMP_FILE = "/home/devuser/.ai-cli-updated";
+const THROTTLE_MS = 24 * 60 * 60 * 1000;
+
+let lastUpdate = 0;
+let timestampFileExists = false;
+try {
+    const raw = readFileSync(TIMESTAMP_FILE, "utf8").trim();
+    lastUpdate = new Date(raw).getTime();
+    timestampFileExists = true;
+} catch {
+    // File missing or unreadable -- treat as never updated
+}
+
+// -- Context snapshot cleanup (best-effort, silent) ---------------------------
+// claude-statusline.sh writes one small per-session snapshot to this directory on every
+// prompt render (see the context-usage helper). Delete week-old entries here -- covers both
+// stale *.json snapshots and orphaned .tmp.* files. Any failure is swallowed so cleanup
+// can never affect readiness checks.
+const SNAPSHOT_DIR = "/home/devuser/.claude/context-usage";
+const SNAPSHOT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+try {
+    for (const name of readdirSync(SNAPSHOT_DIR)) {
+        const path = `${SNAPSHOT_DIR}/${name}`;
+        try {
+            if (Date.now() - statSync(path).mtimeMs > SNAPSHOT_MAX_AGE_MS) unlinkSync(path);
+        } catch {
+            // Skip entries that vanish or cannot be read/removed
+        }
+    }
+} catch {
+    // Directory missing (no snapshots yet) -- nothing to clean
+}
+
+// Print npm's output indented under the bullet above, so its flush-left "changed N packages" summary
+// reads as part of chamba's output rather than looking like it leaked from unrelated logging.
+const printIndented = (text) => {
+    for (const line of text.split("\n")) {
+        if (line.trim()) console.log(grey(`   ${line}`));
+    }
+};
+
+// Run the global npm install behind a one-line braille spinner so the user can see the (otherwise
+// silent, buffered) install is alive on a TTY. npm output is captured and printed indented only once it
+// finishes, keeping the live view to a single animated line. A failed update is NON-FATAL: it reports
+// via warn() (no errors++), so a transient registry/network hiccup never blocks the session -- the user
+// keeps the existing CLI versions. On a non-TTY (tests, piped) the spinner is skipped for clean output.
+const doUpdate = (label) =>
+    new Promise((resolve) => {
+        const animate = process.stdout.isTTY;
+        const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+        let frame = 0;
+        let timer;
+        if (animate) {
+            const draw = () => {
+                process.stdout.write(`\r${blue(frames[frame])} ${dim(label)}`);
+                frame = (frame + 1) % frames.length;
+            };
+            draw();
+            timer = setInterval(draw, 80);
+        } else {
+            console.log(`${blue("●")} ${dim(label)}`);
+        }
+
+        const child = spawn("npm", ["install", "-g", "opencode-ai@latest", "@anthropic-ai/claude-code@latest", "@openai/codex@latest"], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let out = "";
+        let errOut = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (d) => {
+            out += d;
+        });
+        child.stderr.on("data", (d) => {
+            errOut += d;
+        });
+
+        // Settle exactly once (spawn can emit both 'error' and 'close'). Clear the spinner line and leave
+        // a static bullet in its place so scrollback reads cleanly, then print the captured output.
+        let done = false;
+        const finish = (report) => {
+            if (done) return;
+            done = true;
+            if (timer) clearInterval(timer);
+            if (animate) process.stdout.write(`\r\x1b[K${blue("●")} ${dim(label)}\n`);
+            report();
+            resolve();
+        };
+
+        child.on("error", (err) => {
+            finish(() => {
+                printIndented(String(err?.message ?? err));
+                warn("AI CLIs", "update failed -- continuing with existing versions");
+            });
+        });
+        child.on("close", (code) => {
+            finish(() => {
+                if (code === 0) {
+                    printIndented(out);
+                    writeFileSync(TIMESTAMP_FILE, `${new Date().toISOString()}\n`);
+                    ok("AI CLIs", "updated");
+                } else {
+                    printIndented(`${out}${errOut}`);
+                    warn("AI CLIs", "update failed -- continuing with existing versions");
+                }
+            });
+        });
+    });
+
+// SPACE within `seconds` -> skip. Any other input is ignored. Ctrl+C exits 130. Non-TTY -> no skip.
+const promptSkipUpdate = (seconds) =>
+    new Promise((resolve) => {
+        if (!process.stdin.isTTY) {
+            resolve(false);
+            return;
+        }
+        let remaining = seconds;
+        let tick;
+        let timer;
+        const line = (s) => `\r\x1b[K${blue("●")} ${dim(`Updating AI CLIs in ${s}s... press SPACE to skip`)}`;
+        const cleanup = () => {
+            clearInterval(tick);
+            clearTimeout(timer);
+            process.stdin.removeListener("data", onData);
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write("\r\x1b[K");
+        };
+        const onData = (chunk) => {
+            for (const byte of chunk) {
+                if (byte === 0x03) {
+                    cleanup();
+                    process.exit(130);
+                }
+                if (byte === 0x20) {
+                    cleanup();
+                    resolve(true);
+                    return;
+                }
+            }
+        };
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on("data", onData);
+        process.stdout.write(line(remaining));
+        tick = setInterval(() => {
+            remaining -= 1;
+            if (remaining > 0) process.stdout.write(line(remaining));
+        }, 1000);
+        timer = setTimeout(() => {
+            cleanup();
+            resolve(false);
+        }, seconds * 1000);
+    });
+
+if (Number.isFinite(lastUpdate) && Date.now() - lastUpdate < THROTTLE_MS) {
+    ok("AI CLIs", "up to date");
+} else if (!isRoot) {
+    skip("AI CLIs", "update skipped (requires root)");
+} else {
+    // About to show update activity (the skip prompt and/or install/update output). In summary mode that is the
+    // first thing after the host's "Starting dev container...", so add a blank line to separate it.
+    if (summary) console.log("");
+    if (!timestampFileExists) {
+        await doUpdate("Installing AI CLIs...");
+    } else if (await promptSkipUpdate(3)) {
+        skip("AI CLIs", "update skipped by user");
+    } else {
+        await doUpdate("Updating AI CLIs to latest...");
+    }
+}
+
+// -- Security -----------------------------------------------------------------
+section("Security");
+
+const idOutput = run("id devuser");
+if (idOutput?.includes("uid=1001")) {
+    ok("non-root user", "devuser (uid=1001)");
+} else {
+    fail("non-root user", "devuser not found or wrong uid -- container is misconfigured");
+}
+
+// -- Git mode (strict / local / unrestricted) - applied + verified by separate module --
+checkGitMode({ ok, fail, skip, run, isRoot });
+
+// -- AI tools -----------------------------------------------------------------
+section("AI tools");
+
+const checkTool = (cmd) => {
+    const out = run(`${cmd} --version`);
+    if (out !== null && out.trim() !== "") {
+        const version = out.split("\n")[0];
+        ok(cmd, version);
+        return;
+    }
+    const which = run(`which ${cmd}`);
+    if (which !== null) {
+        ok(cmd, "installed");
+    } else {
+        fail(cmd, "not found -- rebuild container");
+    }
+};
+
+checkTool("opencode");
+checkTool("claude");
+checkTool("codex");
+
+// -- Runtimes -----------------------------------------------------------------
+section("Runtimes");
+
+const checkRuntime = (label, version) => {
+    if (version !== null) ok(label, version);
+    else skip(label, "not installed");
+};
+
+// Always present (base image)
+ok("node", run("node --version") ?? "not found");
+ok("npm", `v${run("npm --version") ?? "not found"}`);
+const pnpmVer = run("pnpm --version");
+ok("pnpm", pnpmVer ? `v${pnpmVer}` : "not found");
+ok("python3", run("python3 --version") ?? "not found");
+ok("pipx", run("pipx --version") ?? "not found");
+
+// Optional (installed via profile hooks)
+const bunVer = run("bun --version");
+checkRuntime("bun", bunVer ? `v${bunVer}` : null);
+checkRuntime("go", run("go version"));
+checkRuntime("cargo", run("cargo --version"));
+checkRuntime("java", run("java --version")?.split("\n")[0] ?? null);
+
+// -- Dev tools ----------------------------------------------------------------
+section("Dev tools");
+
+ok("gh", run("gh --version")?.split("\n")[0] ?? "not found");
+ok("rg", run("rg --version")?.split("\n")[0] ?? "not found");
+ok("fd", run("fd --version") ?? "not found");
+ok("fzf", run("fzf --version") ?? "not found");
+ok("jq", run("jq --version") ?? "not found");
+ok("yq", run("yq --version") ?? "not found");
+
+// -- Database tools -----------------------------------------------------------
+section("Database tools");
+
+ok("sqlite3", run("sqlite3 --version")?.split(" ").slice(0, 2).join(" ") ?? "not found");
+ok("psql", run("psql --version") ?? "not found");
+ok("mysql", run("mysql --version") ?? "not found");
+ok("redis-cli", run("redis-cli --version") ?? "not found");
+
+// -- API keys -----------------------------------------------------------------
+section("API keys");
+
+// Direct console.log, so it must be gated explicitly to stay quiet in summary mode (kept for 'status').
+if (!summary) {
+    console.log(
+        `${blue("●")} ${dim("API keys are injected via the env list in chamba.yaml - add your '.env' path, or an inline KEY=VALUE.")}`,
+    );
+}
+
+// -- Summary ------------------------------------------------------------------
+if (errors === 0) {
+    // Summary mode stays silent on success -- the welcome block is printed by the shell on connect.
+    if (!summary) {
+        const workspaceSuffix = process.env.CHAMBA_WORKSPACE ? ` - workspace: ${bold(process.env.CHAMBA_WORKSPACE)}` : "";
+        console.log(`\n${blue("●")}  ${bold("chamba dev container ready")}${workspaceSuffix}`);
+        console.log(
+            `${grey("   To adjust settings, ask any agent about")} ${bold("chamba.yaml")} ${grey("- it lives in the workspace root.")}\n`,
+        );
+        console.log(`${green("●")} ${bold("Ready.")}`);
+        console.log(`${grey("Type 'status' to re-run the readiness check.")}\n`);
+    }
+} else {
+    console.log(`\n${red("●")} ${bold(`${errors} error(s) - see above. Rebuild the container to fix.`)}\n`);
+    if (summary) console.log(`${grey("Run 'status' for full readiness details.")}\n`);
+    process.exit(1);
+}

package/templates/webpane.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# webpane - publish an HTML file as a page in this session's web pane.
+# Baked into the image at /usr/local/share/chamba/webpane.sh, on PATH as `webpane`.
+#
+# Usable by anything running inside a web session: an agent, a script, a shell. The page appears in the pane
+# beside the terminal straight away, and stays - pages are files, filed under the conversation they belong to,
+# and a resumed conversation opens with its own pages again.
+#
+# The caller says who it is by its own pid and nothing more. The server walks up the process tree from there
+# until it reaches a session it started, which is what decides where the page lands: a session key passed as
+# an argument would be a value the server has to trust, and every process in this container could pass one.
+set -euo pipefail
+
+# The interface's own port and key file. Both take the same overrides the server does, so a server started
+# on another port (a hand-run, a test) is still reachable with the same helper.
+CONTAINER_PORT="${WEBTERM_PORT:-3899}"
+KEY_FILE="${WEBTERM_KEY_FILE:-/tmp/webterm.key}"
+
+usage() {
+    echo "Usage: webpane <file.html> [--title \"A title\"]"
+    echo ""
+    echo "Publishes a standalone HTML page to the web pane of the session this runs in."
+    echo "The page's own <title> is what the pane shows; --title names the file it is saved as."
+    echo ""
+    echo "A page may carry a form: give it data-feedback, and what the user submits is written"
+    echo "next to the page as JSON. Your terminal gets a line saying where."
+}
+
+FILE=""
+TITLE=""
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --title)
+            shift
+            TITLE="${1:-}"
+            ;;
+        --title=*)
+            TITLE="${1#--title=}"
+            ;;
+        -h | --help)
+            usage
+            exit 0
+            ;;
+        *)
+            if [ -z "$FILE" ]; then
+                FILE="$1"
+            else
+                echo "webpane: unexpected argument \"$1\"" >&2
+                usage >&2
+                exit 1
+            fi
+            ;;
+    esac
+    shift || true
+done
+
+if [ -z "$FILE" ]; then
+    usage
+    exit 0
+fi
+
+if [ ! -f "$FILE" ] || [ ! -r "$FILE" ]; then
+    echo "webpane: cannot read \"$FILE\" - name an HTML file that exists." >&2
+    exit 1
+fi
+
+# The name the page is saved under when the caller did not choose one: the file's own name, which is almost
+# always what the author meant anyway.
+if [ -z "$TITLE" ]; then
+    TITLE="$(basename "$FILE")"
+    TITLE="${TITLE%.*}"
+fi
+
+# The title travels as an HTTP header, so it is one line of ordinary text before it goes anywhere. The server
+# cleans it again for its own reasons; this is what keeps a stray newline from turning into a curl error the
+# caller cannot make sense of.
+TITLE="$(printf '%s' "$TITLE" | tr -d '[:cntrl:]')"
+
+if [ ! -r "$KEY_FILE" ]; then
+    echo "webpane: the web interface is not running in this container, so there is no pane to publish to." >&2
+    exit 1
+fi
+
+BODY_FILE="$(mktemp)"
+trap 'rm -f "$BODY_FILE"' EXIT
+
+# $$ is this script's own pid. The server climbs from it to whichever session started it.
+STATUS="$(
+    curl -sS -o "$BODY_FILE" -w '%{http_code}' \
+        --connect-timeout 3 --max-time 30 \
+        -X POST \
+        -H "Content-Type: text/html" \
+        -H "X-Webterm-Key: $(head -n 1 "$KEY_FILE")" \
+        -H "X-Webpane-Pid: $$" \
+        -H "X-Webpane-Title: ${TITLE}" \
+        --data-binary "@${FILE}" \
+        "http://127.0.0.1:${CONTAINER_PORT}/pane/publish" 2>/dev/null
+)" || {
+    echo "webpane: could not reach the web interface on this container's port ${CONTAINER_PORT}." >&2
+    exit 1
+}
+
+# The server answers with JSON; jq is in the image, and the raw body is the fallback if it ever is not.
+field() {
+    if command -v jq >/dev/null 2>&1; then
+        jq -r "${1} // empty" <"$BODY_FILE" 2>/dev/null
+    fi
+}
+
+if [ "$STATUS" = "200" ]; then
+    NAME="$(field .id)"
+    SHOWN="$(field .title)"
+    echo "Published \"${SHOWN:-$TITLE}\" to the web pane${NAME:+ as ${NAME}}."
+    exit 0
+fi
+
+REASON="$(field .error)"
+if [ -z "$REASON" ]; then
+    case "$STATUS" in
+        413) REASON="the page is too large" ;;
+        403) REASON="the key on disk is not the one the interface is using" ;;
+        *) REASON="the interface answered ${STATUS}" ;;
+    esac
+fi
+echo "webpane: nothing was published - ${REASON}." >&2
+exit 1