chamba 0.3.1 → 0.4.0

package/dist/commands/menu.js

@@ -0,0 +1,80 @@
+// =========================================================================================================================================
+// src/commands/menu.ts - chamba workspace menu
+// Shows workspace status box with profile, non-git notice, and shadow info.
+// =========================================================================================================================================
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { styleText } from "node:util";
+import { cancel, isCancel, log, select } from "@clack/prompts";
+import { readChambaYaml } from "../lib/chamba-yaml.js";
+import { DEFAULT_PROFILE } from "../lib/constants.js";
+import { readActiveProfile } from "../lib/workspace-identity.js";
+export async function run(args) {
+    const { ctx, activeCount, workspaceRunning, version } = args;
+    // --- Read workspace config -----------------------------------------------------------------------------------------------------------
+    const hasGit = existsSync(join(ctx.workspaceRoot, ".git"));
+    // Profiles come from chamba.yaml (the source of truth). The lock file's active profile can be stale (e.g. a
+    // profile since removed from chamba.yaml), so only trust it when it still exists. Mirror selectProfile() in
+    // dev.ts: a single profile is no real choice, so omit the line entirely rather than show noise.
+    let profileNames = [];
+    try {
+        profileNames = Object.keys(readChambaYaml(ctx.workspaceRoot)?.profiles ?? {});
+    }
+    catch {
+        // chamba.yaml is validated upstream; on any unexpected read error just omit the profile line.
+    }
+    const cachedProfile = readActiveProfile(ctx.workspaceId);
+    // Fall back to a profile that actually exists (default if present, else the first) so the box never
+    // shows a name absent from chamba.yaml. The line only renders when there are >1, so the list is non-empty there.
+    const fallbackProfile = profileNames.includes(DEFAULT_PROFILE) ? DEFAULT_PROFILE : (profileNames[0] ?? DEFAULT_PROFILE);
+    const activeProfile = cachedProfile && profileNames.includes(cachedProfile) ? cachedProfile : fallbackProfile;
+    // --- Status line ---------------------------------------------------------------------------------------------------------------------
+    // A single bold header line: version, then the workspace - with its container state shown only while
+    // running - then an optional profile. Anything else (other containers, git) drops to one quieter
+    // notice line below.
+    const boldSep = styleText(["bold", "gray"], " · ");
+    // Append the running state (green) only when the container is up. A stopped container is the resting
+    // default, so "container down" carries no signal - drop it and just name the workspace.
+    const workspaceSegment = workspaceRunning
+        ? `${styleText("bold", `${ctx.workspaceId} container`)} ${styleText(["bold", "green"], "up")}`
+        : styleText("bold", ctx.workspaceId);
+    const segments = [styleText("bold", `chamba v${version}`), workspaceSegment];
+    if (profileNames.length > 1)
+        segments.push(styleText("bold", `profile: ${activeProfile}`));
+    const header = segments.join(boldSep);
+    // --- Notices -------------------------------------------------------------------------------------------------------------------------
+    // One quieter line under the header, its parts joined by a gray dot separator. Order: other containers,
+    // git. It only renders when at least one part applies, so the common case is just the header.
+    const parts = [];
+    // activeCount includes this workspace's container when it is up, so subtract it to count only the others.
+    // The number always reads as "besides this one", and a lone running workspace shows nothing.
+    const others = activeCount - (workspaceRunning ? 1 : 0);
+    if (others > 0)
+        parts.push(`${others} other container${others === 1 ? "" : "s"} up`);
+    // No git means agent changes are not tracked. dev.ts only feeds this into the agent's context docs, so this
+    // is the only warning a person sees - keep it here when the workspace is not a git repo.
+    if (!hasGit)
+        parts.push("no git");
+    // The whole line is gray so it stays quieter than the bold header above it.
+    const notices = parts.length > 0 ? [styleText("gray", parts.join(" · "))] : [];
+    // Print the header and any notices as clack log lines. log.message already opens with a bar-gutter line, so
+    // it separates itself from whatever precedes it - no extra blank line needed. The gray gutter lines up with
+    // the select menu that follows.
+    log.message([header, ...notices]);
+    const options = [
+        // Two doors into the same container, web first because that is where the work happens. The shell is
+        // the service hatch: it opens no browser, and the greeting inside still names the interface's URL.
+        { value: "web", label: "Web interface", hint: "open this workspace in your browser" },
+        { value: "shell", label: "Container shell", hint: "a shell inside the container, no browser" },
+        ...(workspaceRunning ? [{ value: "stop", label: "Stop container", hint: "stops this workspace's container" }] : []),
+        { value: "settings", label: "Settings", hint: "git mode, shadow paths, web, rebuild" },
+        { value: "advanced", label: "Advanced", hint: "stop, clear, remove, uninstall" },
+        { value: "quit", label: "Quit" },
+    ];
+    const action = await select({ message: "Menu:", options });
+    if (isCancel(action)) {
+        cancel();
+        return "quit";
+    }
+    return action;
+}

package/dist/commands/onboard.js

@@ -0,0 +1,229 @@
+// =========================================================================================================================================
+// src/commands/onboard.ts - First-time workspace setup
+// Creates chamba.yaml, registers the workspace, and returns WorkspaceContext (or null if cancelled).
+// =========================================================================================================================================
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { cancel, confirm, intro, isCancel, log, outro, select, text } from "@clack/prompts";
+import { buildDefaultChambaYaml, readChambaYaml, slugifyForWorkspaceId, validateWorkspaceId, writeChambaYaml, } from "../lib/chamba-yaml.js";
+import { CHAMBA_YAML } from "../lib/constants.js";
+import { readWebRange } from "../lib/global-config.js";
+import { safeRmSync } from "../lib/safe-rm.js";
+import { ensureWebPort } from "../lib/webterm.js";
+import { checkCollision, deriveContainerName, findChambaYamlDir, findOrphanWorkspaceDir, getWorkspaceDir, initWorkspaceDir, readLockFile, } from "../lib/workspace-identity.js";
+/** Derive a unique workspace_id, appending -2, -3, etc. if the base collides with another workspace. */
+function deriveUniqueWorkspaceId(baseId, workspaceRoot) {
+    if (checkCollision(baseId, workspaceRoot) === "ok")
+        return baseId;
+    for (let i = 2; i <= 99; i++) {
+        const candidate = `${baseId}-${i}`;
+        if (checkCollision(candidate, workspaceRoot) === "ok")
+            return candidate;
+    }
+    return baseId; // fallback (collision handled later in onboarding)
+}
+function tryGetGitRoot(cwd) {
+    try {
+        return execSync("git rev-parse --show-toplevel", { encoding: "utf8", cwd, stdio: "pipe" }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+// Public entry point. Wraps the interactive setup so an aborted run (the user cancels a prompt, or an
+// unexpected error) rolls back a chamba.yaml we created this session, leaving the directory as we found it.
+export async function run(cwd) {
+    // Records a chamba.yaml this run creates (never a pre-existing one) so the finally can remove it.
+    const created = { yamlPath: null };
+    let result = null;
+    try {
+        result = await runSetup(cwd, created);
+        return result;
+    }
+    finally {
+        // Non-completion means cancelled (result stays null) or threw (also null). Success assigns result,
+        // so a created config survives only when setup actually finished.
+        if (!result && created.yamlPath)
+            safeRmSync(created.yamlPath, { force: true });
+    }
+}
+async function runSetup(cwd, created) {
+    const toTildePath = (p) => (p.startsWith(homedir()) ? p.replace(homedir(), "~") : p);
+    // --- Detect context ------------------------------------------------------------------------------------------------------------------
+    const gitRoot = tryGetGitRoot(cwd);
+    const searchRoot = gitRoot ?? cwd;
+    const yamlDir = findChambaYamlDir(searchRoot);
+    // --- Intro ---------------------------------------------------------------------------------------------------------------------------
+    process.stdout.write("\n");
+    intro("chamba · new workspace");
+    process.stdout.write("\n");
+    let workspaceRoot;
+    let yaml;
+    if (yamlDir) {
+        // --- chamba.yaml found: read and validate ----------------------------------------------------------------------------------------
+        let existing;
+        try {
+            existing = readChambaYaml(yamlDir);
+        }
+        catch (err) {
+            log.error(`Found ${join(yamlDir, CHAMBA_YAML)} but it is invalid: ${err instanceof Error ? err.message : err}`);
+            cancel("Setup cancelled.");
+            return null;
+        }
+        if (!existing) {
+            log.error(`Could not read ${join(yamlDir, CHAMBA_YAML)}.`);
+            cancel("Setup cancelled.");
+            return null;
+        }
+        workspaceRoot = yamlDir;
+        yaml = existing;
+        const ok = await confirm({ message: `Set up chamba for: ${toTildePath(workspaceRoot)}?` });
+        if (isCancel(ok) || !ok) {
+            cancel("Setup cancelled.");
+            return null;
+        }
+    }
+    else {
+        // --- No chamba.yaml: create one interactively ------------------------------------------------------------------------------------
+        // Choose workspace root
+        const suggestedRoot = gitRoot ?? cwd;
+        const options = [
+            { value: suggestedRoot, label: toTildePath(suggestedRoot), hint: gitRoot ? "git root" : "current directory" },
+        ];
+        if (gitRoot !== null && gitRoot !== cwd) {
+            options.push({ value: cwd, label: toTildePath(cwd), hint: "current directory" });
+        }
+        options.push({ value: "__custom__", label: "Enter a different path…" });
+        const rootChoice = await select({ message: "Workspace root:", options });
+        if (isCancel(rootChoice)) {
+            cancel("Setup cancelled.");
+            return null;
+        }
+        if (rootChoice === "__custom__") {
+            const customPath = await text({
+                message: "Workspace root path:",
+                placeholder: `e.g. ${suggestedRoot}`,
+                validate: (v) => {
+                    const p = (v ?? "").trim();
+                    if (p.length === 0)
+                        return "Path cannot be empty";
+                    if (!existsSync(p))
+                        return `Directory not found: ${p}`;
+                    return undefined;
+                },
+            });
+            if (isCancel(customPath)) {
+                cancel("Setup cancelled.");
+                return null;
+            }
+            workspaceRoot = customPath.trim();
+        }
+        else {
+            workspaceRoot = rootChoice;
+        }
+        // Ask for workspace ID
+        const defaultId = slugifyForWorkspaceId(basename(workspaceRoot));
+        const idInput = await text({
+            message: "Workspace ID:",
+            placeholder: defaultId,
+            defaultValue: defaultId,
+            validate: (v) => validateWorkspaceId((v ?? "").trim() || defaultId),
+        });
+        if (isCancel(idInput)) {
+            cancel("Setup cancelled.");
+            return null;
+        }
+        const inputId = idInput.trim() || defaultId;
+        // Auto-resolve collisions with numeric suffix
+        const workspaceId = deriveUniqueWorkspaceId(inputId, workspaceRoot);
+        // Build and write chamba.yaml
+        yaml = buildDefaultChambaYaml(workspaceId);
+        writeChambaYaml(workspaceRoot, yaml);
+        created.yamlPath = join(workspaceRoot, CHAMBA_YAML);
+        log.success(`Created ${toTildePath(created.yamlPath)}`);
+    }
+    // --- Non-git warning -----------------------------------------------------------------------------------------------------------------
+    const isNonGit = tryGetGitRoot(workspaceRoot) === null;
+    if (isNonGit) {
+        log.warn("No version control detected. Agent changes won't be tracked.");
+        const ack = await confirm({ message: "Continue without git?" });
+        if (isCancel(ack) || !ack) {
+            cancel("Setup cancelled.");
+            return null;
+        }
+    }
+    // --- Collision / orphan check --------------------------------------------------------------------------------------------------------
+    const workspaceId = yaml.workspace_id;
+    const collision = checkCollision(workspaceId, workspaceRoot);
+    if (collision === "collision") {
+        const existingLock = readLockFile(workspaceId);
+        log.error(`Workspace ID "${workspaceId}" is already used by another workspace:\n` +
+            `  ${existingLock}\n\n` +
+            `Choose a different workspace_id in chamba.yaml.`);
+        const newId = await text({
+            message: "New workspace ID:",
+            validate: (v) => {
+                const id = (v ?? "").trim();
+                const err = validateWorkspaceId(id);
+                if (err)
+                    return err;
+                const c = checkCollision(id, workspaceRoot);
+                if (c === "collision")
+                    return `"${id}" is also taken`;
+                return undefined;
+            },
+        });
+        if (isCancel(newId)) {
+            cancel("Setup cancelled.");
+            return null;
+        }
+        yaml.workspace_id = newId.trim();
+        writeChambaYaml(workspaceRoot, yaml);
+        log.info(`Updated workspace_id to "${yaml.workspace_id}"`);
+    }
+    else {
+        // Check for orphan (workspace_id changed in yaml but old dir still points here)
+        const orphanId = findOrphanWorkspaceDir(workspaceRoot);
+        if (orphanId && orphanId !== workspaceId) {
+            log.warn(`Found orphaned workspace cache "${orphanId}" pointing to this workspace.`);
+            const action = await select({
+                message: "How to handle the orphaned cache?",
+                options: [
+                    { value: "realign", label: `Revert workspace_id to "${orphanId}"`, hint: "keeps existing cache" },
+                    { value: "clean", label: `Use "${workspaceId}" (clean slate)`, hint: "deletes old cache" },
+                ],
+            });
+            if (isCancel(action)) {
+                cancel("Setup cancelled.");
+                return null;
+            }
+            if (action === "realign") {
+                yaml.workspace_id = orphanId;
+                writeChambaYaml(workspaceRoot, yaml);
+                log.info(`Reverted workspace_id to "${orphanId}"`);
+            }
+            else {
+                // Clean slate - remove orphaned dir
+                safeRmSync(getWorkspaceDir(orphanId), { recursive: true, force: true });
+                log.info(`Removed orphaned cache for "${orphanId}"`);
+            }
+        }
+    }
+    // --- Initialize workspace dir --------------------------------------------------------------------------------------------------------
+    const finalId = yaml.workspace_id;
+    initWorkspaceDir(finalId, workspaceRoot);
+    // A new workspace takes its sticky web port at creation time (the spec's second calm moment).
+    const assignedWebPort = ensureWebPort(finalId, readWebRange());
+    if (assignedWebPort.ok)
+        log.info(`Web agent interface port: ${assignedWebPort.port} (sticky for this workspace)`);
+    log.success(`Config written to ${toTildePath(getWorkspaceDir(finalId))}`);
+    outro("Setup complete.");
+    return {
+        workspaceId: finalId,
+        workspaceRoot,
+        containerName: deriveContainerName(finalId),
+        workspaceDir: getWorkspaceDir(finalId),
+    };
+}

package/dist/commands/settings.js

@@ -0,0 +1,349 @@
+// =========================================================================================================================================
+// src/commands/settings.ts - Settings submenu: git mode, shadow paths, ports, rebuild, reset config
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { relative } from "node:path";
+import { cancel, confirm, isCancel, log, multiselect, note, outro, path, select, text } from "@clack/prompts";
+import { buildDefaultChambaYaml, readChambaYaml, writeChambaYaml } from "../lib/chamba-yaml.js";
+import { GIT_MODE } from "../lib/constants.js";
+import { readWebRange, writeWebRange } from "../lib/global-config.js";
+import { formatWebRange, PORT_MAX, PORT_MIN, parseWebRange } from "../lib/ports.js";
+import { countPatternHits } from "../lib/shadows.js";
+import { readWebKey, reassignOutOfRangeWebPorts, webInterfaceUrl } from "../lib/webterm.js";
+import { readGitMode, readWebPort, writeGitMode } from "../lib/workspace-identity.js";
+// --- Shadow paths menu -------------------------------------------------------------------------------------------------------------------
+async function shadowPathsMenu(ctx) {
+    const yaml = readChambaYaml(ctx.workspaceRoot);
+    if (!yaml) {
+        log.error("chamba.yaml not found or invalid.");
+        return;
+    }
+    const patterns = yaml.shadow_paths ?? [];
+    if (patterns.length > 0) {
+        const lines = patterns.map((p) => {
+            const hits = countPatternHits(p, ctx.workspaceRoot);
+            return `  ${p}  (${hits} ${hits === 1 ? "match" : "matches"})`;
+        });
+        note(lines.join("\n"), "Shadow patterns");
+    }
+    else {
+        log.info("No shadow patterns configured.");
+    }
+    log.message("Shadow patterns block the agent from seeing matching host paths -\n" +
+        "the container gets an empty, isolated copy instead.\n" +
+        "Supports gitignore-style patterns (e.g. node_modules, .env*).\n" +
+        "Git-tracked paths are skipped to avoid worktree diversions.");
+    const options = [{ value: "add", label: "Add pattern or path" }];
+    if (patterns.length > 0) {
+        options.push({ value: "remove", label: "Remove patterns" });
+    }
+    options.push({ value: "back", label: "← Back" });
+    const action = await select({ message: "Shadow paths:", options });
+    if (isCancel(action) || action === "back")
+        return;
+    if (action === "add") {
+        await addShadowPattern(ctx);
+    }
+    else if (action === "remove") {
+        await removeShadowPatterns(ctx);
+    }
+}
+async function addShadowPattern(ctx) {
+    const yaml = readChambaYaml(ctx.workspaceRoot);
+    if (!yaml)
+        return;
+    const patterns = [...(yaml.shadow_paths ?? [])];
+    const typeChoice = await select({
+        message: "Add:",
+        options: [
+            { value: "pattern", label: "Pattern", hint: "gitignore-style (e.g. .env*, *.log)" },
+            { value: "path", label: "Specific path", hint: "pick a file or directory" },
+        ],
+    });
+    if (isCancel(typeChoice))
+        return;
+    if (typeChoice === "pattern") {
+        const input = await text({
+            message: "Pattern:",
+            placeholder: "e.g. .env* or node_modules",
+            validate: (v) => {
+                const p = (v ?? "").trim();
+                if (p.length === 0)
+                    return "Pattern cannot be empty";
+                if (patterns.includes(p))
+                    return "Pattern already exists";
+                return undefined;
+            },
+        });
+        if (isCancel(input))
+            return;
+        const pattern = input.trim();
+        const hits = countPatternHits(pattern, ctx.workspaceRoot);
+        patterns.push(pattern);
+        log.info(`Added: ${pattern} (${hits} ${hits === 1 ? "match" : "matches"})`);
+    }
+    else {
+        const selected = await path({
+            message: "Path to shadow:",
+            root: ctx.workspaceRoot,
+            directory: true,
+        });
+        if (isCancel(selected))
+            return;
+        const absPath = selected.trim();
+        const rel = relative(ctx.workspaceRoot, absPath);
+        if (!rel || rel.startsWith("..")) {
+            log.warn("Path must be inside the workspace directory. Skipped.");
+            return;
+        }
+        if (patterns.includes(rel)) {
+            log.warn(`"${rel}" is already in shadow patterns. Skipped.`);
+            return;
+        }
+        patterns.push(rel);
+        log.info(`Added: ${rel}`);
+    }
+    yaml.shadow_paths = patterns;
+    writeChambaYaml(ctx.workspaceRoot, yaml);
+    await promptStopContainer(ctx);
+}
+async function removeShadowPatterns(ctx) {
+    const yaml = readChambaYaml(ctx.workspaceRoot);
+    if (!yaml?.shadow_paths?.length)
+        return;
+    const toRemove = await multiselect({
+        message: "Select patterns to remove: (space to toggle, enter to confirm)",
+        options: yaml.shadow_paths.map((p) => ({ value: p, label: p })),
+    });
+    if (isCancel(toRemove))
+        return;
+    const removeSet = new Set(toRemove);
+    yaml.shadow_paths = yaml.shadow_paths.filter((p) => !removeSet.has(p));
+    writeChambaYaml(ctx.workspaceRoot, yaml);
+    log.success(`Removed ${removeSet.size} pattern(s).`);
+    await promptStopContainer(ctx);
+}
+// --- Git mode menu -----------------------------------------------------------------------------------------------------------------------
+async function gitModeMenu(ctx) {
+    const current = readGitMode(ctx.workspaceId) ?? GIT_MODE.local;
+    note("Local         - local mutations allowed; remote blocked\n" +
+        "Strict        - read-only; mutations and remote blocked\n" +
+        "Unrestricted  - no chamba-enforced restrictions", "Git mode");
+    const choice = await select({
+        message: "Git mode:",
+        options: [
+            {
+                value: GIT_MODE.local,
+                label: "Local",
+                hint: current === GIT_MODE.local ? "current · default" : "default",
+            },
+            { value: GIT_MODE.strict, label: "Strict", ...(current === GIT_MODE.strict ? { hint: "current" } : {}) },
+            {
+                value: GIT_MODE.unrestricted,
+                label: "Unrestricted",
+                ...(current === GIT_MODE.unrestricted ? { hint: "current" } : {}),
+            },
+        ],
+        initialValue: current,
+    });
+    if (isCancel(choice))
+        return;
+    if (choice === current)
+        return;
+    if (choice === GIT_MODE.unrestricted) {
+        const confirmed = await confirm({
+            message: "Unrestricted mode disables chamba's built-in git restrictions (allows remote push/pull/fetch). Continue?",
+            initialValue: false,
+        });
+        if (isCancel(confirmed) || !confirmed) {
+            log.info("Git mode unchanged.");
+            return;
+        }
+    }
+    writeGitMode(ctx.workspaceId, choice);
+    log.success(`Git mode set to ${choice}.`);
+    await promptStopContainer(ctx);
+}
+// --- Ports menu ---------------------------------------------------------------------------------------------------------------------------
+// The web interface itself has no setting - it comes up with the container and the browser opens on it. What
+// is left to choose is the host port range every workspace draws its sticky port from, so this screen is that
+// one setting plus where this workspace currently lives.
+async function portsMenu(ctx) {
+    const range = readWebRange();
+    const webPort = readWebPort(ctx.workspaceId);
+    // The URL only opens the interface with the key the running server minted, so the live one is shown
+    // whenever it can be read. With nothing running there is no key to show, and saying where it comes
+    // from beats printing half a URL.
+    const liveKey = webPort === null ? null : readWebKey(ctx.containerName);
+    const url = webPort === null
+        ? "no port assigned yet"
+        : liveKey !== null
+            ? webInterfaceUrl(webPort, liveKey)
+            : `${webInterfaceUrl(webPort, null)}  (the key comes with the interface when it starts)`;
+    note(`web interface range:  ${formatWebRange(range)}  (all workspaces)\nthis workspace:       ${url}`, "Ports");
+    log.message("The host port range the web interface draws from.\n" +
+        "Each workspace keeps one sticky port from it, so its URL never changes.\n" +
+        "Loopback-only, never reachable off this machine, and the URL carries a key\n" +
+        "that is minted fresh every time the interface starts.\n" +
+        "Ports your own project publishes are set in chamba.yaml, not here.");
+    const input = await text({
+        message: "Port range (START-END):",
+        placeholder: formatWebRange(range),
+        initialValue: formatWebRange(range),
+        validate: (v) => {
+            const raw = (v ?? "").trim();
+            if (!/^\d+-\d+$/.test(raw))
+                return "Use START-END, e.g. 3900-3999";
+            const parsed = parseWebRange(raw);
+            if (!parsed) {
+                const [start = 0, end = 0] = raw.split("-").map(Number);
+                if (start >= end)
+                    return "Start must be below end";
+                return `Ports must be between ${PORT_MIN} and ${PORT_MAX}`;
+            }
+            return undefined;
+        },
+    });
+    if (isCancel(input))
+        return;
+    const newRange = parseWebRange(input.trim());
+    if (!newRange)
+        return; // Validate above guarantees this never fires; keeps the type narrow.
+    if (formatWebRange(newRange) === formatWebRange(range))
+        return;
+    writeWebRange(newRange);
+    // Only assignments now outside the range move; in-range ports stay sticky.
+    const moves = reassignOutOfRangeWebPorts(newRange);
+    for (const m of moves) {
+        log.info(`${m.workspaceId}: port ${m.from} -> ${m.to}`);
+    }
+    log.success(`Port range set to ${formatWebRange(newRange)}.`);
+    await promptStopContainer(ctx);
+}
+// --- Prompt to stop container ------------------------------------------------------------------------------------------------------------
+async function promptStopContainer(ctx) {
+    const containerName = ctx.containerName;
+    const inspect = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", containerName], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    const containerStatus = inspect.status === 0 ? inspect.stdout.trim() : null;
+    if (containerStatus !== "running") {
+        log.info("Changes will apply on next session.");
+        return;
+    }
+    const shouldStop = await confirm({ message: "Stop the running container so changes apply on next session?" });
+    if (isCancel(shouldStop) || !shouldStop) {
+        log.warn("Container still running with old config - it will be recreated on next session.");
+        return;
+    }
+    log.info("Stopping container...");
+    spawnSync("docker", ["stop", containerName], { stdio: "pipe" });
+    spawnSync("docker", ["rm", containerName], { stdio: "pipe" });
+    log.info("Container removed. Open a new session to apply changes.");
+}
+// --- Reset chamba.yaml -------------------------------------------------------------------------------------------------------------------
+async function resetChambaYaml(ctx) {
+    const yaml = readChambaYaml(ctx.workspaceRoot);
+    if (!yaml) {
+        log.error("chamba.yaml not found or invalid.");
+        return;
+    }
+    note("This will reset chamba.yaml to the minimal default (workspace_id + shadow_paths).\n" +
+        "Your workspace_id is preserved; shadow_paths reset to the defaults (node_modules, .env*).\n" +
+        "Any env, profiles, or ports settings will be removed - re-add them with your editor, which reads the schema the file points at.", "Reset chamba.yaml");
+    const confirmed = await confirm({ message: "Reset chamba.yaml to defaults?" });
+    if (isCancel(confirmed) || !confirmed)
+        return;
+    const freshYaml = buildDefaultChambaYaml(yaml.workspace_id);
+    writeChambaYaml(ctx.workspaceRoot, freshYaml);
+    log.success("chamba.yaml reset to defaults.");
+    await promptStopContainer(ctx);
+}
+// --- Settings submenu --------------------------------------------------------------------------------------------------------------------
+export async function run(ctx) {
+    while (true) {
+        const currentGitMode = readGitMode(ctx.workspaceId) ?? GIT_MODE.local;
+        const options = [
+            { value: "git-mode", label: "Git mode", hint: `current: ${currentGitMode}` },
+            { value: "shadow-paths", label: "Shadow paths", hint: "manage shadow patterns" },
+            { value: "ports", label: "Ports", hint: `web interface range: ${formatWebRange(readWebRange())}` },
+            { value: "rebuild", label: "Rebuild container", hint: "force a fresh image build" },
+            { value: "clean-rebuild", label: "Clean rebuild", hint: "fresh build, no cache" },
+            { value: "reset", label: "Reset config", hint: "restore chamba.yaml to defaults" },
+            { value: "back", label: "← Back" },
+        ];
+        const action = await select({ message: "Settings:", options });
+        if (isCancel(action) || action === "back") {
+            return "back";
+        }
+        switch (action) {
+            case "git-mode":
+                await gitModeMenu(ctx);
+                break;
+            case "shadow-paths":
+                await shadowPathsMenu(ctx);
+                break;
+            case "ports":
+                await portsMenu(ctx);
+                break;
+            case "rebuild":
+                return "rebuild";
+            case "clean-rebuild":
+                return "clean-rebuild";
+            case "reset":
+                await resetChambaYaml(ctx);
+                break;
+        }
+    }
+}
+// --- Stop workspace container ------------------------------------------------------------------------------------------------------------
+export async function stop(containerName) {
+    const inspectResult = spawnSync("docker", ["inspect", "--type", "container", containerName], { encoding: "utf8" });
+    if (inspectResult.status !== 0) {
+        log.info(`Container ${containerName} is not running.`);
+        return;
+    }
+    const confirmed = await confirm({ message: `Stop ${containerName}?` });
+    if (isCancel(confirmed) || !confirmed) {
+        cancel();
+        return;
+    }
+    log.info(`Stopping ${containerName}...`);
+    // Stop-only (no rm) so the next session resumes fast via the "exited" -> docker start path.
+    spawnSync("docker", ["stop", containerName], { stdio: "pipe" });
+    outro(`${containerName} stopped.`);
+}
+// --- Reset workspace image (stop container + remove image for fresh rebuild) -------------------------------------------------------------
+// Returns false when the user declines a running-container rebuild, so the caller can skip the fresh build
+// and leave the live session untouched.
+export async function resetImage(containerName) {
+    const statusResult = spawnSync("docker", ["inspect", "--type", "container", "--format", "{{.State.Status}}", containerName], {
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    const containerExists = statusResult.status === 0;
+    const running = containerExists && statusResult.stdout.trim() === "running";
+    // A running container is a live session. A rebuild stops and removes it first, so confirm before
+    // killing it out from under the user rather than surprising them mid-session.
+    if (running) {
+        log.warn("Rebuilding stops and removes the running container.\nAgent memory, settings, and workspace data are preserved.");
+        const proceed = await confirm({ message: "Rebuild now?", initialValue: true });
+        if (isCancel(proceed) || !proceed) {
+            cancel("Rebuild cancelled - container left running.");
+            return false;
+        }
+    }
+    if (containerExists) {
+        log.info(`Stopping container ${containerName}...`);
+        spawnSync("docker", ["stop", containerName], { stdio: "pipe" });
+        spawnSync("docker", ["rm", containerName], { stdio: "pipe" });
+    }
+    const imageResult = spawnSync("docker", ["images", "-q", containerName], { encoding: "utf8", stdio: "pipe" });
+    if ((imageResult.stdout ?? "").trim().length > 0) {
+        log.info(`Removing image ${containerName}...`);
+        spawnSync("docker", ["rmi", containerName], { stdio: "pipe" });
+    }
+    log.info("Image removed - starting fresh build…");
+    return true;
+}