totopo 1.0.8 → 2.0.0-rc-2

package/README.md

@@ -10,7 +10,7 @@ A simple CLI to use AI coding agents safely in your local codebase.
 
 ## Why totopo?
 
-Here's the thing about AI agents: they're probabilistic. They occasionally misinterpret instructions, take unexpected shortcuts, or simply get it wrong. Most of the time they're fine. But "most of the time" isn't a great argument for giving them unrestricted access to your machine, your credentials, and your remote repositories.
+Here's the thing about AI agents: they're probabilistic. They occasionally misinterpret instructions or simply get it wrong. Most of the time they're fine. But "most of the time" isn't a great argument for giving them unrestricted access to your machine, your credentials, and your remote repositories.
 
 totopo draws a simple boundary: agents get a full, capable environment to work in — they just can't touch anything outside the project, and they can't reach your remote. That's it. No domain whitelisting, no paranoia, no compromise on what the agent can actually do. Just a reasonable containment for non-deterministic tools.
 
@@ -18,21 +18,24 @@ Note: no sandbox substitutes for good judgment. Consider keeping any sensitive s
 
 ## How totopo Works
 
-- Unified, simple DX: run `npx totopo` from anywhere inside a local git repo.
-- Installed once per git repository in a `.totopo/` directory at the repo root.
-- Manages one Docker container per repository.
+totopo organises work around **projects** — any local directory you register with totopo. The first time you run `npx totopo` in a directory, it walks you through a short setup. Every subsequent run, from anywhere inside that directory tree, totopo resolves the project automatically and shows the project menu:
 
-To start a development session, run `npx totopo`, choose `Open session` and confirm the desired scope: the full repo, the current directory, or selected files and folders.
+- **Open session** — choose a scope and jump into an AI coding session
+- **Stop container** — stop the running container
+- **Runtime Mode** — adjust runtime mode and installed tools
+- **Rebuild container** — rebuild the docker image (upon changing runtime mode)
+
+All config lives in `~/.totopo/` — nothing is written to your project by default.
 
 ### Concurrent Sessions
-totopo uses one container per repository (not per session). This keeps resource usage bounded and makes reconnections fast - you can open as many sessions as you need — they all share the same running container.
+totopo uses one Docker container per project, not one per session. You can open as many terminal sessions as you need — they all connect to the same container, keeping resource usage bounded and reconnections fast.
 
 The tradeoff is that only one scope can be active at a time: if you reopen a session with a different scope, totopo recreates the container to match the new mounts, which would terminate any active sessions connected to the previous container.
 
 ## Requirements
 
-- [Docker](https://www.docker.com/products/docker-desktop/) - used to build and run the dev container
-- [git](https://git-scm.com/) - safeguard to ensure agents only run in projects with version control in place
+- [Docker](https://www.docker.com/products/docker-desktop/) — used to build and run the dev container
+- [Node.js](https://nodejs.org/) — required to run `npx totopo`
 
 ## Quick Start
 
@@ -41,11 +44,11 @@ cd your-project
 npx totopo
 ```
 
-First-time setup — running `npx totopo` in a fresh repo, selecting a runtime mode, and waiting for the Docker image to build for the first time:
-![First-time setup](.github/assets/demo-onboarding.gif)
+<!--First-time setup — running `npx totopo` in a fresh repo, selecting a runtime mode, and waiting for the Docker image to build for the first time:-->
+<!-- ![First-time setup](.github/assets/demo-onboarding.gif) -->
 
-Opening a session when totopo is already initialized is quick. The agent is aware of its scope and sandbox constraints:
-![Quick start](.github/assets/demo-quickstart.gif)
+<!--Opening a session when totopo is already initialized is quick. The agent is aware of its scope and sandbox constraints:-->
+<!-- ![Quick start](.github/assets/demo-quickstart.gif) -->
 
 ## Core features at a glance
 
@@ -75,9 +78,9 @@ Remote git operations are blocked inside the container. Push from your host term
 
 ### Session scope
 
-When you open a session, totopo asks what part of the repository to mount into the container:
+When you open a session, totopo asks what part of the project to mount into the container:
 
-- `Repo root` — the full repository
+- `Repo root` — the full project directory
 - `Current directory` — only the current directory
 - `Selective` — specific files and folders chosen interactively
 
@@ -87,14 +90,14 @@ The selected scope is stored on the container and checked on every later `Open s
 - If the requested scope is different, totopo recreates the container so the mounted paths match the new scope.
 - Parallel terminals on the same scope are fine. totopo connects with `docker exec`, so any concurrency limits are just the normal limits of sharing one running container.
 
-This is an intentional tradeoff: you get predictable resource usage and quick reconnects, but only one active mounted view per repository at a time.
+This is an intentional tradeoff: you get predictable resource usage and quick reconnects, but only one active mounted view per project at a time.
 
 In `Current directory` and `Selective` scopes, `.git` is intentionally not mounted. Mounting `.git` would expose the full commit history of every repository file, including files outside the mounted paths, which defeats the point of scoped access. As a result, git is unavailable inside those scoped sessions and the agent operates without repository history. The agent is instructed to surface these limitations at session start.
 
 Scoped sessions are well-suited for focused tasks where you want to give the agent a narrow, explicit view of your codebase.
 
-Example showcasing agent awareness of selective scope limitations:
-![Scoped access](.github/assets/demo-scoped.gif)
+<!-- Example showcasing agent awareness of selective scope limitations:-->
+<!-- ![Scoped access](.github/assets/demo-scoped.gif) -->
 
 ### AI CLIs with persistent sessions
 
@@ -106,7 +109,7 @@ claude      # Claude Code (Anthropic)
 codex       # Codex (OpenAI)
 ```
 
-Agent session data is isolated per repository, so agents do not bleed context between projects. To clear memory, run `npx totopo` and navigate to `Advanced > Clear agent memory`. This stops the container if running and removes the `.totopo/agents/` directory.
+Agent session data is isolated per project, so agents do not bleed context between projects. To clear memory, run `npx totopo` and navigate to `Manage totopo > Clear agent memory` and select a project. This stops the container if running and removes the agents directory.
 
 ### Dev container runtime
 
@@ -117,27 +120,51 @@ Choose between two modes:
 
 Either way, basic dev tools and all three AI CLIs are always included.
 
-## What gets created in your project
+## What gets installed
+
+All totopo config lives in `~/.totopo/` on your machine — nothing is written to your project directory unless you opt in.
 
 ```text
-your-project/
-└── .totopo/
-    ├── Dockerfile        # container image definition
-    ├── post-start.mjs    # security checks + readiness summary on every start
-    ├── settings.json     # runtime mode + selected tools (committed with project)
-    ├── README.md         # .totopo reference
-    └── agents/           # agent session data — gitignored, created on first session start
-        ├── claude/       # mounted as ~/.claude/
-        ├── opencode/     # mounted as ~/.config/opencode/ + ~/.local/share/opencode/
-        └── codex/        # mounted as ~/.codex/
-
-~/.totopo/.env            # API keys — global, outside all repos, never mounted into container
+~/.totopo/
+├── .env                        # API keys — global, never mounted into container
+└── projects/
+    └── <id>/                   # stable hash of the project root path
+        ├── meta.json           # project root, display name, container name
+        ├── settings.json       # runtime mode + selected tools
+        ├── Dockerfile          # container image definition
+        ├── post-start.mjs      # security checks + readiness summary on every start
+        └── agents/             # agent session data — created on first session start
+            ├── claude/         # mounted as ~/.claude/
+            ├── opencode/       # mounted as ~/.config/opencode/ + ~/.local/share/opencode/
+            └── codex/          # mounted as ~/.codex/
 ```
 
-totopo is initialized at the repository root, and `.totopo/` lives there regardless of which directory you later open a session from. Agent session history and conversation data are persisted in `.totopo/agents/` across container rebuilds and restarts. This directory is gitignored so session data stays local to your machine.
+Agent session history and conversation data are persisted in the `agents/` directory across container rebuilds and restarts.
+
+### Shared onboarding (optional)
+
+If you want contributors to get a one-click setup experience, add a `totopo.yaml` file at your project root:
+
+```yaml
+# totopo.yaml — project anchor
+#
+# name        — shown as: "Welcome to <name>."
+# description — shown as: "<description>"
+
+name: my-project
+description: Our AI coding sandbox. Ask @alice for the API keys.
+```
+
+When a new contributor runs `npx totopo`, totopo reads this file to anchor the project root and displays the welcome message before prompting for setup. Without it, totopo will find the git root and suggest it as the project root, so `totopo.yaml` is purely optional.
+
+To add a project anchor to an existing local-only totopo project, run `npx totopo` and select `Add project anchor` from the project menu.
 
 ## Limitations
 
+**Rename or move** — moving the project directory breaks identity since totopo uses the absolute path as the project key. Re-run `npx totopo` in the new location to onboard again. Orphaned configs can be cleaned up via `Manage totopo`.
+
+**Single machine** — `~/.totopo/` is local. Switching to a new machine requires re-onboarding each project.
+
 **Audio / microphone** — the image includes `sox` (required by Claude Code for voice mode), but audio passthrough from the host depends on your OS. macOS, Linux, and Windows each require different device configuration. If you need voice mode, set up audio passthrough manually for your platform.
 
 ## Disclaimer

package/bin/totopo.js

@@ -1,23 +1,26 @@
 #!/usr/bin/env node
-// =============================================================================
-// bin/totopo.js — totopo entry point
+// =========================================================================================================================================
+// bin/totopo.js - totopo entry point
 // Run this from your project directory (or via npx totopo).
-// =============================================================================
+// =========================================================================================================================================
 
 import { execSync, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { basename, dirname } from "node:path";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { cancel, isCancel, select } from "@clack/prompts";
 import { run as advanced } 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 { addProjectAnchor, run as onboard } from "../dist/commands/onboard.js";
+import { run as rebuild } from "../dist/commands/rebuild.js";
+import { run as settings } from "../dist/commands/settings.js";
 import { run as stop } from "../dist/commands/stop.js";
 import { run as syncDockerfile } from "../dist/commands/sync-dockerfile.js";
-import { toDockerName } from "../dist/lib/docker-name.js";
+import { listProjectIds, resolveProject } from "../dist/lib/project-identity.js";
 
-// ─── Guard: inside container ──────────────────────────────────────────────────
+// --- Guard: inside container -------------------------------------------------------------------------------------------------------------
 try {
     if (execSync("whoami", { encoding: "utf8" }).trim() === "devuser") {
         console.error("");
@@ -29,26 +32,15 @@ try {
         process.exit(1);
     }
 } catch {
-    // whoami unavailable — not blocking
+    // whoami unavailable - not blocking
 }
 
-// ─── Paths ────────────────────────────────────────────────────────────────────
+// --- Paths -------------------------------------------------------------------------------------------------------------------------------
 // dirname(dirname(...)) walks up from bin/ to the package root.
 const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const cwd = process.cwd();
 
-let repoRoot;
-try {
-    repoRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf8" }).trim();
-} catch {
-    console.error("");
-    console.error("  No git repository found.");
-    console.error("");
-    console.error("  totopo requires a git repository. Run 'git init' first, then re-run totopo.");
-    console.error("");
-    process.exit(1);
-}
-
-// ─── Guard: dist/ must exist ─────────────────────────────────────────────────
+// --- Guard: dist/ must exist -------------------------------------------------------------------------------------------------------------
 if (!existsSync(new URL("../dist/commands/sync-dockerfile.js", import.meta.url))) {
     console.error("");
     console.error("  totopo: compiled output not found.");
@@ -58,59 +50,106 @@ if (!existsSync(new URL("../dist/commands/sync-dockerfile.js", import.meta.url))
     process.exit(1);
 }
 
-// ─── Onboarding ───────────────────────────────────────────────────────────────
-if (!existsSync(`${repoRoot}/.totopo/Dockerfile`)) {
-    const completed = await onboard(packageDir, repoRoot);
-    if (!completed) process.exit(0);
+// --- Resolve project from CWD (walk-up through ~/.totopo/projects/) ----------------------------------------------------------------------
+let project = resolveProject(cwd);
+
+// --- Onboarding (if not in a registered project) -----------------------------------------------------------------------------------------
+if (!project) {
+    // Detect project context: git root or totopo.yaml present?
+    let gitRoot = null;
+    try {
+        gitRoot = execSync("git rev-parse --show-toplevel", { encoding: "utf8", stdio: "pipe" }).trim();
+    } catch {
+        // Not in a git repo - that's fine
+    }
+
+    const totopoJsonPath = `${gitRoot ?? cwd}/totopo.yaml`;
+    const hasTotopoYaml = existsSync(totopoJsonPath);
+
+    if (gitRoot !== null || hasTotopoYaml) {
+        // Has project context - if other projects already exist, let the user choose first
+        if (listProjectIds().length > 0) {
+            process.stdout.write("\n");
+            const choice = await select({
+                message: "What would you like to do?",
+                options: [
+                    { value: "setup", label: "Set up totopo for this directory" },
+                    { value: "manage", label: "Manage totopo →" },
+                ],
+            });
+            if (isCancel(choice)) {
+                cancel();
+                process.exit(0);
+            }
+            if (choice === "manage") {
+                await advanced(packageDir);
+                process.exit(0);
+            }
+        }
+
+        const ctx = await onboard(packageDir, cwd);
+        if (!ctx) process.exit(0); // cancelled -> exit cleanly
+        project = ctx;
+    } else {
+        // No project context -> show Manage totopo menu directly
+        await advanced(packageDir);
+        process.exit(0);
+    }
 }
 
-// ─── Sync Dockerfile with host runtimes ───────────────────────────────────────
-await syncDockerfile(packageDir, repoRoot);
+// --- Sync Dockerfile with host runtimes --------------------------------------------------------------------------------------------------
+await syncDockerfile(packageDir, project);
 
-// ─── Doctor (silent pre-check) ────────────────────────────────────────────────
-const doctorResult = await doctor(repoRoot, false);
+// --- Doctor (silent pre-check) -----------------------------------------------------------------------------------------------------------
+const doctorResult = await doctor(project.projectDir, false);
 if (!doctorResult.ok) {
     console.error("  Fix the issues above and re-run totopo.");
     console.error("");
     process.exit(1);
 }
 
-// ─── Gather state for menu ────────────────────────────────────────────────────
-const projectName = basename(repoRoot);
-const dockerName = toDockerName(projectName);
+// --- Gather container state for menu -----------------------------------------------------------------------------------------------------
+const { containerName } = project.meta;
 
-const dockerResult = spawnSync("docker", ["ps", "--filter", "name=totopo-managed-", "--format", "{{.Names}}"], {
+const dockerResult = spawnSync("docker", ["ps", "--filter", "name=totopo-", "--format", "{{.Names}}"], {
     encoding: "utf8",
 });
-const activeCount = dockerResult.stdout ? dockerResult.stdout.trim().split("\n").filter(Boolean).length : 0;
+const activeNames = dockerResult.stdout ? dockerResult.stdout.trim().split("\n").filter(Boolean) : [];
+const activeCount = activeNames.length;
+const projectRunning = activeNames.some((n) => n === containerName);
 
-const projectContainerResult = spawnSync("docker", ["ps", "--filter", `name=${dockerName}`, "--format", "{{.Names}}"], {
-    encoding: "utf8",
-});
-const projectRunning = (projectContainerResult.stdout ?? "")
-    .trim()
-    .split("\n")
-    .filter(Boolean)
-    .some((n) => n === dockerName);
-
-// ─── Interactive menu loop ────────────────────────────────────────────────────
+// --- Interactive menu loop ---------------------------------------------------------------------------------------------------------------
 let showMenu = true;
 while (showMenu) {
     showMenu = false;
 
-    const action = await menu({ projectName, activeCount, projectRunning });
+    // Re-evaluated each iteration so menu options stay in sync (e.g. after "Add project anchor")
+    const hasTotopoYaml = existsSync(`${project.meta.projectRoot}/totopo.yaml`);
+
+    const action = await menu({ ctx: project, activeCount, projectRunning, hasTotopoYaml });
 
     switch (action) {
         case "dev":
-            await dev(packageDir, repoRoot);
+            await dev(packageDir, project);
+            break;
+        case "rebuild":
+            await rebuild(project.meta.containerName);
+            await dev(packageDir, project);
             break;
         case "stop":
-            await stop(projectName);
+            await stop(project.meta.containerName);
+            break;
+        case "settings":
+            await settings(packageDir, project);
+            showMenu = true;
+            break;
+        case "add-anchor":
+            await addProjectAnchor(project);
+            showMenu = true;
             break;
-        case "advanced": {
-            const result = await advanced(packageDir, projectName, repoRoot);
+        case "manage-totopo": {
+            const result = await advanced(packageDir);
             if (result === "back") showMenu = true;
-            if (result === "rebuild") await dev(packageDir, repoRoot);
             break;
         }
         default: