@icebreakers/monorepo-templates 2.1.0 → 2.2.0

package/templates/vitepress/zh/reference/knip.md

@@ -0,0 +1,55 @@
+---
+title: 闲置代码与依赖检查
+description: 显式运行原生 Knip，并使用审阅后的基线逐步治理。
+---
+
+# 闲置代码与依赖检查
+
+`repo check knip` 调用工作区根目录已安装的 [Knip](https://knip.dev/)，报告闲置文件、导出、依赖，以及缺少声明的导入。这是显式启用的可选检查，普通 `repo check`、staged、full 和 affected 模式保留原有行为。
+
+```bash
+pnpm add -Dw knip@^6.39.0
+pnpm exec repo check knip --recommend-config
+pnpm exec repo check knip --dry-run --json
+pnpm exec repo check knip --json
+pnpm exec repo check knip --config knip.config.ts --strict
+```
+
+支持 `>=6.39.0 <7`。repoctl 不下载 Knip、不回退到父目录或全局安装、不将其作为运行时依赖，不运行 `--fix`，也不删除代码。工具缺失或版本不支持时，输出安装指引并失败。此命令关闭 Jiti 磁盘缓存。原生配置及插件仍按 Knip 自身的方式执行，因此应使用可信的仓库配置。
+
+## 原生配置
+
+`--recommend-config` 输出供人工合并的 JSON 建议，列出现有配置，不覆盖或写入它们。建议包含 pnpm workspace、库和 CLI 入口、根目录工具脚本、类型测试，以及构建、覆盖率、框架缓存和 Worker 类型等生成文件的显式排除规则。
+
+项目的 [Knip 原生配置](https://knip.dev/reference/configuration) 与框架插件仍是分析依据。若插件无法推断动态加载或约定式入口，使用 `entry` 显式声明。通过原生 `ignoreFiles`、`ignoreIssues` 审阅并排除示例或 fixture；不会默认豁免所有示例。`"exports": "warn"` 等规则保留原生严重级别。
+
+`--production` 使用 Knip 的 production 分析范围；`--strict` 同时启用 production 范围，并按工作区检查直接依赖声明，避免根目录声明掩盖子包缺失声明。加入 CI 前应先检查原生 production 入口范围。
+
+JSON 报告包含工作区、文件、可用的源码位置、分类、原生诊断信息与 `warn`/`error` 严重级别。配置和标签提示也保留各自级别。退出码如下：
+
+| 状态码 | 含义                                          |
+| ------ | --------------------------------------------- |
+| `0`    | 所选策略通过，警告及基线已有问题仍显示。      |
+| `1`    | error 问题阻断所选策略。                      |
+| `2`    | 分析不完整、本地工具缺失/不支持，或基线无效。 |
+
+**`check knip`** 的 `--json` 输出实际分析结果，另加 `--dry-run` 才是工具命令预览。这两个共享选项可放在 `knip` 前后，其他 Knip 参数放在子命令后面，不能混用父级 `check` 执行模式或选项。`--timeout <ms>` 默认 120000 毫秒。
+
+## 审阅后的基线
+
+```bash
+# 审阅现有问题后，显式创建或更新基线。
+pnpm exec repo check knip --save-baseline knip-baseline.json --json
+# CI 仅阻断新增 error；仍列出已有、新增和已修复问题。
+pnpm exec repo check knip --baseline knip-baseline.json --new-only --json
+```
+
+保存不会隐藏本次问题的退出码：基线可能成功写入，但命令仍以 `1` 退出。普通分析不会更新基线。`--save-baseline` 不能与比较、new-only、dry-run 或配置建议选项混用。未加 `--new-only` 时，比较仍阻断全部当前 error。
+
+问题身份包含分类、严重级别、工作区、文件和符号；仅行号变化不会被当作新增问题，严重级别升级会视为新增。基线绑定 Knip 精确版本、production/strict 模式、根包名称、原生工作区集合、主要配置摘要、报告分类和启用插件。缺失、格式错误、重复、篡改或范围不兼容的基线均失败，即使当前没有 error 也不会放行。
+
+主要配置包含选中的文件、发现的标准 Knip 文件、根 `package.json#knip` 和 pnpm workspace 包模式。修改源码、修复依赖不会令基线失效。导入的配置辅助模块、环境变量驱动的行为，以及各插件的所有辅助配置无法完整指纹化；改变这些分析策略后，需要审阅并显式重新生成基线。
+
+基线输出必须位于工作区内，父目录须已存在且没有链接。已有目标必须是有效基线，不能覆盖其他配置或普通文件。新文件以独占方式创建；更新先暂存并检查并发变化，文件系统失败保留原基线。中断或清理失败时，先检查报告中保留的 `.repoctl-knip-*.tmp` 路径，再重试。
+
+公开 API 为 `planKnipCheck(cwd, options)`、`runKnipCheck(cwd, options)`、`getKnipConfigurationSuggestions(cwd)` 和 `saveKnipBaseline(cwd, report, file)`。支持 `timeoutMs` 与 `AbortSignal`，不完整或被中断的分析不能保存。config 路径相对 `cwd`，baseline 路径相对工作区根目录，从子包执行时也一致。

package/templates/vitepress/zh/reference/move.md

@@ -0,0 +1,39 @@
+# 移动或重命名工作区
+
+`repo workspace move` 分别支持目录移动、npm 包名修改，以及两者同时变更。用准确包名或 `./目录` 选择一个包，`--to` 指定相对工作区根的目标目录，`--name` 指定新 npm 包名。
+
+```bash
+repo workspace move @acme/ui --to libs/ui --json > ../move-plan.json
+repo workspace move @acme/ui --name @acme/design --json > ../rename-plan.json
+repo workspace move ./packages/ui --to libs/design --name @acme/design --json > ../move-plan.json
+repo workspace move --apply ../move-plan.json --json
+```
+
+默认只预览。将 JSON 保存到所选目录之外，审查新旧位置与包名、直接及传递消费者、文件内容、变更字段、阻塞项和人工任务，再显式应用。目标包与待更新文件必须处于干净的 Git 状态，没有强制绕过模式。`--apply` 不能与选择或预览选项混用。
+
+计划会更新四种依赖段的包名键、对应元数据、`workspace:` / `npm:` 别名，以及相对 `workspace:` / `link:` / `file:` 引用。别名键保留，除非它本身就是旧包名。普通 semver 引用沿用共享依赖图的本地候选语义；无法解析或非本地声明只列为人工候选，不猜测目标。与旧目录一致的 `repository.directory` 会同步。保留已有 workspace glob，移动准确路径项，必要时添加目标目录；被排除规则匹配的目标会被拒绝。
+
+对 Git 跟踪的 `tsconfig.json` 和 `tsconfig.*.json`，支持保留 JSONC 注释，更新相对 `extends`、项目 references、`files` / `include` / `exclude`、路径别名，以及显式的 `baseUrl`、`rootDir` / `rootDirs`、`outDir`、`declarationDir`、`typeRoots`。可能改变覆盖范围的较宽 include/exclude glob 保留原样并提示人工复核，不分析通配符展开结果。不执行配置继承解析；`paths` 可能依赖继承的 `baseUrl` 时保持原样并列出人工任务。绝对路径、可执行配置和其他配置格式需要人工复核。
+
+源码保持原样。人工任务提供文件与行号，指出旧名称、旧路径和可能改变含义的相对字符串路径。这是有范围的 Git 跟踪文本扫描，并非完整 import 解析：忽略/未跟踪文件、二进制、超过 1 MiB 的文件、生成代码、插值字符串和动态引用不在覆盖范围内。符号链接文本保留并提示复核。构建前必须处理这些任务；直接依赖改名后，开发者仍需更新源码中的 import。
+
+根目录、越界路径、已存在目标、重复或无效包名、目标祖先中的链接、工作区重叠、内嵌 Git、脏输入和过期计划都会被拒绝。目标目录中的所有文件（包括忽略文件）均纳入清单，提交变更前校验哈希、文件身份、工作区成员和 Git HEAD。失败时协调恢复清单与目录；并发编辑和新建替代目录会保留，并报告恢复路径。若变更已提交但清理失败，返回 `status: applied` 与 `cleanupPending`，检查后再清理。成功且未继续修改的计划可以重复应用，不再次写入。
+
+应用过程从首次重新校验或重复应用检查，到清理或回滚结束，持续持有 `.repoctl/workspace-move.lock`。并发应用会被拒绝。进程异常退出后，先确认没有活动写入者并恢复待处理备份，再人工移除遗留锁。
+
+所选目录内已登记的模板实例会同步移动。预览列出实例 ID 与新旧目标；ID、来源版本、生成参数和基线保持不变，仅修改包名时也遵循这一规则。业务修改仍作为本地变更参与后续模板漂移检查和三方升级。目录、清单和实例目标在实例登记锁内共同提交；登记写入失败时，先恢复文件与目录再释放锁。重复应用也会核对预期登记状态。实例存在待恢复的升级记录时禁止移动，先用 `repo templates recover-upgrade <id>` 检查。仅移动父实例的一部分、复用其他实例已占用的路径（即使原目标缺失）都会被拒绝。
+
+腾出的原路径可以再次创建同模板项目。登记会在锁内分配独立 ID，让已移动项目与新项目分别保留升级历史。若移动已提交但实例锁无法清理，结果仍为 `applied`，并在 `cleanupPending` 中给出准确路径；检查并确认没有活动写入者后再移除遗留锁。
+
+命令不改写锁文件、不执行安装脚本。处理完人工任务后，显式运行：
+
+```bash
+pnpm install --lockfile-only
+pnpm install --frozen-lockfile
+repo check
+git diff
+```
+
+已发布包改名意味着新的 npm 包身份。此命令不发布、不废弃旧包，也不执行 Git 提交或推送。
+
+构建产物 API 导出 `planWorkspaceMove(cwd, options)`、`applyWorkspaceMovePlan(cwd, plan)`、`WorkspaceMoveOptions`、`WorkspaceMovePlan` 和 `WorkspaceMoveResult`。

package/templates/vitepress/zh/reference/organization-presets.md

@@ -0,0 +1,89 @@
+# 组织工程预设
+
+组织预设是包含 `repoctl.preset.json` 的普通 npm 包，用于在独立仓库之间共享配置、模板、能力建议和少量有明确归属的工程文件。
+
+先显式安装，并在工作区根 `package.json` 中保存精确版本：
+
+```bash
+pnpm add -Dw --save-exact @acme/repoctl-preset@1.2.3
+```
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  presets: [{ packageName: '@acme/repoctl-preset', version: '1.2.3' }],
+  commands: { clean: { includePrivate: false } },
+})
+```
+
+引用、依赖声明和已安装包的名称及版本必须一致，不接受版本范围或 tag。加载仅读取已安装的 JSON，不导入包入口、不执行包脚本、不安装依赖、不下载模板、不写缓存。
+
+## 包契约
+
+发布包的 `files` 应包含清单及引用的资产：
+
+```json
+{
+  "schemaVersion": 1,
+  "requires": { "repoctl": ">=5.6.0 <6" },
+  "config": {
+    "commands": {
+      "clean": { "includePrivate": true },
+      "release": { "qualityScripts": ["build", "lint", "test"] }
+    }
+  },
+  "templates": {
+    "acme-sdk": {
+      "source": "templates/sdk",
+      "target": "packages/sdk",
+      "category": "library",
+      "label": "Acme SDK"
+    }
+  },
+  "capabilities": [{ "id": "playwright", "reason": "浏览器交互检查" }],
+  "assets": [{ "source": "assets/check.mjs", "target": "scripts/acme-check.mjs" }]
+}
+```
+
+可选 `extends` 使用同样的精确 `{ packageName, version }` 引用。父预设还需在预设包的 `dependencies` 或 `devDependencies` 中精确声明并已安装；发布包必需的父预设应放入 `dependencies`。加载顺序为依赖预设、声明它的预设、后续顶层预设、原有 C12 项目配置、显式 CLI 参数。预设边界的对象按字段合并，数组整体替换；项目配置内部保留 C12 原有语义。预设 `config` 不接受 C12 元数据、其他 `presets`、`templatesDir` 或 `templateMap`，应使用清单的 `extends` 和 `templates`。
+
+相同引用重复出现时给出诊断并只应用一次。循环引用、同包不同版本、不兼容的 `requires.repoctl`、未知配置、危险资产路径和不支持的能力 ID 会阻止消费命令。最多解析 64 个包、16 层依赖。
+
+```bash
+repo presets inspect --json
+repo config inspect --json
+repo config inspect --command clean --set 'includePrivate=false' --json
+repo templates --json
+```
+
+配置检查包含有序 `layers` 和逐字段 `sources`，标明包名及版本；`effective.sources` 还说明命令默认值与 CLI 覆盖。既有 `effective.origins` 保持 `default | project | cli`，其中预设继续归入 project，兼容现有消费者。配置报告的脱敏规则覆盖每一层。
+
+模板按预设顺序进入统一目录，项目模板声明优先。每个模板使用声明它的预设包的精确 npm 身份。`templates` 与 `config inspect` 仅检查声明；用 `repo templates fetch acme-sdk` 准备经过完整性验证的模板内容，实际创建也可以准备缓存。创建预览和 `--offline` 创建要求已有验证通过的缓存。registry 配置与完整性检查遵循[远程模板来源契约](./templates.md)，不会把已安装配置包直接当作验证过的远程模板缓存。
+
+能力清单仅为建议。加载预设或应用工程文件不会安装、应用能力；审阅后使用显式 `repo tooling` 能力工作流。
+
+## 受管工程文件
+
+```bash
+repo presets plan --json --out preset-plan.json
+repo presets apply preset-plan.json --json
+```
+
+计划默认只读，`--out` 只创建新的审阅文件。计划包含包身份、输入指纹、准确变更、diff 和归属记录。应用需显式执行，输入变化或计划被篡改会被拒绝，重复应用已完成计划不产生变更。将 `.repoctl/baselines/presets` 与受管文件一起提交。
+
+允许的目标包括受支持的根工具配置、GitHub 工作流及 issue 模板、指定 VS Code 配置和工程脚本；不能声明业务代码、依赖清单或 repoctl 内部元数据。拒绝包内符号链接、路径穿越和不兼容平台的文件名。新预设不能认领已有文件，即使内容相同，也不能接管其他预设或 repoctl 的 baseline。多个已启用预设争用同一路径时，整个计划被阻止。已有归属时请选择新目标；首版不自动转移所有权。
+
+升级时显式安装新精确版本、更新引用，再审阅新计划。上一版上游 baseline 用于三方合并：不重叠的本地修改会保留，重叠修改或本地删除会阻止写入。清单不再声明的文件及其归属记录继续保留，删除和归属转移需要单独人工审阅。
+
+工作区锁覆盖校验、暂存、写入和回滚，受管文件写入后才推进 baseline。失败会恢复原始字节；并发编辑及恢复备份会被保留，不会被回滚覆盖。进程中断后，请保留 `.repoctl-upgrade-*.bak`/`.tmp`，确认没有活跃写入进程，按报错核对备份和 baseline 后，再移除遗留 `.repoctl/upgrade.lock` 并重新生成计划。
+
+公共 API 为 `resolveOrganizationPresets(cwd, references)`、`planOrganizationPresetAssets(cwd)` 和 `applyOrganizationPresetAssets(plan)`。解析器返回结构化预设诊断；读取配置的 API 会在写入前将阻断诊断映射为配置校验失败。
+
+## 维护升级 PR
+
+首次显式采用后，[维护工作流](../tasks/checks.md)可在直接配置的预设根依赖精确版本变化时更新已有受管文件。将新依赖、匹配的 `presets` 引用和 frozen lockfile 一起提交。准备阶段核对两个提交的依赖清单、锁定版本与已安装包身份，复用显式预设应用的三方合并和事务。无关依赖变化不运行资产校验；冲突或检查失败保留阻断报告；内容相同或重复运行不创建 PR。
+
+在验证通过的预设已安装时，运行 `repo maintenance workflow --out .github/workflows/repoctl-upgrade.yml`。导出的工作流固化包名、源路径、目标路径三元组。发布 job 独立读取已提交的根依赖和已有归属记录，校验补丁及 baseline 的准确 hash，通过后才获取写凭证。报告不能自行增加路径授权。新增工程文件或改变来源时，先显式采用、审阅，再导出并审阅新工作流；导出命令保护已有文件。仅通过继承引入的预设升级、移除及归属转移仍需显式预设流程。业务文件不会进入自动维护。
+
+维护报告保持 schema version 1：`versions` 和 `plan` 继续表示 repoctl 自身，新增可选 `presets` 保存预设版本、选中计划及跳过的新文件。`planOrganizationPresetAssets(cwd, targets?)` 支持精确目标子集，省略时仍计划全部声明资产；应用时重算同一选择。只有版本变化而上游字节未变时，不单独推进记录；后续实际变化仍从上一份已记录上游内容合并。

package/templates/vitepress/zh/reference/removal.md

@@ -0,0 +1,42 @@
+# 安全移除工作区包
+
+`workspace remove` 按准确包名或显式工作区相对目录预览移除单个包。计划包含根包和私有包消费者、传递依赖路径、目录内容（含忽略文件）、准确清单变更，以及待人工复核的源码/配置引用。
+
+```bash
+repo workspace remove @acme/legacy
+repo workspace remove ./packages/legacy --dry-run --json > ../remove-plan.json
+# 显式将消费者清单中的依赖字段纳入移除计划：
+repo workspace remove @acme/legacy --remove-references --json > ../remove-plan.json
+repo workspace remove --apply ../remove-plan.json --json
+```
+
+预览始终只读，`--dry-run` 用于明确默认行为。请将计划保存在所选包之外。存在阻塞项时仍输出 JSON，但退出码为 1。写入必须另行使用 `--apply`，不能同时传入目标、`--remove-references` 或 `--dry-run`。
+
+## 选择边界和阻塞项
+
+首版要求 Git 仓库已有提交，所选目录没有暂存、未暂存或未跟踪变更。忽略文件会进入待审查的目录清单。根包、工作区外路径、目标祖先中的符号链接、内嵌 Git 仓库，以及包含未选择嵌套工作区的目录均不可移除。重名包必须用显式 `./目录` 消除歧义。这些边界没有 force 绕过选项。
+
+默认情况下，存在消费者就阻止移除。`--remove-references` 仅计划删除预览中列出的准确依赖字段，以及对应 `peerDependenciesMeta` 和不再使用的 `dependenciesMeta` 项；保留无关字段和依赖声明。可能指向目标的不确定图关系（包括未解析 catalog 别名）会阻塞应用。首版只支持每个工作区包使用单一 JSON 清单。
+
+人工复核扫描仅检查所选包外 Git 跟踪的文本，以包名/目录字面量匹配，不解析 import 或动态配置。未跟踪/忽略文件、二进制、符号链接、硬链接、超过 1 MiB 的文件、不支持的文本扩展名和锁文件均被排除。`review.scanned`、`review.matches`、`review.skipped` 描述这一有限证据；命中项需要人工检查，不会自动替换。请另行检查源码 import、scripts、Turbo 配置、workspace glob、bundled dependency 列表、文档和发布配置。
+
+## 应用和恢复
+
+应用前重新生成计划，拒绝清单、工作区集合、Git HEAD、已扫描文本、目录条目、内容、修改时间或链接目标发生漂移的计划。JSON 包含绝对路径和清单内容，分享前请先在本地检查。
+
+工作区操作锁 `.repoctl/workspace-remove.lock` 覆盖重复应用检查、验证、写入、验收、回滚和清理。重叠执行的删除会报告锁定，包括相同计划。进程中断后，先确认没有活动写入进程并恢复保留的原文件，再手动移除锁文件。
+
+事务先暂存清单替换文件，再将所选目录移动到 `node_modules/.cache/repoctl/removals/` 下本次操作专用目录。恢复目录的祖先必须是真实目录；跨设备移动失败会安全退出，不采用复制后删除的降级。提交前发生错误，会在安全前提下恢复已修改清单和原目录。并发编辑与新建的目标目录会被保留；错误中列出保留的原文件路径，供人工恢复。提交后仅清理失败时，返回 `status: "applied"` 和 `cleanupPending` 路径，不会谎报已回滚。核对这些准确路径后再清理，不要直接清空共享缓存。
+
+对于模板生成的包，移除会保留实例 ID、来源登记与模板基线。计划和执行结果会列出受影响实例，移除后它们显示为 `missing`。保留的登记仍拥有原路径，因此 `repo new` 拒绝复用，并给出所属实例 ID。可从版本控制或备份恢复原项目以延续这份历史，或为新项目选择其他未被登记占用的路径。重建模板基线仅恢复上游模板输出，不会恢复业务修改。移除包不会注销模板历史。
+
+命令不会修改锁文件。请使用仓库声明的 pnpm 版本显式完成后续步骤：
+
+```bash
+pnpm install --lockfile-only
+pnpm install --frozen-lockfile
+repo check --full
+git diff
+```
+
+程序调用可使用 `planWorkspaceRemoval(cwd, { target, removeReferences })` 和 `applyWorkspaceRemovalPlan(cwd, plan)`。JSON 计划的 schema 版本为 1。重复应用已完成的计划，仅在剩余工作区仍符合预期时返回 `unchanged`。

package/templates/vitepress/zh/reference/template-assets.md

@@ -81,19 +81,22 @@ repo templates --check --json --out reports/templates.json
 
 ## 5. 自定义模板
 
-可以在 `repoctl.config.ts` 里扩展模板映射：
+在 `commands.create.templateMap` 声明本地模板后，创建、交互选择、列表、详情和健康检查会使用同一份目录结果，包含 key、名称、说明、分类、源目录和默认目标。
 
 ```ts
+import { fileURLToPath } from 'node:url'
 import { defineMonorepoConfig } from 'repoctl'
 
 export default defineMonorepoConfig({
   commands: {
     create: {
-      defaultTemplate: 'internal-service',
       templateMap: {
         'internal-service': {
-          source: 'templates/internal-service',
+          source: fileURLToPath(new URL('./templates/internal-service', import.meta.url)),
           target: 'apps/internal-service',
+          label: 'Internal service',
+          category: 'service',
+          description: 'Company API service',
         },
       },
     },
@@ -101,7 +104,19 @@ export default defineMonorepoConfig({
 })
 ```
 
-自定义模板建议遵守同样的治理规则：唯一 source、唯一 target、模板根目录包含 `package.json`，并避免提交构建输出和缓存文件。
+```bash
+repo templates internal-service --json
+repo templates --check --json
+repo new payments --template internal-service --dry-run
+```
+
+绝对 `source` 路径可让内置模板和本地模板同时可用。相对 `source` 按 `templatesDir` 解析；默认根目录是已安装模板包。设置 `templatesDir: './templates'` 会替换所有模板（包括内置模板）的根目录，相对路径按配置文件所在目录解析。从 pnpm 子包目录运行时会查找工作区根配置，不会把模板路径移到子包内；生成目标仍按调用目录解析。
+
+字符串映射保持兼容：`templateMap: { custom: 'custom' }` 等价于 `{ source: 'custom', target: 'custom' }`。对象定义可补充 `label`、`description`、`category`。非空 `choices` 数组继续控制交互顺序和可选范围，其名称与说明也会显示在列表和详情中；未配置时列出全部模板。内置创建意图的默认模板不变；登记自定义模板后交互会直接展示模板目录。
+
+同名覆盖通过 `origin: 'custom'`、`overridesBuiltin: true` 及 `configFile` / `configPath` 显示。无效定义和重复交互 key 会定位到配置字段；`repo templates --check` 还会检查重复 source/target、失效目录和缺失 `package.json`。列表 JSON 仍为数组、详情 JSON 仍为对象，只增加目录字段；创建 JSON 的 `templateInfo` 携带所选模板的相同信息。
+
+列表与健康检查只读取声明和文件，不生成项目，也不执行模板代码；显式 `--out` 才写出报告。程序调用可使用 `resolveTemplateCatalog({ cwd })` 和 `checkTemplates({ cwd })`。
 
 ## 6. 维护流程