问题：全局二进制文件 PATH 配置失败

• 频率 : 高 × 复杂度: 中
• 根本原因 : npm 前缀不在系统 PATH 中
• 解决方案 :
  1. 快速方案：手动导出 PATH
  2. 更好方案：使用 npx 执行（自 npm 5.2.0 起可用）
  3. 最佳方案：在 postinstall 中自动设置 PATH
• 诊断 : npm config get prefix && echo $PATH
• 资源 : npm 常见错误

问题：npm 11.2+ 未知配置警告

• 频率 : 高 × 复杂度: 低
• 解决方案 : 更新到 npm 11.5+，清理 .npmrc，使用正确的配置键

类别 2：跨平台兼容性（高优先级）

问题：Windows 与 Unix 的路径分隔符问题

• 频率 : 高 × 复杂度: 中
• 根本原因 : 硬编码的 \ 或 / 分隔符
• 解决方案 :
  1. 快速方案：处处使用正斜杠
  2. 更好方案：使用 path.join() 和 path.resolve()
  3. 最佳方案：使用特定处理程序进行平台检测
• 实现 :

// 跨平台路径处理
import { join, resolve, sep } from 'path';
import { homedir, platform } from 'os';

function getConfigPath(appName) {
  const home = homedir();
  switch (platform()) {
    case 'win32':
      return join(home, 'AppData', 'Local', appName);
    case 'darwin':
      return join(home, 'Library', 'Application Support', appName);
    default:
      return process.env.XDG_CONFIG_HOME || join(home, '.config', appName);
  }
}

问题：行尾符问题（CRLF 与 LF）

• 解决方案 : .gitattributes 配置，.editorconfig，强制使用 LF
• 验证 : file cli.js | grep -q CRLF && echo "需要修复"

Unix 哲学原则

Unix 哲学从根本上塑造了 CLI 的设计方式：

1. 做好一件事

// 错误：大而全的 CLI
cli analyze --lint --format --test --deploy

// 正确：分离的专注工具
cli-lint src/
cli-format src/
cli-test
cli-deploy

2. 编写可协作的程序

// 通过管道设计组合
if (!process.stdin.isTTY) {
  // 从管道读取
  const input = await readStdin();
  const result = processInput(input);
  // 为下一个程序输出
  console.log(JSON.stringify(result));
} else {
  // 交互模式
  const file = process.argv[2];
  const result = processFile(file);
  console.log(formatForHuman(result));
}

3. 文本流作为通用接口

// 基于上下文的输出格式
function output(data, options) {
  if (!process.stdout.isTTY) {
    // 用于管道的机器可读格式
    console.log(JSON.stringify(data));
  } else if (options.format === 'csv') {
    console.log(toCSV(data));
  } else {
    // 带颜色的人类可读格式
    console.log(chalk.blue(formatTable(data)));
  }
}

4. 沉默是金

// 只输出必要的内容
if (!options.verbose) {
  // 错误输出到 stderr，而不是 stdout
  process.stderr.write('处理中...\n');
}
// 结果输出到 stdout 用于管道
console.log(result);

// 退出码传达状态
process.exit(0); // 成功
process.exit(1); // 一般错误
process.exit(2); // 命令误用

5. 让数据复杂，而不是程序

// 简单的程序，处理复杂的数据
async function transform(input) {
  return input
    .split('\n')
    .filter(Boolean)
    .map(line => processLine(line))
    .join('\n');
}

6. 构建可组合的工具

# Unix 管道示例
cat data.json | cli-extract --field=users | cli-filter --active | cli-format --table

# 每个工具做好一件事
cli-extract: 从 JSON 提取字段
cli-filter: 基于条件过滤
cli-format: 格式化输出

7. 为常见情况优化

// 智能默认值，但允许覆盖
const config = {
  format: process.stdout.isTTY ? 'pretty' : 'json',
  color: process.stdout.isTTY && !process.env.NO_COLOR,
  interactive: process.stdin.isTTY && !process.env.CI,
  ...userOptions
};

类别 3：参数解析与命令结构（中优先级）

问题：复杂的手动 argv 解析

• 频率 : 中 × 复杂度: 中
• 现代解决方案 (2024):
  • 原生：util.parseArgs() 用于简单 CLI
  • Commander.js：最流行，39K+ 项目
  • Yargs：高级功能，中间件支持
  • Minimist：轻量级，零依赖

实现模式 :

#!/usr/bin/env node
import { Command } from 'commander';
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));
const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));

const program = new Command()
  .name(pkg.name)
  .version(pkg.version)
  .description(pkg.description);

// 工作区感知的参数处理
program
  .option('--workspace <name>', '在特定工作区中运行')
  .option('-v, --verbose', '详细输出')
  .option('-q, --quiet', '抑制输出')
  .option('--no-color', '禁用颜色')
  .allowUnknownOption(); // 工作区兼容性很重要

program.parse(process.argv);

类别 4：交互式 CLI 与用户体验（中优先级）

问题：使用 Inquirer.js 时微调器冻结

• 频率 : 中 × 复杂度: 中
• 根本原因 : 同步代码阻塞事件循环
• 解决方案 :

// 正确的异步模式
const spinner = ora('加载中...').start();
try {
  await someAsyncOperation(); // 必须是真正的异步操作
  spinner.succeed('完成！');
} catch (error) {
  spinner.fail('失败');
  throw error;
}

问题：CI/TTY 检测失败

• 实现 :

const isInteractive = process.stdin.isTTY &&
                     process.stdout.isTTY &&
                     !process.env.CI;

if (isInteractive) {
  // 使用颜色、微调器、提示
  const answers = await inquirer.prompt(questions);
} else {
  // 纯文本输出，使用默认值或失败
  console.log('检测到非交互模式');
}

类别 5：Monorepo 与工作区管理（高优先级）

问题：跨工具的工作区检测

• 频率 : 中 × 复杂度: 高
• 检测策略 :

async function detectMonorepo(dir) {
  // 基于 2024 年使用情况的优先级顺序
  const markers = [
    { file: 'pnpm-workspace.yaml', type: 'pnpm' },
    { file: 'nx.json', type: 'nx' },
    { file: 'lerna.json', type: 'lerna' }, // 现在在底层使用 Nx
    { file: 'rush.json', type: 'rush' }
  ];

  for (const { file, type } of markers) {
    if (await fs.pathExists(join(dir, file))) {
      return { type, root: dir };
    }
  }

  // 检查 package.json 工作区
  const pkg = await fs.readJson(join(dir, 'package.json')).catch(() => null);
  if (pkg?.workspaces) {
    return { type: 'npm', root: dir };
  }

  // 向上遍历树
  const parent = dirname(dir);
  if (parent !== dir) {
    return detectMonorepo(parent);
  }

  return { type: 'none', root: dir };
}

问题：工作区中的 postinstall 失败

• 解决方案 : 在脚本中使用 npx，正确的提升配置，工作区感知的路径

类别 6：包分发与发布（高优先级）

问题：安装后二进制文件不可执行

• 频率 : 中 × 复杂度: 中
• 检查清单 :
  1. Shebang 存在：#!/usr/bin/env node
  2. 文件权限：chmod +x cli.js
  3. package.json bin 字段正确
  4. 文件包含在包中
• 发布前验证 :

# 发布前测试包
npm pack
tar -tzf *.tgz | grep -E "^[^/]+/bin/"
npm install -g *.tgz
which your-cli && your-cli --version

问题：平台特定的可选依赖

• 解决方案 : 正确的 optionalDependencies 配置
• 测试 : 跨 Windows/macOS/Linux 的 CI 矩阵

快速决策树

CLI 框架选择 (2024)

parseArgs (Node 原生) → < 3 个命令，简单参数
Commander.js → 标准选择，39K+ 项目
Yargs → 需要中间件，复杂验证
Oclif → 企业级，插件架构

CLI 开发的包管理器

npm → 简单，标准
pnpm → 工作区支持，快速
Yarn Berry → 零安装，PnP
Bun → 性能关键（实验性）

Monorepo 工具选择

< 10 个包 → npm/yarn 工作区
10-50 个包 → pnpm + Turborepo
> 50 个包 → Nx（包含缓存）
从 Lerna 迁移 → Lerna 6+（使用 Nx）或纯 Nx

性能优化

启动时间 (<100ms 目标)

// 延迟加载命令
const commands = new Map([
  ['build', () => import('./commands/build.js')],
  ['test', () => import('./commands/test.js')]
]);

const cmd = commands.get(process.argv[2]);
if (cmd) {
  const { default: handler } = await cmd();
  await handler(process.argv.slice(3));
}

包大小减少

• 使用审计：npm ls --depth=0 --json | jq '.dependencies | keys'
• 使用 esbuild/rollup 进行分发打包
• 对可选功能使用动态导入

测试策略

单元测试

import { execSync } from 'child_process';
import { test } from 'vitest';

test('CLI 版本标志', () => {
  const output = execSync('node cli.js --version', { encoding: 'utf8' });
  expect(output.trim()).toMatch(/^\d+\.\d+\.\d+$/);
});

跨平台 CI

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [18, 20, 22]

现代模式 (2024)

结构化错误处理

class CLIError extends Error {
  constructor(message, code, suggestions = []) {
    super(message);
    this.code = code;
    this.suggestions = suggestions;
  }
}

// 用法
throw new CLIError(
  '配置文件未找到',
  'CONFIG_NOT_FOUND',
  ['运行 "cli init" 创建配置', '检查 --config 标志路径']
);

流处理支持

// 检测和处理管道输入
if (!process.stdin.isTTY) {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }
  const input = Buffer.concat(chunks).toString();
  processInput(input);
}

应避免的常见反模式

1. 硬编码路径 → 使用 path.join()
2. 忽略 Windows → 在所有平台上测试
3. 没有进度指示 → 添加微调器
4. 手动 argv 解析 → 使用成熟的库
5. 事件循环中的同步 I/O → 使用 async/await
6. 缺少错误上下文 → 提供可操作的错误
7. 没有帮助生成 → 使用 commander 自动生成
8. 忘记 CI 模式 → 检查 process.env.CI
9. 没有版本命令 → 包含 --version
10. 阻塞微调器 → 确保异步操作

外部资源

基本文档

• npm CLI 文档 v10+
• Node.js CLI 最佳实践
• Commander.js - 39K+ 项目
• Yargs - 高级解析
• parseArgs - 原生 Node.js

关键库 (2024)

• Inquirer.js - 为性能重写，更小体积
• Chalk 5 - 仅 ESM，更好的树摇
• Ora 7 - 纯 ESM，改进的动画
• Execa 8 - 更好的 Windows 支持
• Cosmiconfig 9 - 配置文件发现

测试工具

• Vitest - 快速，ESM 优先的测试
• c8 - 原生 V8 覆盖率
• Playwright - E2E CLI 测试

多二进制架构

将复杂的 CLI 拆分为专注的可执行文件，以实现更好的关注点分离：

{
  "bin": {
    "my-cli": "./dist/cli.js",
    "my-cli-daemon": "./dist/daemon.js",
    "my-cli-worker": "./dist/worker.js"
  }
}

好处：

• 每个进程内存占用更小
• 关注点分离更清晰
• 更符合 Unix 哲学（做好一件事）
• 更容易测试单个组件
• 允许每个二进制文件不同的权限级别
• 可以使用不同的 Node 标志运行不同的二进制文件

实现示例：

// cli.js - 主入口点
#!/usr/bin/env node
import { spawn } from 'child_process';

if (process.argv[2] === 'daemon') {
  spawn('my-cli-daemon', process.argv.slice(3), {
    stdio: 'inherit',
    detached: true
  });
} else if (process.argv[2] === 'worker') {
  spawn('my-cli-worker', process.argv.slice(3), {
    stdio: 'inherit'
  });
}

自动化发布工作流

用于 npm 包发布的 GitHub Actions，包含全面验证：

# .github/workflows/release.yml
name: 发布包

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      release-type:
        description: '发布类型'
        required: true
        default: 'patch'
        type: choice
        options:
          - patch
          - minor
          - major

permissions:
  contents: write
  packages: write

jobs:
  check-version:
    name: 检查版本
    runs-on: ubuntu-latest
    outputs:
      should-release: ${{ steps.check.outputs.should-release }}
      version: ${{ steps.check.outputs.version }}

    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: 检查版本是否更改
      id: check
      run: |
        CURRENT_VERSION=$(node -p "require('./package.json').version")
        echo "当前版本: $CURRENT_VERSION"

        # 防止重复发布
        if git tag | grep -q "^v$CURRENT_VERSION$"; then
          echo "标签 v$CURRENT_VERSION 已存在。跳过。"
          echo "should-release=false" >> $GITHUB_OUTPUT
        else
          echo "should-release=true" >> $GITHUB_OUTPUT
          echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
        fi

  release:
    name: 构建和发布
    needs: check-version
    if: needs.check-version.outputs.should-release == 'true'
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: '20'
        registry-url: 'https://registry.npmjs.org'

    - name: 安装依赖
      run: npm ci

    - name: 运行质量检查
      run: |
        npm run test
        npm run lint
        npm run typecheck

    - name: 构建包
      run: npm run build

    - name: 验证构建输出
      run: |
        # 确保 dist 目录有内容
        if [ ! -d "dist" ] || [ -z "$(ls -A dist)" ]; then
          echo "::error::构建输出缺失"
          exit 1
        fi

        # 验证入口点存在
        for file in dist/index.js dist/index.d.ts; do
          if [ ! -f "$file" ]; then
            echo "::error::缺少 $file"
            exit 1
          fi
        done

        # 检查 CLI 二进制文件
        if [ -f "package.json" ]; then
          node -e "
            const pkg = require('./package.json');
            if (pkg.bin) {
              Object.values(pkg.bin).forEach(bin => {
                if (!require('fs').existsSync(bin)) {
                  console.error('缺少二进制文件:', bin);
                  process.exit(1);
                }
              });
            }
          "
        fi

    - name: 测试本地安装
      run: |
        npm pack
        npm install -g *.tgz
        # 测试 CLI 是否工作
        $(node -p "Object.keys(require('./package.json').bin)[0]") --version

    - name: 创建并推送标签
      run: |
        VERSION=${{ needs.check-version.outputs.version }}
        git config user.name "github-actions[bot]"
        git config user.email "github-actions[bot]@users.noreply.github.com"
        git tag -a "v$VERSION" -m "发布 v$VERSION"
        git push origin "v$VERSION"

    - name: 发布到 npm
      run: npm publish --access public
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

    - name: 准备发布说明
      run: |
        VERSION=${{ needs.check-version.outputs.version }}
        REPO_NAME=${{ github.event.repository.name }}

        # 如果 CHANGELOG.md 存在，尝试提取变更日志内容
        if [ -f "CHANGELOG.md" ]; then
          CHANGELOG_CONTENT=$(awk -v version="$VERSION" '
            BEGIN { found = 0; content = "" }
            /^## \[/ {
              if (found == 1) { exit }
              if ($0 ~ "## \\[" version "\\]") { found = 1; next }
            }
            found == 1 { content = content $0 "\n" }
            END { print content }
          ' CHANGELOG.md)
        else
          CHANGELOG_CONTENT="*未找到变更日志。请查看提交历史记录了解更改。*"
        fi

        # 创建发布说明文件
        cat > release_notes.md << EOF
        ## 安装

        \`\`\`bash
        npm install -g ${REPO_NAME}@${VERSION}
        \`\`\`

        ## 更改内容

        ${CHANGELOG_CONTENT}

        ## 链接

        - [完整变更日志](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md)
        - [NPM 包](https://www.npmjs.com/package/${REPO_NAME}/v/${VERSION})
        - [所有发布](https://github.com/${{ github.repository }}/releases)
        - [比较更改](https://github.com/${{ github.repository }}/compare/v${{ needs.check-version.outputs.previous-version }}...v${VERSION})
        EOF

    - name: 创建 GitHub 发布
      uses: softprops/action-gh-release@v2
      with:
        tag_name: v${{ needs.check-version.outputs.version }}
        name: 发布 v${{ needs.check-version.outputs.version }}
        body_path: release_notes.md
        draft: false
        prerelease: false

CI/CD 最佳实践

用于跨平台测试的全面 CI 工作流：

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        exclude:
          # 跳过某些组合以节省 CI 时间
          - os: macos-latest
            node: 18
          - os: windows-latest
            node: 18

    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node }}
        cache: 'npm'

    - name: 安装依赖
      run: npm ci

    - name: 代码检查
      run: npm run lint
      if: matrix.os == 'ubuntu-latest' # 只检查一次

    - name: 类型检查
      run: npm run typecheck

    - name: 测试
      run: npm test
      env:
        CI: true

    - name: 构建
      run: npm run build

    - name: 测试 CLI 安装 (Unix)
      if: matrix.os != 'windows-latest'
      run: |
        npm pack
        npm install -g *.tgz
        which $(node -p "Object.keys(require('./package.json').bin)[0]")
        $(node -p "Object.keys(require('./package.json').bin)[0]") --version

    - name: 测试 CLI 安装 (Windows)
      if: matrix.os == 'windows-latest'
      run: |
        npm pack
        npm install -g *.tgz
        where $(node -p "Object.keys(require('./package.json').bin)[0]")
        $(node -p "Object.keys(require('./package.json').bin)[0]") --version

    - name: 上传覆盖率
      if: matrix.os == 'ubuntu-latest' && matrix.node == '20'
      uses: codecov/codecov-action@v3
      with:
        files: ./coverage/lcov.info

    - name: 检查安全漏洞
      if: matrix.os == 'ubuntu-latest'
      run: npm audit --audit-level=high

  integration:
    runs-on: ubuntu-latest
    needs: test
    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: 安装依赖
      run: npm ci

    - name: 构建
      run: npm run build

    - name: 集成测试
      run: npm run test:integration

    - name: E2E 测试
      run: npm run test:e2e

成功指标

• 全局安装无 PATH 问题
• 在 Windows、macOS、Linux 上工作
• < 100ms 启动时间
• 处理管道输入/输出
• 在 CI 中优雅降级
• Monorepo 感知
• 提供解决方案的适当错误消息
• 自动化的帮助生成
• 平台适当的配置路径
• 无 npm 警告或弃用
• 自动化发布工作流
• 需要时支持多二进制文件
• 跨平台 CI 验证

代码审查清单

审查 CLI 代码和 npm 包时，关注：

安装与设置问题

• Shebang 使用 #!/usr/bin/env node 以实现跨平台兼容性
• 二进制文件具有适当的可执行权限 (chmod +x)
• package.json bin 字段正确映射命令名称到可执行文件
• .gitattributes 防止二进制文件中的行尾符损坏
• npm pack 包含安装所需的所有文件

跨平台兼容性

• 路径操作使用 path.join() 而不是硬编码分隔符
• 平台特定的配置路径使用适当的约定
• 所有脚本文件的行尾符一致 (LF)
• CI 测试覆盖 Windows、macOS 和 Linux 平台
• 环境变量处理在所有平台上工作

参数解析与命令结构

• 参数解析使用成熟的库 (Commander.js, Yargs)
• 帮助文本是自动生成的且全面的
• 子命令结构正确且经过验证
• 未知选项得到优雅处理
• 工作区参数正确传递

交互式 CLI 与用户体验

• TTY 检测防止在 CI 环境中出现交互式提示
• 微调器和进度指示器与异步操作一起工作
• 颜色输出尊重 NO_COLOR 环境变量
• 错误消息提供可操作的建议
• 非交互模式有适当的回退

Monorepo 与工作区管理

• Monorepo 检测支持主要工具 (pnpm, Nx, Lerna)
• 命令在工作区内的任何目录中工作
• 工作区特定的配置正确解析
• 包提升策略正确处理
• 在工作区环境中 postinstall 脚本工作

包分发与发布

• 包大小已优化（排除不必要的文件）
• 可选依赖为平台特定功能配置
• 发布工作流包含全面验证
• 版本号遵循语义化版本控制
• 全局安装无 PATH 配置问题

Unix 哲学与设计

• CLI 做好一件事（专注的职责）
• 支持管道输入/输出以实现可组合性
• 退出码适当传达状态 (0=成功, 1=错误)
• 遵循"沉默是金" - 除非详细模式，否则最小输出
• 数据复杂性由程序处理，而不是强加给用户

每周安装数

3

仓库

0xkynz/codekit

GitHub 星标数

1

首次出现

6 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装在

mcpjam3

claude-code3

replit3

junie3

windsurf3

zencoder3

Problem: Global binary PATH configuration failures

• Frequency : HIGH × Complexity: MEDIUM
• Root Cause : npm prefix not in system PATH
• Solutions :
  1. Quick: Manual PATH export
  2. Better: Use npx for execution (available since npm 5.2.0)
  3. Best: Automated PATH setup in postinstall
• Diagnostic : npm config get prefix && echo $PATH
• Resources : npm common errors

Problem: npm 11.2+ unknown config warnings

• Frequency : HIGH × Complexity: LOW
• Solutions : Update to npm 11.5+, clean .npmrc, use proper config keys

Category 2: Cross-Platform Compatibility (High Priority)

Problem: Path separator issues Windows vs Unix

• Frequency : HIGH × Complexity: MEDIUM

• Root Causes : Hard-coded \ or / separators

• Solutions :

  1. Quick: Use forward slashes everywhere
  2. Better: path.join() and path.resolve()
  3. Best: Platform detection with specific handlers

• Implementation :

  // Cross-platform path handling import { join, resolve, sep } from 'path'; import { homedir, platform } from 'os';

  function getConfigPath(appName) { const home = homedir(); switch (platform()) { case 'win32': return join(home, 'AppData', 'Local', appName); case 'darwin': return join(home, 'Library', 'Application Support', appName); default: return process.env.XDG_CONFIG_HOME || join(home, '.config', appName); } }

Problem: Line ending issues (CRLF vs LF)

• Solutions : .gitattributes configuration, .editorconfig, enforce LF
• Validation : file cli.js | grep -q CRLF && echo "Fix needed"

Unix Philosophy Principles

The Unix philosophy fundamentally shapes how CLIs should be designed:

1. Do One Thing Well

// BAD: Kitchen sink CLI
cli analyze --lint --format --test --deploy

// GOOD: Separate focused tools
cli-lint src/
cli-format src/
cli-test
cli-deploy

2. Write Programs to Work Together

// Design for composition via pipes
if (!process.stdin.isTTY) {
  // Read from pipe
  const input = await readStdin();
  const result = processInput(input);
  // Output for next program
  console.log(JSON.stringify(result));
} else {
  // Interactive mode
  const file = process.argv[2];
  const result = processFile(file);
  console.log(formatForHuman(result));
}

3. Text Streams as Universal Interface

// Output formats based on context
function output(data, options) {
  if (!process.stdout.isTTY) {
    // Machine-readable for piping
    console.log(JSON.stringify(data));
  } else if (options.format === 'csv') {
    console.log(toCSV(data));
  } else {
    // Human-readable with colors
    console.log(chalk.blue(formatTable(data)));
  }
}

4. Silence is Golden

// Only output what's necessary
if (!options.verbose) {
  // Errors to stderr, not stdout
  process.stderr.write('Processing...\n');
}
// Results to stdout for piping
console.log(result);

// Exit codes communicate status
process.exit(0); // Success
process.exit(1); // General error
process.exit(2); // Misuse of command

5. Make Data Complicated, Not the Program

// Simple program, handle complex data
async function transform(input) {
  return input
    .split('\n')
    .filter(Boolean)
    .map(line => processLine(line))
    .join('\n');
}

6. Build Composable Tools

# Unix pipeline example
cat data.json | cli-extract --field=users | cli-filter --active | cli-format --table

# Each tool does one thing
cli-extract: extracts fields from JSON
cli-filter: filters based on conditions
cli-format: formats output

7. Optimize for the Common Case

// Smart defaults, but allow overrides
const config = {
  format: process.stdout.isTTY ? 'pretty' : 'json',
  color: process.stdout.isTTY && !process.env.NO_COLOR,
  interactive: process.stdin.isTTY && !process.env.CI,
  ...userOptions
};

Category 3: Argument Parsing & Command Structure (Medium Priority)

Problem: Complex manual argv parsing

• Frequency : MEDIUM × Complexity: MEDIUM
• Modern Solutions (2024):
  • Native: util.parseArgs() for simple CLIs
  • Commander.js: Most popular, 39K+ projects
  • Yargs: Advanced features, middleware support
  • Minimist: Lightweight, zero dependencies

Implementation Pattern :

#!/usr/bin/env node
import { Command } from 'commander';
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));
const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));

const program = new Command()
  .name(pkg.name)
  .version(pkg.version)
  .description(pkg.description);

// Workspace-aware argument handling
program
  .option('--workspace <name>', 'run in specific workspace')
  .option('-v, --verbose', 'verbose output')
  .option('-q, --quiet', 'suppress output')
  .option('--no-color', 'disable colors')
  .allowUnknownOption(); // Important for workspace compatibility

program.parse(process.argv);

Category 4: Interactive CLI & UX (Medium Priority)

Problem: Spinner freezing with Inquirer.js

• Frequency : MEDIUM × Complexity: MEDIUM

• Root Cause : Synchronous code blocking event loop

• Solution :

  // Correct async pattern const spinner = ora('Loading...').start(); try { await someAsyncOperation(); // Must be truly async spinner.succeed('Done!'); } catch (error) { spinner.fail('Failed'); throw error; }

Problem: CI/TTY detection failures

• Implementation :

  const isInteractive = process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;

  if (isInteractive) { // Use colors, spinners, prompts const answers = await inquirer.prompt(questions); } else { // Plain output, use defaults or fail console.log('Non-interactive mode detected'); }

Category 5: Monorepo & Workspace Management (High Priority)

Problem: Workspace detection across tools

• Frequency : MEDIUM × Complexity: HIGH

• Detection Strategy :

  async function detectMonorepo(dir) { // Priority order based on 2024 usage const markers = [ { file: 'pnpm-workspace.yaml', type: 'pnpm' }, { file: 'nx.json', type: 'nx' }, { file: 'lerna.json', type: 'lerna' }, // Now uses Nx under hood { file: 'rush.json', type: 'rush' } ];

  for (const { file, type } of markers) { if (await fs.pathExists(join(dir, file))) { return { type, root: dir }; } }

  // Check package.json workspaces const pkg = await fs.readJson(join(dir, 'package.json')).catch(() => null); if (pkg?.workspaces) { return { type: 'npm', root: dir }; }

  // Walk up tree const parent = dirname(dir); if (parent !== dir) { return detectMonorepo(parent); }

  return { type: 'none', root: dir }; }

Problem: Postinstall failures in workspaces

• Solutions : Use npx in scripts, proper hoisting config, workspace-aware paths

Category 6: Package Distribution & Publishing (High Priority)

Problem: Binary not executable after install

• Frequency : MEDIUM × Complexity: MEDIUM

• Checklist :

  1. Shebang present: #!/usr/bin/env node
  2. File permissions: chmod +x cli.js
  3. package.json bin field correct
  4. Files included in package

• Pre-publish validation :

  Test package before publishing

  npm pack tar -tzf *.tgz | grep -E "^[^/]+/bin/" npm install -g *.tgz which your-cli && your-cli --version

Problem: Platform-specific optional dependencies

• Solution : Proper optionalDependencies configuration
• Testing : CI matrix across Windows/macOS/Linux

Quick Decision Trees

CLI Framework Selection (2024)

parseArgs (Node native) → < 3 commands, simple args
Commander.js → Standard choice, 39K+ projects
Yargs → Need middleware, complex validation
Oclif → Enterprise, plugin architecture

Package Manager for CLI Development

npm → Simple, standard
pnpm → Workspace support, fast
Yarn Berry → Zero-installs, PnP
Bun → Performance critical (experimental)

Monorepo Tool Selection

< 10 packages → npm/yarn workspaces
10-50 packages → pnpm + Turborepo
> 50 packages → Nx (includes cache)
Migrating from Lerna → Lerna 6+ (uses Nx) or pure Nx

Performance Optimization

Startup Time (<100ms target)

// Lazy load commands
const commands = new Map([
  ['build', () => import('./commands/build.js')],
  ['test', () => import('./commands/test.js')]
]);

const cmd = commands.get(process.argv[2]);
if (cmd) {
  const { default: handler } = await cmd();
  await handler(process.argv.slice(3));
}

Bundle Size Reduction

• Audit with: npm ls --depth=0 --json | jq '.dependencies | keys'
• Bundle with esbuild/rollup for distribution
• Use dynamic imports for optional features

Testing Strategies

Unit Testing

import { execSync } from 'child_process';
import { test } from 'vitest';

test('CLI version flag', () => {
  const output = execSync('node cli.js --version', { encoding: 'utf8' });
  expect(output.trim()).toMatch(/^\d+\.\d+\.\d+$/);
});

Cross-Platform CI

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest, macos-latest]
    node: [18, 20, 22]

Modern Patterns (2024)

Structured Error Handling

class CLIError extends Error {
  constructor(message, code, suggestions = []) {
    super(message);
    this.code = code;
    this.suggestions = suggestions;
  }
}

// Usage
throw new CLIError(
  'Configuration file not found',
  'CONFIG_NOT_FOUND',
  ['Run "cli init" to create config', 'Check --config flag path']
);

Stream Processing Support

// Detect and handle piped input
if (!process.stdin.isTTY) {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }
  const input = Buffer.concat(chunks).toString();
  processInput(input);
}

Common Anti-Patterns to Avoid

1. Hard-coding paths → Use path.join()
2. Ignoring Windows → Test on all platforms
3. No progress indication → Add spinners
4. Manual argv parsing → Use established libraries
5. Sync I/O in event loop → Use async/await
6. Missing error context → Provide actionable errors
7. No help generation → Auto-generate with commander
8. Forgetting CI mode → Check process.env.CI
9. No version command → Include --version
10. Blocking spinners → Ensure async operations

External Resources

Essential Documentation

• npm CLI docs v10+
• Node.js CLI best practices
• Commander.js - 39K+ projects
• Yargs - Advanced parsing
• parseArgs - Native Node.js

Key Libraries (2024)

• Inquirer.js - Rewritten for performance, smaller size
• Chalk 5 - ESM-only, better tree-shaking
• Ora 7 - Pure ESM, improved animations
• Execa 8 - Better Windows support
• Cosmiconfig 9 - Config file discovery

Testing Tools

• Vitest - Fast, ESM-first testing
• c8 - Native V8 coverage
• Playwright - E2E CLI testing

Multi-Binary Architecture

Split complex CLIs into focused executables for better separation of concerns:

{
  "bin": {
    "my-cli": "./dist/cli.js",
    "my-cli-daemon": "./dist/daemon.js",
    "my-cli-worker": "./dist/worker.js"
  }
}

Benefits:

• Smaller memory footprint per process
• Clear separation of concerns
• Better for Unix philosophy (do one thing well)
• Easier to test individual components
• Allows different permission levels per binary
• Can run different binaries with different Node flags

Implementation example:

// cli.js - Main entry point
#!/usr/bin/env node
import { spawn } from 'child_process';

if (process.argv[2] === 'daemon') {
  spawn('my-cli-daemon', process.argv.slice(3), {
    stdio: 'inherit',
    detached: true
  });
} else if (process.argv[2] === 'worker') {
  spawn('my-cli-worker', process.argv.slice(3), {
    stdio: 'inherit'
  });
}

Automated Release Workflows

GitHub Actions for npm package releases with comprehensive validation:

# .github/workflows/release.yml
name: Release Package

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      release-type:
        description: 'Release type'
        required: true
        default: 'patch'
        type: choice
        options:
          - patch
          - minor
          - major

permissions:
  contents: write
  packages: write

jobs:
  check-version:
    name: Check Version
    runs-on: ubuntu-latest
    outputs:
      should-release: ${{ steps.check.outputs.should-release }}
      version: ${{ steps.check.outputs.version }}

    steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Check if version changed
      id: check
      run: |
        CURRENT_VERSION=$(node -p "require('./package.json').version")
        echo "Current version: $CURRENT_VERSION"

        # Prevent duplicate releases
        if git tag | grep -q "^v$CURRENT_VERSION$"; then
          echo "Tag v$CURRENT_VERSION already exists. Skipping."
          echo "should-release=false" >> $GITHUB_OUTPUT
        else
          echo "should-release=true" >> $GITHUB_OUTPUT
          echo "version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
        fi

  release:
    name: Build and Publish
    needs: check-version
    if: needs.check-version.outputs.should-release == 'true'
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: '20'
        registry-url: 'https://registry.npmjs.org'

    - name: Install dependencies
      run: npm ci

    - name: Run quality checks
      run: |
        npm run test
        npm run lint
        npm run typecheck

    - name: Build package
      run: npm run build

    - name: Validate build output
      run: |
        # Ensure dist directory has content
        if [ ! -d "dist" ] || [ -z "$(ls -A dist)" ]; then
          echo "::error::Build output missing"
          exit 1
        fi

        # Verify entry points exist
        for file in dist/index.js dist/index.d.ts; do
          if [ ! -f "$file" ]; then
            echo "::error::Missing $file"
            exit 1
          fi
        done

        # Check CLI binaries
        if [ -f "package.json" ]; then
          node -e "
            const pkg = require('./package.json');
            if (pkg.bin) {
              Object.values(pkg.bin).forEach(bin => {
                if (!require('fs').existsSync(bin)) {
                  console.error('Missing binary:', bin);
                  process.exit(1);
                }
              });
            }
          "
        fi

    - name: Test local installation
      run: |
        npm pack
        npm install -g *.tgz
        # Test that CLI works
        $(node -p "Object.keys(require('./package.json').bin)[0]") --version

    - name: Create and push tag
      run: |
        VERSION=${{ needs.check-version.outputs.version }}
        git config user.name "github-actions[bot]"
        git config user.email "github-actions[bot]@users.noreply.github.com"
        git tag -a "v$VERSION" -m "Release v$VERSION"
        git push origin "v$VERSION"

    - name: Publish to npm
      run: npm publish --access public
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

    - name: Prepare release notes
      run: |
        VERSION=${{ needs.check-version.outputs.version }}
        REPO_NAME=${{ github.event.repository.name }}

        # Try to extract changelog content if CHANGELOG.md exists
        if [ -f "CHANGELOG.md" ]; then
          CHANGELOG_CONTENT=$(awk -v version="$VERSION" '
            BEGIN { found = 0; content = "" }
            /^## \[/ {
              if (found == 1) { exit }
              if ($0 ~ "## \\[" version "\\]") { found = 1; next }
            }
            found == 1 { content = content $0 "\n" }
            END { print content }
          ' CHANGELOG.md)
        else
          CHANGELOG_CONTENT="*Changelog not found. See commit history for changes.*"
        fi

        # Create release notes file
        cat > release_notes.md << EOF
        ## Installation

        \`\`\`bash
        npm install -g ${REPO_NAME}@${VERSION}
        \`\`\`

        ## What's Changed

        ${CHANGELOG_CONTENT}

        ## Links

        - [Full Changelog](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md)
        - [NPM Package](https://www.npmjs.com/package/${REPO_NAME}/v/${VERSION})
        - [All Releases](https://github.com/${{ github.repository }}/releases)
        - [Compare Changes](https://github.com/${{ github.repository }}/compare/v${{ needs.check-version.outputs.previous-version }}...v${VERSION})
        EOF

    - name: Create GitHub Release
      uses: softprops/action-gh-release@v2
      with:
        tag_name: v${{ needs.check-version.outputs.version }}
        name: Release v${{ needs.check-version.outputs.version }}
        body_path: release_notes.md
        draft: false
        prerelease: false

CI/CD Best Practices

Comprehensive CI workflow for cross-platform testing:

# .github/workflows/ci.yml
name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        exclude:
          # Skip some combinations to save CI time
          - os: macos-latest
            node: 18
          - os: windows-latest
            node: 18

    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node }}
        cache: 'npm'

    - name: Install dependencies
      run: npm ci

    - name: Lint
      run: npm run lint
      if: matrix.os == 'ubuntu-latest' # Only lint once

    - name: Type check
      run: npm run typecheck

    - name: Test
      run: npm test
      env:
        CI: true

    - name: Build
      run: npm run build

    - name: Test CLI installation (Unix)
      if: matrix.os != 'windows-latest'
      run: |
        npm pack
        npm install -g *.tgz
        which $(node -p "Object.keys(require('./package.json').bin)[0]")
        $(node -p "Object.keys(require('./package.json').bin)[0]") --version

    - name: Test CLI installation (Windows)
      if: matrix.os == 'windows-latest'
      run: |
        npm pack
        npm install -g *.tgz
        where $(node -p "Object.keys(require('./package.json').bin)[0]")
        $(node -p "Object.keys(require('./package.json').bin)[0]") --version

    - name: Upload coverage
      if: matrix.os == 'ubuntu-latest' && matrix.node == '20'
      uses: codecov/codecov-action@v3
      with:
        files: ./coverage/lcov.info

    - name: Check for security vulnerabilities
      if: matrix.os == 'ubuntu-latest'
      run: npm audit --audit-level=high

  integration:
    runs-on: ubuntu-latest
    needs: test
    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: Install dependencies
      run: npm ci

    - name: Build
      run: npm run build

    - name: Integration tests
      run: npm run test:integration

    - name: E2E tests
      run: npm run test:e2e

Success Metrics

• Installs globally without PATH issues
• Works on Windows, macOS, Linux
• < 100ms startup time
• Handles piped input/output
• Graceful degradation in CI
• Monorepo aware
• Proper error messages with solutions
• Automated help generation
• Platform-appropriate config paths
• No npm warnings or deprecations
• Automated release workflow
• Multi-binary support when needed
• Cross-platform CI validation

Code Review Checklist

When reviewing CLI code and npm packages, focus on:

Installation & Setup Issues

• Shebang uses #!/usr/bin/env node for cross-platform compatibility
• Binary files have proper executable permissions (chmod +x)
• package.json bin field correctly maps command names to executables
• .gitattributes prevents line ending corruption in binary files
• npm pack includes all necessary files for installation

Cross-Platform Compatibility

• Path operations use path.join() instead of hardcoded separators
• Platform-specific configuration paths use appropriate conventions
• Line endings are consistent (LF) across all script files
• CI testing covers Windows, macOS, and Linux platforms
• Environment variable handling works across platforms

Argument Parsing & Command Structure

• Argument parsing uses established libraries (Commander.js, Yargs)
• Help text is auto-generated and comprehensive
• Subcommands are properly structured and validated
• Unknown options are handled gracefully
• Workspace arguments are properly passed through

Interactive CLI & User Experience

• TTY detection prevents interactive prompts in CI environments
• Spinners and progress indicators work with async operations
• Color output respects NO_COLOR environment variable
• Error messages provide actionable suggestions
• Non-interactive mode has appropriate fallbacks

Monorepo & Workspace Management

• Monorepo detection supports major tools (pnpm, Nx, Lerna)
• Commands work from any directory within workspace
• Workspace-specific configurations are properly resolved
• Package hoisting strategies are handled correctly
• Postinstall scripts work in workspace environments

Package Distribution & Publishing

• Package size is optimized (exclude unnecessary files)
• Optional dependencies are configured for platform-specific features
• Release workflow includes comprehensive validation
• Version bumping follows semantic versioning
• Global installation works without PATH configuration issues

Unix Philosophy & Design

• CLI does one thing well (focused responsibility)
• Supports piped input/output for composability
• Exit codes communicate status appropriately (0=success, 1=error)
• Follows "silence is golden" - minimal output unless verbose
• Data complexity handled by program, not forced on user

Weekly Installs

3

Repository

0xkynz/codekit

GitHub Stars

1

First Seen

6 days ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

mcpjam3

claude-code3

replit3

junie3

windsurf3

zencoder3

React Router 框架模式指南：全栈开发、文件路由、数据加载与渲染策略

1,200 周安装