@lkangd/cc-env 1.0.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@lkangd/cc-env",
+  "version": "1.0.0",
+  "description": "",
+  "homepage": "https://github.com/lkangd/cc-env#readme",
+  "bugs": {
+    "url": "https://github.com/lkangd/cc-env/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lkangd/cc-env.git"
+  },
+  "license": "ISC",
+  "author": "",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.2 <21"
+  },
+  "bin": {
+    "cc-env": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@inkjs/ui": "^2.0.0",
+    "commander": "^14.0.0",
+    "cross-spawn": "^7.0.6",
+    "figlet": "^1.11.0",
+    "fs-extra": "^11.3.2",
+    "gradient-string": "^3.0.0",
+    "ink": "^6.3.1",
+    "pino": "^10.0.0",
+    "react": "^19.1.0",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/fs-extra": "^11.0.4",
+    "@types/gradient-string": "^1.1.6",
+    "@types/node": "^20.19.0",
+    "@types/react": "^19.1.10",
+    "execa": "^9.6.0",
+    "react-test-renderer": "^19.2.5",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,337 @@
+import React from 'react'
+import { render } from 'ink'
+import { join } from 'node:path'
+import figlet from 'figlet'
+import gradient from 'gradient-string'
+
+import { Command } from 'commander'
+
+const h = React.createElement
+
+import { createInitCommand } from './commands/init.js'
+import { createPresetCreateCommand } from './commands/preset/create.js'
+import { createDeletePresetCommand } from './commands/preset/delete.js'
+import { PresetDeleteApp } from './ink/preset-delete-app.js'
+import { createShowPresetsCommand } from './commands/preset/show.js'
+import { createRestoreCommand } from './commands/restore.js'
+import { createRunCommand } from './commands/run.js'
+import { findClaudeExecutable } from './core/find-claude.js'
+import { InitApp } from './ink/init-app.js'
+import { renderEnvSummary } from './ink/summary.js'
+import { PresetCreateApp } from './ink/preset-create-app.js'
+import { PresetShowApp } from './ink/preset-show-app.js'
+import { RunPresetSelectApp } from './ink/run-preset-select-app.js'
+import { advanceRestoreFlow, createRestoreFlowState } from './flows/restore-flow.js'
+import { RestoreApp } from './ink/restore-app.js'
+import { CliError } from './core/errors.js'
+import { resolveGlobalRoot } from './core/paths.js'
+import { spawnCommand } from './core/spawn.js'
+import { createClaudeSettingsEnvService } from './services/claude-settings-env-service.js'
+import { createHistoryService } from './services/history-service.js'
+import { createPresetService } from './services/preset-service.js'
+import { createProjectEnvService } from './services/project-env-service.js'
+import { createProjectStateService } from './services/project-state-service.js'
+import { createSettingsEnvService } from './services/settings-env-service.js'
+import { createShellEnvService } from './services/shell-env-service.js'
+
+const program = new Command()
+
+program.name('cc-env').description('Manage runtime environment variables for Claude Code')
+
+const homeDir = process.env.HOME ?? process.cwd()
+const cwd = process.cwd()
+const settingsPath = join(cwd, 'settings.json')
+const globalRoot = resolveGlobalRoot()
+
+const claudeSettingsEnvService = createClaudeSettingsEnvService({ homeDir, cwd })
+const settingsEnvService = createSettingsEnvService({ settingsPath })
+const shellEnvService = createShellEnvService({ homeDir })
+const projectEnvService = createProjectEnvService({ cwd })
+const presetService = createPresetService(globalRoot)
+const historyService = createHistoryService(globalRoot)
+
+async function runRestoreFlow(context: { records: Awaited<ReturnType<typeof historyService.list>>; yes: boolean }) {
+  const state = createRestoreFlowState(context.records)
+  const firstRecord = context.records[0]
+
+  if (!firstRecord) {
+    render(h(RestoreApp, { state }))
+    return undefined
+  }
+
+  if (context.yes) {
+    const selectedRecordState = advanceRestoreFlow(state, {
+      type: 'select-record',
+      timestamp: firstRecord.timestamp
+    })
+
+    if (firstRecord.action === 'init') {
+      const doneState = advanceRestoreFlow(selectedRecordState, { type: 'confirm' })
+      if (doneState.step !== 'done') {
+        return undefined
+      }
+
+      return {
+        confirmed: true,
+        timestamp: firstRecord.timestamp
+      }
+    }
+
+    const confirmState = advanceRestoreFlow(selectedRecordState, {
+      type: 'select-target',
+      targetType: firstRecord.targetType,
+      ...(firstRecord.targetType === 'preset' ? { targetName: firstRecord.targetName } : {})
+    })
+
+    const doneState = advanceRestoreFlow(confirmState, { type: 'confirm' })
+
+    if (doneState.step === 'done' && doneState.targetType === 'preset') {
+      return {
+        confirmed: true,
+        timestamp: doneState.selectedTimestamp,
+        targetType: doneState.targetType,
+        targetName: doneState.targetName
+      }
+    }
+
+    if (doneState.step === 'done') {
+      return {
+        confirmed: true,
+        timestamp: doneState.selectedTimestamp,
+        targetType: doneState.targetType
+      }
+    }
+
+    return undefined
+  }
+
+  let result:
+    | {
+        confirmed: boolean
+        timestamp?: string
+        targetType?: 'settings' | 'preset'
+        targetName?: string
+      }
+    | undefined
+
+  const app = render(
+    h(RestoreApp, {
+      state,
+      onSubmit: value => {
+        result = value
+      }
+    })
+  )
+
+  await app.waitUntilExit()
+  return result
+}
+
+program.exitOverride().configureOutput({
+  writeErr: str => {
+    if (!str.startsWith('error:')) {
+      process.stderr.write(str)
+    }
+  }
+})
+
+program
+  .command('run [args...]')
+  .allowUnknownOption(true)
+  .description('Run claude with merged environment variables')
+  .option('--dry-run', 'Preview the merged env without executing')
+  .option('-y, --yes', 'Auto-select the default preset without interactive prompts')
+  .action((args, options) => {
+    const rawArgs = args ?? []
+
+    return createRunCommand({
+      claudeSettingsEnvService,
+      presetService,
+      projectEnvService,
+      projectStateService: createProjectStateService(globalRoot),
+      findClaude: findClaudeExecutable,
+      renderPresetSelect: async ({ presets, defaultIndex }) => {
+        let result: (typeof presets)[number] | undefined
+        const app = render(
+          h(RunPresetSelectApp, {
+            presets,
+            defaultIndex,
+            onSubmit: preset => {
+              result = preset
+            }
+          })
+        )
+        await app.waitUntilExit()
+        return result
+      },
+      spawnCommand
+    })({
+      args: rawArgs,
+      dryRun: options.dryRun ?? false,
+      yes: options.yes ?? false,
+      cwd
+    })
+  })
+
+program
+  .command('init')
+  .description('Initialize cc-env for the current project')
+  .option('-y, --yes', 'Accept all defaults without interactive prompts')
+  .action(options =>
+    createInitCommand({
+      claudeSettingsEnvService,
+      shellEnvService,
+      historyService,
+      renderEnvSummary,
+      renderFlow: async context => {
+        if (context.yes) {
+          return {
+            selectedKeys: context.requiredKeys,
+            confirmed: true
+          }
+        }
+
+        let result:
+          | {
+              selectedKeys: string[]
+              confirmed: boolean
+            }
+          | undefined
+
+        const app = render(
+          h(InitApp, {
+            ...context,
+            onSubmit: value => {
+              result = value
+            }
+          })
+        )
+
+        await app.waitUntilExit()
+        return result
+      }
+    })({
+      yes: options.yes
+    })
+  )
+
+program
+  .command('restore')
+  .description('Restore environment variables from a previous snapshot')
+  .option('-y, --yes', 'Accept all defaults without interactive prompts')
+  .action(options =>
+    createRestoreCommand({
+      historyService,
+      claudeSettingsEnvService,
+      shellEnvService,
+      settingsEnvService,
+      presetService,
+      renderEnvSummary: renderEnvSummary,
+      renderFlow: context => runRestoreFlow(context)
+    })({
+      yes: options.yes
+    })
+  )
+
+const presetCommand = program.command('preset').description('Manage environment presets')
+presetCommand
+  .command('show')
+  .description('List and view all presets')
+  .action(
+    createShowPresetsCommand({
+      presetService,
+      projectEnvService,
+      renderShow: async presets => {
+        const app = render(h(PresetShowApp, { presets }))
+        await app.waitUntilExit()
+      }
+    })
+  )
+presetCommand
+  .command('delete')
+  .description('Delete a saved preset')
+  .action(
+    createDeletePresetCommand({
+      presetService,
+      projectEnvService,
+      renderDelete: async presets => {
+        let result: (typeof presets)[number] | undefined
+        const app = render(
+          h(PresetDeleteApp, {
+            presets,
+            onSubmit: preset => {
+              result = preset
+            }
+          })
+        )
+        await app.waitUntilExit()
+        return result
+      }
+    })
+  )
+presetCommand
+  .command('create')
+  .description('Create a new environment preset')
+  .action(() =>
+    createPresetCreateCommand({
+      presetService,
+      projectEnvService,
+      renderFlow: async () => {
+        let result: React.ComponentProps<typeof PresetCreateApp>['onSubmit'] extends (result: infer TResult) => unknown
+          ? TResult | undefined
+          : undefined
+        const app = render(
+          h(PresetCreateApp, {
+            onSubmit: value => {
+              result = value
+            },
+            readFile: async filePath => {
+              const { readEnvFile } = await import('./commands/preset/create.js')
+              return readEnvFile(filePath)
+            },
+            globalPresetPath: name => presetService.getPath(name),
+            projectEnvPath: join(cwd, '.cc-env', 'env.json')
+          })
+        )
+
+        await app.waitUntilExit()
+        return result
+      }
+    })({ cwd })
+  )
+
+function printBanner() {
+  const banner = figlet.textSync('CC ENV', { font: 'ANSI Shadow' })
+  const line = '─'.repeat(48)
+  const styled = gradient(['#00d2ff', '#7b2ff7', '#ff0080'])(banner)
+  process.stderr.write(`\n${styled}\x1b[2m\n${line}\x1b[0m\n\n`)
+}
+
+program.hook('preAction', () => {
+  printBanner()
+})
+
+program.parseAsync(process.argv).catch((error: unknown) => {
+  if (error instanceof CliError) {
+    process.stderr.write(`\n  Error: ${error.message}\n\n`)
+    process.exitCode = error.exitCode
+    return
+  }
+
+  if (error && typeof error === 'object' && 'code' in error) {
+    const { code, message } = error as { code?: string; message?: string }
+
+    if (code === 'commander.helpDisplayed') {
+      process.exitCode = 0
+      return
+    }
+
+    const hint = `  Run "cc-env --help" to see available commands and options.\n`
+    const formatted = message?.replace(/^error:\s*/i, '') ?? 'Unknown error'
+    process.stderr.write(`\n  Error: ${formatted}\n\n${hint}\n`)
+    process.exitCode = 1
+    return
+  }
+
+  throw error
+})

package/src/commands/init.ts

@@ -0,0 +1,139 @@
+import React from 'react'
+import { Box, Text } from 'ink'
+
+import { CliError } from '../core/errors.js'
+import { envMapSchema, type EnvMap, type InitHistoryRecord, type SourceEntry } from '../core/schema.js'
+import type { ClaudeSettingsSource } from '../services/claude-settings-env-service.js'
+import type { ShellWriteRecord } from '../services/shell-env-service.js'
+
+const h = React.createElement
+
+const requiredInitKeys = [
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_REASONING_MODEL',
+] as const
+
+type ClaudeSettingsEnvService = {
+  read: () => Promise<ClaudeSettingsSource[]>
+  write: (sources: Array<{ path: string; env: EnvMap }>) => Promise<void>
+}
+
+type ShellEnvService = {
+  write: (env: EnvMap) => Promise<ShellWriteRecord[]>
+}
+
+type HistoryService = {
+  write: (record: InitHistoryRecord) => Promise<unknown>
+}
+
+type InitFlowResult = {
+  selectedKeys: string[]
+  confirmed?: boolean
+}
+
+function omitKeys(env: EnvMap, keys: string[]): EnvMap {
+  return envMapSchema.parse(
+    Object.fromEntries(Object.entries(env).filter(([key]) => !keys.includes(key))),
+  )
+}
+
+export function createInitCommand({
+  claudeSettingsEnvService,
+  shellEnvService,
+  historyService,
+  renderFlow,
+  renderEnvSummary,
+}: {
+  claudeSettingsEnvService: ClaudeSettingsEnvService
+  shellEnvService: ShellEnvService
+  historyService: HistoryService
+  renderFlow: (context: {
+    keys: string[]
+    requiredKeys: string[]
+    yes: boolean
+    sourceFiles: string[]
+  }) => Promise<InitFlowResult | void> | InitFlowResult | void
+  renderEnvSummary: (props: {
+    title: string
+    env: EnvMap
+    fromFiles?: string[]
+    toFiles?: string[]
+    footer?: React.ReactNode
+  }) => Promise<void>
+}) {
+  return async function init({ yes = false }: { yes?: boolean } = {}): Promise<void> {
+    const sources = await claudeSettingsEnvService.read()
+
+    if (sources.every((s) => !s.exists)) {
+      throw new CliError('No Claude settings files were found')
+    }
+
+    const effectiveEnv = envMapSchema.parse(
+      sources.reduce<Record<string, unknown>>((acc, source) => ({ ...acc, ...source.env }), {}),
+    )
+    const keys = Object.keys(effectiveEnv).sort()
+    const requiredKeys = requiredInitKeys.filter((key) => key in effectiveEnv)
+    const sourceFiles = sources.map((s) => s.path)
+    const result = await renderFlow({ keys, requiredKeys, yes, sourceFiles })
+
+    if (!result?.confirmed) {
+      return
+    }
+
+    const migratedEnv = envMapSchema.parse(
+      Object.fromEntries(
+        result.selectedKeys
+          .filter((key) => key in effectiveEnv)
+          .map((key) => [key, effectiveEnv[key]]),
+      ),
+    )
+
+    if (Object.keys(migratedEnv).length === 0) {
+      throw new CliError('No selected env values found to migrate')
+    }
+
+    const initSources: SourceEntry[] = sources.map((source) => ({
+      file: source.path,
+      backup: envMapSchema.parse(
+        Object.fromEntries(
+          result.selectedKeys
+            .filter((key) => key in source.env)
+            .map((key) => [key, source.env[key]]),
+        ),
+      ),
+    }))
+
+    const timestamp = new Date().toISOString()
+    const shellWrites = await shellEnvService.write(migratedEnv)
+
+    await historyService.write({
+      timestamp,
+      action: 'init',
+      migratedKeys: result.selectedKeys,
+      sources: initSources,
+      shellWrites,
+    })
+
+    await claudeSettingsEnvService.write(
+      sources.map((source) => ({
+        path: source.path,
+        env: omitKeys(source.env, result.selectedKeys),
+      })),
+    )
+
+    await renderEnvSummary({
+      title: 'Migrated',
+      env: migratedEnv,
+      fromFiles: initSources.map((s) => s.file),
+      toFiles: shellWrites.map((sw) => sw.filePath),
+      footer: h(Box, { flexDirection: 'column' },
+        h(Text, { color: 'green' }, 'Init complete'),
+        h(Text, { bold: true, color: 'green' }, 'Please restart your terminal for the migrated environment variables to take effect.'),
+      ),
+    })
+  }
+}

package/src/commands/preset/create.ts

@@ -0,0 +1,96 @@
+import { readFile } from 'node:fs/promises'
+import { extname } from 'node:path'
+
+import { parse as parseYaml } from 'yaml'
+
+import { CliError } from '../../core/errors.js'
+import { ensureGitignoreEntry } from '../../core/gitignore.js'
+import { type EnvMap } from '../../core/schema.js'
+import { toProcessEnvMap } from '../../core/process-env.js'
+import type { PresetCreateAppResult } from '../../ink/preset-create-app.js'
+
+type PresetService = {
+  write: (preset: {
+    name: string
+    createdAt: string
+    updatedAt: string
+    env: EnvMap
+  }) => Promise<unknown>
+}
+
+type ProjectEnvService = {
+  write: (env: EnvMap, meta?: { name?: string; createdAt?: string; updatedAt?: string }) => Promise<unknown>
+}
+
+export async function readEnvFile(filePath: string): Promise<{ allKeys: string[]; env: EnvMap }> {
+  try {
+    const content = await readFile(filePath, 'utf8')
+    const extension = extname(filePath).toLowerCase()
+
+    if (extension !== '.yaml' && extension !== '.yml' && extension !== '.json') {
+      throw new CliError(`Unsupported file format: ${extension}`, 2)
+    }
+
+    const parsed = extension === '.yaml' || extension === '.yml'
+      ? parseYaml(content)
+      : JSON.parse(content)
+
+    const raw = (parsed ?? {}) as Record<string, unknown>
+    const source = extension === '.json'
+      && raw
+      && typeof raw === 'object'
+      && 'env' in raw
+      && raw.env
+      && typeof raw.env === 'object'
+      && !Array.isArray(raw.env)
+      ? raw.env as Record<string, unknown>
+      : raw
+
+    const env = toProcessEnvMap(source)
+    return {
+      allKeys: Object.keys(env),
+      env,
+    }
+  } catch (error) {
+    if (error instanceof CliError) throw error
+    throw new CliError(`Failed to read env file: ${filePath}`, 2)
+  }
+}
+
+export function createPresetCreateCommand({
+  presetService,
+  projectEnvService,
+  renderFlow,
+  ensureGitignore = (dir, entry) => ensureGitignoreEntry(dir, entry),
+}: {
+  presetService: PresetService
+  projectEnvService: ProjectEnvService
+  renderFlow: () => Promise<PresetCreateAppResult | void>
+  ensureGitignore?: (dir: string, entry: string) => Promise<void>
+}) {
+  return async function createPreset({ cwd }: { cwd: string }): Promise<void> {
+    const result = await renderFlow()
+
+    if (!result) return
+
+    const selectedEnv: EnvMap = {}
+    for (const key of result.selectedKeys) {
+      selectedEnv[key] = result.env[key] ?? ''
+    }
+
+    const timestamp = new Date().toISOString()
+
+    if (result.destination === 'project') {
+      await projectEnvService.write(selectedEnv, { name: result.presetName, createdAt: timestamp, updatedAt: timestamp })
+      await ensureGitignore(cwd, '.cc-env')
+      return
+    }
+
+    await presetService.write({
+      name: result.presetName,
+      createdAt: timestamp,
+      updatedAt: timestamp,
+      env: selectedEnv,
+    })
+  }
+}

package/src/commands/preset/delete.ts

@@ -0,0 +1,62 @@
+import type { EnvMap } from '../../core/schema.js'
+
+export type PresetSource = 'global' | 'project'
+
+type PresetService = {
+  listNames: () => Promise<string[]>
+  read: (name: string) => Promise<{ env: EnvMap }>
+  remove: (name: string) => Promise<void>
+}
+
+type ProjectEnvService = {
+  readWithMeta: () => Promise<{ env: EnvMap; name?: string | undefined }>
+  write: (env: EnvMap) => Promise<EnvMap>
+}
+
+export type PresetDeleteItem = {
+  name: string
+  env: EnvMap
+  source: PresetSource
+}
+
+export function createDeletePresetCommand({
+  presetService,
+  projectEnvService,
+  renderDelete,
+}: {
+  presetService: PresetService
+  projectEnvService: ProjectEnvService
+  renderDelete: (presets: Array<PresetDeleteItem>) => Promise<PresetDeleteItem | undefined>
+}) {
+  return async function deletePreset(): Promise<void> {
+    const names = await presetService.listNames()
+    const globalPresets = await Promise.all(
+      names.map((name) =>
+        presetService.read(name).then((p) => ({ name, env: p.env, source: 'global' as const })),
+      ),
+    )
+
+    const { env: projectEnv, name: projectName } = await projectEnvService.readWithMeta()
+    const projectPreset =
+      Object.keys(projectEnv).length > 0
+        ? [{ name: projectName ?? 'project', env: projectEnv, source: 'project' as const }]
+        : []
+
+    const presets = [...projectPreset, ...globalPresets]
+    if (presets.length === 0) {
+      console.log('No presets found.')
+      return
+    }
+
+    const selected = await renderDelete(presets)
+    if (!selected) return
+
+    if (selected.source === 'project') {
+      await projectEnvService.write({})
+    } else {
+      await presetService.remove(selected.name)
+    }
+
+    console.log(`Deleted preset: ${selected.name}`)
+  }
+}