Skip to content

Commit 1b51dc4

Browse files
authored
fix: fail fast mac notarization agreement preflight (#411)
1 parent ef90371 commit 1b51dc4

576 files changed

Lines changed: 13190 additions & 36 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
name: gitnexus-cli
3+
description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
4+
---
5+
6+
# GitNexus CLI Commands
7+
8+
Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `bunx`, else `npx`), so no package-manager assumption and no global install is required — including on a bun-only machine, which has no npm, npx or pnpm at all.
9+
10+
> **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root, or `bunx gitnexus@latest analyze` on a bun-only machine. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`), or use `bunx gitnexus@latest analyze`, or `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).
11+
12+
## Commands
13+
14+
### analyze — Build or refresh the index
15+
16+
```bash
17+
node .gitnexus/run.cjs analyze
18+
```
19+
20+
Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
21+
22+
| Flag | Effect |
23+
| -------------- | ---------------------------------------------------------------- |
24+
| `--watch` | Keep a Git repository index current with serialized refreshes |
25+
| `--debounce <ms>` | Watch quiet period before refresh (default: 300 ms) |
26+
| `--force` | Force full re-index even if up to date |
27+
| `--embeddings` | Enable embedding generation for semantic search (off by default) |
28+
| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
29+
| `--pdg` | Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF). |
30+
| `--spring-actuator <path>` | Import opt-in Spring Boot Actuator mappings, beans, conditions, configprops, and env snapshots. Forces a full rebuild; unsupported with `--watch`. |
31+
| `--asyncapi-spec <path>` | Read opt-in AsyncAPI 3.x documents (directory or single file) and mint `Destination` nodes from their operations. 2.x is refused, not mapped. Unsupported with `--watch`. |
32+
33+
**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
34+
35+
For Spring runtime enrichment, pass a JSON bundle, one endpoint JSON file, or a directory containing endpoint files. Route evidence is authoritative only when `runtimeConfirmed === true`; `runtimeSource` records provenance and may also accompany `handler-conflict`. Env/configprops values are never persisted.
36+
37+
## Index storage and retention
38+
39+
Default location is `<repo>/.gitnexus/`. Override with environment variables (also documented in README):
40+
41+
| Env | Effect |
42+
| --- | ------ |
43+
| `GITNEXUS_STORAGE_PATH` | One complete external index directory. Wins if both storage vars are set. |
44+
| `GITNEXUS_STORAGE_ROOT` | Absolute root; GitNexus creates an isolated `<repo-basename>-<12-hex>/` slot per repository. |
45+
| `GITNEXUS_CONTENT_RETENTION` | `full` (default) keeps file text; `symbol` keeps snippets; `none` keeps the graph only. |
46+
47+
`list_repos`, `gitnexus://repo/{name}/context`, and HTTP `GET /api/repos` / `GET /api/repo` expose `storagePath`, `contentRetention`, and `sourceAvailable`. HTTP `/api/file` and `/api/grep` return 410 unless retention is `full`. MCP `include_content` may still return symbol spans when retention is `symbol`.
48+
49+
Use `node .gitnexus/run.cjs analyze --watch` for a long-lived local Git repository. It performs an initial analysis, queues scanner-admitted file changes, and retries intact failed batches with bounded backoff. Watch refreshes update only the graph: they skip AGENTS.md / CLAUDE.md injection and standard skill installation, so run a one-shot `analyze` when those generated files need updating. Watch rejects one-shot or context-output flags including `--force`, embedding flags, `--skills`, `--default-branch`, `--skip-agents-md`, `--skip-skills`, `--no-stats`, `--self-commit`, `--index-only`, and `--skip-git`. It never pulls remotes. Scheduled remote clone/pull is a different command: `gitnexus auto-sync`. Bare `gitnexus watch` is reserved and does not start either job. Running MCP and `serve` processes periodically check for a published replacement and reopen it without a restart. MCP checks are throttled to once every five seconds, so a tool call before the next check can briefly use the previous index.
50+
51+
### status — Check index freshness
52+
53+
```bash
54+
node .gitnexus/run.cjs status
55+
```
56+
57+
Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.
58+
59+
### clean — Delete the index
60+
61+
```bash
62+
node .gitnexus/run.cjs clean
63+
```
64+
65+
Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.
66+
67+
| Flag | Effect |
68+
| --------- | ------------------------------------------------- |
69+
| `--force` | Skip confirmation prompt |
70+
| `--all` | Clean all indexed repos, not just the current one |
71+
72+
### wiki — Generate documentation from the graph
73+
74+
```bash
75+
node .gitnexus/run.cjs wiki
76+
```
77+
78+
Generates repository documentation from the knowledge graph using an LLM. HTTP providers require an API key (saved to `~/.gitnexus/config.json` on first use). Local CLI providers (`--provider cursor|claude|codex|opencode|grok`) use your existing CLI login.
79+
80+
| Flag | Effect |
81+
| ------------------- | ----------------------------------------- |
82+
| `--force` | Force full regeneration, also required to re-generate an existing wiki in a different language |
83+
| `--provider <name>` | LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax). Local CLIs (`cursor`, `claude`, `codex`, `opencode`, `grok`) use your existing CLI login and skip `--api-key`. |
84+
| `--model <model>` | LLM model (default: MiniMax-M3) |
85+
| `--base-url <url>` | LLM API base URL |
86+
| `--api-key <key>` | LLM API key |
87+
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
88+
| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
89+
| `--retries <n>` | Max LLM retry attempts per request (default: 3) |
90+
| `--lang <lang>` | Output language for generated documentation (e.g. english, chinese, spanish, japanese) |
91+
| `--gist` | Publish wiki as a public GitHub Gist |
92+
93+
### list — Show all indexed repos
94+
95+
```bash
96+
node .gitnexus/run.cjs list
97+
```
98+
99+
Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.
100+
101+
## After Indexing
102+
103+
1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
104+
2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task
105+
106+
## Troubleshooting
107+
108+
- **"Not inside a git repository"**: Run from a directory inside a git repo
109+
- **Index is stale after re-analyzing**: Wait for the next MCP tool call to reopen the published index; this normally takes no more than five seconds
110+
- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
name: gitnexus-debugging
3+
description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
4+
---
5+
6+
# Debugging with GitNexus
7+
8+
## When to Use
9+
10+
- "Why is this function failing?"
11+
- "Trace where this error comes from"
12+
- "Who calls this method?"
13+
- "This endpoint returns 500"
14+
- Investigating bugs, errors, or unexpected behavior
15+
16+
## Bind the repository first
17+
18+
A root cause traced in the wrong repository is a wrong root cause.
19+
20+
Call `list_repos {}` before the first tool call. With one indexed repository,
21+
use the examples below as written. With more than one, pass `repo` on every
22+
call: an omitted `repo` normally errors, but under an MCP policy with a
23+
configured default it resolves to that default silently. If you cannot tell
24+
which repository is meant, stop and ask. This matters most for `cypher`, whose
25+
statement carries no in-band hint of which database it ran against.
26+
27+
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
28+
`hasMore` is false before concluding a repository is absent.
29+
30+
A stale index describes the code from before your bug, so refresh before
31+
trusting a trace, and state the repository and index freshness with the
32+
diagnosis.
33+
34+
## Workflow
35+
36+
```
37+
0. list_repos {} → Bind repo
38+
1. query({search_query: "<error or symptom>"}) → Find related execution flows
39+
2. context({name: "<suspect>"}) → See callers/callees/processes
40+
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
41+
4. cypher({statement: "MATCH path..."}) → Custom traces if needed
42+
```
43+
44+
> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
45+
46+
## Checklist
47+
48+
```
49+
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
50+
- [ ] Understand the symptom (error message, unexpected behavior)
51+
- [ ] query for error text or related code
52+
- [ ] Identify the suspect function from returned processes
53+
- [ ] context to see callers and callees
54+
- [ ] Trace execution flow via process resource if applicable
55+
- [ ] cypher for custom call chain traces if needed
56+
- [ ] Read source files to confirm root cause
57+
- [ ] State the repository and index freshness with the diagnosis
58+
```
59+
60+
## Debugging Patterns
61+
62+
| Symptom | GitNexus Approach |
63+
| -------------------- | ---------------------------------------------------------- |
64+
| Error message | `query` for error text → `context` on throw sites |
65+
| Wrong return value | `context` on the function → trace callees for data flow |
66+
| Intermittent failure | `context` → look for external calls, async deps |
67+
| Performance issue | `context` → find symbols with many callers (hot paths) |
68+
| Recent regression | `detect_changes` to see what your changes affect — pass `worktree` for a linked worktree |
69+
| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
70+
71+
## Tools
72+
73+
**query** — find code related to error:
74+
75+
```
76+
query({search_query: "payment validation error", repo: "my-app"})
77+
→ Processes: CheckoutFlow, ErrorHandling
78+
→ Symbols: validatePayment, handlePaymentError, PaymentException
79+
```
80+
81+
**context** — full context for a suspect:
82+
83+
```
84+
context({name: "validatePayment", repo: "my-app"})
85+
→ Incoming calls: processCheckout, webhookHandler
86+
→ Outgoing calls: verifyCard, fetchRates (external API!)
87+
→ Processes: CheckoutFlow (step 3/7)
88+
```
89+
90+
**cypher** — custom call chain traces. Pass `repo` alongside the statement; the
91+
Cypher text itself names no repository, so the result is unattributable without
92+
it:
93+
94+
```cypher
95+
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
96+
RETURN [n IN nodes(path) | n.name] AS chain
97+
```
98+
99+
**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
100+
101+
```
102+
trace({ from: "processCheckout", to: "fetchRates", repo: "my-app" })
103+
→ status: ok, hopCount: 3
104+
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
105+
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
106+
```
107+
108+
When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
109+
110+
## Example: "Payment endpoint returns 500 intermittently"
111+
112+
```
113+
0. list_repos {}
114+
→ total: 2 (my-app, billing-api) — bind my-app explicitly on every call
115+
116+
1. query({search_query: "payment error handling", repo: "my-app"})
117+
→ Processes: CheckoutFlow, ErrorHandling
118+
→ Symbols: validatePayment, handlePaymentError
119+
120+
2. context({name: "validatePayment", repo: "my-app"})
121+
→ Outgoing calls: verifyCard, fetchRates (external API!)
122+
123+
3. READ gitnexus://repo/my-app/process/CheckoutFlow
124+
→ Step 3: validatePayment → calls fetchRates (external)
125+
126+
4. Root cause: fetchRates calls external API without proper timeout
127+
Repository: my-app Index: current
128+
```
129+
130+
With a single indexed repository, step 0 returns `total: 1` and the `repo`
131+
argument drops out of every call above.
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
name: gitnexus-exploring
3+
description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
4+
---
5+
6+
# Exploring Codebases with GitNexus
7+
8+
## When to Use
9+
10+
- "How does authentication work?"
11+
- "What's the project structure?"
12+
- "Show me the main components"
13+
- "Where is the database logic?"
14+
- Understanding code you haven't seen before
15+
16+
## Bind the repository first
17+
18+
Step 1 discovers what is indexed; every call after it must say which of those
19+
it means. With one indexed repository, use the examples below as written. With
20+
more than one, pass `repo` on every call: an omitted `repo` normally errors,
21+
but under an MCP policy with a configured default it resolves to that default
22+
silently. If you cannot tell which repository is meant, stop and ask. Report
23+
the bound repository and index freshness alongside your explanation.
24+
25+
`list_repos` is paginated, so page with `offset: pagination.nextOffset` until
26+
`hasMore` is false before concluding a repository is absent.
27+
28+
## Workflow
29+
30+
```
31+
1. list_repos {} or READ gitnexus://repos → Discover indexed repos
32+
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
33+
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
34+
4. context({name: "<symbol>"}) → Deep dive on specific symbol
35+
5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow
36+
```
37+
38+
> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
39+
40+
## Checklist
41+
42+
```
43+
- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous
44+
- [ ] READ gitnexus://repo/{name}/context
45+
- [ ] query for the concept you want to understand
46+
- [ ] Review returned processes (execution flows)
47+
- [ ] context on key symbols for callers/callees
48+
- [ ] READ process resource for full execution traces
49+
- [ ] Read source files for implementation details
50+
- [ ] State the repository and index freshness with the explanation
51+
```
52+
53+
## Resources
54+
55+
| Resource | What you get |
56+
| --------------------------------------- | ------------------------------------------------------- |
57+
| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
58+
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
59+
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
60+
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
61+
62+
## Tools
63+
64+
**query** — find execution flows related to a concept:
65+
66+
```
67+
query({search_query: "payment processing", repo: "my-app"})
68+
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
69+
→ Symbols grouped by flow with file locations
70+
```
71+
72+
**context** — 360-degree view of a symbol:
73+
74+
```
75+
context({name: "validateUser", repo: "my-app"})
76+
→ Incoming calls: loginHandler, apiMiddleware
77+
→ Outgoing calls: checkToken, getUserById
78+
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
79+
```
80+
81+
`repo` is required once more than one repository is indexed, and may be omitted
82+
with a single one.
83+
84+
## Example: "How does payment processing work?"
85+
86+
```
87+
1. list_repos {} → total: 1 (my-app) — bind it
88+
READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
89+
2. query({search_query: "payment processing"})
90+
→ CheckoutFlow: processPayment → validateCard → chargeStripe
91+
→ RefundFlow: initiateRefund → calculateRefund → processRefund
92+
3. context({name: "processPayment"})
93+
→ Incoming: checkoutHandler, webhookHandler
94+
→ Outgoing: validateCard, chargeStripe, saveTransaction
95+
4. Read src/payments/processor.ts for implementation details
96+
5. Answer, noting: Repository my-app, index current
97+
```
98+
99+
Had step 1 returned two repositories, every call above would carry
100+
`repo: "my-app"`.

0 commit comments

Comments
 (0)