feat: Add a "watch" command，an opt-in auto sync and analysis loop

[im-fan]

Summary

Adds an explicit gitnexus watch CLI entrypoint for long-running auto-sync, replacing env-flag startup with config-driven watch lifecycle controls. The watch flow now supports
branch fallback, per-repo git timeouts, status/lock files, commit info output, and analyze failure threshold skipping.

Motivation / context

Auto-sync needed a safer and more inspectable operating model than implicit startup via AUTO_UPDATE_AND_ANALYZE_FLAG. This change makes watch behavior explicit through
GITNEXUS_HOME/watch_config. yml, prevents duplicate watch processes per GITNEXUS_HOME, and records runtime state for operators.

Areas touched

• gitnexus/ (CLI / core / MCP server)
• gitnexus-web/ (Vite / React UI)
• . github/ (workflows, actions)
• eval/ or other tooling
• Docs / agent config only (README. md, package README)

Scope & constraints

In scope

• Add gitnexus watch [init|start|restart|stop|status].
• Load watch config from GITNEXUS_HOME/watch_config.yml.
• Move watch runtime files under GITNEXUS_HOME/watch/.
• Add PID, lock, and status file handling for single-instance watch execution.
• Support branches with legacy branch compatibility.
• Try configured branches in order and skip repos when all branches fail or time out.
• Restrict auto-sync remotes to SSH SCP URLs for github.com, gitlab.com, and gitee.com.
• Add per-repo git timeout parsing via repo_git_timeout.
• Add analyze consecutive failure tracking and analyze_failure_threshold.
• Write human-readable project_commit_info.txt.
• Update CLI help, i18n descriptions, README docs, and unit tests.

Explicitly out of scope / not done here

• No Web UI changes.
• No change to ordinary gitnexus analyze.
• No reset command for auto-sync failure counters.
• No support for multiple concurrent watch instances under one GITNEXUS_HOME.
• No migration tool for older auto-sync config/state files.

Implementation notes

• Removed implicit env-flag startup from CLI initialization; watch is now an explicit command.
• watch init creates a default config without overwriting an existing file.
• Auto-sync state now lives at GITNEXUS_HOME/watch/auto-sync-state.json.
• project_commit_info.txt is inspection-only; machine state remains JSON.
• Web/API clone repo-name compatibility is preserved through extractWebRepoName, while auto-sync keeps stricter remote/repo validation.
• Existing clone/pull gained auto-sync-only SSH support and branch-specific clone/pull behavior.

Testing & verification

• cd gitnexus && npm test

Focused unit coverage added/updated for:

• watch config parsing and validation
• branch fallback and unavailable branch handling
• analyze failure threshold skipping
• watch PID/lock/status lifecycle
• watch init and CLI help output
• auto-sync SSH clone path and timeout behavior
• web clone repo-name compatibility

Risk & rollout

This changes the auto-sync operating model from implicit env startup to explicit gitnexus watch. Operators using AUTO_UPDATE_AND_ANALYZE_FLAG must switch to gitnexus watch start and create GITNEXUS_HOME/watch_config.yml.

Runtime artifacts now move under GITNEXUS_HOME/watch/; stale older auto-sync state files outside that directory are not migrated automatically.

Index refresh is not required for existing repositories, but watch-managed repos will re-analyze when their configured branch commit changes or prior analysis failed.

[vercel]

Someone is attempting to deploy a commit to the NexusCore Team on Vercel.

A member of the Team first needs to authorize it.

[koriyoshi2041]

I checked the new watch-command PR locally at 9f49eea.

What I ran:

• cd gitnexus && npx tsc --noEmit -> passed
• cd gitnexus && npx prettier --check ../README.md README.md src/cli/help-i18n.ts src/cli/i18n/en.ts src/cli/i18n/zh-CN.ts src/cli/index.ts src/cli/watch.ts src/core/auto-sync/config.ts src/core/auto-sync/index.ts src/core/auto-sync/path-security.ts src/core/auto-sync/repo.ts src/core/auto-sync/runner.ts src/core/auto-sync/starter.ts src/core/auto-sync/state.ts src/server/api.ts src/server/git-clone.ts test/unit/auto-sync-runner.test.ts test/unit/auto-sync.test.ts test/unit/cli-index-help.test.ts test/unit/git-clone.test.ts test/unit/hooks.test.ts ../eslint-rules/require-safe-parse.mjs -> failed only on ../README.md and README.md
• cd gitnexus && npm test -- test/unit/auto-sync-runner.test.ts test/unit/auto-sync.test.ts test/unit/git-clone.test.ts test/unit/cli-index-help.test.ts test/unit/hooks.test.ts --reporter=dot -> 360 passed, 2 failed, 3 skipped

The two failures were both in existing hook-owner-guard cases (npx parent command line... and non-GitNexus ps line...). I reran the matching hook cases on current origin/main in the same environment and saw a baseline failure there too, so I would not treat those as introduced by this PR without a cleaner CI signal.

Actionable cleanup before review: run Prettier on the two README files and update/rebase the branch, since GitHub currently reports the PR as dirty against main.

[im-fan]

run Prettier README file is done . @koriyoshi2041

[koriyoshi2041]

Confirmed at d68999b: both README.md and gitnexus/README.md now pass the repository Prettier check. The branch is still 156 commits behind current main, though, and GitHub still reports it as conflicting, so the rebase/update part remains before this is ready for review.

[im-fan]

The complete branch merge has been completed @koriyoshi2041

[azizur100389]

Thanks for updating the branch. I rechecked the current head against current main.

I am still seeing a blocker in the existing shallow-clone branch fallback path. In cloneOrPull, an existing repo with a requested branch runs:

git fetch --depth 1 origin <branch>
git checkout <branch>

For a repo originally cloned as a single-branch shallow clone, for example --depth 1 --branch master, Git's fetch refspec only tracks that original branch. Fetching main this way can succeed but only update FETCH_HEAD; it does not create origin/main or a local main branch. The following git checkout main then fails with pathspec 'main' did not match any file(s) known to git.

That means watch can remain stuck when a configured fallback branch should take over, such as a repo renamed from master to main, until the operator manually deletes the clone.

Please fetch/update an explicit branch ref and check out/reset from that ref, for example fetch refs/heads/<branch>:refs/remotes/origin/<branch> and then create/reset the local branch from origin/<branch>. It would also be good to add a regression test using a real shallow single-branch clone, because the current auto-sync tests mock cloneOrPull and do not exercise this Git behavior.

[azizur100389]

Requesting changes: the shallow single-branch fallback bug is still present.

In gitnexus/src/server/git-clone.ts, the existing-clone branch path still runs git fetch --depth 1 origin <branch> and then git checkout <branch>. For a repo originally cloned with --depth 1 --branch master, fetching main this way can update only FETCH_HEAD; it does not create origin/main or a local main branch, so git checkout main fails with pathspec 'main' did not match any file(s) known to git.

Please fetch an explicit branch ref, for example refs/heads/<branch>:refs/remotes/origin/<branch>, then create/reset the local branch from origin/<branch>. Please also add a regression test using a real shallow single-branch clone, since the current tests do not exercise this Git behavior.