PJR-9ZN5 @specdojo/docs-siteが生成するpublic/mermaid等を.vitepress配下に集約する
1. 概要
現在 @specdojo/docs-site (packages/docs-site) の build / dev / mermaid 実行時に、Mermaid SVG の出力先（public/mermaid）や kata ステージング（specdojo-kata-staging）が利用リポジトリのワークスペース直下に生成されるため、利用側のルートディレクトリが散らかり .gitignore にも複数のエントリ追加が必要になっている。これらの一時・生成ディレクトリを .vitepress/ 配下（例: .vitepress/mermaid や .vitepress/kata-staging 等）に集約し、VitePress 側の静的配信設定および README / config init の .gitignore テンプレートを整理する。
現在の VitePress 設定は .vitepress/** をページ走査から除外する。kata の配置だけを移すと /ja/specdojo/... のページが欠けるため、配信方法も合わせて設計する。
2. 完了条件
@specdojo/docs-siteのbuild・dev・mermaidが生成する Mermaid SVG と manifest、およびbuild・devが作る kata ステージングが、閲覧対象 workspace の.vitepress/配下に置かれる。新しい利用リポジトリのルートにpublic/mermaid/とspecdojo-kata-staging/を作らない。- Mermaid 図の公開 URL
/mermaid/<hash>.svgを維持し、buildの.vitepress/distに SVG が含まれ、devでも同じ URL から取得できる。既存の利用者が置いたpublic/のファイルを変更・削除しない。 - package 同梱文書を
/ja/specdojo/...で配信し、成果物からの wikilink が解決する。eject 済みの文書は利用リポジトリ側を優先する。.vitepress/**がページ走査から除外される条件で採った配信方法と理由を、個票の対応結果と pipeline のhandoffに記録する。 packages/docs-site/README.md、[[specdojo:docs-editing-guide]]、config initの.gitignore生成内容を新しい配置へ合わせる。既存の.gitignoreを保持し、利用者が作成した.vitepressの設定ファイルを除外しない。- Mermaid 生成と kata ステージングのテスト、
npm --prefix packages/docs-site run typecheck、npm run check、npm run docs:buildが通る。@specdojo/docs-siteの配布物を空の利用リポジトリへ導入し、build・dev・mermaidの生成先、公開 URL、Git の追跡対象を確かめる。
3. 作業内容
| No | 作業 | 担当 | 状態 | メモ |
|---|---|---|---|---|
| 1 | 生成先と VitePress の配信方法を設計する | indie | done | 閲覧用ツリーを srcDir にして走査対象を限定した |
| 2 | Mermaid と kata の生成・配信を変更する | indie | done | SVG の専用配信、eject 優先、dev の文書同期を実装した |
| 3 | .gitignore の生成内容と案内を更新する | indie | done | 生成ディレクトリだけを除外し、既存の設定と利用者の設定ファイルを保持する |
| 4 | テストと空の利用リポジトリで確認する | indie | done | 親検証、全体検査、通常導入した配布物の実描画・build・dev・HTTP・Git 除外を確認した |
4. 対応結果
- Mermaid SVG と manifest の既定出力先を workspace の
.vitepress/mermaid/に変更した。Vite plugin が SVG だけを build の.vitepress/dist/mermaid/に出力し、dev でも/mermaid/<hash>.svg（サイトの base 付き URL にも対応）で配信する。manifest・一時ファイルは専用配信の対象にしない。publicDirは利用者のpublic/を維持し、その内容を生成処理で変更・削除しない。 - 配信方法:
.vitepress/kata-staging/docs/に利用側のdocs/と package 同梱文書を重ね、.vitepress/kata-staging/自体を VitePress のsrcDirにした。workspace をsrcDirにしたままの配置変更では.vitepress/**の走査除外とドットディレクトリの走査制約でページが欠けるため、この方法を採った。閲覧用ツリーにはdocs/だけを置き、dist・cache・設定ファイルを走査対象から外す。既存のdocs/ja/...→/ja/...の rewrites を使えるため、同梱文書も/ja/specdojo/...で公開できる。symlink や VitePress 内部のページ一覧の書き換えは使わない。 - eject 済み文書は利用側を優先し、起動時に古いステージングを作り直す。dev では利用側文書の編集・追加・削除を同期し、eject 文書を削除した場合は同梱文書へ戻す。
@/src/...などのコードスニペットも利用側の元ファイルを解決する。旧配置のpublic/mermaid/とspecdojo-kata-staging/は自動削除しない。 config initの.gitignoreテンプレートに/.vitepress/dist/・/.vitepress/cache/・/.vitepress/mermaid/・/.vitepress/kata-staging/を追加した。既存内容の追記方式を維持し、利用者の.vitepress/config.mtsや theme は除外しない。本リポジトリの.gitignore、packages/docs-site/README.md、specdojo:docs-editing-guide も新配置へ合わせた。- 回帰テストを追加した。Mermaid の既定出力先と利用者の public ファイル保持、dev の SVG middleware、client build の SVG のみの出力と SSR build の重複出力防止、ステージングと eject 優先・同期・削除時の復元・再起動時の掃除、実 Git による生成物だけの除外を対象とする。unit / integration・本体型検査・lint・全体 schema 検査は指定された親 runner に委ねた。
npm run checkは親検証と重複するため executor では実行せず、それ以外の依存宣言・catalog・履歴リンク検査を個別に実行した。 - 親検証の失敗を受けた再開対応:
mermaid-assets.test.tsのテストを非同期にし、Vite の各フック呼び出しをawaitするよう修正した。specdojo-gitignore.test.tsの Git 起動2箇所へgitEnvironment()を渡し、親プロセスの Git 固有環境変数から fixture を隔離した。これにより、前回の Promise 未処理5件と Git 環境隔離違反2件の原因を修正した。lint と unit test の再判定は親 runner が行う。 - 検証済み:
npm --prefix packages/docs-site run typecheck、変更ファイルの Prettier 整形、npm run check:src-imports、node --import tsx tools/catalog-validate-if-configured.mjs、node --import tsx src/specdojo.ts register build、register events のファイル単位 schema 検査。Markdown 検査は指定された親 runner に委ねた。catalog 検査は既存の未作成成果物の警告を伴って成功した。runner が引き継ぎ時に追記した event は検証のみ行い、executor は変更していない。 - 配布物の確認: 再開後に
npm pack --ignore-scriptsで docs-site の tarball を作り、新規の利用リポジトリへ展開した。外部依存は導入済みのものを共有し、同梱文書は最小の specdojo package fixture、Mermaid は既知の SVG を cache に投入して確認した。mermaidとbuildが通り、manifest の新配置、SVG の dist 同梱、同梱ページの公開 URL、wikilink、eject 優先、コードスニペット、public ファイル保持、Git の生成物除外と設定ファイルの追跡対象維持を確認した。HTTP 待受を使わない VitePress の実サーバでも、実 watcher による文書の編集・追加・削除、eject 削除時の同梱文書への復元、更新後の Markdown 変換を確認した。この確認は通常の npm install や実 SVG の描画・HTTP 取得を代替しない。 - 前回の blocker は解消済み:
pjr-e6qa-release-v0-4-7.mdの外部 URL 2件は再開時点で autolink に修正されており、再実行したnpm run validate:history-linksは成功した。本タスクでは当該ファイルを変更していない。 - 保護設定の反映: 利用者の承認後、ルート
package.jsonのdocs:rebuild:mermaidをrm -f .vitepress/mermaid/*.svg && npm run docs:build:mermaidへ変更した。feature ブランチの commit971ca627bをdevelopへ統合した（b6064620f）。依存定義は変更していない。 - 統合後の検証（2026-10-27、specdojo-orchestrator）:
b6064620fのクリーンな worktree でnpm run checkが成功した（178 テストファイル、2,781 テスト）。実 Chromium を指定した本リポジトリのnpm run docs:buildも成功した（84.34 秒）。既存の SVG は生成キャッシュとして再利用した。 - 通常導入した配布物の確認: CLI と docs-site の tarball を空の Git リポジトリへ
npm install --prefer-onlineで導入した。最初の cache 優先の導入ではajv@^8.20.0と@types/estree@1.0.9がETARGETになったが、registry への直接照会で両版の存在を確認し、メタデータ再取得後の通常導入は成功した。 - 配布版の実環境検証:
mermaidで新しい SVG を実 Chromium から.vitepress/mermaid/へ生成した。buildが成功し（9.16 秒）、SVG の dist 同梱、package 同梱ページ、eject 済み文書の優先、wikilink、利用者の public ファイル保持を確認した。旧ルートの生成ディレクトリを新たに作らず、生成物だけが Git の除外対象になることも確かめた。 - 配布版の
devを HTTP 待受付きで起動し、base を含む Mermaid URL の HTTP 200 と SVG 本文、元の Markdown を更新した後のステージング同期と変換後ページへの反映を確認した。検証用サーバは停止済み。sandbox からの申し送りはすべて確認でき、残る確認事項はない。
5. 関連ドキュメント
- specdojo:docs-editing-guide
- prj-0001:pjr-sj3x-docs-site-kata-staging
- prj-0001:pjr-ca0s-docs-site-output-in-node-modules
packages/docs-site/.vitepress/config.mtspackages/docs-site/.vitepress/kata-staging.tspackages/docs-site/src/gen-mermaid-svg.tssrc/shared/specdojo-gitignore.ts