dsh-gitnexus-plus 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,632 @@
-# Temporary Holding Version
+# dsh-gitnexus-plus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A DeepSeek Harness plugin for **GitNexus index visibility** — starting with the part
+GitNexus itself cannot tell you: **what the index left out**.
+
+## The problem it solves
+
+`gitnexus analyze` silently drops files. Its entire surface for saying so is one
+line on stderr, printed once:
+
+```
+  Skipped 3 large files (>512KB, likely generated/vendored)
+    - dist/app.min.js
+    ...and 2 more (set GITNEXUS_VERBOSE=1 to list them all)
+```
+
+That line is not returned, not persisted, not queryable, and gone when the terminal
+scrolls. Meanwhile the files it names can be the difference between an index that
+represents your codebase and one that does not — measured on this machine,
+`material-ui` skips 4.4 MB (12.4 % of scanned bytes), and those files contribute
+**zero** symbols to the graph.
+
+This plugin turns that line into data, a tool, and a route.
+
+## What this project is, and what it is not
+
+[GitNexus](https://github.com/abhigyanpatwari/GitNexus) is a code-intelligence engine by
+**Abhigyan Patwari**. It parses a repository into symbols, relationships and execution
+flows and writes them to a local graph database. It is a genuinely good piece of work,
+and this project would have nothing to show without it.
+
+What GitNexus does not give an everyday user is **visibility** and **automation**:
+
+- **Visibility** — how much of the repository does the index actually cover? Which files
+  were skipped for being too large? Has the index fallen behind `HEAD`, and by how much?
+  The CLI does not answer those unasked, and the answer is invisible exactly when it
+  matters.
+- **Automation** — once an index is stale, somebody has to remember to refresh it.
+
+**This project is a layer that adds those two things and nothing else.** It reads the
+index GitNexus wrote, reports what the index left out, and can start an incremental
+refresh through GitNexus's own CLI.
+
+It does **not**:
+
+- fork GitNexus, patch it, or reimplement its parser or graph database;
+- redistribute GitNexus source. Nothing from that project is inside this package's
+  tarball. `gitnexus` is declared as a **peer**, not a dependency, so installing this
+  plugin installs nothing from it — the operator supplies GitNexus, by whatever means,
+  and the two stay separate;
+- claim authorship of, or any contribution to, GitNexus. All rights in GitNexus belong
+  to its author;
+- replace GitNexus. With no GitNexus index there is no graph to display — only a
+  working-tree scan (file counts, bytes, languages), which is useful but is not a
+  substitute for the graph.
+
+## Licence — read this before a commercial use
+
+This project is **MIT** (see [LICENSE](LICENSE)).
+
+**It depends on GitNexus, which is `PolyForm-Noncommercial-1.0.0`.** That licence grants
+noncommercial use and restricts commercial use. GitNexus is **not** a dependency of this
+package — it is a peer, so installing this plugin does not install it, and the plugin
+never bundles or redistributes it. Installing this plugin's package therefore installs
+nothing under that licence. But every GitNexus-backed feature — reading an index,
+refreshing one, installing one on request — puts your use of *GitNexus* under
+*GitNexus's* licence:
+
+- **your use of this plugin's GitNexus-backed features is subject to GitNexus's
+  licence**, not to this project's MIT grant;
+- **commercial use requires a separate grant from GitNexus's author.** If your use is
+  commercial, read
+  <https://github.com/abhigyanpatwari/GitNexus/blob/main/LICENSE> or contact the author
+  before relying on any of it.
+
+This project cannot and does not change that: it only calls the interfaces GitNexus
+provides. The read-only half — reading `.gitnexus/gitnexus.json` and reporting on it —
+is this project's own code and carries no GitNexus code, but it also has nothing to
+report on unless GitNexus produced that file.
+
+A one-line summary: **the MIT licence here covers my code; GitNexus's licence covers
+GitNexus, and installing this plugin installs GitNexus.**
+
+## What it reports
+
+- **Skipped large files** — path, size, share of its language, and two independent
+  signals for *why* it is not source: a single-line (minified) heuristic, and a
+  build-output path heuristic. Binary assets are detected separately and never
+  called minified.
+- **Index freshness** — the indexed commit against HEAD, classified `current` /
+  `behind` / `diverged` / `unknown` the same way `gitnexus status` does, plus the
+  uncommitted-change count.
+- **Graph composition** — nodes, edges, communities, processes, embeddings, and
+  edges-per-node, all read from the manifest.
+- **Query surfaces** — which of graph / keyword search / semantic search are
+  actually available, with the reason when one is not. An index with no FTS cannot
+  answer keyword queries, and hiding that is how a reader concludes otherwise.
+- **Git activity, crossed with the index** — recent commits, authors (bots marked),
+  branches, most-changed files and most-recent files, each carrying a three-way
+  verdict: *indexed*, *excluded by design*, or **missing from the index**. That last
+  one is the point: of the files people are actively editing, which does the graph
+  not see?
+- **Language distribution by bytes**, split three ways: languages GitNexus can
+  *parse* into the graph, formats it merely *recognizes*, and everything else. When
+  GitNexus is absent, a built-in extension map keeps the breakdown useful; those
+  rows are marked `detector: "builtin"` and are never presented as *parsed*.
+- **Resolver confidence** — untyped receiver sites, which make `impact` and
+  `context` a lower bound rather than an exact answer.
+- **A scan-only report when there is no index** — file count, selected count, bytes
+  and language split are readable from the working tree alone. The panel shows them
+  under "尚未索引" instead of an empty state, and the initialize command sits beside
+  them.
+- **Keyword search with click-to-open** — the panel's search box asks the graph for
+  nodes whose `name` or `filePath` contains the query, and returns the graph node
+  kind, name, path and line. **Clicking a hit opens that file in the platform's file
+  viewer at that line** through `ctx.sidebarRight.openResource` and a
+  `dsh-resource://file/session/...` address; a separate 复制 button copies
+  `path:line`. When the graph helper cannot start, the bounded source-text fallback
+  is used instead and the card is labelled 源码关键词（回退）.
+
+## Why the git three-way split matters
+
+A two-way "indexed / not indexed" count is misleading. Measured on a real
+repository, 1 635 files had been touched in 90 days: 491 indexed, 1 143 absent, and
+reporting that as "70 % missing" is wrong — 1 143 of them are lockfiles, dotfiles
+and binary assets that no scan would select either. Exactly **one** was a genuine
+gap (`src/stores/windowModeStore.ts`). The panel reports the three numbers
+separately, and only the third raises a warning.
+
+
+## Design commitments
+
+**Reuse, don't reimplement.** "Which files did GitNexus skip?" has exactly one
+correct answer: the set `walkRepositoryPaths` produced. This plugin deep-imports
+GitNexus's own `createIgnoreFilter`, `glob` call and `getLanguageFromFilename`
+rather than approximating them, and `test/run.mjs` cross-checks its scan against
+`walkRepositoryPaths` on real repositories. If upstream reshapes those modules the
+plugin degrades to a documented fallback scan (`ScanReport.primitives === 'fallback'`)
+instead of reporting a wrong number.
+
+**Absent is reported as absent.** The size cap an index was built under is read from
+that index. Legacy indexes (`meta.json`, no `indexCoverage`) are reported with the
+cap *unknown* and a note — never defaulted to today's value, which would misattribute
+covered files as skipped.
+
+**Read-only.** Nothing here triggers `analyze`, writes to `.gitnexus/`, or takes the
+index lock. A status check must never start a 30-second rebuild.
+
+## Getting GitNexus — the prerequisite, and the two ways to satisfy it
+
+This plugin reads an index. **Only GitNexus produces one.** So the plugin checks
+whether GitNexus is present, and when it is not, the panel says so above everything else
+rather than letting you wonder why the numbers are missing.
+
+Two ways out, in the order the panel offers them:
+
+**① Install it yourself.** The panel shows a copyable `npm install -g gitnexus`, and
+that is the recommendation. You know your network, your registry and your toolchain; a
+command you can run is more useful than a download this plugin performs on your behalf,
+and it works behind whatever mirror or feed your machine actually reaches.
+
+**② Let the plugin install it.** Second in the list and behind a confirmation, because
+it is a much larger decision. It runs, through the host's shell executor:
+
+```
+npm install --prefix <DSH_HOME>/gitnexus-plus/gitnexus gitnexus@^1.6.12
+```
+
+and the confirmation states what that means before anything starts:
+
+- **about 500 MB to 1 GB** downloaded, from whatever registry your `.npmrc` already
+  names — this plugin hardcodes none, because a hardcoded one breaks exactly the users
+  whose network is why they need this path;
+- **several minutes**, longer on a slow link or when the native modules have to compile;
+- **this machine's build toolchain is used** — `@ladybugdb/core`, `tree-sitter` and
+  `tree-sitter-*` compile on install. That is why this is `npm` and not `pnpm`: pnpm 10+
+  refuses dependency build scripts by default, and the failure it produces is one you
+  cannot act on. GitNexus's own message names the grants it needs:
+  `--allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter`;
+- it installs into a **plugin-owned directory**, never your global prefix, so it needs no
+  elevation and cannot collide with a GitNexus you already have.
+
+Everything runs through `ctx.shell`, so a sandboxed deployment confines it exactly as it
+confines your own commands. **A refusal is reported as a refusal and never retried
+wider** — the plugin never asks for more scope than the session already granted.
+
+**The installed copy is the one every later step uses.** The install prefix is resolved
+once and passed to all three consumers: the coverage engine's own scan primitives, the
+language detector, and the `analyze` runner. This wiring was missing in 0.1.1 — the
+installer wrote a plugin-owned tree, while the reader and runner probed only PATH and
+the declared dependency, so the install succeeded and *nothing used it*. A machine with
+no global GitNexus still reported "absent" after a successful install.
+
+**Install → initialize is one authorised step.** If the current project has no index,
+a successful install continues with a single `gitnexus analyze --index-only` for that
+project, so the operator gets from "no GitNexus" to a visible index without a second
+click. The install confirmation says this before anything starts. The chain is gated on
+the install having been started from this panel and on the project still having no
+index; it never silently refreshes an index that already exists.
+
+If your GitNexus lives somewhere unusual, name it directly and none of this applies:
+
+```sh
+GITNEXUS_CLI=/path/to/gitnexus/dist/cli/index.js
+```
+
+That path is checked first, and it is the answer for an offline or air-gapped machine:
+put a copy anywhere, point at it, done.
+
+## Usage
+
+```sh
+# CLI, no install
+npm run build                       # tsc (host) + tsc (client) + wrap
+node lib/bin/gitnexus-coverage.js <repo-path>
+node lib/bin/gitnexus-coverage.js -r material-ui     # by registry alias
+node lib/bin/gitnexus-coverage.js --all --json       # every indexed repository
+node lib/bin/gitnexus-coverage.js <repo> --fail-on-large   # exit 2 — CI gate
+
+# type check
+npm run check
+
+# tests
+npm test
+```
+
+In DSH the plugin exposes:
+
+- **tool** `gitnexus_coverage` — `{ repo, includeLanguages? }`
+- **route** `GET /api/gitnexus/coverage?repo=<project>` — one report, plus the
+  maintenance commands for that project
+- **route** `GET /api/gitnexus/search?repo=<project>&q=<keyword>&limit=20` —
+  read-only keyword search over the graph's symbol names and file paths
+- **panel** — a right-sidebar tab type `gitnexus`, opened from the sidebar's **+** →
+  guide page ("GitNexus 索引")
+
+The coverage route is read-only. Its bound is a **project root** — a directory with a
+`.gitnexus` index or a `.git` marker — so it cannot be turned into a filesystem probe.
+An index is no longer required: a git project without one gets the engine's scan-only
+report, which is what makes "no index yet" informative. It is additionally restricted
+to loopback peers because a third-party DSH route is unauthenticated by default on a
+bare `dsh web` profile.
+
+There is now a **second** route, `/api/gitnexus/analyze`, and it is the only one that
+can change anything. It answers `POST` to start an incremental refresh (`?force=1`
+selects a full rebuild), `GET` to report where that got to, and `DELETE` to stop it. It is a separate module from the coverage
+route so the read-only half keeps a method policy that cannot mutate — the shared guard
+takes the accepted methods from the route rather than hard-coding one set for both. The
+mutating verbs additionally pass the write guard, which refuses cross-origin requests;
+loopback alone is not enough, because any page the operator visits can reach
+`127.0.0.1`. See **Maintenance** below for what it will and will not do.
+
+A **third** route, `/api/gitnexus/search`, is read-only like coverage but queries the
+LadybugDB graph instead of the manifest. It opens the database read-only and searches
+node names and file paths; it does **not** use FTS, which is why it works on an index
+built with `--skip-fts` and on a machine where the FTS extension fails to load. The
+response carries the node kind, name, path and line, plus an honest warning when
+content-level FTS is unavailable.
+
+**Two tiers, because the host shell can be unavailable.** The normal path is the
+graph query. If the helper cannot start — a Windows sandbox backend that cannot create
+its own temp directory, no shell executor, a busy database — the route falls back to a
+bounded source-text search over the files listed in the index manifest. That fallback
+needs neither a shell nor the native addon; it returns `mode: "text"`, searches code
+files before documentation, caps files/bytes/matches, and says so in `warning` and in
+the panel's card title. A silent swap between "graph" and "source text" would be a
+dishonest answer, so the mode is part of the response.
+
+**The graph query runs in a Node helper subprocess, not in the DSH host.** The host runs on
+Electron's Node, and GitNexus's LadybugDB addon is built for the system Node ABI.
+Loading it in-process fails with `A dynamic link library (DLL) initialization routine
+failed ... lbugjs.node`; the same addon loads under the system Node 24 that the CLI
+uses. The host therefore starts:
+
+```
+node lib/bin/search-helper.js <repo> <keyword> <limit> <managed-prefix>
+```
+
+and parses one JSON object. That is the same execution boundary the analyze runner
+already uses, and it keeps the panel process free of native state it cannot load.
+Consequently the graph path needs a shell executor and `node` on the shell's PATH;
+without them it falls back to source text, not an empty result list.
+
+**Clicking a hit opens the file, not a copy.** The row calls
+`ctx.sidebarRight.openResourceIn(sessionId, address, { params: { line } })` (or the
+public `openResource` when the targeted variant is unavailable) with
+`dsh-resource://file/session/<session>/<path>`. That is the same address and line
+parameter the built-in file strip and the chat's file links use, so the platform's
+own file viewer/editor handles the navigation. A separate 复制 button remains for the
+`path:line` text. A profile without a right-sidebar controller falls back to copying
+and says so.
+
+## TypeScript, and why the build looks the way it does
+
+The source is TypeScript under `strict`, including `noImplicitAny`. That is not
+decoration: an implicit `any` is a **silent** failure — it does not report an error,
+it just makes the checker stop working exactly where it was needed. Migrating this
+codebase from JS+JSDoc to real types surfaced six places where the documentation and
+the code disagreed, none of which produced a runtime error until the affected branch
+was reached:
+
+| Where | JSDoc claimed | Actually |
+| --- | --- | --- |
+| `LargeFile.generatedHint` | `string \| null` | `boolean` — consumed as `if (x)` |
+| `LargeFile.minified` | non-null | nullable, when the probe budget runs out |
+| `analyzer.primitives` | `number` | a **string**, compared against `'gitnexus'` |
+| `MinifiedVerdict` | a type name | **the type did not exist** |
+| `activityView()` result | — | missing `truncated`, which callers read |
+| `analyzeCoverage` options | 3 fields | 5 — two were undocumented |
+
+### Two compile targets, no bundler
+
+```
+src/index.ts ───────────┐
+src/gitnexus/*.ts ──────┤ tsc  (NodeNext)   → lib/**/*.js + *.d.ts    ESM
+src/routes/*.ts ────────┤
+src/bin/*.ts ───────────┘
+
+src/client/index.ts ────→ tsc  (CommonJS)   → build/client/index.js
+                                             ↓ text wrap (scripts/build-client.mjs)
+                                             lib/client.js
+```
+
+The browser half needs no bundler because it **is** one module: its only imports are
+platform baseline modules (`react`, the UI primitives) supplied by the loader's own
+`require` at runtime, and it has no relative imports at all. `tsc --module commonjs`
+therefore emits exactly one self-contained file, and the wrap is a text operation. A
+bundler would add a dependency and a resolution graph to solve a problem this package
+does not have.
+
+`esModuleInterop` is **off** for the client target on purpose: it makes
+`import * as React from 'react'` compile to a bare `const React = require("react")`,
+which is precisely what the loader factory provides. With interop on, tsc injects an
+`__importStar` helper that would ride along in every page load.
+
+### `scripts/*.mjs` stays JavaScript (deliberate)
+
+`scripts/link-runtime.mjs` runs from `postinstall`, and `scripts/build-client.mjs` is
+the build driver itself. A bootstrap script **must not depend on the build it
+bootstraps** — if those needed compiling, a fresh clone's `npm install` would fail
+because `lib/` does not exist yet. `src/**` and `bin/**` are TypeScript; `scripts/`
+is plain ESM, and that line is intentional rather than unfinished.
+
+### Runtime packages ship no type declarations
+
+`@deepseek-ai/schemastery`, `@deepseek-ai/dsh-tools`, `@deepseek-ai/cordis` and
+`@deepseek-ai/dsh-client-ui-primitives` each declare `"types": "lib/types/index.d.ts"`
+in their manifest and ship no such file. Every plugin author has to write these
+declarations; `types/` holds the four, with the surface limited to what this plugin
+actually uses. The primitive **props** were read off real call sites in shipped
+plugins rather than guessed, because a wrong prop name fails silently at runtime —
+the control renders with a default and nothing reports anything.
+
+## Client half
+
+`src/client/index.ts` is one CommonJS module using nothing but baseline modules
+(`react`), so `scripts/build-client.mjs` wraps it into the loader's factory
+artifact with no bundler at all — a text wrap cannot drift from its source the way
+a bundle can.
+
+The panel splits fetching (`CoveragePanel`) from presentation (`CoverageView`).
+That is not stylistic: a component that fetches cannot be rendered against a
+fixture, and the states worth asserting on — a report with skipped files, one
+without, an error, missing language data — are exactly the ones a fixture supplies.
+`test/client.mjs` renders each of them through a minimal single-pass hooks shim.
+Keyword search follows the same split: `CoveragePanel` owns the request and
+`SearchSection` is a pure function of its props, so the empty, error and result
+states are all fixture-testable without a graph database.
+
+Styling is theme-agnostic by construction: host elements only, `color` inherited,
+every border derived from `currentColor`. `@deepseek-ai/dsh-client-ui-primitives` is
+a baseline module but ships no JS in the installed runtime, so its exports cannot
+be verified from outside — guessing at component props would fail at mount time in
+a browser, where no test in this repository can see it.
+
+## Verified end to end
+
+Installed into the `web` profile and booted; the route answered with real data:
+
+```
+GET /api/gitnexus/coverage?repo=D:\Project\material-ui     HTTP 200
+  manifest meta.json · scanned 28927 · selected 28924 · large 3 · 11 languages
+  2.3 MB  packages/mui-icons-material/lib/index.js   generated
+  1.4 MB  CHANGELOG.old.md
+  739.9 KB packages/mui-icons-material/lib/index.mjs  generated
+GET /api/gitnexus/coverage?repo=C:\Windows                 HTTP 404 (refused)
+```
+
+The search engine and its route were exercised over a loopback harness against this
+repository's real index (the same database the panel reads):
+
+```
+GET /api/gitnexus/search?repo=D:\Project\gitnexus-plus&q=analyzeCoverage  HTTP 200
+  Function analyzeCoverage src/gitnexus/coverage.ts:507
+GET /api/gitnexus/search?repo=D:\Project\gitnexus-plus&q=client/index&limit=3  HTTP 200
+  File index.ts src/client/index.ts
+GET /api/gitnexus/search?repo=C:\Windows\System32&q=x                     HTTP 404 (refused)
+```
+
+The helper boundary itself, run under the system Node 24, returns the JSON the host
+parses (the host's Electron Node cannot load the native addon):
+
+```
+node lib/bin/search-helper.js D:\Project\gitnexus-plus analyzeCoverage 5
+{"ok":true,"report":{"query":"analyzecoverage","mode":"graph",
+ "results":[{"kind":"Function","name":"analyzeCoverage",
+ "filePath":"src/gitnexus/coverage.ts","startLine":507,"endLine":864}],
+ "ftsAvailable":false,"total":1,...}}
+```
+
+## Scope: the project you are in, not a global list
+
+The panel reports **the project the session's workspace points at**. It does not
+list indexed repositories and has no picker.
+
+That is a deliberate reversal. The first design read `~/.gitnexus/registry.json`
+and offered a dropdown, which made a global file a hard dependency — so a fresh
+clone, a second working tree, or an index built with `GITNEXUS_HOME` redirected
+could not be shown at all, which is exactly when a coverage panel is most useful.
+The workspace comes from the slot's session-scoped props (`useWorkspaces` matched
+by `sessionId`); the host route accepts any directory **that is already a GitNexus
+index**, which is the bound that keeps it from being a filesystem probe.
+
+## Maintenance: the refresh runs here, the escape hatches do not
+
+Two situations the read-only half cannot resolve on its own:
+
+- **初始化索引 / 增量刷新** — the index is missing or behind HEAD. This one the plugin
+  runs for you.
+- **强制全量重构** — the incremental refresh has hung. GitNexus's update path is not
+  reliably terminating, and when it wedges a full rebuild is the only way out. This
+  one also has a button, behind its own destructive confirmation: the route implements
+  `--force`, and the dialog says what it rebuilds, how long it can take, and that the
+  index may be briefly unavailable.
+
+**Both maintenance actions run through the host's shell executor.** An earlier revision
+handed over every command as text, justified by "a plugin that spawns processes
+bypasses the permission system". That reasoning was wrong, and the correction is worth
+stating precisely:
+
+DSH's approval service governs **sandbox escalation** — widening the scope a session was
+granted. Its audit pair must be turn-enclosed, which is why `ApprovalService.request()`
+throws outside an open turn; a panel route has no turn, so it cannot ask. It also has
+nothing to ask about here: this command writes `.gitnexus/` **inside the workspace**,
+already within the granted scope.
+
+Confinement is not something a caller opts into. It is what `ctx.shell` *is* in a given
+deployment — `dsh-pwsh-local` exposes the argv seam that `dsh-pwsh-sandbox` wraps
+through `ctx.sandbox.confine`. So routing through the executor gives this plugin exactly
+the isolation your own shell commands get.
+
+What the plugin commits to, and what is tested:
+
+- **It never sets `sandboxPolicy`.** Requesting one would be this plugin choosing its
+  own confinement — escalation, asked for through a door that cannot ask. A denial comes
+  back as `denied` and **is never retried wider**.
+- **One run per repository.** Two concurrent `analyze` processes contend for the same
+  store, and the second reports a failure that says nothing about the repository.
+- **`--index-only` always.** Without it `analyze` rewrites `AGENTS.md`, `CLAUDE.md` and
+  the agent skill files in your tree — a far larger change than "refresh the index".
+- **A confirmation before it starts**, stating the exact command, what it touches and
+  how long it takes.
+- **The full rebuild is a separate confirmation.** It runs only when the request carries
+  `force=1`, its confirmation says it rebuilds the graph and FTS and may take minutes,
+  and its button is labelled 全量重建 rather than borrowing the incremental one.
+- **Cancellable**, with a ten-minute ceiling by default (`analyzeTimeoutMs`).
+
+The full rebuild used to have no button because the host route did not implement
+`--force`. The route does now, and the button runs exactly the command its dialog
+shows — a button that quietly ran something other than its label would still be worse
+than no button.
+
+The commands shown and executed are not a bare `gitnexus analyze`, because that does not
+work in every deployment:
+
+```
+$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; \
+  $env:GITNEXUS_HOME='<project>\.gitnexus\plugin-home'; \
+  gitnexus analyze --index-only '<project>'
+
+$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; \
+  $env:GITNEXUS_HOME='<project>\.gitnexus\plugin-home'; \
+  gitnexus analyze --index-only --force '<project>'
+```
+
+- `GITNEXUS_MEMORY=off` — the CLI otherwise re-spawns itself with a larger heap over
+  piped stdio, which a confined sandbox denies (`spawn EPERM`).
+- `NODE_OPTIONS=--max-old-space-size=8192` — supplies the heap that respawn wanted.
+- `GITNEXUS_HOME=<project>\.gitnexus\plugin-home` — the global registry write would
+  otherwise go to `~/.gitnexus`, outside a confined host's writable scope. A failed
+  registry write leaves the index marked `incremental-in-progress` and incomplete.
+  The plugin defaults this redirect to the project's own `.gitnexus/plugin-home`;
+  `gitnexusHome` overrides it.
+- `--index-only` — the default `analyze` also rewrites `AGENTS.md`, `CLAUDE.md` and
+  agent skill files inside your repository. A maintenance action must not edit the
+  working tree.
+
+`--skip-fts` is **adaptive**, not a static default. An index whose manifest says
+`capabilities.fts.status: available` gets no flag; an index without FTS gets
+`--skip-fts`, because the extension's install is an out-of-process step a confined
+host denies (`spawn EPERM`), and that failure aborts the refresh. This matters in both
+directions: measured on a 39-file repository, putting `--skip-fts` on an index that
+already has FTS forces a full graph-store rebuild — 179.22 s against 8.57 s, a 21×
+penalty — while omitting it on an index without FTS makes the refresh fail outright.
+Setting `skipFts: true` forces the flag; there is no config that forces FTS on, because
+enabling it is a repair (`gitnexus analyze --repair-fts`), not an incremental refresh.
+
+The panel prints these rationales next to the commands, so they do not look
+arbitrary. `src/gitnexus/commands.js` is pure and asserted verbatim by tests.
+
+
+The CLI cannot manage the `desktop` profile — Electron owns it. Use the Web
+sidebar's Plugins page there. `web` is CLI-managed:
+
+```sh
+dsh plugin --profile web add <absolute path to this package>
+dsh --profile web --dump-config | grep gitnexus-plus    # layer composes
+dsh --profile web                                        # restart (bundle set changed)
+```
+
+`dsh plugin add` also adds the package to `dsh.profile.bundles` automatically,
+because this package declares `dsh.bundle`.
+
+## Known limits
+
+- **Detection is a filesystem probe, not an execution check.** The plugin declares no
+  runtime dependencies and never imports `gitnexus`; it reads an index another tool
+  produced and, when it can, deep-imports the upstream scan primitives at runtime. That
+  design keeps it a pure observer, but it makes "the operator has no GitNexus" a
+  reachable state — so `src/gitnexus/toolchain.ts` probes it in three states (`ready` /
+  `library-only` / `absent`), separating "the library tree exists" from "a CLI is on
+  PATH" because they gate different promises. The refresh runner consults it **before
+  spawning anything**: with no CLI it reports `unavailable` and tells the operator to
+  install one, rather than starting a process that cannot work. Spawning the CLI to ask
+  its version would be the direct test, but a confined process denies piped stdio, so
+  the probe only stats the filesystem. The engine degrades on its own too — `scan.ts`
+  falls back to its own walker and reports `primitives: 'fallback'`, and the built-in
+  size caps apply.
+- **A report that reused GitNexus's scan rules and one that fell back to an
+  approximation are still not distinguished per file.** The toolchain verdict travels
+  with the report, the language breakdown carries `detector: "gitnexus" | "builtin"`,
+  and the fallback rows are never labelled *parsed* — but the remaining per-file numbers
+  do not carry a provenance marker, so a fallback walk is not labelled as one where
+  those numbers are shown. The built-in walker deliberately does **not** implement
+  upstream's ignore rules faithfully, and its uncovered-file count can therefore carry
+  false positives.
+- **Installing GitNexus from the panel has never been run against a real network.** The
+  command shape is verified (`npm install --prefix … --no-audit --no-fund`, no hardcoded
+  registry), the runner's state machine is covered by fourteen assertions, and the
+  failure paths name the two likely causes — unreachable registry, missing C++ toolchain.
+  What is **not** verified is the download and compile itself: it is several hundred
+  megabytes and was never executed from inside a confined DSH process. Treat the first
+  authorised install on any machine as untested, and fall back to the manual command if
+  it fails — which is why that command is offered first. What *is* verified by tests is
+  that the installed prefix is the one the reader, the language detector and the analyze
+  runner all resolve; the download and compile remain unverified.
+- **`--omit=optional` saves about 486 MB of that install, and is not used by default.**
+  Measured: a full GitNexus tree is 998.9 MB, and omitting the optional dependencies
+  gives 513.2 MB by dropping `onnxruntime-node` (287 MB), `onnxruntime-web` (139 MB) and
+  `@huggingface/transformers`. Those serve vector search and embeddings, which this
+  plugin never enables and reports as `unavailable`. The default does not pass the flag
+  because the plugin cannot verify that analysis still succeeds without them on every
+  platform, and a refresh that fails in an unexplained way is worse than one that is
+  large. A deployment that wants the smaller tree can set `gitnexusInstallDir` aside and
+  install by hand with `--omit=optional`.
+- **The refresh runs outside the conversation, and that has a real consequence.** A
+  command started from the panel goes through `ctx.shell` and is confined exactly as
+  your own shell commands are, but it is **not** a tool call: it writes no
+  `approval/asked` + `approval/decided` pair into the session log, and it does not
+  appear in the transcript. That pair could not be written even if it were wanted —
+  `ApprovalService.request()` requires an open turn and throws without one, which is
+  also why there is nothing to approve: the command does not escalate. The audit record
+  is the run state the panel holds, which is per-process and is not persisted. If you
+  want a refresh on the conversation's record, run the handed-over command in the
+  session instead; that path is unchanged.
+- **Walk cost scales with file count.** ~29 000 files takes ~1.4 s warm, ~13 s on a
+  cold filesystem cache. The host half caches reports for 15 s; a panel that polls
+  faster than that gains nothing.
+- **The minified heuristic reads a 64 KB head and extrapolates.** It flags
+  single-line bundles reliably and correctly *declines* generated-but-multi-line
+  output (verified: a 2.3 MB, 75 263-line file averages 31 chars/line). The
+  generated-path heuristic covers that gap, as a hint rather than a verdict.
+- **Binary assets are detected and reported separately, and that is not cosmetic.**
+  A first revision tested only "no newlines ⇒ one enormous line", so a real 380 MB
+  `.glb` was reported as *"single-line ≈ 399 230 584 chars — probably minified
+  rather than source"*. The number was absurd; the conclusion was worse, because it
+  implied that 97 % of one repository's skipped bytes were compressed **source**
+  when 414 of 417 MB were 3D models that could never hold a symbol. Detection is
+  git's own rule (a NUL byte in the head means binary), plus a control-byte ratio;
+  binary short-circuits both the minified and generated claims, and the headline
+  warning now separates binary from text so the figure worth acting on is visible.
+  Verified end to end on the repository that exposed it: the actionable remainder
+  went from an implied 416.9 MB to **2.6 MB**.
+- **`git ls-tree` is not used.** An earlier design compared the index against
+  git-tracked files; real data killed it — 8 of the "missing" tracked files in a
+  37-file repo were dotfiles excluded by the walker's `dot: false`, and 2 indexed
+  files were untracked. The walker's own rules are the only honest denominator.
+- **Keyword search is graph name/path first, with a source-text fallback.** The graph
+  mode finds symbols and files whose *names* or *paths* contain the query; it does not
+  search function bodies, comments or descriptions. The fallback (`mode: "text"`) does
+  search line text, but only in the files the index manifest lists, and only when the
+  graph helper cannot start. Content-level search as a first-class mode is GitNexus's
+  FTS surface, and on this machine the FTS extension fails to load
+  (`libfts.lbug_extension` missing) and the current index was built with `--skip-fts`.
+  The panel labels the two modes separately (符号名 / 文件路径 vs 源码关键词（回退）) and
+  never presents a text hit as a graph hit.
+- **Search needs a child Node process for the graph path.** The host's Electron Node
+  cannot load the LadybugDB addon (ABI mismatch), so the query is delegated to
+  `lib/bin/search-helper.js` under the system Node 24. This is deliberate, not a
+  workaround to remove: an in-process search fails on the host with the DLL
+  initialization error above. If the shell executor is unavailable (measured on this
+  machine: the Windows `windows-acl-run` sandbox cannot create its temp directory),
+  search does **not** fail — it falls back to the bounded source-text scan and labels
+  the result `text`. The graph query remains the preferred path when the helper can
+  start.
+- **The source fallback is not the graph.** It searches line text in the files the
+  index manifest lists, not symbol relationships; code paths are searched before
+  documentation, and the file/byte/match caps can truncate a large repository. The
+  panel's card title changes to 源码关键词（回退） and the warning names the fallback,
+  so a text hit is never presented as a graph hit.
+- **Panel effects and re-render are still not automated.** `react-dom` is not installed
+  on this machine, so rendering uses a single-pass shim: `useState` yields its initial
+  value and `useEffect` never runs. The pure view is covered; the fetch lifecycle is
+  not. The panel has now been checked once against the real right sidebar, and that
+  check is what exposed the two-column layout clipping the language card at a narrow
+  pane edge, the grey single-bucket chart, the invented `--dsw-color-*` tokens, the
+  raw English `index` cap source, and the `--skip-fts` config default. Those are
+  fixed, but a future prop or layout change can still pass every test here without
+  being seen in a browser.
+- **Install → initialize has not been exercised end to end against a real npm install.**
+  The managed-prefix wiring, the auto-chain gate, and the analyze command are covered by
+  tests; the several-hundred-megabyte download and native compile are not.

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# dsh-gitnexus-plus — bundle layer.
+#
+# Applied when a profile lists this package in `dsh.profile.bundles`. The row id
+# is what a profile-level patch targets to change this plugin's config, so it is
+# deliberately stable and matched by `name`.
+- insert:
+    - id: gitnexus-plus
+      name: dsh-gitnexus-plus
+      config:
+        # Cap for *reporting* only. The index's own recorded cap wins when present,
+        # because judging an index by a threshold it was not built with would
+        # misreport covered files as skipped.
+        scanDefaultCapKb: 512
+        # Sampling budget for the minified heuristic: how many oversized files to
+        # probe by reading their head. Bounded because a repository may hold
+        # hundreds of skipped bundles and this is a heuristic, not a verdict.
+        minifiedSampleLimit: 40
+        serveRoutes: true

package/lib/bin/gitnexus-coverage.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * `gitnexus-coverage` — report what an index left out.
+ *
+ * Usage:
+ *   dsh-gitnexus-coverage [repo-path | -r <alias>] [--json]
+ *   dsh-gitnexus-coverage --all       # every registered repository
+ *
+ * Exit code is 0 even when files were skipped: a skipped bundle is a fact about
+ * the repository, not a failure of this tool. Pass `--fail-on-large` to make it a
+ * CI gate instead.
+ */
+export {};
+//# sourceMappingURL=gitnexus-coverage.d.ts.map