@lkangd/cc-env 1.0.0

package/src/services/project-env-service.ts

@@ -0,0 +1,128 @@
+import { access, mkdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { parse, stringify } from 'yaml'
+
+import { atomicWriteFile } from '../core/fs.js'
+import { CliError } from '../core/errors.js'
+import { envMapSchema, type EnvMap } from '../core/schema.js'
+
+export type ProjectEnvMeta = {
+  name?: string
+  createdAt?: string
+  updatedAt?: string
+}
+
+function parseEnvelope(value: unknown): {
+  env: EnvMap
+  name?: string | undefined
+  createdAt?: string | undefined
+  updatedAt?: string | undefined
+} {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>
+    if (obj.env && typeof obj.env === 'object' && !Array.isArray(obj.env)) {
+      return {
+        env: envMapSchema.parse(obj.env),
+        name: typeof obj.name === 'string' ? obj.name : undefined,
+        createdAt: typeof obj.createdAt === 'string' ? obj.createdAt : undefined,
+        updatedAt: typeof obj.updatedAt === 'string' ? obj.updatedAt : undefined,
+      }
+    }
+  }
+  return { env: envMapSchema.parse(value) }
+}
+
+export function createProjectEnvService({ cwd }: { cwd: string }) {
+  const envDir = join(cwd, '.cc-env')
+  const jsonPath = join(envDir, 'env.json')
+  const yamlPath = join(envDir, 'env.yaml')
+
+  async function exists(filePath: string): Promise<boolean> {
+    try {
+      await access(filePath)
+      return true
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return false
+      }
+
+      throw error
+    }
+  }
+
+  async function resolveMode(): Promise<'json' | 'yaml' | 'missing'> {
+    const [jsonExists, yamlExists] = await Promise.all([exists(jsonPath), exists(yamlPath)])
+
+    if (jsonExists && yamlExists) {
+      throw new CliError('Project env conflict: env.json and env.yaml both exist')
+    }
+
+    if (yamlExists) {
+      return 'yaml'
+    }
+
+    if (jsonExists) {
+      return 'json'
+    }
+
+    return 'missing'
+  }
+
+  async function readRaw(): Promise<{
+    env: EnvMap
+    name?: string | undefined
+    createdAt?: string | undefined
+    updatedAt?: string | undefined
+  }> {
+    const mode = await resolveMode()
+
+    if (mode === 'missing') {
+      return { env: envMapSchema.parse({}) }
+    }
+
+    const filePath = mode === 'yaml' ? yamlPath : jsonPath
+    const content = await readFile(filePath, 'utf8')
+    const value = mode === 'yaml' ? parse(content) : JSON.parse(content)
+    return parseEnvelope(value ?? {})
+  }
+
+  return {
+    async read(): Promise<EnvMap> {
+      const { env } = await readRaw()
+      return env
+    },
+
+    async readWithMeta(): Promise<{
+      env: EnvMap
+      name?: string | undefined
+      createdAt?: string | undefined
+      updatedAt?: string | undefined
+    }> {
+      return readRaw()
+    },
+
+    async write(env: EnvMap, meta?: ProjectEnvMeta): Promise<EnvMap> {
+      const parsedEnv = envMapSchema.parse(env)
+      await mkdir(envDir, { recursive: true })
+      const mode = await resolveMode()
+
+      if (meta?.name !== undefined) {
+        const envelope: Record<string, unknown> = { name: meta.name, env: parsedEnv }
+        if (meta.createdAt !== undefined) envelope.createdAt = meta.createdAt
+        if (meta.updatedAt !== undefined) envelope.updatedAt = meta.updatedAt
+        const content = `${JSON.stringify(envelope, null, 2)}\n`
+        await atomicWriteFile(jsonPath, content)
+        return parsedEnv
+      }
+
+      const filePath = mode === 'yaml' ? yamlPath : jsonPath
+      const content = mode === 'yaml'
+        ? stringify(parsedEnv)
+        : `${JSON.stringify(parsedEnv, null, 2)}\n`
+
+      await atomicWriteFile(filePath, content)
+      return parsedEnv
+    },
+  }
+}

package/src/services/project-state-service.ts

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { atomicWriteFile } from '../core/fs.js'
+
+type PresetRef = { presetName: string; source: 'global' | 'project' }
+
+export function createProjectStateService(globalRoot: string) {
+  const filePath = join(globalRoot, 'project-state.json')
+
+  async function readAll(): Promise<Record<string, PresetRef>> {
+    try {
+      const content = await readFile(filePath, 'utf8')
+      return JSON.parse(content) as Record<string, PresetRef>
+    } catch {
+      return {}
+    }
+  }
+
+  return {
+    async getLastPreset(cwd: string): Promise<PresetRef | undefined> {
+      const state = await readAll()
+      return state[cwd]
+    },
+    async saveLastPreset(cwd: string, ref: PresetRef): Promise<void> {
+      const state = await readAll()
+      state[cwd] = ref
+      await atomicWriteFile(filePath, `${JSON.stringify(state, null, 2)}\n`)
+    },
+  }
+}

package/src/services/settings-env-service.ts

@@ -0,0 +1,40 @@
+import { readFile } from 'node:fs/promises'
+
+import { atomicWriteFile } from '../core/fs.js'
+import { envMapSchema, type EnvMap } from '../core/schema.js'
+
+export function createSettingsEnvService({ settingsPath }: { settingsPath: string }) {
+  return {
+    async read(): Promise<EnvMap> {
+      try {
+        const content = await readFile(settingsPath, 'utf8')
+        const json = JSON.parse(content) as { env?: unknown }
+        return envMapSchema.parse(json.env ?? {})
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          return envMapSchema.parse({})
+        }
+
+        throw error
+      }
+    },
+
+    async write(env: EnvMap): Promise<EnvMap> {
+      const parsedEnv = envMapSchema.parse(env)
+      let json: Record<string, unknown> = {}
+
+      try {
+        const content = await readFile(settingsPath, 'utf8')
+        json = JSON.parse(content) as Record<string, unknown>
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+          throw error
+        }
+      }
+
+      json.env = parsedEnv
+      await atomicWriteFile(settingsPath, `${JSON.stringify(json, null, 2)}\n`)
+      return parsedEnv
+    },
+  }
+}

package/src/services/shell-env-service.ts

@@ -0,0 +1,112 @@
+import { readFile } from 'node:fs/promises'
+
+import { atomicWriteFile } from '../core/fs.js'
+import { resolveShellConfigPaths } from '../core/paths.js'
+import { envMapSchema, type EnvMap } from '../core/schema.js'
+
+const startMarker = '# >>> cc-env >>>'
+const endMarker = '# <<< cc-env <<<'
+
+type ShellName = 'zsh' | 'bash' | 'fish'
+
+export type ShellWriteRecord = {
+  shell: ShellName
+  filePath: string
+  env: EnvMap
+}
+
+function parseManagedEnv(content: string): EnvMap {
+  const match = content.match(/# >>> cc-env >>>[\s\S]*?# <<< cc-env <<</)
+  if (!match) {
+    return envMapSchema.parse({})
+  }
+
+  const lines = match[0]
+    .split('\n')
+    .slice(1, -1)
+    .filter(Boolean)
+
+  return envMapSchema.parse(
+    Object.fromEntries(
+      lines.map((line) => {
+        if (line.startsWith('set -gx ')) {
+          const [, key, value] = line.match(/^set -gx ([A-Z0-9_]+) "(.*)"$/) ?? []
+          return [key, value]
+        }
+
+        const [, key, value] = line.match(/^export ([A-Z0-9_]+)="(.*)"$/) ?? []
+        return [key, value]
+      }),
+    ),
+  )
+}
+
+function renderBlock(shell: ShellName, env: EnvMap): string {
+  const lines = Object.entries(env)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, value]) =>
+      shell === 'fish' ? `set -gx ${key} "${value}"` : `export ${key}="${value}"`,
+    )
+
+  return [startMarker, ...lines, endMarker, ''].join('\n')
+}
+
+function replaceManagedBlock(content: string, block: string): string {
+  const pattern = /# >>> cc-env >>>[\s\S]*?# <<< cc-env <<<\n?/
+  if (pattern.test(content)) {
+    const result = content.replace(pattern, block)
+    if (block === '') {
+      return result.replace(/\n{3,}/g, '\n\n').replace(/\n{2,}$/, '\n')
+    }
+    return result
+  }
+
+  return content.length === 0 ? block : `${content.replace(/\n?$/, '\n')}\n${block}`
+}
+
+export function createShellEnvService({ homeDir }: { homeDir?: string } = {}) {
+  const paths = resolveShellConfigPaths(homeDir)
+
+  async function readContent(path: string): Promise<string> {
+    try {
+      return await readFile(path, 'utf8')
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        return ''
+      }
+
+      throw error
+    }
+  }
+
+  return {
+    async write(env: EnvMap): Promise<ShellWriteRecord[]> {
+      return Promise.all(
+        (Object.entries(paths) as Array<[ShellName, string]>).map(async ([shell, filePath]) => {
+          const content = await readContent(filePath)
+          const mergedEnv = envMapSchema.parse({
+            ...parseManagedEnv(content),
+            ...env,
+          })
+          await atomicWriteFile(filePath, replaceManagedBlock(content, renderBlock(shell, mergedEnv)))
+          return { shell, filePath, env: mergedEnv }
+        }),
+      )
+    },
+    async removeKeys(shellWrites: ShellWriteRecord[], keys: string[]): Promise<void> {
+      await Promise.all(
+        shellWrites.map(async ({ shell, filePath }) => {
+          const content = await readContent(filePath)
+          const current = parseManagedEnv(content)
+          const next = envMapSchema.parse(
+            Object.fromEntries(
+              Object.entries(current).filter(([key]) => !keys.includes(key)),
+            ),
+          )
+          const block = Object.keys(next).length === 0 ? '' : renderBlock(shell, next)
+          await atomicWriteFile(filePath, replaceManagedBlock(content, block))
+        }),
+      )
+    },
+  }
+}

package/src/types.d.ts

@@ -0,0 +1,19 @@
+declare module 'cross-spawn' {
+  import type { SpawnOptions } from 'node:child_process'
+  import type { EventEmitter } from 'node:events'
+  import type { Readable, Writable } from 'node:stream'
+
+  type ChildProcessLike = EventEmitter & {
+    stdout?: Readable | null
+    stderr?: Readable | null
+    stdin?: Writable | null
+    once(event: 'error', listener: (error: Error) => void): ChildProcessLike
+    once(event: 'close', listener: (code: number | null) => void): ChildProcessLike
+  }
+
+  export default function spawn(
+    command: string,
+    args?: readonly string[],
+    options?: SpawnOptions,
+  ): ChildProcessLike
+}

package/tests/cli/help.test.ts

@@ -0,0 +1,133 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { execa } from 'execa'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../', import.meta.url))
+const tsxLoader = join(repoRoot, 'node_modules/tsx/dist/loader.mjs')
+const cliEntry = join(repoRoot, 'src/cli.ts')
+
+const tempRoots: string[] = []
+
+async function createCliFixture() {
+  const root = await mkdtemp(join(tmpdir(), 'cc-env-cli-'))
+  tempRoots.push(root)
+
+  const homeDir = join(root, 'home')
+  const projectDir = join(root, 'project')
+
+  await mkdir(join(homeDir, '.cc-env', 'presets'), { recursive: true })
+  await mkdir(join(projectDir, '.cc-env'), { recursive: true })
+
+  await writeFile(
+    join(homeDir, '.cc-env', 'config.json'),
+    `${JSON.stringify({ defaultPreset: 'openai' }, null, 2)}\n`,
+    'utf8',
+  )
+  await writeFile(
+    join(homeDir, '.cc-env', 'project-state.json'),
+    `${JSON.stringify({}, null, 2)}\n`,
+    'utf8',
+  )
+  await writeFile(
+    join(homeDir, '.cc-env', 'presets', 'openai.json'),
+    `${JSON.stringify({
+      name: 'openai',
+      createdAt: '2026-04-24T00:00:00.000Z',
+      updatedAt: '2026-04-24T00:00:00.000Z',
+      env: {
+        PRESET_KEY: 'preset',
+      },
+    }, null, 2)}\n`,
+    'utf8',
+  )
+  await writeFile(
+    join(projectDir, 'settings.json'),
+    `${JSON.stringify({
+      env: {
+        SETTINGS_KEY: 'settings',
+      },
+    }, null, 2)}\n`,
+    'utf8',
+  )
+  await writeFile(
+    join(projectDir, '.cc-env', 'env.json'),
+    `${JSON.stringify({ PROJECT_KEY: 'project' }, null, 2)}\n`,
+    'utf8',
+  )
+
+  return { homeDir, projectDir }
+}
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('cc-env CLI help', () => {
+  it('shows the top-level commands in --help output', async () => {
+    const { stdout } = await execa('node', ['--import', tsxLoader, cliEntry, '--help'], {
+      cwd: repoRoot,
+    })
+
+    expect(stdout).toContain('run')
+    expect(stdout).toContain('init')
+    expect(stdout).toContain('restore')
+    expect(stdout).toContain('preset')
+  })
+
+  it('shows the preset subcommands in help output', async () => {
+    const { stdout } = await execa('node', ['--import', tsxLoader, cliEntry, 'preset', '--help'], {
+      cwd: repoRoot,
+    })
+
+    expect(stdout).toContain('show')
+    expect(stdout).toContain('delete')
+  })
+
+  it('uses real HOME and cwd wiring for dry-run env resolution', async () => {
+    const { homeDir, projectDir } = await createCliFixture()
+    const result = await execa(
+      'node',
+      ['--import', tsxLoader, cliEntry, 'run', '--dry-run', '--yes', 'claude'],
+      {
+        cwd: projectDir,
+        env: {
+          HOME: homeDir,
+        },
+        reject: false,
+      },
+    )
+
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('PROJECT_KEY=')
+    expect(result.stdout).toContain('Would run: claude')
+  })
+
+  it('prints CliError messages without stack traces at the top level', async () => {
+    const { homeDir, projectDir } = await createCliFixture()
+
+    await mkdir(join(projectDir, '.claude'), { recursive: true })
+    await writeFile(
+      join(projectDir, '.claude', 'settings.json'),
+      `${JSON.stringify({ env: { ANTHROPIC_AUTH_TOKEN: 'stale' } }, null, 2)}\n`,
+      'utf8',
+    )
+
+    const result = await execa(
+      'node',
+      ['--import', tsxLoader, cliEntry, 'run', '--dry-run', '--yes'],
+      {
+        cwd: projectDir,
+        env: { HOME: homeDir },
+        reject: false,
+      },
+    )
+
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).not.toContain('CliError:')
+    expect(result.stderr).toContain('Error:')
+  })
+})

package/tests/cli/init.test.ts

@@ -0,0 +1,76 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { execa } from 'execa'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../', import.meta.url))
+const tsxLoader = join(repoRoot, 'node_modules/tsx/dist/loader.mjs')
+const cliEntry = join(repoRoot, 'src/cli.ts')
+
+const tempRoots: string[] = []
+
+async function createInitFixture() {
+  const root = await mkdtemp(join(tmpdir(), 'cc-env-init-cli-'))
+  tempRoots.push(root)
+
+  const homeDir = join(root, 'home')
+  await mkdir(join(homeDir, '.claude'), { recursive: true })
+
+  await writeFile(
+    join(homeDir, '.claude', 'settings.json'),
+    `${JSON.stringify({
+      env: {
+        ANTHROPIC_BASE_URL: 'https://settings.example.com',
+      },
+    }, null, 2)}\n`,
+    'utf8',
+  )
+  await writeFile(
+    join(homeDir, '.claude', 'settings.local.json'),
+    `${JSON.stringify({
+      env: {
+        ANTHROPIC_AUTH_TOKEN: 'local-token',
+      },
+    }, null, 2)}\n`,
+    'utf8',
+  )
+
+  return { homeDir }
+}
+
+afterEach(async () => {
+  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+describe('cc-env CLI init', () => {
+  it('migrates env into shell config with --yes', async () => {
+    const { homeDir } = await createInitFixture()
+
+    await execa(
+      'node',
+      ['--import', tsxLoader, cliEntry, 'init', '--yes'],
+      {
+        cwd: repoRoot,
+        env: {
+          HOME: homeDir,
+        },
+      },
+    )
+
+    const settings = JSON.parse(
+      await readFile(join(homeDir, '.claude', 'settings.json'), 'utf8'),
+    ) as { env?: Record<string, string> }
+    const settingsLocal = JSON.parse(
+      await readFile(join(homeDir, '.claude', 'settings.local.json'), 'utf8'),
+    ) as { env?: Record<string, string> }
+    const fishConfig = await readFile(join(homeDir, '.config', 'fish', 'config.fish'), 'utf8')
+
+    expect(settings.env).toEqual({})
+    expect(settingsLocal.env).toEqual({})
+    expect(fishConfig).toContain('set -gx ANTHROPIC_AUTH_TOKEN "local-token"')
+    expect(fishConfig).toContain('set -gx ANTHROPIC_BASE_URL "https://settings.example.com"')
+  })
+})