feat: ccreel のセッションを載せる拡張を、例として同梱する

README.en.md

@@ -10,6 +10,7 @@ Turns your local git repositories and their GitHub issues into static HTML, and
 - **All issues in one place too**: open issues from every repo in a single list
 - **Multiple GitHub accounts**: pull issues from separate accounts, such as personal and work, and keep them apart
 - **Light on a phone**: static HTML with no JavaScript, so it opens quickly while you're away
+- **Extensible**: a single Python module can add your own pages or an issue source. A bundled example shows Claude Code session history ([Extensions](#extensions))
 
 <p>
   <img src="docs/screenshots/issues.png" alt="Issues: open issues listed with Open and Draft badges" width="640">
@@ -106,6 +107,20 @@ An extension has only the functions it needs from the following.
 
 `ctx` holds the config, the scanned repositories, the output directories, the `[plugins.<name>]` table (`ctx.options`), and `ctx.read(repo, path)` to read a file at HEAD.
 
+### Example: show Claude Code sessions
+
+[`examples/plugins/sessions.py`](examples/plugins/sessions.py) reads Claude Code sessions from [ccreel](https://github.com/yktsnet/ccreel)'s `list --json` / `show --json` and adds a list page and a page per session. It needs `ccreel` on your `PATH`. Copy it next to `codeview.toml` and list it in the config to try it.
+
+```toml
+[plugins]
+modules = ["sessions"]
+
+[plugins.sessions]
+days = 14   # how far back to show (default 30)
+```
+
+A `sessions` entry appears in the left menu of the top page, and each session page links to its issue and repository. The available keys are described at the top of `sessions.py`.
+
 ## Publishing
 
 The generated files contain the code of every repository. **Keep the repository you publish from (the one holding `codeview.toml`) private, and never put the generated files anywhere public.**

README.md

@@ -10,6 +10,7 @@
 - **Issue も1か所にまとまる**: 全リポの未消化の Issue を1つの一覧にする
 - **GitHub の複数アカウントに対応**: 個人用と仕事用のように、別々のアカウントの Issue を分けて取り込める
 - **スマホで軽い**: JavaScript なしの静的 HTML なので、外出先でもすぐ開ける
+- **拡張でページを足せる**: Python のモジュール1つで、自前のページや Issue の取り込み元を足せる。実例として、Claude Code のセッション履歴を載せる拡張を同梱している（[Extensions](#extensions)）
 
 <p>
   <img src="docs/screenshots/issues.png" alt="Issue 一覧。未消化の Issue が Open と Draft のバッジ付きで並ぶ" width="640">
@@ -106,6 +107,20 @@ gh_config_dir = "~/.config/gh-work"   # 仕事のアカウントで gh auth logi
 
 `ctx` は設定・走査したリポの一覧・出力先・`[plugins.<名前>]` の表（`ctx.options`）・HEAD のファイルを読む `ctx.read(repo, path)` を持つ。
 
+### 例: Claude Code のセッションを載せる
+
+[`examples/plugins/sessions.py`](examples/plugins/sessions.py) は、[ccreel](https://github.com/yktsnet/ccreel) の `list --json` / `show --json` から Claude Code のセッションを読み、一覧と本文のページを足す拡張である。ccreel が `PATH` に要る。`codeview.toml` の隣へコピーして、設定に挙げれば試せる。
+
+```toml
+[plugins]
+modules = ["sessions"]
+
+[plugins.sessions]
+days = 14   # 載せる期間（既定 30）
+```
+
+トップの左メニューに `sessions` が加わり、セッションごとのページから Issue とリポへ飛べる。設定できるキーは `sessions.py` の先頭の説明にある。
+
 ## Publishing
 
 生成物には全リポのコードが入る。**配信するリポ（`codeview.toml` を置いたリポ）は private にし、生成物を公開の場所に置かない。**

context/structure.md

@@ -15,9 +15,13 @@ codeview/
   cloudflare.py  Cloudflare API と資格情報
   cf_setup.py    Pages プロジェクト・カスタムドメイン・Access を作る
   cf_status.py   Pages プロジェクトと直近のデプロイを表示する
+examples/
+  plugins/
+    sessions.py  拡張の実例。ccreel のセッションを一覧と本文のページにする（本体のパッケージには入らない）
 tests/
   conftest.py    見本のリポ群・設定・偽の gh を作るフィクスチャ
   test_*.py      build・issues・plugins・publish の外から見た振る舞い
+  test_example_sessions.py  例の拡張 sessions.py の振る舞い。偽の ccreel で確かめる
 ```
 
 ## データの流れ

docs/guarantees.md

@@ -139,6 +139,36 @@
 | 旧形式の状態 | `test_publish_if_changed_republishes_over_old_state` |
 | 間隔の値の検証 | `test_check_every_hours_must_be_positive_integer` |
 
+### 5. `tests/test_example_sessions.py` — 例の拡張 `examples/plugins/sessions.py`
+
+- `[plugins.sessions]` の `config_dirs` ごとに `ccreel list --json --limit 0 --since <days>d --config-dir <dir>` を呼び、全部をまとめて新しい順に `public/sessions/index.html` へ一覧を書く。各セッションの本文を `ccreel show <id> --json` から `public/sessions/<id>.html` に書く
+- 本文のページには発言と応答のテキストを出し、応答の Markdown は生の HTML・`<script>` を出さずに描く。`ccreel resume <id>` の行を出す
+- セッションの `issue` が一覧にある Issue を指せば、先頭の 0 を無視してその Issue のページへのリンクにする。`repo` が走査対象のリポならリポのページへリンクする。どちらも無ければリンクにしない
+- `show` に失敗したセッションも本文のページは作り、`Could not read this session` を出す。`ccreel` が無いとき、またはいずれかの config dir で `list` が失敗したときは、警告を出してそこを飛ばし、生成は止めない
+- トップの左メニューに `sessions` への入口と件数を出し、トップにセッションの題は出さない
+- `ccreel`・`config_dirs`・`days`・`every_hours` 以外のキーや、型の誤りは `error:` を出して非0で終わる
+- `fingerprint()` は最新の更新時刻を `every_hours` の枠に丸め、枠の中の更新では変わらない
+- 2回目の生成では、中身の変わらないセッションの `show` を呼ばずにページを使い回し、更新されたセッション・Issue の状態が変わったセッションは作り直す。一覧から消えたセッションのキャッシュは消す
+- 生成したページの `href` / `src` は、本体のページと同じく相対パスで、`public/` 内に実在する先を指す
+
+| 保証（要約） | 対応テスト |
+|---|---|
+| `list` の呼び出しと一覧、本文を `show` から書く | `test_list_and_session_pages`、`test_passes_config_dir_and_period`、`test_merges_config_dirs` |
+| 応答の Markdown は生の HTML を出さずに描く | `test_reply_markdown_is_safe` |
+| `ccreel resume` の行 | `test_list_and_session_pages` |
+| Issue（先頭の 0 を無視）とリポへのリンク | `test_links_to_issue_and_repo` |
+| 対応する先が無ければリンクにしない | `test_unlinked_when_issue_or_repo_is_missing` |
+| `show` に失敗したセッションのページ | `test_unreadable_session_still_gets_a_page` |
+| `list` の失敗・`ccreel` が無いときは警告して続ける | `test_build_survives_one_failing_config_dir`、`test_build_survives_missing_ccreel` |
+| トップの入口と件数 | `test_top_menu_links_sessions_without_titles` |
+| 設定の誤り | `test_rejects_bad_options` |
+| 指紋は最新の更新時刻を `every_hours` の枠に丸めて動く | `test_fingerprint_moves_only_across_windows`、`test_fingerprint_follows_every_hours` |
+| 変わらないセッションはページを使い回す（件数を左に出さないのは、セッションが1本増えても、ほかのページの内容が変わらないようにするため） | `test_second_build_reuses_unchanged_pages`、`test_session_page_side_has_no_counts` |
+| 更新されたセッションは作り直す | `test_updated_session_is_rebuilt` |
+| Issue の状態が変わったら作り直す | `test_issue_link_follows_issue_state` |
+| 一覧から消えたセッションのキャッシュを消す | `test_expired_sessions_leave_the_cache` |
+| リンクは相対パスで、実在するファイルを指す | `test_links_are_relative_and_resolve` |
+
 ## Gaps
 
 以下は保証すべきと思われるが、対応するテストが無い。
@@ -147,4 +177,4 @@
 
 ## About
 
-対象は `codeview` コマンド（`build` / `publish`）の外から見える振る舞い、`codeview.toml` の検証、拡張の口。`serve`・`cf-setup`・`cf-status` とページの見た目は対象外。**ここに載っていない振る舞いは約束ではなく、予告なく変わりうる。**
+対象は `codeview` コマンド（`build` / `publish`）の外から見える振る舞い、`codeview.toml` の検証、拡張の口、例の拡張 `examples/plugins/sessions.py`。`serve`・`cf-setup`・`cf-status` とページの見た目は対象外。**ここに載っていない振る舞いは約束ではなく、予告なく変わりうる。**