@lkangd/cc-env 1.1.1 → 1.1.2

package/docs/superpowers/specs/2026-04-24-cc-env-design.md

@@ -1,438 +0,0 @@
-# cc-env Design Spec
-
-Date: 2026-04-24
-Status: Approved for implementation
-Scope: Full v1
-
-## 1. Objective
-
-Build a Node.js CLI named `cc-env` that injects a deterministic set of environment variables into a child process at runtime, primarily for Claude Code CLI usage, without relying on persistent shell mutation.
-
-The tool must support:
-- global presets for provider switching
-- project-level env overrides
-- migration from `~/.claude/settings.json`
-- history and restore flows
-- masked output for sensitive values
-- deterministic merge behavior
-
-## 2. Product Decisions Confirmed
-
-The following decisions were confirmed during design:
-
-- Full v1 scope is in scope, not MVP-only.
-- Destructive or state-changing confirmation flows default to interactive confirmation, with `--yes` available for non-interactive automation.
-- `debug` supports explicit `--preset <name>` and also falls back to a default preset in `~/.cc-env/config.json`.
-- `preset create` interactive variable enumeration defaults to `process.env` and `~/.claude/settings.json.env`, and may additionally import current project env when present.
-- `init` migrates selected keys from `~/.claude/settings.json.env` into a global preset chosen interactively by the user, and also writes a history record.
-- Migrated variables belong to the global configuration domain, not the project override layer.
-- `restore` supports choosing the destination interactively: restore to `settings.json.env` or to a global preset.
-- Preset secrets are allowed to be stored in plaintext on disk in v1; outputs and logs must still mask sensitive values.
-- Project env is part of full v1. It is managed indirectly through `preset create` flows: users can import current project env into a create flow and can choose to save create results back to the current project env file.
-- Action commands use subcommands rather than long flags. Behavior modifiers still use flags.
-- If both `./.cc-env/env.json` and `./.cc-env/env.yaml` exist, the command fails with a human-readable error.
-- The design approach is a layered command-oriented architecture rather than a monolithic CLI or heavyweight domain abstraction.
-
-## 3. Command Model
-
-Action-style operations are represented as subcommands:
-
-```bash
-cc-env run [--preset <name>] [--dry-run] <command> [args...]
-cc-env init [--yes]
-cc-env restore [--yes]
-cc-env preset create [--file <path>] [KEY=VALUE ...]
-cc-env preset list
-cc-env preset show <name>
-cc-env preset delete <name> [--yes]
-cc-env preset edit <name>
-cc-env debug [--preset <name>]
-```
-
-### 3.1 Command semantics
-
-#### `cc-env run`
-- Loads env inputs from all supported sources.
-- Resolves the effective preset from `--preset` or the default preset in `~/.cc-env/config.json`.
-- If neither is available, fails with a human-readable preset selection error.
-- Merges environment variables in the deterministic order defined below.
-- Spawns the target child process with `stdio: 'inherit'`.
-- Uses `cross-spawn`, not `exec()`.
-- In `--dry-run`, prints what would run and the masked env values that would be injected, but does not spawn and does not mutate state.
-
-#### `cc-env init`
-- Reads `~/.claude/settings.json`.
-- If no `env` field exists, prints `No env field found` and exits successfully without writing state.
-- Uses Ink UI to let the user select which keys to migrate.
-- Uses Ink UI to let the user name or select the destination global preset.
-- Shows a preview of which keys will be written to the preset and removed from `settings.json.env`.
-- Confirms before applying unless `--yes` is provided.
-- On apply:
-  - writes selected keys to the destination global preset
-  - writes a history record
-  - removes the selected keys from `~/.claude/settings.json.env`
-
-#### `cc-env restore`
-- Lists available history records in Ink.
-- Lets the user select a history record.
-- Lets the user choose the restore target:
-  - `~/.claude/settings.json.env`
-  - a global preset
-- Detects key collisions and asks for overwrite confirmation unless `--yes` is provided.
-- Applies the restore and records the result in logs.
-
-#### `cc-env preset create`
-Supports three input modes:
-- interactive selection
-- file import with `--file`
-- inline `KEY=VALUE` arguments
-
-Interactive mode:
-- lets the user choose variables from:
-  - `process.env`
-  - `~/.claude/settings.json.env`
-- may additionally import current project env when present
-- then lets the user choose the save target:
-  - a global preset
-  - the current project env file
-
-Project env save behavior:
-- if a project env file already exists, preserve its existing format
-- if neither project env file exists, default to writing `./.cc-env/env.json`
-
-#### `cc-env preset list`
-- Prints a compact tabular list of presets with name, updated date, and variable count.
-- No Ink UI.
-
-#### `cc-env preset show <name>`
-- Prints the preset content with sensitive values masked.
-- No Ink UI.
-
-#### `cc-env preset delete <name>`
-- Requires confirmation unless `--yes` is provided.
-- Deletes the preset file under file lock.
-
-#### `cc-env preset edit <name>`
-- Opens the preset in `$EDITOR`.
-- Validation is re-run after save.
-- Invalid edited content is rejected with a human-readable error.
-
-#### `cc-env debug`
-- Resolves preset from `--preset` or default config.
-- Loads all env sources.
-- Computes the final merged env.
-- Prints masked effective env and source participation details.
-- No Ink UI.
-
-## 4. Storage Layout
-
-Global state lives under:
-
-```text
-~/.cc-env/
-  config.json
-  presets/
-    <name>.json
-  history/
-    <timestamp>.json
-  logs/
-    cc-env.log
-```
-
-Project state lives under the working directory:
-
-```text
-./.cc-env/
-  env.json
-  env.yaml
-```
-
-Exactly zero or one project env file may exist. If both exist, the command fails.
-
-## 5. Data Model
-
-## 5.1 Preset schema
-
-Each preset file is JSON and validates with zod:
-
-```json
-{
-  "name": "openai",
-  "createdAt": "2026-04-24T10:00:00Z",
-  "updatedAt": "2026-04-24T10:00:00Z",
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://api.openai.com",
-    "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
-  }
-}
-```
-
-Rules:
-- `env` must be a flat object
-- all values must be strings
-- all keys must match `^[A-Z0-9_]+$`
-
-## 5.2 History schema
-
-Each history record is JSON and validates with zod:
-
-```json
-{
-  "timestamp": "2026-04-24T10:00:00Z",
-  "action": "init",
-  "movedKeys": ["ANTHROPIC_BASE_URL"],
-  "backup": {
-    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
-  },
-  "targetType": "preset",
-  "targetName": "openai"
-}
-```
-
-Required semantics:
-- `timestamp` identifies when the state-changing operation happened
-- `action` identifies the originating action, such as `init` or `restore`
-- `movedKeys` records which keys were affected
-- `backup` stores the source values needed for restore
-- `targetType` is either `settings` or `preset`
-- `targetName` is present when `targetType` is `preset`
-
-## 5.3 Config schema
-
-`~/.cc-env/config.json` stores stable global tool settings. For v1, it only needs:
-
-```json
-{
-  "defaultPreset": "openai"
-}
-```
-
-## 6. Deterministic Merge Rules
-
-The effective env must always be computed in the same precedence order:
-
-1. `~/.claude/settings.json.env`
-2. `process.env`
-3. selected preset
-4. project env
-
-Later sources override earlier sources.
-
-This order is implemented once in a dedicated runtime env service and reused by both `run` and `debug`.
-
-## 7. Architecture
-
-The implementation uses a layered structure:
-
-- **CLI layer** — Commander setup and top-level process exit handling
-- **Command layer** — one entry per command or subcommand
-- **Service layer** — business logic for presets, history, settings migration, project env, and runtime merge
-- **Core layer** — schemas, masking, paths, locking, errors, logger, and process spawning helpers
-
-Suggested source layout:
-
-```text
-src/
-  cli.ts
-  commands/
-    run.ts
-    init.ts
-    restore.ts
-    debug.ts
-    preset/
-      create.ts
-      list.ts
-      show.ts
-      delete.ts
-      edit.ts
-  services/
-    preset-service.ts
-    project-env-service.ts
-    settings-env-service.ts
-    history-service.ts
-    runtime-env-service.ts
-  core/
-    schema.ts
-    mask.ts
-    paths.ts
-    lock.ts
-    errors.ts
-    logger.ts
-    spawn.ts
-```
-
-### 7.1 Architectural rule
-
-All computation of the final merged env must happen in `runtime-env-service`. No command may reimplement merge precedence independently.
-
-## 8. Interaction Design
-
-Ink is used only for complex interactive flows:
-- `init`
-- `restore`
-- interactive `preset create`
-
-Ink is not used for:
-- `preset list`
-- `preset show`
-- `debug`
-
-### 8.1 `init` interaction flow
-1. Load `settings.json.env`
-2. Show selectable keys and masked previews
-3. Ask for destination global preset name
-4. Show operation preview
-5. Confirm or auto-apply with `--yes`
-6. Apply write operations under lock
-
-### 8.2 `restore` interaction flow
-1. List history records
-2. Select one record
-3. Select restore target
-4. Detect collisions
-5. Ask overwrite confirmation or auto-overwrite with `--yes`
-6. Apply write operations under lock
-
-### 8.3 `preset create` interaction flow
-1. Determine input mode
-2. For interactive mode, select variable source(s)
-3. Select keys and values
-4. Select destination target
-5. Preview result
-6. Apply write operations under lock
-
-## 9. Security and Privacy Rules
-
-Sensitive values may be stored in preset files in plaintext in v1, but must never be emitted raw in user-facing output or logs when the key name indicates a secret.
-
-Masking applies to keys matching at least:
-- `*_TOKEN`
-- `*_KEY`
-- `*_SECRET`
-- `*_PASSWORD`
-
-Masked output should preserve enough prefix to identify the value, for example:
-
-```text
-sk-123456********
-```
-
-The logger must never write full secret values.
-
-## 10. Concurrency and File Safety
-
-Every state-changing write uses file locking via `proper-lockfile`.
-
-This includes:
-- writing presets
-- deleting presets
-- editing presets after validation
-- mutating `~/.claude/settings.json`
-- writing history records
-- writing project env files
-- updating `config.json`
-
-The system must prefer reversible writes:
-- read current state
-- validate intended new state
-- write atomically where possible
-- record history for destructive migrations and restore operations
-
-## 11. Error Handling
-
-All user-facing errors are short and human-readable.
-
-Rules:
-- no stack traces in normal CLI output
-- non-zero exit codes for failure
-- distinguish argument errors from business-logic failures
-
-Suggested exit code policy:
-- `1` — runtime or business error
-- `2` — invalid CLI usage or argument validation
-
-Examples:
-- `Preset not found: openai`
-- `Project env conflict: env.json and env.yaml both exist`
-- `No env field found`
-
-## 12. Logging
-
-Log file path:
-
-```text
-~/.cc-env/logs/cc-env.log
-```
-
-Log entries include:
-- timestamp
-- command
-- result
-- error summary when present
-
-Logs must not include raw secret values.
-
-## 13. Testing Strategy
-
-### 13.1 Unit tests
-Cover:
-- zod schema validation
-- env merge precedence
-- secret masking
-- default preset fallback
-- project env conflict detection
-- project env format preservation
-
-### 13.2 Integration tests
-Cover:
-- `run --dry-run`
-- `preset create --file`
-- inline `preset create`
-- `init` migration side effects
-- `restore` side effects
-- `debug` output shape
-
-### 13.3 Interaction tests
-For Ink flows, test:
-- key selection
-- target selection
-- overwrite confirmation
-- `--yes` bypass behavior
-
-Tests should verify decisions and side effects, not terminal styling.
-
-## 14. Implementation Boundaries
-
-This v1 does not include:
-- shell mutation
-- token lifecycle management
-- secret encryption or OS keychain integration
-- sandboxing
-- Claude CLI hooking
-- project env dedicated management commands outside the `preset create` flow
-
-## 15. Recommended Implementation Sequence
-
-1. Initialize TypeScript project structure and build/test tooling
-2. Implement core schema, path, mask, error, and lock utilities
-3. Implement preset storage service and config service
-4. Implement project env and settings env readers/writers
-5. Implement runtime env merge service
-6. Implement `preset list/show/create/delete/edit`
-7. Implement `debug`
-8. Implement `run` with `--dry-run`
-9. Implement `init`
-10. Implement `restore`
-11. Add interaction tests and integration coverage
-
-## 16. Success Criteria
-
-The design is successful when:
-- the same inputs always produce the same merged env
-- the tool can switch provider settings without shell mutation
-- global presets and project env can be combined predictably
-- migration from `~/.claude/settings.json.env` is reversible
-- restore can target either settings or preset destination
-- all secret-like output is masked
-- all state-changing writes are lock-protected
-- non-interactive automation is possible via `--yes` and `--dry-run`

package/docs/superpowers/specs/2026-04-24-cc-env-init-shell-migration-design.md

@@ -1,181 +0,0 @@
-# cc-env init shell migration redesign
-
-## Goal
-
-Redefine `cc-env init` so it migrates selected env keys out of Claude Code's home-directory settings files and into shell-level global environment configuration. The command must stop creating presets. Its purpose is to remove startup-time env overrides from `~/.claude/settings.json` and `~/.claude/settings.local.json`, then make those values available to new terminal sessions through managed shell config blocks.
-
-## Scope
-
-This redesign changes:
-
-- `init` input sources and migration target
-- history shape for init migrations
-- `restore` behavior for init history
-- supporting services for Claude settings files and shell config files
-
-This redesign does not change:
-
-- preset CRUD behavior
-- project env file behavior
-- runtime merge precedence beyond the already-approved `process < settings < project < preset`
-
-## Required init behavior
-
-### Input sources
-
-`init` reads only these two files in the user's home Claude directory:
-
-- `~/.claude/settings.json`
-- `~/.claude/settings.local.json`
-
-For each file, `init` reads only its `env` field. If both files are missing, `init` exits with an error.
-
-If the same env key exists in both files, `settings.local.json` wins for the effective migration value.
-
-### Selection behavior
-
-`init` builds a candidate view from the union of both `env` maps.
-
-These six keys are always selected by default and cannot be deselected:
-
-- `ANTHROPIC_AUTH_TOKEN`
-- `ANTHROPIC_BASE_URL`
-- `ANTHROPIC_DEFAULT_HAIKU_MODEL`
-- `ANTHROPIC_DEFAULT_OPUS_MODEL`
-- `ANTHROPIC_DEFAULT_SONNET_MODEL`
-- `ANTHROPIC_REASONING_MODEL`
-
-The user may add other discovered keys to the migration set.
-
-If no selected key resolves to an effective value after applying `settings.local.json` precedence, `init` exits with an error instead of writing empty shell config.
-
-### Migration behavior
-
-After confirmation, `init` performs three operations:
-
-1. Remove the selected keys from `~/.claude/settings.json` `env`
-2. Remove the selected keys from `~/.claude/settings.local.json` `env`
-3. Write the effective migrated values to managed shell config blocks for:
-   - `~/.zshrc`
-   - `~/.bashrc`
-   - `~/.config/fish/config.fish`
-
-Shell writes guarantee the values are available to newly opened terminals. Already-running terminals are not updated in place.
-
-`init` no longer creates or updates any preset.
-
-## Managed shell block design
-
-Each supported shell file gets a `cc-env` managed block. `cc-env` may only create, replace, or remove content inside its own block.
-
-### zsh/bash block
-
-```sh
-# >>> cc-env >>>
-export KEY="value"
-# <<< cc-env <<<
-```
-
-### fish block
-
-```fish
-# >>> cc-env >>>
-set -gx KEY "value"
-# <<< cc-env <<<
-```
-
-Behavior rules:
-
-- If the target shell file does not exist, create it and write the managed block
-- If the managed block exists, replace the entire block
-- If the managed block does not exist, append a new block
-- Do not inspect or modify unrelated user content outside the managed block
-
-## Service boundaries
-
-### Claude settings env service
-
-Introduce a dedicated service for Claude home settings files. It is responsible for:
-
-- reading `env` from `~/.claude/settings.json`
-- reading `env` from `~/.claude/settings.local.json`
-- writing updated `env` maps back to each file independently
-- treating missing files as missing sources rather than project-local defaults
-
-This service should expose per-file data so history and restore can preserve source boundaries.
-
-### Shell env service
-
-Introduce a dedicated service for shell config files. It is responsible for:
-
-- rendering shell-specific export syntax
-- inserting/replacing/removing the `cc-env` managed block
-- reading current managed keys when needed for restore
-- handling zsh, bash, and fish paths independently
-
-This service should not parse or rewrite arbitrary user shell config beyond its own block.
-
-## History redesign
-
-The current init history model is too narrow because it stores a single backup map and assumes restore targets are either `settings` or `preset`.
-
-Init history must be expanded so restore can reverse the migration without guessing. An init record must contain at least:
-
-- `timestamp`
-- `action: 'init'`
-- `migratedKeys`
-- `settingsBackup` — keys removed from `~/.claude/settings.json`
-- `settingsLocalBackup` — keys removed from `~/.claude/settings.local.json`
-- `shellWrites` — which shell files were written and which effective key/value pairs were placed there
-
-Restore logic must rely on this persisted data rather than recomputing source ownership later.
-
-## Restore behavior for init history
-
-For an init-created history entry, `restore` performs a two-way reversal:
-
-1. Remove the migrated keys from the `cc-env` managed blocks in zsh, bash, and fish
-2. Restore the backed-up keys to their original Claude settings source files:
-   - `settingsBackup` back to `~/.claude/settings.json`
-   - `settingsLocalBackup` back to `~/.claude/settings.local.json`
-
-If a shell file was not present when the init record was created, restore should only touch files listed in that record's `shellWrites`.
-
-Restore for non-init history should continue using its existing target-driven flow unless deliberately refactored as part of the implementation.
-
-## Error handling
-
-`init` should fail with a `CliError` when:
-
-- both Claude settings files are missing
-- no selected key has an effective value to migrate
-- a required settings file cannot be parsed
-- a shell config file cannot be updated
-
-`restore` should fail with a `CliError` when:
-
-- the requested history entry does not exist
-- a recorded shell target cannot be updated
-- a recorded settings target cannot be restored
-
-## Testing
-
-Add or update tests for:
-
-- reading env from both Claude settings files
-- `settings.local.json` overriding `settings.json` for effective migrated values
-- the six required keys being preselected and non-removable in init flow state
-- writing zsh/bash/fish managed blocks
-- replacing an existing managed block without touching surrounding content
-- removing managed keys during restore
-- recording per-file Claude settings backups in history
-- restoring those backups to the correct source file
-- erroring when both settings files are absent
-- erroring when no selected key resolves to a value
-
-## Implementation notes
-
-- Keep the existing codebase pattern of small services plus thin command handlers
-- Prefer extending existing restore flow carefully over broad refactors
-- Do not add preset compatibility shims to init
-- Do not treat current working directory settings files as init inputs anymore

package/docs/superpowers/specs/2026-04-26-preset-create-interactive-refactor-design.md

@@ -1,78 +0,0 @@
-# Preset Create 交互重构设计
-
-## 目标
-
-将 `preset create` 命令从半交互式（支持 CLI 参数直接执行）改为全交互式，去掉所有 CLI 参数（`-n`、`-f`、`--project`、`[pairs...]`），完全通过 ink UI 引导用户完成 preset 创建。
-
-## 交互流程
-
-```
-source → filePath? → keys → manualInput? → name → destination → confirm → done
-```
-
-### 步骤说明
-
-1. **source** — 选择数据来源：「文件导入（默认）」或「手动输入」，回车确认
-2. **filePath**（仅文件导入）— 文本输入框输入文件路径，回车确认。支持 `.yaml`/`.yml`/`.json` 格式。读取失败时显示红色错误提示，允许重新输入
-3. **keys**（仅文件导入）— 复用 init 的 checkbox 模式（j/k 上下、空格勾选、回车确认），展示从文件解析出的 key 供用户勾选
-4. **manualInput**（仅手动输入）— 文本输入框输入 `KEY=VALUE` 回车添加，已添加的 key-value 实时显示，输入 `q` 结束
-5. **name** — 文本输入框输入 preset 名称，回车确认
-6. **destination** — 选择「全局 preset」或「项目 preset」，回车确认
-7. **confirm** — 复用 `EnvSummary` 组件展示来源文件（如有）、保存路径、key-value 对，回车确认保存，`q` 取消
-
-全局按键：`q`/Escape 在任意步骤退出。
-
-## 架构变更
-
-### Flow 状态机 (`src/flows/preset-create-flow.ts`)
-
-从当前 5 步扩展为 7 步条件分支流程。State 新增字段：
-
-- `source: 'file' | 'manual'`
-- `filePath: string`
-- `presetName: string`
-- `destination: 'global' | 'project'`
-- `env: EnvMap`（解析后的键值对）
-
-路径分支：
-- `source='file'` → `filePath` → `keys` → `name` → `destination` → `confirm` → `done`
-- `source='manual'` → `manualInput` → `name` → `destination` → `confirm` → `done`
-
-### Ink 组件 (`src/ink/preset-create-app.tsx`)
-
-扩展渲染逻辑覆盖所有 7 个步骤。每步根据 flow state 的当前 step 渲染对应 UI。keys 步骤复用 init-app 的 checkbox 模式（j/k/空格/回车）。
-
-### 命令层 (`src/commands/preset/create.ts`)
-
-- 移除所有参数（`name`、`file`、`pairs`、`project`），命令函数无参数
-- 不再有"有参数直接执行 vs 无参数交互"的分支
-- 只调用 `renderFlow()` 拿结果，写入对应位置
-- `buildPlaceholderEnv` 删除
-- `readEnvFile` 和 `parseInlinePairs` 保留，由 ink 组件在交互中通过 renderFlow 回调调用
-
-### CLI 注册 (`src/cli.ts`)
-
-- 移除 `-n`、`-f`、`--project` flag 和 `[pairs...]` 参数
-- 只保留裸命令 `preset create`
-
-### 服务接口
-
-`presetService.write()` 和 `projectEnvService.write()` 保持现有签名不变。
-
-## 文件解析逻辑
-
-在 `readEnvFile` 中增加 JSON env 字段处理：如果解析结果是对象且存在 `env` 字段（且 `env` 是对象），则使用 `env` 内的字段；否则使用第一层字段。
-
-## 错误处理
-
-- 文件不存在 / 无法读取 → 红色提示，停留在 filePath 步骤
-- 文件格式不支持（非 .yaml/.yml/.json）→ 红色提示，重新输入
-- 文件内容解析失败 → 红色提示，重新输入
-- preset 名称为空 → 提示必须输入，停留在 name 步骤
-- preset 名称已存在 → 提示已存在，可选择覆盖或重新输入
-
-## 测试
-
-- `readEnvFile` 的 JSON env 字段提取逻辑补单测
-- flow 状态机的条件分支路径补单测（file 路径 vs manual 路径）
-- 命令函数验证 renderFlow 结果正确路由到对应 service