feat: add external terminal support with cross-platform detection (#565)

* feat(platform): add cross-platform openInTerminal utility

Add utility function to open a terminal in a specified directory:
- macOS: Uses Terminal.app via AppleScript
- Windows: Tries Windows Terminal, falls back to cmd
- Linux: Tries common terminal emulators (gnome-terminal,
  konsole, xfce4-terminal, xterm, x-terminal-emulator)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(server): add open-in-terminal endpoint

Add POST /open-in-terminal endpoint to open a system terminal in the
worktree directory using the cross-platform openInTerminal utility.

The endpoint validates that worktreePath is provided and is an
absolute path for security.

Extracted from PR #558.

* feat(ui): add Open in Terminal action to worktree dropdown

Add "Open in Terminal" option to the worktree actions dropdown menu.
This opens the system terminal in the worktree directory.

Changes:
- Add openInTerminal method to http-api-client
- Add Terminal icon and menu item to worktree-actions-dropdown
- Add onOpenInTerminal prop to WorktreeTab component
- Add handleOpenInTerminal handler to use-worktree-actions hook
- Wire up handler in worktree-panel for both mobile and desktop views

Extracted from PR #558.

* fix(ui): open in terminal navigates to Automaker terminal view

Instead of opening the system terminal, the "Open in Terminal" action
now opens Automaker's built-in terminal with the worktree directory:

- Add pendingTerminalCwd state to app store
- Update use-worktree-actions to set pending cwd and navigate to /terminal
- Add effect in terminal-view to create session with pending cwd

This matches the original PR #558 behavior.

* feat(ui): add terminal open mode setting (new tab vs split)

Add a setting to choose how "Open in Terminal" behaves:
- New Tab: Creates a new tab named after the branch (default)
- Split: Adds to current tab as a split view

Changes:
- Add openTerminalMode setting to terminal state ('newTab' | 'split')
- Update terminal-view to respect the setting
- Add UI in Terminal Settings to toggle the behavior
- Rename pendingTerminalCwd to pendingTerminal with branch name

The new tab mode names tabs after the branch for easy identification.
The split mode is useful for comparing terminals side by side.

* feat(ui): display branch name in terminal header with git icon

- Move branch name display from tab name to terminal header
- Show full branch name (no truncation) with GitBranch icon
- Display branch name for both 'new tab' and 'split' modes
- Persist openTerminalMode setting to server and include in import/export
- Update settings dropdown to simplified "New Tab" label

* feat: add external terminal support with cross-platform detection

Add support for opening worktree directories in external terminals
(iTerm2, Warp, Ghostty, System Terminal, etc.) while retaining the
integrated terminal as the default option.

Changes:
- Add terminal detection for macOS, Windows, and Linux
- Add "Open in Terminal" split-button in worktree dropdown
- Add external terminal selection in Settings > Terminal
- Add default open mode setting (new tab vs split)
- Display branch name in terminal panel header
- Support 20+ terminals across platforms

Part of #558, Closes #550

* fix: address PR review comments

- Add nonce parameter to terminal navigation to allow reopening same
  worktree multiple times
- Fix shell path escaping in editor.ts using single-quote wrapper
- Add validatePathParams middleware to open-in-external-terminal route
- Remove redundant validation block from createOpenInExternalTerminalHandler
- Remove unused pendingTerminal state and setPendingTerminal action
- Remove unused getTerminalInfo function from editor.ts

* fix: address PR review security and validation issues

- Add runtime type check for worktreePath in open-in-terminal handler
- Fix Windows Terminal detection using commandExists before spawn
- Fix xterm shell injection by using sh -c with escapeShellArg
- Use loose equality for null/undefined in useEffectiveDefaultTerminal
- Consolidate duplicate imports from open-in-terminal.js

* chore: update package-lock.json

* fix: use response.json() to prevent disposal race condition in E2E test

Replace response.body() with response.json() in open-existing-project.spec.ts
to fix the "Response has been disposed" error. This matches the pattern used
in other test files.

* Revert "fix: use response.json() to prevent disposal race condition in E2E test"

This reverts commit 36bdf8c24a.

* fix: address PR review feedback for terminal feature

- Add explicit validation for worktreePath in createOpenInExternalTerminalHandler
- Add aria-label to refresh button in terminal settings for accessibility
- Only show "no terminals" message when not refreshing
- Reset initialCwdHandledRef on failure to allow retries
- Use z.coerce.number() for nonce URL param to handle string coercion
- Preserve branchName when creating layout for empty tab
- Update getDefaultTerminal return type to allow null result

---------

Co-authored-by: Kacper <kacperlachowiczwp.pl@wp.pl>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

libs/platform/src/editor.ts

@@ -19,6 +19,15 @@ const execFileAsync = promisify(execFile);
 const isWindows = process.platform === 'win32';
 const isMac = process.platform === 'darwin';
 
+/**
+ * Escape a string for safe use in shell commands
+ * Handles paths with spaces, special characters, etc.
+ */
+function escapeShellArg(arg: string): string {
+  // Escape single quotes by ending the quoted string, adding escaped quote, and starting new quoted string
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
 // Cache with TTL for editor detection
 let cachedEditors: EditorInfo[] | null = null;
 let cacheTimestamp: number = 0;
@@ -341,3 +350,100 @@ export async function openInFileManager(targetPath: string): Promise<{ editorNam
   await execFileAsync(fileManager.command, [targetPath]);
   return { editorName: fileManager.name };
 }
+
+/**
+ * Open a terminal in the specified directory
+ *
+ * Handles cross-platform differences:
+ * - On macOS, uses Terminal.app via 'open -a Terminal' or AppleScript for directory
+ * - On Windows, uses Windows Terminal (wt) or falls back to cmd
+ * - On Linux, uses x-terminal-emulator or common terminal emulators
+ *
+ * @param targetPath - The directory path to open the terminal in
+ * @returns Promise that resolves with terminal info when launched, rejects on error
+ */
+export async function openInTerminal(targetPath: string): Promise<{ terminalName: string }> {
+  if (isMac) {
+    // Use AppleScript to open Terminal.app in the specified directory
+    const script = `
+      tell application "Terminal"
+        do script "cd ${escapeShellArg(targetPath)}"
+        activate
+      end tell
+    `;
+    await execFileAsync('osascript', ['-e', script]);
+    return { terminalName: 'Terminal' };
+  } else if (isWindows) {
+    // Try Windows Terminal first - check if it exists before trying to spawn
+    const hasWindowsTerminal = await commandExists('wt');
+    if (hasWindowsTerminal) {
+      return await new Promise((resolve, reject) => {
+        const child: ChildProcess = spawn('wt', ['-d', targetPath], {
+          shell: true,
+          stdio: 'ignore',
+          detached: true,
+        });
+        child.unref();
+
+        child.on('error', (err) => {
+          reject(err);
+        });
+
+        setTimeout(() => resolve({ terminalName: 'Windows Terminal' }), 100);
+      });
+    }
+    // Fall back to cmd
+    return await new Promise((resolve, reject) => {
+      const child: ChildProcess = spawn(
+        'cmd',
+        ['/c', 'start', 'cmd', '/k', `cd /d "${targetPath}"`],
+        {
+          shell: true,
+          stdio: 'ignore',
+          detached: true,
+        }
+      );
+      child.unref();
+
+      child.on('error', (err) => {
+        reject(err);
+      });
+
+      setTimeout(() => resolve({ terminalName: 'Command Prompt' }), 100);
+    });
+  } else {
+    // Linux: Try common terminal emulators in order
+    const terminals = [
+      {
+        name: 'GNOME Terminal',
+        command: 'gnome-terminal',
+        args: ['--working-directory', targetPath],
+      },
+      { name: 'Konsole', command: 'konsole', args: ['--workdir', targetPath] },
+      {
+        name: 'xfce4-terminal',
+        command: 'xfce4-terminal',
+        args: ['--working-directory', targetPath],
+      },
+      {
+        name: 'xterm',
+        command: 'xterm',
+        args: ['-e', 'sh', '-c', `cd ${escapeShellArg(targetPath)} && $SHELL`],
+      },
+      {
+        name: 'x-terminal-emulator',
+        command: 'x-terminal-emulator',
+        args: ['--working-directory', targetPath],
+      },
+    ];
+
+    for (const terminal of terminals) {
+      if (await commandExists(terminal.command)) {
+        await execFileAsync(terminal.command, terminal.args);
+        return { terminalName: terminal.name };
+      }
+    }
+
+    throw new Error('No terminal emulator found');
+  }
+}