witan-code 0.7.0__tar.gz → 0.8.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.
- {witan_code-0.7.0 → witan_code-0.8.0}/CHANGELOG.md +37 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/PKG-INFO +62 -2
- {witan_code-0.7.0 → witan_code-0.8.0}/README.md +60 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/CLI_REFERENCE.md +57 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/pyproject.toml +7 -3
- witan_code-0.8.0/tests/test_cli_dispatch.py +248 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_cli_output_format.py +17 -13
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_config_targets.py +66 -1
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_context.py +13 -11
- witan_code-0.8.0/tests/test_remote_proxy.py +168 -0
- witan_code-0.8.0/tests/test_server.py +147 -0
- witan_code-0.8.0/tests/test_store.py +112 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_visualize.py +22 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/cli.py +247 -175
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/config.py +51 -13
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/context.py +8 -5
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries/code_read.gq +14 -0
- witan_code-0.8.0/witan_code/remote/__init__.py +12 -0
- witan_code-0.8.0/witan_code/remote/oidc.py +80 -0
- witan_code-0.8.0/witan_code/remote/proxy.py +59 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/server.py +138 -8
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/skills/witan-code/SKILL.md +10 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/store.py +86 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/visualize.py +38 -0
- witan_code-0.7.0/tests/test_server.py +0 -73
- {witan_code-0.7.0 → witan_code-0.8.0}/.gitignore +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/config/claude.json +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/config/copilot.json +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/config/pi.json +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/BRANCH_INDEXING.md +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/EDGE_PRECISION_TIERS.md +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/PACKAGE_MAP.md +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/STAGE2_STITCHING.md +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/SYMBOL_FORMAT.md +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/SYMBOL_TABLE.md +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/docs/USER_GUIDE.md +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/install.sh +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/__init__.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/conftest.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_branches.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_bridge.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_cli_hooks.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_config.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_crossrepo.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_edges.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_elicit.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_enrichment.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_graph.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_hooks.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_indexer.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_languages.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_maintenance.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_package_map.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_repo.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_setup.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_stitch.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_symbol_table.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/tests/test_tasks.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/uv.lock +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/__init__.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/__main__.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/bridge.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/bridge_extractors.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/edges.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/elicit.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/extensions/pi/codegraph.ts +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/graph.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/hooks.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/indexer.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/maintenance.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/output.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/package_map.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries/bridge.gq +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries/code_mutations.gq +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries/delete.gq +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries_ts/bash.scm +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries_ts/hcl.scm +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries_ts/python.scm +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries_ts/sql.scm +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries_ts/typescript.scm +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/queries_ts/yaml.scm +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/repo.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/schema/bridge-schema.pg +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/schema/code-schema.pg +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/setup.py +0 -0
- {witan_code-0.7.0 → witan_code-0.8.0}/witan_code/stitch.py +0 -0
|
@@ -6,6 +6,43 @@ 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.0] - 2026-07-31
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- **Remote MCP-client mode for the CLI (ADR-0005 parity).** With
|
|
14
|
+
`WITAN_REMOTE_URL` + `WITAN_OIDC_ISSUER` set (or `remote_url`/`oidc_*` on the
|
|
15
|
+
matched `[targets.<name>]` block), the read commands — `symbols`, `deps`,
|
|
16
|
+
`stitch`, `repos`, `branches` — dispatch over `streamable-http` to a deployed
|
|
17
|
+
witan service instead of this machine's stores, authenticated with a per-user
|
|
18
|
+
Keycloak JWT. Previously only witan-council's CLI could reach a deployment,
|
|
19
|
+
even though `witan serve` has always mounted this server's `code_*` tools onto
|
|
20
|
+
the same endpoint. Indexing and store maintenance stay local unconditionally:
|
|
21
|
+
they need the checkout and the store files on disk.
|
|
22
|
+
- **`witan-code login` / `logout` / `whoami`** — the OIDC device grant against
|
|
23
|
+
the configured deployment. The token cache and default client id are shared
|
|
24
|
+
with the `witan` CLI and keyed by `(issuer, client id)`, so a prior
|
|
25
|
+
`witan login` already covers witan-code and vice versa.
|
|
26
|
+
- **Four MCP tools** backing the commands above, so both the CLI and an agent
|
|
27
|
+
reach the same data: `code_repo_symbols` (a repo's contract surface — what it
|
|
28
|
+
exports, what it expects), `code_repo_dependencies` (the whole "repo A depends
|
|
29
|
+
on repo B" graph), `code_indexed_repos` and `code_indexed_branches` (coverage:
|
|
30
|
+
which repos and branch views exist, and how fresh).
|
|
31
|
+
|
|
32
|
+
### Changed
|
|
33
|
+
|
|
34
|
+
- **The read commands route through the tool surface, not `OmnigraphClient`.**
|
|
35
|
+
The CLI and the MCP server used to be two disconnected implementations of the
|
|
36
|
+
same queries; the commands now dispatch through a `_srv()` indirection that is
|
|
37
|
+
the in-process server module locally and an MCP proxy remotely. Output is
|
|
38
|
+
unchanged in local mode.
|
|
39
|
+
- **Requires `witan-core>=0.6`** and pulls its `remote` extra — the shared
|
|
40
|
+
`RemoteConfig` and OIDC client stack live there. No new transitive weight:
|
|
41
|
+
`fastmcp` was already required and itself depends on `httpx2`.
|
|
42
|
+
- `witan-code branches --prune` refuses to run in remote mode (it deletes from
|
|
43
|
+
the local stores, comparing against this machine's git refs). Listing works
|
|
44
|
+
against a deployment.
|
|
45
|
+
|
|
9
46
|
## [0.7.0] - 2026-07-30
|
|
10
47
|
|
|
11
48
|
### Changed
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: witan-code
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8.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]<1,>=0.
|
|
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 +
|
|
@@ -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 +
|
|
@@ -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.
|
|
3
|
+
version = "0.8.0"
|
|
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
|
-
|
|
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.
|
|
93
|
+
current_version = "0.8.0"
|
|
90
94
|
allow_dirty = true
|
|
91
95
|
|
|
92
96
|
[[tool.bumpversion.files]]
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
"""Every read command goes through ``_srv()``, never straight to a store.
|
|
2
|
+
|
|
3
|
+
That indirection is what gives the CLI a remote mode (ADR 0005, path a): if a
|
|
4
|
+
command reaches for ``OmnigraphClient`` itself it silently loses it, and only
|
|
5
|
+
works against the local ``~/.local/share/witan/code`` stores. These tests stub
|
|
6
|
+
``_srv()`` and make constructing an ``OmnigraphClient`` an error, so a
|
|
7
|
+
regression here fails loudly instead of quietly going local-only.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from types import SimpleNamespace
|
|
13
|
+
|
|
14
|
+
import pytest
|
|
15
|
+
|
|
16
|
+
from witan_code import cli as cli_module
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@pytest.fixture(autouse=True)
|
|
20
|
+
def _no_direct_store_access(monkeypatch):
|
|
21
|
+
from witan_code import graph
|
|
22
|
+
|
|
23
|
+
def _boom(*_args, **_kwargs):
|
|
24
|
+
raise AssertionError(
|
|
25
|
+
"read command built an OmnigraphClient directly — it must dispatch "
|
|
26
|
+
"through _srv() so remote mode keeps working"
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
monkeypatch.setattr(graph, "OmnigraphClient", _boom)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _stub(**tools):
|
|
33
|
+
"""A stand-in for the tool provider that records the calls it receives."""
|
|
34
|
+
calls: list[tuple[str, dict]] = []
|
|
35
|
+
|
|
36
|
+
def _record(name, result):
|
|
37
|
+
def _call(**kwargs):
|
|
38
|
+
calls.append((name, kwargs))
|
|
39
|
+
return result
|
|
40
|
+
|
|
41
|
+
return _call
|
|
42
|
+
|
|
43
|
+
srv = SimpleNamespace(**{n: _record(n, r) for n, r in tools.items()})
|
|
44
|
+
srv.calls = calls # type: ignore[attr-defined]
|
|
45
|
+
return srv
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def test_symbols_dispatches_to_code_repo_symbols(monkeypatch, capsys):
|
|
49
|
+
srv = _stub(
|
|
50
|
+
code_repo_symbols=[
|
|
51
|
+
{
|
|
52
|
+
"role": "exported",
|
|
53
|
+
"symbol": "env:API_URL",
|
|
54
|
+
"kind": "env_var",
|
|
55
|
+
"n_refs": 2,
|
|
56
|
+
"confidence": 0.9,
|
|
57
|
+
"file": "app/settings.py",
|
|
58
|
+
"line": 12,
|
|
59
|
+
}
|
|
60
|
+
]
|
|
61
|
+
)
|
|
62
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
63
|
+
|
|
64
|
+
cli_module.symbols(repo="https://github.com/test/repo", role="exported")
|
|
65
|
+
|
|
66
|
+
assert srv.calls == [
|
|
67
|
+
(
|
|
68
|
+
"code_repo_symbols",
|
|
69
|
+
{
|
|
70
|
+
"repo": "https://github.com/test/repo",
|
|
71
|
+
"role": "exported",
|
|
72
|
+
"scheme": None,
|
|
73
|
+
},
|
|
74
|
+
)
|
|
75
|
+
]
|
|
76
|
+
out = capsys.readouterr().out
|
|
77
|
+
assert "API_URL" in out
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def test_symbols_resolves_the_repo_client_side(monkeypatch):
|
|
81
|
+
"""The deployment has no checkout, so detection has to happen here."""
|
|
82
|
+
srv = _stub(code_repo_symbols=[])
|
|
83
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
84
|
+
monkeypatch.setattr(
|
|
85
|
+
"witan_code.repo.detect", lambda *a, **kw: "https://github.com/test/detected"
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
cli_module.symbols()
|
|
89
|
+
|
|
90
|
+
assert srv.calls[0][1]["repo"] == "https://github.com/test/detected"
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def test_stitch_dispatches_to_precise_edges(monkeypatch, capsys):
|
|
94
|
+
srv = _stub(
|
|
95
|
+
code_precise_edges=[
|
|
96
|
+
{
|
|
97
|
+
"consumer_repo": "https://github.com/test/a",
|
|
98
|
+
"provider_repo": "https://github.com/test/b",
|
|
99
|
+
"kind": "package",
|
|
100
|
+
"match_count": 2,
|
|
101
|
+
"preferred": True,
|
|
102
|
+
"ambiguous_version": False,
|
|
103
|
+
}
|
|
104
|
+
]
|
|
105
|
+
)
|
|
106
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
107
|
+
|
|
108
|
+
cli_module.stitch()
|
|
109
|
+
|
|
110
|
+
assert srv.calls == [("code_precise_edges", {"repo": None})]
|
|
111
|
+
assert "test/a" in capsys.readouterr().out
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def test_stitch_unresolved_dispatches_to_unresolved_symbols(monkeypatch, capsys):
|
|
115
|
+
srv = _stub(
|
|
116
|
+
code_unresolved_symbols=[
|
|
117
|
+
{
|
|
118
|
+
"repo": "https://github.com/test/a",
|
|
119
|
+
"symbol": "pkg:npm/left-pad",
|
|
120
|
+
"kind": "package",
|
|
121
|
+
"n_refs": 1,
|
|
122
|
+
}
|
|
123
|
+
]
|
|
124
|
+
)
|
|
125
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
126
|
+
|
|
127
|
+
cli_module.stitch(repo="https://github.com/test/a", unresolved=True)
|
|
128
|
+
|
|
129
|
+
assert srv.calls == [
|
|
130
|
+
("code_unresolved_symbols", {"repo": "https://github.com/test/a"})
|
|
131
|
+
]
|
|
132
|
+
assert "left-pad" in capsys.readouterr().out
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def test_deps_dispatches_to_repo_dependencies(monkeypatch, capsys):
|
|
136
|
+
srv = _stub(
|
|
137
|
+
code_repo_dependencies={
|
|
138
|
+
"repos": ["https://github.com/test/a", "https://github.com/test/b"],
|
|
139
|
+
"edges": [
|
|
140
|
+
{
|
|
141
|
+
"consumer": "https://github.com/test/a",
|
|
142
|
+
"provider": "https://github.com/test/b",
|
|
143
|
+
"weight": 3,
|
|
144
|
+
"kinds": {"env_var": 3},
|
|
145
|
+
"contracts": [
|
|
146
|
+
{"kind": "env_var", "key": "API_URL", "confidence": 1.0}
|
|
147
|
+
],
|
|
148
|
+
}
|
|
149
|
+
],
|
|
150
|
+
}
|
|
151
|
+
)
|
|
152
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
153
|
+
|
|
154
|
+
cli_module.deps(kind="env_var")
|
|
155
|
+
|
|
156
|
+
assert srv.calls == [
|
|
157
|
+
(
|
|
158
|
+
"code_repo_dependencies",
|
|
159
|
+
{"kind": "env_var", "repo": None, "min_precision": "heuristic"},
|
|
160
|
+
)
|
|
161
|
+
]
|
|
162
|
+
out = capsys.readouterr().out
|
|
163
|
+
assert "test/a" in out and "test/b" in out
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def test_deps_renders_html_from_the_returned_graph(monkeypatch, tmp_path):
|
|
167
|
+
srv = _stub(
|
|
168
|
+
code_repo_dependencies={
|
|
169
|
+
"repos": ["https://github.com/test/a", "https://github.com/test/b"],
|
|
170
|
+
"edges": [
|
|
171
|
+
{
|
|
172
|
+
"consumer": "https://github.com/test/a",
|
|
173
|
+
"provider": "https://github.com/test/b",
|
|
174
|
+
"weight": 1,
|
|
175
|
+
"kinds": {"package": 1},
|
|
176
|
+
"contracts": [{"kind": "package", "key": "left-pad"}],
|
|
177
|
+
}
|
|
178
|
+
],
|
|
179
|
+
}
|
|
180
|
+
)
|
|
181
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
182
|
+
out = tmp_path / "graph.html"
|
|
183
|
+
|
|
184
|
+
cli_module.deps(html=out)
|
|
185
|
+
|
|
186
|
+
html = out.read_text()
|
|
187
|
+
assert "test/a" in html and "left-pad" in html
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def test_repos_dispatches_to_indexed_repos(monkeypatch, capsys):
|
|
191
|
+
srv = _stub(
|
|
192
|
+
code_indexed_repos=[
|
|
193
|
+
{
|
|
194
|
+
"repo": "https://github.com/test/a",
|
|
195
|
+
"files": 12,
|
|
196
|
+
"bytes": 2048,
|
|
197
|
+
"last_indexed": 1_800_000_000.0,
|
|
198
|
+
}
|
|
199
|
+
]
|
|
200
|
+
)
|
|
201
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
202
|
+
|
|
203
|
+
cli_module.repos()
|
|
204
|
+
|
|
205
|
+
assert srv.calls == [("code_indexed_repos", {})]
|
|
206
|
+
assert "test/a" in capsys.readouterr().out
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def test_repos_shows_a_question_mark_for_an_unreadable_store(monkeypatch, capsys):
|
|
210
|
+
srv = _stub(
|
|
211
|
+
code_indexed_repos=[
|
|
212
|
+
{
|
|
213
|
+
"repo": "https://github.com/test/a",
|
|
214
|
+
"files": None,
|
|
215
|
+
"bytes": 0,
|
|
216
|
+
"last_indexed": 1_800_000_000.0,
|
|
217
|
+
}
|
|
218
|
+
]
|
|
219
|
+
)
|
|
220
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
221
|
+
|
|
222
|
+
cli_module.repos()
|
|
223
|
+
|
|
224
|
+
assert "?" in capsys.readouterr().out
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def test_branches_dispatches_to_indexed_branches(monkeypatch, capsys):
|
|
228
|
+
srv = _stub(
|
|
229
|
+
code_indexed_branches=[
|
|
230
|
+
{"repo": "https://github.com/test/a", "branches": ["feature-x", "main"]}
|
|
231
|
+
]
|
|
232
|
+
)
|
|
233
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: srv)
|
|
234
|
+
|
|
235
|
+
cli_module.branches()
|
|
236
|
+
|
|
237
|
+
assert srv.calls == [("code_indexed_branches", {})]
|
|
238
|
+
assert "https://github.com/test/a: main,feature-x" in capsys.readouterr().out
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def test_branches_prune_is_refused_in_remote_mode(monkeypatch, capsys):
|
|
242
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: _stub(code_indexed_branches=[]))
|
|
243
|
+
monkeypatch.setattr(cli_module, "_is_remote", lambda: True)
|
|
244
|
+
|
|
245
|
+
with pytest.raises(SystemExit):
|
|
246
|
+
cli_module.branches(prune=True)
|
|
247
|
+
|
|
248
|
+
assert "does not share" in capsys.readouterr().out
|
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
from __future__ import annotations
|
|
4
4
|
|
|
5
|
+
import datetime
|
|
5
6
|
import json
|
|
7
|
+
from types import SimpleNamespace
|
|
6
8
|
|
|
7
9
|
import pytest
|
|
8
10
|
|
|
@@ -50,19 +52,20 @@ def test_render_table_toml_dumps_normalized_rows(capsys):
|
|
|
50
52
|
assert payload["rows"] == [{"role": "exported", "refs": 2}]
|
|
51
53
|
|
|
52
54
|
|
|
53
|
-
def test_repos_honors_structured_output(
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
55
|
+
def test_repos_honors_structured_output(monkeypatch, capsys):
|
|
56
|
+
# `repos` dispatches through _srv(), so stub the tool it calls: this test is
|
|
57
|
+
# about rendering the rows, not about stores on disk.
|
|
58
|
+
indexed = SimpleNamespace(
|
|
59
|
+
code_indexed_repos=lambda: [
|
|
60
|
+
{
|
|
61
|
+
"repo": "https://github.com/test/repo",
|
|
62
|
+
"files": 7,
|
|
63
|
+
"bytes": 1024,
|
|
64
|
+
"last_indexed": datetime.datetime(2026, 7, 13, 9, 41).timestamp(),
|
|
65
|
+
}
|
|
66
|
+
]
|
|
64
67
|
)
|
|
65
|
-
monkeypatch.setattr(cli_module, "
|
|
68
|
+
monkeypatch.setattr(cli_module, "_srv", lambda: indexed)
|
|
66
69
|
output_module.set_output_format("json")
|
|
67
70
|
|
|
68
71
|
cli_module.repos()
|
|
@@ -75,7 +78,8 @@ def test_repos_honors_structured_output(tmp_path, monkeypatch, capsys):
|
|
|
75
78
|
"repo": "https://github.com/test/repo",
|
|
76
79
|
"files": "7",
|
|
77
80
|
"size": "1.0KB",
|
|
78
|
-
|
|
81
|
+
# Rendered from the epoch in the reader's local timezone.
|
|
82
|
+
"last indexed": "2026-07-13 09:41",
|
|
79
83
|
}
|
|
80
84
|
],
|
|
81
85
|
}
|