Migrate workspace scripts from .cmux to .mux with backward compatibility

- Export MUX_DIR_NAME and LEGACY_MUX_DIR_NAME constants
- Update script discovery to scan both .mux/scripts and .cmux/scripts
- Update script execution to try canonical path first, then legacy fallback
- Update all UI text and documentation to reference .mux/scripts
- Add tests for backward compatibility with legacy .cmux paths

Change-Id: I1904a0f559b07b1478ff6019bb2b4394a60e057a
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

docs/scripts.md

@@ -4,21 +4,21 @@ Execute custom scripts from your workspace using slash commands or let the AI Ag
 
 ## Overview
 
-Scripts are stored in `.cmux/scripts/` within each workspace. They serve two purposes:
+Scripts are stored in `.mux/scripts/` within each workspace. They serve two purposes:
 
 1. **Human Use**: Executable via `/script <name>` or `/s <name>` in chat.
 2. **Agent Use**: Automatically exposed to the AI as tools (`script_<name>`), allowing the agent to run complex workflows you define.
 
 Scripts run in the workspace directory with full access to project secrets and environment variables.
 
-**Key Point**: Scripts are workspace-specific. Each workspace has its own custom toolkit defined in `.cmux/scripts/`.
+**Key Point**: Scripts are workspace-specific. Each workspace has its own custom toolkit defined in `.mux/scripts/`.
 
 ## Creating Scripts
 
 1. **Create the scripts directory**:
 
    ```bash
-   mkdir -p .cmux/scripts
+   mkdir -p .mux/scripts
    ```
 
 2. **Add an executable script**:
@@ -39,12 +39,12 @@ Scripts run in the workspace directory with full access to project secrets and e
 3. **Make it executable**:
 
    ```bash
-   chmod +x .cmux/scripts/deploy
+   chmod +x .mux/scripts/deploy
    ```
 
 ## Agent Integration (AI Tools)
 
-Every executable script in `.cmux/scripts/` is automatically registered as a tool for the AI Agent.
+Every executable script in `.mux/scripts/` is automatically registered as a tool for the AI Agent.
 
 - **Tool Name**: `script_<name>` (e.g., `deploy` -> `script_deploy`, `run-tests` -> `script_run_tests`)
 - **Tool Description**: Taken from the script's header comment (`# Description: ...`).
@@ -185,16 +185,16 @@ curl -sL "$1"
 
 ## Script Discovery
 
-- Scripts are discovered automatically from `.cmux/scripts/` in the current workspace.
+- Scripts are discovered automatically from `.mux/scripts/` in the current workspace.
 - Discovery is cached for performance but refreshes intelligently.
 - **Sanitization**: Script names are sanitized for tool use (e.g., `my-script.sh` -> `script_my_script_sh`).
 
 ## Troubleshooting
 
 **Script not appearing in suggestions or tools?**
 
-- Ensure file is executable: `chmod +x .cmux/scripts/scriptname`
-- Verify file is in `.cmux/scripts/` directory.
+- Ensure file is executable: `chmod +x .mux/scripts/scriptname`
+- Verify file is in `.mux/scripts/` directory.
 - Check for valid description header.
 
 **Agent using script incorrectly?**

src/browser/components/ChatInputToasts.tsx

@@ -133,7 +133,7 @@ export const createCommandToast = (parsed: ParsedCommand): Toast | null => {
         id: Date.now().toString(),
         type: "error",
         title: "Script Command",
-        message: "Execute a script from .cmux/scripts/",
+        message: "Execute a script from .mux/scripts/",
         solution: (
           <>
             <SolutionLabel>Usage:</SolutionLabel>
@@ -149,7 +149,7 @@ export const createCommandToast = (parsed: ParsedCommand): Toast | null => {
             <br />
             <br />
             <SolutionLabel>Note:</SolutionLabel>
-            Scripts must be executable (chmod +x) and located in .cmux/scripts/
+            Scripts must be executable (chmod +x) and located in .mux/scripts/
           </>
         ),
       };

src/browser/utils/slashCommands/registry.ts

@@ -598,7 +598,7 @@ const newCommandDefinition: SlashCommandDefinition = {
 
 const scriptCommandDefinition: SlashCommandDefinition = {
   key: "script",
-  description: "Execute a script from .cmux/scripts/",
+  description: "Execute a script from .mux/scripts/",
   handler: ({ cleanRemainingTokens }): ParsedCommand => {
     if (cleanRemainingTokens.length === 0) {
       return { type: "script-help" };
@@ -618,7 +618,7 @@ const scriptCommandDefinition: SlashCommandDefinition = {
     if (stage === 1 && context.availableScripts) {
       const scripts = context.availableScripts.map((script) => ({
         key: script.name,
-        description: script.description ?? `Run .cmux/scripts/${script.name}`,
+        description: script.description ?? `Run .mux/scripts/${script.name}`,
       }));
 
       return filterAndMapSuggestions(scripts, partialToken, (definition) => ({

src/common/constants/paths.ts

@@ -2,8 +2,8 @@ import { existsSync, renameSync, symlinkSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
-const LEGACY_MUX_DIR_NAME = ".cmux";
-const MUX_DIR_NAME = ".mux";
+export const LEGACY_MUX_DIR_NAME = ".cmux";
+export const MUX_DIR_NAME = ".mux";
 
 /**
  * Migrate from the legacy ~/.cmux directory into ~/.mux for rebranded installs.

src/node/services/scriptRunner.ts

@@ -1,6 +1,11 @@
 import * as path from "path";
 import { type Runtime } from "@/node/runtime/Runtime";
-import { getScriptPath, getScriptsDir } from "@/utils/scripts/discovery";
+import {
+  getScriptPath,
+  getScriptsDir,
+  getLegacyScriptPath,
+  getLegacyScriptsDir,
+} from "@/utils/scripts/discovery";
 import { createBashTool } from "@/node/services/tools/bash";
 import { writeFileString, readFileString, execBuffered } from "@/node/utils/runtime/helpers";
 import { Ok, Err, type Result } from "@/common/types/result";
@@ -60,43 +65,34 @@ export async function runWorkspaceScript(
   }
 
   // Resolve real paths to handle symlinks and prevent escape
-  const scriptPath = getScriptPath(workspacePath, scriptName);
-  const scriptsDir = getScriptsDir(workspacePath);
+  const canonicalScriptPath = getScriptPath(workspacePath, scriptName);
+  const canonicalScriptsDir = getScriptsDir(workspacePath);
+
+  const legacyScriptPath = getLegacyScriptPath(workspacePath, scriptName);
+  const legacyScriptsDir = getLegacyScriptsDir(workspacePath);
 
   let resolvedScriptPath: string;
   let resolvedScriptsDir: string;
 
   try {
-    // Use runtime.resolvePath (which should behave like realpath) if available,
-    // otherwise rely on the runtime-specific normalization.
-    // Ideally, we want `realpath` behavior here.
-    // Since the Runtime interface doesn't strictly expose `realpath`, we'll rely on
-    // the filesystem (via runtime.exec or similar) or assume normalizePath+standard checks are mostly sufficient.
-    // HOWEVER, for local runtime we can use fs.realpath. For SSH, we might need a command.
-    // To keep it simple and robust within the existing abstractions:
-    // We will use the runtime to resolve the path if possible, but `runtime.resolvePath`
-    // is documented to expand tildes, not necessarily resolve symlinks (though it often does).
-
-    // BUT, to address the specific review concern about symlinks:
-    // We should try to get the canonical path.
-    // Note: checking containment purely by string path on un-resolved paths is weak against symlinks.
-
-    // Strategy:
-    // 1. Get the script path (constructed from workspace + script name).
-    // 2. Get the scripts dir.
-    // 3. Ask runtime to resolve them to absolute, canonical paths (resolving symlinks).
-    //    (If runtime doesn't support explicit symlink resolution in its API, we might be limited).
-    //    The review implies we *should* do this.
-    //    Let's add a helper or use `runtime.resolvePath` which claims to resolve to "absolute, canonical form".
-
-    resolvedScriptPath = await runtime.resolvePath(scriptPath);
-    resolvedScriptsDir = await runtime.resolvePath(scriptsDir);
+    // Try canonical path first
+    const candidatePath = await runtime.resolvePath(canonicalScriptPath);
+    await runtime.stat(candidatePath); // Throws if not exists
+    resolvedScriptPath = candidatePath;
+    resolvedScriptsDir = await runtime.resolvePath(canonicalScriptsDir);
   } catch {
-    // If we can't resolve paths (e.g. file doesn't exist), we can't verify containment securely.
-    // But we already established the script *must* exist in step 2 (which we moved up or will do).
-    // Actually step 2 is below. Let's do existence check + resolution together or accept that
-    // resolution failure implies non-existence.
-    return Err(`Script not found or inaccessible: ${scriptName}`);
+    try {
+      // Try legacy path fallback
+      const candidateLegacyPath = await runtime.resolvePath(legacyScriptPath);
+      await runtime.stat(candidateLegacyPath); // Throws if not exists
+      resolvedScriptPath = candidateLegacyPath;
+      resolvedScriptsDir = await runtime.resolvePath(legacyScriptsDir);
+    } catch {
+      // Both missing. Default to canonical so the error message later (in step 2)
+      // correctly reports the canonical path as missing.
+      resolvedScriptPath = await runtime.resolvePath(canonicalScriptPath);
+      resolvedScriptsDir = await runtime.resolvePath(canonicalScriptsDir);
+    }
   }
 
   // Use runtime-aware normalization on the RESOLVED paths
@@ -115,11 +111,11 @@ export async function runWorkspaceScript(
   try {
     const stat = await runtime.stat(resolvedScriptPath);
     if (stat.isDirectory) {
-      return Err(`Script not found: .cmux/scripts/${scriptName}`);
+      return Err(`Script is a directory: ${scriptName}`);
     }
   } catch {
     return Err(
-      `Script not found: .cmux/scripts/${scriptName}. Create the script in your workspace and make it executable (chmod +x).`
+      `Script not found: .mux/scripts/${scriptName}. Create the script in your workspace and make it executable (chmod +x).`
     );
   }
 

src/utils/scripts/discovery.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "bun:test";
 import type { Runtime } from "@/node/runtime/Runtime";
-import { listScripts, getScriptPath } from "./discovery";
+import { listScripts, getScriptPath, getLegacyScriptPath } from "./discovery";
 import * as path from "path";
 
 // Mock runtime for testing
@@ -215,22 +215,60 @@ describe("listScripts", () => {
       },
     ]);
   });
+
+  test("deduplicates scripts found in both locations (prefers canonical)", async () => {
+    // Construct output where the same script appears twice
+    // Since our implementation scans canonical first, the first occurrence is canonical
+    const output = [
+      `${separator}dup-script`,
+      "IS_EXECUTABLE:1",
+      "#!/bin/bash",
+      "# Description: Canonical version",
+      "echo canonical",
+      "",
+      `${separator}dup-script`,
+      "IS_EXECUTABLE:1",
+      "#!/bin/bash",
+      "# Description: Legacy version",
+      "echo legacy",
+    ].join("\n");
+
+    const runtime = createMockRuntime(new Map([[separator, { stdout: output, exitCode: 0 }]]));
+
+    const scripts = await listScripts(runtime, "/test/workspace/dup");
+    expect(scripts).toEqual([
+      {
+        name: "dup-script",
+        description: "Canonical version",
+        isExecutable: true,
+      },
+    ]);
+  });
 });
 
 describe("getScriptPath", () => {
   test("uses POSIX separators for POSIX workspace paths", () => {
     const workspacePath = "/home/user/workspace";
     const scriptName = "test.sh";
     // Explicitly check for forward slashes regardless of host OS
-    const expected = "/home/user/workspace/.cmux/scripts/test.sh";
+    const expected = "/home/user/workspace/.mux/scripts/test.sh";
     expect(getScriptPath(workspacePath, scriptName)).toBe(expected);
   });
 
   test("uses host separators (default) for Windows workspace paths", () => {
     const workspacePath = "C:\\Users\\user\\workspace";
     const scriptName = "test.bat";
     // Should use path.join, which depends on the host OS running the test
-    const expected = path.join(workspacePath, ".cmux", "scripts", scriptName);
+    const expected = path.join(workspacePath, ".mux", "scripts", scriptName);
     expect(getScriptPath(workspacePath, scriptName)).toBe(expected);
   });
 });
+
+describe("getLegacyScriptPath", () => {
+  test("returns path in .cmux", () => {
+    const workspacePath = "/home/user/workspace";
+    const scriptName = "test.sh";
+    const expected = "/home/user/workspace/.cmux/scripts/test.sh";
+    expect(getLegacyScriptPath(workspacePath, scriptName)).toBe(expected);
+  });
+});