From ffc4b69004832e309ca3f0339cb75a311cdfbde1 Mon Sep 17 00:00:00 2001 From: Linus Beckhaus Date: Wed, 25 Feb 2026 13:05:17 +0100 Subject: [PATCH] feat(plugin): add marketplace, fix manifest, and add CLI commands skill Add .claude-plugin/marketplace.json at repo root so users can permanently install via `/plugin marketplace add nicosxt/gitnexus`. Remove invalid hooks/mcpServers fields from plugin.json (auto-discovered at default locations). Add cli skill covering all agent-relevant CLI commands (analyze, status, clean, wiki, list) with correct flags. Update guide skill and CLAUDE.md generator routing tables. --- .claude-plugin/marketplace.json | 19 +++++ .../.claude-plugin/plugin.json | 4 +- gitnexus-claude-plugin/skills/cli/SKILL.md | 82 +++++++++++++++++++ gitnexus-claude-plugin/skills/cli/mcp.json | 8 ++ gitnexus-claude-plugin/skills/guide/SKILL.md | 1 + gitnexus/skills/cli.md | 82 +++++++++++++++++++ gitnexus/skills/guide.md | 1 + gitnexus/src/cli/ai-context.ts | 5 ++ gitnexus/src/cli/setup.ts | 2 +- 9 files changed, 200 insertions(+), 4 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 gitnexus-claude-plugin/skills/cli/SKILL.md create mode 100644 gitnexus-claude-plugin/skills/cli/mcp.json create mode 100644 gitnexus/skills/cli.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 000000000..489be5599 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,19 @@ +{ + "name": "gitnexus-marketplace", + "owner": { + "name": "GitNexus", + "email": "nico@gitnexus.dev" + }, + "metadata": { + "description": "Code intelligence powered by a knowledge graph — execution flows, blast radius, and semantic search", + "homepage": "https://github.com/nicosxt/gitnexus" + }, + "plugins": [ + { + "name": "gitnexus", + "version": "1.2.8", + "source": "./gitnexus-claude-plugin", + "description": "Code intelligence powered by a knowledge graph. Provides execution flow tracing, blast radius analysis, and augmented search across your codebase." + } + ] +} diff --git a/gitnexus-claude-plugin/.claude-plugin/plugin.json b/gitnexus-claude-plugin/.claude-plugin/plugin.json index 53c40174e..b71c221c8 100644 --- a/gitnexus-claude-plugin/.claude-plugin/plugin.json +++ b/gitnexus-claude-plugin/.claude-plugin/plugin.json @@ -7,7 +7,5 @@ }, "homepage": "https://github.com/nicosxt/gitnexus", "repository": "https://github.com/nicosxt/gitnexus", - "keywords": ["code-intelligence", "knowledge-graph", "mcp", "static-analysis"], - "hooks": "./hooks", - "mcpServers": "./.mcp.json" + "keywords": ["code-intelligence", "knowledge-graph", "mcp", "static-analysis"] } diff --git a/gitnexus-claude-plugin/skills/cli/SKILL.md b/gitnexus-claude-plugin/skills/cli/SKILL.md new file mode 100644 index 000000000..05ef54fd3 --- /dev/null +++ b/gitnexus-claude-plugin/skills/cli/SKILL.md @@ -0,0 +1,82 @@ +--- +name: gitnexus-cli +description: GitNexus CLI commands — index, status, clean, and wiki generation +--- + +# GitNexus CLI Commands + +All commands work via `npx` — no global install required. + +## Commands + +### analyze — Build or refresh the index + +```bash +npx gitnexus 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 | +|------|--------| +| `--force` | Force full re-index even if up to date | +| `--embeddings` | Enable embedding generation for semantic search (off by default) | + +**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. + +### status — Check index freshness + +```bash +npx gitnexus 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 + +```bash +npx gitnexus 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 + +```bash +npx gitnexus wiki +``` + +Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use). + +| Flag | Effect | +|------|--------| +| `--force` | Force full regeneration | +| `--model ` | LLM model (default: minimax/minimax-m2.5) | +| `--base-url ` | LLM API base URL | +| `--api-key ` | LLM API key | +| `--concurrency ` | Parallel LLM calls (default: 3) | +| `--gist` | Publish wiki as a public GitHub Gist | + +### list — Show all indexed repos + +```bash +npx gitnexus list +``` + +Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information. + +## After Indexing + +1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded +2. 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**: Restart Claude Code to reload the MCP server +- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding diff --git a/gitnexus-claude-plugin/skills/cli/mcp.json b/gitnexus-claude-plugin/skills/cli/mcp.json new file mode 100644 index 000000000..cd02d4285 --- /dev/null +++ b/gitnexus-claude-plugin/skills/cli/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "gitnexus": { + "command": "npx", + "args": ["-y", "gitnexus@latest", "mcp"] + } + } +} diff --git a/gitnexus-claude-plugin/skills/guide/SKILL.md b/gitnexus-claude-plugin/skills/guide/SKILL.md index a069af6e7..0981b4661 100644 --- a/gitnexus-claude-plugin/skills/guide/SKILL.md +++ b/gitnexus-claude-plugin/skills/guide/SKILL.md @@ -26,6 +26,7 @@ For any task involving code understanding, debugging, impact analysis, or refact | Trace bugs / "Why is X failing?" | `debugging` | | Rename / extract / split / refactor | `refactoring` | | Tools, resources, schema reference | `guide` (this file) | +| Index, status, clean, wiki CLI commands | `cli` | ## Tools Reference diff --git a/gitnexus/skills/cli.md b/gitnexus/skills/cli.md new file mode 100644 index 000000000..05ef54fd3 --- /dev/null +++ b/gitnexus/skills/cli.md @@ -0,0 +1,82 @@ +--- +name: gitnexus-cli +description: GitNexus CLI commands — index, status, clean, and wiki generation +--- + +# GitNexus CLI Commands + +All commands work via `npx` — no global install required. + +## Commands + +### analyze — Build or refresh the index + +```bash +npx gitnexus 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 | +|------|--------| +| `--force` | Force full re-index even if up to date | +| `--embeddings` | Enable embedding generation for semantic search (off by default) | + +**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. + +### status — Check index freshness + +```bash +npx gitnexus 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 + +```bash +npx gitnexus 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 + +```bash +npx gitnexus wiki +``` + +Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use). + +| Flag | Effect | +|------|--------| +| `--force` | Force full regeneration | +| `--model ` | LLM model (default: minimax/minimax-m2.5) | +| `--base-url ` | LLM API base URL | +| `--api-key ` | LLM API key | +| `--concurrency ` | Parallel LLM calls (default: 3) | +| `--gist` | Publish wiki as a public GitHub Gist | + +### list — Show all indexed repos + +```bash +npx gitnexus list +``` + +Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information. + +## After Indexing + +1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded +2. 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**: Restart Claude Code to reload the MCP server +- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding diff --git a/gitnexus/skills/guide.md b/gitnexus/skills/guide.md index a069af6e7..0981b4661 100644 --- a/gitnexus/skills/guide.md +++ b/gitnexus/skills/guide.md @@ -26,6 +26,7 @@ For any task involving code understanding, debugging, impact analysis, or refact | Trace bugs / "Why is X failing?" | `debugging` | | Rename / extract / split / refactor | `refactoring` | | Tools, resources, schema reference | `guide` (this file) | +| Index, status, clean, wiki CLI commands | `cli` | ## Tools Reference diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts index ebb0ac56f..cc5597256 100644 --- a/gitnexus/src/cli/ai-context.ts +++ b/gitnexus/src/cli/ai-context.ts @@ -59,6 +59,7 @@ This project is indexed by GitNexus as **${projectName}** (${stats.nodes || 0} s | Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/debugging/SKILL.md\` | | Rename / extract / split / refactor | \`.claude/skills/gitnexus/refactoring/SKILL.md\` | | Tools, resources, schema reference | \`.claude/skills/gitnexus/guide/SKILL.md\` | +| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/cli/SKILL.md\` | ${GITNEXUS_END_MARKER}`; } @@ -144,6 +145,10 @@ async function installSkills(repoPath: string): Promise { name: 'guide', description: 'GitNexus quickstart — tools, resources, schema, and workflow reference', }, + { + name: 'cli', + description: 'GitNexus CLI commands — index, status, clean, and wiki generation', + }, ]; for (const skill of skills) { diff --git a/gitnexus/src/cli/setup.ts b/gitnexus/src/cli/setup.ts index 34554ce47..6dc23d813 100644 --- a/gitnexus/src/cli/setup.ts +++ b/gitnexus/src/cli/setup.ts @@ -217,7 +217,7 @@ async function setupOpenCode(result: SetupResult): Promise { // ─── Skill Installation ─────────────────────────────────────────── -const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring', 'guide']; +const SKILL_NAMES = ['exploring', 'debugging', 'impact-analysis', 'refactoring', 'guide', 'cli']; /** * Install GitNexus skills to a target directory.