feat(env): enforce package boundaries + test defaults

Typecheck-time enforcement (scripts/check-env-architecture.ts): - Ban
common/src/** from importing @codebuff/internal/* (layering/secrets) -
Ban 'use client' modules from importing @codebuff/internal/env - Enforce
CLI/SDK process.env access through designated env helpers

Runtime guards (@codebuff/internal/env conditional exports): -
browser/react-server conditions route to 'server-only' stubs - Provides
defense-in-depth for Next.js bundle boundaries

Other changes: - Route CLI/SDK process.env access through env helpers -
Preload safe NEXT_PUBLIC_* defaults in test setup - Clarify test-only
agent runtime fixtures

Author: brandonkachen

bunfig.toml

@@ -7,3 +7,4 @@ linkWorkspacePackages = true
 [test]
 # Exclude test repositories from test execution to prevent timeouts
 exclude = ["evals/test-repos/**"]
+preload = ["./sdk/test/setup-env.ts"]

cli/src/commands/router.ts

@@ -1,5 +1,6 @@
 import { runTerminalCommand } from '@codebuff/sdk'
 
+
 import {
   findCommand,
   type RouterParams,
@@ -25,10 +26,9 @@ import {
   createRunTerminalToolResult,
 } from '../utils/bash-messages'
 import { showClipboardMessage } from '../utils/clipboard'
+import { getSystemProcessEnv } from '../utils/env'
 import { getSystemMessage, getUserMessage } from '../utils/message-history'
 
-
-
 /**
  * Run a bash command with automatic ghost/direct mode selection.
  * Uses ghost mode when streaming or chain in progress, otherwise adds directly to chat history.
@@ -74,7 +74,7 @@ export function runBashCommand(command: string) {
     process_type: 'SYNC',
     cwd: commandCwd,
     timeout_seconds: -1,
-    env: process.env,
+    env: getSystemProcessEnv(),
   })
     .then(([{ value }]) => {
       const stdout = 'stdout' in value ? value.stdout || '' : ''

cli/src/hooks/use-theme.tsx

@@ -7,6 +7,7 @@
 import { create } from 'zustand'
 
 import { themeConfig, buildTheme } from '../utils/theme-config'
+import { getCliEnv } from '../utils/env'
 import {
   chatThemes,
   cloneChatTheme,
@@ -58,7 +59,8 @@ const THEME_PRIORITY: ThemeDetector[] = [
 ]
 
 export const detectSystemTheme = (): ThemeName => {
-  const envPreference = process.env.OPEN_TUI_THEME ?? process.env.OPENTUI_THEME
+  const env = getCliEnv()
+  const envPreference = env.OPEN_TUI_THEME ?? env.OPENTUI_THEME
   const normalizedEnv = envPreference?.toLowerCase()
 
   if (normalizedEnv === 'dark' || normalizedEnv === 'light') {

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

@@ -24,7 +24,7 @@ import { logger } from '../utils/logger'
  * function MyComponent(props: MyProps) {
  *   useWhyDidYouUpdate('MyComponent', props, {
  *     logLevel: 'debug',
- *     enabled: process.env.NODE_ENV === 'development'
+ *     enabled: getCliEnv().NODE_ENV === 'development'
  *   })
  *   return <div>...</div>
  * }

cli/src/types/env.ts

@@ -20,6 +20,8 @@ export type CliEnv = BaseEnv & {
   KITTY_WINDOW_ID?: string
   SIXEL_SUPPORT?: string
   ZED_NODE_ENV?: string
+  ZED_TERM?: string
+  ZED_SHELL?: string
 
   // VS Code family detection
   VSCODE_THEME_KIND?: string
@@ -54,6 +56,7 @@ export type CliEnv = BaseEnv & {
   CODEBUFF_CLI_VERSION?: string
   CODEBUFF_CLI_TARGET?: string
   CODEBUFF_RG_PATH?: string
+  CODEBUFF_SCROLL_MULTIPLIER?: string
 }
 
 /**

cli/src/utils/chat-scroll-accel.ts

@@ -1,9 +1,9 @@
 import { Queue } from './arrays'
 import { clamp } from './math'
+import { getCliEnv } from './env'
 
 import type { ScrollAcceleration } from '@opentui/core'
-
-const SCROLL_MULTIPLIER = 'CODEBUFF_SCROLL_MULTIPLIER'
+import type { CliEnv } from '../types/env'
 
 const ENVIRONMENT_TYPE_VARS = [
   'TERM_PROGRAM',
@@ -30,18 +30,20 @@ type ScrollEnvironment = {
   multiplier: number
 }
 
-const resolveScrollEnvironment = (): ScrollEnvironment => {
-  let multiplier = parseFloat(process.env[SCROLL_MULTIPLIER] ?? '')
+const resolveScrollEnvironment = (
+  env: CliEnv = getCliEnv(),
+): ScrollEnvironment => {
+  let multiplier = parseFloat(env.CODEBUFF_SCROLL_MULTIPLIER ?? '')
 
   if (Number.isNaN(multiplier)) {
     multiplier = 1
   }
 
   for (const hintVar of ENVIRONMENT_TYPE_VARS) {
-    const value = process.env[hintVar]
-    for (const env of ENVIRONMENTS) {
-      if (value?.includes(env)) {
-        return { type: env, multiplier }
+    const value = env[hintVar]
+    for (const environment of ENVIRONMENTS) {
+      if (value?.includes(environment)) {
+        return { type: environment, multiplier }
       }
     }
   }

cli/src/utils/codebuff-client.ts

@@ -1,9 +1,9 @@
-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'
 
 import { getAuthTokenDetails } from './auth'
+import { getCliEnv, getSystemProcessEnv } from './env'
 import { loadAgentDefinitions } from './local-agent-registry'
 import { logger } from './logger'
 import { getRgPath } from '../native/ripgrep'
@@ -64,7 +64,7 @@ export async function getCodebuffClient(): Promise<CodebuffClient | null> {
       try {
         const rgPath = await getRgPath()
         // Note: We still set process.env here because SDK reads from it
-        process.env.CODEBUFF_RG_PATH = rgPath
+        getSystemProcessEnv().CODEBUFF_RG_PATH = rgPath
       } catch (error) {
         logger.error(error, 'Failed to set up ripgrep binary for SDK')
       }

cli/src/utils/env.ts

@@ -5,10 +5,7 @@
  * process env with CLI-specific vars for terminal/IDE detection.
  */
 
-import {
-  getBaseEnv,
-  createTestBaseEnv,
-} from '@codebuff/common/env-process'
+import { getBaseEnv, createTestBaseEnv } from '@codebuff/common/env-process'
 
 import type { CliEnv } from '../types/env'
 
@@ -23,6 +20,8 @@ export const getCliEnv = (): CliEnv => ({
   KITTY_WINDOW_ID: process.env.KITTY_WINDOW_ID,
   SIXEL_SUPPORT: process.env.SIXEL_SUPPORT,
   ZED_NODE_ENV: process.env.ZED_NODE_ENV,
+  ZED_TERM: process.env.ZED_TERM,
+  ZED_SHELL: process.env.ZED_SHELL,
 
   // VS Code family detection
   VSCODE_THEME_KIND: process.env.VSCODE_THEME_KIND,
@@ -57,21 +56,29 @@ export const getCliEnv = (): CliEnv => ({
   CODEBUFF_CLI_VERSION: process.env.CODEBUFF_CLI_VERSION,
   CODEBUFF_CLI_TARGET: process.env.CODEBUFF_CLI_TARGET,
   CODEBUFF_RG_PATH: process.env.CODEBUFF_RG_PATH,
+  CODEBUFF_SCROLL_MULTIPLIER: process.env.CODEBUFF_SCROLL_MULTIPLIER,
 })
 
+/**
+ * Get the raw system process.env object.
+ * Use this when you need to pass the full environment to subprocesses
+ * or when you need to set environment variables at runtime.
+ */
+export const getSystemProcessEnv = (): NodeJS.ProcessEnv => process.env
+
 /**
  * Create a test CliEnv with optional overrides.
  * Composes from createTestBaseEnv() for DRY.
  */
-export const createTestCliEnv = (
-  overrides: Partial<CliEnv> = {},
-): CliEnv => ({
+export const createTestCliEnv = (overrides: Partial<CliEnv> = {}): CliEnv => ({
   ...createTestBaseEnv(),
 
   // CLI-specific defaults
   KITTY_WINDOW_ID: undefined,
   SIXEL_SUPPORT: undefined,
   ZED_NODE_ENV: undefined,
+  ZED_TERM: undefined,
+  ZED_SHELL: undefined,
   VSCODE_THEME_KIND: undefined,
   VSCODE_COLOR_THEME_KIND: undefined,
   VSCODE_GIT_IPC_HANDLE: undefined,
@@ -94,5 +101,6 @@ export const createTestCliEnv = (
   CODEBUFF_CLI_VERSION: undefined,
   CODEBUFF_CLI_TARGET: undefined,
   CODEBUFF_RG_PATH: undefined,
+  CODEBUFF_SCROLL_MULTIPLIER: undefined,
   ...overrides,
 })

common/src/__tests__/agent-validation.test.ts

@@ -74,39 +74,6 @@ describe('Agent Validation', () => {
       expect(result.templates.brainstormer.id).toBe('brainstormer')
     })
 
-    test.skip('should validate spawnable agents', async () => {
-      const fileContext: ProjectFileContext = {
-        ...mockFileContext,
-        agentTemplates: {
-          'invalid.ts': {
-            id: 'invalid_agent',
-            version: '1.0.0',
-            displayName: 'Invalid',
-            spawnerPrompt: 'Invalid agent',
-            model: 'anthropic/claude-4-sonnet-20250522',
-            systemPrompt: 'Test',
-            instructionsPrompt: 'Test',
-            stepPrompt: 'Test',
-            spawnableAgents: ['nonexistent_agent'],
-            outputMode: 'last_message',
-            includeMessageHistory: true,
-            inheritParentSystemPrompt: false,
-            toolNames: ['end_turn'],
-          },
-        },
-      }
-
-      const result = validateAgents({
-        agentTemplates: fileContext.agentTemplates || {},
-        logger,
-      })
-
-      expect(result.validationErrors).toHaveLength(1)
-      expect(result.validationErrors[0].message).toContain(
-        'Invalid spawnable agents: nonexistent_agent',
-      )
-    })
-
     it('should merge static and dynamic templates', async () => {
       const fileContext: ProjectFileContext = {
         ...mockFileContext,

common/src/env.ts

@@ -1,11 +1,49 @@
-import { clientEnvSchema, clientProcessEnv } from './env-schema'
+import {
+  clientEnvSchema,
+  clientProcessEnv,
+  type ClientInput,
+} from './env-schema'
 
-// Only log environment in non-production
-if (process.env.NEXT_PUBLIC_CB_ENVIRONMENT !== 'prod') {
-  console.log('Using environment:', process.env.NEXT_PUBLIC_CB_ENVIRONMENT)
+const isTestRuntime =
+  process.env.NODE_ENV === 'test' || process.env.BUN_ENV === 'test'
+
+const TEST_ENV_DEFAULTS: ClientInput = {
+  NEXT_PUBLIC_CB_ENVIRONMENT: 'test',
+  NEXT_PUBLIC_CODEBUFF_APP_URL: 'http://localhost:3000',
+  NEXT_PUBLIC_SUPPORT_EMAIL: 'support@codebuff.com',
+  NEXT_PUBLIC_POSTHOG_API_KEY: 'test-posthog-key',
+  NEXT_PUBLIC_POSTHOG_HOST_URL: 'https://us.i.posthog.com',
+  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: 'pk_test_placeholder',
+  NEXT_PUBLIC_STRIPE_CUSTOMER_PORTAL:
+    'https://billing.stripe.com/p/login/test_placeholder',
+  NEXT_PUBLIC_GOOGLE_SITE_VERIFICATION_ID: 'test-verification',
+  NEXT_PUBLIC_WEB_PORT: '3000',
+}
+
+const envInput = isTestRuntime
+  ? { ...TEST_ENV_DEFAULTS, ...clientProcessEnv }
+  : clientProcessEnv
+
+const parsedEnv = clientEnvSchema.safeParse(envInput)
+if (!parsedEnv.success) {
+  throw parsedEnv.error
 }
 
-export const env = clientEnvSchema.parse(clientProcessEnv)
+export const env = parsedEnv.data
+
+// Populate process.env with defaults during tests so direct access works
+if (isTestRuntime) {
+  for (const [key, value] of Object.entries(TEST_ENV_DEFAULTS)) {
+    if (!process.env[key] && typeof value === 'string') {
+      process.env[key] = value
+    }
+  }
+}
+
+// Only log environment in non-production
+if (env.NEXT_PUBLIC_CB_ENVIRONMENT !== 'prod') {
+  console.log('Using environment:', env.NEXT_PUBLIC_CB_ENVIRONMENT)
+}
 
 // Derived environment constants for convenience
 export const IS_DEV = env.NEXT_PUBLIC_CB_ENVIRONMENT === 'dev'