@icebreakers/monorepo-templates 3.0.1 → 3.1.0

package/templates/vitepress/zh/tasks/docs.md

@@ -50,6 +50,85 @@ const releaseInputs = {
 
 显式列表会替换该包的默认规则。覆盖包必须具有发布证据、匹配的版本与来源历史，不得存在未消费的发布 intent 或变化的发布输入。缺少证据会阻止对应站点部署；无关包无需为更新该站点额外发版。
 
+## 使用内置 Cloudflare Workers provider
+
+纯静态资源 Worker 可以将站点的 `preview` 和 `stable` 脚本目标替换为原生目标：
+
+```ts
+const cloudflare = {
+  provider: 'cloudflare-workers' as const,
+  config: 'website/wrangler.jsonc',
+  accountId: '0123456789abcdef0123456789abcdef',
+}
+
+const targets = {
+  preview: {
+    ...cloudflare,
+    workerName: 'docs-site-preview',
+    environment: 'preview',
+    url: 'https://next.example.com',
+  },
+  stable: {
+    ...cloudflare,
+    workerName: 'docs-site',
+    url: 'https://docs.example.com',
+  },
+}
+```
+
+站点仍保留原有 `buildScript`、`packages`、`releaseInputs` 和 `patchPaths`。每个目标选择 `deployScript` 或 `provider: 'cloudflare-workers'`，两者不能混用。已有脚本目标无需补充 discriminator 或默认值，其他平台和自定义 Cloudflare 部署仍可使用脚本适配器。
+
+使用已提交、仓库相对路径的 JSON 或 JSONC Wrangler 配置，例如 `website/wrangler.jsonc`：
+
+```jsonc
+{
+  "name": "docs-site",
+  "account_id": "0123456789abcdef0123456789abcdef",
+  "compatibility_date": "2026-10-01",
+  "workers_dev": false,
+  "preview_urls": false,
+  "assets": { "directory": "dist" },
+  "routes": [{ "pattern": "docs.example.com", "custom_domain": true }],
+  "env": {
+    "preview": {
+      "name": "docs-site-preview",
+      "routes": [{ "pattern": "next.example.com", "custom_domain": true }]
+    }
+  }
+}
+```
+
+`workerName` 和 `accountId` 用于校验解析后的部署身份，不会静默改写 Wrangler 配置。省略 `environment` 表示顶层环境。具名环境必须存在；显式 `name` 优先，否则 Wrangler 在顶层 Worker 名后追加环境名。环境内的 `assets` 对象会整体替换顶层对象，所以局部覆盖也必须包含 `directory`。输出路径相对于 Wrangler 文件解析，且解析符号链接后仍须位于冻结源码目录内。
+
+顶层已有路由时，具名环境必须显式配置自己的路由。预览与正式目标不能使用同一账户中的同名 Worker，即使环境名不同；也不能接管对方的自定义域名。配置的 `url` 必须与所选目标一致。示例使用自定义域名路由，无法明确判断归属的路由会被拒绝。
+
+原生 provider 只接受有限的静态配置：JSON/JSONC、纯静态资源 Worker，以及支持的自定义域名路由。TOML、自动生成或插件选择的配置、Worker 代码（`main`）、自定义 build、bindings、service environments、资源自动创建和其他未支持选项，应使用 `deployScript` 适配器。在对应工作区声明 Wrangler 开发依赖并提交锁文件；repoctl 使用已安装的 CLI，不在部署时临时下载。
+
+`deploy` 会先对冻结配置执行原生预检，再安装该源码目录的依赖和运行构建。预检核对凭据、账户/Worker/配置身份、路径，以及 Cloudflare 部署和版本接口的只读响应。运行时提供 `CLOUDFLARE_API_TOKEN`；非秘密的 `accountId` 固定在站点目标中，环境变量 `CLOUDFLARE_ACCOUNT_ID` 或有效的 Wrangler `account_id` 如有配置，必须与其一致。读取成功只能证明能够访问已查询的资源，不能证明后续上传或域名更新的权限；token 仍需具备所选 Worker 和域名操作需要的写权限。部署身份不会保存 token。
+
+只有明确的 Worker 不存在响应，即 HTTP 404 且 Cloudflare 错误码为 `10007`，才允许首次上传。认证错误、普通 404、限流、异常响应和空部署列表都会停止部署。`repo docs plan` 仍只检查源码与发布证据，不执行该凭据预检，也不证明平台访问权限。
+
+构建后，repoctl 再次核对配置与输出路径，并在静态资源中写入 `/.well-known/repoctl-deployment.json`，记录站点、通道、部署 ID、源码/tree SHA 和可选发布记录 ID。该路径已有文件时，必须是完整身份相同的有效 manifest；冲突 manifest 或无关用户文件会使部署失败，不会被覆盖。Cloudflare 确认要求最新生效部署只有一个版本承接 100% 流量，并带有 `repoctl-docs:<deploymentId>` 注解。这里确认的是平台状态；启用下述可选 readiness 门禁后，才会继续核验公网 HTTP 交付。
+
+## 公网交付验证后再推进 current
+
+在任一目标中添加 `readiness: {}`，即可要求平台确认后继续验证公网交付。省略 `readiness` 时保留原有行为，不发起公网 HTTP 请求。启用后必须显式配置 HTTPS `url`，且不得带凭据、query 或 fragment。URL 可以带路径，但 manifest 始终从 origin 根路径 `/.well-known/repoctl-deployment.json` 读取。使用共享 Nimbus 或 VitePress 渠道 helper 时，目标 `url` 应为不带路径的 origin，站点前缀单独通过框架 `base` 配置；repoctl 会将该 URL 原样传入 `REPO_DOCS_URL`。
+
+```ts
+const readiness = {
+  timeoutMs: 120000,
+  requestTimeoutMs: 10000,
+}
+```
+
+两个选项均为正整数。`timeoutMs` 默认 120000，范围为 1–600000 ms；`requestTimeoutMs` 默认 10000，范围为 1–30000 ms。每次重试获得新的有限预算。请求与响应体读取均有时间限制，拒绝重定向、绕过缓存，且不会向公网 URL 发送平台凭据。成功响应必须包含完全一致的 schema、站点、通道、部署 ID、源码/tree SHA 与正式发布记录 ID；旧页面或仅有 HTTP 200 均不足以通过。
+
+原生 provider 在构建后写入身份 manifest。启用此功能的脚本目标需在最终静态产物中生成相同 JSON：`schemaVersion: 1`，并将 `REPO_DOCS_SITE`、`REPO_DOCS_CHANNEL`、`REPO_DOCS_DEPLOYMENT_ID`、`REPO_DOCS_SOURCE_SHA`、`REPO_DOCS_TREE_SHA` 分别写为 `site`、`channel`、`deploymentId`、`sourceSha`、`treeSha`。仅正式通道从 `REPO_DOCS_RELEASE_ID` 写入 `releaseId`。直接使用已包含所选修正的 tree SHA，保留 Nimbus `_headers` 等无关生成文件。manifest 必须可公开访问，无需认证。
+
+平台结果保存后，状态先从 `deploying` 转为 `verifying`，再发起首个公网请求。超时或最终写入失败时保留该 receipt，以及此前已完整验证的 `current` 指针。此时公网流量可能已经切换到新版本，但 `current` 尚未推进。
+
+以相同输入重试可直接恢复验证，无需重新安装、构建或上传冻结源码。原生目标会在轮询前及最终写入前再次确认保存的同一版本仍然生效；脚本目标复用 receipt，不再次运行 `deployScript`。远端变为其他版本、混合流量或身份改变时直接失败，不会自动转为上传。共用工作流仍会安装根依赖来启动 repoctl。正式重试保留已保存的 readiness 策略与 URL，即使 main 修改或删除它们；未解决的 `verifying` 操作也不能被另一正式部署替换。
+
 ## 安装受管工作流
 
 先升级到包含此能力的 repoctl，再审查并应用受管资产更新：
@@ -64,7 +143,7 @@ pnpm exec repo upgrade --yes
 
 停用旧的“main 直接部署正式站”入口，以及托管平台中重复发布正式站的 Git 集成。每个通道只保留一个部署入口。共用工作流使用 `docs-<site>-<channel>` environment 和同名并发组，并关闭自动取消。Environment 是否需要批准由仓库现有设置决定，repoctl 不额外添加审批策略。
 
-Cloudflare 部署沿用仓库或 environment 的 `CLOUDFLARE_API_TOKEN`、`CLOUDFLARE_ACCOUNT_ID`，account ID 也可使用 variable。核心命令不依赖特定托管平台。其他平台可以通过自定义工作流传入凭据，同时保留来源选择、部署命令和并发约定。
+Cloudflare 部署通过仓库或 environment 的 secret 提供 `CLOUDFLARE_API_TOKEN`。受管工作流也会从 secret 或 variable 传入 `CLOUDFLARE_ACCOUNT_ID`；原生目标要求它与配置的 `accountId` 一致。其他平台使用部署脚本，可通过自定义工作流传入凭据，同时保留来源选择、部署命令和并发约定。
 
 ## 正式发布与首个基线
 
@@ -76,7 +155,7 @@ Release 运行的 `repoctl-ci-progress.json` 包含 `releaseRecord`，可用于
 
 接入后的首次正式部署，需要等待下一次完整稳定版发布。不能把当前 main 任意提交直接认作初始稳定基线。在该版本通过文档门禁前，现有正式部署继续提供服务。
 
-每次部署均按原始提交的完整仓库与锁文件安装、构建；后续 main 提交不会进入正式构建。预览使用准确的 main SHA，并在部署前复核远端分支。旧来源不能覆盖已部署的新来源。
+全新部署按原始提交的完整仓库与锁文件安装、构建；已保存验证结果的重试复用平台 receipt；后续 main 提交不会进入正式构建。预览使用准确的 main SHA，并在部署前复核远端分支。旧来源不能覆盖已部署的新来源。
 
 以下命令只检查计划，不安装依赖、不构建、不部署：
 
@@ -103,33 +182,78 @@ repo docs plan guide --channel stable --commits <第一个-SHA> <第二个-SHA>
 
 repoctl 只把明确选中的补丁应用到稳定源码，不会从 main 复制整个目录。发生冲突时停止部署。已应用修正在重试时保留；后续稳定源码已经包含的修正，不会重复应用。
 
-## 部署脚本约定与恢复
+## 部署适配器与恢复
 
-repoctl 在隔离源码目录内依次运行 `pnpm install --frozen-lockfile`、配置的构建脚本、所选部署脚本。构建与部署脚本均收到：
+repoctl 在隔离源码目录内运行 `pnpm install --frozen-lockfile` 和配置的构建脚本，再调用所选原生 provider 或部署脚本。原生目标会先执行前述预检。安装保留生命周期脚本及普通 CI、包管理器环境变量，但移除全部继承的 `REPO_DOCS_*`，并设置 `LEFTHOOK=0`，因此全工作区 postinstall 可按各自默认通道与 origin 构建其他站点。冻结部署上下文仅传给选中站点的构建和 provider／部署阶段，不修改调用方的环境对象。构建脚本和部署脚本均收到：
 
 | 环境变量                               | 含义                                   |
 | -------------------------------------- | -------------------------------------- |
 | `REPO_DOCS_SITE` / `REPO_DOCS_CHANNEL` | 站点与 `preview` / `stable` 通道       |
 | `REPO_DOCS_SOURCE_SHA`                 | 准确的源码提交                         |
+| `REPO_DOCS_TREE_SHA`                   | 包含所选文档修正的已核验源码树         |
 | `REPO_DOCS_RELEASE_ID`                 | 稳定发布完成记录 ID；预览为空          |
 | `REPO_DOCS_DEPLOYMENT_ID`              | 包含修正信息的确定性部署身份           |
 | `REPO_DOCS_URL`                        | 可选的配置目标 URL                     |
-| `REPO_DOCS_RESULT_FILE`                | 部署适配器核实平台结果后必须写入的文件 |
+| `REPO_DOCS_RESULT_FILE`                | 脚本适配器核实平台结果后必须写入的文件 |
 
-适配器须返回非空的平台版本 ID，并可附带 HTTP(S) URL：
+脚本适配器须写入非空的平台版本 ID，并可附带 HTTP(S) URL。原生 provider 直接返回该结果，无需部署脚本或自行写入结果文件：
 
 ```json
 { "versionId": "provider-deployment-version", "url": "https://docs.example.com" }
 ```
 
-用 `REPO_DOCS_DEPLOYMENT_ID` 核对中断部署是否已完成，再决定是否重新上传。平台确认结果后才写入结果文件。进程退出码为零但没有有效结果文件，仍不算部署完成。
+用 `REPO_DOCS_DEPLOYMENT_ID` 核对中断部署是否已完成，再决定是否重新上传。平台确认结果后才写入结果文件。进程退出码为零但没有有效结果文件，仍不算部署完成。启用 readiness 后，保存的 receipt 仅接受 `versionId` 和可选 `url`；版本 ID 必须非空、不超过 512 字符且无控制字符，HTTP(S) URL 不得包含凭据、query 或 fragment。
+
+原生 Cloudflare provider 自行执行上述核对。当前生效版本的注解相同且承接 100% 流量时，复用该版本，不再上传；历史版本匹配不足以恢复，混合流量也会失败。有效的当前版本属于其他部署时，允许本次已授权的新部署上传。Wrangler 返回的 Worker、环境和版本必须匹配目标，且该版本确认已生效后才推进 current 指针。
 
 受管工作流先运行 `repo docs plan`，再以相同输入运行 `repo docs deploy`。正式部署要求 GitHub Actions、run ID，以及与实际串行并发组一致的 `REPO_DOCS_CONCURRENCY_GROUP`；本地审查使用 `plan`。构建或部署前先用 revision 比较并交换取得状态，平台结果确认后才推进已部署指针。
 
-构建失败后，修复原因并针对相同发布记录重跑文档工作流，不会重新发布 npm。若正式站 runner 在部署期间消失，先重跑同一部署，让适配器核实平台结果；未解决的 `deploying` 操作不能被另一正式部署覆盖。预览站则允许串行的受管工作流用最新 main 来源替换中断的旧部署。已完成部署和无关联发布批次会跳过。保留 `repoctl-release-state` 分支；短期 Actions artifact 仅用于诊断，不能代替部署基线。
+构建失败后，修复原因并针对相同发布记录重跑文档工作流，不会重新发布 npm。若正式站 runner 在部署期间消失，先重跑同一部署，让适配器核实平台结果；未解决的 `deploying` 或 `verifying` 操作不能被另一正式部署覆盖。预览站则允许串行的受管工作流用最新 main 来源替换中断的旧部署。已完成部署和无关联发布批次会跳过。保留 `repoctl-release-state` 分支；短期 Actions artifact 仅用于诊断，不能代替部署基线。
 
 未完成的正式部署会保存站点配置、发布记录、请求的修正提交和已核验的源码树。重试时使用相同的发布记录和修正输入，计划器会重新核验保存的输入与部署标识，构建也使用保存的配置，即使 main 已修改配置或删除该站点。省略 `release` 时使用当前正式基线；首次部署还没有正式基线时，使用未完成部署的发布记录。若已有旧基线，而新版本部署尚未完成，必须明确指定新版本的发布记录。保存的状态损坏或不一致时，会在构建和上传前停止恢复。
 
+上传成功但结果尚未持久化为验证 receipt，或未启用 readiness 且最终写入失败时，保留 `deploying` 状态。重试仍会安装和构建同一份冻结源码，再查询远端生效版本以决定是否上传。重试中的预检或构建失败，不会清除这个结果未知的上传状态。即使当前配置已切换到原生 provider，旧的未完成脚本部署仍使用保存的脚本目标和原始源码恢复；迁移后续部署时不要改写历史快照。
+
 如果修复需要修改产品源码或构建脚本，应发布新的稳定基线；相同发布记录始终使用原来的源码。
 
-程序化 API 为 `planDocsDeployment(options)` 与 `deployDocs(options)`。`DocsOptions` 接受站点、通道、来源/发布/修正选择，以及可选配置、环境和 `DocsStateStore`。状态适配器需实现 `readAutomationState`、支持 revision 检查的 `writeAutomationState`、`readBranchHead`；查询失败必须抛出，不得假装没有历史状态。
+repoctl 已知失败保留固定原因码和处理建议，包括缺少凭据、平台身份冲突、不支持的配置、已保存版本不再生效、状态认领变化以及 main 已前进。未知异常只保留阶段分类，不复制其原始 message 或 cause。
+
+程序化 API 为 `planDocsDeployment(options)` 与 `deployDocs(options)`。`DocsOptions` 接受站点、通道、来源/发布/修正选择，以及可选配置、环境和 `DocsStateStore`。状态适配器需实现 `readAutomationState`、支持 revision 检查的 `writeAutomationState`、`readBranchHead`；可选 `fetch` 提供原生 provider 与公网 readiness 的 HTTP transport，`spawn` 提供进程 transport。查询失败必须抛出，不得假装没有历史状态。公开目标类型为 `DocsScriptDeploymentTarget`、`DocsCloudflareWorkersTarget` 及其联合类型 `DocsDeploymentTarget`。
+
+## 部署报告
+
+`deployDocs()` 的已部署和跳过结果包含可选 `report`。失败时抛出公开的 `DocsDeploymentError`，其 `report` 为安全的结构化失败结果。`DocsDeploymentReport` 包含本次时间戳与单调时钟耗时（毫秒），按顺序记录 `plan`、`preflight`、`install`、`build`、`provider`、`readiness`、`finalize`；每阶段明确标记 completed/skipped/failed、安全原因码，平台操作区分 `upload`/`reconcile`，并记录已知部署/版本 ID。失败包含 `failedStage`，可恢复时附带 `deploying` 或 `verifying` 的 `resumablePhase`。恢复时复用的安装和构建阶段标为跳过，不伪装成零耗时执行成功。
+
+`repo docs deploy ... --json` 的 stdout 仅输出结果或安全失败报告，失败退出码非零。安装、构建和脚本日志仍实时输出，JSON 模式下转到 stderr；程序化调用可设置 `DocsOptions.json` 使用相同传输方式。普通 CLI 模式另在 stderr 输出安全失败提示。repoctl 生成的报告和错误不会包含原始异常、HTTP 响应体或凭据；部署脚本仍需自行管理终端日志，repoctl 不承诺脱敏任意脚本输出。
+
+成功、跳过和失败均向 `GITHUB_STEP_SUMMARY` 写入同一阶段报告，转义文字并提供重试说明。摘要写入失败仅增加 `warnings: ['summary-write-failed']`，不会改变部署结果、回滚 current 或掩盖主要错误。报告只描述本次调用，不虚构跨重试的累计耗时。
+
+## 构建渠道上下文
+
+Nimbus 和 VitePress 使用轻量入口 `repoctl/docs-context`。在站点的 deployment 模块中配置不同的预览与正式 origin：Nimbus 使用 `src/lib/deployment.ts`，VitePress 使用 `.vitepress/deployment/index.ts`。仅在框架构建边界读取公开输入：
+
+```ts
+import { resolveDocsContext } from 'repoctl/docs-context'
+
+const context = resolveDocsContext({
+  channel: process.env.REPO_DOCS_CHANNEL,
+  url: process.env.REPO_DOCS_URL,
+  previewOrigin: 'https://next.example.com',
+  stableOrigin: 'https://docs.example.com',
+})
+```
+
+未设置或空渠道默认为 `preview`，未知渠道会失败。两个 origin 必须不同，且必须是没有凭据、路径、查询和片段的 HTTP(S) origin；根路径末尾斜杠会规范化。子路径部署单独设置框架 `base`。提供非空 `REPO_DOCS_URL` 时，它必须与渠道配置的 origin 一致。helper 不读取凭据、GitHub 状态或发布记录，下面两种本地构建均不需要部署授权：
+
+```sh
+REPO_DOCS_CHANNEL=preview pnpm build
+REPO_DOCS_CHANNEL=stable pnpm build
+```
+
+`resolveDocsContext(options)` 返回包含 `channel`、`preview`、`origin`、`stableOrigin` 的 `DocsContext`，同时导出 `DocsChannel` 和 `DocsContextOptions`。`docsPreviewRobots`、`docsRobots(context, sitemapUrl?)`、`mergeDocsHeaders(existing, context)` 提供公共爬虫策略。正式 sitemap 默认为 `<origin>/sitemap.xml`，Nimbus 传入自己的 `sitemap-index.xml` URL。核心包的 `@icebreakers/monorepo/docs-context` 提供相同纯 API，不加载 CLI、文件系统或部署 provider。
+
+预览 origin 统一用于 canonical、hreflang、社交/结构化 URL，以及 Nimbus 的 Markdown、LLM 和发现导出。预览站显示未发布提示并链接正式站，输出 `noindex, nofollow, noarchive`、robots.txt 全站禁止策略，以及带归属标记的等效 X-Robots-Tag。本地搜索继续建立索引。页面原本声明的 `noindex` 在正式站继续生效；Nimbus 独立遵守显式 `searchable: true`。爬虫指令不是访问控制。
+
+`mergeDocsHeaders` 保留用户与 Nimbus 的响应头，优先在已有通配规则内插入带标记的预览字段，正式构建只移除自身字段。归属标记损坏会让构建失败。Nimbus 在发现集成之后合并，VitePress 在 buildEnd 中执行。重复构建通过框架清理输出，避免遗留另一个渠道的产物。
+
+模板在 build、lint、typecheck 和 test 的任务级 Turbo `env` 中声明 `REPO_DOCS_CHANNEL`、`REPO_DOCS_URL`，Markdown、框架配置和验证脚本均参与缓存。保持这些值进入 hash，不要只声明 passthrough；用 `repo env check build lint typecheck test --json` 检查。文档工作区需要在 devDependencies 中声明 `repoctl`，以便冻结构建能使用 helper。已有自定义布局继续保留：手动接入这些部分，或审查 `repo templates upgrade` 计划；不要假定根目录的 `repo upgrade` 会重写布局。

package/templates/vitepress/zh/tasks/release.md

@@ -24,6 +24,8 @@ repo release plan --markdown
 
 ## 预期结果
 
+计划同时检查公开包的内部依赖协议：`dependencies`、`devDependencies`、`optionalDependencies` 必须使用 `workspace:*`；`peerDependencies` 可以使用 `workspace:*`、`workspace:^` 或 `workspace:~`。例如目标包版本为 `2.0.1` 时，pnpm pack 分别生成 `2.0.1`、`^2.0.1` 和 `~2.0.1` 的 peer 范围。按兼容性承诺选择原始声明，不要为了通过检查把 caret 或 tilde peer 改为精确版本。外部依赖范围和私有消费包不受这项发布协议约束。无效协议会使计划返回 `blocked`，而不改写 manifest 或执行发布 hooks。
+
 JSON 与 Markdown 表达相同的原生版本决策。说明条目复用已有发布 renderer，并排除已消费的 intent 条目。私有包可以升级版本，但标记为非发布候选。公共 `createReleasePlan({ cwd })` API 返回同一报告，不自行写入文件。
 
 计划、自动触发和版本准备统一识别根包与私有包的 intent，由 pnpm 在完整工作区内计算版本传播。Release PR 只为可发布的子包生成说明，并要求这些包具有对应版本的 changelog；根包或私有包缺少 changelog 不会阻断准备。根包即使未标记为 private，也不属于发布候选。不希望某个工作区包参与版本计算时，应配置 pnpm 的 `versioning.ignore`，不要只在实际写版本时改变工作区发现范围。