@lkangd/cc-env 1.2.1 → 1.3.1

package/README.md

@@ -20,6 +20,8 @@
 
 `cc-env` is a CLI tool that lets you define, switch, and restore environment variable configurations for Claude Code — per project or via reusable presets. No more manually editing `settings.json` or juggling `.env` files across workspaces.
 
+> **Alias:** `ccenv` can be used as a shorthand for `cc-env` everywhere (e.g., `ccenv run`, `ccenv create`).
+
 ## Installation
 
 ### via npm
@@ -75,6 +77,8 @@ cc-env run
 
 ## Shell Completion
 
+> Both `cc-env` and `ccenv` are supported in completion scripts.
+
 ```bash
 # bash
 cc-env completion bash >> ~/.bashrc

package/README.zh.md

@@ -20,6 +20,8 @@
 
 `cc-env` 是一个 CLI 工具，让你可以为 Claude Code 定义、切换和恢复环境变量配置——支持按项目配置或使用可复用的预设。不再需要手动编辑 `settings.json` 或在不同工作区之间切换 `.env` 文件。
 
+> **别名：** `ccenv` 可以作为 `cc-env` 的简写使用（例如 `ccenv run`、`ccenv create`）。
+
 ## 安装
 
 ### 通过 npm
@@ -75,6 +77,8 @@ cc-env run
 
 ## Shell 补全
 
+> 补全脚本同时支持 `cc-env` 和 `ccenv`。
+
 ```bash
 # bash
 cc-env completion bash >> ~/.bashrc

package/dist/cli.js

@@ -7,7 +7,6 @@ import gradient from 'gradient-string';
 import { Command } from 'commander';
 import packageJson from '../package.json' with { type: 'json' };
 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 { createEditPresetCommand } from './commands/preset/edit.js';
@@ -19,13 +18,13 @@ import { createRestoreCommand } from './commands/restore.js';
 import { createRunCommand } from './commands/run.js';
 import { runDoctorCommand } from './commands/doctor.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 { getCliName } from './core/cli-name.js';
 import { CliError } from './core/errors.js';
 import { resolveGlobalRoot } from './core/paths.js';
 import { spawnCommand } from './core/spawn.js';
@@ -38,7 +37,7 @@ import { createSettingsEnvService } from './services/settings-env-service.js';
 import { createShellEnvService } from './services/shell-env-service.js';
 const program = new Command();
 program
-    .name('cc-env')
+    .name(getCliName())
     .description('Manage runtime environment variables for Claude Code')
     .version(packageJson.version)
     .option('--verbose', 'Enable verbose output')
@@ -54,8 +53,80 @@ const shellEnvService = createShellEnvService({ homeDir });
 const projectEnvService = createProjectEnvService({ cwd });
 const presetService = createPresetService(globalRoot);
 const historyService = createHistoryService(globalRoot);
+const projectStateService = createProjectStateService(globalRoot);
+async function runPresetCreateFlow({ detectedEnv, requiredKeys }) {
+    let result;
+    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'),
+        detectedEnv,
+        requiredKeys,
+    }));
+    await app.waitUntilExit();
+    return result;
+}
+async function runWithBootstrap({ args = [], dryRun = false, yes = false, json = false, skipDetect = false, }) {
+    const result = await createRunCommand({
+        claudeSettingsEnvService,
+        presetService,
+        projectEnvService,
+        projectStateService,
+        findClaude: findClaudeExecutable,
+        renderPresetSelect: async ({ presets, defaultIndex }) => {
+            let selected;
+            const app = render(h(RunPresetSelectApp, {
+                presets,
+                defaultIndex,
+                onSubmit: preset => {
+                    selected = preset;
+                }
+            }));
+            await app.waitUntilExit();
+            return selected;
+        },
+        spawnCommand
+    })({
+        args,
+        dryRun,
+        yes,
+        json,
+        skipDetect,
+        cwd,
+    });
+    if (!result || result.status === 'executed') {
+        return;
+    }
+    if (Object.keys(result.detectedEnv).length === 0) {
+        throw new CliError('No presets found and no migratable Claude settings were detected.');
+    }
+    const createdPreset = await createPresetCreateCommand({
+        presetService,
+        projectEnvService,
+        claudeSettingsEnvService,
+        historyService,
+        renderFlow: runPresetCreateFlow,
+    })({ cwd });
+    if (!createdPreset) {
+        return;
+    }
+    await projectStateService.saveLastPreset(cwd, createdPreset);
+    await runWithBootstrap({
+        args,
+        dryRun,
+        yes: true,
+        json,
+        skipDetect: true,
+    });
+}
 async function runRestoreFlow(context) {
-    const state = createRestoreFlowState(context.records);
+    const state = createRestoreFlowState(context.records, cwd);
     const firstRecord = context.records[0];
     if (!firstRecord) {
         render(h(RestoreApp, { state }));
@@ -66,16 +137,19 @@ async function runRestoreFlow(context) {
             type: 'select-record',
             timestamp: firstRecord.timestamp
         });
-        if (firstRecord.action === 'init') {
+        if (firstRecord.action === 'init' || firstRecord.action === 'preset-create') {
             const doneState = advanceRestoreFlow(selectedRecordState, { type: 'confirm' });
             if (doneState.step !== 'done') {
                 return undefined;
             }
             return {
                 confirmed: true,
-                timestamp: firstRecord.timestamp
+                timestamp: firstRecord.timestamp,
             };
         }
+        if (firstRecord.action !== 'restore') {
+            return undefined;
+        }
         const confirmState = advanceRestoreFlow(selectedRecordState, {
             type: 'select-target',
             targetType: firstRecord.targetType,
@@ -94,7 +168,7 @@ async function runRestoreFlow(context) {
             return {
                 confirmed: true,
                 timestamp: doneState.selectedTimestamp,
-                targetType: doneState.targetType
+                ...(doneState.targetType ? { targetType: doneState.targetType } : {}),
             };
         }
         return undefined;
@@ -125,62 +199,13 @@ program
     .option('--json', 'Output as JSON (only with --dry-run)')
     .action((args, options) => {
     const rawArgs = args ?? [];
-    return createRunCommand({
-        claudeSettingsEnvService,
-        presetService,
-        projectEnvService,
-        projectStateService: createProjectStateService(globalRoot),
-        findClaude: findClaudeExecutable,
-        renderPresetSelect: async ({ presets, defaultIndex }) => {
-            let result;
-            const app = render(h(RunPresetSelectApp, {
-                presets,
-                defaultIndex,
-                onSubmit: preset => {
-                    result = preset;
-                }
-            }));
-            await app.waitUntilExit();
-            return result;
-        },
-        spawnCommand
-    })({
+    return runWithBootstrap({
         args: rawArgs,
         dryRun: options.dryRun ?? false,
         yes: options.yes ?? false,
         json: options.json ?? 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;
-        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')
@@ -233,26 +258,15 @@ program
 program
     .command('create')
     .description('Create a new environment preset')
-    .action(() => createPresetCreateCommand({
-    presetService,
-    projectEnvService,
-    renderFlow: async () => {
-        let result;
-        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 }));
+    .action(async () => {
+    await createPresetCreateCommand({
+        presetService,
+        projectEnvService,
+        claudeSettingsEnvService,
+        historyService,
+        renderFlow: runPresetCreateFlow,
+    })({ cwd });
+});
 program
     .command('doctor')
     .description('Check system health and configuration')
@@ -286,7 +300,7 @@ program
     .option('--shell <shell>', 'Shell type (bash, zsh, fish)', 'bash')
     .action(async (options) => {
     const { generateCompletion } = await import('./commands/completion.js');
-    process.stdout.write(generateCompletion(options.shell));
+    process.stdout.write(generateCompletion(options.shell, getCliName()));
 });
 function printBanner() {
     const banner = figlet.textSync('CC ENV', { font: 'ANSI Shadow' });
@@ -306,7 +320,22 @@ program.hook('preAction', (thisCommand) => {
             thisCommand.setOptionValue('yes', true);
     }
 });
-program.parseAsync(process.argv).catch((error) => {
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        const hasGlobalPreset = (await presetService.listNames()).length > 0;
+        const { env: projectEnv } = await projectEnvService.readWithMeta();
+        if (hasGlobalPreset || Object.keys(projectEnv).length > 0) {
+            await runWithBootstrap({ args: [], yes: !process.stdin.isTTY });
+            return;
+        }
+        program.outputHelp();
+        process.exitCode = 0;
+        return;
+    }
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
     if (error instanceof CliError) {
         process.stderr.write(`\n  Error: ${error.message}\n\n`);
         process.exitCode = error.exitCode;
@@ -318,7 +347,7 @@ program.parseAsync(process.argv).catch((error) => {
             process.exitCode = 0;
             return;
         }
-        const hint = `  Run "cc-env --help" to see available commands and options.\n`;
+        const hint = `  Run "${getCliName()} --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;

package/dist/commands/completion.js

@@ -1,16 +1,16 @@
 const COMMANDS = ['run', 'init', 'restore', 'show', 'delete', 'create', 'doctor', 'completion', '--help', '--version'];
-export function generateCompletion(shell) {
+export function generateCompletion(shell, cliName = 'cc-env') {
     switch (shell) {
         case 'zsh':
-            return generateZsh();
+            return generateZsh(cliName);
         case 'fish':
-            return generateFish();
+            return generateFish(cliName);
         default:
-            return generateBash();
+            return generateBash(cliName);
     }
 }
-function generateBash() {
-    return `# cc-env bash completion
+function generateBash(cliName) {
+    return `# ${cliName} bash completion
 # Add to ~/.bashrc: eval "$(cc-env completion --shell bash)"
 _cc_env_completions() {
   local cur="\${COMP_WORDS[COMP_CWORD]}"
@@ -18,12 +18,13 @@ _cc_env_completions() {
   COMPREPLY=($(compgen -W "$commands" -- "$cur"))
 }
 complete -F _cc_env_completions cc-env
+complete -F _cc_env_completions ccenv
 `;
 }
-function generateZsh() {
+function generateZsh(cliName) {
     const cmds = COMMANDS.filter((c) => !c.startsWith('-'));
     const cmdList = cmds.map((c) => `    '${c}'`).join('\n');
-    return `# cc-env zsh completion
+    return `# ${cliName} zsh completion
 # Add to ~/.zshrc: eval "$(cc-env completion --shell zsh)"
 _cc_env() {
   local -a commands
@@ -33,9 +34,10 @@ ${cmdList}
   _describe 'command' commands
 }
 compdef _cc_env cc-env
+compdef _cc_env ccenv
 `;
 }
-function generateFish() {
+function generateFish(cliName) {
     const cmds = [
         ['run', 'Run claude with merged environment variables'],
         ['init', 'Initialize cc-env for the current project'],
@@ -46,15 +48,19 @@ function generateFish() {
         ['doctor', 'Check system health and configuration'],
         ['completion', 'Generate shell completion script'],
     ];
-    const lines = cmds.map(([cmd, desc]) => `complete -c cc-env -f -n '__fish_use_subcommand' -a '${cmd}' -d '${desc}'`);
-    return `# cc-env fish completion
+    const names = ['cc-env', 'ccenv'];
+    const subcommandLines = names.flatMap(name => cmds.map(([cmd, desc]) => `complete -c ${name} -f -n '__fish_use_subcommand' -a '${cmd}' -d '${desc}'`));
+    const flagLines = names.flatMap(name => [
+        `complete -c ${name} -l help -d 'Show help'`,
+        `complete -c ${name} -l version -d 'Show version'`,
+        `complete -c ${name} -l json -d 'Output as JSON'`,
+        `complete -c ${name} -l quiet -d 'Suppress non-essential output'`,
+        `complete -c ${name} -l verbose -d 'Enable verbose output'`,
+        `complete -c ${name} -l no-interactive -d 'Disable interactive prompts'`,
+    ]);
+    return `# ${cliName} fish completion
 # Add to fish config: cc-env completion --shell fish | source
-${lines.join('\n')}
-complete -c cc-env -l help -d 'Show help'
-complete -c cc-env -l version -d 'Show version'
-complete -c cc-env -l json -d 'Output as JSON'
-complete -c cc-env -l quiet -d 'Suppress non-essential output'
-complete -c cc-env -l verbose -d 'Enable verbose output'
-complete -c cc-env -l no-interactive -d 'Disable interactive prompts'
+${subcommandLines.join('\n')}
+${flagLines.join('\n')}
 `;
 }

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { access, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { getCliName } from '../core/cli-name.js';
 import { findClaudeExecutable } from '../core/find-claude.js';
 import { resolveGlobalRoot } from '../core/paths.js';
 async function exists(p) {
@@ -36,7 +37,7 @@ async function checkClaudeExecutable() {
 async function checkProjectEnv(cwd) {
     const path = join(cwd, '.cc-env', 'env.json');
     const ok = await exists(path);
-    return { label: 'Project env (.cc-env/env.json)', ok, detail: ok ? path : 'not initialized — run: cc-env init' };
+    return { label: 'Project env (.cc-env/env.json)', ok, detail: ok ? path : `not initialized — run: ${getCliName()} init` };
 }
 function renderCheck(result, json) {
     if (json)

package/dist/commands/init.js

@@ -1,16 +1,9 @@
 import React from 'react';
 import { Box, Text } from 'ink';
+import { requiredClaudeKeys } from '../core/claude-required-keys.js';
 import { CliError } from '../core/errors.js';
 import { envMapSchema } from '../core/schema.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',
-];
 function omitKeys(env, keys) {
     return envMapSchema.parse(Object.fromEntries(Object.entries(env).filter(([key]) => !keys.includes(key))));
 }
@@ -22,7 +15,7 @@ export function createInitCommand({ claudeSettingsEnvService, shellEnvService, h
         }
         const effectiveEnv = envMapSchema.parse(sources.reduce((acc, source) => ({ ...acc, ...source.env }), {}));
         const keys = Object.keys(effectiveEnv).sort();
-        const requiredKeys = requiredInitKeys.filter((key) => key in effectiveEnv);
+        const requiredKeys = requiredClaudeKeys.filter((key) => key in effectiveEnv);
         const sourceFiles = sources.map((s) => s.path);
         const result = await renderFlow({ keys, requiredKeys, yes, sourceFiles });
         if (!result?.confirmed) {

package/dist/commands/preset/create.js

@@ -1,8 +1,10 @@
 import { readFile } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { requiredClaudeKeys } from '../../core/claude-required-keys.js';
 import { CliError } from '../../core/errors.js';
 import { ensureGitignoreEntry } from '../../core/gitignore.js';
+import { envMapSchema } from '../../core/schema.js';
 import { toProcessEnvMap } from '../../core/process-env.js';
 export async function readEnvFile(filePath) {
     try {
@@ -36,9 +38,44 @@ export async function readEnvFile(filePath) {
         throw new CliError(`Failed to read env file: ${filePath}`, 2);
     }
 }
-export function createPresetCreateCommand({ presetService, projectEnvService, renderFlow, ensureGitignore = (dir, entry) => ensureGitignoreEntry(dir, entry), }) {
+function getDetectedEnv(sources) {
+    return toProcessEnvMap(sources.reduce((acc, source) => ({ ...acc, ...source.env }), {}));
+}
+function omitKeys(env, keys) {
+    return envMapSchema.parse(Object.fromEntries(Object.entries(env).filter(([key]) => !keys.includes(key))));
+}
+function buildSourceBackups(sources, selectedKeys, selectedEnv) {
+    const backups = new Map();
+    for (const source of sources) {
+        backups.set(source.path, envMapSchema.parse({}));
+    }
+    for (const key of selectedKeys) {
+        for (const source of [...sources].reverse()) {
+            if (!(key in source.env)) {
+                continue;
+            }
+            if (source.env[key] !== selectedEnv[key]) {
+                continue;
+            }
+            const current = backups.get(source.path) ?? envMapSchema.parse({});
+            backups.set(source.path, envMapSchema.parse({
+                ...current,
+                [key]: source.env[key],
+            }));
+            break;
+        }
+    }
+    return sources.map((source) => ({
+        file: source.path,
+        backup: backups.get(source.path) ?? envMapSchema.parse({}),
+    }));
+}
+export function createPresetCreateCommand({ presetService, projectEnvService, claudeSettingsEnvService, historyService, renderFlow, ensureGitignore = (dir, entry) => ensureGitignoreEntry(dir, entry), }) {
     return async function createPreset({ cwd }) {
-        const result = await renderFlow();
+        const sources = claudeSettingsEnvService ? await claudeSettingsEnvService.read() : [];
+        const detectedEnv = claudeSettingsEnvService ? getDetectedEnv(sources) : {};
+        const requiredKeys = requiredClaudeKeys.filter((key) => key in detectedEnv);
+        const result = await renderFlow({ detectedEnv, requiredKeys });
         if (!result)
             return;
         const selectedEnv = {};
@@ -46,16 +83,40 @@ export function createPresetCreateCommand({ presetService, projectEnvService, re
             selectedEnv[key] = result.env[key] ?? '';
         }
         const timestamp = new Date().toISOString();
+        const selectedKeys = result.selectedKeys;
+        const sourceBackups = result.source === 'detected'
+            ? buildSourceBackups(sources, selectedKeys, selectedEnv)
+            : [];
         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,
-        });
+        else {
+            await presetService.write({
+                name: result.presetName,
+                createdAt: timestamp,
+                updatedAt: timestamp,
+                env: selectedEnv,
+            });
+        }
+        if (result.source === 'detected' && claudeSettingsEnvService && historyService) {
+            await historyService.write({
+                timestamp,
+                action: 'preset-create',
+                projectPath: cwd,
+                presetName: result.presetName,
+                destination: result.destination,
+                migratedKeys: selectedKeys,
+                sources: sourceBackups,
+            });
+            await claudeSettingsEnvService.write(sources.map((source) => ({
+                path: source.path,
+                env: omitKeys(source.env, Object.keys(sourceBackups.find((entry) => entry.file === source.path)?.backup ?? {})),
+            })));
+        }
+        return {
+            presetName: result.presetName,
+            source: result.destination,
+        };
     };
 }

package/dist/commands/restore.js

@@ -2,9 +2,12 @@ import React from 'react';
 import { Box, Text } from 'ink';
 import { CliError } from '../core/errors.js';
 const h = React.createElement;
+function isRestorableRecord(record) {
+    return record.action === 'init' || record.action === 'restore' || record.action === 'preset-create';
+}
 export function createRestoreCommand({ historyService, claudeSettingsEnvService, shellEnvService, settingsEnvService, presetService, renderFlow, renderEnvSummary, }) {
     return async function restore({ yes = false } = {}) {
-        const records = await historyService.list();
+        const records = (await historyService.list()).filter(isRestorableRecord);
         const result = await renderFlow({ records, yes });
         if (!result?.confirmed) {
             return;
@@ -33,6 +36,27 @@ export function createRestoreCommand({ historyService, claudeSettingsEnvService,
             });
             return;
         }
+        if (record.action === 'preset-create') {
+            const mergedBackup = Object.fromEntries(record.sources.flatMap((source) => Object.entries(source.backup)));
+            const current = await claudeSettingsEnvService.read();
+            await claudeSettingsEnvService.write(current.map((source) => ({
+                path: source.path,
+                env: {
+                    ...source.env,
+                    ...(record.sources.find((entry) => entry.file === source.path)?.backup ?? {}),
+                },
+            })));
+            await renderEnvSummary({
+                title: `Restored from detected preset ${record.presetName}`,
+                env: mergedBackup,
+                toFiles: record.sources.map((source) => source.file),
+                footer: h(Box, { flexDirection: 'column' }, h(Text, { color: 'green' }, 'Restore complete'), h(Text, { bold: true, color: 'green' }, 'Please restart your terminal for the restored environment variables to take effect.')),
+            });
+            return;
+        }
+        if (record.action !== 'restore') {
+            throw new CliError('Restore record type is not supported');
+        }
         if (result.targetType === 'settings') {
             const currentSettings = await settingsEnvService.read();
             await settingsEnvService.write({