@zvec/zvec-grep 0.1.5 → 0.1.6

package/dist/observability/trace-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../../src/observability/trace-context.ts"],"names":[],"mappings":"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"}

package/docs/01-agents.md

@@ -0,0 +1,111 @@
+# Agent integrations
+
+[Documentation](./README.md) · [Agents](./01-agents.md) ·
+[CLI](./02-cli.md) · [MCP](./03-mcp.md) · [Pipeline](./04-pipeline.md) ·
+[Architecture](./05-architecture.md) · [Server](./06-server.md) ·
+[Embedding](./07-embedding.md) · [Roadmap](./08-roadmap.md)
+
+`zg install` connects zvec-grep to supported agents through the local MCP
+server. After that, the agent can use zg for conceptual discovery and exact
+search without switching between unrelated search tools.
+
+## Supported agents
+
+| Agent | Target | Managed configuration |
+| --- | --- | --- |
+| Codex | `codex` | `~/.codex/config.toml` and `~/.codex/AGENTS.md` |
+| Claude Code | `claude` | `~/.claude.json`, `~/.claude/settings.json`, and `~/.claude/CLAUDE.md` |
+| OpenCode | `opencode` | `~/.config/opencode/opencode.json` and the adjacent `AGENTS.md` |
+| Cursor | `cursor` | `~/.cursor/mcp.json` |
+
+The standard environment overrides used by each agent are respected, including
+`CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG`, and
+`CURSOR_CONFIG_DIR`.
+
+## Install an integration
+
+Run the guided installer to select from detected agents:
+
+```bash
+zg install
+```
+
+For scripts or repeatable setup, select targets explicitly:
+
+```bash
+zg install --target codex --yes
+zg install --target claude --target cursor --yes
+zg install --target all --yes
+```
+
+The installer:
+
+1. adds a managed `zvec_grep` MCP entry;
+2. adds search guidance where the agent supports it;
+3. adds local MCP tool approval for Codex and Claude Code;
+4. starts the local zvec-grep server when possible.
+
+The [Server guide](./06-server.md) explains when the daemon is useful and how its
+lifecycle differs from Direct execution.
+
+Managed text blocks use `ZVEC_GREP_START` and `ZVEC_GREP_END` markers. Existing
+content outside those blocks is preserved. If an unmanaged `zvec_grep` entry
+already exists, inspect it before using `--force` to replace it.
+
+Restart the selected agent, or open a new session, after installation.
+
+## How the agent searches
+
+The default MCP surface gives the agent one indexed search tool and leaves exact
+lexical lookup to the agent's native tools:
+
+| Intent | Tool |
+| --- | --- |
+| Locating known words, symbols, filenames, paths, or regexes is sufficient | Native grep or rg |
+| The answer requires conceptual discovery, architecture, lifecycle, or cross-component flow | `zvec_grep_search` |
+| Exact symbols are known but the answer spans components, files, or stages | `zvec_grep_search`, then native grep or rg |
+
+`zvec_grep_search` needs an existing index. Managed rg remains available through
+`zg query --rg` and through the optional `full` MCP toolset. See the
+[Pipeline guide](./04-pipeline.md) for the distinction and the
+[MCP guide](./03-mcp.md) for tool inputs.
+
+## Verify the setup
+
+Check the server first:
+
+```bash
+zg server status --check-ready
+```
+
+Then start a new agent session and confirm that `zvec_grep_search` is available.
+If the MCP connection is unavailable, the same indexed search and optional
+managed-rg route remain available from the shell:
+
+```bash
+zg query "where theme preferences are restored"
+zg query --rg -F "loadTheme" src
+```
+
+## Permissions and remote data
+
+The server listens on loopback and has no token by default. See
+[Server authentication](./06-server.md#bearer-authentication) when a local Bearer
+token is required.
+
+MCP tool approval only authorizes calls to the local server. It does **not**
+authorize sending query text or workspace content to a remote Embedding
+provider. Remote Embedding asks separately on first use; see
+[Embedding models](./07-embedding.md#remote-embedding-and-authorization).
+
+## Remove an integration
+
+Use the same target names to remove only zvec-grep-managed entries:
+
+```bash
+zg uninstall --target codex --yes
+zg uninstall --target all --yes
+```
+
+Restart the agent or open a new session to apply the change. Uninstalling an
+agent integration does not delete repository indexes or the npm package.

package/docs/02-cli.md

@@ -0,0 +1,229 @@
+# CLI guide
+
+[Documentation](./README.md) · [Agents](./01-agents.md) ·
+[CLI](./02-cli.md) · [MCP](./03-mcp.md) · [Pipeline](./04-pipeline.md) ·
+[Architecture](./05-architecture.md) · [Server](./06-server.md) ·
+[Embedding](./07-embedding.md) · [Roadmap](./08-roadmap.md)
+
+The `zg` command is the human and shell interface to the same local search
+layer used by agents. This page groups the main commands and options; use the
+installed CLI for version-specific help:
+
+```bash
+zg help
+zg help query
+zg help environment
+zg <command> --help
+```
+
+## Command overview
+
+| Command | Purpose |
+| --- | --- |
+| `query` | Search an index or run managed ripgrep |
+| `index` | Build, update, rebuild, or drop a Workspace index |
+| `status` | Inspect Workspace and index state |
+| `install` / `uninstall` | Manage agent integrations |
+| `config` | Configure provider credentials and model defaults |
+| `auth` | Manage Remote Embedding authorization |
+| `server` | Manage the shared MCP server |
+| `help` / `version` | Show help or the installed version |
+
+## `zg query`
+
+```text
+zg query <query> [options]
+zg query --hybrid <query> --fts <query> --vector <query> [--fuse]
+zg query --rg [rg-options] <pattern> [path...]
+```
+
+Search routes:
+
+| Option | Meaning |
+| --- | --- |
+| positional query | Hybrid lexical and vector retrieval |
+| `--hybrid <query>` | Add an explicit hybrid query group |
+| `--fts <query>` | Add a ranked lexical query group |
+| `--vector <query>` | Add a semantic-only query group |
+| `--fuse` | Combine all groups into one ranked plan |
+| `--rg` | Run exhaustive managed ripgrep without an index |
+
+Result controls:
+
+| Option | Meaning |
+| --- | --- |
+| `--limit <n>` | Maximum returned items per group |
+| `--human` | Terminal-oriented output with full previews by default |
+| `--preview none\|short\|full` | Indexed source preview size |
+| `--refresh background\|wait\|off` | Index refresh policy |
+| `--mode direct\|server\|auto` | Execution transport |
+| `--debug` | Print diagnostics to stderr |
+| `--trace` | Add per-hit indexed search trace |
+| `--prefer-symbol` | Prefer an exact indexed symbol |
+| `--symbol-type <type>` | Restrict results to a symbol type |
+| `--modified-after <time>` | Search files modified after a time |
+| `--modified-before <time>` | Search files modified before a time |
+
+Valid symbol types are `module`, `class`, `interface`, `function`, `value`, and
+`alias`.
+
+Common scope options for indexed search are `-g/--glob`, `--iglob`, `-t/--type`,
+and `-T/--type-not`. Managed rg additionally supports common ripgrep matching,
+context, discovery, encoding, and regex-engine flags.
+
+Examples:
+
+```bash
+zg query "theme preference persistence on startup"
+zg query --fts "loadTheme" -g "src/**" -t ts
+zg query --vector "where user preferences are restored" --limit 5
+zg query --human "plugin lifecycle" --preview full
+zg query --rg -i -C 2 -g "*.ts" "dark mode" src
+```
+
+See [Retrieval pipeline](./04-pipeline.md#3-query-through-one-search-layer) for
+route selection and freshness behavior.
+
+## `zg index`
+
+```text
+zg index [root] [options]
+zg index [root] --rebuild [options]
+zg index [root] --drop [--yes]
+```
+
+Core options:
+
+| Option | Meaning |
+| --- | --- |
+| `--embedding <model>` | Model for a new or rebuilt index |
+| `--rebuild` | Recreate an existing index |
+| `--drop` | Permanently remove the Workspace index |
+| `--yes` | Confirm `--drop` without a prompt |
+| `--reset-paths` | Replace stored file-selection settings |
+| `--mode direct\|server\|auto` | Execution transport |
+| `--api-key <key>` | One-command provider credential |
+| `--endpoint <url>` | Remote provider endpoint |
+| `--model-cache <path>` | Local model cache directory |
+| `--device <device>` | `auto`, `cpu`, `metal`, `vulkan`, or `cuda` |
+| `--embedding-concurrency <n>` | Concurrent Embedding tasks |
+| `--allow-remote` | Authorize Remote Embedding for this command |
+
+File discovery accepts `-g/--glob`, `--iglob`, `-t/--type`, `-T/--type-not`,
+`--hidden`, `--no-ignore`, `--ignore-file`, `--max-depth`, `--max-filesize`, and
+`-L/--follow`.
+
+Examples:
+
+```bash
+zg index --embedding local/potion-code-16m-v2
+zg index
+zg index --rebuild --embedding local/jina-embeddings-v2-base-code
+zg index --drop --yes
+```
+
+## `zg status`
+
+```text
+zg status [root] [--mode direct|server|auto] [--check-ready]
+```
+
+Status includes the selected root, index policy, stored schema and paths, file
+counts, refresh state, and a suggested next action. `--check-ready` preserves
+normal output and exits non-zero unless the index is ready, which is useful in
+scripts.
+
+## `zg install` and `zg uninstall`
+
+```text
+zg install [--target codex|claude|opencode|cursor|all|auto] [--yes] [--force]
+zg uninstall [--target codex|claude|opencode|cursor|all|auto] [--yes]
+```
+
+`--target` is repeatable. `zg install` also accepts:
+
+| Option | Meaning |
+| --- | --- |
+| `--mcp-tool-timeout <seconds>` | Codex/OpenCode MCP timeout; default 600 seconds |
+| `--mcp-token-env <name>` | Environment variable containing the server token |
+| `--force` | Replace a conflicting unmanaged `zvec_grep` entry |
+
+See [Agent integrations](./01-agents.md) before using `--force`.
+
+## `zg config`
+
+```text
+zg config provider set <provider> --api-key <key>
+zg config model set <model> [--endpoint <url> | --device <device>] [--default]
+```
+
+Examples:
+
+```bash
+zg config provider set qwen --api-key "$DASHSCOPE_API_KEY"
+zg config model set qwen/text-embedding-v4 --default
+zg config model set local/embeddinggemma-300m --device metal
+```
+
+Global configuration is stored in `~/.zvec-grep/config.json`. Existing indexes
+continue to use their stored model until explicitly rebuilt.
+
+## `zg auth`
+
+```text
+zg auth grant [root] --capability embedding --scope workspace [--embedding <model>]
+zg auth status [root]
+zg auth revoke [root]
+```
+
+Workspace grants are stored under `.zvec-grep/authorization.json` and shared by
+the CLI and MCP server. `--allow-remote` is the non-persistent alternative for
+one `query` or `index` command. `--embedding` selects the Remote Embedding model
+to authorize; it does not run embedding. It may be omitted when the model can be
+resolved from the existing Workspace index, `ZVEC_GREP_EMBEDDING`, or the global
+default, in that order.
+
+## `zg server`
+
+```text
+zg server on [--listen 127.0.0.1:7999] [--token-file <path>] [--mcp-toolset agent|full]
+zg server off [--token-file <path>]
+zg server status [--check-ready]
+zg server run [--listen 127.0.0.1:7999] [--token-file <path>] [--mcp-toolset agent|full]
+```
+
+`on` starts the background daemon; `run` keeps it in the foreground. The server
+only accepts loopback listen addresses. The default public endpoint is
+`http://127.0.0.1:7999/mcp` with the `agent` toolset.
+
+See [Server and execution modes](./06-server.md) for mode selection, lifecycle,
+refresh, authentication, and logs. See [MCP](./03-mcp.md) for the tool contract.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `ZVEC_GREP_HOME` | Override zvec-grep state directory |
+| `ZVEC_GREP_MODE` | Default `direct`, `server`, or `auto` transport |
+| `ZVEC_GREP_SERVER_URL` | Override the MCP server URL used by clients |
+| `ZVEC_GREP_SERVER_TOKEN` | Server/client Bearer token |
+| `ZVEC_GREP_SERVER_TOKEN_FILE` | File containing the server/client token |
+| `ZVEC_GREP_MCP_TOOLSET` | Default `agent` or `full` MCP surface |
+| `ZVEC_GREP_EMBEDDING` | Default model for new indexes |
+| `ZVEC_GREP_API_KEY` | Embedding provider API key |
+| `ZVEC_GREP_ENDPOINT` | Remote Embedding endpoint |
+| `ZVEC_GREP_MODEL_CACHE` | Local model cache directory |
+| `ZVEC_GREP_DEVICE` | Local model device |
+| `DASHSCOPE_API_KEY` | Qwen API-key fallback after `ZVEC_GREP_API_KEY` |
+| `QWEN_API_KEY` | Qwen API-key fallback after `DASHSCOPE_API_KEY` |
+
+Run `zg help environment` for advanced variables, agent integration paths,
+scope, and detailed precedence. A new index selects its model in this order:
+explicit `--embedding`, `ZVEC_GREP_EMBEDDING`, then the global default. Existing
+indexes continue to use their stored model unless `--embedding` and `--rebuild`
+explicitly change it.
+
+Embedding runtime values such as endpoint and device retain this order: explicit
+command option, Workspace snapshot, global configuration, then environment.
+`zg index` forwards its `ZVEC_GREP_EMBEDDING` value in server and auto modes;
+direct MCP calls use the environment inherited when the daemon started.

package/docs/03-mcp.md

@@ -0,0 +1,167 @@
+# MCP guide
+
+[Documentation](./README.md) · [Agents](./01-agents.md) ·
+[CLI](./02-cli.md) · [MCP](./03-mcp.md) · [Pipeline](./04-pipeline.md) ·
+[Architecture](./05-architecture.md) · [Server](./06-server.md) ·
+[Embedding](./07-embedding.md) · [Roadmap](./08-roadmap.md)
+
+zvec-grep exposes its local search layer over Streamable HTTP MCP. The normal
+endpoint is:
+
+```text
+http://127.0.0.1:7999/mcp
+```
+
+Run `zg install` to configure a supported agent automatically. Use this page
+when building another MCP client or when you need the exact boundary between
+the default and compatibility toolsets. See
+[Server and execution modes](./06-server.md) for lifecycle, mode selection,
+refresh, authentication, and logs.
+
+## Default agent toolset
+
+The default `agent` toolset intentionally exposes only search:
+
+| Tool | Use it when | Index required |
+| --- | --- | --- |
+| `zvec_grep_search` | The answer requires conceptual discovery, architecture, lifecycle, or cross-component flow | Yes |
+
+Agents use native grep or rg when locating an exact word, symbol, filename, path,
+source fragment, or regex is sufficient. For mixed tasks, start with
+`zvec_grep_search`, then use native grep or rg for focused follow-up.
+
+Every repository tool input uses an absolute `root` visible to the daemon.
+
+## `zvec_grep_search`
+
+The indexed tool supports hybrid, lexical, and vector query groups. At least one
+of `query`, `queries`, `fts`, or `vector` is required.
+
+Minimal conceptual search:
+
+```json
+{
+  "root": "/absolute/path/to/repository",
+  "query": "theme preference persistence on startup",
+  "limit": 5
+}
+```
+
+Explicit query routes and scope:
+
+```json
+{
+  "root": "/absolute/path/to/repository",
+  "query": "authentication flow",
+  "fts": ["AuthService", "ForbiddenError"],
+  "globs": ["src/**", "!src/generated/**"],
+  "fileTypes": ["ts"],
+  "fuse": true,
+  "limit": 10
+}
+```
+
+Important inputs:
+
+| Input | Meaning |
+| --- | --- |
+| `query` | One hybrid natural-language or exact query |
+| `queries` | One or more hybrid query groups |
+| `fts` | Ranked lexical query groups |
+| `vector` | Semantic-only query groups |
+| `fuse` | Combine every group into one ranked plan |
+| `limit` | Maximum items per group, up to 50 |
+| `globs` / `insensitiveGlobs` | Ordered path rules |
+| `fileTypes` / `excludedFileTypes` | ripgrep file-type filters |
+| `symbolTypes` / `preferSymbol` | Indexed symbol controls |
+| `modifiedAfter` / `modifiedBefore` | File modification-time bounds |
+| `freshness` | `eventual` or `wait_for_fresh` |
+| `autoUpdate` | Allow an eventual search to schedule a background update |
+
+The response is compact text designed for agent context. It begins with index
+state and then groups ranked results by file:
+
+```text
+freshness: fresh
+src/theme/use-theme.ts:12-36
+matched: 16-18
+source:
+15  export function useTheme() {
+16    const [theme, setTheme] = useState("light");
+17    useEffect(() => saveTheme(theme), [theme]);
+```
+
+When `freshness` is `possibly_stale`, the response may also include current
+indexing state. Agents can use sufficient results immediately rather than
+running a status preflight.
+
+Remote models may cause the tool to request explicit Remote Embedding
+authorization. See
+[Embedding models](./07-embedding.md#remote-embedding-and-authorization).
+
+## `zvec_grep_rg`
+
+This tool is retained in the optional `full` MCP toolset and is not registered
+in the default `agent` toolset. The CLI equivalent, `zg query --rg`, remains
+available without changing the MCP toolset.
+
+Pass the ripgrep command you would otherwise run. The command is parsed into
+arguments and is never executed by a shell:
+
+```json
+{
+  "root": "/absolute/path/to/repository",
+  "command": "rg -n -F 'loadTheme' -g '*.ts' src"
+}
+```
+
+The tool is exhaustive by default. Append `| head -N` only when intentionally
+requesting bounded output:
+
+```json
+{
+  "root": "/absolute/path/to/repository",
+  "command": "rg -n 'TODO|FIXME' src | head -50"
+}
+```
+
+Scope broad searches with command paths, `-g/--glob`, or `-t/--type`. Managed rg
+supports common ripgrep matching, context, type, glob, ignore, encoding, and
+regex-engine options while preserving zvec-grep's compact result format.
+
+## Full compatibility toolset
+
+The CLI owns index lifecycle and diagnostics, so agents normally do not need
+administrative MCP tools. Clients that require them can restart the server with:
+
+```bash
+zg server off
+zg server on --mcp-toolset full
+```
+
+The `full` toolset exposes six tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `zvec_grep_search` | Indexed retrieval |
+| `zvec_grep_rg` | No-index exhaustive search |
+| `zvec_grep_index` | Create, update, rebuild, or explicitly drop an index |
+| `zvec_grep_index_drop` | Explicitly delete an index |
+| `zvec_grep_index_status` | Inspect persisted and active index state |
+| `zvec_grep_server_status` | Inspect daemon, queue, runtime, and model-pool state |
+
+`zvec_grep_index` requires an absolute root. Its `wait` input defaults to
+`false`, returning a background job identifier. Poll `zvec_grep_index_status`
+only when completion, progress, failure diagnosis, or explicit monitoring is
+needed. An agent must never silently create, rebuild, or delete a persistent
+index.
+
+Set `ZVEC_GREP_MCP_TOOLSET=full` as an environment fallback. An explicit
+`--mcp-toolset` flag takes precedence.
+
+## Transport security
+
+The MCP endpoint is loopback-only. Optional Bearer authentication protects the
+local Server but remains independent of Embedding provider credentials and
+Remote Embedding authorization. Configuration examples are in
+[Server authentication](./06-server.md#bearer-authentication).