mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-10-12 03:48:38 +00:00

feat: add gitnexus auto-sync for scheduled remote clone and analyze (#2493 )

* adds an opt-in auto sync and analysis loop for GitNexus

* adds an opt-in auto sync and analysis loop for GitNexus,gitnexus watch [init|start|restart|stop|status]

* adds an opt-in auto sync and analysis loop for GitNexus,gitnexus watch [init|start|restart|stop|status]

* fix: address PR review cleanup

* Prettier code style

* merge main

* fix(watch): protect local repos and cancel active analysis

* fix(watch): harden auto-sync lifecycle and locking

- validate watch process identity before lifecycle operations\n- serialize registry, analysis, and LadybugDB access with recoverable locks\n- harden clone paths, symlinks, hooks, quarantine, and worker timeouts\n- install procps in the CLI image for reliable Docker watch control\n- add focused regression coverage for lifecycle, locks, clone, and registry behavior

* update agents & claude md

* merge main

* fix(watch): harden auto-sync lifecycle

* fix(watch): normalize SSH repo identity paths

* fix(watch): normalize SSH repo identity paths

* fix(watch): safely cancel analysis across platforms

* fix(auto-sync): close worker and group sync failure paths

* fix(auto-sync): drop retired allowStale from group sync

allowStale was removed from SyncOptions, which broke typecheck and CI on this PR.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(watch): satisfy prefer-const and Prettier in auto-sync

The watch timers are assigned exactly once, so prefer-const rejected the
deferred `let` declarations. They are only read from `stop()` and the control
poll, both of which run after the assignments, so binding them at creation is
safe and drops the now-dead undefined guards.

Remaining files are formatting only.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(watch): make lock identity absolute and stop three fail-open paths

Lock owner identity was rendered by `ps -o lstart=` through localtime and the
active locale, so the same live process produced a different string under a
different TZ. A mismatch reads as PID reuse, so one daemon could reclaim a
mutex another still held. Pin TZ=UTC and LC_ALL=C.

The owner record also carried no hostname, so a holder on another machine was
judged by this kernel's view of its PID — always "stale" — and its lock stolen
whenever GITNEXUS_HOME is a shared volume. Record and compare the hostname, as
the index lock already does.

Ownership verification threw unconditionally on win32, which is reached once
per project per tick, so watch reported `running` and then failed every repo
forever. POSIX uid/mode cannot be checked there; skip those two assertions and
keep the dangerous-root, symlink, containment and internal-root guards.

Also: quarantine sweep now refuses a symlinked root instead of deleting
through it; an unreadable state file propagates instead of being rewritten as
empty state, which used to erase every repo's analyzed commit and failure
count; a failed staging cleanup no longer strands a published lock with no
release handle; and the concurrency runner settles every worker before
surfacing a failure so cancellation cannot orphan a live analyze fork.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(watch): land the deferred review findings

Six findings that were deferred from the review backlog, plus the docs they
change.

Worker heap: admission allowed `floor(availableMemoryGB / 2)` slots while every
fork was handed the whole machine's heap cap, so the budget meant nothing as
soon as an operator raised max_concurrency. Divide the cap by the repos
actually analyzed in parallel. The default single-project path is unchanged.

Registration: the parent registered without a branch, so it always took the
primary/flat arm and relabelled a pinned branch entry on the branch-fallback
path. Reproduce the worker's own resolveBranchPlacement decision instead.

Cancellation: requestCancellation cleared the only timer and settled nothing,
so a worker wedged past its safe point left the promise pending forever,
wedging activeRun and hanging `watch stop`. Add a 5s grace after which the
parent stops waiting and releases the IPC channel's hold on its event loop.
The child is still never killed — it may be inside native work.

overwrite_local_changes: `checkout --force` rewrites tracked files only, so
untracked sources survived and were indexed as if they came from the remote.
`git clean -fd -e /.gitnexus` after checkout; no -x/-X, so ignored paths and
GitNexus's own storage survive.

Quarantine: age alone never bounds a repo that fails every tick, since each
partial clone is younger than the retention window. Keep the five newest per
repo.

Validation: repo_git_timeout is now bounded by the lesser of an hour and the
sync interval, which is also the guard for the bare-number-means-seconds slip
(`600000` meant ~7 days and cleared the timer ceiling). And the remote URL's
final segment is validated at config load rather than failing once per tick
inside the sync loop.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(watch): release an errored worker, and stop rejecting dotted repo names

Three findings from the latest review pass.

The 'error' handler settles immediately rather than waiting out the grace, so
cleanup() clears the grace timer that would otherwise have released the child.
An errored IPC channel does not mean the worker stopped, so release it on that
path too — still no kill.

The traversal guard tested the raw path for '..', which also rejected an
ordinary name like owner/foo..bar that the repository-name rule accepts.
Traversal is a whole segment, so test segments.

The heap-cap test left two runs and their real timers pending; it now stubs
timers and settles both promises. Registration coverage now pins the branch
slot rather than leaving it implicit.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(watch): validate namespace segments and pin the stopped process identity

Replacing the raw-string `..` test with a per-segment one dropped a guard: a
segment like `..\..\outside` is not literally `..`, so it passed, and those
segments build the clone path — on Windows the backslashes are separators.
Hold every namespace segment to the same charset as the repo name, which keeps
a separator out of a segment while still allowing an ordinary `foo..bar`. The
final segment keeps its own check so a bad repo name keeps its own message.

The stop wait polled liveness by pid alone, so a pid reused mid-wait would
have it wait on an unrelated process and then report the watch stopped. Compare
the process start time recorded for the owner, which also returns sooner.

Registration now omits `branch` for a primary index instead of passing it as
undefined, so that call keeps the shape it had before this branch.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(cli): ship auto-sync as the remote daemon, reserve gitnexus watch.

Keep analyze --watch for local incremental re-index and stop the top-level watch verb from starting a clone/pull loop.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(auto-sync): reject invalid branch refs and verify status identity (#2493)

Reject leading slashes and per-component trailing dots in configured branches, and verify the live watch owner before trusting a stored error status.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(auto-sync): reject ownerIds that can escape the watch directory (#2493)

Stop interpolating a tampered ownerId into the stop-request filename; only basename-safe values are treated as owners.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(auto-sync): recognize auto-sync in the watch-process identity check (#2493)

Stop/status were still looking for a standalone watch token after the command rename, so a live gitnexus auto-sync start process would be refused as unrelated.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore(autofix): apply prettier + eslint fixes via /autofix command

* fix(auto-sync): reject boolean max_concurrency instead of coercing it to 1 (#2493)

Number(true) is 1, so a YAML boolean would have passed the integer check and silently meant one worker.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(auto-sync): swallow status errors in the watch finally path (#2493)

An uncaught updateStatus rejection in finally became an unhandled
rejection. Skip the clone-root symlink test on Windows, where directory
symlinks need privileges. Align the group-lock comment with fail-closed
registry timeouts.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(auto-sync): catch cancelling status-write failures (#2493)

Fire-and-forget updateStatus('cancelling') could become an unhandled
rejection, the same class as the finally-path status write.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(auto-sync): ignore queued interval ticks after stop (#2493)

clearInterval does not cancel a timer callback already queued. Guard
runSafely on stopping so shutdown cannot start a new un-cancellable run.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(auto-sync): report stored watch status timestamps (#2493)

status should show when the watch last entered a state, not when the
CLI queried it. The failure-count test still expects 1 after a new
commit resets the streak; rename it so that reset is explicit.

Co-authored-by: Cursor <cursoragent@cursor.com>

* style(auto-sync): apply prettier to starter status logger (#2493)

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: weiyf <weiyf3634@163.com>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: Gergo Magyar <gergomagyar0@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

2026-09-02 19:40:18 +01:00

7.1 KiB

Raw Blame History

name	description
gitnexus-cli	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"

GitNexus CLI Commands

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.

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.

Commands

analyze — Build or refresh the index

node .gitnexus/run.cjs analyze

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.

Flag	Effect
`--watch`	Keep a Git repository index current with serialized refreshes
`--debounce <ms>`	Watch quiet period before refresh (default: 300 ms)
`--force`	Force full re-index even if up to date
`--embeddings`	Enable embedding generation for semantic search (off by default)
`--drop-embeddings`	Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them.
`--pdg`	Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF).
`--spring-actuator <path>`	Import opt-in Spring Boot Actuator mappings, beans, conditions, configprops, and env snapshots. Forces a full rebuild; unsupported with `--watch`.

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.

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.

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.

status — Check index freshness

node .gitnexus/run.cjs status

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.

clean — Delete the index

node .gitnexus/run.cjs clean

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.

Flag	Effect
`--force`	Skip confirmation prompt
`--all`	Clean all indexed repos, not just the current one

wiki — Generate documentation from the graph

node .gitnexus/run.cjs wiki

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.

Flag	Effect
`--force`	Force full regeneration, also required to re-generate an existing wiki in a different language
`--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`.
`--model <model>`	LLM model (default: MiniMax-M3)
`--base-url <url>`	LLM API base URL
`--api-key <key>`	LLM API key
`--concurrency <n>`	Parallel LLM calls (default: 3)
`--timeout <seconds>`	LLM request timeout in seconds (default: disabled)
`--retries <n>`	Max LLM retry attempts per request (default: 3)
`--lang <lang>`	Output language for generated documentation (e.g. english, chinese, spanish, japanese)
`--gist`	Publish wiki as a public GitHub Gist

list — Show all indexed repos

node .gitnexus/run.cjs list

Lists all repositories registered in ~/.gitnexus/registry.json. The MCP list_repos tool provides the same information.

After Indexing

Read gitnexus://repo/{name}/context to verify the index loaded
Use the other GitNexus skills (exploring, debugging, impact-analysis, refactoring) for your task

Troubleshooting

"Not inside a git repository": Run from a directory inside a git repo
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
Embeddings slow: Omit --embeddings (it's off by default) or set OPENAI_API_KEY for faster API-based embedding

7.1 KiB Raw Blame History