从零搭建 TypeScript CLI/npm…

需要从零初始化一个带固定工具链、双 tsdown 输出、changesets 和 npm OIDC 发布模板的 TypeScript CLI/npm 包时使用。

适用场景

解决思路

1. 仅用于从零引导全新 TypeScript CLI 或 npm 包（Node 24、TypeScript 7），使用 references/ 中固定模板，目标是通过首次 CI 并得到 npm 可通过 OIDC 发布的包。
2. 保持既定工具链：tsdown 而非 tsup，vitest 而非 jest，通过 ultracite 使用 oxlint 和 oxfmt 而非 eslint 或 prettier，node:util styleText 而非 chalk，@clack/prompts 而非 ora；不要替换其中任何一项或重构布局，否则模板说明不再适用。
3. Step 1 收集项目信息：只询问用户未提供的 {{name}}、{{description}}、{{bin}}、{{repo}}、{{author}}、{{year}}；{{bin}} 默认与 {{name}} 相同，{{year}} 默认当前年份；{{repo}} 必须是精确的 GitHub owner/name，因为 npm provenance 会拒绝 repository.url 与来源仓库不一致的发布。
4. Step 2 创建目录结构：在 {{name}}/ 下创建 .changeset/、.github/workflows/、src/、skills/{{bin}}/。
5. Step 3 生成配置文件：加载 references/scaffold-configs.md，生成其中每个文件并替换每个 {{placeholder}}：package.json、tsconfig.json、tsdown.config.ts、.gitignore、LICENSE.md、.changeset/config.json、.changeset/README.md、.github/workflows/ci.yml、.github/workflows/npm-publish.yml。
6. Step 4 生成源文件：加载 references/scaffold-source.md，生成 src/cli.ts（Commander 入口点，带 agent-friendly 默认值：--output text|json、--no-input、stdout 数据/stderr 日志分离、JSON 错误信封）、src/index.ts（公共 API 导出）、src/types.ts（共享类型定义）。
7. Step 4 条件做法：当命令接受标识符、路径或 URL，或会改变状态时，额外加载 references/agent-friendly-cli.md 并复制匹配的固定模式；若 CLI 没有此类命令则跳过。
8. Step 5 生成文档与技能：从同一 references/scaffold-source.md 生成 AGENTS.md（命令、架构、陷阱、agent 不变量）、README.md（安装、使用、API、agent skill 安装、许可证）、skills/{{bin}}/SKILL.md（agent skill 定义）；直接使用 AGENTS.md，不要创建 CLAUDE.md 包装或符号链接。
9. Step 6 运行 scaffold 后命令：加载 references/post-scaffold.md，按给定顺序运行命令序列，包括在 ultracite init 和首次提交之间覆盖 lefthook.yml。
10. Step 7 验证 scaffold：运行 references/post-scaffold.md 中的验证清单；每一项都是命令，其输出是证据；清单包括 publint、arethetypeswrong、针对真实文件演练 hook、以及占位符扫描。
11. Step 8 引导 GitHub 与 npm：若是本地 scaffold，到 Step 7 后停止；若用户已请求远程设置或发布，执行已授权范围；否则在询问创建或发布前先展示准备好的 repository/package 身份。
12. Step 8 远程 bootstrap：按 references/post-scaffold.md 中「Bootstrap GitHub and npm」执行：创建并推送 repo，启用 Actions-created PRs，手动发布 0.0.1 一次使包存在，然后把 workflow 注册为 trusted publisher；终端证据是推送提交上 CI 绿色且 npm view {{name}} version 打印 0.0.1；此后每次发布归 autoship。
13. 依赖：运行时使用 @clack/prompts、commander；开发依赖在 package.json 模板中包括 @changesets/cli、@types/node、tsdown、typescript、vitest；由 ultracite init 添加且绝不手工列出：ultracite（由 init 精确固定）、oxlint、oxfmt、lefthook，以及 check、fix、prepare 脚本；手工添加会产生重复脚本和版本偏移。
14. tsdown 默认输出 .mjs：platform: node（默认）时 fixedExtension 开启，若配置中没有 outputOptions.entryFileNames: "[name].js"，会构建 dist/cli.mjs、dist/index.mjs、dist/index.d.mts，导致 bin 和 exports 指向不存在的文件；模板中的 outputOptions 块就是保持 .js 的关键，不要当作噪音删掉。
15. 不要在 src/cli.ts 中写 shebang：tsdown 的 banner 会注入 #!/usr/bin/env node，源 shebang 会在 dist/cli.js 中重复；两个构建入口保持分开：CLI 入口有 banner 且 dts: false，库入口有 dts: true 且无 banner。
16. ultracite init --quiet 必须带 --linter oxlint：不带时 quiet 模式默认 linter 为 Biome，仓库会静默使用错误工具链；要传递 post-scaffold 命令中的每个 flag。
17. 在 ultracite init 之前先 git init：init 会添加 prepare: lefthook install 并立即运行；lefthook install 写入 .git/hooks，没有仓库会失败。
18. 首次提交前替换生成的 lefthook.yml：它运行 npx ultracite fix 且没有文件参数，一行改动会重新格式化整个树（参考仓库中 31 个文件）；其 **/*.ts glob 从不匹配根文件，所以 package.json 和 tsdown.config.ts 编辑会绕过 hook；仅添加 {staged_files} 更糟，因为仅 JSON 提交（changesets bot 的 Version Packages 提交形状）会让 oxlint 没有可 lint 文件并退出 1；使用 references/post-scaffold.md 中的版本，用 *.{...} glob，绝不用 **/。
19. 不要用 touch <file> && git add <file> 来验证 hook：未更改文件没有 staged diff，hook 会跳过，检查证明不了任何东西；用 npx lefthook run pre-commit --file <path> 演练 hook。
20. 避免 "test": "vitest run" 不带 --passWithNoTests：在零测试文件仓库会退出 1，导致首次 CI 变红。
21. @changesets/cli@3 与 changesets/action@v2 及 publish-script: 输入配对：@v1 不能驱动 changesets v3；@v2 给 v1 的 publish: 输入会版本化包然后绿色完成但不发布；模板携带匹配对，不要降级一侧。
22. npm 不能为尚不存在的包注册 trusted publisher：在 Step 8 的一次性手动 npm publish 创建包并注册 workflow 之前，首次发布运行会失败 E404 或 ENEEDAUTH；该发布发生在任何 changeset 之前，是 autoship 规则不禁止的唯一手动发布。
23. 注意 npm 版本：Node 22 自带 npm 10.9.x，OIDC 发布需要 npm 11.5.1 或更高；Node 24 自带 npm 11.19，所以两个 workflow 都固定 node-version: 24；降到 22 会因 ENEEDAUTH 破坏发布。
24. Agent 面向输出是格式契约：数据在 stdout，日志和进度在 stderr；多余的 console.log 会破坏解析 --output json 的消费者；stdin 不是 TTY 时绝不提示：遵守 --no-input，每个值都作为 flag 传入，否则进程在管道下挂起。
25. 替代项目值并对照已安装包版本验证模板 API；修复已证实的不兼容，而不是盲目复现。
26. 相关技能：autoship 处理 bootstrap 发布后的每次发布；dx-audit 在真实命令存在后审计 CLI flags、errors、types；agents-md 随代码库成长扩展生成的 AGENTS.md；ghostwriter 在有真实使用故事后重写 README；evals/evals.json 仅用于维护此技能的回归场景，不加载于用户任务。

适用边界 · 注意事项

• 不是 Next.js Web 应用；若需要 Next.js 应用脚手架，用 scaffold-nextjs。
• 不是为已有代码库建立目录结构或模块契约；此类任务用 codebase-architecture。
• 不是审计已有 CLI 的人机工程，也不是发布已有包；分别用 dx-audit 和 autoship。