dual-channel-watchexec

watchexec のデュアルチャネル通知

watchexec がファイルの変更やプロセスのクラッシュを検出した際に、Telegram と Pushover の両方に確実に通知します。

自己進化するスキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターにずれが生じた場合、または回避策が必要になった場合は、先送りせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使う場面

次のような場合に、このスキルを使ってください。

• 通知付きのファイル変更監視を設定する
• Telegram と Pushover を使ったプロセスクラッシュのアラートを実装する
• デュアルチャネル通知に対応した watchexec のラッパーを作成する
• HTML（Telegram）とプレーンテキスト（Pushover）両方のメッセージを整形する
• 通知の配信やフォーマットの問題をトラブルシューティングする

基本パターン

watchexec ラッパースクリプト → イベントを検出 → 通知スクリプト → Telegram + Pushover

# wrapper.sh - Monitors process and detects restart reasons
watchexec --restart -- python bot.py

# On event, call:
notify-script.sh <reason> <exit_code> <watchexec_info_file> <crash_context>

---

重要なルール：フォーマットの違い

Telegram：HTML モードのみ

MESSAGE="<b>Alert</b>: <code>file.py</code>"
# Escape 3 chars: & → &amp;, < → &lt;, > → &gt;

Pushover：プレーンテキストのみ

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
# Strip HTML tags before sending
MESSAGE_PLAIN=$(echo "$MESSAGE_HTML" | sed 's/<[^>]*>//g')
SKILL_SCRIPT_EOF

Telegram で HTML を使う理由：

• Markdown では 40 文字以上（.、-、_ など）のエスケープが必要です
• HTML でエスケープが必要なのは 3 文字（&、<、>）だけです
• 業界のベストプラクティスです

---

クイックリファレンス

両方のチャネルに送信する

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
# 1. Build HTML message for Telegram
MESSAGE_HTML="<b>File</b>: <code>handler_classes.py</code>"

# 2. Strip HTML for Pushover
MESSAGE_PLAIN=$(echo "$MESSAGE_HTML" | sed 's/<[^>]*>//g')

# 3. Send to Telegram with HTML
curl -s -d "chat_id=$CHAT_ID" \
  -d "text=$MESSAGE_HTML" \
  -d "parse_mode=HTML" \
  https://api.telegram.org/bot$BOT_TOKEN/sendMessage

# 4. Send to Pushover with plain text
curl -s --form-string "message=$MESSAGE_PLAIN" \
  https://api.pushover.net/1/messages.json
SKILL_SCRIPT_EOF_2

実行パターン

# Fire-and-forget background notifications (don't block restarts)
"$NOTIFY_SCRIPT" "crash" "$EXIT_CODE" "$INFO_FILE" "$CONTEXT_FILE" &

---

検証チェックリスト

デプロイする前に確認してください。

• Telegram で Markdown ではなく HTML の解析モードを使用している
• Pushover 向けに HTML タグを除去している（プレーンテキストのみ）
• 動的なコンテンツすべてに HTML エスケープを適用している（&、<、>）
• 認証情報をハードコードせず、環境変数／Doppler から読み込んでいる
• デバッグ用にメッセージのアーカイブを有効にしている
• ファイルの検出に find -newermt ではなく stat を使用している
• ヒアドキュメントで、変数展開を有効にするために区切り文字をクォートしていない
• 通知をバックグラウンドで実行している（実行後は待たない）
• 特殊文字（_、.、-）を含むファイルでテストしている
• Telegram と Pushover の両方で通知を受信できている

---

まとめ

重要なポイント：

1. Telegram では常に HTML モードを使用してください（エスケープが簡単です）
2. Pushover では常に HTML タグを除去してください（プレーンテキストのみ）
3. HTML でエスケープするのは 3 文字だけです：& → &、< → <、> → >
4. デバッグ用に、送信前にメッセージをアーカイブしてください
5. macOS でのファイル検出には find -newermt ではなく stat を使用してください
6. 認証情報は環境変数／Doppler から読み込み、ハードコードしないでください
7. バックグラウンド通知は送信後に待たないようにしてください（再起動をブロックしません）

---

参考ドキュメント

詳細については、以下を参照してください。

• Telegram HTML - HTML モードのフォーマットとメッセージテンプレート
• Pushover Integration - API 呼び出しと優先度
• Credential Management - Doppler、環境変数、キーチェーンのパターン
• Watchexec Patterns - ファイル検出と再起動理由の検出
• Common Pitfalls - Pushover での HTML タグ、エスケープの問題、macOS との互換性

同梱の例：

• examples/notify-restart.sh - デュアルチャネル通知の完全なスクリプト
• examples/bot-wrapper.sh - 再起動検出機能付き watchexec ラッパー
• examples/setup-example.sh - セットアップガイドとインストール手順

トラブルシューティング

問題	原因	解決策
Telegram のエスケープエラー	Markdown を使用している	parse_mode=HTML で HTML モードに切り替えます
Pushover に HTML タグが表示される	HTML が除去されていない	Pushover に送信する前に sed でタグを除去します
通知が届かない	認証情報が不足している	BOT_TOKEN、CHAT_ID、Pushover のキーを確認します
特殊文字が壊れている	HTML エスケープが不足している	動的コンテンツ内の &、<、> をエスケープします
find -newermt が macOS で失敗する	macOS との互換性がない	代わりに stat を使ってファイルを検出します
通知がブロックされる	バックグラウンドで実行されていない	& を追加して通知スクリプトを非同期実行します
通知が重複する	再起動ループ	デバウンス処理またはクールダウン期間を追加します
クラッシュのコンテキストが不足している	コンテキストファイルが書き込まれていない	watchexec の情報ファイルのパスが存在することを確認します

実行後の振り返り

このスキルの実行が完了したら、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラー表を修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーター表を更新して一致させます。
3. 回避策が必要でしたか？ — 即興で対応した場合（異なるフラグや追加手順など）は、次回同じ回避策が必要にならないよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新してください。憶測で更新しないでください。