@xortex/xcode 3.0.0

package/utils/apiPreconnect.ts

@@ -0,0 +1,71 @@
+/**
+ * Preconnect to the Anthropic API to overlap TCP+TLS handshake with startup.
+ *
+ * The TCP+TLS handshake is ~100-200ms that normally blocks inside the first
+ * API call. Kicking a fire-and-forget fetch during init lets the handshake
+ * happen in parallel with action-handler work (~100ms of setup/commands/mcp
+ * before the API request in -p mode; unbounded "user is typing" window in
+ * interactive mode).
+ *
+ * Bun's fetch shares a keep-alive connection pool globally, so the real API
+ * request reuses the warmed connection.
+ *
+ * Called from init.ts AFTER applyExtraCACertsFromConfig() + configureGlobalAgents()
+ * so settings.json env vars are applied and the TLS cert store is finalized.
+ * The early cli.tsx call site was removed — it ran before settings.json loaded,
+ * so ANTHROPIC_BASE_URL/proxy/mTLS in settings would be invisible and preconnect
+ * would warm the wrong pool (or worse, lock BoringSSL's cert store before
+ * NODE_EXTRA_CA_CERTS was applied).
+ *
+ * Skipped when:
+ * - proxy/mTLS/unix socket configured (preconnect would use wrong transport —
+ *   the SDK passes a custom dispatcher/agent that doesn't share the global pool)
+ * - Bedrock/Vertex/Foundry (different endpoints, different auth)
+ */
+
+import { getOauthConfig } from '../constants/oauth.js'
+import { isEnvTruthy } from './envUtils.js'
+
+let fired = false
+
+export function preconnectAnthropicApi(): void {
+  if (fired) return
+  fired = true
+
+  // Skip if using a cloud provider — different endpoint + auth
+  if (
+    isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK) ||
+    isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX) ||
+    isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY)
+  ) {
+    return
+  }
+  // Skip if proxy/mTLS/unix — SDK's custom dispatcher won't reuse this pool
+  if (
+    process.env.HTTPS_PROXY ||
+    process.env.https_proxy ||
+    process.env.HTTP_PROXY ||
+    process.env.http_proxy ||
+    process.env.ANTHROPIC_UNIX_SOCKET ||
+    process.env.CLAUDE_CODE_CLIENT_CERT ||
+    process.env.CLAUDE_CODE_CLIENT_KEY
+  ) {
+    return
+  }
+
+  // Use configured base URL (staging, local, or custom gateway). Covers
+  // ANTHROPIC_BASE_URL env + USE_STAGING_OAUTH + USE_LOCAL_OAUTH in one lookup.
+  // NODE_EXTRA_CA_CERTS no longer a skip — init.ts applied it before this fires.
+  const baseUrl =
+    process.env.ANTHROPIC_BASE_URL || getOauthConfig().BASE_API_URL
+
+  // Fire and forget. HEAD means no response body — the connection is eligible
+  // for keep-alive pool reuse immediately after headers arrive. 10s timeout
+  // so a slow network doesn't hang the process; abort is fine since the real
+  // request will handshake fresh if needed.
+  // eslint-disable-next-line eslint-plugin-n/no-unsupported-features/node-builtins
+  void fetch(baseUrl, {
+    method: 'HEAD',
+    signal: AbortSignal.timeout(10_000),
+  }).catch(() => {})
+}

package/utils/appleTerminalBackup.ts

@@ -0,0 +1,124 @@
+import { stat } from 'fs/promises'
+import { homedir } from 'os'
+import { join } from 'path'
+import { getGlobalConfig, saveGlobalConfig } from './config.js'
+import { execFileNoThrow } from './execFileNoThrow.js'
+import { logError } from './log.js'
+export function markTerminalSetupInProgress(backupPath: string): void {
+  saveGlobalConfig(current => ({
+    ...current,
+    appleTerminalSetupInProgress: true,
+    appleTerminalBackupPath: backupPath,
+  }))
+}
+
+export function markTerminalSetupComplete(): void {
+  saveGlobalConfig(current => ({
+    ...current,
+    appleTerminalSetupInProgress: false,
+  }))
+}
+
+function getTerminalRecoveryInfo(): {
+  inProgress: boolean
+  backupPath: string | null
+} {
+  const config = getGlobalConfig()
+  return {
+    inProgress: config.appleTerminalSetupInProgress ?? false,
+    backupPath: config.appleTerminalBackupPath || null,
+  }
+}
+
+export function getTerminalPlistPath(): string {
+  return join(homedir(), 'Library', 'Preferences', 'com.apple.Terminal.plist')
+}
+
+export async function backupTerminalPreferences(): Promise<string | null> {
+  const terminalPlistPath = getTerminalPlistPath()
+  const backupPath = `${terminalPlistPath}.bak`
+
+  try {
+    const { code } = await execFileNoThrow('defaults', [
+      'export',
+      'com.apple.Terminal',
+      terminalPlistPath,
+    ])
+
+    if (code !== 0) {
+      return null
+    }
+
+    try {
+      await stat(terminalPlistPath)
+    } catch {
+      return null
+    }
+
+    await execFileNoThrow('defaults', [
+      'export',
+      'com.apple.Terminal',
+      backupPath,
+    ])
+
+    markTerminalSetupInProgress(backupPath)
+
+    return backupPath
+  } catch (error) {
+    logError(error)
+    return null
+  }
+}
+
+type RestoreResult =
+  | {
+      status: 'restored' | 'no_backup'
+    }
+  | {
+      status: 'failed'
+      backupPath: string
+    }
+
+export async function checkAndRestoreTerminalBackup(): Promise<RestoreResult> {
+  const { inProgress, backupPath } = getTerminalRecoveryInfo()
+  if (!inProgress) {
+    return { status: 'no_backup' }
+  }
+
+  if (!backupPath) {
+    markTerminalSetupComplete()
+    return { status: 'no_backup' }
+  }
+
+  try {
+    await stat(backupPath)
+  } catch {
+    markTerminalSetupComplete()
+    return { status: 'no_backup' }
+  }
+
+  try {
+    const { code } = await execFileNoThrow('defaults', [
+      'import',
+      'com.apple.Terminal',
+      backupPath,
+    ])
+
+    if (code !== 0) {
+      return { status: 'failed', backupPath }
+    }
+
+    await execFileNoThrow('killall', ['cfprefsd'])
+
+    markTerminalSetupComplete()
+    return { status: 'restored' }
+  } catch (restoreError) {
+    logError(
+      new Error(
+        `Failed to restore Terminal.app settings with: ${restoreError}`,
+      ),
+    )
+    markTerminalSetupComplete()
+    return { status: 'failed', backupPath }
+  }
+}

package/utils/argumentSubstitution.ts

@@ -0,0 +1,145 @@
+/**
+ * Utility for substituting $ARGUMENTS placeholders in skill/command prompts.
+ *
+ * Supports:
+ * - $ARGUMENTS - replaced with the full arguments string
+ * - $ARGUMENTS[0], $ARGUMENTS[1], etc. - replaced with individual indexed arguments
+ * - $0, $1, etc. - shorthand for $ARGUMENTS[0], $ARGUMENTS[1]
+ * - Named arguments (e.g., $foo, $bar) - when argument names are defined in frontmatter
+ *
+ * Arguments are parsed using shell-quote for proper shell argument handling.
+ */
+
+import { tryParseShellCommand } from './bash/shellQuote.js'
+
+/**
+ * Parse an arguments string into an array of individual arguments.
+ * Uses shell-quote for proper shell argument parsing including quoted strings.
+ *
+ * Examples:
+ * - "foo bar baz" => ["foo", "bar", "baz"]
+ * - 'foo "hello world" baz' => ["foo", "hello world", "baz"]
+ * - "foo 'hello world' baz" => ["foo", "hello world", "baz"]
+ */
+export function parseArguments(args: string): string[] {
+  if (!args || !args.trim()) {
+    return []
+  }
+
+  // Return $KEY to preserve variable syntax literally (don't expand variables)
+  const result = tryParseShellCommand(args, key => `$${key}`)
+  if (!result.success) {
+    // Fall back to simple whitespace split if parsing fails
+    return args.split(/\s+/).filter(Boolean)
+  }
+
+  // Filter to only string tokens (ignore shell operators, etc.)
+  return result.tokens.filter(
+    (token): token is string => typeof token === 'string',
+  )
+}
+
+/**
+ * Parse argument names from the frontmatter 'arguments' field.
+ * Accepts either a space-separated string or an array of strings.
+ *
+ * Examples:
+ * - "foo bar baz" => ["foo", "bar", "baz"]
+ * - ["foo", "bar", "baz"] => ["foo", "bar", "baz"]
+ */
+export function parseArgumentNames(
+  argumentNames: string | string[] | undefined,
+): string[] {
+  if (!argumentNames) {
+    return []
+  }
+
+  // Filter out empty strings and numeric-only names (which conflict with $0, $1 shorthand)
+  const isValidName = (name: string): boolean =>
+    typeof name === 'string' && name.trim() !== '' && !/^\d+$/.test(name)
+
+  if (Array.isArray(argumentNames)) {
+    return argumentNames.filter(isValidName)
+  }
+  if (typeof argumentNames === 'string') {
+    return argumentNames.split(/\s+/).filter(isValidName)
+  }
+  return []
+}
+
+/**
+ * Generate argument hint showing remaining unfilled args.
+ * @param argNames - Array of argument names from frontmatter
+ * @param typedArgs - Arguments the user has typed so far
+ * @returns Hint string like "[arg2] [arg3]" or undefined if all filled
+ */
+export function generateProgressiveArgumentHint(
+  argNames: string[],
+  typedArgs: string[],
+): string | undefined {
+  const remaining = argNames.slice(typedArgs.length)
+  if (remaining.length === 0) return undefined
+  return remaining.map(name => `[${name}]`).join(' ')
+}
+
+/**
+ * Substitute $ARGUMENTS placeholders in content with actual argument values.
+ *
+ * @param content - The content containing placeholders
+ * @param args - The raw arguments string (may be undefined/null)
+ * @param appendIfNoPlaceholder - If true and no placeholders are found, appends "ARGUMENTS: {args}" to content
+ * @param argumentNames - Optional array of named arguments (e.g., ["foo", "bar"]) that map to indexed positions
+ * @returns The content with placeholders substituted
+ */
+export function substituteArguments(
+  content: string,
+  args: string | undefined,
+  appendIfNoPlaceholder = true,
+  argumentNames: string[] = [],
+): string {
+  // undefined/null means no args provided - return content unchanged
+  // empty string is a valid input that should replace placeholders with empty
+  if (args === undefined || args === null) {
+    return content
+  }
+
+  const parsedArgs = parseArguments(args)
+  const originalContent = content
+
+  // Replace named arguments (e.g., $foo, $bar) with their values
+  // Named arguments map to positions: argumentNames[0] -> parsedArgs[0], etc.
+  for (let i = 0; i < argumentNames.length; i++) {
+    const name = argumentNames[i]
+    if (!name) continue
+
+    // Match $name but not $name[...] or $nameXxx (word chars)
+    // Also ensure we match word boundaries to avoid partial matches
+    content = content.replace(
+      new RegExp(`\\$${name}(?![\\[\\w])`, 'g'),
+      parsedArgs[i] ?? '',
+    )
+  }
+
+  // Replace indexed arguments ($ARGUMENTS[0], $ARGUMENTS[1], etc.)
+  content = content.replace(/\$ARGUMENTS\[(\d+)\]/g, (_, indexStr: string) => {
+    const index = parseInt(indexStr, 10)
+    return parsedArgs[index] ?? ''
+  })
+
+  // Replace shorthand indexed arguments ($0, $1, etc.)
+  content = content.replace(/\$(\d+)(?!\w)/g, (_, indexStr: string) => {
+    const index = parseInt(indexStr, 10)
+    return parsedArgs[index] ?? ''
+  })
+
+  // Replace $ARGUMENTS with the full arguments string
+  content = content.replaceAll('$ARGUMENTS', args)
+
+  // If no placeholders were found and appendIfNoPlaceholder is true, append
+  // But only if args is non-empty (empty string means command invoked with no args)
+  if (content === originalContent && appendIfNoPlaceholder && args) {
+    content = content + `\n\nARGUMENTS: ${args}`
+  }
+
+  return content
+}

package/utils/array.ts

@@ -0,0 +1,13 @@
+export function intersperse<A>(as: A[], separator: (index: number) => A): A[] {
+  return as.flatMap((a, i) => (i ? [separator(i), a] : [a]))
+}
+
+export function count<T>(arr: readonly T[], pred: (x: T) => unknown): number {
+  let n = 0
+  for (const x of arr) n += +!!pred(x)
+  return n
+}
+
+export function uniq<T>(xs: Iterable<T>): T[] {
+  return [...new Set(xs)]
+}

package/utils/asciicast.ts

@@ -0,0 +1,239 @@
+import { appendFile, rename } from 'fs/promises'
+import { basename, dirname, join } from 'path'
+import { getOriginalCwd, getSessionId } from '../bootstrap/state.js'
+import { createBufferedWriter } from './bufferedWriter.js'
+import { registerCleanup } from './cleanupRegistry.js'
+import { logForDebugging } from './debug.js'
+import { getClaudeConfigHomeDir, isEnvTruthy } from './envUtils.js'
+import { getFsImplementation } from './fsOperations.js'
+import { sanitizePath } from './path.js'
+import { jsonStringify } from './slowOperations.js'
+
+// Mutable recording state — filePath is updated when session ID changes (e.g., --resume)
+const recordingState: { filePath: string | null; timestamp: number } = {
+  filePath: null,
+  timestamp: 0,
+}
+
+/**
+ * Get the asciicast recording file path.
+ * For ants with CLAUDE_CODE_TERMINAL_RECORDING=1: returns a path.
+ * Otherwise: returns null.
+ * The path is computed once and cached in recordingState.
+ */
+export function getRecordFilePath(): string | null {
+  if (recordingState.filePath !== null) {
+    return recordingState.filePath
+  }
+  if (process.env.USER_TYPE !== 'ant') {
+    return null
+  }
+  if (!isEnvTruthy(process.env.CLAUDE_CODE_TERMINAL_RECORDING)) {
+    return null
+  }
+  // Record alongside the transcript.
+  // Each launch gets its own file so --continue produces multiple recordings.
+  const projectsDir = join(getClaudeConfigHomeDir(), 'projects')
+  const projectDir = join(projectsDir, sanitizePath(getOriginalCwd()))
+  recordingState.timestamp = Date.now()
+  recordingState.filePath = join(
+    projectDir,
+    `${getSessionId()}-${recordingState.timestamp}.cast`,
+  )
+  return recordingState.filePath
+}
+
+export function _resetRecordingStateForTesting(): void {
+  recordingState.filePath = null
+  recordingState.timestamp = 0
+}
+
+/**
+ * Find all .cast files for the current session.
+ * Returns paths sorted by filename (chronological by timestamp suffix).
+ */
+export function getSessionRecordingPaths(): string[] {
+  const sessionId = getSessionId()
+  const projectsDir = join(getClaudeConfigHomeDir(), 'projects')
+  const projectDir = join(projectsDir, sanitizePath(getOriginalCwd()))
+  try {
+    // eslint-disable-next-line custom-rules/no-sync-fs -- called during /share before upload, not in hot path
+    const entries = getFsImplementation().readdirSync(projectDir)
+    const names = (
+      typeof entries[0] === 'string'
+        ? entries
+        : (entries as { name: string }[]).map(e => e.name)
+    ) as string[]
+    const files = names
+      .filter(f => f.startsWith(sessionId) && f.endsWith('.cast'))
+      .sort()
+    return files.map(f => join(projectDir, f))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Rename the recording file to match the current session ID.
+ * Called after --resume/--continue changes the session ID via switchSession().
+ * The recorder was installed with the initial (random) session ID; this renames
+ * the file so getSessionRecordingPaths() can find it by the resumed session ID.
+ */
+export async function renameRecordingForSession(): Promise<void> {
+  const oldPath = recordingState.filePath
+  if (!oldPath || recordingState.timestamp === 0) {
+    return
+  }
+  const projectsDir = join(getClaudeConfigHomeDir(), 'projects')
+  const projectDir = join(projectsDir, sanitizePath(getOriginalCwd()))
+  const newPath = join(
+    projectDir,
+    `${getSessionId()}-${recordingState.timestamp}.cast`,
+  )
+  if (oldPath === newPath) {
+    return
+  }
+  // Flush pending writes before renaming
+  await recorder?.flush()
+  const oldName = basename(oldPath)
+  const newName = basename(newPath)
+  try {
+    await rename(oldPath, newPath)
+    recordingState.filePath = newPath
+    logForDebugging(`[asciicast] Renamed recording: ${oldName} → ${newName}`)
+  } catch {
+    logForDebugging(
+      `[asciicast] Failed to rename recording from ${oldName} to ${newName}`,
+    )
+  }
+}
+
+type AsciicastRecorder = {
+  flush(): Promise<void>
+  dispose(): Promise<void>
+}
+
+let recorder: AsciicastRecorder | null = null
+
+function getTerminalSize(): { cols: number; rows: number } {
+  // Direct access to stdout dimensions — not in a React component
+  // eslint-disable-next-line custom-rules/prefer-use-terminal-size
+  const cols = process.stdout.columns || 80
+  // eslint-disable-next-line custom-rules/prefer-use-terminal-size
+  const rows = process.stdout.rows || 24
+  return { cols, rows }
+}
+
+/**
+ * Flush pending recording data to disk.
+ * Call before reading the .cast file (e.g., during /share).
+ */
+export async function flushAsciicastRecorder(): Promise<void> {
+  await recorder?.flush()
+}
+
+/**
+ * Install the asciicast recorder.
+ * Wraps process.stdout.write to capture all terminal output with timestamps.
+ * Must be called before Ink mounts.
+ */
+export function installAsciicastRecorder(): void {
+  const filePath = getRecordFilePath()
+  if (!filePath) {
+    return
+  }
+
+  const { cols, rows } = getTerminalSize()
+  const startTime = performance.now()
+
+  // Write the asciicast v2 header
+  const header = jsonStringify({
+    version: 2,
+    width: cols,
+    height: rows,
+    timestamp: Math.floor(Date.now() / 1000),
+    env: {
+      SHELL: process.env.SHELL || '',
+      TERM: process.env.TERM || '',
+    },
+  })
+
+  try {
+    // eslint-disable-next-line custom-rules/no-sync-fs -- one-time init before Ink mounts
+    getFsImplementation().mkdirSync(dirname(filePath))
+  } catch {
+    // Directory may already exist
+  }
+  // eslint-disable-next-line custom-rules/no-sync-fs -- one-time init before Ink mounts
+  getFsImplementation().appendFileSync(filePath, header + '\n', { mode: 0o600 })
+
+  let pendingWrite: Promise<void> = Promise.resolve()
+
+  const writer = createBufferedWriter({
+    writeFn(content: string) {
+      // Use recordingState.filePath (mutable) so writes follow renames from --resume
+      const currentPath = recordingState.filePath
+      if (!currentPath) {
+        return
+      }
+      pendingWrite = pendingWrite
+        .then(() => appendFile(currentPath, content))
+        .catch(() => {
+          // Silently ignore write errors — don't break the session
+        })
+    },
+    flushIntervalMs: 500,
+    maxBufferSize: 50,
+    maxBufferBytes: 10 * 1024 * 1024, // 10MB
+  })
+
+  // Wrap process.stdout.write to capture output
+  const originalWrite = process.stdout.write.bind(
+    process.stdout,
+  ) as typeof process.stdout.write
+  process.stdout.write = function (
+    chunk: string | Uint8Array,
+    encodingOrCb?: BufferEncoding | ((err?: Error) => void),
+    cb?: (err?: Error) => void,
+  ): boolean {
+    // Record the output event
+    const elapsed = (performance.now() - startTime) / 1000
+    const text =
+      typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf-8')
+    writer.write(jsonStringify([elapsed, 'o', text]) + '\n')
+
+    // Pass through to the real stdout
+    if (typeof encodingOrCb === 'function') {
+      return originalWrite(chunk, encodingOrCb)
+    }
+    return originalWrite(chunk, encodingOrCb, cb)
+  } as typeof process.stdout.write
+
+  // Handle terminal resize events
+  function onResize(): void {
+    const elapsed = (performance.now() - startTime) / 1000
+    const { cols: newCols, rows: newRows } = getTerminalSize()
+    writer.write(jsonStringify([elapsed, 'r', `${newCols}x${newRows}`]) + '\n')
+  }
+  process.stdout.on('resize', onResize)
+
+  recorder = {
+    async flush(): Promise<void> {
+      writer.flush()
+      await pendingWrite
+    },
+    async dispose(): Promise<void> {
+      writer.dispose()
+      await pendingWrite
+      process.stdout.removeListener('resize', onResize)
+      process.stdout.write = originalWrite
+    },
+  }
+
+  registerCleanup(async () => {
+    await recorder?.dispose()
+    recorder = null
+  })
+
+  logForDebugging(`[asciicast] Recording to ${filePath}`)
+}