Markdownの更新を検出してHTMLに変換する abook-watch-server の概要 by Claude Code

このサーバは結城さんがabookという書籍を執筆する際に開発したものです。

概要

abook-watch-serverは、Rubyで実装されたファイル監視ツールで、Markdownファイルの変更を検出して自動的にhtml-builderを実行し、ブラウザでプレビューする機能を提供します。

主要な特徴

1. 単一プロセス管理方式

• 同時に監視できるのは1つのファイルのみ
• 新しい監視を開始すると、既存の監視プロセスを自動停止
• PIDファイル（.tmp/.watch-server.pid）で現在の監視対象を管理

2. コマンド体系

直接実行：

# ID指定が必要なコマンド
bin/abook-watch-server <id> start    # 指定ファイルの監視開始
bin/abook-watch-server <id> restart  # 指定ファイルの監視再開

# ID不要のコマンド（全プロセス対象）
bin/abook-watch-server stop          # 全監視プロセス停止
bin/abook-watch-server status        # 全監視プロセスの状態表示
bin/abook-watch-server log           # ログ表示

Makefile経由：

make start     # $(id).mdの監視開始
make restart   # $(id).mdの監視再開
make stop      # 全監視プロセス停止
make status    # 全監視プロセスの状態表示
make log       # ログ表示

3. 技術的実装

ファイル監視：

• entrコマンドを使用（要事前インストール：brew install entr）
• ファイル変更時に自動的にコマンドを再実行

プロセス管理：

# 新しいプロセスグループで起動
pid = fork do
  Process.setsid
  # ログファイルにリダイレクト
  $stdout.reopen(log_file, 'w')
  $stderr.reopen(log_file, 'w')
  
  # entrでファイル監視・html-builder実行
  exec("echo #{file} | entr -n -r sh -c 'bin/html-builder #{file} && browser-open && focus-terminal'")
end

プロセス停止処理：

# プロセスグループ全体を終了
pgid = Process.getpgid(pid)
Process.kill('TERM', -pgid)

4. ビルド・プレビューフロー

1. Markdownファイルの変更を検出
2. html-builderコマンドを実行
3. 生成されたHTMLをブラウザで開く
4. ターミナル（iTerm2）にフォーカスを戻す

5. ファイル構成

.tmp/
├── .watch-server.pid     # 現在の監視プロセス情報（PID:ID形式）
└── .watch-server.log     # 実行ログ

6. 環境変数

• OPENER: ブラウザ起動コマンド（デフォルト：open -a "Microsoft Edge"）

実装のポイント

1. 互換性維持：古い形式のPID/ログファイルも認識し、移行をスムーズに
2. エラー処理：プロセスが既に終了している場合の適切な処理
3. シェルエスケープ：Shellwords.escapeで安全なコマンド実行
4. フォーカス制御：AppleScriptでターミナルにフォーカスを戻す

必要な依存関係

• Ruby（標準ライブラリのみ使用）
• entrコマンド（ファイル監視）
• macOS（openコマンド、AppleScript使用）

このツールは、ファイル編集時の即座のプレビュー確認を可能にし、開発効率を向上させる設計となっています。