个人 Node CLI 脚本库

这是一个私有 Node CLI 包，用来维护本地开发、仓库维护和自动化处理相关的可复用命令。默认使用 pnpm 管理依赖和开发命令，不发布到 npm registry。

目录结构

.
├── bin/                 # npm CLI shim 入口，只做参数转发和错误出口
├── src/
│   ├── commands/        # 每个工具一个命令模块
│   └── shared/          # 至少两个命令复用后才放共享工具
├── tests/               # node:test 测试
├── docs/                # 每个命令的使用文档
├── examples/            # 示例输入、配置或调用方式
├── README.md            # 工具索引、安装、开发约定
└── AGENTS.md            # 仓库协作约束

安装

pnpm install

可用命令

命令	用途	文档
zread-generate	生成 .zread 文档，并支持重试、草稿续跑和结果校验	docs/zread-generate.md

本地运行

pnpm exec zread-generate --cwd /path/to/repo

查看帮助：

pnpm exec zread-generate --help

开发验证

pnpm test

测试使用 Node 内置 node:test，默认不引入额外测试依赖。

新增命令流程

1. 在 src/commands/<name>.js 中实现命令逻辑，并导出可测试的纯函数或主入口。
2. 在 bin/<name>.js 中创建带 shebang 的薄入口，只负责调用命令模块和设置退出码。
3. 在 package.json 的 bin 字段注册命令名。
4. 在 docs/<name>.md 中补充使用文档、参数、环境变量、副作用和退出码。
5. 在 tests/ 中补充参数解析、关键分支和 CLI 冒烟测试。
6. 更新本 README 的命令索引。
7. 提交前运行 pnpm test，必要时再补充 lint、typecheck 或更贴近命令副作用的验证。

约定

• 命令名使用清晰的短横线形式，例如 zread-generate。
• bin/ 入口保持薄，只做参数转发、调用主入口和统一退出码处理。
• 业务逻辑放在 src/commands/，便于测试和后续维护。
• 只有至少两个命令真实复用时，才把代码提取到 src/shared/。
• 优先使用 Node 标准库，不新增运行时依赖。
• 会写入文件或调用外部工具的命令，必须在对应文档中说明写入位置、前置依赖和失败模式。
• 生成物、缓存、凭据以及一次性下载内容不提交到 git；只有持续出现的临时文件类型才加入 .gitignore。