@icebreakers/monorepo-templates 2.0.6 → 2.1.0

package/templates/vitepress/test/mermaid.test.ts

@@ -0,0 +1,39 @@
+import { createMarkdownRenderer } from 'vitepress'
+import { describe, expect, it } from 'vitest'
+import { mermaidMarkdown } from '../.vitepress/mermaid/markdown'
+import { resolveMermaidTheme } from '../.vitepress/mermaid/render'
+
+describe('Mermaid Markdown integration', () => {
+  it('round-trips diagram text without injecting attributes or Vue expressions', async () => {
+    const md = await createMarkdownRenderer(process.cwd(), { config: mermaidMarkdown })
+    const source = 'flowchart LR\n A["引号 & <tag> {{ value }}"] --> B["it\'s fine"]\n'
+    const html = await md.renderAsync(`\`\`\`mermaid\n${source}\`\`\``)
+    const graph = html.match(/graph="([^"]+)"/)![1]!
+    expect(decodeURIComponent(graph)).toBe(source)
+    expect(html).not.toContain('<tag>')
+    expect(html).not.toContain('{{ value }}')
+    expect(html).toContain('<Mermaid ')
+  })
+
+  it('keeps normal fences and the mmd source-code escape hatch highlighted', async () => {
+    const md = await createMarkdownRenderer(process.cwd(), { config: mermaidMarkdown })
+    const html = await md.renderAsync('```ts\nconst answer = 42\n```\n\n```mmd\nflowchart LR\n A --> B\n```')
+    expect(html).toContain('language-ts')
+    expect(html).toContain('language-mermaid')
+    expect(html).not.toContain('<Mermaid ')
+    expect(html).toContain('shiki')
+  })
+
+  it('renders multiple independent component instances', async () => {
+    const md = await createMarkdownRenderer(process.cwd(), { config: mermaidMarkdown })
+    const html = await md.renderAsync('```mermaid\nflowchart LR\n A --> B\n```\n\n```mermaid\nsequenceDiagram\n A->>B: Hello\n```')
+    expect(html.match(/<Mermaid /g)).toHaveLength(2)
+  })
+
+  it('validates page themes and lets dark mode take precedence', () => {
+    expect(resolveMermaidTheme(false, 'forest')).toBe('forest')
+    expect(resolveMermaidTheme(true, 'forest')).toBe('dark')
+    expect(resolveMermaidTheme(false, { theme: 'forest' })).toBe('default')
+    expect(resolveMermaidTheme(false, undefined)).toBe('default')
+  })
+})

package/templates/vitepress/test/render.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const engine = vi.hoisted(() => ({ initialize: vi.fn(), render: vi.fn() }))
+vi.mock('mermaid', () => ({ default: engine }))
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.resetAllMocks()
+})
+
+describe('Mermaid rendering queue', () => {
+  it('serializes theme configuration with rendering and cleans up failed diagrams', async () => {
+    const containers: { remove: ReturnType<typeof vi.fn> }[] = []
+    vi.stubGlobal('document', {
+      createElement: () => {
+        const container = { style: {}, setAttribute: vi.fn(), remove: vi.fn() }
+        containers.push(container)
+        return container
+      },
+      body: { append: vi.fn() },
+    })
+    const { renderMermaid } = await import('../.vitepress/mermaid/render')
+    const first = Promise.withResolvers<{ svg: string }>()
+    const started = Promise.withResolvers<void>()
+    engine.render.mockImplementationOnce(() => {
+      started.resolve()
+      return first.promise
+    }).mockRejectedValueOnce(new Error('Invalid diagram')).mockResolvedValueOnce({ svg: '<svg />' })
+
+    const one = renderMermaid('flowchart LR; A-->B', 'forest')
+    const two = renderMermaid('invalid', 'dark')
+    const failure = expect(two).rejects.toThrow('Invalid diagram')
+    const three = renderMermaid('flowchart LR; B-->C', 'neutral')
+    await started.promise
+    expect(engine.initialize).toHaveBeenCalledTimes(1)
+    expect(engine.initialize).toHaveBeenLastCalledWith(expect.objectContaining({ theme: 'forest' }))
+    first.resolve({ svg: '<svg />' })
+    await one
+    await failure
+    await expect(three).resolves.toEqual({ svg: '<svg />' })
+    expect(engine.initialize.mock.calls.map(([config]) => config.theme)).toEqual(['forest', 'dark', 'neutral'])
+    expect(new Set(engine.render.mock.calls.map(([id]) => id)).size).toBe(3)
+    expect(containers).toHaveLength(3)
+    for (const container of containers) {
+      expect(container.remove).toHaveBeenCalledOnce()
+    }
+  })
+})

package/templates/vitepress/test/seo.test.ts

@@ -0,0 +1,19 @@
+import type { TransformContext } from 'vitepress'
+import { expect, it } from 'vitest'
+import { faqContent } from '../.vitepress/home/faq'
+import { createPageHead } from '../.vitepress/seo'
+
+it.each([['index.md', 'en'], ['zh/index.md', 'zh']] as const)('renders valid FAQ structured data for %s', (page, locale) => {
+  const head = createPageHead({ page, title: 'repoctl', description: 'A </script> description' } as TransformContext)
+  const script = head.find(([tag, attrs]) => tag === 'script' && attrs.type === 'application/ld+json')!
+  const content = script[2]!
+  expect(content).not.toContain('</script>')
+  const schema = JSON.parse(content)
+  const faq = schema['@graph'].find((item: { '@type': string }) => item['@type'] === 'FAQPage')
+  expect(faq.mainEntity.map((item: { name: string, acceptedAnswer: { text: string } }) => [item.name, item.acceptedAnswer.text])).toEqual(faqContent[locale])
+})
+
+it('keeps homepage FAQ data off documentation pages', () => {
+  const head = createPageHead({ page: 'reference/commands.md', title: 'Commands', description: 'Commands' } as TransformContext)
+  expect(head.find(([tag]) => tag === 'script')![2]).not.toContain('FAQPage')
+})

package/templates/vitepress/tsconfig.json

@@ -10,14 +10,14 @@
     "skipLibCheck": true
   },
   "include": [
-    ".vitepress/home/**/*.ts",
-    ".vitepress/navigation/**/*.ts",
-    ".vitepress/seo.ts",
-    ".vitepress/theme/**/*.ts",
-    ".vitepress/theme/**/*.vue",
-    ".vitepress/env.d.ts",
+    ".vitepress/**/*.ts",
+    ".vitepress/**/*.vue",
     "scripts/**/*.ts",
-    "why/examples/2.npm-basic-package/src/**/*.ts",
-    "why/examples/3.npm-basic-package/src/**/*.ts"
+    "test/**/*.ts",
+    "vitest.config.ts"
+  ],
+  "exclude": [
+    ".vitepress/dist",
+    ".vitepress/cache"
   ]
 }

package/templates/vitepress/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    name: 'website',
+    include: ['test/*.test.ts'],
+  },
+})

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

@@ -34,7 +34,7 @@ pnpm exec repo doctor
 | API / Hono 服务     | `hono-server`                         |
 | TypeScript 库 / SDK | `tsdown`                              |
 | Vue 组件库          | `vue-lib`                             |
-| 文档站              | `vitepress`                           |
+| 文档站              | `nimbus`                              |
 | CLI                 | `cli`                                 |
 
 意图不清时省略 `--templates`。初始化后再：

package/templates/vitepress/zh/learn/monorepo/manage.md

@@ -169,7 +169,7 @@ pnpm run repo:new
 ### 直接指定模板
 
 ```bash
-pnpm exec repo new docs --template vitepress
+pnpm exec repo new docs --template nimbus
 pnpm exec repo new sdk --template tsdown
 ```
 

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

@@ -79,9 +79,9 @@ repo templates --markdown --out docs/templates.md
 ```bash
 repo new
 repo new sdk --template tsdown
-repo new docs --template vitepress
-repo new docs --template vitepress --dry-run
-repo new docs --template vitepress --json --out plans/docs.json
+repo new docs --template nimbus
+repo new docs --template nimbus --dry-run
+repo new docs --template nimbus --json --out plans/docs.json
 ```
 
 用途：

package/templates/vitepress/zh/reference/execution-model.md

@@ -61,7 +61,7 @@ repoctl 的失败状态遵循阻塞优先：
 如果只是想知道会发生什么，先加 `--dry-run` 或输出计划：
 
 ```bash
-repo new docs --template vitepress --json --out plans/docs.json
+repo new docs --template nimbus --json --out plans/docs.json
 repo check --markdown --out reports/check-plan.md
 ```
 

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

@@ -15,6 +15,7 @@ repoctl 的模板能力不只是复制目录。它会把模板元数据、默认
 | `hono-server` | `templates/server`    | `apps/server`      | Hono service          |
 | `vue-hono`    | `templates/client`    | `apps/client`      | Vue + Hono app        |
 | `vitepress`   | `templates/vitepress` | `apps/website`     | docs site             |
+| `nimbus`      | `templates/nimbus`    | `apps/docs`        | default docs site     |
 | `cli`         | `templates/cli`       | `apps/cli`         | command line tool     |
 
 查看实际可用模板：
@@ -42,8 +43,8 @@ repo templates --markdown --out docs/templates.md
 预览创建：
 
 ```bash
-repo new docs --template vitepress --dry-run
-repo new docs --template vitepress --json --out plans/docs.json
+repo new docs --template nimbus --dry-run
+repo new docs --template nimbus --json --out plans/docs.json
 ```
 
 `--json` 和 `--out` 都隐含 `--dry-run`，不会写入文件。

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

@@ -6,14 +6,17 @@ repoctl 的模板由 `@icebreakers/monorepo-templates` 维护。CLI、脚手架
 
 ## 内置模板
 
-| Key           | Category | 默认目录           | 适合场景                    |
-| ------------- | -------- | ------------------ | --------------------------- |
-| `tsdown`      | library  | `packages/tsdown`  | TypeScript 库包             |
-| `vue-lib`     | library  | `packages/vue-lib` | Vue 3 组件库                |
-| `vue-hono`    | app      | `apps/client`      | Vue 3 + Hono 前后端一体应用 |
-| `hono-server` | service  | `apps/server`      | Hono API 服务               |
-| `vitepress`   | docs     | `apps/website`     | VitePress 文档站            |
-| `cli`         | tool     | `apps/cli`         | TypeScript 命令行工具       |
+| Key           | Category | 默认目录           | 适合场景                         |
+| ------------- | -------- | ------------------ | -------------------------------- |
+| `tsdown`      | library  | `packages/tsdown`  | TypeScript 库包                  |
+| `vue-lib`     | library  | `packages/vue-lib` | Vue 3 组件库                     |
+| `vue-hono`    | app      | `apps/client`      | Vue 3 + Hono 前后端一体应用      |
+| `hono-server` | service  | `apps/server`      | Hono API 服务                    |
+| `vitepress`   | docs     | `apps/website`     | VitePress 文档站                 |
+| `nimbus`      | docs     | `apps/docs`        | Nimbus + Astro，默认中英双语文档 |
+| `cli`         | tool     | `apps/cli`         | TypeScript 命令行工具            |
+
+Nimbus 是新建文档站点（`Docs Site`）的默认模板，提供英文 `/`、中文 `/zh/`、搜索和 AI 文档入口。VitePress 仍可显式选择，两者分别生成到 `apps/docs` 和 `apps/website`，可以同时使用。通用创建命令仍默认使用 `tsdown`；项目名称 `docs` 不会隐式改变模板。非交互调用请显式指定 `--template nimbus`。
 
 ## 查看模板
 
@@ -31,6 +34,7 @@ repo templates --markdown --out docs/templates.md
 repo new sdk --template tsdown
 repo new ui --template vue-lib
 repo new api --template hono-server
+repo new docs --template nimbus
 repo new website --template vitepress
 repo new toolbox --template cli
 ```
@@ -87,7 +91,7 @@ repo new api --template hono-server
 ### 要创建文档站
 
 ```bash
-repo new docs --template vitepress
+repo new docs --template nimbus
 ```
 
 生成后先检查：

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

@@ -36,7 +36,7 @@ pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
 ```bash
 pnpm exec repo templates
 pnpm exec repo new sdk --template tsdown
-pnpm exec repo new docs --template vitepress --dry-run
+pnpm exec repo new docs --template nimbus --dry-run
 ```
 
 如果只是日常开发，根脚本也可以：

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

@@ -70,6 +70,24 @@ const hook = { script: 'publish:extension', idempotent: true }
 
 程序化注入的旧 `GitHubOperations` adapter 保留原行为；要启用跨 runner 恢复，需要实现 `readReleaseState`、`writeReleaseState`、`listReleases`、`ensureTag`，并建议提供 `readTagTarget`。写入必须校验 revision，查询错误必须抛出。仅有本地 summary 不能代替远端检查点。
 
+## 无需发布的记录与原提交恢复
+
+仅包含 `none` 或空 frontmatter 的 intent 表示无需发布。它不会创建版本 PR，也不阻断已经准备好的版本发布。合并后重新出现、但 ledger 已记录消费的 intent 不会再次升级版本；pnpm 会在下一次有效版本操作中清理这些文件。
+
+版本 PR 以 pnpm 返回的实际发布包列表为依据，不再把任意 Git 改动视为版本变化。新包首次发布可以保留初始版本号，但仍会列入发布说明。仅清理记录不会创建发布 PR。
+
+已有版本尚未完成发布时，新的版本准备会在消费 intent 前失败，并给出原始提交和恢复命令。先恢复旧发布，再准备新版本：
+
+```bash
+repo release ci --mode publish --source-sha <完整的-main-提交-SHA> --dry-run
+repo release ci --mode publish --source-sha <完整的-main-提交-SHA>
+repo release ci --mode prepare
+```
+
+受管 Release 工作流为 `publish` 和 `publish-unpublished` 提供相同的 `source-sha` 输入。当前工具会在独立目录检出原提交，按照其锁文件安装、构建和验证，恢复该提交 manifest 或 ledger 新增的整批版本，包括依赖传播升级的包。package/version 输入只校验是否属于该批发布，不拆分原发布批次。SHA 必须属于 `origin/main` 历史。dry-run 只检查源码与远端状态，不安装、不上传、不运行 hook、不写检查点。后续变更保留到下一版本；恢复过程中不修改版本号。
+
+恢复保留 GitHub 工作流环境，供可信发布和 provenance 使用：签名身份对应运行工作流的提交；独立检出的源码、发布检查点、Git tag 和 Release 目标则对应 `source-sha`。不要通过覆盖 `GITHUB_SHA` 恢复旧源码，npm 会拒绝与工作流签名身份不一致的 provenance。
+
 ## 下一步
 
 阅读[发包与变更日志](/zh/learn/monorepo/publish)，再查看[报告与输出](/zh/tasks/reports)了解 CI 产物。

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

@@ -94,7 +94,7 @@ JSON 适合机器判断，不适合人工长时间阅读：
 ```bash
 repo doctor --json --out reports/doctor.json
 repo templates --check --json --out reports/templates.json
-repo new docs --template vitepress --json --out plans/docs.json
+repo new docs --template nimbus --json --out plans/docs.json
 ```
 
 常见消费方式：

package/assets/.changeset/wicked-ravens-wonder.md

@@ -1,5 +0,0 @@
----
-"@icebreakers/monorepo-templates": none
----
-
-优化构建产物测试夹具的依赖复用，避免 Windows CI 因反复复制依赖树而超时；仅影响测试，无需发布。