totopo 3.2.1 → 3.3.0-rc-1

package/README.md

@@ -12,15 +12,14 @@ Local sandbox for AI agents.
 
 ## Motivation
 
-Before they run freely on your machine, ask yourself: **can you trust AI agents?**
+Two fundamental risks when running AI agents locally:
 
-- **Inherently unpredictable**: agents inevitably make mistakes, in ways that may be hard to detect or undo.
-- **Vulnerable to prompt injection**: agents with internet access can be subtly manipulated to leak sensitive data or execute unauthorized operations.
+1. Agents are unpredictable — they will make mistakes that may be hard to detect or undo.
+2. Agents are vulnerable to prompt injection and can be subtly manipulated to leak sensitive data or execute unauthorized operations.
 
-Totopo mitigates both risks with a dev container - when you run totopo in a given directory, that directory is mounted as a workspace where agents get a full, capable environment to work in - without access to anything outside it or to remote Git repositories.
+Totopo mitigates both risks by letting you run agents in a dev container — when you run totopo in a given directory, that directory is mounted as a workspace where agents can work freely, without access to the rest of your filesystem or your git remote.
 
-If an agent makes a mistake, damage is contained to the workspace, your git remote is out of reach.<br>
-If an agent gets compromised, it can't reach your host files — blast radius is limited to the workspace you chose to share.
+In practice, this means any mistake can be reverted from your git remote, and even a compromised agent can't access sensitive files on your machine — SSH keys, credentials, browser data — things a locally-running agent could otherwise read without you ever noticing.
 
 > totopo's security approach is basic — it is about the minimal precautions I believe anyone running AI agents should have. If you need more robust protections, look somewhere else.
 

package/dist/commands/dev.js

@@ -251,7 +251,7 @@ export async function run(packageDir, ctx, options) {
         envFilePath,
         hasGit,
         shadowPatterns,
-        workspaceName: ctx.displayName,
+        workspaceName: ctx.workspaceId,
         ...(options?.noCache !== undefined && { noCache: options.noCache }),
     };
     startContainer(containerOpts);

package/dist/commands/global.js

@@ -70,12 +70,12 @@ async function clearAgentMemory() {
         if (w === undefined)
             return;
         toClear = [w.workspaceId];
-        log.info(`Clearing agent memory for ${w.displayName}...`);
+        log.info(`Clearing agent memory for ${w.workspaceId}...`);
     }
     else {
         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.displayName, hint: w.workspaceRoot })),
+            options: workspaces.map((w) => ({ value: w.workspaceId, label: w.workspaceId, hint: w.workspaceRoot })),
             required: false,
         });
         if (isCancel(selected)) {
@@ -95,7 +95,7 @@ async function clearAgentMemory() {
         const isRunning = inspectResult.status === 0 && inspectResult.stdout.trim() === "running";
         if (isRunning) {
             const confirmed = await confirm({
-                message: `Container for ${w.displayName} is running. Stop it to clear memory?`,
+                message: `Container for ${w.workspaceId} is running. Stop it to clear memory?`,
             });
             if (isCancel(confirmed) || !confirmed)
                 continue;
@@ -104,7 +104,7 @@ async function clearAgentMemory() {
         }
         const agentsDir = join(w.workspaceDir, AGENTS_DIR);
         safeRmSync(agentsDir, { recursive: true, force: true });
-        log.success(`Cleared agent memory for ${w.displayName}.`);
+        log.success(`Cleared agent memory for ${w.workspaceId}.`);
     }
 }
 // --- Remove images (multi-select across all workspaces) ----------------------------------------------------------------------------------
@@ -163,7 +163,7 @@ async function uninstallWorkspaces(currentWorkspaceId) {
         message: "Select workspaces to uninstall: (space to toggle, enter to confirm)",
         options: sorted.map((w) => ({
             value: w.workspaceId,
-            label: w.displayName,
+            label: w.workspaceId,
             hint: w.workspaceRoot + (w.workspaceId === currentWorkspaceId ? " (current)" : ""),
         })),
         required: false,
@@ -199,7 +199,7 @@ async function uninstallWorkspaces(currentWorkspaceId) {
             removeTotopoYaml = !isCancel(ans) && ans;
         }
         removeWorkspaceFiles(w.workspaceRoot, w.workspaceDir, removeTotopoYaml);
-        log.success(`Uninstalled workspace ${w.displayName}.`);
+        log.success(`Uninstalled workspace ${w.workspaceId}.`);
     }
     return currentWorkspaceId !== undefined && selectedIds.includes(currentWorkspaceId);
 }

package/dist/commands/menu.js

@@ -16,7 +16,7 @@ export async function run(args) {
     // --- Status box ----------------------------------------------------------------------------------------------------------------------
     const containerStatus = workspaceRunning ? "running" : "stopped";
     const gitNotice = hasGit ? "" : `\n${styleText("yellow", "●")} no git — agent changes are not tracked`;
-    box(`workspace:   ${ctx.displayName}\nprofile:     ${activeProfile}\ncontainer:   ${containerStatus}${gitNotice}`, ` totopo v${version} `, {
+    box(`workspace:   ${ctx.workspaceId}\nprofile:     ${activeProfile}\ncontainer:   ${containerStatus}${gitNotice}`, ` totopo v${version} `, {
         contentAlign: "left",
         titleAlign: "center",
         width: "auto",

package/dist/commands/onboard.js

@@ -60,11 +60,6 @@ export async function run(cwd) {
         }
         workspaceRoot = yamlDir;
         yaml = existing;
-        // Show welcome message
-        if (yaml.name) {
-            log.info(yaml.name);
-            process.stdout.write("\n");
-        }
         const ok = await confirm({ message: `Set up totopo for: ${toTildePath(workspaceRoot)}?` });
         if (isCancel(ok) || !ok) {
             cancel("Setup cancelled.");
@@ -109,22 +104,23 @@ export async function run(cwd) {
         else {
             workspaceRoot = rootChoice;
         }
-        // Ask for workspace name (used as display name, also derives workspace_id)
-        const defaultName = basename(workspaceRoot);
-        const nameInput = await text({
-            message: "Workspace name:",
-            placeholder: defaultName,
-            defaultValue: defaultName,
+        // 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(nameInput)) {
+        if (isCancel(idInput)) {
             cancel("Setup cancelled.");
             return null;
         }
-        const workspaceName = nameInput.trim() || defaultName;
-        // Derive workspace_id from name, auto-resolve collisions with numeric suffix
-        const workspaceId = deriveUniqueWorkspaceId(slugifyForWorkspaceId(workspaceName), workspaceRoot);
+        const inputId = idInput.trim() || defaultId;
+        // Auto-resolve collisions with numeric suffix
+        const workspaceId = deriveUniqueWorkspaceId(inputId, workspaceRoot);
         // Build and write totopo.yaml
-        yaml = buildDefaultTotopoYaml(workspaceId, workspaceName);
+        yaml = buildDefaultTotopoYaml(workspaceId);
         writeTotopoYaml(workspaceRoot, yaml);
         log.success(`Created ${toTildePath(join(workspaceRoot, TOTOPO_YAML))}`);
     }
@@ -205,6 +201,5 @@ export async function run(cwd) {
         workspaceRoot,
         containerName: deriveContainerName(finalId),
         workspaceDir: getWorkspaceDir(finalId),
-        displayName: yaml.name || finalId,
     };
 }

package/dist/commands/workspace.js

@@ -147,12 +147,12 @@ async function resetTotopoYaml(ctx) {
         return;
     }
     note("This will reset totopo.yaml to factory defaults.\n" +
-        "Your workspace_id and name will be preserved.\n" +
+        "Your workspace_id will be preserved.\n" +
         "Shadow paths, profiles, and env_file will be reset to defaults.", "Reset totopo.yaml");
     const confirmed = await confirm({ message: "Reset totopo.yaml to defaults?" });
     if (isCancel(confirmed) || !confirmed)
         return;
-    const freshYaml = buildDefaultTotopoYaml(yaml.workspace_id, yaml.name);
+    const freshYaml = buildDefaultTotopoYaml(yaml.workspace_id);
     writeTotopoYaml(ctx.workspaceRoot, freshYaml);
     log.success("totopo.yaml reset to defaults.");
     await promptStopContainer(ctx);

package/dist/lib/migrate-to-latest.js

@@ -6,7 +6,7 @@
 //   v2.x (~/.totopo/projects/<sha256-hash>/)
 //     Each workspace stored as: meta.json, settings.json, agents/, shadows/
 //     Global API keys in ~/.totopo/.env
-//     Optional totopo.yaml with name field (no schema_version)
+//     Optional totopo.yaml with name field (removed in v3.3)
 //
 //   v3-rc-1/rc-2 (~/.totopo/workspaces/<workspace_id>/)
 //     Renamed projects/ to workspaces/, hash dirs to workspace_id dirs
@@ -16,6 +16,9 @@
 //   v3-rc-3+ (latest)
 //     project_id renamed to workspace_id in totopo.yaml
 //
+//   v3.2.1 and earlier
+//     totopo.yaml had schema_version field and yaml-language-server header (both redundant)
+//
 // All migrations are idempotent - each checks if needed and skips if not.
 // =========================================================================================================================================
 import { spawnSync } from "node:child_process";
@@ -54,18 +57,6 @@ function readV2ShadowPaths(dirPath) {
         return [];
     }
 }
-function readV2YamlName(workspaceRoot) {
-    try {
-        const raw = loadYaml(readFileSync(join(workspaceRoot, TOTOPO_YAML), "utf8"));
-        if (typeof raw !== "object" || raw === null)
-            return null;
-        const obj = raw;
-        return typeof obj.name === "string" ? obj.name : null;
-    }
-    catch {
-        return null;
-    }
-}
 function detectV2Projects() {
     const baseDir = getWorkspacesBaseDir();
     if (!existsSync(baseDir))
@@ -123,9 +114,8 @@ function migrateSingleV2Workspace(v2, existingIds) {
         workspaceId = yaml.workspace_id;
     }
     else {
-        const v2Name = readV2YamlName(v2.projectRoot);
         workspaceId = generateUniqueWorkspaceId(v2.displayName, existingIds);
-        yaml = buildDefaultTotopoYaml(workspaceId, v2Name ?? v2.displayName);
+        yaml = buildDefaultTotopoYaml(workspaceId);
         if (v2.shadowPaths.length > 0) {
             yaml.shadow_paths = [...new Set([...(yaml.shadow_paths ?? []), ...v2.shadowPaths])];
         }
@@ -351,6 +341,52 @@ function migrateRemoveLastCliUpdate() {
         }
     }
 }
+/**
+ * v3.2.1 and earlier: Remove deprecated fields from totopo.yaml.
+ * - schema_version: redundant, totopo validates with the bundled JSON schema at runtime
+ * - yaml-language-server header: created stale versioned URLs
+ * - name: redundant, workspace_id serves as both identifier and display name
+ * Only migrates the current workspace (found by walking up from cwd).
+ */
+function migrateRemoveDeprecatedYamlFields(cwd) {
+    const dir = findTotopoYamlDir(cwd);
+    if (!dir)
+        return;
+    const filePath = join(dir, TOTOPO_YAML);
+    try {
+        const content = readFileSync(filePath, "utf8");
+        const hasSchemaVersion = /^schema_version:\s/m.test(content);
+        const hasYamlLsHeader = content.includes("# yaml-language-server:");
+        const hasName = /^name:\s/m.test(content);
+        if (!hasSchemaVersion && !hasYamlLsHeader && !hasName)
+            return;
+        const raw = loadYaml(content);
+        if (typeof raw !== "object" || raw === null)
+            return;
+        const obj = raw;
+        delete obj.schema_version;
+        delete obj.name;
+        try {
+            writeTotopoYaml(dir, obj);
+            readTotopoYaml(dir);
+        }
+        catch {
+            writeFileSync(filePath, content);
+            return;
+        }
+        const removed = [];
+        if (hasSchemaVersion)
+            removed.push("schema_version");
+        if (hasYamlLsHeader)
+            removed.push("yaml-language-server header");
+        if (hasName)
+            removed.push("name");
+        log.success(`Migrated totopo.yaml: removed ${removed.join(", ")}`);
+    }
+    catch {
+        // Unreadable or invalid yaml - skip
+    }
+}
 // Order matters: migrateProjectsDir must run before migrateV2Workspaces because
 // step 2 scans ~/.totopo/workspaces/ which only exists after step 1 renames projects/.
 // Steps 3 and 4 are independent of each other and of steps 1-2.
@@ -365,6 +401,11 @@ const MIGRATIONS = [
     { from: "v3-rc-6", description: "Upgrade .lock files from positional to key=value format", run: migrateLockFileFormat },
     { from: "v3-rc-8", description: "Rename 'yaml' key to 'root' in .lock files", run: migrateLockKeyYamlToRoot },
     { from: "v3.1.0", description: "Remove last-cli-update key from .lock files", run: migrateRemoveLastCliUpdate },
+    {
+        from: "v3.2.1",
+        description: "Remove deprecated fields (schema_version, name, yaml-language-server) from totopo.yaml",
+        run: migrateRemoveDeprecatedYamlFields,
+    },
 ];
 /** Run all migrations in order. Called early in bin/totopo.js startup. */
 export function runMigration(cwd) {

package/dist/lib/totopo-yaml.js

@@ -78,18 +78,14 @@ export function readTotopoYaml(dir) {
 // Every published version (rc or release) has a corresponding git tag created by pnpm rc / pnpm rc:promote.
 // We rely on that tag existing so these URLs resolve correctly for every installed version.
 const { version } = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-const GITHUB_RAW_BASE = `https://raw.githubusercontent.com/asafratzon/totopo/v${version}`;
 export const GITHUB_README_URL = `https://github.com/asafratzon/totopo/blob/v${version}/README.md`;
-const YAML_HEADER = `# yaml-language-server: $schema=${GITHUB_RAW_BASE}/schema/totopo.schema.json
-`;
 // Inline comments injected before specific YAML keys (preceded by a blank line)
 const YAML_COMMENTS = {
-    workspace_id: "# totopo workspace config — run 'npx totopo' from anywhere under this directory tree to start your dev container.\n" +
+    workspace_id: "# totopo workspace config - run 'npx totopo' from anywhere under this directory tree to start your dev container.\n" +
         "# Ask the AI agent inside the container to help you edit this file if needed.\n" +
         "# This file may be rewritten by totopo (repair, reset, settings changes). Custom comments will not be preserved.",
-    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 totopo base image (Debian + Node.js + git + AI CLIs).\n" +
-        `# Base Dockerfile: ${GITHUB_RAW_BASE}/templates/Dockerfile\n` +
+    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 totopo base image (Debian + Node.js + git + AI CLIs).\n" +
         "# Switch profiles in the totopo settings menu, or ask the agent inside the container to help you add a new one.",
 };
 /** Write totopo.yaml to a directory with schema header and inline comments. */
@@ -113,7 +109,7 @@ export function writeTotopoYaml(dir, config) {
         output.push(line);
     }
     const body = output.join("\n").trimEnd();
-    writeFileSync(filePath, `${YAML_HEADER}${body}\n${PROFILES_FOOTER_COMMENT}\n`);
+    writeFileSync(filePath, `${body}\n${PROFILES_FOOTER_COMMENT}\n`);
 }
 // --- Defaults ----------------------------------------------------------------------------------------------------------------------------
 const DEFAULT_PROFILE_HOOK = `# No extras — uses the totopo base image as-is (Node.js + git + AI CLIs).
@@ -138,9 +134,8 @@ RUN curl -fsSL https://bun.sh/install | bash
 // Appended after the last profile to hint at adding more
 const PROFILES_FOOTER_COMMENT = "  # Add more profiles here — or ask the agent inside the container to set one up for you.";
 /** Create a default TotopoYamlConfig with sane defaults. */
-export function buildDefaultTotopoYaml(workspaceId, name) {
-    const config = {
-        schema_version: 3,
+export function buildDefaultTotopoYaml(workspaceId) {
+    return {
         workspace_id: workspaceId,
         shadow_paths: [...DEFAULT_SHADOW_PATHS],
         profiles: {
@@ -154,18 +149,10 @@ export function buildDefaultTotopoYaml(workspaceId, name) {
             },
         },
     };
-    if (name)
-        config.name = name;
-    // Reorder keys so name appears after workspace_id
-    const { schema_version, workspace_id, name: n, ...rest } = config;
-    const ordered = { schema_version, workspace_id };
-    if (n !== undefined)
-        ordered.name = n;
-    return Object.assign(ordered, rest);
 }
 // --- Repair -------------------------------------------------------------------------------------------------------------------------------
 /** Set of keys that TotopoYamlConfig allows (used to strip unknown fields). */
-const KNOWN_KEYS = new Set(["schema_version", "workspace_id", "name", "env_file", "shadow_paths", "profiles"]);
+const KNOWN_KEYS = new Set(["workspace_id", "env_file", "shadow_paths", "profiles"]);
 /**
  * Attempt to repair an invalid totopo.yaml on disk.
  * Strips unknown fields, fills missing required/optional fields from defaults,
@@ -192,10 +179,6 @@ export function repairTotopoYaml(dir) {
         const fallbackId = slugifyForWorkspaceId(basename(dir));
         const defaults = buildDefaultTotopoYaml(obj.workspace_id || fallbackId);
         // Fill missing required fields
-        if (!("schema_version" in obj)) {
-            obj.schema_version = defaults.schema_version;
-            fixes.push("added missing schema_version");
-        }
         if (!("workspace_id" in obj)) {
             obj.workspace_id = defaults.workspace_id;
             fixes.push(`added missing workspace_id ("${defaults.workspace_id}")`);

package/dist/lib/workspace-identity.js

@@ -126,7 +126,6 @@ export function listWorkspaces() {
                 workspaceRoot: lockPath,
                 containerName: deriveContainerName(workspaceId),
                 workspaceDir: getWorkspaceDir(workspaceId),
-                displayName: yaml.name || workspaceId,
             };
         }
         catch {
@@ -154,7 +153,6 @@ export function resolveWorkspace(fromPath) {
                     workspaceRoot: current,
                     containerName: deriveContainerName(yaml.workspace_id),
                     workspaceDir: getWorkspaceDir(yaml.workspace_id),
-                    displayName: yaml.name || yaml.workspace_id,
                 };
             }
             // totopo.yaml found but workspace not initialized or lock mismatch - return null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totopo",
-  "version": "3.2.1",
+  "version": "3.3.0-rc-1",
   "description": "Run AI coding agents safely in your local codebase",
   "type": "module",
   "bin": {

package/schema/totopo.schema.json

@@ -3,14 +3,9 @@
     "title": "totopo.yaml",
     "description": "Configuration file for totopo — secure AI dev containers",
     "type": "object",
-    "required": ["schema_version", "workspace_id"],
+    "required": ["workspace_id"],
     "additionalProperties": false,
     "properties": {
-        "schema_version": {
-            "type": "integer",
-            "const": 3,
-            "description": "Schema version — must be 3"
-        },
         "workspace_id": {
             "type": "string",
             "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
@@ -18,10 +13,6 @@
             "maxLength": 48,
             "description": "Unique workspace identifier. Used for container naming and cache directory. Lowercase alphanumeric and hyphens only."
         },
-        "name": {
-            "type": "string",
-            "description": "Human-readable workspace name (shown in menus and welcome message)"
-        },
         "env_file": {
             "type": "string",
             "description": "Path to env file relative to totopo.yaml (e.g. '.env'). Injected into container at runtime via --env-file."