ccc-notifier 0.4.0 → 0.6.0

package/README.md

@@ -1,179 +1,186 @@
 # ccc-notifier
 
-**ccc = Claude Code Cost**(現在は [Codex CLI](docs/codex.md) のコストも同じ仕組みで扱えます)。Claude Code や Codex CLI で **プロンプトを実行するたび**、そのターンにかかったコストを **$(USD)と¥(JPY)の両方** で自動通知するツールです。**5分で導入できます。**
+Claude CodeとCodex CLIの利用コストをターンごとに通知し、履歴とダッシュボードで見えるようにするツールです。
 
-```
-💰 API換算 $0.267(¥40)| Fable 5
-in 1.2k(cache 40%)/ out 480 · 📁 my-app · 今日: $1.85
+> [!IMPORTANT]
+> **表示される金額は概算です。** 実際の請求額と一致する保証はありません。「使いすぎに気づく」ための目安として使ってください。詳しくは[金額の意味](docs/cost.md)を参照してください。
+
+```text
+💰 API換算 $0.267(¥40) | Fable 5
+in 1.2k(cache 40%) / out 480 · 📁 my-app · 今日: $1.85
 バグを直してテストを通してください
 ```
 
-上が通知の例です(1行目がタイトル、2〜3行目が本文)。応答が完了するたびに OS 通知(任意で Slack 通知も)としてこれが届きます。
-
-> **⚠️ 表示される金額はあくまで概算値です。** transcript のトークン数 × 公開単価表からローカルで計算した参考値であり、Anthropic の請求額と一致することを保証するものではありません。「使いすぎに気づく」ための目安としてご利用ください(詳細は [金額の意味](docs/cost.md))。
-
 ![通知の実例](docs/images/notification.png)
 
 ![ダッシュボード](docs/images/dashboard.png)
 
-## 特徴 / Features
+## 主な機能
 
-- **ターン毎に自動通知** — Claude Code / Codex CLI の応答が完了するたび(Stop hook)に、そのターンのコストを自動でプッシュ通知します。自分から `/cost` を見に行く必要はありません
-- **$ と ¥ を併記** — USD と JPY の両方を毎回表示します(為替レートは自動取得 + キャッシュ + 固定フォールバックの三段構え)
-- **プロンプト全文をローカルに履歴保存** — `~/.ccc-notifier/history.jsonl` にそのターンのプロンプト全文を保存します(外部には送信されません)
-- **HTMLダッシュボード** — `dashboard` コマンドで、サマリー・コスト推移(**日 / 週 / 月**で切替、横スクロールで過去まで)・モデル別/プロジェクト別内訳・検索できるターン履歴を1枚の HTML(完全自己完結・ライト/ダーク対応)に書き出してブラウザで開きます。棒をクリックするとその期間が選択され、内訳・履歴が連動(「通算」で全期間)。Codex CLI を併用していれば **Claude / Codex** のソースフィルタも使えます
-- **月予算(monthly budget)** — 月に使える金額(USD)を設定すると、ダッシュボードに**当月の使用額 / 予算・使用率(%)** をプログレスバーで表示します(`init` の対話、または `ccc-notifier budget <金額>` で設定。Claude Code と Codex CLI の合算です)
-- **Codex CLI もそのまま検出** — `init` を実行すると `~/.codex` の有無を見て、あれば Codex にも導入するか聞かれます。通知・履歴・ダッシュボード・`sweep` は Claude Code と全く同じ仕組みで扱います([詳細](docs/codex.md))
-- **OS 標準の通知機構のみ使用・追加依存ゼロ** — 通知は macOS では `osascript`、Windows では PowerShell 標準のトースト通知機能のみで送信します(node-notifier 等の外部通知ライブラリには一切依存しません)
-- **全処理ローカル・フェイルセーフ設計** — 通知や集計の処理が失敗しても、Claude Code / Codex CLI 本体の応答は絶対にブロックしません
+- Claude Codeの応答完了ごとに、USD・JPYの概算をOS通知またはSlackへ送ります
+- プロンプトと概算をローカルへ保存し、あとから検索・集計できます
+- 日・週・月の推移やモデル別・プロジェクト別の内訳をHTMLダッシュボードで確認できます
+- 月予算を設定し、今月の使用率を確認できます
+- 通知を一時停止しても、履歴の記録は続けられます
+- Codex CLIも任意で追加し、Claude Codeと同じダッシュボードで確認できます
 
-## 必要環境 / Requirements
+## 必要なもの
 
-- Node.js 20 以上(未導入の場合は [Node.js の用意](docs/installing-node.md) を参照してください)
-- Claude Code(インストール・利用中であること。`init` は Claude Code の Stop hook を必ず設定します)
-- (任意)[Codex CLI](docs/codex.md) を併用している場合は、`init` が自動検出してそのコストも同じ仕組みで通知できます
+- Node.js 20以上（未導入の場合は[Node.jsの用意](docs/installing-node.md)）
+- Claude Code（必須）
+- Codex CLI（任意）
 
-Windows / WSL2 で使う場合は、環境ごとの手順を [Windows / WSL2 での導入](docs/windows-wsl2.md) にまとめています。
+Windows / WSL2は[専用の導入手順](docs/windows-wsl2.md)も参照してください。
 
-## インストール / Install
+## まず試す
 
-### 方法A: npm から(推奨)
+グローバルインストールは不要です。最新版を一度試します。
 
 ```bash
-npm install -g ccc-notifier
-ccc-notifier init
+npx ccc-notifier@latest init
 ```
 
-グローバルに入れず一度だけ試すなら `npx ccc-notifier init` でも実行できます。`ccc-notifier` には短縮エイリアス `cccn` もあります(`cccn doctor` など)。
+画面の質問に沿って、通知方法・金額ラベル・月予算・Codex連携を選びます。
 
-### 方法B: ソースから(開発版・最新を試したいとき)
+`init`がClaude Codeの`~/.claude/settings.json`を書き換える場合は、**書き換える前にタイムスタンプ付きのバックアップ**を作ります。既存の設定を解析できない場合は自動編集せず、手動設定方法を表示します。
+
+セットアップ後にClaude Codeで何か実行してください。通知が届かない場合は次で診断できます。
 
 ```bash
-git clone https://github.com/shimabox/ccc-notifier.git
-cd ccc-notifier
-mise install          # mise 利用時(Node.js 20 が自動で入ります)。mise が無ければ Node.js 20 以上を用意してください
-npm ci
-npm run build
-node dist/cli.js init
+npx ccc-notifier@latest doctor
 ```
 
-最後の `node dist/cli.js init` が次の「セットアップ」の内容(対話形式のセットアップ)です。
+Codex連携を選んだ場合は、Codexを再起動し、表示されるhookの確認画面で承認してください。詳しくは[Codex CLI対応](docs/codex.md)を参照してください。
 
-## セットアップ / Setup
+<details>
+<summary><strong>まず直近1週間の履歴で試す（全履歴・完全削除まで）</strong></summary>
 
-> **補足**: 以降に出てくる `npx ccc-notifier <command>` や `npm install -g ccc-notifier` は、npm でインストールした場合(方法A)の表記です。**方法B(ソースから)でインストールした場合は、`npx ccc-notifier <command>` を `node dist/cli.js <command>` に読み替えてください**(リポジトリのディレクトリで実行します)。
+上のセットアップが終わったら、まず直近7日分の件数と概算を事前確認します。この操作では何も変更しません。
 
-1. **セットアップコマンドを実行**
+```bash
+npx ccc-notifier@latest sweep --dry-run --days 7
+```
 
-   インストール方法に応じて `init` を実行します。
+次の操作は、保存済み履歴をいったん消し、直近7日分だけを作り直します。履歴のバックアップは作りません。
 
-   - 方法A(npm)の場合: `npx ccc-notifier@latest init`
-   - 方法B(ソースから)の場合: `node dist/cli.js init`
+```bash
+npx ccc-notifier@latest sweep --days 7
+```
 
-2. **質問に答える**
+作成した7日分の履歴をダッシュボードで確認します。
 
-   対話形式で次の4点(Codex CLI を検出した場合はもう1点)を聞かれます。
+```bash
+npx ccc-notifier@latest dashboard --days 7
+```
 
-   - 通知チャネル(OS通知のみ / Slackのみ / OS通知+Slack / 通知なし(記録・ダッシュボードのみ))
-   - コスト表示ラベル(API換算 / 実額)
-   - USD/JPY のフォールバック為替レート(既定 150円)
-   - 月の予算(USD、既定 $400。`0` で無効。ダッシュボードに当月の使用率を表示。詳細は [月予算](docs/monthly-budget.md))
-   - (Codex CLI 検出時)Codex にもコスト通知を入れるか(既定 Yes。詳細は [Codex CLI 対応](docs/codex.md))
+### 続けて使う場合
 
-   完了すると Claude Code の `~/.claude/settings.json` に Stop hook が自動で追記されます。**既存の設定内容(他の hook や設定)は一切変更されず**、書き込み前に必ず `settings.json.bak-<タイムスタンプ>` としてバックアップが作成されます。settings.json が壊れている(JSONとして解析できない)場合は自動編集を諦め、手動で追記する内容を画面に表示するだけで、ファイルには一切書き込みません。
+まず、全履歴を作り直した場合の件数と概算を事前確認します。
 
-3. **Claude Code(や Codex CLI)で何か実行してみる**
+```bash
+npx ccc-notifier@latest sweep --dry-run
+```
 
-   ひとこと実行して応答が完了すると、通知が届きます。
+問題なければ、7日版の履歴をいったん消し、残っているデータから全履歴を作り直します。
 
-届かない場合は `npx ccc-notifier doctor` で診断できます。hook登録・設定ファイル・単価表・為替レート・テスト通知・直近セッション合計などを ✅ / ⚠️ / ❌ で表示し、❌ が1つでもあれば終了コード1を返します(通知が来ないときの詳しい対処は [FAQ](docs/faq.md) 参照)。
+```bash
+npx ccc-notifier@latest sweep
+```
 
-### 非対話実行(CI・スクリプト向け)/ Non-interactive flags
+継続利用しやすいようにグローバルインストールし、連携先をグローバル版へ更新します。
 
-CI などから非対話で `init` したい場合は次のフラグが使えます。
+```bash
+npm install -g ccc-notifier
+ccc-notifier init
+```
 
-| フラグ | 説明 |
-|---|---|
-| `--yes`, `-y` | 対話プロンプトを出さずに実行(非対話には必須) |
-| `--os-only` | Slack を無効化し OS通知のみにする |
-| `--slack-webhook <url>` | Slack Incoming Webhook URL を指定して有効化 |
-| `--slack-only` | Slack のみにする(OS 通知を無効化)。`--slack-webhook` と併用が必須 |
-| `--no-notify` | 通知なし(記録・ダッシュボードのみ)。`--os-only` / `--slack-only` / `--slack-webhook` とは併用不可(例: `npx ccc-notifier init --yes --no-notify`。詳細は [設定](docs/configuration.md#通知なしモード記録ダッシュボードのみ--dashboard-only-mode)) |
-| `--label <api_equivalent\|actual>` | コスト表示ラベルを指定 |
-| `--rate <number>` | USD/JPY フォールバックレートを指定 |
-| `--budget <USD>` | 月予算(USD)を指定(0 で無効)。未指定なら既定 **$400**(既存設定があれば維持) |
-| `--codex` | Codex CLI にも Stop hook を導入する(`~/.codex` 未検出でも強制導入。詳細は [Codex CLI 対応](docs/codex.md)) |
-| `--no-codex` | Codex hook を導入しない(検出しても触らない)。`--codex` とは併用不可 |
-
-## コマンド一覧 / Commands
-
-| コマンド | 説明 |
-|---|---|
-| `init` | Stop hook を対話形式でセットアップ(前述のフラグで非対話実行も可) |
-| `doctor` | hook登録・設定・単価表・為替・通知・直近セッション合計を診断 |
-| `report [--days N] [--json]` | 蓄積した履歴を集計してターミナルに表示(`--days` の既定は30、不正な値も30扱い)。`--json` で機械可読な出力 |
-| `dashboard [--all\|--days N] [--no-open] [--out <path>] [--refresh <sec>\|--no-refresh]` | 履歴を可視化した HTML ダッシュボードを生成してブラウザで開く(引数なしは設定期間の直近版 `report.html`、`--all` は全履歴版 `report-all.html`。詳細は [ダッシュボード](docs/dashboard.md)) |
-| `sweep [--dry-run] [--days N] [--include-active]` | 過去の未計上分(hook 導入前や後から完了したサブエージェント分)を一括で履歴に取り込む。ローカル走査のみで **Claude API を呼ばず料金ゼロ**・二重計上なし(詳細は [過去分の取り込み](docs/sweep.md)) |
-| `history <clear\|redact> [--days N] [--yes]` | 履歴(`history.jsonl`)を削除。`clear` はレコードごと、`redact` はプロンプト全文だけ消去。`--days N` で「N 日より前」だけ対象(詳細は [履歴の削除](docs/dashboard.md#履歴の削除--deleting-history)) |
-| `budget [<USD>]` | 月予算(USD)の表示/設定。金額省略で現在の予算と当月の使用率を表示、`budget 400` で設定、`budget 0` で解除(詳細は [月予算](docs/monthly-budget.md)) |
-| `mute [30m\|2h\|1d]` | 通知(OS/Slack)を一時停止する。期間省略で無期限、`30m`/`2h`/`1d` で期限付き。**停止中もコスト記録とダッシュボード更新は続きます**(詳細は [設定 / mute](docs/configuration.md#通知の一時停止と再開--pausing--resuming-notifications)) |
-| `unmute` | 停止した通知を再開する |
-| `uninstall [--purge] [--yes]` | Stop hook を削除。`--purge` を付けると `~/.ccc-notifier` のデータ(設定・履歴・キャッシュ)も削除 |
-| `track` | Stop hook から自動的に呼ばれる**内部コマンド**。stdin 経由で JSON を受け取ります。手動実行は不要です |
-| `--version`, `-v` | バージョン表示 |
-| `--help`, `-h` | ヘルプ表示 |
-
-`report --json` は次のような形の JSON を出力します(スクリプト等への取り込み用)。
-
-```json
-{
-  "days": 30,
-  "daily": [{ "date": "2026-07-06", "turns": 3, "inputTokens": 12345, "outputTokens": 678, "costUSD": 0.42, "costJPY": 63 }],
-  "byModel": { "claude-fable-5": { "turns": 2, "costUSD": 0.3, "costJPY": 45 }, "claude-sonnet-5": { "turns": 1, "costUSD": 0.03, "costJPY": 4.5 } },
-  "total": { "turns": 3, "inputTokens": 12345, "outputTokens": 678, "costUSD": 0.42, "costJPY": 63, "subagentsUSD": 0.03 }
-}
+### 使わない場合
+
+この時点ではグローバル版を入れていないため、npxでccc-notifierのhook・設定・履歴・キャッシュを削除します。
+
+```bash
+npx ccc-notifier@latest uninstall --yes --purge
 ```
 
-金額(`costUSD`・`costJPY`)は**サブエージェント分を含む総額**です。`total.subagentsUSD` はそのうちサブエージェントが占める金額(なければ 0)、`byModel` にはサブエージェントが使ったモデルも含まれます。
+安全のため作成した`settings.json.bak-*`などのバックアップは残ります。不要なら内容を確認してから手動で削除してください。
 
-## ダッシュボード / Dashboard
+</details>
 
-`dashboard` コマンドで、サマリー(今日 / 今週 / 今月 / 通算)、コスト推移(日/週/月で切替・横スクロールで過去まで)、モデル別/プロジェクト別内訳、検索・行展開できるターン履歴を HTML に書き出してブラウザで開きます。自動生成物は、毎ターン更新する直近版 `~/.ccc-notifier/report.html`(既定30日)と、ローカル日の最初の正常なターンだけ更新する全履歴版 `~/.ccc-notifier/report-all.html` に分かれます。片方が未生成でも生成方法を示すplaceholderを置くため、ページ内リンクは切れません。履歴・カーソル・生成snapshotは `cache/data.lock/` で直列化されます。履歴の読み込みと解析は正確な当月予算を保つため全履歴が対象です。生成物は **CSS/JS/SVG をすべてインライン化した完全自己完結・オフライン動作・外部通信ゼロ**のファイルで、ライト/ダーク両対応です。
+## 気に入ったらグローバルインストール
 
 ```bash
-npx ccc-notifier dashboard            # 設定期間(既定30日)の直近版 report.html を生成して開く
-npx ccc-notifier dashboard --all      # 全履歴版 report-all.html を生成して開く
-npx ccc-notifier dashboard --days 7   # 直近7日の report.html を生成して開く
+npm install -g ccc-notifier
+ccc-notifier init
 ```
 
-グラフの棒をクリックするとその期間に内訳・履歴が連動し、全履歴版では「通算」、期間限定版では「対象期間合計」で埋め込まれた全期間に戻せます。直近版は応答完了ごと、全履歴版は1日1回(または手動 `dashboard --all`)更新されます。Codex CLI のレコードがあれば **Claude / Codex** を絞り込むソースフィルタも表示されます(詳細は [Codex CLI 対応](docs/codex.md))。検索・行クリックでプロンプト全文を確認できます:
+以降は`ccc-notifier doctor`のように短く実行できます。`cccn`も同じコマンドとして使えます。
+
+## よく使うコマンド
+
+以下はグローバルインストール後の表記です。npxで使う場合は`ccc-notifier`を`npx ccc-notifier@latest`に置き換えてください。
+
+| コマンド | できること |
+|---|---|
+| `ccc-notifier init` | 通知や連携を設定する |
+| `ccc-notifier doctor` | 設定と通知を診断する |
+| `ccc-notifier report [--days N]` | コスト集計をターミナルに表示する |
+| `ccc-notifier dashboard` | 直近のHTMLダッシュボードを開く |
+| `ccc-notifier dashboard --all` | 保存済みの全履歴版を開く |
+| `ccc-notifier budget [<USD>]` | 月予算を確認・設定する（`0`で解除） |
+| `ccc-notifier mute [30m\|2h\|1d]` | 通知を一時停止する（期間省略で無期限） |
+| `ccc-notifier unmute` | 通知を再開する |
+| `ccc-notifier sweep --dry-run [--days N]` | 履歴を作り直した場合の件数と概算を確認する |
+| `ccc-notifier sweep [--days N]` | 残っている利用データから履歴を作り直す |
+
+> [!CAUTION]
+> **`sweep`は履歴を作り直すコマンドです。** 保存済みの履歴をいったん消し、Claude Code / Codex CLIに残っているデータから再作成します。設定や通知は消えませんが、履歴のバックアップは作りません。以前に削除・伏せ字にした履歴も、Claude Code / Codex CLI側の元データに残っていれば再び入ります。また、再作成した時点の単価と為替を使うため、以前の金額から変わることがあります。先に`--dry-run`で確認してください。詳しくは[履歴の再生成](docs/sweep.md)を参照してください。
+
+ダッシュボード、履歴の削除、通知なしモードなど、その他の操作は[ドキュメント](#ドキュメント)または`ccc-notifier --help`で確認できます。
+
+## アップデート
+
+npxで使う場合は、各コマンドに`@latest`を付ければ常に最新版が使われるため、別の更新作業は不要です。
+
+グローバルインストールの場合は、次のコマンドだけで更新できます。
+
+```bash
+npm update -g ccc-notifier
+```
+
+hook設定の更新が必要なリリースだけ、リリース案内に従って`init`を実行してください。Codexの更新手順は[Codex CLI対応](docs/codex.md)にまとめています。
+
+## 完全に削除する
+
+グローバルインストールした場合は、ccc-notifierのhookと保存データを削除してからパッケージを削除します。
+
+```bash
+ccc-notifier uninstall --yes --purge
+npm uninstall -g ccc-notifier
+```
 
-![ターン履歴(検索と全文展開)](docs/images/history-expand.png)
+npxだけで使っていた場合は、最初のコマンドを`npx ccc-notifier@latest uninstall --yes --purge`に置き換え、`npm uninstall -g`は不要です。安全のため作成した`settings.json.bak-*`などのバックアップは自動削除しません。
 
-期間の連動・自動更新・月予算表示・履歴の削除など、詳しくは [ダッシュボード](docs/dashboard.md) を参照してください。
+## プライバシー
 
-## プライバシー / Privacy
+- 履歴とプロンプトは`~/.ccc-notifier`にローカル保存します
+- Slackを設定した場合だけ、概算・トークン情報とプロンプトを指定したSlack Webhookへ送ります。既定はプロンプト冒頭100字で、設定により文字数の変更や全文送信もできます
+- 単価表と為替レートの取得時に外部通信しますが、プロンプトやコードは送りません
 
-- プロンプトの全文は **ローカルの `~/.ccc-notifier/history.jsonl` にのみ** 保存されます
-- OS通知に表示されるプロンプトは、ローカル上で先頭50字程度に切り詰めたものです
-- Slack を設定した場合のみ、既定でプロンプト冒頭100字(`sendFullPrompt` で文字数変更・全文送信も可能)がその Slack Webhook 宛に送信されます
-- それ以外に外部へ送信されるのは次の2種類の API 呼び出しだけです。いずれもプロンプトやコードの内容を一切含まない、レート・価格を取得するだけのリクエストです
-  - 為替レート取得([frankfurter.dev](https://frankfurter.dev/) → 失敗時は [open.er-api.com](https://open.er-api.com/))
-  - 単価表取得([LiteLLM の公開JSON](https://github.com/BerriAI/litellm))
+詳しくは[Slack通知](docs/slack.md)と[仕組み](docs/how-it-works.md)を参照してください。
 
-## ドキュメント / Documentation
+## ドキュメント
 
-- [Node.js の用意](docs/installing-node.md) — Node.js 20 が未導入の方へ(mise / 公式インストーラ)
-- [Windows / WSL2 での導入](docs/windows-wsl2.md) — ネイティブ Windows と WSL2 での手順
-- [Codex CLI 対応](docs/codex.md) — 導入・hook の信頼承認・仕組み・制限
-- [ダッシュボード](docs/dashboard.md) — 期間の連動・自動更新・履歴の削除
-- [月予算 / Monthly budget](docs/monthly-budget.md) — 当月の使用率表示
-- [過去分の取り込み / sweep](docs/sweep.md) — hook 導入前・後から完了した分の回収
-- [金額の意味](docs/cost.md) — ラベルの意味と、概算値である理由
-- [設定 / Configuration](docs/configuration.md) — `config.json` の全キーと通知の一時停止(mute)
-- [Slack 通知の有効化](docs/slack.md) — Incoming Webhook の設定
-- [仕組み / How it Works](docs/how-it-works.md) — Stop hook から通知までの流れ
-- [よくある質問 / FAQ](docs/faq.md) — 通知が来ない・`/cost` との差など
+- [Node.jsの用意](docs/installing-node.md)
+- [Windows / WSL2での導入](docs/windows-wsl2.md)
+- [Codex CLI対応](docs/codex.md)
+- [Slack通知](docs/slack.md)
+- [設定・通知の一時停止](docs/configuration.md)
+- [金額の意味](docs/cost.md)
+- [ダッシュボードと履歴の削除](docs/dashboard.md)
+- [月予算](docs/monthly-budget.md)
+- [履歴の再生成（sweep）](docs/sweep.md)
+- [仕組み](docs/how-it-works.md)
+- [よくある質問](docs/faq.md)
 
 ## License
 

package/dist/{budget-EHWPEYXY.js → budget-V7CCMJHF.js}

@@ -7,7 +7,7 @@ import {
   currentMonthTotals,
   paths,
   readConfig
-} from "./chunk-26CISNOE.js";
+} from "./chunk-OOAC5ULQ.js";
 
 // src/budget.ts
 import { writeFileSync } from "fs";

package/dist/{chunk-J6Y3RMMC.js → chunk-27SJELD2.js}

@@ -1,19 +1,100 @@
 #!/usr/bin/env node
 import {
   paths
-} from "./chunk-26CISNOE.js";
+} from "./chunk-OOAC5ULQ.js";
 
-// src/data-lock.ts
-import { randomUUID } from "crypto";
-import { hostname } from "os";
+// src/dashboard-state.ts
 import {
+  closeSync,
   existsSync,
-  mkdirSync,
+  openSync,
   readFileSync,
+  readSync,
   renameSync,
   rmSync,
   writeFileSync
 } from "fs";
+import { randomUUID } from "crypto";
+function localDate(now) {
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, "0");
+  const d = String(now.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+function timeZone() {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone || "unknown";
+}
+function makeFullDashboardState(now = /* @__PURE__ */ new Date()) {
+  return { localDate: localDate(now), timeZone: timeZone(), generatedAt: now.toISOString() };
+}
+function readState() {
+  const file = paths().dashboardFullStateFile;
+  if (!existsSync(file)) return null;
+  try {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+    const v = value;
+    if (typeof v.localDate !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(v.localDate) || typeof v.timeZone !== "string" || v.timeZone.length === 0 || typeof v.generatedAt !== "string" || !Number.isFinite(Date.parse(v.generatedAt))) {
+      return null;
+    }
+    return v;
+  } catch {
+    return null;
+  }
+}
+function isFullDashboardDue(now = /* @__PURE__ */ new Date()) {
+  const p = paths();
+  if (!existsSync(p.fullDashboardFile)) return true;
+  try {
+    const fd = openSync(p.fullDashboardFile, "r");
+    try {
+      const head = Buffer.alloc(512);
+      const n = readSync(fd, head, 0, head.length, 0);
+      if (head.toString("utf8", 0, n).includes('name="cccn-placeholder"')) return true;
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return true;
+  }
+  const state = readState();
+  if (state === null) return true;
+  const expected = makeFullDashboardState(now);
+  if (state.timeZone !== expected.timeZone) return true;
+  if (state.localDate !== expected.localDate) return true;
+  if (state.localDate > expected.localDate) return true;
+  if (Date.parse(state.generatedAt) > now.getTime()) return true;
+  return false;
+}
+function writeFullDashboardStateAtomic(state) {
+  const file = paths().dashboardFullStateFile;
+  const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(state)}
+`, "utf8");
+    renameSync(tmp, file);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+}
+function invalidateCanonicalDashboards() {
+  const p = paths();
+  for (const file of [p.recentDashboardFile, p.fullDashboardFile, p.dashboardFullStateFile]) {
+    rmSync(file, { force: true });
+  }
+}
+
+// src/data-lock.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { hostname } from "os";
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync as readFileSync2,
+  renameSync as renameSync2,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
 import { join } from "path";
 var DATA_LOCK_LEASE_MS = 3e4;
 var HEARTBEAT_MS = 5e3;
@@ -22,7 +103,7 @@ function ownerFile(dir) {
 }
 function readOwner(dir) {
   try {
-    const v = JSON.parse(readFileSync(ownerFile(dir), "utf8"));
+    const v = JSON.parse(readFileSync2(ownerFile(dir), "utf8"));
     if (typeof v.token !== "string" || typeof v.pid !== "number" || typeof v.hostname !== "string" || typeof v.acquiredAt !== "string" || typeof v.heartbeatAt !== "string") return null;
     return v;
   } catch {
@@ -30,21 +111,21 @@ function readOwner(dir) {
   }
 }
 function writeOwner(dir, owner) {
-  const tmp = join(dir, `owner.${owner.token}.${randomUUID()}.tmp`);
+  const tmp = join(dir, `owner.${owner.token}.${randomUUID2()}.tmp`);
   try {
-    writeFileSync(tmp, `${JSON.stringify(owner)}
+    writeFileSync2(tmp, `${JSON.stringify(owner)}
 `, "utf8");
-    renameSync(tmp, ownerFile(dir));
+    renameSync2(tmp, ownerFile(dir));
   } finally {
-    rmSync(tmp, { force: true });
+    rmSync2(tmp, { force: true });
   }
 }
 function quarantineOwned(dir, token, label) {
   const before = readOwner(dir);
   if (before?.token !== token) return false;
-  const quarantine = `${dir}.${label}-${token}-${randomUUID()}`;
+  const quarantine = `${dir}.${label}-${token}-${randomUUID2()}`;
   try {
-    renameSync(dir, quarantine);
+    renameSync2(dir, quarantine);
   } catch {
     return false;
   }
@@ -52,21 +133,21 @@ function quarantineOwned(dir, token, label) {
   if (moved?.token !== token) {
     return false;
   }
-  rmSync(quarantine, { recursive: true, force: true });
+  rmSync2(quarantine, { recursive: true, force: true });
   return true;
 }
 function claimDir(fixed, label, now, metadataWriter = writeOwner) {
-  const token = randomUUID();
+  const token = randomUUID2();
   const staging = `${fixed}.${label}-${token}`;
   const iso = now.toISOString();
   const owner = { token, pid: process.pid, hostname: hostname(), acquiredAt: iso, heartbeatAt: iso };
   try {
     mkdirSync(staging);
     metadataWriter(staging, owner);
-    renameSync(staging, fixed);
+    renameSync2(staging, fixed);
     return { token, owner };
   } catch {
-    rmSync(staging, { recursive: true, force: true });
+    rmSync2(staging, { recursive: true, force: true });
     return null;
   }
 }
@@ -99,15 +180,15 @@ function tryReclaim(now, leaseMs) {
     if (!processDefinitelyDead(first.pid)) return false;
     const second = readOwner(p.dataLockDir);
     if (second === null || second.token !== first.token || second.heartbeatAt !== first.heartbeatAt) return false;
-    const orphan = `${p.dataLockDir}.orphan-${first.token}-${randomUUID()}`;
+    const orphan = `${p.dataLockDir}.orphan-${first.token}-${randomUUID2()}`;
     try {
-      renameSync(p.dataLockDir, orphan);
+      renameSync2(p.dataLockDir, orphan);
     } catch {
       return false;
     }
     const moved = readOwner(orphan);
     if (moved?.token !== first.token || moved.heartbeatAt !== first.heartbeatAt) return false;
-    rmSync(orphan, { recursive: true, force: true });
+    rmSync2(orphan, { recursive: true, force: true });
     return true;
   } finally {
     quarantineOwned(p.dataReclaimDir, guard.token, "released");
@@ -117,15 +198,15 @@ function acquireDataLock(opts = {}) {
   const now = opts.now ?? /* @__PURE__ */ new Date();
   const leaseMs = opts.leaseMs ?? DATA_LOCK_LEASE_MS;
   const p = paths();
-  if (existsSync(p.dataReclaimDir) && reclaimerGuardBlocks(now, leaseMs)) return null;
+  if (existsSync2(p.dataReclaimDir) && reclaimerGuardBlocks(now, leaseMs)) return null;
   let claim = claimDir(p.dataLockDir, "acquire", now, opts.metadataWriter);
   if (claim === null) {
     if (!tryReclaim(now, leaseMs)) return null;
-    if (existsSync(p.dataReclaimDir) && reclaimerGuardBlocks(now, leaseMs)) return null;
+    if (existsSync2(p.dataReclaimDir) && reclaimerGuardBlocks(now, leaseMs)) return null;
     claim = claimDir(p.dataLockDir, "acquire", now, opts.metadataWriter);
     if (claim === null) return null;
   }
-  if (existsSync(p.dataReclaimDir) && reclaimerGuardBlocks(now, leaseMs)) {
+  if (existsSync2(p.dataReclaimDir) && reclaimerGuardBlocks(now, leaseMs)) {
     quarantineOwned(p.dataLockDir, claim.token, "yielded");
     return null;
   }
@@ -168,5 +249,9 @@ async function waitForDataLock(timeoutMs, pollMs = 25) {
 }
 
 export {
+  makeFullDashboardState,
+  isFullDashboardDue,
+  writeFullDashboardStateAtomic,
+  invalidateCanonicalDashboards,
   waitForDataLock
 };