dual-channel-watchexec-notifications

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

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

このスキルを使う場面

次のような場合にこのスキルを使います。

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

基本パターン

watchexec ラッパースクリプト → イベントを検出 → notify-script → 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 でファイルを検出してください
通知処理がブロックする	バックグラウンドで実行されていません	notify スクリプトに & を追加して、完了を待たずに実行してください
通知が重複する	再起動ループ	デバウンスロジックまたはクールダウン期間を追加してください
クラッシュ時のコンテキストがない	コンテキストファイルが書き込まれていません	watchexec の情報ファイルのパスが存在することを確認してください