embark-cli 1.3.4 → 1.3.6

package/docs/README.md

@@ -0,0 +1,485 @@
+# Embark CLI Documentation
+
+Embark CLI is a command-line tool and MCP (Model Context Protocol) server that provides AI-powered semantic code search. It understands code meaning and context, not just keyword matching, making it ideal for exploring codebases and integrating with AI coding assistants.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Authentication](#authentication)
+- [CLI Commands](#cli-commands)
+- [MCP Server Integration](#mcp-server-integration)
+- [Agent Integration](#agent-integration)
+- [Configuration](#configuration)
+- [Skills](#skills)
+- [Statistics Dashboard](#statistics-dashboard)
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g embark-cli
+```
+
+### Verify Installation
+
+```bash
+embark --version
+```
+
+## Authentication
+
+Embark requires authentication to access the JetBrains AI API. There are two authentication methods:
+
+### Method 1: JetBrains Account OAuth (Recommended)
+
+On first use, Embark will open a browser window for you to log in with your JetBrains Account. The credentials are cached locally in `~/.embark/`.
+
+**Requirements:**
+- A JetBrains Account with an active license (IDE license, All Products Pack, etc.)
+
+### Method 2: Direct JWT Token
+
+Set the `GRAZIE_JWT_TOKEN` environment variable:
+
+```bash
+export GRAZIE_JWT_TOKEN="your-token-here"
+```
+
+This method is useful for CI/CD environments or when OAuth is not available.
+
+## CLI Commands
+
+### Search
+
+Perform semantic code search in a repository.
+
+```bash
+embark search [options] <query> [path]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-p, --path <path>` | Limit search to a directory or file |
+| `-r, --repo <url>` | Git remote URL to search |
+| `-R, --revision <rev>` | Git revision/branch/tag to search |
+| `--json` | Output results as JSON |
+| `--debug` | Output full HTTP request/response |
+| `-h, --help` | Show help message |
+
+**Examples:**
+
+```bash
+# Basic search in current repository
+embark search "authentication middleware"
+
+# Search with path filter
+embark search "user validation" src/auth
+
+# Search specific repository
+embark search --repo https://github.com/owner/repo.git "error handling"
+
+# Search specific branch
+embark search -R main "database connection pooling"
+
+# Output as JSON for scripting
+embark search --json "React modal component"
+```
+
+**Query Tips:**
+- Be descriptive: `"function that validates user email addresses"` > `"email"`
+- Include context: `"error handling middleware for HTTP requests with logging"`
+- Specify what you're looking for: `"React component that renders a modal dialog"`
+
+### History
+
+Search through commit history to understand how code evolved.
+
+```bash
+embark history [options] <query>
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-r, --repo <url>` | Git remote URL to search |
+| `-R, --revision <rev>` | Git revision/branch/tag to search |
+| `-n, --max-results <n>` | Maximum number of results (default: 10) |
+| `--min-score <score>` | Minimum similarity score (default: 0.0) |
+| `--json` | Output results as JSON |
+| `--debug` | Output full HTTP request/response |
+| `-h, --help` | Show help message |
+
+**Examples:**
+
+```bash
+# Find commits related to a feature
+embark history "add user authentication"
+
+# Get more results
+embark history -n 20 "refactor database queries"
+
+# Search specific repository
+embark history --repo https://github.com/owner/repo.git "fix memory leak"
+```
+
+**Output includes:**
+- Commit hash and timestamp
+- Author name
+- Commit message (first line)
+- Files changed in the commit
+- Similarity score
+
+### Index
+
+Schedule repository indexing for semantic search.
+
+```bash
+embark index [options]
+```
+
+**Modes:**
+| Mode | Description |
+|------|-------------|
+| `local` (default) | Run indexing locally |
+| `--remote` | Schedule remote indexing via Embark API |
+| `--mock` | Run mock indexing for testing |
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `-r, --repo <url>` | Git remote URL to index |
+| `-R, --revision <rev>` | Revision/branch/tag to index |
+| `--reschedule-period <int>` | Reschedule period for recurring jobs |
+| `--debug` | Output full HTTP request/response |
+| `-h, --help` | Show help message |
+
+**Examples:**
+
+```bash
+# Local indexing (current directory)
+embark index
+
+# Remote indexing
+embark index --remote
+
+# Remote indexing for specific repository
+embark index --remote --repo https://github.com/owner/repo.git
+
+# Schedule recurring indexing
+embark index --remote --revision main --reschedule-period 24
+```
+
+### Install
+
+Install Embark integration for AI coding agents.
+
+```bash
+embark install [options]
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--agent <name>` | Specific agent: `claude`, `codex`, `amp`, `gemini` |
+| `--scope <scope>` | Installation scope: `global` (default) or `project` |
+| `--skills-only` | Only install skills, skip hooks |
+| `--hooks-only` | Only install hooks, skip skills |
+| `-h, --help` | Show help message |
+
+**Examples:**
+
+```bash
+# Interactive mode - detect and install for all found agents
+embark install
+
+# Install for specific agent
+embark install --agent claude
+
+# Install in project-local config
+embark install --scope project
+
+# Install only skills (no hooks)
+embark install --skills-only
+```
+
+**Supported Agents:**
+- **Claude Code** (`~/.claude/`)
+- **OpenAI Codex** (`~/.codex/`)
+- **Amp** (`~/.amp/`)
+- **Gemini Code Assist** (`~/.gemini/`)
+
+### Stats
+
+Open the statistics dashboard in your browser.
+
+```bash
+embark stats [--port <port>]
+```
+
+## MCP Server Integration
+
+Embark runs as an MCP (Model Context Protocol) server, allowing AI coding assistants to use semantic code search.
+
+### Starting the MCP Server
+
+Simply run `embark` without any command:
+
+```bash
+embark
+```
+
+The server communicates via stdio and provides the `semantic_code_search` tool to MCP clients.
+
+### Available MCP Tools
+
+#### `semantic_code_search`
+
+Performs AI-powered semantic code search.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `text` | string | Yes | Descriptive search query |
+| `pathFilter` | string | No | Path to restrict search scope |
+
+**Example usage by an AI agent:**
+
+```json
+{
+  "name": "semantic_code_search",
+  "arguments": {
+    "text": "function that validates user email addresses and returns boolean",
+    "pathFilter": "src/auth"
+  }
+}
+```
+
+### Configuring MCP Clients
+
+#### Claude Desktop
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "embark": {
+      "command": "embark",
+      "env": {
+        "REPOSITORY_GIT_REMOTE_URL": "https://github.com/your/repo.git"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "embark": {
+      "command": "embark"
+    }
+  }
+}
+```
+
+## Agent Integration
+
+Use `embark install` to automatically configure AI coding agents with Embark integration.
+
+### What Gets Installed
+
+1. **MCP Server Configuration** - Adds Embark as an MCP server
+2. **Skills** - Adds `/embark-research` and `/embark-review` slash commands
+3. **Hooks** - Adds session start/end hooks to trigger indexing
+
+### Manual Configuration
+
+#### Claude Code
+
+1. Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "embark-mcp": {
+      "command": "embark"
+    }
+  }
+}
+```
+
+2. Copy skills from `src/skills/` to `~/.claude/skills/`
+
+#### Codex
+
+Add to `~/.codex/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "embark-mcp": {
+      "command": "embark"
+    }
+  }
+}
+```
+
+## Configuration
+
+Embark is configured through environment variables.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `JETBRAINS_AI_URL` | Embark API base URL | `https://api.jetbrains.ai` |
+| `REPOSITORY_GIT_REMOTE_URL` | Default repository to search | Auto-detected from git |
+| `REPOSITORY_REVISION` | Default revision/branch | `HEAD` |
+| `WORKING_DIR` | Working directory for local operations | Current directory |
+| `GRAZIE_JWT_TOKEN` | Direct JWT token (skips OAuth) | None |
+| `TYPE_TOKEN` | Token type: `USER` or `APPLICATION` | `USER` |
+| `ENABLE_REMOTE_LOGS` | Enable remote logging | `false` |
+| `INCLUDE_REPOSITORY_URLS` | Comma-separated list of additional repos | None |
+| `EXCLUDE_REPOSITORY_URLS` | Comma-separated list of repos to exclude | None |
+
+### Multi-Repository Search
+
+Embark automatically discovers Git repositories from MCP client roots. You can also configure multiple repositories:
+
+```bash
+# Include additional repositories
+export INCLUDE_REPOSITORY_URLS="https://github.com/org/repo1.git,https://github.com/org/repo2.git"
+
+# Exclude specific repositories
+export EXCLUDE_REPOSITORY_URLS="https://github.com/org/legacy-repo.git"
+```
+
+## Skills
+
+Skills are pre-configured workflows for common tasks. After running `embark install`, these are available as slash commands.
+
+### `/embark-research`
+
+Use this skill to research and understand unfamiliar codebases.
+
+**When to use:**
+- Understanding unfamiliar codebases
+- Finding implementations or definitions
+- Before making changes to understand context
+
+**Example workflow:**
+
+```bash
+# Start broad
+embark search "user authentication login"
+
+# Narrow down
+embark search -p src/auth "JWT token validation"
+
+# Check history
+embark history "add JWT authentication"
+```
+
+### `/embark-review`
+
+Use this skill to review code changes using semantic search.
+
+**When to use:**
+- Before committing changes
+- Reviewing pull requests
+- Understanding impact of changes
+
+**Example workflow:**
+
+```bash
+# See what's changed
+git diff --staged
+
+# Find similar patterns
+embark search "authentication middleware pattern"
+
+# Find callers
+embark search "uses auth middleware to protect routes"
+
+# Check for related bug fixes
+embark history "fix auth middleware"
+```
+
+## Statistics Dashboard
+
+Embark tracks usage statistics locally in `~/.embark/stats/`.
+
+### Viewing Statistics
+
+```bash
+# Open dashboard in browser
+embark stats
+
+# Start server on specific port
+embark stats --port 8080
+
+# Start server without opening browser
+embark stats-server --port 8080
+```
+
+### Dashboard Features
+
+- **Total Searches** - Count of all search operations
+- **Semantic/Dependency/History Searches** - Breakdown by search type
+- **Estimated Tokens** - Query token estimates
+- **Average Duration** - Search performance metrics
+- **Repository Usage** - Searches per repository
+- **Client Types** - Usage by different AI agents
+- **Error Tracking** - Categorized error counts
+
+### Data Location
+
+Statistics are stored as daily JSON files in `~/.embark/stats/`:
+
+```
+~/.embark/stats/
+  2024-01-15.json
+  2024-01-16.json
+  ...
+```
+
+## Troubleshooting
+
+### Debug Mode
+
+Add `--debug` to any command to see full HTTP request/response details:
+
+```bash
+embark search --debug "authentication"
+embark history --debug "fix bug"
+```
+
+### Logs
+
+Local logs are stored in `~/.embark/logs/`. Check these for detailed error information.
+
+### Common Issues
+
+**"Repository not found" (404 error)**
+- The repository may not be indexed yet
+- Run `embark index --remote` to schedule indexing
+
+**"No valid license found"**
+- Ensure you have an active JetBrains license
+- Try logging out and back in: delete `~/.embark/jba-account.json`
+
+**"No repositories available"**
+- Set `REPOSITORY_GIT_REMOTE_URL` environment variable
+- Or run from within a Git repository
+
+### Getting Help
+
+- Check the [GitHub Issues](https://github.com/jetbrains/embark-mcp/issues)
+- Run `embark <command> --help` for command-specific help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "embark-cli",
-  "version": "1.3.4",
+  "version": "1.3.6",
   "description": "CLI and MCP server proxy for EmbArk code search",
   "main": "dist/index.js",
   "bin": {