vibe-forge 0.4.0 → 0.8.1

package/bin/lib/terminal.js

@@ -1,446 +1,452 @@
-#!/usr/bin/env node
-/**
- * Vibe Forge - Cross-Platform Terminal Detection & Spawning
- *
- * Detects available terminals and spawns new tabs/windows for worker agents.
- *
- * Supported terminals:
- *   Windows: Windows Terminal, PowerShell
- *   macOS:   Terminal.app, iTerm2, Kitty
- *   Linux:   gnome-terminal, konsole, kitty, xterm
- *
- * Usage:
- *   node terminal.js detect              List available terminals
- *   node terminal.js spawn <terminal> <title> <command>
- */
-
-const { execSync, spawn } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-// =============================================================================
-// Terminal Definitions
-// =============================================================================
-
-const TERMINALS = {
-  // Windows
-  'windows-terminal': {
-    name: 'Windows Terminal',
-    platform: 'win32',
-    detect: () => commandExists('wt') || commandExists('wt.exe'),
-    spawn: (title, command, opts) => spawnWindowsTerminal(title, command, opts),
-  },
-  'powershell': {
-    name: 'PowerShell',
-    platform: 'win32',
-    detect: () => commandExists('pwsh') || commandExists('powershell'),
-    spawn: (title, command, opts) => spawnPowerShell(title, command, opts),
-  },
-
-  // macOS
-  'terminal-app': {
-    name: 'Terminal.app',
-    platform: 'darwin',
-    detect: () => fs.existsSync('/System/Applications/Utilities/Terminal.app'),
-    spawn: (title, command, opts) => spawnTerminalApp(title, command, opts),
-  },
-  'iterm2': {
-    name: 'iTerm2',
-    platform: 'darwin',
-    detect: () => fs.existsSync('/Applications/iTerm.app'),
-    spawn: (title, command, opts) => spawnITerm2(title, command, opts),
-  },
-  'kitty-mac': {
-    name: 'Kitty',
-    platform: 'darwin',
-    detect: () => commandExists('kitty') || fs.existsSync('/Applications/kitty.app'),
-    spawn: (title, command, opts) => spawnKitty(title, command, opts),
-  },
-
-  // Linux
-  'gnome-terminal': {
-    name: 'GNOME Terminal',
-    platform: 'linux',
-    detect: () => commandExists('gnome-terminal'),
-    spawn: (title, command, opts) => spawnGnomeTerminal(title, command, opts),
-  },
-  'konsole': {
-    name: 'Konsole',
-    platform: 'linux',
-    detect: () => commandExists('konsole'),
-    spawn: (title, command, opts) => spawnKonsole(title, command, opts),
-  },
-  'kitty-linux': {
-    name: 'Kitty',
-    platform: 'linux',
-    detect: () => commandExists('kitty'),
-    spawn: (title, command, opts) => spawnKitty(title, command, opts),
-  },
-  'xterm': {
-    name: 'XTerm',
-    platform: 'linux',
-    detect: () => commandExists('xterm'),
-    spawn: (title, command, opts) => spawnXterm(title, command, opts),
-  },
-};
-
-// =============================================================================
-// Detection Helpers
-// =============================================================================
-
-function commandExists(cmd) {
-  try {
-    if (os.platform() === 'win32') {
-      execSync(`where ${cmd}`, { stdio: 'pipe' });
-    } else {
-      execSync(`which ${cmd}`, { stdio: 'pipe' });
-    }
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function getPlatform() {
-  const p = os.platform();
-  if (p === 'win32') return 'win32';
-  if (p === 'darwin') return 'darwin';
-  return 'linux'; // Treat all other Unix-likes as Linux
-}
-
-function detectTerminals() {
-  const platform = getPlatform();
-  const available = [];
-
-  for (const [id, terminal] of Object.entries(TERMINALS)) {
-    if (terminal.platform === platform) {
-      try {
-        if (terminal.detect()) {
-          available.push({
-            id,
-            name: terminal.name,
-            platform: terminal.platform,
-          });
-        }
-      } catch {
-        // Detection failed, skip this terminal
-      }
-    }
-  }
-
-  return available;
-}
-
-function getBestTerminal() {
-  const available = detectTerminals();
-  return available.length > 0 ? available[0] : null;
-}
-
-// =============================================================================
-// Spawn Functions - Windows
-// =============================================================================
-
-function spawnWindowsTerminal(title, command, opts = {}) {
-  const { cwd, tabColor } = opts;
-
-  // Build wt arguments
-  const args = ['-w', '0', 'new-tab', '--title', title];
-
-  if (tabColor) {
-    args.push('--tabColor', tabColor);
-  }
-
-  // Determine bash path
-  const bashPath = findGitBash();
-
-  if (bashPath) {
-    args.push(bashPath, '-c', command);
-  } else {
-    args.push('bash', '-c', command);
-  }
-
-  const child = spawn('wt', args, {
-    detached: true,
-    stdio: 'ignore',
-    cwd: cwd || process.cwd(),
-    shell: true,
-  });
-
-  child.unref();
-  return { success: true, terminal: 'windows-terminal' };
-}
-
-function spawnPowerShell(title, command, opts = {}) {
-  const { cwd } = opts;
-
-  // PowerShell: Start-Process to open new window
-  // We wrap in bash since the command expects bash
-  const bashPath = findGitBash();
-  const bashCmd = bashPath ? `& '${bashPath}' -c '${command.replace(/'/g, "''")}'` : `bash -c '${command.replace(/'/g, "''")}'`;
-
-  const psCommand = `Start-Process pwsh -ArgumentList '-NoExit', '-Command', '${bashCmd.replace(/'/g, "''")}'`;
-
-  const child = spawn('pwsh', ['-Command', psCommand], {
-    detached: true,
-    stdio: 'ignore',
-    cwd: cwd || process.cwd(),
-    shell: true,
-  });
-
-  child.unref();
-  return { success: true, terminal: 'powershell' };
-}
-
-function findGitBash() {
-  if (os.platform() !== 'win32') return null;
-
-  const paths = [
-    'C:\\Program Files\\Git\\bin\\bash.exe',
-    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
-    path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Git', 'bin', 'bash.exe'),
-  ];
-
-  for (const p of paths) {
-    if (fs.existsSync(p)) {
-      return p;
-    }
-  }
-
-  // Try to find via where command
-  try {
-    const gitPath = execSync('where git', { stdio: 'pipe' }).toString().trim().split('\n')[0];
-    const gitDir = path.dirname(path.dirname(gitPath));
-    const bashPath = path.join(gitDir, 'bin', 'bash.exe');
-    if (fs.existsSync(bashPath)) {
-      return bashPath;
-    }
-  } catch {
-    // Ignore
-  }
-
-  return null;
-}
-
-// =============================================================================
-// Spawn Functions - macOS
-// =============================================================================
-
-function spawnTerminalApp(title, command, opts = {}) {
-  const { cwd } = opts;
-  const workDir = cwd || process.cwd();
-
-  // AppleScript to open new Terminal tab
-  const script = `
-    tell application "Terminal"
-      activate
-      do script "cd '${workDir.replace(/'/g, "'\\''")}' && ${command.replace(/"/g, '\\"')}"
-      set custom title of front window to "${title}"
-    end tell
-  `;
-
-  try {
-    execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, { stdio: 'pipe' });
-    return { success: true, terminal: 'terminal-app' };
-  } catch (err) {
-    return { success: false, error: err.message, terminal: 'terminal-app' };
-  }
-}
-
-function spawnITerm2(title, command, opts = {}) {
-  const { cwd } = opts;
-  const workDir = cwd || process.cwd();
-
-  // AppleScript for iTerm2
-  const script = `
-    tell application "iTerm2"
-      activate
-      tell current window
-        create tab with default profile
-        tell current session
-          write text "cd '${workDir.replace(/'/g, "'\\''")}' && ${command.replace(/"/g, '\\"')}"
-          set name to "${title}"
-        end tell
-      end tell
-    end tell
-  `;
-
-  try {
-    execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, { stdio: 'pipe' });
-    return { success: true, terminal: 'iterm2' };
-  } catch (err) {
-    return { success: false, error: err.message, terminal: 'iterm2' };
-  }
-}
-
-// =============================================================================
-// Spawn Functions - Linux & Cross-Platform
-// =============================================================================
-
-function spawnGnomeTerminal(title, command, opts = {}) {
-  const { cwd } = opts;
-
-  const child = spawn('gnome-terminal', [
-    '--tab',
-    '--title', title,
-    '--', 'bash', '-c', `${command}; exec bash`
-  ], {
-    detached: true,
-    stdio: 'ignore',
-    cwd: cwd || process.cwd(),
-  });
-
-  child.unref();
-  return { success: true, terminal: 'gnome-terminal' };
-}
-
-function spawnKonsole(title, command, opts = {}) {
-  const { cwd } = opts;
-
-  const child = spawn('konsole', [
-    '--new-tab',
-    '-p', `tabtitle=${title}`,
-    '-e', 'bash', '-c', `${command}; exec bash`
-  ], {
-    detached: true,
-    stdio: 'ignore',
-    cwd: cwd || process.cwd(),
-  });
-
-  child.unref();
-  return { success: true, terminal: 'konsole' };
-}
-
-function spawnKitty(title, command, opts = {}) {
-  const { cwd } = opts;
-
-  // Kitty can work in single-instance mode with remote control
-  // or spawn new windows
-  const child = spawn('kitty', [
-    '--title', title,
-    '--directory', cwd || process.cwd(),
-    'bash', '-c', `${command}; exec bash`
-  ], {
-    detached: true,
-    stdio: 'ignore',
-  });
-
-  child.unref();
-  return { success: true, terminal: 'kitty' };
-}
-
-function spawnXterm(title, command, opts = {}) {
-  const { cwd } = opts;
-
-  const child = spawn('xterm', [
-    '-T', title,
-    '-e', 'bash', '-c', `cd '${cwd || process.cwd()}' && ${command}; exec bash`
-  ], {
-    detached: true,
-    stdio: 'ignore',
-  });
-
-  child.unref();
-  return { success: true, terminal: 'xterm' };
-}
-
-// =============================================================================
-// Main Spawn Function
-// =============================================================================
-
-function spawnTerminal(terminalId, title, command, opts = {}) {
-  const terminal = TERMINALS[terminalId];
-
-  if (!terminal) {
-    return { success: false, error: `Unknown terminal: ${terminalId}` };
-  }
-
-  try {
-    return terminal.spawn(title, command, opts);
-  } catch (err) {
-    return { success: false, error: err.message, terminal: terminalId };
-  }
-}
-
-// =============================================================================
-// CLI Interface
-// =============================================================================
-
-function main() {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  switch (command) {
-    case 'detect': {
-      const terminals = detectTerminals();
-      console.log(JSON.stringify({ platform: getPlatform(), terminals }, null, 2));
-      break;
-    }
-
-    case 'best': {
-      const best = getBestTerminal();
-      if (best) {
-        console.log(JSON.stringify(best, null, 2));
-      } else {
-        console.log(JSON.stringify({ error: 'No supported terminal found' }));
-        process.exit(1);
-      }
-      break;
-    }
-
-    case 'spawn': {
-      const terminalId = args[1];
-      const title = args[2];
-      const cmd = args[3];
-      const cwd = args[4];
-      const tabColor = args[5];
-
-      if (!terminalId || !title || !cmd) {
-        console.error('Usage: terminal.js spawn <terminal-id> <title> <command> [cwd] [tabColor]');
-        process.exit(1);
-      }
-
-      const result = spawnTerminal(terminalId, title, cmd, { cwd, tabColor });
-      console.log(JSON.stringify(result));
-      process.exit(result.success ? 0 : 1);
-      break;
-    }
-
-    case 'list': {
-      const platform = getPlatform();
-      const all = Object.entries(TERMINALS)
-        .filter(([, t]) => t.platform === platform)
-        .map(([id, t]) => ({ id, name: t.name }));
-      console.log(JSON.stringify({ platform, terminals: all }, null, 2));
-      break;
-    }
-
-    default:
-      console.log(`Vibe Forge Terminal Utility
-
-Usage:
-  node terminal.js detect         Detect available terminals (JSON)
-  node terminal.js best           Get best available terminal (JSON)
-  node terminal.js list           List all terminals for this platform
-  node terminal.js spawn <id> <title> <command> [cwd] [tabColor]
-
-Examples:
-  node terminal.js detect
-  node terminal.js spawn windows-terminal "Anvil" "claude --chat"
-`);
-  }
-}
-
-// Export for use as module
-module.exports = {
-  detectTerminals,
-  getBestTerminal,
-  spawnTerminal,
-  TERMINALS,
-  getPlatform,
-};
-
-// Run CLI if executed directly
-if (require.main === module) {
-  main();
-}
+#!/usr/bin/env node
+/**
+ * Vibe Forge - Cross-Platform Terminal Detection & Spawning
+ *
+ * Detects available terminals and spawns new tabs/windows for worker agents.
+ *
+ * Supported terminals:
+ *   Windows: Windows Terminal, PowerShell
+ *   macOS:   Terminal.app, iTerm2, Kitty
+ *   Linux:   gnome-terminal, konsole, kitty, xterm
+ *
+ * Usage:
+ *   node terminal.js detect              List available terminals
+ *   node terminal.js spawn <terminal> <title> <command>
+ */
+
+const { execSync, spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// =============================================================================
+// Terminal Definitions
+// =============================================================================
+
+const TERMINALS = {
+  // Windows
+  'windows-terminal': {
+    name: 'Windows Terminal',
+    platform: 'win32',
+    detect: () => commandExists('wt') || commandExists('wt.exe'),
+    spawn: (title, command, opts) => spawnWindowsTerminal(title, command, opts),
+  },
+  'powershell': {
+    name: 'PowerShell',
+    platform: 'win32',
+    detect: () => commandExists('pwsh') || commandExists('powershell'),
+    spawn: (title, command, opts) => spawnPowerShell(title, command, opts),
+  },
+
+  // macOS
+  'terminal-app': {
+    name: 'Terminal.app',
+    platform: 'darwin',
+    detect: () => fs.existsSync('/System/Applications/Utilities/Terminal.app'),
+    spawn: (title, command, opts) => spawnTerminalApp(title, command, opts),
+  },
+  'iterm2': {
+    name: 'iTerm2',
+    platform: 'darwin',
+    detect: () => fs.existsSync('/Applications/iTerm.app'),
+    spawn: (title, command, opts) => spawnITerm2(title, command, opts),
+  },
+  'kitty-mac': {
+    name: 'Kitty',
+    platform: 'darwin',
+    detect: () => commandExists('kitty') || fs.existsSync('/Applications/kitty.app'),
+    spawn: (title, command, opts) => spawnKitty(title, command, opts),
+  },
+
+  // Linux
+  'gnome-terminal': {
+    name: 'GNOME Terminal',
+    platform: 'linux',
+    detect: () => commandExists('gnome-terminal'),
+    spawn: (title, command, opts) => spawnGnomeTerminal(title, command, opts),
+  },
+  'konsole': {
+    name: 'Konsole',
+    platform: 'linux',
+    detect: () => commandExists('konsole'),
+    spawn: (title, command, opts) => spawnKonsole(title, command, opts),
+  },
+  'kitty-linux': {
+    name: 'Kitty',
+    platform: 'linux',
+    detect: () => commandExists('kitty'),
+    spawn: (title, command, opts) => spawnKitty(title, command, opts),
+  },
+  'xterm': {
+    name: 'XTerm',
+    platform: 'linux',
+    detect: () => commandExists('xterm'),
+    spawn: (title, command, opts) => spawnXterm(title, command, opts),
+  },
+};
+
+// =============================================================================
+// Detection Helpers
+// =============================================================================
+
+function commandExists(cmd) {
+  try {
+    if (os.platform() === 'win32') {
+      execSync(`where ${cmd}`, { stdio: 'pipe' });
+    } else {
+      execSync(`which ${cmd}`, { stdio: 'pipe' });
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getPlatform() {
+  const p = os.platform();
+  if (p === 'win32') return 'win32';
+  if (p === 'darwin') return 'darwin';
+  return 'linux'; // Treat all other Unix-likes as Linux
+}
+
+function detectTerminals() {
+  const platform = getPlatform();
+  const available = [];
+
+  for (const [id, terminal] of Object.entries(TERMINALS)) {
+    if (terminal.platform === platform) {
+      try {
+        if (terminal.detect()) {
+          available.push({
+            id,
+            name: terminal.name,
+            platform: terminal.platform,
+          });
+        }
+      } catch {
+        // Detection failed, skip this terminal
+      }
+    }
+  }
+
+  return available;
+}
+
+function getBestTerminal() {
+  const available = detectTerminals();
+  return available.length > 0 ? available[0] : null;
+}
+
+// =============================================================================
+// Spawn Functions - Windows
+// =============================================================================
+
+function spawnWindowsTerminal(title, command, opts = {}) {
+  const { cwd, tabColor, suppressApplicationTitle = true } = opts;
+
+  // Build wt arguments
+  const args = ['-w', '0', 'new-tab', '--title', title];
+
+  // FORGE-9: Prevent the spawned process from overwriting the tab title
+  if (suppressApplicationTitle) {
+    args.push('--suppressApplicationTitle');
+  }
+
+  if (tabColor) {
+    args.push('--tabColor', tabColor);
+  }
+
+  // Determine bash path
+  const bashPath = findGitBash();
+
+  if (bashPath) {
+    args.push(bashPath, '-c', command);
+  } else {
+    args.push('bash', '-c', command);
+  }
+
+  const child = spawn('wt', args, {
+    detached: true,
+    stdio: 'ignore',
+    cwd: cwd || process.cwd(),
+    shell: true,
+  });
+
+  child.unref();
+  return { success: true, terminal: 'windows-terminal' };
+}
+
+function spawnPowerShell(title, command, opts = {}) {
+  const { cwd } = opts;
+
+  // PowerShell: Start-Process to open new window
+  // We wrap in bash since the command expects bash
+  const bashPath = findGitBash();
+  const bashCmd = bashPath ? `& '${bashPath}' -c '${command.replace(/'/g, "''")}'` : `bash -c '${command.replace(/'/g, "''")}'`;
+
+  const psCommand = `Start-Process pwsh -ArgumentList '-NoExit', '-Command', '${bashCmd.replace(/'/g, "''")}'`;
+
+  const child = spawn('pwsh', ['-Command', psCommand], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: cwd || process.cwd(),
+    shell: true,
+  });
+
+  child.unref();
+  return { success: true, terminal: 'powershell' };
+}
+
+function findGitBash() {
+  if (os.platform() !== 'win32') return null;
+
+  const paths = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+    path.join(process.env.LOCALAPPDATA || '', 'Programs', 'Git', 'bin', 'bash.exe'),
+  ];
+
+  for (const p of paths) {
+    if (fs.existsSync(p)) {
+      return p;
+    }
+  }
+
+  // Try to find via where command
+  try {
+    const gitPath = execSync('where git', { stdio: 'pipe' }).toString().trim().split('\n')[0];
+    const gitDir = path.dirname(path.dirname(gitPath));
+    const bashPath = path.join(gitDir, 'bin', 'bash.exe');
+    if (fs.existsSync(bashPath)) {
+      return bashPath;
+    }
+  } catch {
+    // Ignore
+  }
+
+  return null;
+}
+
+// =============================================================================
+// Spawn Functions - macOS
+// =============================================================================
+
+function spawnTerminalApp(title, command, opts = {}) {
+  const { cwd } = opts;
+  const workDir = cwd || process.cwd();
+
+  // AppleScript to open new Terminal tab
+  const script = `
+    tell application "Terminal"
+      activate
+      do script "cd '${workDir.replace(/'/g, "'\\''")}' && ${command.replace(/"/g, '\\"')}"
+      set custom title of front window to "${title}"
+    end tell
+  `;
+
+  try {
+    execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, { stdio: 'pipe' });
+    return { success: true, terminal: 'terminal-app' };
+  } catch (err) {
+    return { success: false, error: err.message, terminal: 'terminal-app' };
+  }
+}
+
+function spawnITerm2(title, command, opts = {}) {
+  const { cwd } = opts;
+  const workDir = cwd || process.cwd();
+
+  // AppleScript for iTerm2
+  const script = `
+    tell application "iTerm2"
+      activate
+      tell current window
+        create tab with default profile
+        tell current session
+          write text "cd '${workDir.replace(/'/g, "'\\''")}' && ${command.replace(/"/g, '\\"')}"
+          set name to "${title}"
+        end tell
+      end tell
+    end tell
+  `;
+
+  try {
+    execSync(`osascript -e '${script.replace(/'/g, "'\\''")}'`, { stdio: 'pipe' });
+    return { success: true, terminal: 'iterm2' };
+  } catch (err) {
+    return { success: false, error: err.message, terminal: 'iterm2' };
+  }
+}
+
+// =============================================================================
+// Spawn Functions - Linux & Cross-Platform
+// =============================================================================
+
+function spawnGnomeTerminal(title, command, opts = {}) {
+  const { cwd } = opts;
+
+  const child = spawn('gnome-terminal', [
+    '--tab',
+    '--title', title,
+    '--', 'bash', '-c', `${command}; exec bash`
+  ], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: cwd || process.cwd(),
+  });
+
+  child.unref();
+  return { success: true, terminal: 'gnome-terminal' };
+}
+
+function spawnKonsole(title, command, opts = {}) {
+  const { cwd } = opts;
+
+  const child = spawn('konsole', [
+    '--new-tab',
+    '-p', `tabtitle=${title}`,
+    '-e', 'bash', '-c', `${command}; exec bash`
+  ], {
+    detached: true,
+    stdio: 'ignore',
+    cwd: cwd || process.cwd(),
+  });
+
+  child.unref();
+  return { success: true, terminal: 'konsole' };
+}
+
+function spawnKitty(title, command, opts = {}) {
+  const { cwd } = opts;
+
+  // Kitty can work in single-instance mode with remote control
+  // or spawn new windows
+  const child = spawn('kitty', [
+    '--title', title,
+    '--directory', cwd || process.cwd(),
+    'bash', '-c', `${command}; exec bash`
+  ], {
+    detached: true,
+    stdio: 'ignore',
+  });
+
+  child.unref();
+  return { success: true, terminal: 'kitty' };
+}
+
+function spawnXterm(title, command, opts = {}) {
+  const { cwd } = opts;
+
+  const child = spawn('xterm', [
+    '-T', title,
+    '-e', 'bash', '-c', `cd '${cwd || process.cwd()}' && ${command}; exec bash`
+  ], {
+    detached: true,
+    stdio: 'ignore',
+  });
+
+  child.unref();
+  return { success: true, terminal: 'xterm' };
+}
+
+// =============================================================================
+// Main Spawn Function
+// =============================================================================
+
+function spawnTerminal(terminalId, title, command, opts = {}) {
+  const terminal = TERMINALS[terminalId];
+
+  if (!terminal) {
+    return { success: false, error: `Unknown terminal: ${terminalId}` };
+  }
+
+  try {
+    return terminal.spawn(title, command, opts);
+  } catch (err) {
+    return { success: false, error: err.message, terminal: terminalId };
+  }
+}
+
+// =============================================================================
+// CLI Interface
+// =============================================================================
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case 'detect': {
+      const terminals = detectTerminals();
+      console.log(JSON.stringify({ platform: getPlatform(), terminals }, null, 2));
+      break;
+    }
+
+    case 'best': {
+      const best = getBestTerminal();
+      if (best) {
+        console.log(JSON.stringify(best, null, 2));
+      } else {
+        console.log(JSON.stringify({ error: 'No supported terminal found' }));
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'spawn': {
+      const terminalId = args[1];
+      const title = args[2];
+      const cmd = args[3];
+      const cwd = args[4];
+      const tabColor = args[5];
+
+      if (!terminalId || !title || !cmd) {
+        console.error('Usage: terminal.js spawn <terminal-id> <title> <command> [cwd] [tabColor]');
+        process.exit(1);
+      }
+
+      const result = spawnTerminal(terminalId, title, cmd, { cwd, tabColor });
+      console.log(JSON.stringify(result));
+      process.exit(result.success ? 0 : 1);
+      break;
+    }
+
+    case 'list': {
+      const platform = getPlatform();
+      const all = Object.entries(TERMINALS)
+        .filter(([, t]) => t.platform === platform)
+        .map(([id, t]) => ({ id, name: t.name }));
+      console.log(JSON.stringify({ platform, terminals: all }, null, 2));
+      break;
+    }
+
+    default:
+      console.log(`Vibe Forge Terminal Utility
+
+Usage:
+  node terminal.js detect         Detect available terminals (JSON)
+  node terminal.js best           Get best available terminal (JSON)
+  node terminal.js list           List all terminals for this platform
+  node terminal.js spawn <id> <title> <command> [cwd] [tabColor]
+
+Examples:
+  node terminal.js detect
+  node terminal.js spawn windows-terminal "Anvil" "claude --chat"
+`);
+  }
+}
+
+// Export for use as module
+module.exports = {
+  detectTerminals,
+  getBestTerminal,
+  spawnTerminal,
+  findGitBash,
+  TERMINALS,
+  getPlatform,
+};
+
+// Run CLI if executed directly
+if (require.main === module) {
+  main();
+}