witan-code 0.7.0__tar.gz → 0.8.1__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 (87) hide show
  1. {witan_code-0.7.0 → witan_code-0.8.1}/CHANGELOG.md +88 -0
  2. {witan_code-0.7.0 → witan_code-0.8.1}/PKG-INFO +91 -2
  3. {witan_code-0.7.0 → witan_code-0.8.1}/README.md +89 -0
  4. {witan_code-0.7.0 → witan_code-0.8.1}/docs/CLI_REFERENCE.md +57 -0
  5. {witan_code-0.7.0 → witan_code-0.8.1}/pyproject.toml +7 -3
  6. witan_code-0.8.1/tests/test_cli_dispatch.py +248 -0
  7. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_cli_output_format.py +17 -13
  8. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_config_targets.py +66 -1
  9. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_context.py +13 -11
  10. witan_code-0.8.1/tests/test_indexer_scope.py +296 -0
  11. witan_code-0.8.1/tests/test_remote_proxy.py +168 -0
  12. witan_code-0.8.1/tests/test_server.py +147 -0
  13. witan_code-0.8.1/tests/test_store.py +112 -0
  14. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_visualize.py +22 -0
  15. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/bridge.py +19 -9
  16. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/cli.py +250 -175
  17. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/config.py +51 -13
  18. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/context.py +8 -5
  19. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/indexer.py +146 -19
  20. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries/code_read.gq +14 -0
  21. witan_code-0.8.1/witan_code/remote/__init__.py +12 -0
  22. witan_code-0.8.1/witan_code/remote/oidc.py +80 -0
  23. witan_code-0.8.1/witan_code/remote/proxy.py +59 -0
  24. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/server.py +139 -8
  25. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/skills/witan-code/SKILL.md +10 -0
  26. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/store.py +86 -0
  27. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/visualize.py +38 -0
  28. witan_code-0.7.0/tests/test_server.py +0 -73
  29. {witan_code-0.7.0 → witan_code-0.8.1}/.gitignore +0 -0
  30. {witan_code-0.7.0 → witan_code-0.8.1}/config/claude.json +0 -0
  31. {witan_code-0.7.0 → witan_code-0.8.1}/config/copilot.json +0 -0
  32. {witan_code-0.7.0 → witan_code-0.8.1}/config/pi.json +0 -0
  33. {witan_code-0.7.0 → witan_code-0.8.1}/docs/BRANCH_INDEXING.md +0 -0
  34. {witan_code-0.7.0 → witan_code-0.8.1}/docs/EDGE_PRECISION_TIERS.md +0 -0
  35. {witan_code-0.7.0 → witan_code-0.8.1}/docs/PACKAGE_MAP.md +0 -0
  36. {witan_code-0.7.0 → witan_code-0.8.1}/docs/STAGE2_STITCHING.md +0 -0
  37. {witan_code-0.7.0 → witan_code-0.8.1}/docs/SYMBOL_FORMAT.md +0 -0
  38. {witan_code-0.7.0 → witan_code-0.8.1}/docs/SYMBOL_TABLE.md +0 -0
  39. {witan_code-0.7.0 → witan_code-0.8.1}/docs/USER_GUIDE.md +0 -0
  40. {witan_code-0.7.0 → witan_code-0.8.1}/install.sh +0 -0
  41. {witan_code-0.7.0 → witan_code-0.8.1}/tests/__init__.py +0 -0
  42. {witan_code-0.7.0 → witan_code-0.8.1}/tests/conftest.py +0 -0
  43. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_branches.py +0 -0
  44. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_bridge.py +0 -0
  45. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_cli_hooks.py +0 -0
  46. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_config.py +0 -0
  47. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_crossrepo.py +0 -0
  48. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_edges.py +0 -0
  49. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_elicit.py +0 -0
  50. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_enrichment.py +0 -0
  51. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_graph.py +0 -0
  52. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_hooks.py +0 -0
  53. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_indexer.py +0 -0
  54. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_languages.py +0 -0
  55. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_maintenance.py +0 -0
  56. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_package_map.py +0 -0
  57. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_repo.py +0 -0
  58. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_setup.py +0 -0
  59. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_stitch.py +0 -0
  60. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_symbol_table.py +0 -0
  61. {witan_code-0.7.0 → witan_code-0.8.1}/tests/test_tasks.py +0 -0
  62. {witan_code-0.7.0 → witan_code-0.8.1}/uv.lock +0 -0
  63. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/__init__.py +0 -0
  64. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/__main__.py +0 -0
  65. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/bridge_extractors.py +0 -0
  66. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/edges.py +0 -0
  67. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/elicit.py +0 -0
  68. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/extensions/pi/codegraph.ts +0 -0
  69. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/graph.py +0 -0
  70. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/hooks.py +0 -0
  71. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/maintenance.py +0 -0
  72. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/output.py +0 -0
  73. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/package_map.py +0 -0
  74. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries/bridge.gq +0 -0
  75. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries/code_mutations.gq +0 -0
  76. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries/delete.gq +0 -0
  77. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries_ts/bash.scm +0 -0
  78. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries_ts/hcl.scm +0 -0
  79. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries_ts/python.scm +0 -0
  80. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries_ts/sql.scm +0 -0
  81. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries_ts/typescript.scm +0 -0
  82. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/queries_ts/yaml.scm +0 -0
  83. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/repo.py +0 -0
  84. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/schema/bridge-schema.pg +0 -0
  85. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/schema/code-schema.pg +0 -0
  86. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/setup.py +0 -0
  87. {witan_code-0.7.0 → witan_code-0.8.1}/witan_code/stitch.py +0 -0
@@ -6,6 +6,94 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/) (pre-1.0:
7
7
  a MINOR bump may include breaking changes).
8
8
 
9
+ ## [0.8.1] - 2026-07-31
10
+
11
+ ### Fixed
12
+
13
+ - **Nested checkouts are no longer indexed as part of the parent repo.** The
14
+ walk skipped `.git` *directories*, but a linked worktree or submodule marks
15
+ itself with a `.git` **file**, so `.claude/worktrees/<name>/` was descended
16
+ into and every file there was attributed to the parent repo — at a different
17
+ path, at whatever revision that worktree happened to be on. In this repo's
18
+ own store that was **732 of 990 indexed files (74%)**, spread across every
19
+ branch view. The practical damage was to `code_search_symbol` and friends:
20
+ a query returned the same function many times over with *different, older
21
+ signatures*, so reading the first hit gave a confidently wrong answer, and
22
+ `code_impact` inflated blast radius with callers that only exist on an
23
+ abandoned branch. Any subdirectory holding a `.git` entry is now skipped.
24
+ Indexing from *inside* a worktree is unaffected — only descending into one
25
+ from the parent is refused — so the hooks keep working on a branch.
26
+ - **A full-repo index now purges files the repo no longer has**, reported as
27
+ `purged=N`. Nothing removed a `CodeFile`/`Symbol` once written unless that
28
+ same file was re-indexed, so deletions leaked forever: this repo's store
29
+ still held `_detach.py` and its tests, moved out to `witan-core` several
30
+ releases ago. This is also what clears the worktree rows above — excluding a
31
+ path stops adding rows but cannot retract the ones already written, so
32
+ without it the fix would only have stopped the bleeding.
33
+
34
+ Purging never runs against a shared cluster graph (`is_remote`): there the
35
+ default branch is indexed by CI and everyone else gets a read-only view, so
36
+ one developer's working tree must not reconcile it for everybody. Inert
37
+ today — code stores are still local — and load-bearing once witan-code
38
+ addresses `--server`/`--graph`.
39
+
40
+ Membership is decided by the set of files just collected, **not** by whether
41
+ the file still exists on disk: a linked worktree's files are on disk and
42
+ still must go. Purging requires a confirmed git root and a full-repo target;
43
+ a subpath, a single file (the reindex hook), or a non-git directory never
44
+ purges — without a git root `base` falls back to the target directory, which
45
+ would make every stored path look stale.
46
+
47
+ ### Changed
48
+
49
+ - An unreadable directory now suppresses the purge for that run (and is
50
+ reported on stderr, counting toward `errors`). `os.walk` hands such a
51
+ directory to `onerror` and otherwise continues silently, so a subtree the
52
+ walk could not enter is indistinguishable from one that was deleted — which
53
+ would have taken its still-present files' rows with it. Indexing still
54
+ proceeds with whatever was readable; only the destructive half backs off.
55
+ - The file walk prunes as it goes (`os.walk`) instead of walking everything and
56
+ filtering afterwards, so `node_modules`/`.venv` subtrees are no longer
57
+ traversed in full. Collection order is now sorted, making a run reproducible.
58
+ - `code_reindex` returns a `purged` count alongside the existing counters.
59
+
60
+ ## [0.8.0] - 2026-07-31
61
+
62
+ ### Added
63
+
64
+ - **Remote MCP-client mode for the CLI (ADR-0005 parity).** With
65
+ `WITAN_REMOTE_URL` + `WITAN_OIDC_ISSUER` set (or `remote_url`/`oidc_*` on the
66
+ matched `[targets.<name>]` block), the read commands — `symbols`, `deps`,
67
+ `stitch`, `repos`, `branches` — dispatch over `streamable-http` to a deployed
68
+ witan service instead of this machine's stores, authenticated with a per-user
69
+ Keycloak JWT. Previously only witan-council's CLI could reach a deployment,
70
+ even though `witan serve` has always mounted this server's `code_*` tools onto
71
+ the same endpoint. Indexing and store maintenance stay local unconditionally:
72
+ they need the checkout and the store files on disk.
73
+ - **`witan-code login` / `logout` / `whoami`** — the OIDC device grant against
74
+ the configured deployment. The token cache and default client id are shared
75
+ with the `witan` CLI and keyed by `(issuer, client id)`, so a prior
76
+ `witan login` already covers witan-code and vice versa.
77
+ - **Four MCP tools** backing the commands above, so both the CLI and an agent
78
+ reach the same data: `code_repo_symbols` (a repo's contract surface — what it
79
+ exports, what it expects), `code_repo_dependencies` (the whole "repo A depends
80
+ on repo B" graph), `code_indexed_repos` and `code_indexed_branches` (coverage:
81
+ which repos and branch views exist, and how fresh).
82
+
83
+ ### Changed
84
+
85
+ - **The read commands route through the tool surface, not `OmnigraphClient`.**
86
+ The CLI and the MCP server used to be two disconnected implementations of the
87
+ same queries; the commands now dispatch through a `_srv()` indirection that is
88
+ the in-process server module locally and an MCP proxy remotely. Output is
89
+ unchanged in local mode.
90
+ - **Requires `witan-core>=0.6`** and pulls its `remote` extra — the shared
91
+ `RemoteConfig` and OIDC client stack live there. No new transitive weight:
92
+ `fastmcp` was already required and itself depends on `httpx2`.
93
+ - `witan-code branches --prune` refuses to run in remote mode (it deletes from
94
+ the local stores, comparing against this machine's git refs). Listing works
95
+ against a deployment.
96
+
9
97
  ## [0.7.0] - 2026-07-30
10
98
 
11
99
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: witan-code
3
- Version: 0.7.0
3
+ Version: 0.8.1
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]<1,>=0.5
28
+ Requires-Dist: witan-core[cli,remote]<1,>=0.6
29
29
  Provides-Extra: tasks
30
30
  Requires-Dist: fastmcp-tasks<5,>=4.0.0b1; extra == 'tasks'
31
31
  Description-Content-Type: text/markdown
@@ -339,6 +339,11 @@ symlink alternative:
339
339
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
340
340
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
341
341
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
342
+ | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
343
+ | `WITAN_OIDC_ISSUER` | — | Keycloak realm `witan-code login` authenticates against. Required whenever `WITAN_REMOTE_URL` is set |
344
+ | `WITAN_OIDC_CLIENT_ID` | `witan-cli` | public OIDC client id for the device grant. Shared with witan on purpose — see [Remote mode](#remote-mode) |
345
+ | `WITAN_OIDC_AUDIENCE` | — | audience/resource to request, matching the deployment's expected `aud` claim |
346
+ | `WITAN_TOKEN_CACHE` | `~/.config/witan/tokens.json` | where the 0600 token cache lives (shared with witan) |
342
347
 
343
348
  The store URI for a repo is `<dir>/<sanitized-slug>.omni`, where the slug's `/`
344
349
  and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
@@ -362,6 +367,12 @@ the same name — each server reads only the fields it knows:
362
367
  server = "http://witan.internal:8080" # witan (witan-council)
363
368
  code_dir = "/mnt/work/witan-code" # witan-code
364
369
  match_orgs = ["myorg"]
370
+
371
+ [targets.hosted]
372
+ # remote_url/oidc_* route BOTH CLIs at one deployed endpoint — see Remote mode.
373
+ remote_url = "https://witan.example.org/mcp"
374
+ oidc_issuer = "https://sso.example.org/realms/ol-platform-engineering"
375
+ match_orgs = ["ol-platform-engineering"]
365
376
  ```
366
377
 
367
378
  Environment variables always win over `config.toml`.
@@ -394,6 +405,18 @@ that repo's bridge branch overlay instead of `main` — see
394
405
  | `code_interface_consumers(kind, key)` | repos that **consume** it (`endpoint` keys are normalized from raw paths) |
395
406
  | `code_cross_repo_impact(symbol_id)` | the symbol's own bindings + every binding for those same contracts in **other** repos |
396
407
  | `code_interface_search(query, kind=None)` | BM25 search over interface bindings by normalized key |
408
+ | `code_precise_edges(repo=None)` | Stage-2 cross-repo edges resolved by canonical symbol string |
409
+ | `code_unresolved_symbols(repo=None)` | external references with no precise match (indexing-coverage gaps) |
410
+ | `code_repo_symbols(repo=None, role=None, scheme=None)` | a repo's symbol table — what it exports, what it expects |
411
+ | `code_repo_dependencies(kind=None, repo=None)` | the whole "repo A depends on repo B" graph (`{repos, edges}`) |
412
+
413
+ Coverage tools (which stores exist at all — read the store directory, not the
414
+ graph):
415
+
416
+ | Tool | Returns |
417
+ |------|---------|
418
+ | `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 |
397
420
 
398
421
  ## CLI
399
422
 
@@ -437,10 +460,47 @@ that repo's bridge branch overlay instead of `main` — see
437
460
  - `checkpoint` — opportunistically compact the current repo's store and the
438
461
  bridge store if due (see [Hooks](#hooks)); registered as the `Stop` hook,
439
462
  not usually run by hand.
463
+ - `login` / `logout` / `whoami` — authenticate to a deployed witan service
464
+ (see [Remote mode](#remote-mode)); no-ops with nothing configured.
440
465
 
441
466
  Both print a summary: files scanned/indexed/skipped, symbols, edges, errors. A
442
467
  parse failure on one file logs to stderr and continues.
443
468
 
469
+ ## Remote mode
470
+
471
+ The deployed witan service mounts this server's `code_*` tools into its own
472
+ FastMCP server with no prefix (`witan serve`), so one endpoint serves both tool
473
+ surfaces. Point the CLI at it and the **read** commands query the deployment's
474
+ code graphs instead of this machine's stores — witan-council's ADR-0005 path a,
475
+ same mechanism ([`docs/adr/0005`](../witan/docs/adr/0005-secure-cli-path-into-deployed-witan.md)):
476
+
477
+ ```bash
478
+ export WITAN_REMOTE_URL=https://witan.example.org/mcp
479
+ export WITAN_OIDC_ISSUER=https://sso.example.org/realms/ol-platform-engineering
480
+ witan-code login # OIDC device grant; approve in a browser
481
+ witan-code repos # now answers about the deployment's stores
482
+ ```
483
+
484
+ Or put `remote_url`/`oidc_issuer`/`oidc_client_id`/`oidc_audience` on a
485
+ `[targets.<name>]` block, alongside that target's `code_dir` — the same four
486
+ keys witan reads, so one block routes both CLIs.
487
+
488
+ Which commands move:
489
+
490
+ | Local **and** remote | Local only |
491
+ |---|---|
492
+ | `symbols`, `deps`, `stitch`, `repos`, `branches` | `index`, `reindex`, `optimize`, `cleanup`, `checkpoint`, `branches --prune`, the four hooks |
493
+
494
+ Indexing and store maintenance need the git checkout and the store files on
495
+ disk, so they always run against this machine and ignore `WITAN_REMOTE_URL`
496
+ entirely.
497
+
498
+ The token cache (`~/.config/witan/tokens.json`) and the default client id
499
+ (`witan-cli`) are shared with the `witan` CLI, and cache entries are keyed by
500
+ `(issuer, client id)` — so **one login covers both**. If you have already run
501
+ `witan login` against the same deployment, `witan-code login` is unnecessary;
502
+ conversely `witan-code logout` also logs `witan` out.
503
+
444
504
  ## Store compaction
445
505
 
446
506
  Every `load()`/`mutate()` call (indexing) appends a new tiny Lance fragment +
@@ -513,9 +573,38 @@ Manual install: register the bare commands directly under the matching event
513
573
  in `settings.json` (see the linked README for the exact JSON) — there are no
514
574
  scripts to symlink.
515
575
 
576
+ ## What gets indexed
577
+
578
+ The walk skips the usual noise directories (`.git`, `node_modules`, `.venv`,
579
+ `__pycache__`, `dist`, `build`, the various caches) and — importantly — does
580
+ not descend into a **nested checkout**: any subdirectory containing a `.git`
581
+ entry belongs to a different repository. That covers linked worktrees
582
+ (`.claude/worktrees/<name>/`, where `.git` is a *file*, not a directory),
583
+ submodules, and plain clones dropped inside the tree. Their files are that
584
+ repo's; indexing them here would attribute them to this one and leave the
585
+ store serving stale copies of itself under a second set of paths.
586
+
587
+ Indexing *from inside* a worktree still works normally — only descending into
588
+ one from the parent is refused — so the hooks keep indexing while an agent
589
+ works on a branch.
590
+
516
591
  ## Incremental indexing
517
592
 
518
593
  Each `CodeFile` stores a sha256 `contentHash`. On reindex, if the hash is
519
594
  unchanged the file is skipped. Otherwise its `Symbol`s and `CodeFile` are
520
595
  deleted (as separate `delete.gq` calls — Omnigraph cannot mix deletes with
521
596
  inserts in one query) and then re-parsed and re-inserted.
597
+
598
+ A **full-repo** index additionally purges rows for files the repo no longer
599
+ has — deleted, or newly excluded by the rules above. Membership is decided by
600
+ the set of files just collected, not by whether the file still exists on disk:
601
+ a linked worktree's files are very much on disk, they simply aren't this
602
+ repo's. The count is reported as `purged=N` when non-zero. Purging requires a
603
+ confirmed git root; indexing a subpath, a single file (the reindex hook), a
604
+ directory that isn't a git checkout, or a directory the walk could not fully
605
+ read never purges.
606
+
607
+ Nor does a **shared cluster graph** (`is_remote`). There the default branch is
608
+ indexed by CI and everyone else reads it — reconciling it against one
609
+ developer's working tree (a sparse checkout, a stale one, uncommitted
610
+ deletions) would purge files for every other user of that graph.
@@ -307,6 +307,11 @@ symlink alternative:
307
307
  | `WITAN_CODE_OPTIMIZE_INTERVAL` | `86400` (daily) | throttle window (seconds) for `checkpoint`'s opportunistic store compaction; `0` disables it |
308
308
  | `WITAN_CONFIG` | `~/.config/witan/config.toml` | config file path (see below) |
309
309
  | `WITAN_TARGET` | — | force a named `[targets.<name>]` block instead of auto-detecting one |
310
+ | `WITAN_REMOTE_URL` | — | a deployed witan MCP endpoint; routes the read commands through it (see [Remote mode](#remote-mode)) |
311
+ | `WITAN_OIDC_ISSUER` | — | Keycloak realm `witan-code login` authenticates against. Required whenever `WITAN_REMOTE_URL` is set |
312
+ | `WITAN_OIDC_CLIENT_ID` | `witan-cli` | public OIDC client id for the device grant. Shared with witan on purpose — see [Remote mode](#remote-mode) |
313
+ | `WITAN_OIDC_AUDIENCE` | — | audience/resource to request, matching the deployment's expected `aud` claim |
314
+ | `WITAN_TOKEN_CACHE` | `~/.config/witan/tokens.json` | where the 0600 token cache lives (shared with witan) |
310
315
 
311
316
  The store URI for a repo is `<dir>/<sanitized-slug>.omni`, where the slug's `/`
312
317
  and `:` are replaced with `_`. The shared cross-repo bridge lives alongside them
@@ -330,6 +335,12 @@ the same name — each server reads only the fields it knows:
330
335
  server = "http://witan.internal:8080" # witan (witan-council)
331
336
  code_dir = "/mnt/work/witan-code" # witan-code
332
337
  match_orgs = ["myorg"]
338
+
339
+ [targets.hosted]
340
+ # remote_url/oidc_* route BOTH CLIs at one deployed endpoint — see Remote mode.
341
+ remote_url = "https://witan.example.org/mcp"
342
+ oidc_issuer = "https://sso.example.org/realms/ol-platform-engineering"
343
+ match_orgs = ["ol-platform-engineering"]
333
344
  ```
334
345
 
335
346
  Environment variables always win over `config.toml`.
@@ -362,6 +373,18 @@ that repo's bridge branch overlay instead of `main` — see
362
373
  | `code_interface_consumers(kind, key)` | repos that **consume** it (`endpoint` keys are normalized from raw paths) |
363
374
  | `code_cross_repo_impact(symbol_id)` | the symbol's own bindings + every binding for those same contracts in **other** repos |
364
375
  | `code_interface_search(query, kind=None)` | BM25 search over interface bindings by normalized key |
376
+ | `code_precise_edges(repo=None)` | Stage-2 cross-repo edges resolved by canonical symbol string |
377
+ | `code_unresolved_symbols(repo=None)` | external references with no precise match (indexing-coverage gaps) |
378
+ | `code_repo_symbols(repo=None, role=None, scheme=None)` | a repo's symbol table — what it exports, what it expects |
379
+ | `code_repo_dependencies(kind=None, repo=None)` | the whole "repo A depends on repo B" graph (`{repos, edges}`) |
380
+
381
+ Coverage tools (which stores exist at all — read the store directory, not the
382
+ graph):
383
+
384
+ | Tool | Returns |
385
+ |------|---------|
386
+ | `code_indexed_repos()` | every indexed repo with file count, size, and last-indexed timestamp |
387
+ | `code_indexed_branches()` | the omnigraph branches each repo's store carries |
365
388
 
366
389
  ## CLI
367
390
 
@@ -405,10 +428,47 @@ that repo's bridge branch overlay instead of `main` — see
405
428
  - `checkpoint` — opportunistically compact the current repo's store and the
406
429
  bridge store if due (see [Hooks](#hooks)); registered as the `Stop` hook,
407
430
  not usually run by hand.
431
+ - `login` / `logout` / `whoami` — authenticate to a deployed witan service
432
+ (see [Remote mode](#remote-mode)); no-ops with nothing configured.
408
433
 
409
434
  Both print a summary: files scanned/indexed/skipped, symbols, edges, errors. A
410
435
  parse failure on one file logs to stderr and continues.
411
436
 
437
+ ## Remote mode
438
+
439
+ The deployed witan service mounts this server's `code_*` tools into its own
440
+ FastMCP server with no prefix (`witan serve`), so one endpoint serves both tool
441
+ surfaces. Point the CLI at it and the **read** commands query the deployment's
442
+ code graphs instead of this machine's stores — witan-council's ADR-0005 path a,
443
+ same mechanism ([`docs/adr/0005`](../witan/docs/adr/0005-secure-cli-path-into-deployed-witan.md)):
444
+
445
+ ```bash
446
+ export WITAN_REMOTE_URL=https://witan.example.org/mcp
447
+ export WITAN_OIDC_ISSUER=https://sso.example.org/realms/ol-platform-engineering
448
+ witan-code login # OIDC device grant; approve in a browser
449
+ witan-code repos # now answers about the deployment's stores
450
+ ```
451
+
452
+ Or put `remote_url`/`oidc_issuer`/`oidc_client_id`/`oidc_audience` on a
453
+ `[targets.<name>]` block, alongside that target's `code_dir` — the same four
454
+ keys witan reads, so one block routes both CLIs.
455
+
456
+ Which commands move:
457
+
458
+ | Local **and** remote | Local only |
459
+ |---|---|
460
+ | `symbols`, `deps`, `stitch`, `repos`, `branches` | `index`, `reindex`, `optimize`, `cleanup`, `checkpoint`, `branches --prune`, the four hooks |
461
+
462
+ Indexing and store maintenance need the git checkout and the store files on
463
+ disk, so they always run against this machine and ignore `WITAN_REMOTE_URL`
464
+ entirely.
465
+
466
+ The token cache (`~/.config/witan/tokens.json`) and the default client id
467
+ (`witan-cli`) are shared with the `witan` CLI, and cache entries are keyed by
468
+ `(issuer, client id)` — so **one login covers both**. If you have already run
469
+ `witan login` against the same deployment, `witan-code login` is unnecessary;
470
+ conversely `witan-code logout` also logs `witan` out.
471
+
412
472
  ## Store compaction
413
473
 
414
474
  Every `load()`/`mutate()` call (indexing) appends a new tiny Lance fragment +
@@ -481,9 +541,38 @@ Manual install: register the bare commands directly under the matching event
481
541
  in `settings.json` (see the linked README for the exact JSON) — there are no
482
542
  scripts to symlink.
483
543
 
544
+ ## What gets indexed
545
+
546
+ The walk skips the usual noise directories (`.git`, `node_modules`, `.venv`,
547
+ `__pycache__`, `dist`, `build`, the various caches) and — importantly — does
548
+ not descend into a **nested checkout**: any subdirectory containing a `.git`
549
+ entry belongs to a different repository. That covers linked worktrees
550
+ (`.claude/worktrees/<name>/`, where `.git` is a *file*, not a directory),
551
+ submodules, and plain clones dropped inside the tree. Their files are that
552
+ repo's; indexing them here would attribute them to this one and leave the
553
+ store serving stale copies of itself under a second set of paths.
554
+
555
+ Indexing *from inside* a worktree still works normally — only descending into
556
+ one from the parent is refused — so the hooks keep indexing while an agent
557
+ works on a branch.
558
+
484
559
  ## Incremental indexing
485
560
 
486
561
  Each `CodeFile` stores a sha256 `contentHash`. On reindex, if the hash is
487
562
  unchanged the file is skipped. Otherwise its `Symbol`s and `CodeFile` are
488
563
  deleted (as separate `delete.gq` calls — Omnigraph cannot mix deletes with
489
564
  inserts in one query) and then re-parsed and re-inserted.
565
+
566
+ A **full-repo** index additionally purges rows for files the repo no longer
567
+ has — deleted, or newly excluded by the rules above. Membership is decided by
568
+ the set of files just collected, not by whether the file still exists on disk:
569
+ a linked worktree's files are very much on disk, they simply aren't this
570
+ repo's. The count is reported as `purged=N` when non-zero. Purging requires a
571
+ confirmed git root; indexing a subpath, a single file (the reindex hook), a
572
+ directory that isn't a git checkout, or a directory the walk could not fully
573
+ read never purges.
574
+
575
+ Nor does a **shared cluster graph** (`is_remote`). There the default branch is
576
+ indexed by CI and everyone else reads it — reconciling it against one
577
+ developer's working tree (a sparse checkout, a stale one, uncommitted
578
+ deletions) would purge files for every other user of that graph.
@@ -18,6 +18,18 @@ mounted under the umbrella CLI, e.g. `witan --output-format json code repos`.
18
18
  Boolean flags follow cyclopts' `--flag`/`--no-flag` convention; both forms are
19
19
  always available even where only `--flag` is shown below.
20
20
 
21
+ ## Local vs. remote
22
+
23
+ The read commands — `symbols`, `deps`, `stitch`, `repos`, `branches` — dispatch
24
+ through the same `code_*` tool surface the MCP server exposes, so setting
25
+ `WITAN_REMOTE_URL` (plus `WITAN_OIDC_ISSUER`) points them at a deployed witan
26
+ service instead of this machine's stores. See
27
+ [Remote mode](../README.md#remote-mode) and `login`/`logout`/`whoami` below.
28
+
29
+ Everything else operates on the checkout and the store files on disk — `index`,
30
+ `reindex`, `optimize`, `cleanup`, `checkpoint`, `branches --prune`, and the
31
+ hook commands — and always runs locally regardless of `WITAN_REMOTE_URL`.
32
+
21
33
  ## `index [PATH]`
22
34
 
23
35
  Incrementally index `PATH` (file or directory). Files whose content hash is
@@ -157,3 +169,48 @@ re-running after an omnigraph version bump refreshes the binary.
157
169
  witan-code setup
158
170
  witan-code setup --dry-run
159
171
  ```
172
+
173
+ ## `login`
174
+
175
+ Authenticate to the deployed witan service named by `WITAN_REMOTE_URL` +
176
+ `WITAN_OIDC_ISSUER` (or the matched `[targets.<name>]` block) via the OIDC
177
+ device-authorization grant. Prints a verification URL and a user code; approve
178
+ it in a browser and the resulting token is cached at
179
+ `~/.config/witan/tokens.json` (mode 0600) and refreshed automatically.
180
+
181
+ Exits 1 with an explanation when no remote is configured.
182
+
183
+ No parameters.
184
+
185
+ ```bash
186
+ witan-code login
187
+ ```
188
+
189
+ The cache is shared with the `witan` CLI and keyed by `(issuer, client id)`, so
190
+ a prior `witan login` against the same deployment already covers witan-code —
191
+ and this command covers `witan` in turn.
192
+
193
+ ## `logout`
194
+
195
+ Forget the cached token for the configured deployment. Shared cache, so this
196
+ logs the `witan` CLI out as well.
197
+
198
+ No parameters.
199
+
200
+ ```bash
201
+ witan-code logout
202
+ ```
203
+
204
+ ## `whoami`
205
+
206
+ Show the identity the CLI presents to the deployed service: the matched target
207
+ (if any), endpoint, username, email, `sub`, and token expiry. Claims are
208
+ decoded for display only — the CLI never verifies the JWT; the deployment does.
209
+
210
+ Exits 1 when there is no valid cached token (run `witan-code login`).
211
+
212
+ No parameters.
213
+
214
+ ```bash
215
+ witan-code whoami
216
+ ```
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "witan-code"
3
- version = "0.7.0"
3
+ version = "0.8.1"
4
4
  description = "witan-code — tree-sitter code graph + cross-repo bridge (mounts under `witan code`)"
5
5
  readme = "README.md"
6
6
  license = "BSD-3-Clause"
@@ -11,7 +11,11 @@ classifiers = [
11
11
  ]
12
12
  dependencies = [
13
13
  "agent-config-kit>=0.4,<1",
14
- "witan-core[cli]>=0.5,<1",
14
+ # `remote`: the ADR-0005 client stack (OIDC device grant + MCP-client
15
+ # proxy) behind `witan-code login` and the read commands' remote mode.
16
+ # Costs nothing extra in practice — fastmcp is already required here and
17
+ # itself depends on httpx2, the extra's only other dependency.
18
+ "witan-core[cli,remote]>=0.6,<1",
15
19
  "fastmcp>=3.4.2,<5",
16
20
  "cyclopts>=4,<5",
17
21
  # [targets.<name>] override models (config.py) — also transitively pulled
@@ -86,7 +90,7 @@ testpaths = ["tests"]
86
90
  packages = ["witan_code"]
87
91
 
88
92
  [tool.bumpversion]
89
- current_version = "0.7.0"
93
+ current_version = "0.8.1"
90
94
  allow_dirty = true
91
95
 
92
96
  [[tool.bumpversion.files]]