witan-code 0.8.1__tar.gz → 0.10.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. witan_code-0.10.0/CHANGELOG.md +394 -0
  2. {witan_code-0.8.1 → witan_code-0.10.0}/PKG-INFO +121 -11
  3. {witan_code-0.8.1 → witan_code-0.10.0}/README.md +119 -9
  4. witan_code-0.10.0/docs/BRANCH_INDEXING.md +337 -0
  5. {witan_code-0.8.1 → witan_code-0.10.0}/docs/CLI_REFERENCE.md +6 -2
  6. {witan_code-0.8.1 → witan_code-0.10.0}/docs/USER_GUIDE.md +18 -11
  7. {witan_code-0.8.1 → witan_code-0.10.0}/pyproject.toml +3 -3
  8. {witan_code-0.8.1 → witan_code-0.10.0}/tests/conftest.py +15 -0
  9. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_branches.py +239 -0
  10. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_cli_dispatch.py +52 -3
  11. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_config_targets.py +67 -0
  12. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_context.py +86 -3
  13. witan_code-0.10.0/tests/test_graph.py +124 -0
  14. witan_code-0.10.0/tests/test_identity.py +143 -0
  15. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_indexer_scope.py +230 -2
  16. witan_code-0.10.0/tests/test_ingest.py +220 -0
  17. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_maintenance.py +51 -3
  18. witan_code-0.10.0/tests/test_reaper.py +394 -0
  19. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_remote_proxy.py +1 -1
  20. witan_code-0.10.0/tests/test_remote_store.py +342 -0
  21. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_server.py +2 -1
  22. witan_code-0.10.0/tests/test_store.py +366 -0
  23. witan_code-0.10.0/tests/test_views.py +218 -0
  24. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/bridge.py +32 -14
  25. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/cli.py +228 -61
  26. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/config.py +159 -4
  27. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/context.py +65 -9
  28. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/extensions/pi/codegraph.ts +3 -2
  29. witan_code-0.10.0/witan_code/graph.py +248 -0
  30. witan_code-0.10.0/witan_code/identity.py +106 -0
  31. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/indexer.py +36 -14
  32. witan_code-0.10.0/witan_code/ingest.py +340 -0
  33. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries/code_read.gq +14 -0
  34. witan_code-0.10.0/witan_code/reaper.py +224 -0
  35. witan_code-0.10.0/witan_code/remote/store.py +264 -0
  36. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/server.py +252 -43
  37. witan_code-0.10.0/witan_code/store.py +618 -0
  38. witan_code-0.10.0/witan_code/views.py +177 -0
  39. witan_code-0.8.1/CHANGELOG.md +0 -214
  40. witan_code-0.8.1/docs/BRANCH_INDEXING.md +0 -123
  41. witan_code-0.8.1/tests/test_graph.py +0 -23
  42. witan_code-0.8.1/tests/test_store.py +0 -112
  43. witan_code-0.8.1/witan_code/graph.py +0 -99
  44. witan_code-0.8.1/witan_code/store.py +0 -202
  45. {witan_code-0.8.1 → witan_code-0.10.0}/.gitignore +0 -0
  46. {witan_code-0.8.1 → witan_code-0.10.0}/config/claude.json +0 -0
  47. {witan_code-0.8.1 → witan_code-0.10.0}/config/copilot.json +0 -0
  48. {witan_code-0.8.1 → witan_code-0.10.0}/config/pi.json +0 -0
  49. {witan_code-0.8.1 → witan_code-0.10.0}/docs/EDGE_PRECISION_TIERS.md +0 -0
  50. {witan_code-0.8.1 → witan_code-0.10.0}/docs/PACKAGE_MAP.md +0 -0
  51. {witan_code-0.8.1 → witan_code-0.10.0}/docs/STAGE2_STITCHING.md +0 -0
  52. {witan_code-0.8.1 → witan_code-0.10.0}/docs/SYMBOL_FORMAT.md +0 -0
  53. {witan_code-0.8.1 → witan_code-0.10.0}/docs/SYMBOL_TABLE.md +0 -0
  54. {witan_code-0.8.1 → witan_code-0.10.0}/install.sh +0 -0
  55. {witan_code-0.8.1 → witan_code-0.10.0}/tests/__init__.py +0 -0
  56. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_bridge.py +0 -0
  57. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_cli_hooks.py +0 -0
  58. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_cli_output_format.py +0 -0
  59. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_config.py +0 -0
  60. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_crossrepo.py +0 -0
  61. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_edges.py +0 -0
  62. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_elicit.py +0 -0
  63. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_enrichment.py +0 -0
  64. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_hooks.py +0 -0
  65. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_indexer.py +0 -0
  66. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_languages.py +0 -0
  67. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_package_map.py +0 -0
  68. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_repo.py +0 -0
  69. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_setup.py +0 -0
  70. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_stitch.py +0 -0
  71. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_symbol_table.py +0 -0
  72. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_tasks.py +0 -0
  73. {witan_code-0.8.1 → witan_code-0.10.0}/tests/test_visualize.py +0 -0
  74. {witan_code-0.8.1 → witan_code-0.10.0}/uv.lock +0 -0
  75. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/__init__.py +0 -0
  76. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/__main__.py +0 -0
  77. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/bridge_extractors.py +0 -0
  78. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/edges.py +0 -0
  79. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/elicit.py +0 -0
  80. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/hooks.py +0 -0
  81. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/maintenance.py +0 -0
  82. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/output.py +0 -0
  83. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/package_map.py +0 -0
  84. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries/bridge.gq +0 -0
  85. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries/code_mutations.gq +0 -0
  86. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries/delete.gq +0 -0
  87. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries_ts/bash.scm +0 -0
  88. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries_ts/hcl.scm +0 -0
  89. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries_ts/python.scm +0 -0
  90. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries_ts/sql.scm +0 -0
  91. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries_ts/typescript.scm +0 -0
  92. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/queries_ts/yaml.scm +0 -0
  93. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/remote/__init__.py +0 -0
  94. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/remote/oidc.py +0 -0
  95. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/remote/proxy.py +0 -0
  96. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/repo.py +0 -0
  97. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/schema/bridge-schema.pg +0 -0
  98. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/schema/code-schema.pg +0 -0
  99. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/setup.py +0 -0
  100. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/skills/witan-code/SKILL.md +0 -0
  101. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/stitch.py +0 -0
  102. {witan_code-0.8.1 → witan_code-0.10.0}/witan_code/visualize.py +0 -0
@@ -0,0 +1,394 @@
1
+ # Changelog
2
+
3
+ All notable changes to `witan-code` are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
7
+ a MINOR bump may include breaking changes).
8
+
9
+ ## [0.10.0] - 2026-08-01
10
+
11
+ ### Added
12
+
13
+ - **Index onto a cluster code graph from outside the cluster —
14
+ `code_transport = "mcp"` (ADR-0005 path c).** The omnigraph-server holding
15
+ the code graphs is ClusterIP-only and stays that way, so until now a
16
+ developer's checkout could reach it only through `kubectl port-forward`.
17
+ Set the transport (env `WITAN_CODE_TRANSPORT`) and every store operation
18
+ travels to the deployed witan MCP endpoint — the one exposed boundary —
19
+ which performs it against the cluster graph **as the caller**: it resolves
20
+ the actor from the validated JWT, looks up that actor's own omnigraph token,
21
+ and applies the branch-view ownership guard server-side. The client keeps
22
+ everything that needs a working tree; `indexer`/`bridge` are unchanged, and
23
+ `RemoteStoreClient` stands in for an `OmnigraphClient`. It holds one
24
+ connection open for the run rather than one per call, since an index is
25
+ thousands of store operations, and reconnects once on a dropped one.
26
+ Deliberate consequences: a write through this route can only target a view
27
+ the caller's own actor owns, and can never target the shared
28
+ default-branch view — that one's writer is the CI indexer, in-cluster over
29
+ `code_server`, which is unchanged. Compaction and view reaping refuse here
30
+ too; they belong to the cluster's own scheduled jobs.
31
+ - **`code_store_*` tools** — the server half of the above: `read`, `mutate`,
32
+ `load`, `open`, `views`, `graphs`, mirroring the store operations the write
33
+ path performs rather than modelling indexing itself, so indexing policy
34
+ stays with the client that has the checkout. Mediated, not arbitrary:
35
+ `query` may only name a query file bundled with the server, and the graph is
36
+ resolved from a repo URI against the server's own configuration. Registered
37
+ **only on a deployment** (`WITAN_OIDC_ISSUER` set; override with
38
+ `WITAN_CODE_STORE_TOOLS`) — a local stdio server writes its stores directly,
39
+ so serving them there would add six machine-facing tools to every agent's
40
+ tool list to serve a caller that cannot exist.
41
+
42
+ - **`witan-code reap-views` — a stale branch-view reaper for the shared graph.**
43
+ With per-writer views on one cluster graph, every developer's every git branch
44
+ gets a view and nothing ever removes one. This sweeps views nobody has written
45
+ in `WITAN_CODE_VIEW_MAX_IDLE_DAYS` (default 14; `0` disables). It is not
46
+ `branches --prune` with a wider scope: prune asks whether *this checkout* still
47
+ has the git branch, which is unanswerable about a store every user writes, and
48
+ it keeps refusing there. This asks the store's own commit log how long ago a
49
+ view was last written. `main` is never reaped (idle by design between merges),
50
+ and neither is a view with no commits of its own — it holds nothing that isn't
51
+ already on its fork point, and omnigraph records no branch-creation time to
52
+ age it by, so reaping it would race the indexer that just made it. Reports by
53
+ default; `--apply` deletes, and refuses on a shared graph unless
54
+ `WITAN_CODE_INDEX_ROLE=ci`. Unparseable `commit list` output raises rather
55
+ than reading as "never written" — `None` is what tells the reaper to leave a
56
+ view alone, so degrading a parse failure to it would turn an omnigraph output
57
+ change into a reaper that reports success forever while sprawl grows. A
58
+ disabled window (`0`) skips the per-view aging entirely instead of scanning
59
+ and discarding, and a graph that cannot be surveyed is reported and
60
+ non-zero-exited without stranding the other stores in the sweep. See
61
+ `docs/BRANCH_INDEXING.md` § Reaping stale views and witan `docs/adr/0006`.
62
+
63
+ ### Changed
64
+
65
+ - **`graph.check_writable` takes `is_remote: bool`, not a `client`.** It only
66
+ ever read that one bit off the client, and the MCP tier serving somebody
67
+ else's write has no client of its own to read it from — the answer there is
68
+ "shared, by construction", since that is the only reason the request exists.
69
+ Taking the bit lets both sides ask the same question.
70
+ - **Cedar can gate `main` vs WIP, but not view ownership** — corrected from
71
+ 0.9.0's claim that one rule could. omnigraph 0.8.1 compiles a bundle rule to a
72
+ bare `permit(...)` with no `when {}` clause, and its only branch predicate is
73
+ the three-valued protected/unprotected scope: there is no branch-name pattern
74
+ and no `principal.actor` to compare a prefix against. The `act-<sub>/` prefix
75
+ is therefore enforced by the client write guard alone. The policy bundle now
76
+ pins this gap with a deliberately-`allow` test case, so an omnigraph release
77
+ that closes it fails the build instead of passing unnoticed.
78
+
79
+ - **Requires `witan-core>=0.7`.** The mtime-stamped schema re-apply
80
+ (`_schema_apply` / `_schema_apply_if_changed` / `_schema_stamp` in
81
+ `witan_code/store.py`) moved up into `witan_core.omnigraph` as
82
+ `schema_apply` / `schema_apply_if_changed` / `schema_stamp_path`, so
83
+ witan-council can pick up additive schema changes on an existing store the
84
+ same way. No behavior change here — `ensure_store` and `ensure_bridge_store`
85
+ call the shared functions with the same arguments — but the floor moves,
86
+ because resolving witan-core 0.6 would now fail at import.
87
+
88
+ ## [0.9.0] - 2026-07-31
89
+
90
+ ### Added
91
+
92
+ - **Branch views are namespaced per writer, and the purge follows view
93
+ ownership.** A git branch is not a unique key for an index: two checkouts on
94
+ `feature-x` — two developers, one developer in two worktrees, an agent and
95
+ its human — are two working trees, and a view named for the branch alone
96
+ meant the second writer silently overwrote the first with a different
97
+ uncommitted state. A view is now named `[<actor>/]<branch>` on a per-repo
98
+ graph and `[<actor>/]<repo-slug>/<branch>` on the bridge, where `<actor>` is
99
+ the ADR-0004 `act-<sub>` id resolved from the `witan login` session (shared
100
+ derivation with the deployed server, `witan_core.identity`; never `$USER`,
101
+ which is not what the cluster's tokens and Cedar policies are written
102
+ against). Set `WITAN_ACTOR`, or `actor` on a `[targets.<name>]` block, for a
103
+ writer with no interactive login. The actor comes first in both schemes on
104
+ purpose: ownership is then a *prefix*, so one comparison, one reaper sweep,
105
+ and one Cedar rule cover both stores.
106
+
107
+ Isolation did not cost visibility, which is the whole reason branch views
108
+ live on the shared graph: `code_indexed_branches(branch=<git branch>)` (CLI:
109
+ `witan code branches --branch <b>`) lists every writer's view of a branch
110
+ with its owner, and any listed view name goes straight back as `branch=` to
111
+ `code_find_definition` / `code_search_symbol` / `code_symbols_in_file`.
112
+ Default reads follow the checkout's branch to *this* actor's view first,
113
+ then any other writer's, then `main`.
114
+
115
+ `graph.owns_view` is now the single predicate behind both `check_writable`
116
+ and `indexer._may_purge`, replacing two separate approximations of the same
117
+ question: a local store has one user who is its writer, CI owns the shared
118
+ default view, and every actor owns its own branch views. A developer may
119
+ therefore purge their own branch view again — under the old "remote and not
120
+ the designated writer" rule they could not, so files they had deleted
121
+ lingered in their own view. Writing a view owned by another actor, or an
122
+ un-owned branch view, is refused on a shared graph. Purely local use is
123
+ unchanged: no identity, no prefix, no migration, and no login needed to
124
+ index offline. `branches --prune` remains refused against a shared graph —
125
+ no client can tell whose views are live. See
126
+ [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md#per-writer-branch-views).
127
+
128
+ **Breaking (tool surface):** `code_indexed_branches` returns
129
+ `{repo, views: [{view, branch, actor}]}` instead of
130
+ `{repo, branches: [str]}`, and no longer lists `main` (the default view is
131
+ not an in-flight branch view).
132
+
133
+ - **`WITAN_CODE_INDEX_ROLE` — an explicit writer role for the shared
134
+ default-branch view.** On the deployed cluster a per-repo code graph is one
135
+ graph for the whole team, and its `main` view — the one every reader falls
136
+ back to — had no owner. It has one now: CI indexes the default branch,
137
+ everyone else reads it. Indexing a shared graph's default-branch view is
138
+ refused unless the process declares itself the writer
139
+ (`WITAN_CODE_INDEX_ROLE=ci`, or `index_role = "ci"` on a `[targets.<name>]`
140
+ block); an unrecognized value is an error rather than a silent demotion to
141
+ reader, which would freeze the shared view with nothing to explain it.
142
+ Authority is deliberately a **role, not a transport**: the CI indexer is
143
+ remote too, so the blanket "refuse writes when remote" that 0.8.1 shipped as
144
+ a down payment would have blocked the one writer the design depends on.
145
+ `_may_purge` now reads "not remote **or** designated writer" accordingly —
146
+ dropping rows for files deleted from the default branch is precisely CI's
147
+ job. Local stores are unaffected (one user, who is their writer), and branch
148
+ views stay writable by anyone: they are branch-scoped, so in-flight work
149
+ never lands on the shared view. That exemption is deliberate — per-user
150
+ branch views live *on* the shared graph, so isolated agents can see each
151
+ other's work as it happens. The two follow-ups that decision required
152
+ (namespacing views per writer, and re-scoping the purge to "this actor owns
153
+ the view being written") landed in the entry above. See
154
+ [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view).
155
+
156
+ ### Changed
157
+
158
+ - **The `inject-context` block now names a call instead of stating a
159
+ preference.** The old block ended with "prefer `code_search_symbol` /
160
+ `code_find_definition` / ... over grep", which measured badly: across 50
161
+ sessions in `agent-kit` that received it, the block was injected 248 times
162
+ and produced 5 `code_*` calls against 802 Grep/Read/Glob/Explore calls, with
163
+ 46 of the 50 sessions never calling a `code_*` tool at all. The cause is that
164
+ the `code_*` tools reach the agent **deferred** — name only, no schema, a
165
+ `ToolSearch` round-trip short of callable — in 50 of 50 of those sessions,
166
+ while Grep/Read/Glob are always loaded. Preferring a tool that is not in the
167
+ tool list is not an actionable instruction. The block now leads with the
168
+ `ToolSearch(query="+code_ find_definition callers impact")` that makes them
169
+ callable (the `+code_` form is used because `select:` needs the full
170
+ `mcp__<server>__` prefix, which depends on the user's MCP config), gives a
171
+ `code_find_definition` → `symbol_id` → `code_callers`/`code_impact` template
172
+ to fill in, reports how many *other* repos are indexed so an empty
173
+ `code_interface_*` result is not misread as "nothing consumes this", and
174
+ points at the `/witan-code` skill. Net cost is ~110 chars per prompt; a
175
+ regression test caps the whole block at 600.
176
+
177
+ ### Fixed
178
+
179
+ - **`branches --prune` no longer prunes a shared graph.** It deletes store
180
+ branches whose git branch is absent from *this machine's* refs — against a
181
+ graph shared by the team, "this checkout doesn't have that branch" and "that
182
+ branch is gone" are indistinguishable, so one user pruning would delete
183
+ another user's in-flight branch view. Now refused per-repo when the store is
184
+ remote, with the repo named. This is a **separate** check from the ADR-0005
185
+ guard added in 0.8.1: that one refuses `--prune` in remote MCP-*client* mode
186
+ (`WITAN_REMOTE_URL`), which is about where the read tools dispatch, whereas
187
+ cluster addressing is the data tier — either can be remote without the other.
188
+
189
+ ## [0.8.1] - 2026-07-31
190
+
191
+ ### Fixed
192
+
193
+ - **Nested checkouts are no longer indexed as part of the parent repo.** The
194
+ walk skipped `.git` *directories*, but a linked worktree or submodule marks
195
+ itself with a `.git` **file**, so `.claude/worktrees/<name>/` was descended
196
+ into and every file there was attributed to the parent repo — at a different
197
+ path, at whatever revision that worktree happened to be on. In this repo's
198
+ own store that was **732 of 990 indexed files (74%)**, spread across every
199
+ branch view. The practical damage was to `code_search_symbol` and friends:
200
+ a query returned the same function many times over with *different, older
201
+ signatures*, so reading the first hit gave a confidently wrong answer, and
202
+ `code_impact` inflated blast radius with callers that only exist on an
203
+ abandoned branch. Any subdirectory holding a `.git` entry is now skipped.
204
+ Indexing from *inside* a worktree is unaffected — only descending into one
205
+ from the parent is refused — so the hooks keep working on a branch.
206
+ - **A full-repo index now purges files the repo no longer has**, reported as
207
+ `purged=N`. Nothing removed a `CodeFile`/`Symbol` once written unless that
208
+ same file was re-indexed, so deletions leaked forever: this repo's store
209
+ still held `_detach.py` and its tests, moved out to `witan-core` several
210
+ releases ago. This is also what clears the worktree rows above — excluding a
211
+ path stops adding rows but cannot retract the ones already written, so
212
+ without it the fix would only have stopped the bleeding.
213
+
214
+ Purging never runs against a shared cluster graph (`is_remote`): there the
215
+ default branch is indexed by CI and everyone else gets a read-only view, so
216
+ one developer's working tree must not reconcile it for everybody. Inert
217
+ today — code stores are still local — and load-bearing once witan-code
218
+ addresses `--server`/`--graph`.
219
+
220
+ Membership is decided by the set of files just collected, **not** by whether
221
+ the file still exists on disk: a linked worktree's files are on disk and
222
+ still must go. Purging requires a confirmed git root and a full-repo target;
223
+ a subpath, a single file (the reindex hook), or a non-git directory never
224
+ purges — without a git root `base` falls back to the target directory, which
225
+ would make every stored path look stale.
226
+
227
+ ### Changed
228
+
229
+ - An unreadable directory now suppresses the purge for that run (and is
230
+ reported on stderr, counting toward `errors`). `os.walk` hands such a
231
+ directory to `onerror` and otherwise continues silently, so a subtree the
232
+ walk could not enter is indistinguishable from one that was deleted — which
233
+ would have taken its still-present files' rows with it. Indexing still
234
+ proceeds with whatever was readable; only the destructive half backs off.
235
+ - The file walk prunes as it goes (`os.walk`) instead of walking everything and
236
+ filtering afterwards, so `node_modules`/`.venv` subtrees are no longer
237
+ traversed in full. Collection order is now sorted, making a run reproducible.
238
+ - `code_reindex` returns a `purged` count alongside the existing counters.
239
+
240
+ ## [0.8.0] - 2026-07-31
241
+
242
+ ### Added
243
+
244
+ - **Remote MCP-client mode for the CLI (ADR-0005 parity).** With
245
+ `WITAN_REMOTE_URL` + `WITAN_OIDC_ISSUER` set (or `remote_url`/`oidc_*` on the
246
+ matched `[targets.<name>]` block), the read commands — `symbols`, `deps`,
247
+ `stitch`, `repos`, `branches` — dispatch over `streamable-http` to a deployed
248
+ witan service instead of this machine's stores, authenticated with a per-user
249
+ Keycloak JWT. Previously only witan-council's CLI could reach a deployment,
250
+ even though `witan serve` has always mounted this server's `code_*` tools onto
251
+ the same endpoint. Indexing and store maintenance stay local unconditionally:
252
+ they need the checkout and the store files on disk.
253
+ - **`witan-code login` / `logout` / `whoami`** — the OIDC device grant against
254
+ the configured deployment. The token cache and default client id are shared
255
+ with the `witan` CLI and keyed by `(issuer, client id)`, so a prior
256
+ `witan login` already covers witan-code and vice versa.
257
+ - **Four MCP tools** backing the commands above, so both the CLI and an agent
258
+ reach the same data: `code_repo_symbols` (a repo's contract surface — what it
259
+ exports, what it expects), `code_repo_dependencies` (the whole "repo A depends
260
+ on repo B" graph), `code_indexed_repos` and `code_indexed_branches` (coverage:
261
+ which repos and branch views exist, and how fresh).
262
+
263
+ ### Changed
264
+
265
+ - **The read commands route through the tool surface, not `OmnigraphClient`.**
266
+ The CLI and the MCP server used to be two disconnected implementations of the
267
+ same queries; the commands now dispatch through a `_srv()` indirection that is
268
+ the in-process server module locally and an MCP proxy remotely. Output is
269
+ unchanged in local mode.
270
+ - **Requires `witan-core>=0.6`** and pulls its `remote` extra — the shared
271
+ `RemoteConfig` and OIDC client stack live there. No new transitive weight:
272
+ `fastmcp` was already required and itself depends on `httpx2`.
273
+ - `witan-code branches --prune` refuses to run in remote mode (it deletes from
274
+ the local stores, comparing against this machine's git refs). Listing works
275
+ against a deployment.
276
+
277
+ ## [0.7.0] - 2026-07-30
278
+
279
+ ### Changed
280
+
281
+ - **Requires `witan-core>=0.5`** (was `>=0.2`) — the server now imports
282
+ `witan_core.caching` and `elicit.MRTRElicitationMiddleware`, neither of which
283
+ exists below that.
284
+ - **`code_reindex` is now async and no longer blocks the event loop.** It was a
285
+ plain `def`, so a multi-minute index stalled every other request on the server
286
+ for its whole run; the indexer now runs on a thread.
287
+ - **`tools/list` declares a cache directive** — `ttlMs=300000`,
288
+ `cacheScope=private`.
289
+ - **Elicitation works on the stateless protocol era again** — the index-now
290
+ confirms and the repo prompt had been silently returning their
291
+ non-interactive defaults on any MCP 2026-07-28 connection. See the
292
+ `witan-core` 0.5.0 entry.
293
+
294
+ ### Added
295
+
296
+ - **`code_reindex` accepts task-augmented execution** (`io.modelcontextprotocol/tasks`,
297
+ SEP-2663) via the new optional `witan-code[tasks]` extra: a client can take a
298
+ handle and poll rather than holding the tool call open for the whole rebuild.
299
+ Opt-in per call — a client that does not ask gets the same completed result as
300
+ before. Without the extra the tool stays synchronous; the extra is separate
301
+ because it pulls a Docket/Redis stack most installs never need, and because it
302
+ requires FastMCP 4 while this package still supports 3.4.x. Note that while
303
+ 4.0 is still a pre-release, `witan-code[tasks]` needs `--prerelease=allow`
304
+ under uv; the base package does not.
305
+
306
+ ## [0.6.0] - 2026-07-21
307
+
308
+ ### Fixed
309
+
310
+ - **`repo.detect(override=...)` and the `WITAN_REPO` env var now route
311
+ through `normalise`** (issue #142), same as an auto-detected git remote —
312
+ matching the fix in witan-council 0.6.0. Previously an explicitly-passed
313
+ `repo=` (or `WITAN_REPO`) was stored verbatim, bypassing
314
+ canonicalization. `graph_id` (the shared-cluster graph id) already
315
+ case-folded unconditionally and needs no change; a repo whose canonical
316
+ key changes case after this fix should be re-indexed (`witan-code
317
+ reindex`) so its per-repo store lands under the new key.
318
+ - Depends on `witan-core[cli]>=0.2,<1` (unchanged range; picks up 0.4.0's
319
+ repo-key case-fold in `normalise`, which this package's `repo.detect`
320
+ relies on).
321
+
322
+ ## [0.5.0] - 2026-07-20
323
+
324
+ ### Added
325
+
326
+ - `config.toml` + `[targets.<name>]` support (previously env-var only):
327
+ `WITAN_CONFIG` / `~/.config/witan/config.toml`, a global `code_dir`/
328
+ `author`, and named targets overriding `code_dir`/`author`, selected by
329
+ `WITAN_TARGET` env var, an explicit `load(target=...)`, or auto-detection
330
+ via `match_paths`/`match_repos`/`match_hosts`/`match_orgs` (same
331
+ precedence and file as witan — see `witan_core.target_config` and
332
+ `witan.config.load()`'s docstring). A target can carry witan's
333
+ `server`/`graph`/`token` alongside this server's `code_dir` under one
334
+ name; witan-code reads only the fields it knows. `Config` gained
335
+ `target_name`. `load()` now optionally takes a `target` argument (was
336
+ zero-argument only). New dependency: `pydantic>=2,<3`.
337
+
338
+ ### Changed
339
+
340
+ - Now depends on `witan-core[cli]>=0.2,<1` (unchanged range; picks up
341
+ 0.3.0, which adds the shared target-routing logic this release uses).
342
+
343
+ ## [0.4.0] - 2026-07-16
344
+
345
+ ### Added
346
+
347
+ - **`witan-code --output-format`**: `repos`, `symbols`, and `stitch` can now
348
+ render their table data as `json`, `toml`, or `yaml` in addition to the
349
+ default Rich table output. The same option is honored when mounted as
350
+ `witan --output-format … code …`.
351
+
352
+ ### Changed
353
+
354
+ - Adopted the shared `witan-core` package for the CLI scaffolding
355
+ (`make_app`/`report_install`/`resolve_author` + agent-name constants),
356
+ replacing the previously duplicated copies. No user-facing behavior change.
357
+ Now depends on `witan-core[cli]>=0.2,<1`.
358
+
359
+ ## [0.3.0] - 2026-07-10
360
+
361
+ ### Added
362
+
363
+ - **`witan-code --version`**: prints the installed package version,
364
+ appending a git short ref when installed editable (local workspace) or
365
+ directly from a VCS URL (`uvx --from git+...`), via the new
366
+ `agent_config_kit.resolve_version()` helper.
367
+
368
+ ### Changed
369
+
370
+ - `agent-config-kit` dependency bumped to `>=0.4,<1` (was `>=0.1,<1`) to
371
+ require the version that ships `resolve_version`, which backs the new
372
+ `--version` flag.
373
+
374
+ ## [0.2.1] - 2026-07-09
375
+
376
+ ### Fixed
377
+
378
+ - **Pinned `tree-sitter` to `0.25.x`**: `0.26.0` has a use-after-free in its
379
+ pyo3 `Node` binding that segfaults (exit 139) under the heavy
380
+ `.parent()`/`.children()` churn `_walk_defs` does on real-world-sized
381
+ files — deterministically on the 2nd-3rd parse in one process, so
382
+ `witan-code index` hard-crashed on any real repo. `0.25.0`-`0.25.2` are
383
+ crash-free with the same ABI-15 grammar wheels.
384
+
385
+ ## [0.2.0] - 2026-07-09
386
+
387
+ Initial PyPI release. `witan-code` is a tree-sitter-based code graph MCP
388
+ server (Layer 2): indexes a repo's symbols (functions, methods, classes,
389
+ modules) and their relationships, then exposes `code_search_symbol` /
390
+ `code_find_definition` / `code_find_references` / `code_callers` /
391
+ `code_impact` queries to the agent. Includes the Layer 2.5 cross-repo bridge,
392
+ linking SOA repos by shared `env_var`/`endpoint`/`package`/`service` contract
393
+ keys. Mounts standalone as `witan-code` or under `witan code …` when the
394
+ `witan` umbrella CLI is installed alongside it.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: witan-code
3
- Version: 0.8.1
3
+ Version: 0.10.0
4
4
  Summary: witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)
5
5
  Project-URL: Homepage, https://github.com/mitodl/agent-kit/tree/main/mcp/servers/witan-code
6
6
  Project-URL: Repository, https://github.com/mitodl/agent-kit
@@ -25,7 +25,7 @@ Requires-Dist: tree-sitter-sql<0.4,>=0.3
25
25
  Requires-Dist: tree-sitter-typescript<0.24,>=0.23
26
26
  Requires-Dist: tree-sitter-yaml<0.8,>=0.7
27
27
  Requires-Dist: tree-sitter<0.26,>=0.25
28
- Requires-Dist: witan-core[cli,remote]<1,>=0.6
28
+ Requires-Dist: witan-core[cli,remote]<1,>=0.7
29
29
  Provides-Extra: tasks
30
30
  Requires-Dist: fastmcp-tasks<5,>=4.0.0b1; extra == 'tasks'
31
31
  Description-Content-Type: text/markdown
@@ -333,10 +333,15 @@ symlink alternative:
333
333
 
334
334
  | Variable | Default | Purpose |
335
335
  |----------|---------|---------|
336
- | `WITAN_CODE_DIR` | `~/.local/share/witan/code` | directory of per-repo `<slug>.omni` stores |
336
+ | `WITAN_CODE_DIR` | `~/.local/share/witan/code` | directory of per-repo `<slug>.omni` stores. Unused when `WITAN_CODE_SERVER` is set |
337
+ | `WITAN_CODE_SERVER` | — | base URL of the deployed omnigraph-server holding the code graphs. Set, every code graph is a graph on that server (`--server <url> --graph code-<repo>`) instead of a local directory. Reachable from inside the cluster only — intended for CI/in-cluster indexers, not laptops. See [Shared cluster graphs](#shared-cluster-graphs) |
338
+ | `WITAN_CODE_TOKEN` | — | bearer token presented to `WITAN_CODE_SERVER`. Per-actor: the server resolves the writer from it |
339
+ | `WITAN_CODE_TRANSPORT` | `direct` | how a cluster code graph is reached. `mcp` writes through the deployed witan MCP endpoint (`WITAN_REMOTE_URL`) instead of addressing the omnigraph-server — the supported path from outside the cluster. See [Writing through the MCP tier](#writing-through-the-mcp-tier) |
337
340
  | `WITAN_AUTHOR` / `USER` | `unknown` | attribution string |
338
341
  | `WITAN_REPO` | — | override the detected repo slug |
339
342
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
343
+ | `WITAN_CODE_INDEX_ROLE` | `client` | `ci` designates this process the writer of a shared graph's default-branch view. Only meaningful against a shared cluster graph; local stores are unaffected. See [Branch indexing](docs/BRANCH_INDEXING.md#who-may-write-the-shared-default-branch-view) |
344
+ | `WITAN_ACTOR` | derived from the `witan login` session | the identity that owns the branch views this process writes; an `act-…` id or a raw OIDC `sub`. For a non-interactive writer (CI, a maintenance job). See [Branch indexing](docs/BRANCH_INDEXING.md#per-writer-branch-views) |
340
345
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
341
346
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
342
347
  | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
@@ -350,6 +355,95 @@ and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
350
355
  at `<dir>/_bridge.omni` and is created lazily on the first index that yields any
351
356
  bindings.
352
357
 
358
+ ### Shared cluster graphs
359
+
360
+ Set `code_server` (env `WITAN_CODE_SERVER`) and each repo's code graph is
361
+ instead a graph on the deployed omnigraph-server, addressed as `--server <url>
362
+ --graph <id>` with the id from `witan_code.config.graph_id()` — e.g.
363
+ `https://github.com/mitodl/ol-django` → `code-github-com-mitodl-ol-django`.
364
+ The bridge graph is the fixed `code-bridge`. That id function is a contract
365
+ shared byte-for-byte with ol-infrastructure's provisioning
366
+ (`applications/omnigraph/data_tier.py`), which is what *declares* the graphs
367
+ and applies their schema; this client never creates one, and indexing a repo
368
+ the cluster has no graph for fails immediately with the id it expected and the
369
+ ids the server actually serves.
370
+
371
+ This is the **data tier** and is independent of `remote_url`
372
+ ([Remote mode](#remote-mode)), which routes read *tools* through a deployed
373
+ witan MCP endpoint. Indexing needs a git checkout, so the indexer always runs
374
+ locally; `code_server` only changes where it writes. Either tier can be remote
375
+ without the other.
376
+
377
+ > **Who this is for.** `code_server` addresses the omnigraph-server
378
+ > *directly*, which only works from inside the cluster — the data tier is a
379
+ > ClusterIP service with no external route, while the witan MCP tier is the
380
+ > one that is publicly exposed. So:
381
+ >
382
+ > - **CI / in-cluster indexers** use `code_server` as documented here.
383
+ > - **Everyone else** sets `code_transport = "mcp"` and writes through the
384
+ > deployed witan endpoint — see below.
385
+ >
386
+ > Do not configure `code_server` on a laptop: it needs a `kubectl
387
+ > port-forward` and is not the supported path. Reads are unaffected either way.
388
+
389
+ ### Writing through the MCP tier
390
+
391
+ `code_transport = "mcp"` (env `WITAN_CODE_TRANSPORT`) makes the deployed witan
392
+ endpoint — the same `remote_url` the read commands already use — the address
393
+ of every code graph. It is the supported way to index onto the cluster from a
394
+ machine that is not in it:
395
+
396
+ ```toml
397
+ [targets.hosted]
398
+ remote_url = "https://witan.example.org/mcp"
399
+ oidc_issuer = "https://sso.example.org/realms/ol-platform-engineering"
400
+ code_transport = "mcp"
401
+ match_orgs = ["ol-platform-engineering"]
402
+ ```
403
+
404
+ Then `witan-code index` runs exactly as it always has — parsing your working
405
+ tree locally, because that is the part that needs a checkout — and its store
406
+ operations travel to the deployment, which performs them against the cluster
407
+ graph *as you*: it resolves your actor from the JWT `witan-code login`
408
+ obtained and looks up your own omnigraph token (ADR-0004). Nothing about
409
+ your local process decides who the write is attributed to.
410
+
411
+ Two consequences follow from that, and they are the point rather than
412
+ limitations:
413
+
414
+ - **You can only write views you own.** The deployment applies the same
415
+ ownership rule the client does (`[<actor>/]<branch>`, see
416
+ [Branch indexing](docs/BRANCH_INDEXING.md)) — but against the actor in your
417
+ token, so naming someone else's view is refused rather than honoured.
418
+ - **You cannot write the shared default-branch view through this path at
419
+ all.** Its single writer is the CI indexer, which runs in-cluster. Index a
420
+ non-default git branch, which is what a developer is doing anyway.
421
+
422
+ Store maintenance (`optimize`/`cleanup`) and stale-view reaping are refused
423
+ here too: they run inside the cluster against the storage root, not from
424
+ whichever machine indexed last.
425
+
426
+ Requires `remote_url` + `oidc_issuer` (a bare `code_transport = "mcp"` with no
427
+ endpoint is a configuration error, not a silent fall back to a local store).
428
+ The indexer holds one connection open for the run rather than one per store
429
+ operation; the per-prompt hook block, being a fresh process each time, pays a
430
+ connection and a round trip or two per prompt, and stays silent if the
431
+ deployment is unreachable or the login has expired.
432
+
433
+ Two things a cluster graph cannot answer, and doesn't pretend to:
434
+
435
+ - **Size and last-modified** are properties of a store directory. `witan-code
436
+ repos` and `code_indexed_repos` report `?`/null for both rather than a
437
+ plausible zero; `files` stays real, since it is a query.
438
+ - **Compaction.** `witan-code optimize`/`cleanup` refuse a cluster graph —
439
+ they are direct-storage commands, and compacting the shared storage root is
440
+ the cluster's own scheduled job, not every client's at the end of every
441
+ session.
442
+
443
+ Who may write which view on a shared graph is a separate question, answered by
444
+ `index_role` and the per-writer view naming — see
445
+ [Branch indexing](docs/BRANCH_INDEXING.md).
446
+
353
447
  ### config.toml
354
448
 
355
449
  witan-code reads the same `config.toml` as witan (witan-council) — a global
@@ -359,8 +453,9 @@ CLI `--target` flag yet), or auto-detection against the current
359
453
  repo/checkout (`match_paths` > `match_repos` > `match_hosts` > `match_orgs`
360
454
  — see witan's README/`witan/config.py` docstring for the full precedence).
361
455
  Because the file is shared, one target block can carry witan's
362
- `server`/`graph`/`token` alongside `code_dir` under
363
- the same name — each server reads only the fields it knows:
456
+ `server`/`graph`/`token` alongside witan-code's `code_dir` (or
457
+ `code_server`/`code_token`) under the same name — each server reads only the
458
+ fields it knows:
364
459
 
365
460
  ```toml
366
461
  [targets.work]
@@ -368,6 +463,14 @@ server = "http://witan.internal:8080" # witan (witan-council)
368
463
  code_dir = "/mnt/work/witan-code" # witan-code
369
464
  match_orgs = ["myorg"]
370
465
 
466
+ [targets.cluster]
467
+ # The shared data tier: code graphs live on the deployed omnigraph-server,
468
+ # one `code-<repo>` graph each. For a CI or in-cluster indexer — the server is
469
+ # not reachable from a laptop. See Shared cluster graphs.
470
+ code_server = "https://omnigraph.example.org"
471
+ code_token = "..."
472
+ match_orgs = ["ol-platform-engineering"]
473
+
371
474
  [targets.hosted]
372
475
  # remote_url/oidc_* route BOTH CLIs at one deployed endpoint — see Remote mode.
373
476
  remote_url = "https://witan.example.org/mcp"
@@ -416,7 +519,7 @@ graph):
416
519
  | Tool | Returns |
417
520
  |------|---------|
418
521
  | `code_indexed_repos()` | every indexed repo with file count, size, and last-indexed timestamp |
419
- | `code_indexed_branches()` | the omnigraph branches each repo's store carries |
522
+ | `code_indexed_branches(branch=None)` | the in-flight branch views each repo's store carries, and who owns each; pass a git branch to see every writer's view of it |
420
523
 
421
524
  ## CLI
422
525
 
@@ -427,10 +530,13 @@ graph):
427
530
  - `index [PATH]` — incremental; skips files whose content hash is unchanged.
428
531
  - `reindex [PATH]` — force rebuild a path.
429
532
  - `repos` — list all indexed repos with file count, symbol count, and store size.
430
- - `branches [--prune]` — list omnigraph branches per store; `--prune` deletes
431
- the current repo's store branches whose git branch is gone (plus
432
- `_detached`). Non-default git branches index onto same-named omnigraph
433
- branches so in-flight work never overwrites the shared `main` view — see
533
+ - `branches [--branch B] [--prune]` — list the in-flight branch views per
534
+ store; `--branch` shows every writer's view of one git branch (how you find
535
+ a teammate's WIP — pass a listed view name to a read command's `--branch`),
536
+ `--prune` deletes the current repo's views whose git branch is gone (plus
537
+ `_detached`). A non-default git branch indexes onto its own view, named for
538
+ its writer as well as the branch, so in-flight work neither overwrites the
539
+ shared `main` view nor another checkout of the same branch — see
434
540
  [docs/BRANCH_INDEXING.md](docs/BRANCH_INDEXING.md).
435
541
  - `deps [--kind K] [--repo SUBSTR] [--html PATH] [--open-browser]` —
436
542
  visualize cross-repo dependencies from the bridge store. Prints a Rich
@@ -559,7 +665,11 @@ A Pi equivalent of all four lives in one extension,
559
665
  - **`witan-code inject-context`** (`UserPromptSubmit`) — prints a short status
560
666
  block: whether the current repo is indexed (file count, last-updated time),
561
667
  or that a background index from `session-init` is still running (checking
562
- the same lock path above), plus a nudge to prefer `code_*` tools over grep.
668
+ the same lock path above), how many *other* repos are indexed (so the agent
669
+ can tell "no cross-repo consumers" from "no cross-repo data"), and the
670
+ `ToolSearch` call that makes the `code_*` tools callable when the harness
671
+ delivers them deferred — followed by a `code_find_definition` →
672
+ `code_callers`/`code_impact` call template.
563
673
  Independent of `witan`'s own `inject-context` hook (no cross-package
564
674
  coupling) — register it alone for a witan-code-only install. Prints
565
675
  nothing when the repo has neither a store nor an index in flight.