@xortex/xcode 3.0.0

package/utils/secureStorage/macOsKeychainStorage.ts

@@ -0,0 +1,231 @@
+import { execaSync } from 'execa'
+import { logForDebugging } from '../debug.js'
+import { execFileNoThrow } from '../execFileNoThrow.js'
+import { execSyncWithDefaults_DEPRECATED } from '../execFileNoThrowPortable.js'
+import { jsonParse, jsonStringify } from '../slowOperations.js'
+import {
+  CREDENTIALS_SERVICE_SUFFIX,
+  clearKeychainCache,
+  getMacOsKeychainStorageServiceName,
+  getUsername,
+  KEYCHAIN_CACHE_TTL_MS,
+  keychainCacheState,
+} from './macOsKeychainHelpers.js'
+import type { SecureStorage, SecureStorageData } from './types.js'
+
+// `security -i` reads stdin with a 4096-byte fgets() buffer (BUFSIZ on darwin).
+// A command line longer than this is truncated mid-argument: the first 4096
+// bytes are consumed as one command (unterminated quote → fails), the overflow
+// is interpreted as a second unknown command. Net: non-zero exit with NO data
+// written, but the *previous* keychain entry is left intact — which fallback
+// storage then reads as stale. See #30337.
+// Headroom of 64B below the limit guards against edge-case line-terminator
+// accounting differences.
+const SECURITY_STDIN_LINE_LIMIT = 4096 - 64
+
+export const macOsKeychainStorage = {
+  name: 'keychain',
+  read(): SecureStorageData | null {
+    const prev = keychainCacheState.cache
+    if (Date.now() - prev.cachedAt < KEYCHAIN_CACHE_TTL_MS) {
+      return prev.data
+    }
+
+    try {
+      const storageServiceName = getMacOsKeychainStorageServiceName(
+        CREDENTIALS_SERVICE_SUFFIX,
+      )
+      const username = getUsername()
+      const result = execSyncWithDefaults_DEPRECATED(
+        `security find-generic-password -a "${username}" -w -s "${storageServiceName}"`,
+      )
+      if (result) {
+        const data = jsonParse(result)
+        keychainCacheState.cache = { data, cachedAt: Date.now() }
+        return data
+      }
+    } catch (_e) {
+      // fall through
+    }
+    // Stale-while-error: if we had a value before and the refresh failed,
+    // keep serving the stale value rather than caching null. Since #23192
+    // clears the upstream memoize on every API request (macOS path), a
+    // single transient `security` spawn failure would otherwise poison the
+    // cache and surface as "Not logged in" across all subsystems until the
+    // next user interaction. clearKeychainCache() sets data=null, so
+    // explicit invalidation (logout, delete) still reads through.
+    if (prev.data !== null) {
+      logForDebugging('[keychain] read failed; serving stale cache', {
+        level: 'warn',
+      })
+      keychainCacheState.cache = { data: prev.data, cachedAt: Date.now() }
+      return prev.data
+    }
+    keychainCacheState.cache = { data: null, cachedAt: Date.now() }
+    return null
+  },
+  async readAsync(): Promise<SecureStorageData | null> {
+    const prev = keychainCacheState.cache
+    if (Date.now() - prev.cachedAt < KEYCHAIN_CACHE_TTL_MS) {
+      return prev.data
+    }
+    if (keychainCacheState.readInFlight) {
+      return keychainCacheState.readInFlight
+    }
+
+    const gen = keychainCacheState.generation
+    const promise = doReadAsync().then(data => {
+      // If the cache was invalidated or updated while we were reading,
+      // our subprocess result is stale — don't overwrite the newer entry.
+      if (gen === keychainCacheState.generation) {
+        // Stale-while-error — mirror read() above.
+        if (data === null && prev.data !== null) {
+          logForDebugging('[keychain] readAsync failed; serving stale cache', {
+            level: 'warn',
+          })
+        }
+        const next = data ?? prev.data
+        keychainCacheState.cache = { data: next, cachedAt: Date.now() }
+        keychainCacheState.readInFlight = null
+        return next
+      }
+      return data
+    })
+    keychainCacheState.readInFlight = promise
+    return promise
+  },
+  update(data: SecureStorageData): { success: boolean; warning?: string } {
+    // Invalidate cache before update
+    clearKeychainCache()
+
+    try {
+      const storageServiceName = getMacOsKeychainStorageServiceName(
+        CREDENTIALS_SERVICE_SUFFIX,
+      )
+      const username = getUsername()
+      const jsonString = jsonStringify(data)
+
+      // Convert to hexadecimal to avoid any escaping issues
+      const hexValue = Buffer.from(jsonString, 'utf-8').toString('hex')
+
+      // Prefer stdin (`security -i`) so process monitors (CrowdStrike et al.)
+      // see only "security -i", not the payload (INC-3028).
+      // When the payload would overflow the stdin line buffer, fall back to
+      // argv. Hex in argv is recoverable by a determined observer but defeats
+      // naive plaintext-grep rules, and the alternative — silent credential
+      // corruption — is strictly worse. ARG_MAX on darwin is 1MB so argv has
+      // effectively no size limit for our purposes.
+      const command = `add-generic-password -U -a "${username}" -s "${storageServiceName}" -X "${hexValue}"\n`
+
+      let result
+      if (command.length <= SECURITY_STDIN_LINE_LIMIT) {
+        result = execaSync('security', ['-i'], {
+          input: command,
+          stdio: ['pipe', 'pipe', 'pipe'],
+          reject: false,
+        })
+      } else {
+        logForDebugging(
+          `Keychain payload (${jsonString.length}B JSON) exceeds security -i stdin limit; using argv`,
+          { level: 'warn' },
+        )
+        result = execaSync(
+          'security',
+          [
+            'add-generic-password',
+            '-U',
+            '-a',
+            username,
+            '-s',
+            storageServiceName,
+            '-X',
+            hexValue,
+          ],
+          { stdio: ['ignore', 'pipe', 'pipe'], reject: false },
+        )
+      }
+
+      if (result.exitCode !== 0) {
+        return { success: false }
+      }
+
+      // Update cache with new data on success
+      keychainCacheState.cache = { data, cachedAt: Date.now() }
+      return { success: true }
+    } catch (_e) {
+      return { success: false }
+    }
+  },
+  delete(): boolean {
+    // Invalidate cache before delete
+    clearKeychainCache()
+
+    try {
+      const storageServiceName = getMacOsKeychainStorageServiceName(
+        CREDENTIALS_SERVICE_SUFFIX,
+      )
+      const username = getUsername()
+      execSyncWithDefaults_DEPRECATED(
+        `security delete-generic-password -a "${username}" -s "${storageServiceName}"`,
+      )
+      return true
+    } catch (_e) {
+      return false
+    }
+  },
+} satisfies SecureStorage
+
+async function doReadAsync(): Promise<SecureStorageData | null> {
+  try {
+    const storageServiceName = getMacOsKeychainStorageServiceName(
+      CREDENTIALS_SERVICE_SUFFIX,
+    )
+    const username = getUsername()
+    const { stdout, code } = await execFileNoThrow(
+      'security',
+      ['find-generic-password', '-a', username, '-w', '-s', storageServiceName],
+      { useCwd: false, preserveOutputOnError: false },
+    )
+    if (code === 0 && stdout) {
+      return jsonParse(stdout.trim())
+    }
+  } catch (_e) {
+    // fall through
+  }
+  return null
+}
+
+let keychainLockedCache: boolean | undefined
+
+/**
+ * Checks if the macOS keychain is locked.
+ * Returns true if on macOS and keychain is locked (exit code 36 from security show-keychain-info).
+ * This commonly happens in SSH sessions where the keychain isn't automatically unlocked.
+ *
+ * Cached for process lifetime — execaSync('security', ...) is a ~27ms sync
+ * subprocess spawn, and this is called from render (AssistantTextMessage).
+ * During virtual-scroll remounts on sessions with "Not logged in" messages,
+ * each remount re-spawned security(1), adding 27ms/message to the commit.
+ * Keychain lock state doesn't change during a CLI session.
+ */
+export function isMacOsKeychainLocked(): boolean {
+  if (keychainLockedCache !== undefined) return keychainLockedCache
+  // Only check on macOS
+  if (process.platform !== 'darwin') {
+    keychainLockedCache = false
+    return false
+  }
+
+  try {
+    const result = execaSync('security', ['show-keychain-info'], {
+      reject: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    // Exit code 36 indicates the keychain is locked
+    keychainLockedCache = result.exitCode === 36
+  } catch {
+    // If the command fails for any reason, assume keychain is not locked
+    keychainLockedCache = false
+  }
+  return keychainLockedCache
+}

package/utils/secureStorage/plainTextStorage.ts

@@ -0,0 +1,84 @@
+import { chmodSync } from 'fs'
+import { join } from 'path'
+import { getClaudeConfigHomeDir } from '../envUtils.js'
+import { getErrnoCode } from '../errors.js'
+import { getFsImplementation } from '../fsOperations.js'
+import {
+  jsonParse,
+  jsonStringify,
+  writeFileSync_DEPRECATED,
+} from '../slowOperations.js'
+import type { SecureStorage, SecureStorageData } from './types.js'
+
+function getStoragePath(): { storageDir: string; storagePath: string } {
+  const storageDir = getClaudeConfigHomeDir()
+  const storageFileName = '.credentials.json'
+  return { storageDir, storagePath: join(storageDir, storageFileName) }
+}
+
+export const plainTextStorage = {
+  name: 'plaintext',
+  read(): SecureStorageData | null {
+    // sync IO: called from sync context (SecureStorage interface)
+    const { storagePath } = getStoragePath()
+    try {
+      const data = getFsImplementation().readFileSync(storagePath, {
+        encoding: 'utf8',
+      })
+      return jsonParse(data)
+    } catch {
+      return null
+    }
+  },
+  async readAsync(): Promise<SecureStorageData | null> {
+    const { storagePath } = getStoragePath()
+    try {
+      const data = await getFsImplementation().readFile(storagePath, {
+        encoding: 'utf8',
+      })
+      return jsonParse(data)
+    } catch {
+      return null
+    }
+  },
+  update(data: SecureStorageData): { success: boolean; warning?: string } {
+    // sync IO: called from sync context (SecureStorage interface)
+    try {
+      const { storageDir, storagePath } = getStoragePath()
+      try {
+        getFsImplementation().mkdirSync(storageDir)
+      } catch (e: unknown) {
+        const code = getErrnoCode(e)
+        if (code !== 'EEXIST') {
+          throw e
+        }
+      }
+
+      writeFileSync_DEPRECATED(storagePath, jsonStringify(data), {
+        encoding: 'utf8',
+        flush: false,
+      })
+      chmodSync(storagePath, 0o600)
+      return {
+        success: true,
+        warning: 'Warning: Storing credentials in plaintext.',
+      }
+    } catch {
+      return { success: false }
+    }
+  },
+  delete(): boolean {
+    // sync IO: called from sync context (SecureStorage interface)
+    const { storagePath } = getStoragePath()
+    try {
+      getFsImplementation().unlinkSync(storagePath)
+      return true
+    } catch (e: unknown) {
+      const code = getErrnoCode(e)
+      if (code === 'ENOENT') {
+        return true
+      }
+      return false
+    }
+  },
+} satisfies SecureStorage

package/utils/semanticBoolean.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod/v4'
+
+/**
+ * Boolean that also accepts the string literals "true"/"false".
+ *
+ * Tool inputs arrive as model-generated JSON. The model occasionally quotes
+ * booleans — `"replace_all":"false"` instead of `"replace_all":false` — and
+ * z.boolean() rejects that with a type error. z.coerce.boolean() is the wrong
+ * fix: it uses JS truthiness, so "false" → true.
+ *
+ * z.preprocess emits {"type":"boolean"} to the API schema, so the model is
+ * still told this is a boolean — the string tolerance is invisible client-side
+ * coercion, not an advertised input shape.
+ *
+ * .optional()/.default() go INSIDE (on the inner schema), not chained after:
+ * chaining them onto ZodPipe widens z.output<> to unknown in Zod v4.
+ *
+ *   semanticBoolean()                              → boolean
+ *   semanticBoolean(z.boolean().optional())        → boolean | undefined
+ *   semanticBoolean(z.boolean().default(false))    → boolean
+ */
+export function semanticBoolean<T extends z.ZodType>(
+  inner: T = z.boolean() as unknown as T,
+) {
+  return z.preprocess(
+    (v: unknown) => (v === 'true' ? true : v === 'false' ? false : v),
+    inner,
+  )
+}

package/utils/semanticNumber.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod/v4'
+
+/**
+ * Number that also accepts numeric string literals like "30", "-5", "3.14".
+ *
+ * Tool inputs arrive as model-generated JSON. The model occasionally quotes
+ * numbers — `"head_limit":"30"` instead of `"head_limit":30` — and z.number()
+ * rejects that with a type error. z.coerce.number() is the wrong fix: it
+ * accepts values like "" or null by converting them via JS Number(), masking
+ * bugs rather than surfacing them.
+ *
+ * Only strings that are valid decimal number literals (matching /^-?\d+(\.\d+)?$/)
+ * are coerced. Anything else passes through and is rejected by the inner schema.
+ *
+ * z.preprocess emits {"type":"number"} to the API schema, so the model is
+ * still told this is a number — the string tolerance is invisible client-side
+ * coercion, not an advertised input shape.
+ *
+ * .optional()/.default() go INSIDE (on the inner schema), not chained after:
+ * chaining them onto ZodPipe widens z.output<> to unknown in Zod v4.
+ *
+ *   semanticNumber()                              → number
+ *   semanticNumber(z.number().optional())         → number | undefined
+ *   semanticNumber(z.number().default(0))         → number
+ */
+export function semanticNumber<T extends z.ZodType>(
+  inner: T = z.number() as unknown as T,
+) {
+  return z.preprocess((v: unknown) => {
+    if (typeof v === 'string' && /^-?\d+(\.\d+)?$/.test(v)) {
+      const n = Number(v)
+      if (Number.isFinite(n)) return n
+    }
+    return v
+  }, inner)
+}

package/utils/semver.ts

@@ -0,0 +1,59 @@
+/**
+ * Semver comparison utilities that use Bun.semver when available
+ * and fall back to the npm `semver` package in Node.js environments.
+ *
+ * Bun.semver.order() is ~20x faster than npm semver comparisons.
+ * The npm semver fallback always uses { loose: true }.
+ */
+
+let _npmSemver: typeof import('semver') | undefined
+
+function getNpmSemver(): typeof import('semver') {
+  if (!_npmSemver) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    _npmSemver = require('semver') as typeof import('semver')
+  }
+  return _npmSemver
+}
+
+export function gt(a: string, b: string): boolean {
+  if (typeof Bun !== 'undefined') {
+    return Bun.semver.order(a, b) === 1
+  }
+  return getNpmSemver().gt(a, b, { loose: true })
+}
+
+export function gte(a: string, b: string): boolean {
+  if (typeof Bun !== 'undefined') {
+    return Bun.semver.order(a, b) >= 0
+  }
+  return getNpmSemver().gte(a, b, { loose: true })
+}
+
+export function lt(a: string, b: string): boolean {
+  if (typeof Bun !== 'undefined') {
+    return Bun.semver.order(a, b) === -1
+  }
+  return getNpmSemver().lt(a, b, { loose: true })
+}
+
+export function lte(a: string, b: string): boolean {
+  if (typeof Bun !== 'undefined') {
+    return Bun.semver.order(a, b) <= 0
+  }
+  return getNpmSemver().lte(a, b, { loose: true })
+}
+
+export function satisfies(version: string, range: string): boolean {
+  if (typeof Bun !== 'undefined') {
+    return Bun.semver.satisfies(version, range)
+  }
+  return getNpmSemver().satisfies(version, range, { loose: true })
+}
+
+export function order(a: string, b: string): -1 | 0 | 1 {
+  if (typeof Bun !== 'undefined') {
+    return Bun.semver.order(a, b)
+  }
+  return getNpmSemver().compare(a, b, { loose: true })
+}

package/utils/sequential.ts

@@ -0,0 +1,56 @@
+type QueueItem<T extends unknown[], R> = {
+  args: T
+  resolve: (value: R) => void
+  reject: (reason?: unknown) => void
+  context: unknown
+}
+
+/**
+ * Creates a sequential execution wrapper for async functions to prevent race conditions.
+ * Ensures that concurrent calls to the wrapped function are executed one at a time
+ * in the order they were received, while preserving the correct return values.
+ *
+ * This is useful for operations that must be performed sequentially, such as
+ * file writes or database updates that could cause conflicts if executed concurrently.
+ *
+ * @param fn - The async function to wrap with sequential execution
+ * @returns A wrapped version of the function that executes calls sequentially
+ */
+export function sequential<T extends unknown[], R>(
+  fn: (...args: T) => Promise<R>,
+): (...args: T) => Promise<R> {
+  const queue: QueueItem<T, R>[] = []
+  let processing = false
+
+  async function processQueue(): Promise<void> {
+    if (processing) return
+    if (queue.length === 0) return
+
+    processing = true
+
+    while (queue.length > 0) {
+      const { args, resolve, reject, context } = queue.shift()!
+
+      try {
+        const result = await fn.apply(context, args)
+        resolve(result)
+      } catch (error) {
+        reject(error)
+      }
+    }
+
+    processing = false
+
+    // Check if new items were added while we were processing
+    if (queue.length > 0) {
+      void processQueue()
+    }
+  }
+
+  return function (this: unknown, ...args: T): Promise<R> {
+    return new Promise((resolve, reject) => {
+      queue.push({ args, resolve, reject, context: this })
+      void processQueue()
+    })
+  }
+}

package/utils/sessionActivity.ts

@@ -0,0 +1,133 @@
+/**
+ * Session activity tracking with refcount-based heartbeat timer.
+ *
+ * The transport registers its keep-alive sender via registerSessionActivityCallback().
+ * Callers (API streaming, tool execution) bracket their work with
+ * startSessionActivity() / stopSessionActivity(). When the refcount is >0 a
+ * periodic timer fires the registered callback every 30 seconds to keep the
+ * container alive.
+ *
+ * Sending keep-alives is gated behind CLAUDE_CODE_REMOTE_SEND_KEEPALIVES.
+ * Diagnostic logging always fires to help diagnose idle gaps.
+ */
+
+import { registerCleanup } from './cleanupRegistry.js'
+import { logForDiagnosticsNoPII } from './diagLogs.js'
+import { isEnvTruthy } from './envUtils.js'
+
+const SESSION_ACTIVITY_INTERVAL_MS = 30_000
+
+export type SessionActivityReason = 'api_call' | 'tool_exec'
+
+let activityCallback: (() => void) | null = null
+let refcount = 0
+const activeReasons = new Map<SessionActivityReason, number>()
+let oldestActivityStartedAt: number | null = null
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null
+let idleTimer: ReturnType<typeof setTimeout> | null = null
+let cleanupRegistered = false
+
+function startHeartbeatTimer(): void {
+  clearIdleTimer()
+  heartbeatTimer = setInterval(() => {
+    logForDiagnosticsNoPII('debug', 'session_keepalive_heartbeat', {
+      refcount,
+    })
+    if (isEnvTruthy(process.env.CLAUDE_CODE_REMOTE_SEND_KEEPALIVES)) {
+      activityCallback?.()
+    }
+  }, SESSION_ACTIVITY_INTERVAL_MS)
+}
+
+function startIdleTimer(): void {
+  clearIdleTimer()
+  if (activityCallback === null) {
+    return
+  }
+  idleTimer = setTimeout(() => {
+    logForDiagnosticsNoPII('info', 'session_idle_30s')
+    idleTimer = null
+  }, SESSION_ACTIVITY_INTERVAL_MS)
+}
+
+function clearIdleTimer(): void {
+  if (idleTimer !== null) {
+    clearTimeout(idleTimer)
+    idleTimer = null
+  }
+}
+
+export function registerSessionActivityCallback(cb: () => void): void {
+  activityCallback = cb
+  // Restart timer if work is already in progress (e.g. reconnect during streaming)
+  if (refcount > 0 && heartbeatTimer === null) {
+    startHeartbeatTimer()
+  }
+}
+
+export function unregisterSessionActivityCallback(): void {
+  activityCallback = null
+  // Stop timer if the callback is removed
+  if (heartbeatTimer !== null) {
+    clearInterval(heartbeatTimer)
+    heartbeatTimer = null
+  }
+  clearIdleTimer()
+}
+
+export function sendSessionActivitySignal(): void {
+  if (isEnvTruthy(process.env.CLAUDE_CODE_REMOTE_SEND_KEEPALIVES)) {
+    activityCallback?.()
+  }
+}
+
+export function isSessionActivityTrackingActive(): boolean {
+  return activityCallback !== null
+}
+
+/**
+ * Increment the activity refcount. When it transitions from 0→1 and a callback
+ * is registered, start a periodic heartbeat timer.
+ */
+export function startSessionActivity(reason: SessionActivityReason): void {
+  refcount++
+  activeReasons.set(reason, (activeReasons.get(reason) ?? 0) + 1)
+  if (refcount === 1) {
+    oldestActivityStartedAt = Date.now()
+    if (activityCallback !== null && heartbeatTimer === null) {
+      startHeartbeatTimer()
+    }
+  }
+  if (!cleanupRegistered) {
+    cleanupRegistered = true
+    registerCleanup(async () => {
+      logForDiagnosticsNoPII('info', 'session_activity_at_shutdown', {
+        refcount,
+        active: Object.fromEntries(activeReasons),
+        // Only meaningful while work is in-flight; stale otherwise.
+        oldest_activity_ms:
+          refcount > 0 && oldestActivityStartedAt !== null
+            ? Date.now() - oldestActivityStartedAt
+            : null,
+      })
+    })
+  }
+}
+
+/**
+ * Decrement the activity refcount. When it reaches 0, stop the heartbeat timer
+ * and start an idle timer that logs after 30s of inactivity.
+ */
+export function stopSessionActivity(reason: SessionActivityReason): void {
+  if (refcount > 0) {
+    refcount--
+  }
+  const n = (activeReasons.get(reason) ?? 0) - 1
+  if (n > 0) activeReasons.set(reason, n)
+  else activeReasons.delete(reason)
+  if (refcount === 0 && heartbeatTimer !== null) {
+    clearInterval(heartbeatTimer)
+    heartbeatTimer = null
+    startIdleTimer()
+  }
+}

package/utils/sessionEnvVars.ts

@@ -0,0 +1,22 @@
+/**
+ * Session-scoped environment variables set via /env.
+ * Applied only to spawned child processes (via bash provider env overrides),
+ * not to the REPL process itself.
+ */
+const sessionEnvVars = new Map<string, string>()
+
+export function getSessionEnvVars(): ReadonlyMap<string, string> {
+  return sessionEnvVars
+}
+
+export function setSessionEnvVar(name: string, value: string): void {
+  sessionEnvVars.set(name, value)
+}
+
+export function deleteSessionEnvVar(name: string): void {
+  sessionEnvVars.delete(name)
+}
+
+export function clearSessionEnvVars(): void {
+  sessionEnvVars.clear()
+}