Add database maintenance commands

DEVELOPER_GUIDE.md

@@ -148,6 +148,8 @@ Scoped `--files` / `--commits` refreshes reuse the same path filter as full scan
 
 Incremental refreshes that mutate `fts_chunks` increment `codeindex_meta.fts_incremental_writes_since_optimize`. When the counter reaches `DbWriter.DefaultFtsOptimizeIncrementalWriteThreshold`, the update path runs `INSERT INTO fts_chunks(fts_chunks) VALUES('optimize')`, resets the counter, and stamps `fts_last_optimized_at`. Users can run the same maintenance directly with `cdidx optimize --db <path>` or `cdidx index <projectPath> --optimize`; this may briefly hold the writer lock on large indexes.
 
+Successful writer sessions attempt `PRAGMA wal_checkpoint(TRUNCATE)` before closing a writable `DbContext`, so large WAL files are reclaimed after index, backfill, optimize, prune, and other DB-writing commands. `cdidx db schema [--json]` dumps `sqlite_master` entries plus `PRAGMA user_version` for schema inspection, and `cdidx db prune --dry-run|--apply [--json]` counts or deletes orphaned `symbol_references`, `reference_lines`, and `symbols` rows before running `PRAGMA optimize` on apply.
+
 ### Extending the indexer
 
 Out-of-tree post-extraction hooks can implement `CodeIndex.Indexer.Hooks.IPostExtractionHook` in a `.dll` placed under `~/.config/cdidx/hooks/` (or the directory named by `CDIDX_HOOKS_DIR`). Hook assemblies are discovered in path order. Each concrete hook type is instantiated with a public parameterless constructor, then called after built-in symbol extraction and again after built-in reference extraction, before rows are persisted. Hooks receive a `FileContext` plus mutable `IList<SymbolRecord>` / `IList<ReferenceRecord>` values, so they can annotate extracted records, add synthetic symbols, or add domain-specific references.

README.md

@@ -376,7 +376,7 @@ upgrade / downgrade 後はインストール済み補完 script を再生成し
 | MCP 連携 | Claude Code、Cursor、Windsurf などの AI クライアント向け MCP server。tools、インデックス済みファイル resources、starter prompts、ローカル引数検証用の schema constraints、text content block の `mimeType`、logging、構造化された `ping` health result、HTTP `GET /healthz`、opt-in の HTTP `/events` keep-alive notification、stdio または HTTP `/events` stream 上の互換性用 server-side `notifications/initialized` ready signal、`cdidx languages` と同じ言語レジストリ由来の `Language support:` 説明を提供します。Tool schema は未知の引数を `-32602` で拒否し、`x-stability` を公開し、CLI JSON contract と一致する snake_case の structured JSON key を使います。 |
 | freshness | `--parallelism` による parallel full-scan、`--files` / `--commits` による差分更新、`--watch` による継続更新、`status --check` による完全一致確認、`--stale-after` / `CDIDX_STALE_AFTER` による age threshold 上書きに対応します。 |
 | storage | `.cdidx/codeindex.db` に保存する local-first 設計。ネストしたディレクトリからの query コマンドは、current directory にフォールバックする前に最上位祖先の `.cdidx/codeindex.db` を優先します。既定の SQLite 保存先は `--data-dir <dir>`、`CDIDX_DATA_DIR`、`XDG_DATA_HOME` で workspace 外へ移せます。明示的な `--db <path>` は引き続き最優先です。 |
-| DB maintenance | 新規 index DB は SQLite incremental auto-vacuum を使います。既存 DB は `cdidx vacuum` で free page を回収でき、legacy no-autovacuum DB は初回だけ full `VACUUM` で変換します。`status --json` は `db_pragma_settings` 配下に metrics を出力します。 |
+| DB maintenance | 新規 index DB は SQLite incremental auto-vacuum を使います。成功した writer 実行は WAL を `TRUNCATE` checkpoint します。既存 DB は `cdidx vacuum` で free page を回収でき、legacy no-autovacuum DB は初回だけ full `VACUUM` で変換します。`cdidx db schema` は on-disk schema を出力し、`cdidx db prune --dry-run|--apply` は orphaned DB rows を検査・削除します。`status --json` は `db_pragma_settings` 配下に metrics を出力します。 |
 | security defaults | POSIX では `.cdidx` を `0700` 権限で作成します。`status --json` は利用可能な場合に実効 POSIX mode を `data_dir_mode` として報告します。 |
 | diagnostics | `status --config` は source attribution 付きの effective configuration を出力し、`status --explain <field>` は readiness field の意味と対処を説明します。read 系コマンドは `--profile`、`--slow-query-ms <n>`、<code>--trace=stderr&#124;file&#124;none</code> に対応し、file trace は lifecycle log と同じ場所に日次 `query-trace-YYYYMMDD.jsonl` を書きます。 |
 | drift checks | `cdidx diff <db1> <db2>` は schema、file、symbol、reference の差分を比較します。exit code は `0` identical、`1` drift、`2` schema mismatch、`3` unreadable DB です。 |

changelog.d/unreleased/1644.fixed.md

@@ -0,0 +1,16 @@
+---
+category: fixed
+issues:
+  - 1644
+affected:
+  - src/CodeIndex/Database/DbContext.cs
+  - tests/CodeIndex.Tests/DatabaseTests.cs
+---
+
+## English
+
+- **Successful writer sessions now truncate-checkpoint the SQLite WAL (#1644)** — writable DB contexts attempt `PRAGMA wal_checkpoint(TRUNCATE)` after write work so large `codeindex.db-wal` sidecars are reclaimed after successful maintenance and index runs.
+
+## 日本語
+
+- **成功した writer session が SQLite WAL を truncate checkpoint するようになりました (#1644)** — 書き込みを行った DB context は `PRAGMA wal_checkpoint(TRUNCATE)` を試行し、成功した maintenance / index 実行後に肥大化した `codeindex.db-wal` sidecar を回収します。

changelog.d/unreleased/1646.added.md

@@ -0,0 +1,17 @@
+---
+category: added
+issues:
+  - 1646
+affected:
+  - src/CodeIndex/Cli/DbCommandRunner.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - tests/CodeIndex.Tests/DbCommandRunnerTests.cs
+---
+
+## English
+
+- **Added `cdidx db schema` for on-disk schema inspection (#1646)** — the new command prints SQLite schema entries and `PRAGMA user_version`, with `--json` for automation.
+
+## 日本語
+
+- **on-disk schema を確認する `cdidx db schema` を追加しました (#1646)** — 新しいコマンドは SQLite schema entries と `PRAGMA user_version` を出力し、自動化向けに `--json` も提供します。

changelog.d/unreleased/1728.added.md

@@ -0,0 +1,17 @@
+---
+category: added
+issues:
+  - 1728
+affected:
+  - src/CodeIndex/Cli/DbCommandRunner.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - tests/CodeIndex.Tests/DbCommandRunnerTests.cs
+---
+
+## English
+
+- **Added `cdidx db prune --dry-run|--apply` for stale DB rows (#1728)** — the command counts or deletes orphaned `symbol_references`, `reference_lines`, and `symbols` rows, then runs `PRAGMA optimize` after apply.
+
+## 日本語
+
+- **stale DB rows を処理する `cdidx db prune --dry-run|--apply` を追加しました (#1728)** — このコマンドは orphaned `symbol_references`、`reference_lines`、`symbols` rows を集計または削除し、apply 後に `PRAGMA optimize` を実行します。

src/CodeIndex/Cli/ConsoleUi.cs

@@ -85,7 +85,7 @@ private static readonly (string Command, string Usage)[] CommandUsageLines =
         ("workspace", "cdidx workspace <list|status|use|current> [name] [--json]"),
         ("config", "cdidx config show [--json]"),
         ("validate-config", "cdidx validate-config"),
-        ("db", "cdidx db --integrity-check [--db <path>] [--json]"),
+        ("db", "cdidx db --integrity-check|schema|prune [--dry-run|--apply] [--db <path>] [--json]"),
         ("diff", "cdidx diff <db1> <db2> [--json] [--summary-only] [--detailed] [--limit <n>]"),
         ("report", "cdidx report --output <path> [--db <path>] [--json] [--log-lines <n>] [--no-log] [--include-args]"),
         ("validate", "cdidx validate [--db <path>] [--json] [--verbose] [--kind <kind>] [--path <glob>]"),
@@ -768,6 +768,8 @@ private static void PrintCommandSummary()
         Console.WriteLine("  upgrade                    Check for and install the latest release via install.sh");
         Console.WriteLine("  validate-config            Validate .cdidx/config.json or .cdidxrc.json");
         Console.WriteLine("  db --integrity-check       Run SQLite `PRAGMA integrity_check` and report findings");
+        Console.WriteLine("  db schema                  Dump SQLite schema entries and PRAGMA user_version");
+        Console.WriteLine("  db prune --dry-run|--apply Count or delete orphaned DB rows");
         Console.WriteLine("  diff <db1> <db2>           Compare two index databases; exit 0 identical, 1 drift, 2 schema mismatch, 3 unreadable");
         Console.WriteLine("  report --output <path>     Build a redacted crash-repro tarball (.tgz) for bug reports");
         Console.WriteLine("  validate                   Report encoding issues (U+FFFD, BOM, null bytes, mixed line endings, UTF-16 BOM, likely non-UTF8)");