githits 0.6.6 → 0.7.0

package/.claude-plugin/marketplace.json

@@ -6,12 +6,12 @@
   },
   "metadata": {
     "description": "The code context layer for AI coding agents",
-    "version": "0.6.6"
+    "version": "0.7.0"
   },
   "plugins": [
     {
       "name": "githits",
-      "source": "./plugins/claude",
+      "version": "0.7.0",
       "description": "The code context layer for AI coding agents",
       "author": {
         "name": "GitHits"
@@ -19,7 +19,25 @@
       "homepage": "https://githits.com",
       "repository": "https://github.com/githits-com/githits-cli",
       "license": "Apache-2.0",
-      "keywords": ["code-search", "open-source", "examples"],
+      "keywords": [
+        "githits",
+        "context layer",
+        "public open-source",
+        "open-source code",
+        "code search",
+        "package documentation",
+        "documentation search",
+        "package metadata",
+        "vulnerabilities",
+        "changelogs",
+        "dependency graphs",
+        "upgrade evidence",
+        "implementation examples"
+      ],
+      "source": {
+        "source": "url",
+        "url": "https://github.com/githits-com/githits-cli.git"
+      },
       "category": "developer-tools"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "The code context layer for AI coding agents",
   "author": {
     "name": "GitHits"
@@ -8,5 +8,19 @@
   "homepage": "https://githits.com",
   "repository": "https://github.com/githits-com/githits-cli",
   "license": "Apache-2.0",
-  "keywords": ["githits", "code-examples", "search", "mcp", "ai"]
+  "keywords": [
+    "githits",
+    "context layer",
+    "public open-source",
+    "open-source code",
+    "code search",
+    "package documentation",
+    "documentation search",
+    "package metadata",
+    "vulnerabilities",
+    "changelogs",
+    "dependency graphs",
+    "upgrade evidence",
+    "implementation examples"
+  ]
 }

package/.codex-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "githits",
+  "version": "0.7.0",
+  "description": "The code context layer for AI coding agents",
+  "author": {
+    "name": "GitHits"
+  },
+  "homepage": "https://githits.com",
+  "repository": "https://github.com/githits-com/githits-cli",
+  "license": "Apache-2.0",
+  "keywords": [
+    "githits",
+    "context layer",
+    "public open-source",
+    "open-source code",
+    "code search",
+    "package documentation",
+    "documentation search",
+    "package metadata",
+    "vulnerabilities",
+    "changelogs",
+    "dependency graphs",
+    "upgrade evidence",
+    "implementation examples"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "GitHits",
+    "shortDescription": "The code context layer for AI coding agents",
+    "longDescription": "Search public open-source code, documentation, package metadata, vulnerabilities, changelogs, dependencies, and implementation examples.",
+    "developerName": "GitHits",
+    "category": "Developer Tools",
+    "capabilities": ["Code Search", "Documentation Search", "Package Research"],
+    "websiteURL": "https://githits.com",
+    "defaultPrompt": [
+      "Use GitHits to inspect this project's open-source dependencies.",
+      "Find source-backed examples for this implementation.",
+      "Research package documentation and upgrade risks."
+    ]
+  }
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "githits",
+  "version": "0.7.0",
+  "description": "The code context layer for AI coding agents",
+  "author": {
+    "name": "GitHits"
+  },
+  "homepage": "https://githits.com",
+  "repository": "https://github.com/githits-com/githits-cli",
+  "license": "Apache-2.0",
+  "keywords": [
+    "githits",
+    "context layer",
+    "public open-source",
+    "open-source code",
+    "code search",
+    "package documentation",
+    "documentation search",
+    "package metadata",
+    "vulnerabilities",
+    "changelogs",
+    "dependency graphs",
+    "upgrade evidence",
+    "implementation examples"
+  ],
+  "skills": "skills",
+  "mcpServers": ".mcp.json",
+  "logo": "github-githits.png"
+}

package/.mcp.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "githits": {
-      "command": "npx",
-      "args": ["-y", "githits@latest", "mcp", "start"]
+      "type": "http",
+      "url": "https://mcp.githits.com"
     }
   }
 }

package/.plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "githits",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "The code context layer for AI coding agents",
   "author": {
     "name": "GitHits"
@@ -8,5 +8,19 @@
   "homepage": "https://githits.com",
   "repository": "https://github.com/githits-com/githits-cli",
   "license": "Apache-2.0",
-  "keywords": ["githits", "code-examples", "search", "mcp", "ai"]
+  "keywords": [
+    "githits",
+    "context layer",
+    "public open-source",
+    "open-source code",
+    "code search",
+    "package documentation",
+    "documentation search",
+    "package metadata",
+    "vulnerabilities",
+    "changelogs",
+    "dependency graphs",
+    "upgrade evidence",
+    "implementation examples"
+  ]
 }

package/AGENTS.md

@@ -0,0 +1,201 @@
+# githits Agent Instructions
+
+GitHits companion for the backend - provides MCP server and command-line tools for code example search.
+
+We strive to produce high quality code that can easily be maintained. Focus is on long term development speed, not on quick wins.
+
+This document contains the most important instructions that need to be kept always in context.
+
+## General
+
+- Use very concise output and neutral tone
+- If unclear about anything or stuck, please stop and ask for clarification
+- Always verify assumptions
+- Don't jump into coding, plan and assess the impact first
+- Read more detailed documentation when needed
+- Remember your MCP tools and use them when needed
+
+## Architecture
+
+Philosophy: "Create architecture that is performant and easy to test"
+
+- Focus on building structures that are performant and scalable
+- Build architecture that is easy to test
+- Isolate functionality into sensible small modules
+- Follow single responsibility principle
+- Prefer public helper modules to lots of private methods
+- Use dependency injection for external services (REST client, etc.)
+- Do not eagerly validate network/proxy/environment configuration while constructing command dependencies when the command has local-only or no-network paths. Defer validation until the first network operation and add regression tests for malformed env values on local paths.
+- For MCP/agent-facing tools, avoid coupled optional flags and default-true booleans. Design schemas for real agent calls, including empty strings, empty arrays, and explicit `false` values.
+- For GraphQL/API-backed tools, treat minimal data fetching as part of the tool contract. Before adding or changing selected fields, compare the query against every consumer (text, verbose, JSON, MCP, CLI, and internal callers), use conditional fields or separate queries for mode-specific data, and add tests that assert the wire variables/selections for compact and detailed modes.
+
+See `docs/guidelines/ARCHITECTURAL_GUIDELINES.md` for detailed planning checklist and design principles.
+
+## Testing
+
+Philosophy: "If it is not tested, it is likely broken"
+
+**Critical Rules:**
+
+- Use `bun test` for running tests
+- Use `bun run smoke:mcp` and `bun run smoke:cli` when changing MCP tools, CLI commands, shared formatters, auth/error envelopes, or MCP/CLI parity behavior. These are live-capable local suites, not the normal unit suite; they must pass unauthenticated by validating auth handling, and provide deeper coverage when authenticated. After building, also run `bun run smoke:cli:built` and `bun run smoke:mcp:built` when changing smoke launch behavior or CI product validation; these secret-free modes execute `dist/cli.js` under Node.
+- Use `bun run agent:e2e` when changing MCP instructions, tool descriptions, or agent-facing tool behavior. This is a human/agent-driven qualitative eval, not a deterministic CI gate. Pick targeted workloads from `eval/agentic/README.md`; run both Claude and Codex for broad instruction changes when practical. Inspect `tool-calls.json` and `final.json` for actual tool use, `toolIssues`, `instructionIssues`, and usefulness, not just harness pass/fail.
+- Maintain smoke coverage when adding or changing user-facing tools/commands. Prefer structural UX assertions over brittle snapshots, and keep MCP `format: "json"` and CLI `--json` behavior aligned.
+- When changing GraphQL/API selections, add regression tests for over-fetch controls (for example `@include` variables, body omission, field lists, or query builders) and live-smoke the affected CLI/MCP surfaces when authenticated access is available.
+- Keep tests async and isolated
+- Mock services at the interface level using factory functions
+- Use mock factories from `test-helpers.ts` (e.g., `createMockGitHitsService()`, `createMockAuthService()`)
+- Test behavior, not implementation - focus on inputs and outputs
+- Test only one layer at a time - mock dependencies
+- When tests simulate another platform, simulate that platform's path semantics too. Use `path.win32` for Windows paths and avoid mixed literals like `C:\\Users\\me/app`; mixed separators can make tests pass while real Windows logic is broken.
+
+**Test Structure:**
+
+```typescript
+import { describe, expect, it, mock } from "bun:test";
+import { createMockGitHitsService } from "./test-helpers.js";
+
+describe("myTool", () => {
+  it("does something", async () => {
+    const mockService = createMockGitHitsService({
+      /* overrides */
+    });
+    // test...
+  });
+});
+```
+
+See `docs/guidelines/TESTING.md` for comprehensive patterns.
+
+## Development Workflow (Docs-driven)
+
+- Proposals -> Plans -> Implementation -> Completion
+- Keep docs updated as features evolve:
+  - Implementation notes: `docs/implementation/`
+  - Guidelines: `docs/guidelines/`
+- Use test driven development whenever possible
+- Document what and why with JSDoc comments
+
+## Plugin Asset Workflow
+
+- Root `skills/` and `AGENTS.md` are the only authored shared agent guidance. `CLAUDE.md` and `GEMINI.md` must remain symlinks to `AGENTS.md`.
+- Use the repository-internal `githits-plugin-maintenance` skill when changing skills, agent guidance, plugin/marketplace/extension manifests, MCP transport metadata, root release metadata, generator behavior, or agent-facing setup/auth behavior. It must remain under `.agents/skills/` and must not be published with the public root `skills/` tree.
+- Do not edit generated plugin assets directly. Change their canonical inputs, run `bun run plugins:generate`, inspect the diff, and run `bun run plugins:check`.
+- `server.json` owns the canonical plugin keyword list used by generated manifests; keep `package.json` aligned with it.
+- All plugin and extension packages use hosted remote MCP. Direct `githits init` configuration retains local stdio except for Cursor, which is remote-only. Claude and Gemini direct setup remove legacy plugin or extension state before installing the user-scoped stdio server.
+
+## TypeScript Essentials
+
+### Quick Start
+
+- Use `bun run dev` for development
+- Use `bun test` for testing
+- Use `bun run build` before committing
+
+### Code Style
+
+- Always add TypeScript types for function parameters and returns
+- Prefer interfaces to type aliases for object shapes
+- Use `const` assertions for literal types
+- Prefer explicit types over inference for public APIs
+- Use Zod for runtime validation
+
+### Patterns
+
+- **Dependency Injection**: Use factory functions that accept dependencies
+- **Service Layer**: Abstract external calls behind service interfaces
+- **Error Handling**: Use `withErrorHandling()` wrapper for consistent errors
+- **Tool Pattern**: Follow `ToolDefinition` interface for MCP tools
+
+## Workspace Boundaries
+
+- Root `src/**` is still the published `githits` CLI implementation until the CLI package move completes. It owns Commander commands, local auth storage, browser login, init/setup flows, local stdio MCP startup, and plugin/assistant packaging assets.
+- `packages/core-internal` is private source. It owns transport-neutral service clients, service interfaces, shared request/header/telemetry primitives, neutral service errors, PKCE helpers, and `TokenProvider`. Never publish or leak `@githits/core-internal` into public artifacts.
+- `packages/mcp` is the public `@githits/mcp` package. Its public tool/server API is `packages/mcp/src/index.ts`: transport-neutral MCP server creation, tool registration, descriptors, instructions, request-scoped service provider types, and MCP service types. Its public runtime/client API is `packages/mcp/src/client.ts`, exported as `@githits/mcp/client`, for remote MCP servers that need concrete service implementations and token/header/config helpers.
+- `@githits/mcp/smoke-test` is a public validation helper entrypoint for remote MCP servers. It exports smoke assertions and `runMcpSmoke()` without depending on local CLI startup.
+- `@githits/mcp/internal` is a workspace-only alias for root CLI transition helpers. External packages and the future remote MCP server repo must never import it. If remote server work needs something internal, promote the smallest stable API through `@githits/mcp` instead.
+- Public package artifacts for both root `githits` and `@githits/mcp` must not contain `@githits/core-internal`, `workspace:*`, `@githits/mcp/internal`, or private source aliases in JS, declarations, or manifests.
+
+## Release Boundaries
+
+- `githits` and `@githits/mcp` have separate release flows. They may be bumped together when both surfaces changed, but CLI-only changes should not bump `@githits/mcp`.
+- Root `githits` release versions must stay aligned with generated plugin/assistant manifests: `.plugin/plugin.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.cursor-plugin/plugin.json`, `.claude-plugin/marketplace.json`, and `gemini-extension.json`. The versionless Antigravity `plugin.json` and `mcp_config.json` must also be regenerated and checked.
+- `@githits/mcp` release versions live in `packages/mcp/package.json` and should change only for MCP package API, tool behavior, MCP instructions, schemas, MCP auth/error behavior, or remote-server-facing public type changes.
+- For coordinated CLI and MCP releases, keep the MCP minor aligned with the CLI minor for discoverability. The first MCP release for a CLI minor starts at `X.Y.0`; later MCP-package-visible changes in that CLI minor bump the MCP patch.
+- Successful `Main` runs on `main` trigger both root and MCP release workflows. The MCP workflow publishes only when the package version is not already published; manual dispatch is for recovery or dry runs.
+- Validate package behavior from outside root path aliases. Repo-local imports can hide package export-map or declaration problems.
+
+### Common Pitfalls
+
+- Not mocking services in tests
+- Missing error handling in async operations
+- Not updating `index.ts` exports when adding new modules
+
+## Commit & PR Guidelines
+
+### Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>: <description>
+
+[optional body with context]
+```
+
+**Types:**
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation only
+- `refactor:` - Code change that neither fixes a bug nor adds a feature
+- `test:` - Adding or updating tests
+- `chore:` - Maintenance tasks (deps, build, etc.)
+
+**Examples:**
+
+```
+feat: add search MCP tool
+
+Implements code example search via GitHits backend REST API
+with license filtering support.
+```
+
+```
+fix: handle expired tokens in auth status
+```
+
+### Pull Requests
+
+- Use descriptive PR titles (they appear in release notes)
+- Add labels for categorization:
+  - `feature` / `enhancement` - New features
+  - `bug` / `fix` - Bug fixes
+  - `documentation` - Docs changes
+  - `maintenance` / `chore` - Maintenance
+  - `skip-changelog` - Exclude from release notes
+
+### Other Rules
+
+- No single liners - include body with context
+- Follow guidelines from `docs/guidelines/REVIEW_GUIDELINES.md`
+- Do not amend commits or rebase unless asked specifically
+
+## Project Structure
+
+```
+src/
+  cli.ts              # root CLI entry point for published githits package
+  container.ts        # root CLI dependency injection
+  auth/               # OAuth PKCE utilities
+  commands/           # CLI commands and local stdio MCP command
+  services/           # CLI/local auth storage and service composition
+  tools/              # root CLI/MCP parity tests only
+packages/
+  core-internal/      # private transport-neutral service/core source
+  mcp/                # public @githits/mcp package source
+  cli/                # private placeholder until CLI package move
+docs/
+  guidelines/         # Development guidelines
+  implementation/     # Implementation documentation
+```

package/README.md

@@ -16,6 +16,8 @@
   <a href="https://www.npmjs.com/package/githits"><img alt="Node" src="https://img.shields.io/node/v/githits.svg"></a>
   <a href="https://modelcontextprotocol.io/"><img alt="MCP" src="https://img.shields.io/badge/MCP-enabled-5C4EE5"></a>
   <a href="https://skills.sh/githits-com/githits-cli"><img alt="skills.sh" src="https://skills.sh/b/githits-com/githits-cli"></a>
+  <a href="https://smithery.ai/servers/githits/GitHits"><img alt="smithery badge" src="https://smithery.ai/badge/githits/GitHits"></a>
+  <a href="https://glama.ai/mcp/servers/githits-com/githits-cli"><img alt="githits-cli MCP server" src="https://glama.ai/mcp/servers/githits-com/githits-cli/badges/score.svg"></a>
 </p>
 
 <p align="center">
@@ -41,8 +43,9 @@ enough.
 npx githits@latest init
 ```
 
-`init` signs you in, detects supported coding tools, and configures the local
-GitHits MCP server for the tools you select.
+`init` signs you in, detects supported coding tools, and configures GitHits for
+the tools you select. It uses the local stdio MCP except for Cursor, whose
+direct setup uses the hosted remote MCP.
 
 Automatic setup currently supports Claude Code, Cursor, Windsurf,
 VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Pi, Gemini CLI,
@@ -248,18 +251,32 @@ npx githits@latest init --install-agents cursor,codex
 
 ## Plugin and Extension Packaging
 
-The npm package also includes the existing plugin and extension assets used by
-compatible hosts:
+The repository and published package provide the plugin and extension assets
+used by compatible hosts. Git-based installs also retain the context-file
+symlinks (`CLAUDE.md` and `GEMINI.md`) to the canonical `AGENTS.md`:
 
 - `.plugin/plugin.json`
 - `.claude-plugin/plugin.json`
 - `.claude-plugin/marketplace.json`
+- `.codex-plugin/plugin.json`
+- `.cursor-plugin/plugin.json`
 - `.mcp.json`
 - `gemini-extension.json`
+- `plugin.json` (Google Antigravity)
+- `mcp_config.json` (Google Antigravity)
+- `AGENTS.md`
+- `CLAUDE.md`
 - `GEMINI.md`
-- `plugins/claude/`
 - `skills/`
-- `commands/`
+
+The root skill tree is shared by all supported hosts. Every plugin and extension
+install uses the hosted remote MCP, including Claude, Codex, Cursor, Gemini CLI,
+Google Antigravity, and VS Code/GitHub Copilot OpenPlugin. Direct `githits init`
+setup is a separate path: it installs local stdio configurations for supported
+tools except Cursor, which remains remote-only. The repository root is a native
+Antigravity plugin through `plugin.json`, `mcp_config.json`, and the shared
+`skills/` tree. Generated manifests are refreshed with `bun run plugins:generate`
+and validated with `bun run plugins:check`.
 
 For Claude Code marketplace installs: