@icebreakers/monorepo-templates 1.0.15 → 1.2.0

package/templates/vitepress/monorepo/publish.md

@@ -1,260 +1,32 @@
-# monorepo 发包与变更日志
+# Publishing and Changelogs
 
-这套模板默认推荐用 `changesets` 管理版本和 changelog。原因不是“它很流行”，而是它对 monorepo 的工作方式最顺手：
+repoctl coordinates release tasks with pnpm versioning. It does not replace the registry, GitHub Actions, or package build scripts.
 
-- 变更是按包记录的
-- 版本升级能自动联动内部依赖
-- changelog 可以稳定产出
-- 很容易接到 CI 里
-
-repoctl 在发布流程里的位置很明确：它不替代 `changesets` 发布版本，而是在发布前帮你确认仓库状态、模板资产和校验计划。
-
-## repoctl 在发布前做什么
-
-```bash
-pnpm exec repo doctor --strict
-pnpm exec repo check --full
-pnpm exec repo env support --markdown --redact --out reports/support.md
-```
-
-| 命令                   | 发布前价值                                               |
-| ---------------------- | -------------------------------------------------------- |
-| `repo doctor --strict` | 确认仓库结构、Node、脚本、配置和提交链路没有漂移         |
-| `repo check --full`    | 跑根脚本里的 lint/typecheck/test/build 计划              |
-| `repo env support`     | 保存环境、配置、doctor 和 check plan，方便发布失败后回溯 |
-
-发布本身仍交给 `changesets`：
+## Development Flow
 
 ```bash
-pnpm changeset
-pnpm exec repo release stable
+pnpm change
+pnpm change status
+repo release stable prepare
+repo release stable publish
 ```
 
-正式发布只走 `main`；`alpha`、`beta`、`rc`、`next` 只做 Changesets 的 prerelease，并发布对应 tag 包。
-
-## 一条务实的发布流程
+Change intents record the affected package and release level. The release preparation step updates versions and repository changelogs; publish sends built packages to the configured registry.
 
-先把顺序记住：
+## Versioning Configuration
 
-1. 写代码
-2. 跑校验
-3. 生成 changeset
-4. 合并后 version / publish
+Fixed groups and repository changelog storage live in `pnpm-workspace.yaml`. `repo doctor` reports missing or legacy release configuration.
 
-对应到命令，一般是：
+## Prerelease Lanes
 
 ```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm tsd
-pnpm test
-pnpm changeset
+repo release pre enter beta
+repo release pre publish
+repo release pre exit
 ```
 
-如果你改的是公开类型或类库 API，`tsd` 不要省。
-
-## 为什么推荐 `changesets`
-
-| 需求           | `changesets` 的做法                       |
-| -------------- | ----------------------------------------- |
-| 记录哪些包变了 | 每次变更生成单独的 `.changeset/*.md` 文件 |
-| 控制版本类型   | 明确选择 `patch` / `minor` / `major`      |
-| 自动生成日志   | `changeset version` 统一产出 changelog    |
-| 联动内部包版本 | 自动改内部依赖引用                        |
-| CI 自动发布    | 可接 `changesets/action`                  |
-
-## 日常开发阶段怎么做
-
-### 1. 本地先把质量门过掉
-
-```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm tsd
-pnpm test
-```
-
-这一点和仓库的提交要求是一致的。
-
-### 2. 记录 changeset
-
-```bash
-pnpm changeset
-```
-
-按提示选择：
-
-1. 哪些包受影响
-2. 这些包分别是 `patch` / `minor` / `major`
-3. 这次改动怎么写进 changelog
-
-示例：
-
-```md
----
-"@my/utils": minor
-"@my/ui": patch
----
-
-- feat(utils): 新增时间格式化工具
-- fix(ui): 修复按钮禁用态样式
-```
-
-### 3. 合并前看一眼影响面
-
-changeset 文件本身就是最便宜的“发布预告”。代码评审时顺手看一下，通常就能避免：
-
-- 漏记某个包
-- 版本类型选错
-- changelog 写得太含糊
-
-## 发布阶段怎么做
-
-### 手动流程
-
-```bash
-pnpm exec repo release stable
-```
-
-`repo release stable` 会先执行构建、lint 和测试，再调用 `changeset version` 与 `changeset publish`。其中 `changeset version` 会做这些事：
-
-- 更新受影响包的版本号
-- 调整内部依赖版本
-- 生成或更新每个包的 `CHANGELOG.md`
-
-### CI 自动流程
-
-模板推荐结合 `changesets/action`。
-
-一个常见的工作流结构如下：
-
-```yaml
-name: Release
-
-on:
-  push:
-    branches:
-      - main
-      - alpha
-      - beta
-      - rc
-      - next
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  pull-requests: write
-  issues: write
-  id-token: write
-
-env:
-  HUSKY: 0
-
-jobs:
-  release:
-    if: github.ref_name == 'main'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-      - uses: pnpm/action-setup@v6
-      - uses: actions/setup-node@v7
-        with:
-          node-version: 24
-          cache: pnpm
-          registry-url: https://registry.npmjs.org
-      - run: pnpm install
-      - name: Create Release Pull Request or Publish to npm
-        uses: changesets/action@v2.0.0
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          publish-script: pnpm exec repo release stable
-        env:
-          NPM_CONFIG_PROVENANCE: true
-
-  prerelease:
-    if: github.ref_name != 'main'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-      - uses: pnpm/action-setup@v6
-      - uses: actions/setup-node@v7
-        with:
-          node-version: 24
-          cache: pnpm
-      - run: pnpm install
-      - run: git config user.name "github-actions[bot]"
-      - run: git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-      - name: Publish Prerelease
-        run: pnpm exec repo release pre publish
-```
-
-## 关于 npm 鉴权
-
-现在更推荐在 CI 里使用 OIDC，而不是长期保存一个会过期的 `NPM_TOKEN`。
-
-原因很现实：
-
-- token 会过期
-- token 泄漏风险更高
-- OIDC 更适合自动化发布
-
-所以工作流里建议保留：
-
-```yaml
-permissions:
-  id-token: write
-```
-
-## 常见发布约束
-
-### 私有包不会被发布
-
-如果一个包是：
-
-```json
-{
-  "private": true
-}
-```
-
-那么它通常不会进入 npm 发布流程。
-
-### 没有 changeset 就不会有版本 PR
-
-如果你改了公开包，却没有提交 `.changeset/*.md`，那么后续版本流转通常会断掉。
-
-### 先 build 再发
-
-这个仓库的约定很明确：先 build，再 lint / typecheck / tsd / test，再谈发布。不要跳步。
-
-## 常见问题
-
-### 为什么没有生成 changelog？
-
-通常是下面几种原因：
-
-- 没有执行 `pnpm changeset version`
-- `.changeset/*.md` 没有提交
-- 受影响包实际没有进入版本计算
-
-### 如何跳过某个包的发布？
-
-- 在 changeset 里不要勾选它
-- 或者把它标记为 `private: true`
-
-### 为什么要在 PR 阶段就看 changeset？
-
-因为它本质上是在回答一个非常具体的问题：
-
-“这次改动准备怎么影响发布面？”
-
-这个问题越早看，越不容易在合并后补救。
+Supported lane names include `alpha`, `beta`, `rc`, and `next`.
 
-## 继续阅读
+## Recovery
 
-- [如何管理 monorepo](./manage.md)
-- [repoctl 工作流与 CI](../repoctl/workflows.md)
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
-- [命令别名](../repoctl/aliases.md)
+Use the publish-unpublished release mode to recover versions that were prepared but not published. Inspect the generated report before retrying a partial release.

package/templates/vitepress/monorepo/templates.md

@@ -1,21 +1,14 @@
-# 模板速查
+# Template Systems
 
-模板创建已经收敛到 repoctl 文档：
+Templates make repository conventions executable. repoctl ships internal source workspaces for libraries, Vue components, apps, services, documentation sites, and CLIs.
 
-- [repoctl 模板与创建](../repoctl/templates.md)
-- [repoctl 快速开始](../repoctl/getting-started.md)
+```bash
+repo templates
+repo templates --category library
+repo new sdk --template tsdown --dry-run
+repo templates --check
+```
 
-## monorepo 知识点：模板为什么重要
+The publishable `@icebreakers/monorepo-templates` package owns the registry and packaged assets. Individual `templates/*` workspaces are private and are not release units.
 
-当仓库里存在多种产物时，模板能把重复选择前置成稳定默认值：
-
-| 产物          | 常见目录                 | 关注点                         |
-| ------------- | ------------------------ | ------------------------------ |
-| TypeScript 库 | `packages/*`             | exports、types、构建和 tsd     |
-| Vue 组件库    | `packages/*`             | SFC、样式校验、类型声明        |
-| 应用          | `apps/*`                 | dev、build、部署资产           |
-| 服务          | `apps/*`                 | API 入口、运行时类型、环境变量 |
-| 文档站        | `apps/*`                 | VitePress 配置、导航、内容结构 |
-| CLI           | `apps/*` 或 `packages/*` | bin 入口、参数解析、发布       |
-
-repoctl 的 `repo templates` 和 `repo new` 负责把这些约定落实到文件系统。
+See [Templates](../repoctl/templates.md) and [Template Asset Management](../repoctl/template-assets.md).

package/templates/vitepress/monorepo/troubleshooting.md

@@ -1,20 +1,17 @@
-# 常见问题排障
+# Monorepo Troubleshooting
 
-repoctl 排障文档已经集中到：
+Start by identifying the problem class: workspace discovery, dependency installation, task orchestration, repository policy, or release state.
 
-- [repoctl 排障与报告](../repoctl/troubleshooting.md)
-- [repoctl 命令速查](../repoctl/commands.md)
+```bash
+repo doctor
+repo env support --markdown --redact --out reports/support.md
+repo check --full --dry-run
+pnpm change status
+```
 
-## monorepo 知识点：先区分问题类型
+- Workspace discovery failures usually point to `pnpm-workspace.yaml` patterns.
+- Missing task output or cache behavior belongs to Turbo task configuration.
+- Tooling drift belongs to managed config and `repo upgrade`.
+- Release failures require checking both versioning state and registry publication.
 
-排障前先判断问题属于哪一类：
-
-| 类型           | 先看什么                              | 常用命令                                |
-| -------------- | ------------------------------------- | --------------------------------------- |
-| 仓库结构问题   | 根目录、workspace 文件、Node 版本     | `repo doctor`                           |
-| 模板创建问题   | 模板 key、目标目录、创建计划          | `repo templates` / `repo new --dry-run` |
-| 提交前校验问题 | staged 文件、workspace 归属、任务路由 | `repo check --dry-run`                  |
-| 环境差异问题   | Node、pnpm、Git、CI、路径             | `repo env support --markdown --redact`  |
-| 遗留配置问题   | `repoctl.config.ts` 与旧配置文件      | `repo config inspect`                   |
-
-旧页面继续保留为知识点索引，具体排查步骤以后优先维护在 repoctl 分区。
+Do not overwrite custom files until the diagnostic report and planned changes are understood.

package/templates/vitepress/package.json

@@ -2,18 +2,24 @@
   "name": "@icebreakers/website",
   "type": "module",
   "version": "0.0.1",
-  "description": "https://repo.icebreaker.top source code",
+  "private": true,
+  "description": "Documentation website for repoctl",
   "author": "ice breaker <hi@sonofmagic.top>",
   "homepage": "https://repo.icebreaker.top",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sonofmagic/monorepo-template.git",
+    "url": "git+https://github.com/sonofmagic/repoctl.git",
     "directory": "templates/vitepress"
   },
   "bugs": {
-    "url": "https://github.com/sonofmagic/monorepo-template/issues"
+    "url": "https://github.com/sonofmagic/repoctl/issues"
   },
-  "keywords": [],
+  "keywords": [
+    "repoctl",
+    "documentation",
+    "vitepress",
+    "monorepo"
+  ],
   "scripts": {
     "dev": "vitepress dev",
     "build": "vitepress build",
@@ -35,7 +41,7 @@
     "mermaid": "^11.16.1",
     "tailwindcss": "^4.3.3",
     "vitepress": "^1.6.4",
-    "vitepress-plugin-llms": "^1.13.4",
+    "vitepress-plugin-llms": "^1.13.5",
     "vitepress-plugin-mermaid": "^2.0.17"
   }
 }

package/templates/vitepress/public/_redirects

@@ -0,0 +1,3 @@
+/en / 301
+/en/ / 301
+/en/* /:splat 301

package/templates/vitepress/repoctl/adopt-existing.md

@@ -1,17 +1,17 @@
-# 接入已有仓库
+# Adopt Existing Repositories
 
-repoctl 不只适合新模板仓库。它也可以渐进接入已有 pnpm workspace，用诊断报告和非覆盖同步把风险降下来。
+repoctl is not only for newly generated repositories. It can be adopted gradually in existing pnpm workspaces by using diagnostics and conservative asset syncs.
 
-## 适合接入的仓库
+## Good Candidates
 
-优先满足这些条件：
+A repository is a good fit when:
 
-- 已经使用 pnpm 或准备迁移到 pnpm。
-- 有根 `package.json`。
-- 能接受 `apps/*`、`packages/*`、`examples/*` 这类 workspace 目录约定。
-- 希望统一 `repo:init`、`repo:doctor`、`repo:new`、`repo:check` 这类日常入口。
+- It already uses pnpm, or is ready to move to pnpm.
+- It has a root `package.json`.
+- It can use workspace folders such as `apps/*`, `packages/*`, or `examples/*`.
+- The team wants stable daily entries such as `repo:init`, `repo:doctor`, `repo:new`, and `repo:check`.
 
-如果仓库还不是 pnpm workspace，先补最小 `pnpm-workspace.yaml`：
+If the repository is not yet a pnpm workspace, start with a minimal `pnpm-workspace.yaml`:
 
 ```yaml
 packages:
@@ -19,47 +19,47 @@ packages:
   - packages/*
 ```
 
-## 第一步：安装并初始化
+## Step 1: Install And Setup
 
 ```bash
 pnpm add -D repoctl
 pnpm exec repo init --yes
 ```
 
-`repo init --yes` 会使用安全默认值。它会补齐推荐脚本和 workspace patterns，但不会无条件覆盖已有 README、package.json、pnpm-workspace.yaml 或 tooling 配置。
+`repo init --yes` uses safe defaults. It adds recommended scripts and workspace patterns, but it does not blindly overwrite existing README, package.json, pnpm-workspace.yaml, or tooling files.
 
-## 第二步：保存第一次诊断
+## Step 2: Save The First Diagnostic Report
 
 ```bash
 pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
 pnpm exec repo doctor --json --out reports/doctor-before.json
 ```
 
-建议把第一次报告提交到 PR 评论或 artifact，而不是只看终端输出。
+Prefer saving the first report as a PR comment or CI artifact instead of relying only on terminal output.
 
-重点看这些项：
+Watch these checks:
 
-| 检查项                       | 常见问题                                         |
-| ---------------------------- | ------------------------------------------------ |
-| `package-json`               | 当前目录不是仓库根目录                           |
-| `workspace-manifest`         | 缺少 `pnpm-workspace.yaml`                       |
-| `node-version`               | 根 package 没声明 `engines.node` 或版本不匹配    |
-| `tool-package`               | 没安装 `repoctl`                                 |
-| `root-scripts`               | 缺少 `repo:init/repo:new/repo:check/repo:doctor` |
-| `config-file`                | 残留已废弃的 `monorepo.config.ts`                |
-| `commit-hooks`               | Husky 和 lint-staged 只接了一半                  |
-| `workspace-package-coverage` | package.json 没被 workspace patterns 覆盖        |
+| Check                        | Common Issue                                                      |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `package-json`               | Current directory is not the repository root                      |
+| `workspace-manifest`         | `pnpm-workspace.yaml` is missing                                  |
+| `node-version`               | Root package has no `engines.node`, or the version does not match |
+| `tool-package`               | `repoctl` is not installed                                        |
+| `root-scripts`               | `repo:init/repo:new/repo:check/repo:doctor` scripts are missing   |
+| `config-file`                | A stale `monorepo.config.ts` file is still present                |
+| `commit-hooks`               | Husky and lint-staged are only partially configured               |
+| `workspace-package-coverage` | Some package.json files are not covered by workspace patterns     |
 
-## 第三步：保守同步标准资产
+## Step 3: Sync Conservatively
 
 ```bash
 pnpm exec repo upgrade --no-overwrite
 pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
 ```
 
-`--no-overwrite` 适合第一次接入：它同步缺失资产，但保留已有 drifted 文件。你可以在 PR diff 里逐项看哪些配置要进一步迁移。
+Use `--no-overwrite` for the first adoption pass. It syncs missing assets while preserving changed managed files.
 
-## 第四步：预览校验计划
+## Step 4: Preview Verification
 
 ```bash
 pnpm exec repo check --dry-run
@@ -67,11 +67,11 @@ pnpm exec repo check --json --out reports/check-plan.json
 pnpm exec repo check --markdown --redact --out reports/check-plan.md
 ```
 
-先看 plan，再决定要不要接入 hook 或 CI。
+Review the plan before wiring hooks or CI.
 
-## 第五步：接入根脚本
+## Step 5: Use Root Scripts
 
-如果 `repo init` 已补齐根脚本，团队日常文档优先改成：
+After `repo init`, team docs can use:
 
 ```bash
 pnpm run repo:doctor
@@ -79,57 +79,55 @@ pnpm run repo:new -- sdk
 pnpm run repo:check
 ```
 
-CI 和自动化脚本仍建议写完整 CLI：
+CI and automation should still prefer explicit commands:
 
 ```bash
 pnpm exec repo doctor --strict
 pnpm exec repo check --full
 ```
 
-## 第六步：处理遗留配置
+## Step 6: Resolve Legacy Config
 
-### 遗留配置文件
+### Config Conflicts
 
-只保留：
+Keep only:
 
 ```txt
 repoctl.config.ts
 ```
 
-`monorepo.config.ts` 已不再加载；请改名为 `repoctl.config.ts`。
+`monorepo.config.ts` is no longer loaded at runtime; rename it to `repoctl.config.ts`.
 
-### 本地 tooling loader
+### Local Tooling Loader
 
-如果 `doctor` 提示 tooling 配置引用了本地源码 loader，使用：
+If `doctor` reports local source tooling loaders, migrate with:
 
 ```bash
 pnpm exec repo upgrade --yes
 ```
 
-这个命令会迁移到 `repoctl/tooling` 入口。简单的 `@icebreakers/commitlint-config`、`@icebreakers/eslint-config`、`@icebreakers/stylelint-config` wrapper 也会被保守转换为 `repoctl/tooling`，复杂 ESLint 配置会保留原有 rules、ignores、overrides 和额外 flat config 语义。
+The same migration also converts simple wrappers from `@icebreakers/commitlint-config`, `@icebreakers/eslint-config`, and `@icebreakers/stylelint-config` to `repoctl/tooling`. Complex ESLint configs keep their rules, ignores, overrides, and extra flat config semantics.
 
-### workspace patterns 不覆盖包
+### Workspace Pattern Gaps
 
-运行：
+Run:
 
 ```bash
 pnpm exec repo init --yes
 ```
 
-或手动扩展 `pnpm-workspace.yaml`。
+or manually extend `pnpm-workspace.yaml`.
 
-## 推荐 PR 结构
+## Recommended PR Shape
 
-存量仓库接入建议拆成小 PR：
+1. Install `repoctl` and add root scripts.
+2. Attach `doctor-before` and `doctor-after` reports.
+3. Sync or migrate tooling config.
+4. Wire hooks and CI.
+5. Verify scaffolding paths with `repo new --dry-run`.
 
-1. 安装 `repoctl`，补 `init/doctor/new/check` 根脚本。
-2. 提交 `doctor-before` 和 `doctor-after` 报告。
-3. 同步或迁移 tooling 配置。
-4. 接入 hook 和 CI。
-5. 用 `repo new --dry-run` 验证模板创建路径。
+## Keep Reading
 
-## 下一步
-
-- [工作流与 CI](./workflows.md)
-- [排障与报告](./troubleshooting.md)
-- [配置文件](./config.md)
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Configuration](./config.md)

package/templates/vitepress/repoctl/aliases.md

@@ -1,10 +1,10 @@
-# 命令别名
+# Command Aliases
 
-repoctl 保留了一组短别名，方便熟悉后在终端里少打字。团队文档仍建议优先写完整命令，减少新人理解成本。
+repoctl keeps several aliases for terminal convenience. Team docs should still prefer full commands because they are easier for new users to read.
 
-## 包入口别名
+## Binary Aliases
 
-`repoctl` 包提供多个 bin：
+The `repoctl` package exposes these bins:
 
 ```bash
 repo
@@ -14,9 +14,9 @@ rc
 mo
 ```
 
-文档统一推荐 `repo`。
+The docs recommend `repo`.
 
-这些 bin 都进入同一套命令实现：
+These bins all enter the same command implementation:
 
 ```bash
 repoctl doctor
@@ -25,16 +25,16 @@ rc doctor
 mo doctor
 ```
 
-## 顶层命令别名
+## Top-Level Aliases
 
-| 推荐写法         | 短写        | 说明             |
-| ---------------- | ----------- | ---------------- |
-| `repo init`      | `repo init` | 初始化仓库默认值 |
-| `repo templates` | `repo tpl`  | 查看或检查模板   |
+| Recommended      | Alias       | Purpose                       |
+| ---------------- | ----------- | ----------------------------- |
+| `repo init`      | `repo init` | Initialize workspace defaults |
+| `repo templates` | `repo tpl`  | Inspect or check templates    |
 
-## 分组命令别名
+## Group Aliases
 
-| 完整命令                       | 短写            |
+| Full Command                   | Alias           |
 | ------------------------------ | --------------- |
 | `repo workspace`               | `repo ws`       |
 | `repo workspace upgrade`       | `repo ws up`    |
@@ -62,9 +62,9 @@ mo doctor
 | `repo ai prompt`               | `repo ai p`     |
 | `repo ai prompt create`        | `repo ai p new` |
 
-## 推荐使用原则
+## Recommendation
 
-- 新手教程写完整命令，例如 `pnpm exec repo doctor`。
-- 团队 README 写根脚本，例如 `pnpm run repo:doctor`。
-- 维护者脚本可以写短别名，但要在注释或文档里说明用途。
-- CI 里优先写完整命令，方便日志搜索。
+- Use full commands in onboarding docs.
+- Use `repo:*` root scripts in project README files, for example `pnpm run repo:doctor`.
+- Use short aliases in maintainer scripts only when the surrounding docs explain them.
+- Prefer full commands in CI logs.