log

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.html

manual-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 のみ、本家認証で保護)

移行作業の推奨順序

  1. 本家リポジトリに tools-src/ と html-build スクリプトを設置(esbuild transformer 版)
  2. ブログリポジトリで public/tools/board-face/ を src/tools/boardface/(split)と public/tools/boardface/(bundle 出力先)に分離
  3. ハイフン削除リネーム(board-face → boardface)
  4. boardface の core を TS 化、playground.html と widget.html の 2 本立てに分割
  5. 本家 React に <iframe> 埋め込みを実装、widget.html との疎通確認
  6. manual-gen を本家リポジトリの tools-src/manual-gen/ で立ち上げ、IR 型定義から着手
  7. manual-gen の React viewer を実装、R2 認証経路と接続
  8. manual-gen の playground.html を html-build でビルド、admin 保護を設定

原則の再確認

  • データの機密性が配置を決める(ツール配置は従)
  • サブモジュール禁止、リポジトリは 2 つのまま
  • 壁打ち html-build スタイルは維持する(本家でも使える)
  • 非対称でよい(無理に揃えない)
  • src/ と public/ の分離は王道パターン(Web 標準に従う)