Skip to content

RUNBOOK.md

Latest commit

 

History

History
163 lines (103 loc) · 4.05 KB

RUNBOOK.md

File metadata and controls

163 lines (103 loc) · 4.05 KB

Runbook — GitNexus

Short, copy-paste operations for local development, MCP, and CI. Commands assume a Unix shell; on Windows use Git Bash or equivalent paths.

Prerequisites

  • Node.js ≥ 20 (gitnexus-web/package.json engines).
  • Git (analyze requires a git repository).
  • From repo root, install and build the CLI package:
cd gitnexus
npm install
npm run build

Use npx gitnexus … from any path after global/published install, or node dist/cli/index.js … when developing from gitnexus/ with a local build.

Index out of date / “stale” tools

Symptom: MCP or resources warn the index is behind HEAD, or results don’t reflect recent commits.

Fix (from the target repo root):

npx gitnexus analyze

Force full rebuild (same commit but suspect corruption or changed ignore rules):

npx gitnexus analyze --force

Check status:

npx gitnexus status

List what MCP knows about:

npx gitnexus list

Embeddings

First time with vectors (slower, more disk/RAM):

npx gitnexus analyze --embeddings

Important: If you already had embeddings, always pass --embeddings on later analyzes, or they can be dropped. See stats.embeddings in .gitnexus/meta.json (0 means none).

Large repos: Analyze may skip or limit embedding work when node counts are very high; watch CLI output.

MCP: no repos / empty tools

Symptom: GitNexus: No indexed repos yet on stderr when starting MCP.

Fix: In each project you want indexed:

cd /path/to/repo
npx gitnexus analyze

Restart the editor MCP session if needed. The server refreshes the registry lazily; new analyzes are picked up without necessarily reinstalling MCP.

Symptom: Wrong repo when multiple are indexed — pass repo on tools or use list_repos first.

Clean slate (corrupt or huge .gitnexus)

Current repo only (prompts for confirmation):

npx gitnexus clean

Skip confirmation:

npx gitnexus clean --force

All registered repos:

npx gitnexus clean --all --force

Then re-run npx gitnexus analyze (and --embeddings if you need vectors).

Local bridge for the web UI

cd gitnexus
npx gitnexus serve
# default http://127.0.0.1:4747 — see serve --help for port/host

Use when the browser UI should talk to local indexed repos instead of WASM-only mode.

CLI equivalents of MCP tools

Useful for debugging without an editor:

cd gitnexus
npx gitnexus query "authentication flow" --repo MyRepo
npx gitnexus context SomeSymbol --repo MyRepo
npx gitnexus impact SomeSymbol --direction upstream --repo MyRepo
npx gitnexus cypher "MATCH (n) RETURN count(n) LIMIT 1" --repo MyRepo

CI failures (contributors)

Orchestrator: .github/workflows/ci.yml.

Job Typical local repro
quality cd gitnexus && npx tsc --noEmit
unit-tests cd gitnexus && npx vitest run test/unit
integration cd gitnexus && npx vitest run test/integration (see workflow matrix for groups)
e2e Triggered when gitnexus-web/ changes; cd gitnexus-web && E2E=1 npx playwright test (requires gitnexus serve + npm run dev)

Note: Pushes that touch only certain markdown paths may be skipped by paths-ignore in CI — see workflow file for exact patterns.

Memory / analyze crashes

Analyze re-execs Node with a large old-space heap when needed (analyze.ts). If you still OOM on huge repos, close other processes, avoid --embeddings for a first pass, or analyze a smaller path if supported by your workflow.

LadybugDB / lock errors

Only one process should open a repo’s .gitnexus/lbug store at a time. If MCP and a second analyze run conflict, stop one process, then retry analyze or restart MCP.

Where to dig deeper