GitNexus/gitnexus/src/cli
achianuri 0b877ce869 feat(cli): add --skip-skills and --index-only flags to analyze (resubmit of #742) (#1485)
* feat(cli): add --skip-skills and --index-only flags to analyze command

The `installSkills()` call in `generateAIContextFiles()` runs
unconditionally, injecting 6 skill files into `.claude/skills/gitnexus/`
even when `--skip-agents-md` is passed. This is problematic for bulk
indexing operations on read-only mirrors or third-party repos.

Add two new flags:
- `--skip-skills`: suppress standard GitNexus skill file injection
- `--index-only`: pure index mode that suppresses all file injection
  (AGENTS.md, CLAUDE.md, and skills), writing only to `.gitnexus/`

This gives users three levels of control:
- `--skip-agents-md` — suppress only root context files
- `--skip-skills` — suppress only skill injection
- `--index-only` — suppress everything (pure indexing)

Discovery context: while bulk-indexing 176 repos with
`--skip-agents-md`, all 144 indexed repos were contaminated with
`.claude/skills/gitnexus/` files requiring manual cleanup.

* fix(cli): address PR #742 review — gate community skills, drop dangling refs, add tests

Bot review (#742) flagged three issues with the original commit:

1. `--index-only --skills` still wrote community-derived skill files
   to `.claude/skills/generated/`. The `--skills` branch in analyze.ts
   was not gated by `skipAll`, so the "skip all file injection" contract
   was violated. Gate `generateSkillFiles()` with `!skipAll` so
   `--index-only` truly wins over `--skills`.

2. `--skip-skills` without `--skip-agents-md` produced AGENTS.md /
   CLAUDE.md that still referenced `.claude/skills/gitnexus/*/SKILL.md`
   files that were never installed — every agent load incurred 6
   failed reads. Pass `skipSkills` through to `generateGitNexusContent()`
   and omit the standard-skill rows (and the entire `## CLI` heading
   when the table is empty). Community skills, when present via
   `--skills`, are unaffected.

3. No filesystem tests for `skipSkills` / `indexOnly`. Add three
   regression guards to `test/unit/ai-context.test.ts`:
   - `.claude/skills/gitnexus/` is NOT created when skipSkills=true
   - Nothing is written when both skipAgentsMd and skipSkills are true
     (the resolved-flag state from --index-only)
   - AGENTS.md/CLAUDE.md routing table omits standard skill references
     when skipSkills=true, but preserves the load-bearing imperative
     sections (Always Do / Never Do / Resources)

* test(cli): PR 1485 review follow-ups (help text, gate test, --skip-skills docs)

- Assert --skip-skills and --index-only in analyze --help (skip-git-cli.test.ts).

- Export shouldGenerateCommunitySkillFiles; unit-test index-only+skills gate.

- Clarify --skip-skills does not suppress --skills community files; --index-only for full skip.

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

* fix(cli): warn when --index-only silently overrides --skills

Address review findings on PR 1485 follow-ups:
- analyze.ts emits a one-line note when both --index-only and --skills
  are set, so users see why a pipeline re-index ran with no skill files
  written.
- index.ts --skills help text now flags the --index-only override.
- shouldGenerateCommunitySkillFiles JSDoc documents the dual role of
  the gate (community skills + AGENTS.md/CLAUDE.md re-generation).
- skip-git-cli.test.ts pins the override-warning surface end-to-end.

---------

Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-11 15:00:58 +01:00
..
ai-context.ts feat(cli): add --skip-skills and --index-only flags to analyze (resubmit of #742) (#1485) 2026-05-11 15:00:58 +01:00
analyze.ts feat(cli): add --skip-skills and --index-only flags to analyze (resubmit of #742) (#1485) 2026-05-11 15:00:58 +01:00
augment.ts feat(cursor): upgrade hooks to Cursor 2.4 postToolUse for Read/Grep/Shell coverage (#1467) 2026-05-10 13:29:06 +01:00
clean.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
cli-message.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
doctor.ts fix: add platform-aware semantic fallback (#1150) 2026-04-28 12:21:25 +01:00
eval-server.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
group.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
index-repo.ts fix(cli): keep GitNexus ignores inside .gitnexus (#1248) 2026-05-01 16:46:05 +01:00
index.ts feat(cli): add --skip-skills and --index-only flags to analyze (resubmit of #742) (#1485) 2026-05-11 15:00:58 +01:00
lazy-action.ts feat: configure prettier with pre-commit hook (#563) 2026-03-28 14:58:04 +00:00
list.ts feat(cli): analyze --name <alias> + duplicate-name guard for the repo registry (#955) 2026-04-19 07:23:48 +01:00
mcp.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
optional-grammars.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
publish.ts feat(cli): add gitnexus publish for opt-in understand-quickly registry (#1425) 2026-05-09 09:52:26 +01:00
remove.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
serve.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
setup.ts fix(security): close URL/regex/tag-filter sanitization cluster (U7) (#1330) 2026-05-08 07:11:29 +01:00
skill-gen.ts feat: configure eslint with unused import removal (#564) 2026-03-28 15:28:09 +00:00
status.ts feat: configure prettier with pre-commit hook (#563) 2026-03-28 14:58:04 +00:00
tool.ts feat(core): adopt pino structured logger (#1336) 2026-05-07 20:56:25 +01:00
wiki.ts fix(security): close URL/regex/tag-filter sanitization cluster (U7) (#1330) 2026-05-08 07:11:29 +01:00