dsh-gitnexus-plus

English · 简体中文

Current release: 0.1.2 · npm · Issues

What it does · Install · Troubleshooting · Upstream GitNexus docs

A DeepSeek Harness plugin: see what a GitNexus index covers and what it leaves out, refresh it from the sidebar, and search its symbols by keyword.

It does not fork GitNexus, rewrite its parser, or bundle/redistribute it. gitnexus is a peer; you provide it.

What it does

• Index coverage — lists the oversized files gitnexus analyze skipped, with size, language share, and generated/minified signals.
• Index freshness — indexed commit vs HEAD, classified current / behind / diverged / unknown, plus the uncommitted-change count.
• Graph composition — nodes, edges, communities, processes, embeddings, edges per node.
• Git activity × index — recent commits, authors, branches and most-changed files, each file marked indexed, excluded by design, or missing from the index.
• Language distribution — bytes split into languages GitNexus can parse, formats it only recognizes, and everything else. Without GitNexus, a built-in extension map keeps the breakdown useful and marks it builtin, never "parsed".
• Keyword search — matches graph node name / filePath, returns kind, path and line; clicking a hit opens the file at that line, and a separate Copy button copies path:line.
• Source fallback — when the graph helper cannot start (no usable shell sandbox, DLL/ABI, busy index), a bounded line search over the indexed files returns mode: "text" instead of pretending to be the graph.
• No-index visibility — a git project without an index shows a scan overview, language split and the initialize command instead of an empty panel.
• Maintenance — initialize, incremental refresh and full rebuild (--force) run through DSH's shell executor, with no self-escalation.

Install

Requirements:

• DSH >=0.2.0-rc.2 <0.3.0
• Node >=22
• GitNexus >=1.6.0 <2.0.0 (peer; not installed by this plugin)

dsh plugin add dsh-gitnexus-plus

Restart DSH after adding it. The panel is a right-sidebar tab: open the sidebar's + → guide page → GitNexus 索引.

The desktop profile is managed by Electron; the CLI cannot change it. Use the Web sidebar's Plugins page there. From a local checkout:

dsh plugin --profile web add <absolute path to this package>

GitNexus can be installed by you or by the panel. For a custom location:

GITNEXUS_CLI=/path/to/gitnexus/dist/cli/index.js

Getting GitNexus

Installing it yourself is recommended:

npm install -g gitnexus

The panel can also install it through DSH's shell:

npm install --prefix <DSH_HOME>/gitnexus-plus/gitnexus gitnexus@^1.6.12

That downloads roughly 500 MB–1 GB and needs a C++ toolchain; no registry is hardcoded. Treat the first install as unverified and fall back to the manual command if it fails.

Usage

The panel reports the project the current workspace points at; it has no global repository list. Its bound is a project root (a .gitnexus index or a .git marker), so it cannot become a filesystem probe.

Inside DSH:

• tool gitnexus_coverage: { repo, includeLanguages? }
• route GET /api/gitnexus/coverage?repo=<project>
• route GET /api/gitnexus/search?repo=<project>&q=<keyword>&limit=20
• route POST/GET/DELETE /api/gitnexus/analyze (the only entry that changes an index)
• right-sidebar tab gitnexus

CLI:

npm run build
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 # CI gate, exit 2
npm run check
npm test

Search has two modes:

• graph — the normal path. The host does not load native lbug; it starts lib/bin/search-helper.js under system Node and searches node names and file paths. It does not search bodies, so it works on an index built with --skip-fts.
• text — the fallback when the graph query cannot start. It reads the files listed in the index manifest, matches lines, searches code before docs, and caps files/bytes/ matches. The panel labels it 源码关键词（回退）.

Clicking a hit calls ctx.sidebarRight.openResourceIn(sessionId, address, { params: { line } }) to open the platform file viewer at that line; without that service it falls back to copying the path.

Troubleshooting

Start with the state the panel reports: GitNexus absent, no index, index stale, FTS unavailable. The rows below cover this plugin's boundary; the linked upstream GitNexus path owns the rest.

Symptom	What to do here	Upstream GitNexus path
The panel says GitNexus is absent	Install it yourself, or use the panel's install. For a non-standard location set GITNEXUS_CLI=/path/to/gitnexus/dist/cli/index.js.	gitnexus/README.md — Requirements, Quick Start
The project has no index	Use 初始化索引 in the panel, or run gitnexus analyze --index-only <repo>.	README.md — CLI Reference, RUNBOOK.md — Index out of date
Refresh fails, spawn EPERM, or the index stays incremental-in-progress	The panel's command already sets GITNEXUS_MEMORY=off, NODE_OPTIONS=--max-old-space-size=8192, GITNEXUS_HOME=<repo>/.gitnexus/plugin-home and --index-only. If the sandbox still refuses, run the copied command in your own shell; the plugin will not escalate.	RUNBOOK.md — LadybugDB / lock errors, Memory / analyze crashes
Refresh fails with EPERM … mkdir '<repo>\.gitnexus\parsedfile-store'	GitNexus 1.6.12 creates this cache directory from the parse worker. The plugin pre-creates the cache directories before spawning; restart DSH after upgrading. If it still fails, the sandbox token cannot write .gitnexus; run the copied command in a normal terminal.	RUNBOOK.md — LadybugDB / lock errors, RUNBOOK.md — Clean slate
Incremental analyze hangs, or the database reports Maximum database size … has been reached	Use 全量重建 (--force), or the clean-slate steps.	RUNBOOK.md — Clean slate, gitnexus/README.md — Troubleshooting
Search fails with A dynamic link library (DLL) initialization routine failed / lbugjs.node	Graph search runs in lib/bin/search-helper.js, never in the Electron host. Restart DSH after upgrading and keep node on the shell PATH. If the helper cannot start at all, search falls back to source text.	gitnexus/README.md — Troubleshooting
Windows search returns very few hits, or the panel warns FTS is unavailable	The index was built with --skip-fts, or the FTS extension cannot load. Keyword search still matches names and paths; the source fallback matches lines. Repairing FTS is an upstream action.	gitnexus/README.md — Windows: full-text search unavailable, Analyze warns about unavailable FTS
Clicking a search hit does not open a file	The click uses ctx.sidebarRight.openResourceIn; a profile without that service falls back to copying path:line. Restart DSH; if it persists, use the Copy button.	This panel/DSH boundary; no upstream GitNexus path.
Analyze runs out of memory	Keep the panel's NODE_OPTIONS / GITNEXUS_MEMORY settings, or raise the heap manually; the index may need a full rebuild.	gitnexus/README.md — Analysis runs out of memory, RUNBOOK.md — Memory / analyze crashes
A large file is missing from the graph	This is what the panel reports: size/share, generated/minified heuristics, binary detection. Raising the cap is an upstream analyze option; this plugin only reports the skip.	gitnexus/README.md — Large files are being skipped
Native install fails (@ladybugdb/core, tree-sitter-*)	The plugin runs npm install --prefix …; it needs a C++ toolchain and a reachable registry. Run the manual command from Getting GitNexus to see the compiler error.	gitnexus/README.md — Installation fails with native module errors
The panel does not appear at all	Check that dsh plugin add succeeded and DSH was restarted; open it from the sidebar's + guide page. For the desktop profile, use the Web Plugins page.	This plugin's install path; no upstream GitNexus path.

Upstream GitNexus documentation

This README describes the plugin, not GitNexus. GitNexus behavior follows its source docs. Repository: abhigyanpatwari/GitNexus (branch main).

Topic	Path
Install, CLI, environment variables, MCP	README.md
CLI package, requirements, full Troubleshooting	gitnexus/README.md
Index stale, clean slate, locks, memory	RUNBOOK.md
Architecture and data flow	ARCHITECTURE.md
Tests and guardrails	TESTING.md, GUARDRAILS.md
CLI command reference	gitnexus/skills/gitnexus-cli.md
Language-specific notes	docs/languages/

Local .docs/ notes are gitignored; the links above are the published source of truth.

Maintenance commands

The panel shows and runs more than a bare gitnexus analyze:

$env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; `
  $env:GITNEXUS_HOME='<repo>/.gitnexus/plugin-home'; `
  gitnexus analyze --index-only '<repo>'

Add --force for a full rebuild.

• GITNEXUS_MEMORY=off — stops the CLI from re-spawning itself 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 — redirects the global registry write into the project, so a failed write to ~/.gitnexus cannot leave the index stuck at incremental-in-progress.
• --index-only — otherwise analyze rewrites AGENTS.md, CLAUDE.md and skill files inside the repository.

--skip-fts is adaptive per index: no flag when the manifest says FTS is available, and the flag when it is not. skipFts: true can force the flag; there is no config that forces FTS on, because enabling it is a repair (gitnexus analyze --repair-fts), not an incremental refresh.

License (read before commercial use)

This plugin is MIT (see LICENSE).

GitNexus is PolyForm-Noncommercial-1.0.0: noncommercial use is granted, commercial use is restricted. gitnexus is a peer; this package does not install, bundle or redistribute it. But using this plugin's GitNexus-backed features (reading an index, refreshing it, installing it) puts your use of GitNexus under GitNexus's license; commercial use needs a separate grant from GitNexus's author:

https://github.com/abhigyanpatwari/GitNexus/blob/main/LICENSE

In one line: MIT covers this plugin's code; GitNexus's license covers GitNexus, and using the related features puts that use under it.

Boundaries

• Coverage and search are read-only; maintenance is a separately confirmed write and never starts by itself.
• The plugin reports facts about a GitNexus index; it does not rewrite the parser or reimplement the graph database.
• Graph search matches names/paths, not bodies; the text fallback matches lines and is capped.
• The source fallback only covers files in the index manifest; refresh the index for new files.
• Deeper design/build notes are kept out of the public README; this file stays at the "what it does" and "how to fix it" level.