@icebreakers/monorepo-templates 1.2.0 → 1.3.0

package/templates/vitepress/why/what-is-npm-package.md

@@ -1,7 +1,36 @@
 # What Is An npm Package?
 
-An npm package is a directory described by `package.json`. It can expose runtime code, types, command-line bins, assets, or configuration.
+An npm package is a versioned archive with a `package.json` contract. It may provide runtime JavaScript, type declarations, a command-line binary, configuration presets, or assets. Publishing a folder is easy; maintaining that contract is the real work.
 
-The public contract includes the package name, version, `exports`, `types`, `bin`, supported runtimes, files included in the tarball, and semantic versioning behavior. Treat these fields as API design, not publishing metadata afterthoughts.
+## The package boundary
 
-Use `pnpm pack` to inspect the exact artifact before publishing.
+```text
+package.json  name, version, exports, files, engines
+README.md     install and supported usage
+dist/         built runtime and type declarations
+LICENSE       license terms for consumers
+```
+
+Only files named by `files`, exports, and package metadata should be treated as public. Internal source layout is free to change until it appears in the published contract.
+
+## Inspect what ships
+
+```bash
+npm pack --dry-run
+pnpm pack --pack-destination ./artifacts
+```
+
+Review the archive after every material packaging change. This catches missing declarations, accidental source publication, and files referenced by `exports` that were not included.
+
+## Version with intent
+
+- Patch: compatible fix or metadata correction.
+- Minor: compatible capability, such as a new public command or template.
+- Major: incompatible API, behavior, or supported runtime change.
+
+Repository versioning tools record that decision, but they cannot determine whether a consumer will be broken. Write the release note from the consumer's point of view.
+
+## Keep Reading
+
+- [Publishing A Package](./publish-basic-npm-package.md)
+- [Modern Package Guide](./modern/)

package/templates/vitepress/wrangler.jsonc

@@ -1,5 +1,22 @@
 {
-  "$schema": "https://unpkg.com/wrangler/config-schema.json",
-  "name": "monorepo-template",
-  "pages_build_output_dir": ".vitepress/dist"
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "repoctl-docs",
+  "compatibility_date": "2026-08-16",
+  "compatibility_flags": ["nodejs_compat"],
+  "workers_dev": false,
+  "preview_urls": true,
+  "assets": {
+    "directory": ".vitepress/dist",
+    "not_found_handling": "404-page"
+  },
+  "routes": [
+    {
+      "pattern": "repoctl.icebreaker.top",
+      "custom_domain": true
+    }
+  ],
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1
+  }
 }

package/templates/vitepress/zh/ai/index.md

@@ -16,7 +16,7 @@ AI 文档入口用于给 Cursor、Claude Code、Codex 和其他 AI 编程工具
 
 ## 2. 在 AI 工具里怎么用
 
-优先把 `https://repo.icebreaker.top/llms.txt` 作为入口提供给 AI 工具。只有当工具不能继续抓取链接，或者你需要离线提供完整上下文时，再使用 `https://repo.icebreaker.top/llms-full.txt`。
+优先把 `https://repoctl.icebreaker.top/llms.txt` 作为入口提供给 AI 工具。只有当工具不能继续抓取链接，或者你需要离线提供完整上下文时，再使用 `https://repoctl.icebreaker.top/llms-full.txt`。
 
 ```txt
 先给 llms.txt

package/templates/vitepress/zh/ai/llms-txt.md

@@ -16,7 +16,7 @@ description: 使用 llms.txt 为大语言模型提供更易读取的 repoctl 文
 
 ## 1. 使用方式
 
-访问 `https://repo.icebreaker.top/llms.txt` 可以获取当前文档的 LLM 索引。如果需要一次性提供完整上下文，可以使用 `https://repo.icebreaker.top/llms-full.txt`。
+访问 `https://repoctl.icebreaker.top/llms.txt` 可以获取当前文档的 LLM 索引。如果需要一次性提供完整上下文，可以使用 `https://repoctl.icebreaker.top/llms-full.txt`。
 
 当你在 Cursor、Claude Code、Codex 或其他 AI 编程工具里引用 repoctl 文档时，优先提供 `llms.txt`，再按需要补充具体页面链接。
 

package/templates/vitepress/zh/index.md

@@ -1,66 +1,9 @@
 ---
-layout: home
-
-hero:
-  name: repoctl
-  text: 让 pnpm monorepo 的日常操作更短、更稳
-  tagline: 用一套 CLI 管理初始化、诊断、创建模板、提交前校验和模板资产同步。
-  image:
-    src: /logo.jpg
-    alt: repoctl logo
-  actions:
-    - theme: brand
-      text: 快速开始
-      link: /zh/repoctl/getting-started
-    - theme: alt
-      text: 命令速查
-      link: /zh/repoctl/commands
-    - theme: alt
-      text: AI 文档入口
-      link: /zh/ai/
-
-features:
-  - title: 从已有仓库开始
-    details: 安装 repoctl 后运行 setup 和 doctor，先把 workspace、根脚本、配置冲突和提交链路检查清楚。
-  - title: 用模板创建包和应用
-    details: repo new 支持交互式创建、指定模板、dry-run、JSON 输出和创建计划落盘。
-  - title: 把质量门禁变成日常命令
-    details: repo check 统一预览和执行 lint、typecheck、build、test、tsd 等推荐校验。
-  - title: 给 AI 工具的文档入口
-    details: 构建时自动生成 llms.txt、llms-full.txt 和页面 Markdown，让 AI 编程工具更容易读取 repoctl 文档。
+layout: page
+aside: false
+pageClass: repoctl-home-page
+title: repoctl
+description: 面向 pnpm 与 Turborepo monorepo 的任务型 CLI。
 ---
 
-## 最短路径
-
-```bash
-pnpm add -D repoctl
-pnpm exec repo init
-pnpm exec repo doctor
-pnpm exec repo new
-pnpm exec repo check
-```
-
-在由 repoctl 创建或初始化的仓库里，同一套工作流会暴露成更短的根脚本：
-
-```bash
-pnpm run repo:init
-pnpm run repo:doctor
-pnpm run repo:new
-pnpm run repo:check
-```
-
-## 你可以继续阅读
-
-- [repoctl 概览](./repoctl/index.md)
-- [快速开始](./repoctl/getting-started.md)
-- [接入已有仓库](./repoctl/adopt-existing.md)
-- [按场景选命令](./repoctl/scenarios.md)
-- [执行模型](./repoctl/execution-model.md)
-- [命令速查](./repoctl/commands.md)
-- [校验链路](./repoctl/checks.md)
-- [doctor 诊断](./repoctl/doctor.md)
-- [配置文件](./repoctl/config.md)
-- [模板与创建](./repoctl/templates.md)
-- [模板资产治理](./repoctl/template-assets.md)
-- [工作流与 CI](./repoctl/workflows.md)
-- [报告与自动化输出](./repoctl/reports.md)
+<HomePage locale="zh" />

package/templates/vitepress/zh/repoctl/workflows.md

@@ -110,6 +110,41 @@ repo ws ls --json --out reports/workspaces.json
 | 输出给脚本         | `--json --out <file>`                              |
 | 输出给人看并脱敏   | `--markdown --redact --out <file>`                 |
 
+## 文档 Worker
+
+repoctl 文档通过名为 `repoctl-docs` 的 Cloudflare Worker 部署。VitePress 只生成静态资产，Workers Static Assets 直接提供这些文件，因此不需要应用 handler，也不声明 `ASSETS` binding。
+
+### Workers Builds 配置
+
+| 配置项     | 值                                                      |
+| ---------- | ------------------------------------------------------- |
+| 仓库根目录 | 仓库根目录                                              |
+| 生产分支   | `main`                                                  |
+| 构建命令   | `pnpm --filter @icebreakers/website build`              |
+| 生产部署   | `pnpm --filter @icebreakers/website run deploy`         |
+| 非生产部署 | `pnpm --filter @icebreakers/website run deploy:preview` |
+
+构建命令会先校验双语页面，再由 VitePress 生成 `.vitepress/dist`。Worker 配置会为不存在的路由返回生成后的 `404.html`，并继续读取 `public/_redirects`，兼容旧的 `/en/*` 链接。
+
+### 预览、发布与回滚
+
+修改生产部署前，先完成本地验证：
+
+```bash
+pnpm --filter @icebreakers/website build
+pnpm --filter @icebreakers/website run deploy:dry-run
+pnpm --filter @icebreakers/website exec wrangler dev
+```
+
+非生产 Workers Builds 上传预览版本。验证通过后再执行生产部署。需要回滚时，先查看版本历史，再选择最近的稳定版本：
+
+```bash
+pnpm --filter @icebreakers/website exec wrangler versions list
+pnpm --filter @icebreakers/website exec wrangler rollback <VERSION_ID>
+```
+
+`repoctl.icebreaker.top` 是唯一 canonical custom domain。Cloudflare Redirect Rules 把 `repo.icebreaker.top/*` 和 `monorepo.icebreaker.top/*` 永久跳转到主域名，同时保留路径和查询参数。
+
 ## 下一步
 
 - 查所有参数：[命令速查](./commands.md)

package/templates/vitepress/zh/thinking.md

@@ -69,17 +69,20 @@
 
 此外，模板里还有许多为 `GitHub` 显示优化的 `md` 文档。
 
-## 部署
+## 文档部署
 
-文档网站通过 `netlify.toml` 配置部署在 `Netlify` 上。最初我使用的是 `Vercel`，但由于**国内**访问速度的原因，最终迁移到了 `Netlify`。
+文档是一个 VitePress 静态站点，以名为 `repoctl-docs` 的 Cloudflare Worker 发布。Workers Static Assets 直接托管 `.vitepress/dist`，同时处理自定义 404 页面和 `_redirects` 兼容规则。站点没有动态请求逻辑，因此不额外编写 Worker handler，也不声明 `ASSETS` binding。
 
-而且由于我是开源项目贡献者的原因，`Netlify` 为我 `免费` 提供了 `Pro` 版本的计划 (通常这需要 `$19/per member/month`)
+Cloudflare Workers Builds 从仓库根目录执行：
 
-感谢 `Netlify`! 爱你❤️😍。
+```bash
+pnpm --filter @icebreakers/website build
+pnpm --filter @icebreakers/website run deploy
+```
 
-如果看到这里的哥们，你也有一定影响力的开源项目，也可以通过下方的链接申请。
+非生产分支使用 `pnpm --filter @icebreakers/website run deploy:preview` 上传预览版本。生产发布前运行 `pnpm --filter @icebreakers/website run deploy:dry-run`，校验静态资产清单和 Wrangler 配置。需要回滚时，先用 `wrangler versions list` 确认版本，再执行 `wrangler rollback <VERSION_ID>`。
 
-https://www.netlify.com/legal/open-source-policy/
+唯一主域名是 `https://repoctl.icebreaker.top`。`repo.icebreaker.top` 和 `monorepo.icebreaker.top` 只作为兼容入口，由 Cloudflare 301 跳转到主域名，并保留原路径与查询参数。
 
 ## 总结
 

package/templates/vitepress/zh/why/examples/2.npm-basic-package/README.md

@@ -1 +1 @@
-https://repo.icebreaker.top/
+https://repoctl.icebreaker.top/

package/templates/vitepress/zh/why/examples/3.npm-basic-package/README.md

@@ -1 +1 @@
-https://repo.icebreaker.top/
+https://repoctl.icebreaker.top/

package/templates/vitepress/zh/why/index.md

@@ -1 +1,38 @@
-# 从 0 到 1 构建 monorepo
+# 包的演进
+
+一个可发布的 npm 包不只是源代码目录。消费者依赖它的运行时格式、类型声明、入口点、发布文件和兼容性承诺。这里按这些公开边界整理现代包的基础知识。
+
+## 先从消费者开始
+
+在选择打包器或模块格式前，先回答：
+
+- 消费者使用 ESM、CommonJS，还是两者都需要？
+- 包发布运行时代码、类型、CLI、配置预设还是资源？
+- 需要支持哪些 Node 版本？
+- 对外只暴露一个入口，还是需要明确的子路径？
+
+这些答案定义了包的边界。工具链应该实现边界，而不是替代边界决策。
+
+## 推荐目录
+
+```text
+src/          源代码
+dist/         生成的 ESM、CommonJS 与声明文件
+package.json  公开 metadata 与 exports 映射
+README.md     安装和使用契约
+```
+
+使用 `files` 控制发布内容，并在发布前执行 `npm pack --dry-run` 检查实际 tarball。
+
+## 专题
+
+- [ESM 与 CommonJS](./modern/esm-vs-cjs.md)
+- [类型声明](./modern/dts.md)
+- [包入口](./modern/package-entry-points.md)
+- [构建工具](./modern/bundlers.md)
+- [TypeScript](./modern/typescript.md)
+
+## 继续阅读
+
+- [什么是 npm 包](./what-is-npm-package.md)
+- [发布 npm 包](./publish-basic-npm-package.md)

package/templates/vue-lib/package.json

@@ -6,7 +6,7 @@
   "description": "Internal Vue library template shipped with repoctl",
   "author": "ice breaker <hi@sonofmagic.top>",
   "license": "ISC",
-  "homepage": "https://repo.icebreaker.top",
+  "homepage": "https://repoctl.icebreaker.top",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sonofmagic/repoctl.git",

package/assets/.changeset/ledger.yaml

@@ -1,51 +0,0 @@
-"@icebreakers/monorepo-templates@1.1.0":
-  dir: packages/monorepo-templates
-  intents:
-    - pnpm-native-versioning
-    - release-ci-token
-    - repoctl-release-orchestration
-    - vitest-native-config
-"@icebreakers/monorepo-templates@1.2.0":
-  dir: packages/monorepo-templates
-  intents:
-    - repoctl-brand-and-i18n
-"@icebreakers/monorepo@5.1.0":
-  dir: packages/monorepo
-  intents:
-    - close-legacy-release-pr
-    - human-readable-release-notes
-    - pnpm-native-versioning
-    - publish-versioned-packages
-    - release-ci-token
-    - release-links
-    - release-npm-links
-    - release-npm-links-prepublish
-    - release-pr-body
-    - release-pr-layout
-    - release-test-isolation
-    - repoctl-release-orchestration
-"@icebreakers/monorepo@5.1.1":
-  dir: packages/monorepo
-  intents:
-    - release-publish-summary
-    - repair-release-notes
-"@icebreakers/monorepo@5.2.0":
-  dir: packages/monorepo
-  intents:
-    - repoctl-brand-and-i18n
-create-icebreaker@1.1.0:
-  dir: packages/create-icebreaker
-  intents:
-    - pnpm-native-versioning
-create-icebreaker@1.1.1:
-  dir: packages/create-icebreaker
-  intents:
-    - repoctl-brand-and-i18n
-create-repoctl@0.1.0:
-  dir: packages/create-repoctl
-  intents:
-    - repoctl-brand-and-i18n
-repoctl@5.2.0:
-  dir: packages/repoctl
-  intents:
-    - repoctl-brand-and-i18n

package/assets/netlify.toml

@@ -1,14 +0,0 @@
-[build]
-publish = "dist"
-command = "pnpm run build"
-
-[build.environment]
-NODE_VERSION = "22"
-
-[[redirects]]
-from = "/*"
-to = "/index.html"
-status = 200
-
-[context.deploy-preview]
-ignore = "exit 0"