🤖 Centralize workspace metadata in config.json

Move workspace metadata from scattered metadata.json files to centralized
config.json. This establishes config as the single source of truth for
workspace data and fixes missing projectPath errors in git status checks.

**New config structure:**
- Workspace entries now include: id, name, createdAt (optional)
- Legacy path-only entries still supported (backward compat)
- Automatic migration on app startup: reads metadata.json, writes to config

**Benefits:**
- Single source of truth (no scattered session files)
- No more missing projectPath errors
- Simpler architecture
- Backward compatible

**Changes:**
- Workspace interface: Added optional id/name/createdAt fields
- getAllWorkspaceMetadata(): Prefers config, falls back to metadata files
- Workspace create/rename: Now writes full metadata to config
- Migration: Automatic on first load, writes back to config

**Migration strategy:**
- Config entries with id/name: Used directly (new format)
- Config entries with path only: Read from metadata.json, migrate to config
- No metadata file: Generate legacy ID, save to config
- Config saved once if any migrations occurred

Metadata.json files kept for backward compat with older cmux versions.

Fixes #259 (git status not appearing due to missing projectPath)

Author: ammar-agent

src/config.test.ts

@@ -161,17 +161,14 @@ describe("Config", () => {
       expect(metadata.projectName).toBe("project");
       expect(metadata.projectPath).toBe(projectPath);
 
-      // Verify metadata file was created
-      const sessionDir = config.getSessionDir("project-feature-branch");
-      const metadataPath = path.join(sessionDir, "metadata.json");
-      expect(fs.existsSync(metadataPath)).toBe(true);
-
-      const savedMetadata = JSON.parse(fs.readFileSync(metadataPath, "utf-8")) as {
-        id: string;
-        name: string;
-      };
-      expect(savedMetadata.id).toBe("project-feature-branch");
-      expect(savedMetadata.name).toBe("feature-branch");
+      // Verify metadata was migrated to config
+      const configData = config.loadConfigOrDefault();
+      const projectConfig = configData.projects.get(projectPath);
+      expect(projectConfig).toBeDefined();
+      expect(projectConfig!.workspaces).toHaveLength(1);
+      const workspace = projectConfig!.workspaces[0];
+      expect(workspace.id).toBe("project-feature-branch");
+      expect(workspace.name).toBe("feature-branch");
     });
 
     it("should use existing metadata file if present", () => {
@@ -204,14 +201,24 @@ describe("Config", () => {
         return cfg;
       });
 
-      // Get all metadata (should use existing metadata)
+      // Get all metadata (should use existing metadata and migrate to config)
       const allMetadata = config.getAllWorkspaceMetadata();
 
       expect(allMetadata).toHaveLength(1);
       const metadata = allMetadata[0];
       expect(metadata.id).toBe(workspaceId);
       expect(metadata.name).toBe("my-feature");
       expect(metadata.createdAt).toBe("2025-01-01T00:00:00.000Z");
+
+      // Verify metadata was migrated to config
+      const configData = config.loadConfigOrDefault();
+      const projectConfig = configData.projects.get(projectPath);
+      expect(projectConfig).toBeDefined();
+      expect(projectConfig!.workspaces).toHaveLength(1);
+      const workspace = projectConfig!.workspaces[0];
+      expect(workspace.id).toBe(workspaceId);
+      expect(workspace.name).toBe("my-feature");
+      expect(workspace.createdAt).toBe("2025-01-01T00:00:00.000Z");
     });
   });
 });

src/config.ts

@@ -7,10 +7,36 @@ import writeFileAtomic from "write-file-atomic";
 import type { WorkspaceMetadata } from "./types/workspace";
 import type { Secret, SecretsConfig } from "./types/secrets";
 
+/**
+ * Workspace configuration in config.json.
+ * 
+ * NEW FORMAT (preferred, used for all new workspaces):
+ * {
+ *   "path": "~/.cmux/src/project/workspace-id",  // Kept for backward compat
+ *   "id": "a1b2c3d4e5",                          // Stable workspace ID
+ *   "name": "feature-branch",                    // User-facing name
+ *   "createdAt": "2024-01-01T00:00:00Z"         // Creation timestamp
+ * }
+ * 
+ * LEGACY FORMAT (old workspaces, still supported):
+ * {
+ *   "path": "~/.cmux/src/project/workspace-id"   // Only field present
+ * }
+ * 
+ * For legacy entries, metadata is read from ~/.cmux/sessions/{workspaceId}/metadata.json
+ */
 export interface Workspace {
-  path: string; // Absolute path to workspace worktree (format: ~/.cmux/src/{projectName}/{workspaceId})
-  // NOTE: The workspace ID is the basename of this path (stable random ID like 'a1b2c3d4e5').
-  // Use config.getWorkspacePath(projectPath, workspaceId) to construct paths consistently.
+  /** Absolute path to workspace worktree - REQUIRED for backward compatibility */
+  path: string;
+  
+  /** Stable workspace ID (10 hex chars for new workspaces) - optional for legacy */
+  id?: string;
+  
+  /** User-facing workspace name - optional for legacy */
+  name?: string;
+  
+  /** ISO 8601 creation timestamp - optional for legacy */
+  createdAt?: string;
 }
 
 export interface ProjectConfig {
@@ -292,20 +318,19 @@ export class Config {
 
   /**
    * Get all workspace metadata by loading config and metadata files.
-   * Performs eager migration for legacy workspaces on startup.
-   *
-   * Migration strategy:
-   * - For each workspace in config, try to load metadata.json from session dir
-   * - If metadata exists, use it (already migrated or new workspace)
-   * - If metadata doesn't exist, this is a legacy workspace:
-   *   - Generate legacy ID from path (for backward compatibility)
-   *   - Extract name from workspace path
-   *   - Create and save metadata.json
-   *   - Create symlink if name differs from ID (new workspaces only)
+   * 
+   * NEW BEHAVIOR: Config is the primary source of truth
+   * - If workspace has id/name/createdAt in config, use those directly
+   * - If workspace only has path, fall back to reading metadata.json
+   * - Migrate old workspaces by copying metadata from files to config
+   * 
+   * This centralizes workspace metadata in config.json and eliminates the need
+   * for scattered metadata.json files (kept for backward compat with older versions).
    */
   getAllWorkspaceMetadata(): WorkspaceMetadata[] {
     const config = this.loadConfigOrDefault();
     const workspaceMetadata: WorkspaceMetadata[] = [];
+    let configModified = false;
 
     for (const [projectPath, projectConfig] of config.projects) {
       const projectName = this.getProjectName(projectPath);
@@ -316,68 +341,95 @@ export class Config {
           workspace.path.split("/").pop() ?? workspace.path.split("\\").pop() ?? "unknown";
 
         try {
-          // Try to load metadata using workspace basename as ID (works for new workspaces with stable IDs)
+          // NEW FORMAT: If workspace has metadata in config, use it directly
+          if (workspace.id && workspace.name) {
+            const metadata: WorkspaceMetadata = {
+              id: workspace.id,
+              name: workspace.name,
+              projectName,
+              projectPath,
+              createdAt: workspace.createdAt,
+            };
+            workspaceMetadata.push(metadata);
+            continue; // Skip metadata file lookup
+          }
+
+          // LEGACY FORMAT: Fall back to reading metadata.json
+          // Try workspace basename first (for new stable ID workspaces)
           let metadataPath = path.join(this.getSessionDir(workspaceBasename), "metadata.json");
+          let metadataFound = false;
 
           if (fs.existsSync(metadataPath)) {
             const data = fs.readFileSync(metadataPath, "utf-8");
             let metadata = JSON.parse(data) as WorkspaceMetadata;
 
-            // Migrate legacy metadata that's missing required fields
+            // Ensure required fields are present
             if (!metadata.name || !metadata.projectPath) {
               metadata = {
                 ...metadata,
                 name: metadata.name ?? workspaceBasename,
                 projectPath: metadata.projectPath ?? projectPath,
                 projectName: metadata.projectName ?? projectName,
               };
-              // Save migrated metadata
-              fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
             }
 
+            // Migrate to config for next load
+            workspace.id = metadata.id;
+            workspace.name = metadata.name;
+            workspace.createdAt = metadata.createdAt;
+            configModified = true;
+
             workspaceMetadata.push(metadata);
-          } else {
-            // Try legacy ID format (project-workspace)
+            metadataFound = true;
+          }
+
+          // Try legacy ID format (project-workspace)
+          if (!metadataFound) {
             const legacyId = this.generateWorkspaceId(projectPath, workspace.path);
             metadataPath = path.join(this.getSessionDir(legacyId), "metadata.json");
 
             if (fs.existsSync(metadataPath)) {
               const data = fs.readFileSync(metadataPath, "utf-8");
               let metadata = JSON.parse(data) as WorkspaceMetadata;
 
-              // Migrate legacy metadata that's missing required fields
+              // Ensure required fields are present
               if (!metadata.name || !metadata.projectPath) {
                 metadata = {
                   ...metadata,
                   name: metadata.name ?? workspaceBasename,
                   projectPath: metadata.projectPath ?? projectPath,
                   projectName: metadata.projectName ?? projectName,
                 };
-                // Save migrated metadata
-                fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
               }
 
-              workspaceMetadata.push(metadata);
-            } else {
-              // No metadata found - create it for legacy workspace
-              const metadata: WorkspaceMetadata = {
-                id: legacyId, // Use legacy ID format for backward compatibility
-                name: workspaceBasename,
-                projectName,
-                projectPath, // Add full project path
-                // No createdAt for legacy workspaces (unknown)
-              };
-
-              // Save metadata for future loads
-              const sessionDir = this.getSessionDir(legacyId);
-              if (!fs.existsSync(sessionDir)) {
-                fs.mkdirSync(sessionDir, { recursive: true });
-              }
-              fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
+              // Migrate to config for next load
+              workspace.id = metadata.id;
+              workspace.name = metadata.name;
+              workspace.createdAt = metadata.createdAt;
+              configModified = true;
 
               workspaceMetadata.push(metadata);
+              metadataFound = true;
             }
           }
+
+          // No metadata found anywhere - create basic metadata
+          if (!metadataFound) {
+            const legacyId = this.generateWorkspaceId(projectPath, workspace.path);
+            const metadata: WorkspaceMetadata = {
+              id: legacyId,
+              name: workspaceBasename,
+              projectName,
+              projectPath,
+            };
+
+            // Save to config for next load
+            workspace.id = metadata.id;
+            workspace.name = metadata.name;
+            configModified = true;
+
+            workspaceMetadata.push(metadata);
+          }
         } catch (error) {
           console.error(`Failed to load/migrate workspace metadata:`, error);
           // Fallback to basic metadata if migration fails
@@ -386,12 +438,17 @@ export class Config {
             id: legacyId,
             name: workspaceBasename,
             projectName,
-            projectPath, // Add full project path
+            projectPath,
           });
         }
       }
     }
 
+    // Save config if we migrated any workspaces
+    if (configModified) {
+      this.saveConfig(config);
+    }
+
     return workspaceMetadata;
   }
 

src/services/ipcMain.ts

@@ -224,7 +224,7 @@ export class IpcMain {
           };
           await this.aiService.saveWorkspaceMetadata(workspaceId, metadata);
 
-          // Update config to include the new workspace
+          // Update config to include the new workspace (with full metadata)
           this.config.editConfig((config) => {
             let projectConfig = config.projects.get(projectPath);
             if (!projectConfig) {
@@ -235,9 +235,12 @@ export class IpcMain {
               };
               config.projects.set(projectPath, projectConfig);
             }
-            // Add workspace to project config
+            // Add workspace to project config with full metadata
             projectConfig.workspaces.push({
               path: result.path!,
+              id: workspaceId,
+              name: branchName,
+              createdAt: metadata.createdAt,
             });
             return config;
           });
@@ -322,6 +325,20 @@ export class IpcMain {
             return Err(`Failed to save metadata: ${saveResult.error}`);
           }
 
+          // Update config with new name
+          this.config.editConfig((config) => {
+            const projectConfig = config.projects.get(projectPath);
+            if (projectConfig) {
+              const workspaceEntry = projectConfig.workspaces.find(
+                (w) => w.path === workspace.workspacePath
+              );
+              if (workspaceEntry) {
+                workspaceEntry.name = newName;
+              }
+            }
+            return config;
+          });
+
           // Emit metadata event with updated metadata (same workspace ID)
           const session = this.sessions.get(workspaceId);
           if (session) {