🤖 feat: use workspace name for plan file storage (#1082)

ammar-agent · web-flow · commit 5f47458685f7 · 2025-12-10T12:10:58.000-06:00
Store plan files at `~/.mux/plans/{projectName}/{workspaceName}.md`
instead of `~/.mux/plans/{workspaceId}.md` for better discoverability.

## Changes
- `getPlanFilePath` now takes `(workspaceName, projectName)`
- Added `getLegacyPlanFilePath` for migration support
- Migrate legacy plans to new location on read
- Handle plan file rename when workspace is renamed

## New Format
- Makes plans discoverable: `ls ~/.mux/plans/mux/` shows all mux
workspace plans
- Provides global uniqueness via `projectName + workspaceName`
- Supports future workspace rename by moving files within project folder

## Legacy Support
- On read, checks new path first, falls back to legacy
- When legacy found, migrates to new location and deletes old file

_Generated with `mux`_
diff --git a/src/common/utils/planStorage.test.ts b/src/common/utils/planStorage.test.ts
@@ -0,0 +1,35 @@
+import { getPlanFilePath, getLegacyPlanFilePath } from "./planStorage";
+
+describe("planStorage", () => {
+  describe("getPlanFilePath", () => {
+    it("should return path with project name and workspace name", () => {
+      const result = getPlanFilePath("fix-plan-a1b2", "mux");
+      expect(result).toBe("~/.mux/plans/mux/fix-plan-a1b2.md");
+    });
+
+    it("should produce same path for same inputs", () => {
+      const result1 = getPlanFilePath("fix-bug-x1y2", "myproject");
+      const result2 = getPlanFilePath("fix-bug-x1y2", "myproject");
+      expect(result1).toBe(result2);
+    });
+
+    it("should organize plans by project folder", () => {
+      const result1 = getPlanFilePath("sidebar-a1b2", "mux");
+      const result2 = getPlanFilePath("auth-c3d4", "other-project");
+      expect(result1).toBe("~/.mux/plans/mux/sidebar-a1b2.md");
+      expect(result2).toBe("~/.mux/plans/other-project/auth-c3d4.md");
+    });
+  });
+
+  describe("getLegacyPlanFilePath", () => {
+    it("should return path with workspace ID", () => {
+      const result = getLegacyPlanFilePath("a1b2c3d4e5");
+      expect(result).toBe("~/.mux/plans/a1b2c3d4e5.md");
+    });
+
+    it("should handle legacy format IDs", () => {
+      const result = getLegacyPlanFilePath("mux-main");
+      expect(result).toBe("~/.mux/plans/mux-main.md");
+    });
+  });
+});
diff --git a/src/common/utils/planStorage.ts b/src/common/utils/planStorage.ts
@@ -3,8 +3,25 @@
  * Returns a path with ~ prefix that works with both local and SSH runtimes.
  * The runtime will expand ~ to the appropriate home directory.
  *
- * Plan files are stored at: ~/.mux/plans/{workspaceId}.md
+ * Plan files are stored at: ~/.mux/plans/{projectName}/{workspaceName}.md
+ *
+ * Workspace names include a random suffix (e.g., "sidebar-a1b2") making them
+ * globally unique with high probability. The project folder is for organization
+ * and discoverability, not uniqueness.
+ *
+ * @param workspaceName - Human-readable workspace name with suffix (e.g., "fix-plan-a1b2")
+ * @param projectName - Project name extracted from project path (e.g., "mux")
+ */
+export function getPlanFilePath(workspaceName: string, projectName: string): string {
+  return `~/.mux/plans/${projectName}/${workspaceName}.md`;
+}
+
+/**
+ * Get the legacy plan file path (stored by workspace ID).
+ * Used for migration: when reading, check new path first, then fall back to legacy.
+ *
+ * @param workspaceId - Stable workspace identifier (e.g., "a1b2c3d4e5")
  */
-export function getPlanFilePath(workspaceId: string): string {
+export function getLegacyPlanFilePath(workspaceId: string): string {
   return `~/.mux/plans/${workspaceId}.md`;
 }
diff --git a/src/node/orpc/router.ts b/src/node/orpc/router.ts
@@ -13,9 +13,9 @@ import type {
 } from "@/common/orpc/types";
 import { createAuthMiddleware } from "./authMiddleware";
 import { createAsyncMessageQueue } from "@/common/utils/asyncMessageQueue";
-import { getPlanFilePath } from "@/common/utils/planStorage";
+
 import { createRuntime } from "@/node/runtime/runtimeFactory";
-import { readFileString } from "@/node/utils/runtime/helpers";
+import { readPlanFile } from "@/node/utils/runtime/helpers";
 import { createAsyncEventQueue } from "@/common/utils/asyncEventIterator";
 
 export const router = (authToken?: string) => {
@@ -592,9 +592,7 @@ export const router = (authToken?: string) => {
         .input(schemas.workspace.getPlanContent.input)
         .output(schemas.workspace.getPlanContent.output)
         .handler(async ({ context, input }) => {
-          const planPath = getPlanFilePath(input.workspaceId);
-
-          // Get workspace metadata to determine runtime
+          // Get workspace metadata to determine runtime and paths
           const metadata = await context.workspaceService.getInfo(input.workspaceId);
           if (!metadata) {
             return { success: false as const, error: `Workspace not found: ${input.workspaceId}` };
@@ -605,12 +603,17 @@ export const router = (authToken?: string) => {
             projectPath: metadata.projectPath,
           });
 
-          try {
-            const content = await readFileString(runtime, planPath);
-            return { success: true as const, data: { content, path: planPath } };
-          } catch {
-            return { success: false as const, error: `Plan file not found at ${planPath}` };
+          const result = await readPlanFile(
+            runtime,
+            metadata.name,
+            metadata.projectName,
+            input.workspaceId
+          );
+
+          if (!result.exists) {
+            return { success: false as const, error: `Plan file not found at ${result.path}` };
           }
+          return { success: true as const, data: { content: result.content, path: result.path } };
         }),
       backgroundBashes: {
         subscribe: t
diff --git a/src/node/services/aiService.ts b/src/node/services/aiService.ts
@@ -57,7 +57,7 @@ import { EnvHttpProxyAgent, type Dispatcher } from "undici";
 import { getPlanFilePath } from "@/common/utils/planStorage";
 import { getPlanModeInstruction } from "@/common/utils/ui/modeUtils";
 import type { UIMode } from "@/common/types/mode";
-import { readFileString } from "@/node/utils/runtime/helpers";
+import { readPlanFile } from "@/node/utils/runtime/helpers";
 
 // Export a standalone version of getToolsForModel for use in backend
 
@@ -992,17 +992,18 @@ export class AIService extends EventEmitter {
       // Construct plan mode instruction if in plan mode
       // This is done backend-side because we have access to the plan file path
       let effectiveAdditionalInstructions = additionalSystemInstructions;
+      const planFilePath = getPlanFilePath(metadata.name, metadata.projectName);
+
+      // Read plan file (handles legacy migration transparently)
+      const planResult = await readPlanFile(
+        runtime,
+        metadata.name,
+        metadata.projectName,
+        workspaceId
+      );
+
       if (mode === "plan") {
-        const planFilePath = getPlanFilePath(workspaceId);
-        // Check if plan file exists using runtime (supports both local and SSH)
-        let planExists = false;
-        try {
-          await runtime.stat(planFilePath);
-          planExists = true;
-        } catch {
-          // File doesn't exist
-        }
-        const planModeInstruction = getPlanModeInstruction(planFilePath, planExists);
+        const planModeInstruction = getPlanModeInstruction(planFilePath, planResult.exists);
         effectiveAdditionalInstructions = additionalSystemInstructions
           ? `${planModeInstruction}\n\n${additionalSystemInstructions}`
           : planModeInstruction;
@@ -1015,16 +1016,8 @@ export class AIService extends EventEmitter {
         const lastAssistantMessage = [...filteredMessages]
           .reverse()
           .find((m) => m.role === "assistant");
-        if (lastAssistantMessage?.metadata?.mode === "plan") {
-          const planFilePath = getPlanFilePath(workspaceId);
-          try {
-            const content = await readFileString(runtime, planFilePath);
-            if (content.trim()) {
-              planContentForTransition = content;
-            }
-          } catch {
-            // No plan file exists, proceed without plan content
-          }
+        if (lastAssistantMessage?.metadata?.mode === "plan" && planResult.content.trim()) {
+          planContentForTransition = planResult.content;
         }
       }
 
@@ -1141,7 +1134,7 @@ export class AIService extends EventEmitter {
           backgroundProcessManager: this.backgroundProcessManager,
           // Plan mode configuration for path enforcement
           mode: mode as UIMode | undefined,
-          planFilePath: mode === "plan" ? getPlanFilePath(workspaceId) : undefined,
+          planFilePath: mode === "plan" ? planFilePath : undefined,
           workspaceId,
           // External edit detection callback
           recordFileState,
diff --git a/src/node/services/workspaceService.ts b/src/node/services/workspaceService.ts
@@ -40,6 +40,8 @@ import { createBashTool } from "@/node/services/tools/bash";
 import type { BashToolResult } from "@/common/types/tools";
 import { secretsToRecord } from "@/common/types/secrets";
 
+import { movePlanFile } from "@/node/utils/runtime/helpers";
+
 /** Maximum number of retry attempts when workspace name collides */
 const MAX_WORKSPACE_NAME_COLLISION_RETRIES = 3;
 
@@ -560,6 +562,9 @@ export class WorkspaceService extends EventEmitter {
         return config;
       });
 
+      // Rename plan file if it exists (uses workspace name, not ID)
+      await movePlanFile(runtime, oldName, newName, oldMetadata.projectName);
+
       const allMetadataUpdated = await this.config.getAllWorkspaceMetadata();
       const updatedMetadata = allMetadataUpdated.find((m) => m.id === workspaceId);
       if (!updatedMetadata) {
diff --git a/src/node/utils/runtime/helpers.ts b/src/node/utils/runtime/helpers.ts
@@ -1,5 +1,6 @@
 import type { Runtime, ExecOptions } from "@/node/runtime/Runtime";
 import { PlatformPaths } from "@/node/utils/paths.main";
+import { getLegacyPlanFilePath, getPlanFilePath } from "@/common/utils/planStorage";
 
 /**
  * Convenience helpers for working with streaming Runtime APIs.
@@ -117,3 +118,76 @@ async function streamToString(stream: ReadableStream<Uint8Array>): Promise<strin
     reader.releaseLock();
   }
 }
+
+/**
+ * Result from reading a plan file with legacy migration support
+ */
+export interface ReadPlanResult {
+  /** Plan file content (empty string if file doesn't exist) */
+  content: string;
+  /** Whether a plan file exists */
+  exists: boolean;
+  /** The canonical plan file path (new format) */
+  path: string;
+}
+
+/**
+ * Read plan file content, checking new path first then legacy, migrating if needed.
+ * This handles the transparent migration from ~/.mux/plans/{id}.md to
+ * ~/.mux/plans/{projectName}/{workspaceName}.md
+ */
+export async function readPlanFile(
+  runtime: Runtime,
+  workspaceName: string,
+  projectName: string,
+  workspaceId: string
+): Promise<ReadPlanResult> {
+  const planPath = getPlanFilePath(workspaceName, projectName);
+  const legacyPath = getLegacyPlanFilePath(workspaceId);
+
+  // Try new path first
+  try {
+    const content = await readFileString(runtime, planPath);
+    return { content, exists: true, path: planPath };
+  } catch {
+    // Fall back to legacy path
+    try {
+      const content = await readFileString(runtime, legacyPath);
+      // Migrate: move to new location
+      try {
+        const planDir = planPath.substring(0, planPath.lastIndexOf("/"));
+        await execBuffered(runtime, `mkdir -p "${planDir}" && mv "${legacyPath}" "${planPath}"`, {
+          cwd: "/tmp",
+          timeout: 5,
+        });
+      } catch {
+        // Migration failed, but we have the content
+      }
+      return { content, exists: true, path: planPath };
+    } catch {
+      // File doesn't exist at either location
+      return { content: "", exists: false, path: planPath };
+    }
+  }
+}
+
+/**
+ * Move a plan file from one workspace name to another (e.g., during rename).
+ * Silently succeeds if source file doesn't exist.
+ */
+export async function movePlanFile(
+  runtime: Runtime,
+  oldWorkspaceName: string,
+  newWorkspaceName: string,
+  projectName: string
+): Promise<void> {
+  const oldPath = getPlanFilePath(oldWorkspaceName, projectName);
+  const newPath = getPlanFilePath(newWorkspaceName, projectName);
+
+  try {
+    await runtime.stat(oldPath);
+    await execBuffered(runtime, `mv "${oldPath}" "${newPath}"`, { cwd: "/tmp", timeout: 5 });
+  } catch {
+    // No plan file to move, that's fine
+  }
+}
diff --git a/tests/ipc/fileChangeNotification.test.ts b/tests/ipc/fileChangeNotification.test.ts
@@ -94,11 +94,13 @@ describeIntegration("File Change Notification Integration", () => {
     if (!createResult.success) throw new Error("Failed to create workspace");
 
     const workspaceId = createResult.metadata.id;
+    const workspaceName = createResult.metadata.name;
+    const projectName = createResult.metadata.projectName;
 
     try {
       // 2. Get the AgentSession and plan file path
       const session = env.services.workspaceService.getOrCreateSession(workspaceId);
-      const planPath = getPlanFilePath(workspaceId);
+      const planPath = getPlanFilePath(workspaceName, projectName);
 
       // 3. Create the plan directory and file
       const planDir = join(planPath, "..");
@@ -206,11 +208,13 @@ describeIntegration("File Change Notification Integration", () => {
     if (!createResult.success) throw new Error("Failed to create workspace");
 
     const workspaceId = createResult.metadata.id;
+    const workspaceName = createResult.metadata.name;
+    const projectName = createResult.metadata.projectName;
 
     try {
       // 2. Get the AgentSession and plan file path
       const session = env.services.workspaceService.getOrCreateSession(workspaceId);
-      const planPath = getPlanFilePath(workspaceId);
+      const planPath = getPlanFilePath(workspaceName, projectName);
 
       // 3. Create the plan directory and file
       const planDir = join(planPath, "..");
diff --git a/tests/ipc/planCommands.test.ts b/tests/ipc/planCommands.test.ts
@@ -79,10 +79,12 @@ describeIntegration("Plan Commands Integration", () => {
       if (!createResult.success) throw new Error("Failed to create workspace");
 
       const workspaceId = createResult.metadata.id;
+      const workspaceName = createResult.metadata.name;
+      const projectName = createResult.metadata.projectName;
 
       try {
         // Create a plan file
-        const planPath = getPlanFilePath(workspaceId);
+        const planPath = getPlanFilePath(workspaceName, projectName);
         const expandedPlanPath = expandTilde(planPath);
         const planDir = path.dirname(expandedPlanPath);
         await fs.mkdir(planDir, { recursive: true });
@@ -116,10 +118,12 @@ describeIntegration("Plan Commands Integration", () => {
       if (!createResult.success) throw new Error("Failed to create workspace");
 
       const workspaceId = createResult.metadata.id;
+      const workspaceName = createResult.metadata.name;
+      const projectName = createResult.metadata.projectName;
 
       try {
         // Create an empty plan file
-        const planPath = getPlanFilePath(workspaceId);
+        const planPath = getPlanFilePath(workspaceName, projectName);
         const expandedPlanPath = expandTilde(planPath);
         const planDir = path.dirname(expandedPlanPath);
         await fs.mkdir(planDir, { recursive: true });
@@ -153,10 +157,12 @@ describeIntegration("Plan Commands Integration", () => {
       if (!createResult.success) throw new Error("Failed to create workspace");
 
       const workspaceId = createResult.metadata.id;
+      const workspaceName = createResult.metadata.name;
+      const projectName = createResult.metadata.projectName;
 
       try {
         // Create a plan file
-        const planPath = getPlanFilePath(workspaceId);
+        const planPath = getPlanFilePath(workspaceName, projectName);
         const planDir = path.dirname(planPath);
         await fs.mkdir(planDir, { recursive: true });
         await fs.writeFile(planPath, "# Test Plan");
