githits 0.1.7 → 0.1.9

package/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "githits-plugins",
+  "owner": {
+    "name": "GitHits",
+    "email": "support@githits.com"
+  },
+  "metadata": {
+    "description": "GitHits plugins for Claude Code - code examples from global open source",
+    "version": "0.1.9"
+  },
+  "plugins": [
+    {
+      "name": "githits",
+      "source": "./plugins/claude",
+      "description": "Code examples from global open source for developers and AI assistants",
+      "author": {
+        "name": "GitHits"
+      },
+      "homepage": "https://githits.com",
+      "repository": "https://github.com/githits-com/githits-cli",
+      "license": "Apache-2.0",
+      "keywords": ["code-search", "open-source", "examples"],
+      "category": "developer-tools"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "githits",
+  "version": "0.1.9",
+  "description": "Code examples from global open source for developers and AI assistants",
+  "author": {
+    "name": "GitHits"
+  },
+  "homepage": "https://githits.com",
+  "repository": "https://github.com/githits-com/githits-cli",
+  "license": "Apache-2.0",
+  "keywords": ["githits", "code-examples", "search", "mcp", "ai"]
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "githits": {
+      "command": "npx",
+      "args": ["-y", "githits@latest", "mcp", "start"]
+    }
+  }
+}

package/.plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "githits",
+  "version": "0.1.9",
+  "description": "Code examples from global open source for developers and AI assistants",
+  "author": {
+    "name": "GitHits"
+  },
+  "homepage": "https://githits.com",
+  "repository": "https://github.com/githits-com/githits-cli",
+  "license": "Apache-2.0",
+  "keywords": ["githits", "code-examples", "search", "mcp", "ai"]
+}

package/GEMINI.md

@@ -0,0 +1,75 @@
+# GitHits
+
+Code examples from global open source for developers and AI assistants.
+
+## Available Tools
+
+### search
+
+Find code examples from open source repositories.
+
+**Parameters:**
+
+- `query` (string, required) - natural language description of what you need
+- `language` (string, required) - programming language name (use `search_language` to verify)
+- `license_mode` (string, optional) - one of `strict` (default), `yolo`, or `custom`
+
+### search_language
+
+Look up supported programming language names. Use this before calling `search` to get the correct language identifier.
+
+**Parameters:**
+
+- `query` (string, required) - partial or full language name to look up
+
+### feedback
+
+Rate a search result. Submit feedback after each search to improve future result quality.
+
+**Parameters:**
+
+- `solution_id` (string, required) - the ID of the search result
+- `accepted` (boolean, required) - whether the result was useful
+- `feedback_text` (string, optional) - additional context about why the result was or was not helpful
+
+## When to Use
+
+Use `search` when:
+
+- You are stuck or blocked on an implementation problem
+- You need up-to-date examples for an API, library, or framework
+- The user mentions GitHits or asks you to search for code examples
+- You encounter an error you cannot resolve from your training data
+
+Do not use `search` for:
+
+- General knowledge questions that do not require code examples
+- Problems you can already solve confidently
+
+## Authentication
+
+- If any GitHits tool returns an authentication error, immediately run
+  `npx -y githits login` in the terminal. This opens the user's browser for
+  quick OAuth approval. Wait for the command to complete, then retry the
+  original tool call.
+- If the environment has no display (SSH, containers), use
+  `npx -y githits login --no-browser` instead, which prints a URL for the
+  user to open on another device.
+- Do NOT ask the user to run login manually - handle it automatically.
+- If login fails, inform the user of the error.
+
+## How to Search Well
+
+- Call `search_language` first to confirm the correct language name before calling `search`
+- Formulate queries as natural language questions (e.g., "How to stream responses with the Vercel AI SDK in Next.js")
+- Include specific error messages, library names, or API names when relevant
+- Keep queries focused: 3-4 technical terms maximum
+- Submit `feedback` after every search result you use or discard
+
+## License Filtering
+
+Results respect license filtering by default. Three modes:
+
+- **strict** (default) - excludes copyleft licenses
+- **yolo** - includes all licenses
+- **custom** - uses the user's blocklist configured at githits.com

package/README.md

@@ -14,11 +14,81 @@ npx githits init
 
 Supported tools: Claude Code, Cursor, Windsurf, VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Gemini CLI, and Google Antigravity.
 
-That's it. Your assistant now has a `search` tool it will use automatically when it needs code examples.
+If you are using a tool that is not listed above, use the manual MCP setup instructions near the end of this README.
+
+### Plugin Installation (Open Plugin standard)
+
+The npm package includes Open Plugin-compatible files:
+
+- `.plugin/plugin.json` (vendor-neutral, used by Cursor/Codex/Copilot-compatible hosts)
+- `.claude-plugin/plugin.json` (Claude Code compatibility)
+- `.claude-plugin/marketplace.json` (Claude Code marketplace catalog)
+- `.mcp.json` (Open Plugin MCP server config for plugin hosts)
+- `plugins/claude/` (Claude plugin runtime payload: `.claude-plugin/plugin.json`, `.mcp.json`, `skills/`, and `commands/`)
+
+Root `.claude-plugin/marketplace.json` provides marketplace metadata. Claude Code
+loads the plugin runtime payload from `plugins/claude/`.
+
+**Claude Code Plugin (Marketplace)**
+
+Install from terminal (recommended):
+
+```sh
+claude plugin marketplace add githits-com/githits-cli
+claude plugin install githits@githits-plugins
+```
+
+This is preferred over in-session install so the plugin is loaded cleanly on
+next `claude` launch.
+
+Alternative (inside Claude input):
+
+```sh
+/plugin marketplace add githits-com/githits-cli
+/plugin install githits@githits-plugins
+```
+
+If installed inside a running Claude session, reload/restart Claude if the
+plugin is not immediately available.
+
+For unpublished/local testing of this repository:
+
+```sh
+claude plugin marketplace add "$PWD"
+claude plugin install githits@githits-plugins
+```
+
+By default, the plugin starts MCP with `npx -y githits@latest mcp start` so installs track the latest published GitHits CLI.
+
+For unpublished/local testing, install from your local repository path and verify behavior in your host before publishing.
+
+In Claude Code, run `/mcp` and confirm `plugin:githits:githits` is listed for the plugin path.
+
+Note: when running Claude in this repository directory, root `.mcp.json` can also register `githits` for project-level MCP. For plugin-only attribution during testing, run Claude from a different working directory.
+
+**Gemini CLI extension install**
+
+```sh
+gemini extensions install https://github.com/githits-com/githits-cli
+```
+
+For plugin-based hosts, install from npm/GitHub using your agent's plugin workflow and enable plugin `githits`.
+
+### Agent Coverage
+
+- **Cursor**: reads vendor-neutral `.plugin/` for Open Plugin installs
+- **Claude Code**: supports `.claude-plugin/` and Open Plugin components
+- **Codex**: supports Open Plugin components
+- **GitHub Copilot**: supports Open Plugin components
+- **Gemini CLI**: supports `gemini-extension.json` and `GEMINI.md`
+
+That's it. Your assistant now has GitHits search tools, and on accounts with package/source access enabled it also gets dependency inspection tools.
 
 ## How It Works
 
-GitHits runs as an [MCP server](https://modelcontextprotocol.io/) that your AI assistant connects to over stdio. The assistant gets three tools:
+GitHits runs as an [MCP server](https://modelcontextprotocol.io/) that your AI assistant connects to over stdio.
+
+Core tools available in every authenticated session:
 
 | Tool | Purpose |
 |---|---|
@@ -28,6 +98,21 @@ GitHits runs as an [MCP server](https://modelcontextprotocol.io/) that your AI a
 
 The assistant decides when to call these tools on its own — typically when it's stuck, needs a working example for an unfamiliar API, or encounters an error it can't resolve from its training data alone.
 
+When package/source access is enabled for the current token, GitHits also exposes these capability-gated tools:
+
+| Tool | Purpose |
+|---|---|
+| `package_summary` | Quick package overview: version, license, downloads, quickstart, advisories |
+| `package_vulnerabilities` | CVE / OSV advisories for a package or specific version |
+| `package_dependencies` | Direct dependencies, dependency groups, and optional transitive graph |
+| `package_changelog` | Release notes / changelog entries for a package or GitHub repo |
+| `search_symbols` | Exact-token search inside indexed dependency source |
+| `list_files` | Discover what files a dependency or repo contains |
+| `read_file` | Read a dependency file by path |
+| `grep_file` | Search for a case-insensitive substring within one file |
+
+These advanced tools remain feature-gated. The MCP server advertises them only when the authenticated token is entitled to package/source access.
+
 ### License Filtering
 
 Search results respect license filtering by default, excluding copyleft-licensed code. Three modes are available:
@@ -73,6 +158,13 @@ githits mcp start      Always start MCP server (for use in MCP config files)
 githits auth status    Show current authentication status
 ```
 
+When package/source access is enabled for the current token, two extra command groups are also available:
+
+```
+githits pkg ...        Package metadata: overview, advisories, deps, changelog
+githits code ...       Dependency source inspection: search, files, read, grep
+```
+
 ## Environment Variables
 
 | Variable | Purpose | Default |
@@ -80,6 +172,35 @@ githits auth status    Show current authentication status
 | `GITHITS_API_TOKEN` | API token for authentication | — |
 | `GITHITS_MCP_URL` | Override MCP server URL | `https://mcp.githits.com` |
 | `GITHITS_API_URL` | Override REST API URL | `https://api.githits.com` |
+| `GITHITS_CODE_NAV_URL` | Override package/source service URL | environment-specific |
+| `GITHITS_CODE_NAVIGATION` | Expose hidden `pkg` / `code` command groups locally | — |
+
+## Manual Setup
+
+If your tool is not in the supported `githits init` list, configure GitHits manually.
+
+The same MCP server command exposes both the core search tools and, when your token is entitled, the package/source inspection tools. No separate install is required.
+
+Use this MCP server command in your tool's MCP config (the host/agent runs this command):
+
+```sh
+npx -y githits@latest mcp start
+```
+
+A typical MCP config looks like this (check your tool's docs for exact schema/key names):
+
+```json
+{
+  "mcpServers": {
+    "githits": {
+      "command": "npx",
+      "args": ["-y", "githits@latest", "mcp", "start"]
+    }
+  }
+}
+```
+
+If you'd like another tool to be included in `githits init` for auto-configuration, open an issue or PR.
 
 ## Development
 

package/commands/help.md

@@ -0,0 +1,46 @@
+---
+description: Show available GitHits commands and usage
+disable-model-invocation: true
+---
+
+# GitHits Help
+
+Run the GitHits CLI help command in the terminal:
+
+```
+npx -y githits help
+```
+
+Then display the command output clearly to the user, followed by this plugin
+context summary:
+
+## Slash Commands
+
+- `/githits:search <query>` — Search for code examples from open source.
+- `/githits:login` — Authenticate with your GitHits account.
+- `/githits:status` — Show your current authentication status.
+- `/githits:logout` — Remove stored credentials.
+- `/githits:help` — Show this help message.
+
+## MCP Tools
+
+This plugin connects to the GitHits MCP server and exposes three tools:
+
+- **search** — Find code examples by describing what you need in natural
+  language. Requires `query` and `language` parameters.
+- **search_language** — Look up supported programming language names before
+  searching.
+- **feedback** — Rate a search result to improve future quality.
+
+## Authentication
+
+Run `npx -y githits login` to authenticate via browser, or set the
+`GITHITS_API_TOKEN` environment variable for headless environments.
+
+If users want to verify MCP tools loaded, suggest `/mcp`.
+
+If the command fails, report the error and suggest running:
+
+```
+npx -y githits login
+```

package/commands/login.md

@@ -0,0 +1,36 @@
+---
+description: Log in to your GitHits account
+---
+
+# Login
+
+Authenticate the user with GitHits by running the CLI login command in the
+terminal:
+
+```
+npx -y githits login
+```
+
+This opens the user's browser for secure OAuth authentication. Tokens are stored
+locally and refreshed automatically.
+
+If the environment has no display (SSH, CI, containers), use the `--no-browser`
+flag instead:
+
+```
+npx -y githits login --no-browser
+```
+
+This prints a URL the user can open on another device.
+
+Other useful flags:
+
+- `--force` — re-authenticate even if already logged in.
+- `--port <port>` — use a specific port for the local callback server.
+
+After running the command, inform the user of the result. If login succeeds,
+confirm they are authenticated. If it fails, provide the error and suggest they
+try again.
+
+Alternative: the user can set the `GITHITS_API_TOKEN` environment variable
+instead of using browser login.

package/commands/logout.md

@@ -0,0 +1,16 @@
+---
+description: Log out of your GitHits account
+---
+
+# Logout
+
+Sign the user out of GitHits by running the CLI logout command in the terminal:
+
+```
+npx -y githits logout
+```
+
+This removes the locally stored authentication tokens.
+
+Confirm to the user that they have been logged out successfully. If the logout
+fails, provide the error details.

package/commands/search.md

@@ -0,0 +1,23 @@
+---
+description: Search for code examples from open source via GitHits
+---
+
+# Search
+
+Search for code examples using GitHits for the query: "$ARGUMENTS"
+
+Use the GitHits MCP `search` tool with the user's query. The tool requires two
+parameters:
+
+- **query**: The user's search query, formulated in natural language.
+- **language**: The programming language. If the language is unclear from
+  context, use the `search_language` tool first to find the correct language
+  name.
+
+Optional parameter:
+
+- **license_mode**: `"strict"` (default, excludes copyleft), `"yolo"` (all
+  licenses), or `"custom"` (user's blocklist).
+
+Present the results clearly. After the user has reviewed the result, use the
+`feedback` tool to report whether the example was helpful.

package/commands/status.md

@@ -0,0 +1,22 @@
+---
+description: Show your GitHits authentication status
+---
+
+# Status
+
+Check the user's current GitHits authentication status by running the CLI
+command in the terminal:
+
+```
+npx -y githits auth status
+```
+
+This shows whether the user is authenticated, where credentials are sourced
+from, and token expiry details when available.
+
+After running the command, report the status clearly. If the user is not
+authenticated, suggest running:
+
+```
+npx -y githits login
+```