chamba 0.3.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asaf Ratzon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,67 +1,70 @@
 # chamba
 
-A browser workspace beside your terminal coding agent - a rich parallel interface to the terminal chat.
+Run AI coding agents in a container, one per workspace, and work with them from the browser.
 
-## Quick start
+Chamba is a personal tool.
+It is built for one person's machine and published to npm only so that `npx` can fetch it - no support, no compatibility promises, no release notes.
 
-Install the skill for your agent:
+> Chamba is a fork of [totopo](https://www.npmjs.com/package/totopo), taken web-first.
+> Totopo stays what it is: terminal-first, public, and maintained on its own.
+> The two run side by side on one host - separate config files, separate caches, separate containers - so a directory can be managed by either.
 
-```
-npx chamba@latest skill install
-```
-
-Then, in your agent, run `/chamba` (or ask it to "open chamba").
-It opens a browser workspace where you read rendered markdown, paste screenshots the agent can read, point at UI in the app tab, and view rich HTML pages the agent renders in the Illustration tab.
+## Quick start
 
-The browser is a second conversation beside the terminal: a background `chamba poll` keeps the agent listening for browser input while it stays available in the terminal, and each channel is answered where it was asked.
+```bash
+npx chamba
+```
 
-Add `--global` to install the skill for every project (`~/.claude/skills`).
+Run it from your project directory.
+The first run walks through a short setup and writes a `chamba.yaml` at the workspace root; every run after that opens the workspace menu.
 
-## Testing
+## How it works
 
-`pnpm check` is the full gate: typecheck (the packages plus the test sources, via `tsconfig.test.json`), lint, both builds (`inject`, `web`), then `pnpm test` and `pnpm test:e2e:flake`.
-`pnpm test` runs Vitest's two projects (`unit` + `integration`).
-`pnpm test:e2e` runs the Playwright suite once; `pnpm test:e2e:flake` repeats it three times with no retries so an intermittent failure cannot hide, and is the e2e variant the gate runs on every push.
-`pnpm test:e2e:video` runs the suite once and records a video of every flow under `test-results/e2e/`, for watching the browser interactions.
+A **workspace** is any directory holding a `chamba.yaml`.
+`npx chamba` walks up from where it runs to find the nearest one, so any subdirectory of a project reaches the same workspace.
 
-| Path | Covers | Run by |
-| --- | --- | --- |
-| `packages/*/src/**/*.test.ts` | Unit tests colocated with each package (`shared`, `server`, `cli`, `inject`): pure schema and logic. | `pnpm test` (Vitest `unit` project, parallel). |
-| `tests/integration/` | Integration: real server and CLI processes over real ports and the WebSocket transport (roundtrip, durability, annotations, attachments, issues, pages, references, binding, init, lifecycle). Shared helpers live in `tests/support/`. | `pnpm test` (Vitest `integration` project, sequential forks with long timeouts, since parallel port binding would flake). |
-| `tests/e2e/` | End-to-end: a real browser drives the production web build against a real server and CLI, proving the human and agent exchange renders live. | `pnpm test:e2e` (Playwright, serial; `pretest:e2e` installs the browser first). |
-| `tests/fixtures/` | Sample apps for the "Your app" surface: a Vite + React app on port 4001 and a Next.js app on port 4002. The e2e suite drives the React app as a cross-origin annotation target; both are runnable by hand for manual exploration. | `pnpm fixture:react`, `pnpm fixture:next` (see `tests/fixtures/README.md`). |
+Each workspace gets one container, not one per session, so several terminals share it and reconnect fast.
+The workspace directory is mounted at `/workspace`, and nothing outside it is.
 
-The e2e browser runs inside the dev container, which provides the Chromium system libraries and fonts it needs.
+`chamba.yaml` needs only a `workspace_id`.
+The optional fields - `shadow_paths`, `env`, `ports`, `profiles` - are all described in the JSON schema the generated file points at, which editors read for completion and validation.
 
-## Local package testing
+## What the container gives an agent
 
-`pnpm -s chamba` drives the working copy: it runs the source under tsx (no build) and resolves only inside this repo, so it is always the local version, never the published package.
+- **Its own filesystem.** Only the workspace is mounted, as a non-root user, with `no-new-privileges` set. No host credentials go in.
+- **No git remote.** The default git mode blocks every remote operation while leaving local commits free. `strict` also blocks mutating git commands; `unrestricted` lifts the remote block, and only you can turn it on.
+- **Hidden paths.** Shadow paths (`node_modules`, `.env*` by default) are overlaid with empty container-local copies, so an agent never reads the real thing.
+- **The current CLIs.** claude, opencode and codex are kept on their latest versions, each with its config directory bind-mounted to the workspace cache so conversations and memory survive rebuilds.
+- **A web interface.** The browser front-end relays the real agent TUI over a websocket - every session on one page, several agents at once, images and dictation. It starts with the container. Claude sessions also get a status strip above the composer: model, context used, quota left.
 
-### One command
+The menu has two doors into that container.
+**Web interface** brings it up, opens the interface in your browser, and hands your terminal straight back - the work happens in the tab.
+**Container shell** drops you into a shell inside the container and opens nothing; the greeting there still prints the interface's URL, because it is running either way.
 
-From the repo root:
+## The web pane
 
-```
-pnpm try:chamba
-```
+Beside the terminal is a pane of pages, there from the first second of a session: until an agent has published anything it is a spine at the edge of the window, and opening it says what the pane is for and what to ask for.
+An agent publishes a standalone HTML file into it - `webpane report.html --title "Port rework"` - and it shows up as a chip above the pane: a plan, a comparison table, a long answer, anything worth reading at your own pace instead of scrolling back for.
 
-It waits until the Next fixture is serving `:4002`, then drops you straight into a sandbox session in the same terminal tab.
-This tab never starts the fixture itself, so it can never leave one running in the background.
-If nothing is serving `:4002` yet, it prints the command to start the fixture and waits; open a separate tab in the repo root, run `pnpm dev:next` (or `pnpm re:dev:next` for a clean reinstall first), and this tab continues on its own once the port is up.
+A page can also ask.
+A form marked `data-feedback` is wired up by the interface, and what you submit is written as JSON next to the page, with one line typed into the agent's terminal saying where to read it.
 
-### The individual pieces
+Pages are kept, one directory per conversation, so resuming a conversation opens with them again.
+They live under `~/.chamba/workspaces/<id>/agents/webpane/` on the host, and nothing deletes them.
 
-Each runs from the repo root; add `-w` (`pnpm -w dev:next`) to run it from any subdir.
+## Where state lives
 
-- `pnpm dev:next` - Next fixture on `:4002` (fast; assumes deps are installed via `pnpm install`).
-- `pnpm re:dev:next` - clean build dirs, reinstall, then the same (the container shadows `node_modules`, so this matters for a truly fresh run).
-- `pnpm fixtures:stop` - stop the fixture dev servers (React on `:4001`, Next on `:4002`). Run it where the fixture runs (host or container); it kills only the fixture processes, never Docker's port forwarder.
-- `npx totopo` - start the workspace's sandbox session; runs from anywhere under the repo.
-- `pnpm -s chamba open` - inside the session, opens chamba and prints its URL.
+`chamba.yaml` lives in the workspace and can be committed.
+Everything else is on your machine under `~/.chamba/`: one directory per workspace holding its lock file, agent config, and shadow overlays, plus a host-global `config` for settings that are yours rather than the project's.
 
-Confirm the workspace publishes chamba's port with `CHAMBA_HOST=0.0.0.0` and `CHAMBA_PORT=4319`; the fixture's inject script targets `:4319`.
-Then open the printed chamba URL, point the "Your app" tab at `:4002`, and do real work: paste a screenshot, annotate, ask the agent to show an illustration page.
+## Developing chamba
 
----
+```bash
+pnpm install
+pnpm start        # run the CLI from source (host only - Docker is not available in the dev container)
+pnpm check        # typecheck, lint, repo checks, tests, build
+pnpm release      # check, bump, commit and publish to npm
+```
 
-A personal tool, published as-is with no stability promises.
+`pnpm release` is the whole release process: it reads the live version off npm, offers a bump, runs `pnpm check`, commits the bump and publishes.
+`AGENTS.md` carries the conventions this repo is written to.

package/bin/chamba.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// =========================================================================================================================================
+// bin/chamba.js - chamba entry point
+// Run this from your workspace directory (or via npx chamba).
+// =========================================================================================================================================
+
+import { execSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cancel, confirm, isCancel, log, select } from "@clack/prompts";
+import { run as advancedMenu } from "../dist/commands/advanced.js";
+import { run as dev } from "../dist/commands/dev.js";
+import { run as doctor } from "../dist/commands/doctor.js";
+import { run as menu } from "../dist/commands/menu.js";
+import { run as onboard } from "../dist/commands/onboard.js";
+import { resetImage, run as settingsMenu, stop } from "../dist/commands/settings.js";
+import { repairChambaYaml } from "../dist/lib/chamba-yaml.js";
+import { deriveContainerName, findChambaYamlDir, listWorkspaceIds, resolveWorkspace } from "../dist/lib/workspace-identity.js";
+
+// --- Suppress Docker CLI hints ------------------------------------------------------------------------------------------------------------
+// Docker prints a "What's next:" hint block (about `docker debug`) to stderr after commands like `docker run`. Our
+// interactive docker calls inherit stderr, so the hint leaks between chamba's own log steps. chamba owns this process
+// and never wants those hints, so force it off unconditionally; every docker child inherits this env.
+process.env.DOCKER_CLI_HINTS = "false";
+
+// --- Guard: inside container -------------------------------------------------------------------------------------------------------------
+try {
+    if (execSync("whoami", { encoding: "utf8" }).trim() === "devuser") {
+        console.error("");
+        console.error("  You are running chamba from inside the dev container.");
+        console.error("  Open a terminal on your host machine and run:");
+        console.error("");
+        console.error("    chamba  (or npx chamba from your workspace directory)");
+        console.error("");
+        process.exit(1);
+    }
+} catch {
+    // whoami unavailable - not blocking
+}
+
+// --- Paths -------------------------------------------------------------------------------------------------------------------------------
+const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const cwd = process.cwd();
+
+// --- Version -----------------------------------------------------------------------------------------------------------------------------
+const { version } = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+
+// --- Guard: dist/ must exist -------------------------------------------------------------------------------------------------------------
+if (!existsSync(new URL("../dist/commands/dev.js", import.meta.url))) {
+    console.error("");
+    console.error("  chamba: compiled output not found.");
+    console.error("  This should not happen with a published package.");
+    console.error("  If you are developing locally, run: pnpm build");
+    console.error("");
+    process.exit(1);
+}
+
+// --- Auto-repair chamba.yaml if needed ---------------------------------------------------------------------------------------------------
+// Every chamba workspace onboards fresh, so there is no old shape to detect and nothing to migrate.
+const yamlDir = findChambaYamlDir(cwd);
+if (yamlDir) {
+    const result = repairChambaYaml(yamlDir);
+    if (result.error) {
+        console.error("");
+        console.error(`  ${result.error}`);
+        console.error("");
+        process.exit(1);
+    }
+    if (result.repairedYaml) {
+        log.info(result.message);
+
+        // Prompt to stop container if running (config changed)
+        const cn = deriveContainerName(result.repairedYaml.workspace_id);
+        const inspect = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", cn], {
+            encoding: "utf8",
+            stdio: "pipe",
+        });
+        if (inspect.status === 0 && inspect.stdout.trim() === "running") {
+            const shouldStop = await confirm({
+                message: "Stop the running container so repaired config applies on next session?",
+            });
+            if (isCancel(shouldStop) || !shouldStop) {
+                log.warn("Container still running with old config.");
+            } else {
+                spawnSync("docker", ["stop", cn], { stdio: "pipe" });
+                spawnSync("docker", ["rm", cn], { stdio: "pipe" });
+                log.info("Container stopped. Changes will apply on next session.");
+            }
+        }
+    }
+}
+
+// --- Resolve workspace from CWD (walk-up looking for chamba.yaml) ------------------------------------------------------------------------
+let workspace;
+try {
+    workspace = resolveWorkspace(cwd);
+} catch (err) {
+    console.error("");
+    console.error(`  ${err instanceof Error ? err.message : err}`);
+    console.error("");
+    process.exit(1);
+}
+
+// --- Onboarding (if not in a registered workspace) ---------------------------------------------------------------------------------------
+if (!workspace) {
+    // If other workspaces already exist, let the user choose setup vs manage
+    if (listWorkspaceIds().length > 0) {
+        while (true) {
+            process.stdout.write("\n");
+            const choice = await select({
+                message: "What would you like to do?",
+                options: [
+                    { value: "setup", label: "Set up chamba for this directory" },
+                    { value: "advanced", label: "Advanced" },
+                ],
+            });
+            if (isCancel(choice)) {
+                cancel();
+                process.exit(0);
+            }
+            if (choice === "advanced") {
+                // "Back" returns here to re-show this chooser; a terminal action (uninstall) returns
+                // undefined and exits, matching the main menu loop's handling below.
+                const result = await advancedMenu();
+                if (result === "back") continue;
+                process.exit(0);
+            }
+            // "setup" - leave the chooser and fall through to onboarding.
+            break;
+        }
+    }
+
+    const ctx = await onboard(cwd);
+    if (!ctx) process.exit(0);
+    workspace = ctx;
+}
+
+// --- Doctor (pre-check; silent on success, prints failed checks otherwise) ---------------------------------------------------------------
+const doctorResult = await doctor();
+if (!doctorResult.ok) {
+    console.error("");
+    console.error("  chamba can't start:");
+    for (const err of doctorResult.errors) {
+        console.error(`    \x1b[2m•\x1b[0m  ${err}`);
+    }
+    console.error("");
+    console.error("  Fix the issues above and re-run chamba.");
+    console.error("");
+    process.exit(1);
+}
+
+// --- Interactive menu loop ---------------------------------------------------------------------------------------------------------------
+const { containerName } = workspace;
+let showMenu = true;
+while (showMenu) {
+    showMenu = false;
+
+    // Refresh container state on each loop iteration
+    const dockerResult = spawnSync("docker", ["ps", "--filter", "name=chamba-", "--format", "{{.Names}}"], {
+        encoding: "utf8",
+    });
+    const activeNames = dockerResult.stdout ? dockerResult.stdout.trim().split("\n").filter(Boolean) : [];
+    const activeCount = activeNames.length;
+    const workspaceRunning = activeNames.some((n) => n === containerName);
+
+    const action = await menu({ ctx: workspace, activeCount, workspaceRunning, version });
+
+    switch (action) {
+        case "web":
+            await dev(packageDir, workspace, { mode: "web" });
+            break;
+        case "shell":
+            await dev(packageDir, workspace, { mode: "shell" });
+            break;
+        case "stop":
+            await stop(workspace.containerName);
+            break;
+        case "settings": {
+            const settingsResult = await settingsMenu(workspace);
+            if (settingsResult === "rebuild") {
+                // resetImage returns false when the user declines a running-container rebuild - skip the
+                // build and return to the menu, leaving the live session untouched.
+                if (await resetImage(workspace.containerName)) {
+                    await dev(packageDir, workspace, { mode: "web" });
+                } else {
+                    showMenu = true;
+                }
+            } else if (settingsResult === "clean-rebuild") {
+                if (await resetImage(workspace.containerName)) {
+                    await dev(packageDir, workspace, { noCache: true, mode: "web" });
+                } else {
+                    showMenu = true;
+                }
+            } else {
+                showMenu = true;
+            }
+            break;
+        }
+        case "advanced": {
+            const result = await advancedMenu(workspace.workspaceId);
+            if (result === "back") showMenu = true;
+            break;
+        }
+        case "quit":
+            // Trailing blank line so the menu does not sit flush against the next shell prompt.
+            process.stdout.write("\n");
+            break;
+        default:
+            break;
+    }
+}

package/dist/commands/advanced.js

@@ -0,0 +1,278 @@
+// =========================================================================================================================================
+// src/commands/advanced.ts - Advanced menu: less-common operations (stop containers, clear agent memory, remove images, uninstall)
+// =========================================================================================================================================
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { cancel, confirm, isCancel, log, multiselect, outro, select, text } from "@clack/prompts";
+import { AGENTS_DIR, CHAMBA_DIR, CHAMBA_YAML, CONTAINER_NAME_PREFIX, LABEL_MANAGED } from "../lib/constants.js";
+import { safeRmSync } from "../lib/safe-rm.js";
+import { listWorkspaces } from "../lib/workspace-identity.js";
+// --- Helpers -----------------------------------------------------------------------------------------------------------------------------
+/** Remove workspace cache dir and optionally chamba.yaml from the workspace root. Exported for testing. */
+export function removeWorkspaceFiles(workspaceRoot, workspaceDir, removeChambaYaml) {
+    safeRmSync(workspaceDir, { recursive: true, force: true });
+    if (removeChambaYaml) {
+        const yamlPath = join(workspaceRoot, CHAMBA_YAML);
+        if (existsSync(yamlPath)) {
+            safeRmSync(yamlPath);
+        }
+    }
+}
+// Stop-only (no rm) so the next session resumes fast via the "exited" -> docker start path.
+function stopContainer(name) {
+    spawnSync("docker", ["stop", name], { stdio: "pipe" });
+}
+// Stop and remove - only for flows that must recreate the container (image removal, uninstall).
+function stopAndRemoveContainer(name) {
+    spawnSync("docker", ["stop", name], { stdio: "pipe" });
+    spawnSync("docker", ["rm", name], { stdio: "pipe" });
+}
+// --- Stop containers (multi-select across all workspaces) --------------------------------------------------------------------------------
+async function stopContainers() {
+    const listResult = spawnSync("docker", ["ps", "--filter", `name=${CONTAINER_NAME_PREFIX}`, "--format", "{{.Names}}"], {
+        encoding: "utf8",
+    });
+    const running = (listResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    if (running.length === 0) {
+        log.info("No running chamba containers.");
+        return;
+    }
+    // Always show the selector, even for a single container, so nothing is stopped without the user picking it.
+    const selected = await multiselect({
+        message: "Select containers to stop: (space to toggle, enter to confirm)",
+        options: running.map((name) => ({ value: name, label: name })),
+        required: false,
+    });
+    if (isCancel(selected)) {
+        cancel();
+        return;
+    }
+    const toStop = selected;
+    if (toStop.length === 0) {
+        log.info("Nothing selected - no containers stopped.");
+        return;
+    }
+    for (const name of toStop) {
+        log.info(`Stopping ${name}...`);
+        stopContainer(name);
+    }
+    log.success("Done.");
+}
+// --- Clear agent memory (multi-select across all workspaces) -----------------------------------------------------------------------------
+async function clearAgentMemory() {
+    const workspaces = listWorkspaces().filter((w) => existsSync(join(w.workspaceDir, AGENTS_DIR)));
+    if (workspaces.length === 0) {
+        log.info("No agent memory found.");
+        return;
+    }
+    // Always show the selector, even for a single workspace, so memory is never cleared without the user picking it.
+    const selected = await multiselect({
+        message: "Select workspaces to clear agent memory for: (space to toggle, enter to confirm)",
+        options: workspaces.map((w) => ({ value: w.workspaceId, label: w.workspaceId, hint: w.workspaceRoot })),
+        required: false,
+    });
+    if (isCancel(selected)) {
+        cancel();
+        return;
+    }
+    const toClear = selected;
+    if (toClear.length === 0) {
+        log.info("Nothing selected - no agent memory cleared.");
+        return;
+    }
+    for (const id of toClear) {
+        const w = workspaces.find((x) => x.workspaceId === id);
+        if (!w)
+            continue;
+        const inspectResult = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", w.containerName], {
+            encoding: "utf8",
+            stdio: "pipe",
+        });
+        const isRunning = inspectResult.status === 0 && inspectResult.stdout.trim() === "running";
+        if (isRunning) {
+            const confirmed = await confirm({
+                message: `Container for ${w.workspaceId} is running. Stop it to clear memory?`,
+            });
+            if (isCancel(confirmed) || !confirmed)
+                continue;
+            log.info(`Stopping ${w.containerName}...`);
+            stopContainer(w.containerName);
+        }
+        const agentsDir = join(w.workspaceDir, AGENTS_DIR);
+        safeRmSync(agentsDir, { recursive: true, force: true });
+        log.success(`Cleared agent memory for ${w.workspaceId}.`);
+    }
+}
+// --- Remove images (multi-select across all workspaces) ----------------------------------------------------------------------------------
+async function removeImages() {
+    const listResult = spawnSync("docker", ["images", "--filter", `label=${LABEL_MANAGED}=true`, "--format", "{{.Repository}}\t{{.ID}}"], {
+        encoding: "utf8",
+    });
+    const lines = (listResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    if (lines.length === 0) {
+        log.info("No chamba images found.");
+        return;
+    }
+    const images = lines.map((line) => {
+        const parts = line.split("\t");
+        const repo = parts[0] ?? "";
+        const id = parts[1] ?? "";
+        return { repo, id };
+    });
+    const selected = await multiselect({
+        message: "Select images to remove: (space to toggle, enter to confirm)",
+        options: images.map((img) => ({ value: img.repo, label: img.repo, hint: img.id.slice(0, 12) })),
+        required: false,
+    });
+    if (isCancel(selected)) {
+        cancel();
+        return;
+    }
+    // Stop any running container using this image first
+    for (const repo of selected) {
+        const psResult = spawnSync("docker", ["ps", "--filter", `name=${repo}`, "--format", "{{.Names}}"], {
+            encoding: "utf8",
+        });
+        const containers = (psResult.stdout ?? "").trim().split("\n").filter(Boolean);
+        for (const c of containers) {
+            log.info(`Stopping container ${c} before removing image...`);
+            stopAndRemoveContainer(c);
+        }
+        log.info(`Removing image ${repo}...`);
+        spawnSync("docker", ["rmi", repo], { stdio: "pipe" });
+    }
+    log.success("Done.");
+}
+// --- Uninstall workspaces (multi-select, remove container + image + workspace dir) -------------------------------------------------------
+async function uninstallWorkspaces(currentWorkspaceId) {
+    const workspaces = listWorkspaces();
+    if (workspaces.length === 0) {
+        log.info("No registered workspaces.");
+        return false;
+    }
+    // Show current workspace first if known
+    const sorted = currentWorkspaceId
+        ? [...workspaces].sort((a, b) => (a.workspaceId === currentWorkspaceId ? -1 : b.workspaceId === currentWorkspaceId ? 1 : 0))
+        : workspaces;
+    log.info("Uninstalling a workspace stops and removes its container and image, and deletes its data from ~/.chamba/workspaces/. Your files are untouched.");
+    const selected = await multiselect({
+        message: "Select workspaces to uninstall: (space to toggle, enter to confirm)",
+        options: sorted.map((w) => ({
+            value: w.workspaceId,
+            label: w.workspaceId,
+            hint: w.workspaceRoot + (w.workspaceId === currentWorkspaceId ? " (current)" : ""),
+        })),
+        required: false,
+    });
+    if (isCancel(selected)) {
+        cancel();
+        return false;
+    }
+    const selectedIds = selected;
+    for (const id of selectedIds) {
+        const w = workspaces.find((x) => x.workspaceId === id);
+        if (!w)
+            continue;
+        // Stop and remove container if it exists (running or exited)
+        const psResult = spawnSync("docker", ["ps", "-a", "--filter", `name=${w.containerName}`, "--format", "{{.Names}}"], {
+            encoding: "utf8",
+        });
+        const containers = (psResult.stdout ?? "").trim().split("\n").filter(Boolean);
+        for (const c of containers) {
+            log.info(`Stopping and removing container ${c}...`);
+            stopAndRemoveContainer(c);
+        }
+        log.info(`Removing image ${w.containerName}...`);
+        spawnSync("docker", ["rmi", w.containerName], { stdio: "inherit" });
+        // Ask whether to also remove chamba.yaml from the workspace root
+        const yamlPath = join(w.workspaceRoot, CHAMBA_YAML);
+        let removeChambaYaml = false;
+        if (existsSync(yamlPath)) {
+            const ans = await confirm({
+                message: `Also remove chamba.yaml from ${w.workspaceRoot}?`,
+                initialValue: true,
+            });
+            removeChambaYaml = !isCancel(ans) && ans;
+        }
+        removeWorkspaceFiles(w.workspaceRoot, w.workspaceDir, removeChambaYaml);
+        log.success(`Uninstalled workspace ${w.workspaceId}.`);
+    }
+    return currentWorkspaceId !== undefined && selectedIds.includes(currentWorkspaceId);
+}
+// --- Uninstall chamba (global) -----------------------------------------------------------------------------------------------------------
+async function uninstallChamba() {
+    const confirmed = await text({
+        message: 'Type "uninstall-chamba" to confirm full uninstall:',
+        validate: (v) => ((v ?? "").trim() !== "uninstall-chamba" ? 'Type exactly "uninstall-chamba" to confirm' : undefined),
+    });
+    if (isCancel(confirmed) || confirmed.trim() !== "uninstall-chamba") {
+        cancel("Uninstall cancelled.");
+        return;
+    }
+    // Stop and remove all chamba containers
+    const psResult = spawnSync("docker", ["ps", "-a", "--filter", `name=${CONTAINER_NAME_PREFIX}`, "--format", "{{.Names}}"], {
+        encoding: "utf8",
+    });
+    const containers = (psResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    for (const c of containers) {
+        log.info(`Stopping and removing container ${c}...`);
+        stopAndRemoveContainer(c);
+    }
+    // Remove all chamba images
+    const imagesResult = spawnSync("docker", ["images", "--filter", `label=${LABEL_MANAGED}=true`, "--format", "{{.Repository}}"], {
+        encoding: "utf8",
+    });
+    const imgs = (imagesResult.stdout ?? "").trim().split("\n").filter(Boolean);
+    for (const img of imgs) {
+        log.info(`Removing image ${img}...`);
+        spawnSync("docker", ["rmi", img], { stdio: "inherit" });
+    }
+    // Delete ~/.chamba/
+    const globalChambaDir = join(homedir(), CHAMBA_DIR);
+    if (existsSync(globalChambaDir)) {
+        log.info("Deleting ~/.chamba/...");
+        safeRmSync(globalChambaDir, { recursive: true, force: true });
+    }
+    outro("chamba uninstalled. Re-run npx chamba to set up again.");
+}
+// --- Advanced menu -----------------------------------------------------------------------------------------------------------------------
+export async function run(currentWorkspaceId) {
+    while (true) {
+        const action = await select({
+            message: "Advanced:",
+            options: [
+                { value: "stop-containers", label: "Stop containers", hint: "pick running containers" },
+                { value: "clear-memory", label: "Clear agent memory", hint: "pick workspaces to clear" },
+                { value: "remove-images", label: "Remove images", hint: "pick images to remove" },
+                { value: "uninstall-workspace", label: "Uninstall workspaces", hint: "pick workspaces to remove" },
+                { value: "uninstall", label: "Uninstall chamba", hint: "wipe ~/.chamba/ and all containers/images" },
+                { value: "back", label: "← Back" },
+            ],
+        });
+        if (isCancel(action) || action === "back") {
+            return "back";
+        }
+        switch (action) {
+            case "stop-containers":
+                await stopContainers();
+                break;
+            case "clear-memory":
+                await clearAgentMemory();
+                break;
+            case "remove-images":
+                await removeImages();
+                break;
+            case "uninstall-workspace": {
+                const currentDeleted = await uninstallWorkspaces(currentWorkspaceId);
+                if (currentDeleted)
+                    return undefined;
+                break;
+            }
+            case "uninstall":
+                await uninstallChamba();
+                return undefined;
+        }
+    }
+}