boardface と manual-gen の配置方針決定 - 非対称配置と src/public 分離
boardface / manual-gen 配置方針の決定
背景
ボードゲームプラットフォーム(本家サイト、React + Vite)に、以下 2 つのツールを組み込みたい:
- boardface: seed と role からアバター SVG を決定論的に生成するツール
- manual-gen: ルールブック DSL から HTML を生成するツール(DSL → IR → MD → HTML の 4 段パイプライン)
現在ブログリポジトリ側で html-build(自作のマーカーコメント式バンドラ、esbuild を transformer として採用)を使った試作が非常にうまく回っており、壁打ちエージェントによる開発生産性が高い。このスタイルを維持したい。
一方で製品化を見据えると、両ツールをブログに置くか本家に置くか、どう共有するかを決める必要があった。
検討した選択肢と却下理由
却下: モノレポ + git submodule / パッケージ共有
- サブモジュール管理コストが重い
- リポジトリは「ブログ」「本家」の 2 つに留めたい(これは強い前提)
却下: 本家から TS ソースを fetch で読み込む
- CORS、バージョン固定、CDN キャッシュで事故る
- ブログ更新が本家を壊す方向の結合を生む
- 「フロント完結・費用ゼロ」の美点が崩れる
却下: manual-gen のために R2 を public 化してブログに置く
- R2 は現在 private で機密データが入っている
- ツール配置の都合でデータの機密レベルを下げるのは本末転倒
- データ側の要件が主、ツール配置は従
決定事項
1. 非対称配置を採用する
boardface と manual-gen を同じパターンで扱わない。データ性質が異なるため。
| ツール | 性質 | 配置リポジトリ |
|---|---|---|
| boardface | 計算器(seed → SVG、データ依存なし) | ブログ |
| manual-gen | ビューア(R2 の機密データを叙述) | 本家 |
理由: boardface は入力さえあれば単体で動く純粋計算。manual-gen は R2 認証と不可分なので、認証機構が既にある本家側に置くのが自然。
2. ディレクトリ構成は src/ と public/ の標準パターンに寄せる
現状の public/tools/board-face/ と public/tools/board-face/bundle/ の併置をやめる。
Before(現状):
public/tools/board-face/ ← split(編集用)public/tools/board-face/bundle/ ← bundle(出力)After(決定):
src/tools/boardface/ ← split(編集専用、公開しない)public/tools/boardface/ ← bundle(html-build 出力、公開)- 命名はハイフンなしで
boardfaceに統一(board-faceから変更) src/→public/は Vite / Next.js / webpack 等の業界標準パターンなので「気持ち悪さ」は慣れの問題- 「編集する場所」と「配信する場所」を分離することで事故が減る
3. ツールごとに playground と widget の 2 本立てにする
コア純関数を共有し、UI だけ 2 種類作る。
boardface(ブログリポジトリ):
src/tools/boardface/├── core/│ └── generate.ts ← seed, role → SVG 文字列(純関数、DOM 非依存)├── playground.html ← 全パターン展示・パラメータ探索(開発者向け、公開 OK)└── widget.html ← 製品版(?seed=xxx&role=user の最小 UI)ビルド後:
public/tools/boardface/├── playground.html└── widget.htmlmanual-gen(本家リポジトリ):
tools-src/manual-gen/ ← html-build 用(Vite の対象外)├── core/│ ├── dsl-parser.ts│ ├── ir.ts ← 判別共用体(既決事項)│ └── renderer.ts├── playground.html ← ローカルディレクトリ読み込み式、admin 専用└── (widget は React 側で実装)
src/tools/manual-gen/ ← Vite が見るメインソース└── viewer/ ← React コンポーネント、?id=xxx で R2 から取得
public/tools/manual-gen/└── playground.html ← html-build 出力、admin のみアクセス可4. 本家 ↔ ブログ連携は iframe 方式
本家 React から boardface を使う場合:
<iframe src={`https://blog.example.com/tools/boardface/widget.html?seed=${userId}&role=user`} width="48" height="48"/>- サブモジュール不要
- ブログデプロイで本家に反映される
- アバターは独立矩形なので iframe と相性が良い
- CSP 設定だけ注意
5. html-build は本家リポジトリでも使う
本家 Vite プロジェクト内に html-build を同居させる:
tools-src/manual-gen/を html-build が処理public/tools/manual-gen/playground.htmlを生成- React viewer と playground が同じ
core/を import する(本家リポジトリ内なのでパス直結、サブモジュール不要)
これにより本家側でも壁打ち開発スタイルが維持できる。
気にしているポイント(移行時の注意)
a. ディレクトリ移動の影響
- 現状の
public/tools/board-face/を触っている既存リンク・参照があれば洗い出す必要あり board-face→boardfaceのリネームと同時に行う- 既存 URL からのリダイレクトを張るかは要検討
b. html-build のビルド出力先切り替え
- 現在
public/tools/board-face/bundle/に吐いている設定をpublic/tools/boardface/に変更 - 入力ソースの参照先を
public/tools/board-face/からsrc/tools/boardface/に変更 - esbuild transformer 対応(別件で決定済み)と同時に進めると変更が重なるので、順序を決めて段階的に
c. manual-gen の playground をどう保護するか
- R2 private が前提なので playground.html 自体は読まれても再生できない設計
- とはいえ本家の admin ロールチェックは入れておくべき
- 本家に既にある認証ミドルウェアで
/tools/manual-gen/playground.htmlを守る
d. ブログと本家で html-build を二重管理するか
- 現時点では 両方にコピー配置 を許容する(最小構成を優先)
- 将来 html-build 自体をパッケージ化したくなったら再検討
- サブモジュール化はしない方針を維持
e. core/*.ts の TS 化タイミング
- boardface の core を TS 化(純関数、型定義)
- manual-gen の IR 型(判別共用体、別 decision で決定済み)
- 型チェックは
tsc --noEmitを別コマンドで(html-build のバンドルには含めない、別 decision 済み)
f. playground を公開するかどうか
- boardface playground: 公開 OK(計算器なので情報漏洩リスクなし)
- manual-gen playground: public に出さない(admin のみ、本家認証で保護)
移行作業の推奨順序
- 本家リポジトリに
tools-src/と html-build スクリプトを設置(esbuild transformer 版) - ブログリポジトリで
public/tools/board-face/をsrc/tools/boardface/(split)とpublic/tools/boardface/(bundle 出力先)に分離 - ハイフン削除リネーム(
board-face→boardface) - boardface の core を TS 化、playground.html と widget.html の 2 本立てに分割
- 本家 React に
<iframe>埋め込みを実装、widget.html との疎通確認 - manual-gen を本家リポジトリの
tools-src/manual-gen/で立ち上げ、IR 型定義から着手 - manual-gen の React viewer を実装、R2 認証経路と接続
- manual-gen の playground.html を html-build でビルド、admin 保護を設定
原則の再確認
- データの機密性が配置を決める(ツール配置は従)
- サブモジュール禁止、リポジトリは 2 つのまま
- 壁打ち html-build スタイルは維持する(本家でも使える)
- 非対称でよい(無理に揃えない)
src/とpublic/の分離は王道パターン(Web 標準に従う)