Doc History Server

ドキュメントのgit履歴の配信と生成のためのスタンドアロンパッケージです。ローカル開発用のREST APIサーバーとCIビルド用のCLIバッチジェネレーターの2つのモードを持ちます。

概要

Doc History Serverはpackages/doc-history-server/にあるサブパッケージで、ドキュメント履歴機能のすべてのgit履歴抽出を処理します。コストの高いgit操作をサイトビルドから分離するために、zfbビルドパイプラインから抽出されました。

2つのモードで動作します：

• サーバーモード -- ローカル開発時にHTTPサーバーを実行し、オンデマンドで履歴を配信

• CLIモード -- CIの本番ビルドですべての履歴JSONファイルをバッチ生成

この分離により、zfbサイトビルドとHistory生成を独立したジョブとして実行する並列CI戦略が可能になり、合計ビルド時間を短縮します。

サーバーモード（ローカル開発）

サーバーは設定可能なポート（デフォルト4322）で実行され、REST API経由でドキュメント履歴を配信します。標準のpnpm devセットアップでは、zfbとdoc-history-serverがrun-pを使用して同時に実行されます。

サーバーの起動

pnpm dev -- --content-dir src/content/docs --locale ja:src/content/docs-ja --port 4322

エンドポイント

GET /doc-history/{slug}.json

ドキュメントの完全なgit履歴を返します。

GET /doc-history/guides/writing-docs.json

GET /doc-history/{locale}/{slug}.json

ローカライズされたドキュメントの履歴を返します。

GET /doc-history/ja/guides/writing-docs.json

GET /health

ヘルスチェックエンドポイント。

{ "status": "ok" }

サーバーオプション

サーバーの動作

• ファイルインデックスは10秒ごとにリフレッシュされ、新しいファイルやリネームされたファイルを自動的に検出します

• クロスオリジン開発アクセス用のCORSヘッダーが含まれます

• 不明なスラッグへのリクエストは{ "error": "No doc found for slug: ..." }とともに404を返します

zfbインテグレーション

開発モードでは、doc-historyのzfbプラグインのdevMiddlewareフックが/doc-history/*リクエストをこのサーバーにプロキシします。これにより、ブラウザの履歴パネルはzfb開発サーバーを通じてスタンドアロンサーバーから透過的に取得します。

ルートのpnpm devコマンドは、run-pを使用してzfb（ポート4321）とdoc-history-server（ポート4322）を同時に実行します。

CLIモード（CIビルド）

CLIはすべてのドキュメントの静的JSONファイルを生成します。CIパイプライン向けです。

使い方

pnpm generate -- --content-dir src/content/docs --locale ja:src/content/docs-ja --out-dir dist/doc-history

CLIオプション

CIパイプライン統合

CIパイプラインはzfbサイトビルドと並行して履歴生成を実行します：

• build-siteジョブ：フルクローン（fetch-depth: 0）、pnpm buildでzfbサイトをビルド（SKIP_DOC_HISTORYなし — preBuildステップがgit log --followを実行して.zfb/doc-history-meta.jsonに実際の日付を書き込み、SSG HTMLに作成日・更新日・著者ブロックとしてインライン展開される）

• build-historyジョブ：フルクローン（fetch-depth: 0）、@takazudo/zudo-doc-history-server generateを実行

• deployジョブ：両方のアーティファクトをマージしてCloudflare Workersにデプロイ

この並列化は、履歴生成がzfbビルドから完全に独立しているため可能です。

データ形式

DocHistoryEntry

ドキュメントの単一のgitリビジョンエントリ：

interface DocHistoryEntry {
  /** 完全なコミットハッシュ（表示には.slice(0, 7)を使用） */
  hash: string;
  /** ISO 8601形式の日付文字列 */
  date: string;
  /** コミット著者名 */
  author: string;
  /** コミットメッセージの1行目 */
  message: string;
  /** このリビジョンでの完全なファイル内容 */
  content: string;
}

DocHistoryData

単一ドキュメントの完全な履歴データ：

interface DocHistoryData {
  /** ドキュメントスラッグ（ルートパス） */
  slug: string;
  /** リポジトリ内の相対ファイルパス */
  filePath: string;
  /** gitリビジョンエントリ（新しい順） */
  entries: DocHistoryEntry[];
}

出力構造

生成されるファイルはコンテンツディレクトリ構造をミラーします：

dist/doc-history/
  getting-started.json
  guides/writing-docs.json
  guides/color.json
  ja/getting-started.json
  ja/guides/writing-docs.json

アーキテクチャ

Git操作

履歴抽出は以下の同期gitコール（execFileSync）を使用します：

• git log -- --followによるリネーム追跡を含むコミットリスト

• git show -- 各リビジョンでのファイル内容

--followフラグは複数のフォールバック戦略によるリネーム追跡を行うため、移動やリネームされたドキュメントでも完全な履歴が保持されます。

主要な設計判断

• 同期git -- execFileSyncは開発サーバー（同一プロセス、逐次処理）で問題ありません。CI CLIは境界付き並列処理を使用します：Promise.allとセマフォでMath.min(8, Math.max(2, cpus().length))の同時ワーカー数に制限して実行します

• リポジトリ相対パス -- APIレスポンスは絶対サーバーパスの漏洩を避けるために相対ファイルパスを使用します

• スタンドアロンパッケージ -- 並列CIビルドと独立したバージョニングを可能にするためにzfbから分離されています

サブパッケージの場所

packages/doc-history-server/
├── src/
│   ├── index.ts        # サーバーエントリー — 引数解析、HTTPサーバー起動
│   ├── cli.ts          # CLIエントリー — 引数解析、JSONバッチ生成
│   ├── args.ts         # 境界チェック付き共有引数解析
│   ├── server.ts       # HTTPサーバー（REST APIエンドポイント）
│   ├── git-history.ts  # コアgitロジック（log、show、follow、リネーム追跡）
│   ├── shared.ts       # 共有ヘルパー（getContentDirEntries）
│   └── types.ts        # DocHistoryEntry、DocHistoryData型
├── package.json
├── tsconfig.json
└── README.md