feat: Add env dependency injection architecture

Overhaul environment variable handling to use structured dependency injection,
making code more testable and removing direct process.env.* calls.

Architecture:
- Base types (BaseEnv, BaseCiEnv) in common that packages extend
- Package-specific types: CliEnv, SdkEnv, EvalsCiEnv
- Helper functions: getCliEnv(), getSdkEnv(), getBaseEnv()
- Test helpers: createTestCliEnv(), createTestSdkEnv(), etc.

New files:
- common/src/types/contracts/env.ts - Base type definitions
- common/src/env-process.ts - Base env helpers
- common/src/env-ci.ts - CI env helpers
- cli/src/types/env.ts, cli/src/utils/env.ts - CLI env
- sdk/src/types/env.ts, sdk/src/env.ts - SDK env
- evals/types/env.ts - Evals env

Migrated files:
- CLI utilities (theme-system, open-file, detect-shell, etc.)
- Agent runtime (linkup-api, codebuff-web-api, tool handlers)
- SDK impl/agent-runtime.ts

Other changes:
- Added clientEnv and ciEnv to AgentRuntimeDeps
- Added ESLint rules to enforce package-specific env types
- Added 62 unit tests for env helpers
- Documented architecture in knowledge.md

Author: brandonkachen

cli/src/__tests__/utils/env.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect, afterEach } from 'bun:test'
+
+import { getCliEnv, createTestCliEnv } from '../../utils/env'
+
+describe('cli/utils/env', () => {
+  describe('getCliEnv', () => {
+    const originalEnv = { ...process.env }
+
+    afterEach(() => {
+      // Restore original env
+      Object.keys(process.env).forEach((key) => {
+        if (!(key in originalEnv)) {
+          delete process.env[key]
+        }
+      })
+      Object.assign(process.env, originalEnv)
+    })
+
+    test('returns current process.env values for base vars', () => {
+      process.env.SHELL = '/bin/zsh'
+      process.env.HOME = '/Users/testuser'
+      const env = getCliEnv()
+      expect(env.SHELL).toBe('/bin/zsh')
+      expect(env.HOME).toBe('/Users/testuser')
+    })
+
+    test('returns current process.env values for terminal detection vars', () => {
+      process.env.TERM_PROGRAM = 'iTerm.app'
+      process.env.KITTY_WINDOW_ID = '12345'
+      const env = getCliEnv()
+      expect(env.TERM_PROGRAM).toBe('iTerm.app')
+      expect(env.KITTY_WINDOW_ID).toBe('12345')
+    })
+
+    test('returns current process.env values for VS Code detection', () => {
+      process.env.VSCODE_PID = '1234'
+      process.env.VSCODE_THEME_KIND = 'dark'
+      const env = getCliEnv()
+      expect(env.VSCODE_PID).toBe('1234')
+      expect(env.VSCODE_THEME_KIND).toBe('dark')
+    })
+
+    test('returns current process.env values for Cursor detection', () => {
+      process.env.CURSOR_PORT = '5678'
+      process.env.CURSOR = 'true'
+      const env = getCliEnv()
+      expect(env.CURSOR_PORT).toBe('5678')
+      expect(env.CURSOR).toBe('true')
+    })
+
+    test('returns current process.env values for JetBrains detection', () => {
+      process.env.TERMINAL_EMULATOR = 'JetBrains-JediTerm'
+      process.env.IDE_CONFIG_DIR = '/path/to/idea'
+      const env = getCliEnv()
+      expect(env.TERMINAL_EMULATOR).toBe('JetBrains-JediTerm')
+      expect(env.IDE_CONFIG_DIR).toBe('/path/to/idea')
+    })
+
+    test('returns current process.env values for editor preferences', () => {
+      process.env.EDITOR = 'vim'
+      process.env.CODEBUFF_CLI_EDITOR = 'code'
+      const env = getCliEnv()
+      expect(env.EDITOR).toBe('vim')
+      expect(env.CODEBUFF_CLI_EDITOR).toBe('code')
+    })
+
+    test('returns current process.env values for theme preferences', () => {
+      process.env.OPEN_TUI_THEME = 'dark'
+      const env = getCliEnv()
+      expect(env.OPEN_TUI_THEME).toBe('dark')
+    })
+
+    test('returns current process.env values for binary build config', () => {
+      process.env.CODEBUFF_IS_BINARY = 'true'
+      process.env.CODEBUFF_CLI_VERSION = '1.0.0'
+      const env = getCliEnv()
+      expect(env.CODEBUFF_IS_BINARY).toBe('true')
+      expect(env.CODEBUFF_CLI_VERSION).toBe('1.0.0')
+    })
+
+    test('returns undefined for unset env vars', () => {
+      delete process.env.KITTY_WINDOW_ID
+      delete process.env.VSCODE_PID
+      const env = getCliEnv()
+      expect(env.KITTY_WINDOW_ID).toBeUndefined()
+      expect(env.VSCODE_PID).toBeUndefined()
+    })
+
+    test('returns a snapshot that does not change when process.env changes', () => {
+      process.env.TERM_PROGRAM = 'iTerm.app'
+      const env = getCliEnv()
+      process.env.TERM_PROGRAM = 'vscode'
+      expect(env.TERM_PROGRAM).toBe('iTerm.app')
+    })
+  })
+
+  describe('createTestCliEnv', () => {
+    test('returns a CliEnv with default test values', () => {
+      const env = createTestCliEnv()
+      expect(env.HOME).toBe('/home/test')
+      expect(env.NODE_ENV).toBe('test')
+      expect(env.TERM).toBe('xterm-256color')
+      expect(env.PATH).toBe('/usr/bin')
+    })
+
+    test('returns undefined for CLI-specific vars by default', () => {
+      const env = createTestCliEnv()
+      expect(env.KITTY_WINDOW_ID).toBeUndefined()
+      expect(env.VSCODE_PID).toBeUndefined()
+      expect(env.CURSOR_PORT).toBeUndefined()
+      expect(env.IDE_CONFIG_DIR).toBeUndefined()
+      expect(env.CODEBUFF_IS_BINARY).toBeUndefined()
+    })
+
+    test('allows overriding terminal detection vars', () => {
+      const env = createTestCliEnv({
+        TERM_PROGRAM: 'iTerm.app',
+        KITTY_WINDOW_ID: '12345',
+        SIXEL_SUPPORT: 'true',
+      })
+      expect(env.TERM_PROGRAM).toBe('iTerm.app')
+      expect(env.KITTY_WINDOW_ID).toBe('12345')
+      expect(env.SIXEL_SUPPORT).toBe('true')
+    })
+
+    test('allows overriding VS Code detection vars', () => {
+      const env = createTestCliEnv({
+        VSCODE_PID: '1234',
+        VSCODE_THEME_KIND: 'dark',
+        VSCODE_GIT_IPC_HANDLE: '/tmp/vscode-git',
+      })
+      expect(env.VSCODE_PID).toBe('1234')
+      expect(env.VSCODE_THEME_KIND).toBe('dark')
+      expect(env.VSCODE_GIT_IPC_HANDLE).toBe('/tmp/vscode-git')
+    })
+
+    test('allows overriding editor preferences', () => {
+      const env = createTestCliEnv({
+        EDITOR: 'vim',
+        VISUAL: 'code',
+        CODEBUFF_CLI_EDITOR: 'cursor',
+      })
+      expect(env.EDITOR).toBe('vim')
+      expect(env.VISUAL).toBe('code')
+      expect(env.CODEBUFF_CLI_EDITOR).toBe('cursor')
+    })
+
+    test('allows overriding binary build config', () => {
+      const env = createTestCliEnv({
+        CODEBUFF_IS_BINARY: 'true',
+        CODEBUFF_CLI_VERSION: '2.0.0',
+        CODEBUFF_CLI_TARGET: 'darwin-arm64',
+      })
+      expect(env.CODEBUFF_IS_BINARY).toBe('true')
+      expect(env.CODEBUFF_CLI_VERSION).toBe('2.0.0')
+      expect(env.CODEBUFF_CLI_TARGET).toBe('darwin-arm64')
+    })
+
+    test('allows overriding default values', () => {
+      const env = createTestCliEnv({
+        HOME: '/custom/home',
+        NODE_ENV: 'production',
+      })
+      expect(env.HOME).toBe('/custom/home')
+      expect(env.NODE_ENV).toBe('production')
+    })
+  })
+})

cli/src/hooks/use-usage-query.ts

@@ -1,8 +1,10 @@
+import { env } from '@codebuff/common/env'
 import { useQuery, useQueryClient } from '@tanstack/react-query'
 
 import { getAuthToken } from '../utils/auth'
 import { logger as defaultLogger } from '../utils/logger'
 
+import type { ClientEnv } from '@codebuff/common/types/contracts/env'
 import type { Logger } from '@codebuff/common/types/contracts/logger'
 
 // Query keys for type-safe cache management
@@ -26,6 +28,7 @@ interface UsageResponse {
 interface FetchUsageParams {
   authToken: string
   logger?: Logger
+  clientEnv?: ClientEnv
 }
 
 /**
@@ -34,8 +37,9 @@ interface FetchUsageParams {
 export async function fetchUsageData({
   authToken,
   logger = defaultLogger,
+  clientEnv = env,
 }: FetchUsageParams): Promise<UsageResponse> {
-  const appUrl = process.env.NEXT_PUBLIC_CODEBUFF_APP_URL
+  const appUrl = clientEnv.NEXT_PUBLIC_CODEBUFF_APP_URL
   if (!appUrl) {
     throw new Error('NEXT_PUBLIC_CODEBUFF_APP_URL is not set')
   }

cli/src/hooks/use-why-did-you-update.ts

@@ -1,5 +1,7 @@
 import { useEffect, useRef } from 'react'
 
+import { getCliEnv } from '../utils/env'
+
 import { logger } from '../utils/logger'
 
 /**
@@ -35,9 +37,10 @@ export function useWhyDidYouUpdate<T extends Record<string, any>>(
     enabled?: boolean
   } = {},
 ): void {
+  const env = getCliEnv()
   const {
     logLevel = 'info',
-    enabled = process.env.NODE_ENV === 'development',
+    enabled = env.NODE_ENV === 'development',
   } = options
 
   const previousProps = useRef<T | null>(null)
@@ -115,7 +118,8 @@ export function useWhyDidYouUpdateById<T extends Record<string, any>>(
     enabled?: boolean
   } = {},
 ): void {
-  const { logLevel = 'info', enabled = process.env.ENVIRONMENT === 'dev' } =
+  const env = getCliEnv()
+  const { logLevel = 'info', enabled = env.NODE_ENV === 'development' } =
     options
 
   const previousProps = useRef<T | null>(null)

cli/src/native/ripgrep.ts

@@ -1,13 +1,15 @@
 import path from 'path'
 
+import { getCliEnv } from '../utils/env'
 import { getBundledRgPath } from '@codebuff/sdk'
 import { spawnSync } from 'bun'
 
 import { logger } from '../utils/logger'
 
 const getRipgrepPath = async (): Promise<string> => {
+  const env = getCliEnv()
   // In dev mode, use the SDK's bundled ripgrep binary
-  if (!process.env.CODEBUFF_IS_BINARY) {
+  if (!env.CODEBUFF_IS_BINARY) {
     return getBundledRgPath()
   }
 

cli/src/types/env.ts

@@ -0,0 +1,70 @@
+/**
+ * CLI-specific environment variable types.
+ *
+ * Extends base types from common with CLI-specific vars for:
+ * - Terminal/IDE detection
+ * - Editor preferences
+ * - Binary build configuration
+ */
+
+import type {
+  BaseEnv,
+  ClientEnv,
+} from '@codebuff/common/types/contracts/env'
+
+/**
+ * CLI-specific env vars for terminal/IDE detection and editor preferences.
+ */
+export type CliEnv = BaseEnv & {
+  // Terminal-specific
+  KITTY_WINDOW_ID?: string
+  SIXEL_SUPPORT?: string
+  ZED_NODE_ENV?: string
+
+  // VS Code family detection
+  VSCODE_THEME_KIND?: string
+  VSCODE_COLOR_THEME_KIND?: string
+  VSCODE_GIT_IPC_HANDLE?: string
+  VSCODE_PID?: string
+  VSCODE_CWD?: string
+  VSCODE_NLS_CONFIG?: string
+
+  // Cursor editor detection
+  CURSOR_PORT?: string
+  CURSOR?: string
+
+  // JetBrains IDE detection
+  JETBRAINS_REMOTE_RUN?: string
+  IDEA_INITIAL_DIRECTORY?: string
+  IDE_CONFIG_DIR?: string
+  JB_IDE_CONFIG_DIR?: string
+
+  // Editor preferences
+  VISUAL?: string
+  EDITOR?: string
+  CODEBUFF_CLI_EDITOR?: string
+  CODEBUFF_EDITOR?: string
+
+  // Theme preferences
+  OPEN_TUI_THEME?: string
+  OPENTUI_THEME?: string
+
+  // Codebuff CLI-specific (set during binary build)
+  CODEBUFF_IS_BINARY?: string
+  CODEBUFF_CLI_VERSION?: string
+  CODEBUFF_CLI_TARGET?: string
+  CODEBUFF_RG_PATH?: string
+}
+
+/**
+ * Full CLI env deps combining client env and CLI env.
+ */
+export type CliEnvDeps = {
+  clientEnv: ClientEnv
+  env: CliEnv
+}
+
+/**
+ * Function type for getting CLI env values.
+ */
+export type GetCliEnvFn = () => CliEnv

cli/src/utils/codebuff-client.ts

@@ -1,3 +1,4 @@
+import { getCliEnv } from './env'
 import { API_KEY_ENV_VAR } from '@codebuff/common/old-constants'
 import { AskUserBridge } from '@codebuff/common/utils/ask-user-bridge'
 import { CodebuffClient } from '@codebuff/sdk'
@@ -58,9 +59,11 @@ export async function getCodebuffClient(): Promise<CodebuffClient | null> {
     const projectRoot = getProjectRoot()
 
     // Set up ripgrep path for SDK to use
-    if (process.env.CODEBUFF_IS_BINARY) {
+    const env = getCliEnv()
+    if (env.CODEBUFF_IS_BINARY) {
       try {
         const rgPath = await getRgPath()
+        // Note: We still set process.env here because SDK reads from it
         process.env.CODEBUFF_RG_PATH = rgPath
       } catch (error) {
         logger.error(error, 'Failed to set up ripgrep binary for SDK')

cli/src/utils/detect-shell.ts

@@ -1,5 +1,8 @@
 import { execSync } from 'child_process'
 
+import type { CliEnv } from '../types/env'
+import { getCliEnv } from './env'
+
 type KnownShell =
   | 'bash'
   | 'zsh'
@@ -23,24 +26,24 @@ const SHELL_ALIASES: Record<string, KnownShell> = {
   'powershell.exe': 'powershell',
 }
 
-export function detectShell(): ShellName {
+export function detectShell(env: CliEnv = getCliEnv()): ShellName {
   if (cachedShell) {
     return cachedShell
   }
 
   const detected =
-    detectFromEnvironment() ?? detectViaParentProcessInspection() ?? 'unknown'
+    detectFromEnvironment(env) ?? detectViaParentProcessInspection() ?? 'unknown'
   cachedShell = detected
   return detected
 }
 
-function detectFromEnvironment(): ShellName | null {
+function detectFromEnvironment(env: CliEnv): ShellName | null {
   const candidates: Array<string | undefined> = []
 
   if (process.platform === 'win32') {
-    candidates.push(process.env.COMSPEC, process.env.SHELL)
+    candidates.push(env.COMSPEC, env.SHELL)
   } else {
-    candidates.push(process.env.SHELL)
+    candidates.push(env.SHELL)
   }
 
   for (const candidate of candidates) {