@xortex/xcode 3.0.0

package/utils/swarm/backends/detection.ts

@@ -0,0 +1,128 @@
+import { env } from '../../../utils/env.js'
+import { execFileNoThrow } from '../../../utils/execFileNoThrow.js'
+import { TMUX_COMMAND } from '../constants.js'
+
+/**
+ * Captured at module load time to detect if the user started Claude from within tmux.
+ * Shell.ts may override TMUX env var later, so we capture the original value.
+ */
+// eslint-disable-next-line custom-rules/no-process-env-top-level
+const ORIGINAL_USER_TMUX = process.env.TMUX
+
+/**
+ * Captured at module load time to get the leader's tmux pane ID.
+ * TMUX_PANE is set by tmux to the pane ID (e.g., %0, %1) when a process runs inside tmux.
+ * We capture this at startup so we always know the leader's original pane, even if
+ * the user switches to a different pane later.
+ */
+// eslint-disable-next-line custom-rules/no-process-env-top-level
+const ORIGINAL_TMUX_PANE = process.env.TMUX_PANE
+
+/** Cached result for isInsideTmux */
+let isInsideTmuxCached: boolean | null = null
+
+/** Cached result for isInITerm2 */
+let isInITerm2Cached: boolean | null = null
+
+/**
+ * Checks if we're currently running inside a tmux session (synchronous version).
+ * Uses the original TMUX value captured at module load, not process.env.TMUX,
+ * because Shell.ts overrides TMUX when Claude's socket is initialized.
+ *
+ * IMPORTANT: We ONLY check the TMUX env var. We do NOT run `tmux display-message`
+ * as a fallback because that command will succeed if ANY tmux server is running
+ * on the system, not just if THIS process is inside tmux.
+ */
+export function isInsideTmuxSync(): boolean {
+  return !!ORIGINAL_USER_TMUX
+}
+
+/**
+ * Checks if we're currently running inside a tmux session.
+ * Uses the original TMUX value captured at module load, not process.env.TMUX,
+ * because Shell.ts overrides TMUX when Claude's socket is initialized.
+ * Caches the result since this won't change during the process lifetime.
+ *
+ * IMPORTANT: We ONLY check the TMUX env var. We do NOT run `tmux display-message`
+ * as a fallback because that command will succeed if ANY tmux server is running
+ * on the system, not just if THIS process is inside tmux.
+ */
+export async function isInsideTmux(): Promise<boolean> {
+  if (isInsideTmuxCached !== null) {
+    return isInsideTmuxCached
+  }
+
+  // Check the original TMUX env var (captured at module load)
+  // This tells us if the user started Claude from within their tmux session
+  // If TMUX is not set, we are NOT inside tmux - period.
+  isInsideTmuxCached = !!ORIGINAL_USER_TMUX
+  return isInsideTmuxCached
+}
+
+/**
+ * Gets the leader's tmux pane ID captured at module load.
+ * Returns null if not running inside tmux.
+ */
+export function getLeaderPaneId(): string | null {
+  return ORIGINAL_TMUX_PANE || null
+}
+
+/**
+ * Checks if tmux is available on the system (installed and in PATH).
+ */
+export async function isTmuxAvailable(): Promise<boolean> {
+  const result = await execFileNoThrow(TMUX_COMMAND, ['-V'])
+  return result.code === 0
+}
+
+/**
+ * Checks if we're currently running inside iTerm2.
+ * Uses multiple detection methods:
+ * 1. TERM_PROGRAM env var set to "iTerm.app"
+ * 2. ITERM_SESSION_ID env var is present
+ * 3. env.terminal detection from utils/env.ts
+ *
+ * Caches the result since this won't change during the process lifetime.
+ *
+ * Note: iTerm2 backend uses AppleScript (osascript) which is built into macOS,
+ * so no external CLI tool installation is required.
+ */
+export function isInITerm2(): boolean {
+  if (isInITerm2Cached !== null) {
+    return isInITerm2Cached
+  }
+
+  // Check multiple indicators for iTerm2
+  const termProgram = process.env.TERM_PROGRAM
+  const hasItermSessionId = !!process.env.ITERM_SESSION_ID
+  const terminalIsITerm = env.terminal === 'iTerm.app'
+
+  isInITerm2Cached =
+    termProgram === 'iTerm.app' || hasItermSessionId || terminalIsITerm
+
+  return isInITerm2Cached
+}
+
+/**
+ * The it2 CLI command name.
+ */
+export const IT2_COMMAND = 'it2'
+
+/**
+ * Checks if the it2 CLI tool is available AND can reach the iTerm2 Python API.
+ * Uses 'session list' (not '--version') because --version succeeds even when
+ * the Python API is disabled in iTerm2 preferences — which would cause
+ * 'session split' to fail later with no fallback.
+ */
+export async function isIt2CliAvailable(): Promise<boolean> {
+  const result = await execFileNoThrow(IT2_COMMAND, ['session', 'list'])
+  return result.code === 0
+}
+
+/**
+ * Resets all cached detection results. Used for testing.
+ */
+export function resetDetectionCache(): void {
+  isInsideTmuxCached = null
+  isInITerm2Cached = null
+}

package/utils/swarm/backends/it2Setup.ts

@@ -0,0 +1,245 @@
+import { homedir } from 'os'
+import { getGlobalConfig, saveGlobalConfig } from '../../../utils/config.js'
+import { logForDebugging } from '../../../utils/debug.js'
+import {
+  execFileNoThrow,
+  execFileNoThrowWithCwd,
+} from '../../../utils/execFileNoThrow.js'
+import { logError } from '../../../utils/log.js'
+
+/**
+ * Package manager types for installing it2.
+ * Listed in order of preference.
+ */
+export type PythonPackageManager = 'uvx' | 'pipx' | 'pip'
+
+/**
+ * Result of attempting to install it2.
+ */
+export type It2InstallResult = {
+  success: boolean
+  error?: string
+  packageManager?: PythonPackageManager
+}
+
+/**
+ * Result of verifying it2 setup.
+ */
+export type It2VerifyResult = {
+  success: boolean
+  error?: string
+  needsPythonApiEnabled?: boolean
+}
+
+/**
+ * Detects which Python package manager is available on the system.
+ * Checks in order of preference: uvx, pipx, pip.
+ *
+ * @returns The detected package manager, or null if none found
+ */
+export async function detectPythonPackageManager(): Promise<PythonPackageManager | null> {
+  // Check uv first (preferred for isolated environments)
+  // We check for 'uv' since 'uv tool install' is the install command
+  const uvResult = await execFileNoThrow('which', ['uv'])
+  if (uvResult.code === 0) {
+    logForDebugging('[it2Setup] Found uv (will use uv tool install)')
+    return 'uvx' // Keep the type name for compatibility
+  }
+
+  // Check pipx (good for isolated environments)
+  const pipxResult = await execFileNoThrow('which', ['pipx'])
+  if (pipxResult.code === 0) {
+    logForDebugging('[it2Setup] Found pipx package manager')
+    return 'pipx'
+  }
+
+  // Check pip (fallback)
+  const pipResult = await execFileNoThrow('which', ['pip'])
+  if (pipResult.code === 0) {
+    logForDebugging('[it2Setup] Found pip package manager')
+    return 'pip'
+  }
+
+  // Also check pip3
+  const pip3Result = await execFileNoThrow('which', ['pip3'])
+  if (pip3Result.code === 0) {
+    logForDebugging('[it2Setup] Found pip3 package manager')
+    return 'pip'
+  }
+
+  logForDebugging('[it2Setup] No Python package manager found')
+  return null
+}
+
+/**
+ * Checks if the it2 CLI tool is installed and accessible.
+ *
+ * @returns true if it2 is available
+ */
+export async function isIt2CliAvailable(): Promise<boolean> {
+  const result = await execFileNoThrow('which', ['it2'])
+  return result.code === 0
+}
+
+/**
+ * Installs the it2 CLI tool using the detected package manager.
+ *
+ * @param packageManager - The package manager to use for installation
+ * @returns Result indicating success or failure
+ */
+export async function installIt2(
+  packageManager: PythonPackageManager,
+): Promise<It2InstallResult> {
+  logForDebugging(`[it2Setup] Installing it2 using ${packageManager}`)
+
+  // Run from home directory to avoid reading project-level pip.conf/uv.toml
+  // which could be maliciously crafted to redirect to an attacker's PyPI server
+  let result
+  switch (packageManager) {
+    case 'uvx':
+      // uv tool install it2 installs it globally in isolated env
+      // (uvx is for running, uv tool install is for installing)
+      result = await execFileNoThrowWithCwd('uv', ['tool', 'install', 'it2'], {
+        cwd: homedir(),
+      })
+      break
+    case 'pipx':
+      result = await execFileNoThrowWithCwd('pipx', ['install', 'it2'], {
+        cwd: homedir(),
+      })
+      break
+    case 'pip':
+      // Use --user to install without sudo
+      result = await execFileNoThrowWithCwd(
+        'pip',
+        ['install', '--user', 'it2'],
+        { cwd: homedir() },
+      )
+      if (result.code !== 0) {
+        // Try pip3 if pip fails
+        result = await execFileNoThrowWithCwd(
+          'pip3',
+          ['install', '--user', 'it2'],
+          { cwd: homedir() },
+        )
+      }
+      break
+  }
+
+  if (result.code !== 0) {
+    const error = result.stderr || 'Unknown installation error'
+    logError(new Error(`[it2Setup] Failed to install it2: ${error}`))
+    return {
+      success: false,
+      error,
+      packageManager,
+    }
+  }
+
+  logForDebugging('[it2Setup] it2 installed successfully')
+  return {
+    success: true,
+    packageManager,
+  }
+}
+
+/**
+ * Verifies that it2 is properly configured and can communicate with iTerm2.
+ * This tests the Python API connection by running a simple it2 command.
+ *
+ * @returns Result indicating success or the specific failure reason
+ */
+export async function verifyIt2Setup(): Promise<It2VerifyResult> {
+  logForDebugging('[it2Setup] Verifying it2 setup...')
+
+  // First check if it2 is installed
+  const installed = await isIt2CliAvailable()
+  if (!installed) {
+    return {
+      success: false,
+      error: 'it2 CLI is not installed or not in PATH',
+    }
+  }
+
+  // Try to list sessions - this tests the Python API connection
+  const result = await execFileNoThrow('it2', ['session', 'list'])
+
+  if (result.code !== 0) {
+    const stderr = result.stderr.toLowerCase()
+
+    // Check for common Python API errors
+    if (
+      stderr.includes('api') ||
+      stderr.includes('python') ||
+      stderr.includes('connection refused') ||
+      stderr.includes('not enabled')
+    ) {
+      logForDebugging('[it2Setup] Python API not enabled in iTerm2')
+      return {
+        success: false,
+        error: 'Python API not enabled in iTerm2 preferences',
+        needsPythonApiEnabled: true,
+      }
+    }
+
+    return {
+      success: false,
+      error: result.stderr || 'Failed to communicate with iTerm2',
+    }
+  }
+
+  logForDebugging('[it2Setup] it2 setup verified successfully')
+  return {
+    success: true,
+  }
+}
+
+/**
+ * Returns instructions for enabling the Python API in iTerm2.
+ */
+export function getPythonApiInstructions(): string[] {
+  return [
+    'Almost done! Enable the Python API in iTerm2:',
+    '',
+    '  iTerm2 → Settings → General → Magic → Enable Python API',
+    '',
+    'After enabling, you may need to restart iTerm2.',
+  ]
+}
+
+/**
+ * Marks that it2 setup has been completed successfully.
+ * This prevents showing the setup prompt again.
+ */
+export function markIt2SetupComplete(): void {
+  const config = getGlobalConfig()
+  if (config.iterm2It2SetupComplete !== true) {
+    saveGlobalConfig(current => ({
+      ...current,
+      iterm2It2SetupComplete: true,
+    }))
+    logForDebugging('[it2Setup] Marked it2 setup as complete')
+  }
+}
+
+/**
+ * Marks that the user prefers to use tmux over iTerm2 split panes.
+ * This prevents showing the setup prompt when in iTerm2.
+ */
+export function setPreferTmuxOverIterm2(prefer: boolean): void {
+  const config = getGlobalConfig()
+  if (config.preferTmuxOverIterm2 !== prefer) {
+    saveGlobalConfig(current => ({
+      ...current,
+      preferTmuxOverIterm2: prefer,
+    }))
+    logForDebugging(`[it2Setup] Set preferTmuxOverIterm2 = ${prefer}`)
+  }
+}
+
+/**
+ * Checks if the user prefers tmux over iTerm2 split panes.
+ */
+export function getPreferTmuxOverIterm2(): boolean {
+  return getGlobalConfig().preferTmuxOverIterm2 === true
+}