chamba 0.3.0 → 0.4.0

package/dist/lib/agent-context.js

@@ -0,0 +1,177 @@
+// Agent mount definitions and context injection for AI CLIs running inside chamba containers.
+//
+// This file is the single source of truth for which directories each AI CLI reads/writes
+// and how chamba intercepts them via bind mounts. If an AI CLI changes its config layout,
+// this file must be updated.
+//
+// Verify against official docs periodically:
+//   Claude Code: https://docs.anthropic.com/en/docs/claude-code
+//   OpenCode:    https://github.com/opencode-ai/opencode
+//   Codex:       https://github.com/openai/codex
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AGENTS_DIR, CLAUDE_STATUSLINE_PATH, CONTAINER_HOME, GIT_MODE, PACKAGE_ROOT } from "./constants.js";
+export const AGENT_MOUNTS = [
+    {
+        agent: "claude",
+        hostSubpath: "claude",
+        container: `${CONTAINER_HOME}/.claude`,
+        description: "Claude Code user-level config and session data",
+    },
+    {
+        agent: "opencode",
+        hostSubpath: "opencode/config",
+        container: `${CONTAINER_HOME}/.config/opencode`,
+        description: "OpenCode user-level config",
+    },
+    {
+        agent: "opencode",
+        hostSubpath: "opencode/data",
+        container: `${CONTAINER_HOME}/.local/share/opencode`,
+        description: "OpenCode user-level data and session history",
+    },
+    {
+        agent: "codex",
+        hostSubpath: "codex",
+        container: `${CONTAINER_HOME}/.codex`,
+        description: "Codex user-level config and session data",
+    },
+];
+export const AGENT_FILE_MOUNTS = [
+    {
+        // .claude.json lives outside ~/.claude/ so it is not covered by the directory mount.
+        // Persisting it as a file mount avoids losing Claude Code settings on container rebuild.
+        hostSubpath: "claude/.claude.json",
+        container: `${CONTAINER_HOME}/.claude.json`,
+        initialContent: "{}\n",
+    },
+];
+// --- Build agent mount args --------------------------------------------------------------------------------------------------------------
+/**
+ * Creates agents/ subdirectories in the workspace cache dir on the host (lazily) and
+ * returns volume mount args for all supported agent tools.
+ */
+export function buildAgentMountArgs(workspaceDir) {
+    const agentsDir = join(workspaceDir, AGENTS_DIR);
+    const mounts = AGENT_MOUNTS.map((m) => ({
+        host: join(agentsDir, m.hostSubpath),
+        container: m.container,
+    }));
+    for (const { host } of mounts)
+        mkdirSync(host, { recursive: true });
+    const fileMounts = AGENT_FILE_MOUNTS.map((m) => ({
+        host: join(agentsDir, m.hostSubpath),
+        container: m.container,
+        initialContent: m.initialContent,
+    }));
+    for (const { host, initialContent } of fileMounts) {
+        if (!existsSync(host))
+            writeFileSync(host, initialContent);
+    }
+    return [
+        ...mounts.flatMap(({ host, container }) => ["-v", `${host}:${container}`]),
+        ...fileMounts.flatMap(({ host, container }) => ["-v", `${host}:${container}`]),
+    ];
+}
+// --- Template helpers --------------------------------------------------------------------------------------------------------------------
+function loadTemplate(name) {
+    return readFileSync(join(PACKAGE_ROOT, "templates", "context", `${name}.md`), "utf8").trimEnd();
+}
+function renderTemplate(template, vars) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
+}
+function writeFileEnsuringDir(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content);
+}
+// --- Build agent context documents -------------------------------------------------------------------------------------------------------
+/**
+ * Assembles the agent context markdown injected into each supported agent's config dir at session start.
+ */
+export function buildAgentContextDocs(hasGit, shadowPatterns, gitMode = GIT_MODE.local) {
+    const gitSection = loadTemplate(hasGit ? `git-mode-${gitMode}` : "git-unavailable");
+    const shadowSection = shadowPatterns && shadowPatterns.length > 0
+        ? renderTemplate(loadTemplate("shadow-paths"), {
+            // Indented two spaces to nest under the section's leading bullet.
+            pattern_list: shadowPatterns.map((p) => `  - \`${p}\``).join("\n"),
+        })
+        : null;
+    const baselineTemplate = loadTemplate("baseline");
+    // The doc is one bullet list: baseline holds the unconditional bullets, followed by the
+    // conditional ones (shadow paths, git mode) and any agent-specific extras.
+    function build(toolPath, extraSections = []) {
+        const sections = [
+            renderTemplate(baselineTemplate, { tool_path: toolPath }),
+            ...(shadowSection ? [shadowSection] : []),
+            gitSection,
+            ...extraSections,
+        ];
+        return `${sections.join("\n")}\n`;
+    }
+    // The context-usage section is Claude-only: the snapshot it points at is written by the status line
+    // script Claude Code runs, so other agents' sessions never refresh it.
+    return {
+        claude: build("~/.claude/CLAUDE.md", [loadTemplate("context-usage")]),
+        opencode: build("~/.config/opencode/AGENTS.md"),
+        codex: build("~/.codex/AGENTS.md"),
+    };
+}
+// --- Claude settings.json bootstrap ------------------------------------------------------------------------------------------------------
+function readSettingsObject(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing file or malformed JSON: caller proceeds with an empty object.
+    }
+    return {};
+}
+// Sets ~/.claude/settings.json -> statusLine to the chamba default if no value is set.
+// Non-destructive: preserves other fields and never overwrites a user-set statusLine.
+export function ensureClaudeStatusLine(workspaceDir) {
+    const settingsPath = join(workspaceDir, AGENTS_DIR, "claude", "settings.json");
+    const settings = readSettingsObject(settingsPath);
+    if (settings.statusLine === undefined) {
+        settings.statusLine = { type: "command", command: CLAUDE_STATUSLINE_PATH };
+        writeFileEnsuringDir(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    }
+}
+// --- Claude skills injection -------------------------------------------------------------------------------------------------------------
+// Renders every templates/skills/<name>/SKILL.md into agents/claude/skills/<name>/SKILL.md. Drop a
+// new directory under templates/skills/ to ship a new skill - no other code changes needed.
+export function injectClaudeSkills(workspaceDir) {
+    const templatesSkillsDir = join(PACKAGE_ROOT, "templates", "skills");
+    if (!existsSync(templatesSkillsDir))
+        return;
+    const targetSkillsDir = join(workspaceDir, AGENTS_DIR, "claude", "skills");
+    const vars = { statusline_path: CLAUDE_STATUSLINE_PATH };
+    for (const entry of readdirSync(templatesSkillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const sourcePath = join(templatesSkillsDir, entry.name, "SKILL.md");
+        if (!existsSync(sourcePath))
+            continue;
+        const rendered = renderTemplate(readFileSync(sourcePath, "utf8"), vars);
+        writeFileEnsuringDir(join(targetSkillsDir, entry.name, "SKILL.md"), rendered);
+    }
+}
+// --- Inject agent context ----------------------------------------------------------------------------------------------------------------
+/**
+ * Writes agent context markdown files into the workspace's agents/ directory.
+ */
+export function injectAgentContext(workspaceDir, docs) {
+    const a = join(workspaceDir, AGENTS_DIR);
+    const files = [
+        { path: join(a, "claude", "CLAUDE.md"), content: docs.claude },
+        { path: join(a, "opencode", "config", "AGENTS.md"), content: docs.opencode },
+        { path: join(a, "codex", "AGENTS.md"), content: docs.codex },
+    ];
+    for (const { path: filePath, content } of files) {
+        writeFileEnsuringDir(filePath, content);
+    }
+    ensureClaudeStatusLine(workspaceDir);
+    injectClaudeSkills(workspaceDir);
+}

package/dist/lib/browser.js

@@ -0,0 +1,40 @@
+// =========================================================================================================================================
+// src/lib/browser.ts - Open a URL in the host's default browser
+// One tiny best-effort step of the session start: chamba resolves the web port, brings the interface up,
+// and hands the URL to whatever the platform uses to open links. Never blocks and never fails a session.
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+// A hung opener would sit in front of the user's shell, so give it a short deadline and move on. Every
+// opener below hands the URL to a running desktop and returns at once, so this only bites when something
+// is wrong - and then printing the URL is the better outcome anyway.
+const OPEN_TIMEOUT_MS = 3000;
+/**
+ * The argv that opens a URL in the default browser on this platform, or null when we know of no opener for
+ * it. Argv, never a shell string: the URL carries a key read back from a file every process in the
+ * container can write, so it must reach the opener as one argument and never as something a shell parses.
+ * On Windows the opener is `start`, which is a cmd builtin rather than a program, hence the `cmd /c` -
+ * its first quoted argument is the window title, which is why an empty one goes before the URL.
+ */
+export function browserOpenArgv(url, platform = process.platform) {
+    if (platform === "darwin")
+        return ["open", url];
+    if (platform === "win32")
+        return ["cmd", "/c", "start", "", url];
+    if (platform === "linux")
+        return ["xdg-open", url];
+    return null;
+}
+/**
+ * Open a URL in the host's default browser. Returns false when there is no opener for this platform, the
+ * opener is not installed (a headless host, an SSH session), or it failed - the caller then prints the URL
+ * and carries on. Nothing here is allowed to throw: opening the browser for the user is the convenience, and
+ * the printed URL reaches the same interface, so a session must start either way.
+ */
+export function openInBrowser(url, platform = process.platform) {
+    const argv = browserOpenArgv(url, platform);
+    if (argv === null)
+        return false;
+    const [command = "", ...args] = argv;
+    const result = spawnSync(command, args, { stdio: "ignore", timeout: OPEN_TIMEOUT_MS });
+    return result.error === undefined && result.status === 0;
+}

package/dist/lib/chamba-yaml.js

@@ -0,0 +1,191 @@
+// =========================================================================================================================================
+// src/lib/chamba-yaml.ts - Read, write, and validate chamba.yaml
+// =========================================================================================================================================
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import AjvModule from "ajv";
+import { dump as dumpYaml, load as loadYaml } from "js-yaml";
+import { CHAMBA_SCHEMA_DIR, CHAMBA_SCHEMA_FILE, CHAMBA_YAML, DEFAULT_SHADOW_PATHS, PACKAGE_ROOT, WORKSPACE_ID_MAX, WORKSPACE_ID_MIN, } from "./constants.js";
+// --- Validation --------------------------------------------------------------------------------------------------------------------------
+// Must match the pattern, minLength, and maxLength in schema/chamba.schema.json
+const WORKSPACE_ID_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
+/** Returns error message if invalid, undefined if valid. Used for interactive input validation. */
+export function validateWorkspaceId(id) {
+    if (id.length < WORKSPACE_ID_MIN)
+        return `Workspace ID must be at least ${WORKSPACE_ID_MIN} characters`;
+    if (id.length > WORKSPACE_ID_MAX)
+        return `Workspace ID must be at most ${WORKSPACE_ID_MAX} characters`;
+    if (!WORKSPACE_ID_PATTERN.test(id))
+        return "Workspace ID must be lowercase alphanumeric with hyphens, not starting or ending with a hyphen";
+    return undefined;
+}
+/** Slugify a directory name into a valid workspace_id candidate. */
+export function slugifyForWorkspaceId(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, WORKSPACE_ID_MAX) || "my-workspace");
+}
+// --- Schema validation -------------------------------------------------------------------------------------------------------------------
+const schemaPath = join(PACKAGE_ROOT, CHAMBA_SCHEMA_DIR, CHAMBA_SCHEMA_FILE);
+// ajv is a CJS module - under nodenext resolution the class is nested under .default
+const Ajv = AjvModule.default ?? AjvModule;
+let _validate = null;
+/** Lazily compile and cache the JSON Schema validator. */
+function getValidator() {
+    if (!_validate) {
+        const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+        // allowUnionTypes: the `ports` port field is intentionally an integer|string union (bare identity port or
+        // "HOST:CONTAINER" string); the schema keeps only coarse structure while ports.ts owns range/format semantics.
+        const ajv = new Ajv({ allErrors: true, allowUnionTypes: true });
+        _validate = ajv.compile(schema);
+    }
+    return _validate;
+}
+// --- Validation helpers ------------------------------------------------------------------------------------------------------------------
+/** Format ajv validation errors into a human-readable string. */
+// biome-ignore lint/suspicious/noExplicitAny: ajv error objects lack a stable exported type
+function formatValidationErrors(errors) {
+    return (errors ?? [])
+        .map((e) => {
+        if (e.keyword === "additionalProperties" && e.params?.additionalProperty) {
+            return `unknown property "${e.params.additionalProperty}"`;
+        }
+        const path = e.instancePath ? `"${e.instancePath.slice(1).replace(/\//g, ".")}"` : "";
+        return path ? `${path} ${e.message}` : (e.message ?? "validation error");
+    })
+        .join("; ");
+}
+// --- Read --------------------------------------------------------------------------------------------------------------------------------
+/** Read and validate chamba.yaml from a directory. Returns null if file missing. Throws if invalid. */
+export function readChambaYaml(dir) {
+    const filePath = join(dir, CHAMBA_YAML);
+    if (!existsSync(filePath))
+        return null;
+    const raw = loadYaml(readFileSync(filePath, "utf8"));
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error(`${CHAMBA_YAML} is empty or not a valid YAML object`);
+    }
+    // Validate against JSON Schema
+    const validate = getValidator();
+    if (!validate(raw)) {
+        throw new Error(`Invalid ${CHAMBA_YAML}: ${formatValidationErrors(validate.errors)}`);
+    }
+    return raw;
+}
+// --- Write -------------------------------------------------------------------------------------------------------------------------------
+// Editor schema header. It points into the published npm package through a public CDN rather than at a
+// repository URL: this repo is private and carries no release tags, so nothing a git host serves would
+// resolve. The URL is pinned by the package's own version, so an installed chamba always names the schema
+// it actually ships, and the pin needs no upkeep - the version string is already there.
+const { version } = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+export const SCHEMA_URL = `https://unpkg.com/chamba@${version}/schema/${CHAMBA_SCHEMA_FILE}`;
+const SCHEMA_HEADER = `# yaml-language-server: $schema=${SCHEMA_URL}`;
+// Inline comments injected before specific YAML keys (preceded by a blank line)
+const YAML_COMMENTS = {
+    workspace_id: "# chamba workspace config - run 'npx chamba' from anywhere under this directory tree to start your dev container.\n" +
+        "# Every field is documented in the schema above, which your editor reads for completion and validation.\n" +
+        "# This file may be rewritten by chamba (repair, reset, settings changes). Custom comments will not be preserved.",
+    env: "# Environment injected into the container - a single value or a list.\n" +
+        "# Each entry is an env-file path relative to this directory (e.g. '.env') or an inline 'KEY=VALUE' variable.",
+    shadow_paths: "# .gitignore-style patterns - agents see an empty, isolated copy instead of the real host data.",
+    profiles: "# Dockerfile profiles - each adds on top of the chamba base image (Debian + Node.js + git + AI CLIs).\n" +
+        "# Useful for teams: each person can have a lean profile for their stack instead of one large shared image.\n" +
+        "# When multiple profiles exist, chamba prompts you to pick one on session start.",
+};
+/** Write chamba.yaml to a directory with schema header and inline comments. */
+export function writeChambaYaml(dir, config) {
+    const filePath = join(dir, CHAMBA_YAML);
+    const yamlContent = dumpYaml(config, {
+        lineWidth: -1,
+        quotingType: '"',
+        forceQuotes: false,
+    });
+    // Inject blank lines and comments before known keys
+    const lines = yamlContent.split("\n");
+    const output = [];
+    for (const line of lines) {
+        const key = line.match(/^(\w[\w_]*):/)?.[1];
+        const comment = key && YAML_COMMENTS[key];
+        if (comment) {
+            output.push(""); // blank line before section
+            output.push(comment);
+        }
+        output.push(line);
+    }
+    // The body opens with a blank line (the injected comment block above workspace_id), so the schema
+    // header sits on its own line at the very top with that blank line under it.
+    const body = output.join("\n").trimEnd();
+    // The "add more profiles" footer only makes sense when a profiles: block was actually written above it.
+    const footer = config.profiles && Object.keys(config.profiles).length > 0 ? `\n${PROFILES_FOOTER_COMMENT}` : "";
+    writeFileSync(filePath, `${SCHEMA_HEADER}${body}${footer}\n`);
+}
+// --- Defaults ----------------------------------------------------------------------------------------------------------------------------
+// Appended after the last profile to hint at adding more (only when a profiles: block is present).
+const PROFILES_FOOTER_COMMENT = "  # Add more profiles here - or ask the agent inside the container to set one up for you.";
+/**
+ * Create the minimal default ChambaYamlConfig: just the required workspace_id plus the security-relevant
+ * shadow_paths isolation default. Everything else (env, profiles, ports) is optional and documented
+ * in the schema the file's header points at, so we do not scaffold it into freshly generated files.
+ */
+export function buildDefaultChambaYaml(workspaceId) {
+    return {
+        workspace_id: workspaceId,
+        shadow_paths: [...DEFAULT_SHADOW_PATHS],
+    };
+}
+// --- Repair -------------------------------------------------------------------------------------------------------------------------------
+/** Set of keys that ChambaYamlConfig allows (used to strip unknown fields). */
+const KNOWN_KEYS = new Set(["workspace_id", "env", "shadow_paths", "profiles", "ports"]);
+/**
+ * Attempt to repair an invalid chamba.yaml on disk.
+ * Strips unknown fields, fills missing required/optional fields from defaults,
+ * and rewrites with canonical formatting. Returns a result describing what happened.
+ */
+export function repairChambaYaml(dir) {
+    const filePath = join(dir, CHAMBA_YAML);
+    if (!existsSync(filePath))
+        return { repairedYaml: null };
+    try {
+        const raw = loadYaml(readFileSync(filePath, "utf8"));
+        if (typeof raw !== "object" || raw === null)
+            return { repairedYaml: null };
+        const obj = raw;
+        const fixes = [];
+        // Strip unknown fields
+        for (const key of Object.keys(obj)) {
+            if (!KNOWN_KEYS.has(key)) {
+                delete obj[key];
+                fixes.push(`removed unknown field "${key}"`);
+            }
+        }
+        // Build defaults to fill from
+        const fallbackId = slugifyForWorkspaceId(basename(dir));
+        const defaults = buildDefaultChambaYaml(obj.workspace_id || fallbackId);
+        // Fill missing required fields
+        if (!("workspace_id" in obj)) {
+            obj.workspace_id = defaults.workspace_id;
+            fixes.push(`added missing workspace_id ("${defaults.workspace_id}")`);
+        }
+        // Restore the shadow_paths isolation default when absent (security-relevant). profiles/env are
+        // optional and intentionally not backfilled, so a deliberately minimal file is not re-bloated on repair.
+        if (!("shadow_paths" in obj)) {
+            obj.shadow_paths = defaults.shadow_paths;
+            fixes.push("added default shadow_paths");
+        }
+        if (fixes.length === 0)
+            return { repairedYaml: null };
+        // Validate the repaired object
+        const validate = getValidator();
+        if (!validate(obj)) {
+            return { repairedYaml: null, error: `${CHAMBA_YAML} could not be repaired: ${formatValidationErrors(validate.errors)}` };
+        }
+        const yaml = obj;
+        writeChambaYaml(dir, yaml);
+        return { repairedYaml: yaml, message: `Repaired ${CHAMBA_YAML}: ${fixes.join(", ")}` };
+    }
+    catch (err) {
+        return { repairedYaml: null, error: `${CHAMBA_YAML} repair failed: ${err instanceof Error ? err.message : err}` };
+    }
+}

package/dist/lib/constants.js

@@ -0,0 +1,135 @@
+// =========================================================================================================================================
+// src/lib/constants.ts - Canonical constants used across the chamba codebase
+// =========================================================================================================================================
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// Resolve the package root (repo root in dev, npm package root when installed).
+// All compiled lib modules sit at dist/lib/*.js, so dirname x3 from this file lands at the package root.
+export const PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+// ~/.chamba/ structure
+export const CHAMBA_DIR = ".chamba";
+export const WORKSPACES_DIR = "workspaces";
+export const GLOBAL_DIR = "global"; // host-global state not tied to a workspace (the config file)
+// Workspace cache subdirectories (under ~/.chamba/workspaces/<id>/)
+export const AGENTS_DIR = "agents";
+export const SHADOWS_DIR = "shadows";
+export const PNPM_STORE_DIR = "pnpm-store";
+export const WEBTERM_STATE_DIR = "webterm"; // the web interface's own state, bind-mounted into the container
+// Filenames
+export const CHAMBA_YAML = "chamba.yaml";
+export const CHAMBA_SCHEMA_DIR = "schema";
+export const CHAMBA_SCHEMA_FILE = "chamba.schema.json";
+export const LOCK_FILE = ".lock";
+export const GLOBAL_CONFIG_FILE = "config"; // ~/.chamba/global/config - key=value host-global settings
+// The workspace shape this chamba writes, stamped into every .lock as `version=`. It is the shape's
+// number, not the package version: it changes only when the on-disk layout does. Chamba's own numbering
+// starts at 1 - every chamba workspace is created by this shape or a later one, so there is no older
+// layout to recognize and nothing reads the marker yet. It exists so a future shape change can.
+export const LOCK_VERSION = "1";
+// Workspace ID constraints (must match schema/chamba.schema.json)
+export const WORKSPACE_ID_MIN = 2;
+export const WORKSPACE_ID_MAX = 48;
+// Default shadow paths applied to new workspaces
+export const DEFAULT_SHADOW_PATHS = ["node_modules", ".env*"];
+// Container filesystem
+export const CONTAINER_USER = "devuser";
+export const CONTAINER_HOME = `/home/${CONTAINER_USER}`;
+export const CONTAINER_WORKSPACE = "/workspace";
+export const CONTAINER_STARTUP = `${CONTAINER_HOME}/startup.mjs`;
+// pnpm's default global store path inside the container. Single source of truth for both the -v mount (pnpm-store.ts)
+// and the store-dir env var (RUNTIME_ENV below) so the mount target and the env var can never drift apart.
+export const CONTAINER_PNPM_STORE = `${CONTAINER_HOME}/.local/share/pnpm/store`;
+// What the container runs as PID 1 so it stays up between sessions. It has to be a shell that traps TERM,
+// not a bare `sleep infinity`: the kernel drops signals sent to PID 1 from inside its own PID namespace
+// unless PID 1 installed a handler, and without a handler nothing in the container - including the web
+// interface's "stop the container" button - can ever end it. `docker stop` from the host works either way,
+// and gets cleaner with the trap: an immediate exit 0 instead of the 10s timeout and a SIGKILL.
+export const CONTAINER_KEEP_ALIVE = ["bash", "-c", 'trap "exit 0" TERM INT; while :; do sleep 86400 & wait $!; done'];
+// The status line script chamba installs - baked into the image, referenced from ~/.claude/settings.json.
+// It renders nothing: it writes the per-session snapshot the web interface's status strip and the
+// context-usage helper both read.
+export const CLAUDE_STATUSLINE_PATH = "/usr/local/share/chamba/claude-statusline.sh";
+// Docker container/image naming
+export const CONTAINER_NAME_PREFIX = "chamba-";
+// Docker label keys
+export const LABEL_MANAGED = "chamba.managed";
+export const LABEL_SHADOWS = "chamba.shadows";
+export const LABEL_PROFILE = "chamba.profile";
+export const LABEL_RUNTIME_ENV = "chamba.runtime-env";
+export const LABEL_GIT_MODE = "chamba.git-mode";
+export const LABEL_BUILD_HASH = "chamba.build-hash";
+export const LABEL_PORTS = "chamba.ports";
+export const LABEL_ENV = "chamba.env";
+// Fallback active-profile name - used for the container label and .lock file when a workspace defines no profiles of its own.
+export const DEFAULT_PROFILE = "default";
+// Git guardrails modes (per-workspace, stored in .lock).
+// Single source of truth lives in templates/runtime-constants.mjs so container-side
+// scripts (startup.mjs, startup-git-mode.mjs) and TS code can both reference the
+// same values without drift. We re-export here so internal code keeps importing
+// from "./constants.js" as before.
+import { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE } from "../../templates/runtime-constants.mjs";
+export { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE };
+export const GIT_MODES = Object.values(GIT_MODE);
+// Runtime env vars injected into every container via docker run -e.
+// Suppress Claude Code features that are inapplicable or disruptive inside the container, tune session behavior,
+// and pin container-isolation safeguards (e.g. pnpm's store path).
+export const RUNTIME_ENV = {
+    CLAUDE_AFK_TIMEOUT_MS: "2147483647", // Max 32-bit timer value (~24.8 days); avoids AFK timeouts in long unattended container sessions
+    CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY: "1", // Periodic feedback survey prompt is noise in ephemeral container sessions
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1", // Suppress non-essential network calls (autoupdate checks, telemetry pings)
+    CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1", // Skip automatic addition of the official plugin marketplace on first run
+    CLAUDE_CODE_NO_FLICKER: "1", // Steadier redraws, which is the better terminal here and the one the web interface relays
+    DISABLE_AUTOUPDATER: "1", // In-process updater fails (root-owned prefix); startup.mjs handles updates
+    DISABLE_ERROR_REPORTING: "1", // Container errors include sandbox paths not useful to Anthropic
+    DISABLE_INSTALLATION_CHECKS: "1", // npm install is by design; native installer is not applicable
+    DISABLE_TELEMETRY: "1", // Container sessions should not phone home
+    DISABLE_UPGRADE_COMMAND: "1", // /upgrade is wrong path inside container; chamba manages CLI version
+    DO_NOT_TRACK: "1", // Universal opt-out honored by many CLIs/tools running in the container
+    // Force pnpm's store to the mounted host path so a per-project .pnpm-store never leaks to the host repo (see pnpm-store.ts).
+    // This removes pnpm's store-dir auto-detection, which could otherwise pick a different path before the mount takes effect.
+    // Both the pnpm-native and legacy npm-style keys are set so older pnpm versions honor it too.
+    npm_config_store_dir: CONTAINER_PNPM_STORE,
+    pnpm_config_store_dir: CONTAINER_PNPM_STORE,
+};
+// The agents chamba runs. Each value is the command itself, so the list doubles as what the webterm server
+// may spawn, what the `webterm` launcher accepts, and what the browser may ask for per session. The default
+// is what a session starts with until the user names another one.
+export const WEB_AGENTS = ["claude", "opencode", "codex"];
+export const DEFAULT_WEB_AGENT = "claude";
+// Web agent interface (webterm). The server always binds this fixed container port; chamba publishes it
+// loopback-only to a sticky per-workspace host port taken from web_range (host-global setting).
+export const WEB_CONTAINER_PORT = 3899;
+export const WEB_RANGE_DEFAULT = "3900-3999";
+// Where the webterm server publishes the key its URL carries (`/?k=<key>`). A new key is minted every time
+// that server starts and written here as soon as it has the port, so whoever prints the URL reads it back
+// from this file rather than storing one: the container greeting, the `webterm` launcher, and chamba on the
+// host before it probes /status. Container-side path - the host only ever reads it through `docker exec`.
+export const WEB_KEY_FILE_PATH = "/tmp/webterm.key";
+// Where the container sees this workspace's webterm state dir, bind-mounted from the cache dir above. The
+// one thing in it is the agent file: which agent new web sessions start with, written by the server when
+// `webterm <agent>` moves it and read back by the host at the next container start. It lives on the host
+// side of a mount precisely so the choice outlives a container recreate.
+export const CONTAINER_WEBTERM_STATE_DIR = `${CONTAINER_HOME}/.chamba-webterm`;
+export const WEBTERM_AGENT_FILE = "agent";
+export const WEBTERM_AGENT_FILE_PATH = `${CONTAINER_WEBTERM_STATE_DIR}/${WEBTERM_AGENT_FILE}`;
+// The web pane's artifacts: one directory per conversation, holding the pages published to that
+// conversation's pane and the feedback submitted on them. On the host it sits under the cache dir's
+// agents/ dir, which is exactly what Advanced > Clear agent memory removes, so that menu item is the one
+// thing that clears the pane. It is bind-mounted into the container, so the pages outlive the container
+// and a resumed conversation finds its own history again. Nothing sweeps it by age.
+export const WEBPANE_DIR = "webpane";
+export const CONTAINER_WEBPANE_DIR = `${CONTAINER_HOME}/.webpane`;
+// Resume marker: a host-written container file whose content is the full command that resumes the most
+// recent conversation. Planted by dev.ts on every container create/start; consumed (rename-then-read,
+// atomic) by exactly one webterm session, so the first session after a container start resumes and every
+// later one starts fresh. Lives in the devuser home, not /tmp - the consumer executes the file's content,
+// so it must not sit in a world-writable dir.
+export const RESUME_MARKER_PATH = `${CONTAINER_HOME}/.chamba-resume-pending`;
+// Per-agent command that reopens the most recent conversation. Pinned against the real CLIs by the
+// drift test in tests/webterm.test.ts, which checks each flag/subcommand against the CLI's own help.
+// Claude is not here: it is resumed by session id instead (resumeCommandFor), because `claude --continue`
+// exits with "No conversation found to continue" when there is nothing to continue.
+export const AGENT_RESUME_COMMAND = {
+    opencode: "opencode --continue",
+    codex: "codex resume --last",
+};