@zvec/zvec-grep 0.1.5 → 0.1.6

package/README_CN.md

@@ -3,302 +3,138 @@
 </p>
 
 <div align="center">
+  <p>
+    <a href="./docs/08-roadmap.md"><img src="https://img.shields.io/badge/status-work%20in%20progress-F59E0B?style=for-the-badge" alt="项目开发中" /></a>
+  </p>
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_log_2.svg" />
-    <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_logo_1.svg" width="400" alt="zvec logo" />
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/zg-logo-dark.svg">
+    <img src="./.github/assets/zg-logo.svg" width="150" alt="zg logo" />
   </picture>
+  <p><strong>Know the words—or don’t. Just zg.</strong></p>
+  <p>面向人与 Agent 的本地优先统一检索层。</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm 版本" /></a>
+    <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache 2.0 许可证" /></a>
+    <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js 22 或更新版本" />
+  </p>
+
+  <p>
+    <a href="#tour">🎬 <strong>功能演示</strong></a> |
+    <a href="#features">💫 <strong>核心特性</strong></a> |
+    <a href="#quickstart">🚀 <strong>快速开始</strong></a> |
+    <a href="./docs/README.md">📚 <strong>文档</strong></a> |
+    <a href="#benchmarks">📊 <strong>性能测试</strong></a> |
+    <a href="#community">🤝 <strong>社区</strong></a>
+  </p>
 </div>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm 版本"/></a>
-  <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="许可证"/></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js >=22"/>
-  <img src="https://img.shields.io/badge/CLI-zg-2ea44f.svg" alt="zg CLI"/>
-</p>
+**zg**（**z**vec-**g**rep）将 ripgrep、BM25 与向量检索统一在一个
+[本地优先的检索入口](./docs/05-architecture.md)中。无论是人在终端中搜索，
+还是让 Agent 自主检索，只用 zg 即可。
 
-<p align="center">
-  <a href="#quickstart">🚀 <strong>快速开始</strong></a> |
-  <a href="#features">💫 <strong>核心特性</strong></a> |
-  <a href="#installation">📦 <strong>安装</strong></a> |
-  <a href="#models">🧠 <strong>模型</strong></a> |
-  <a href="#library-api">🛠️ <strong>库 API</strong></a>
-</p>
+<a id="tour"></a>
 
-**zvec-grep** 是基于 Zvec 构建的、面向 agent 的代码库混合检索工具。它为仓库维护本地语义索引，融合向量检索与全文检索，并默认输出节省 token 的结果；当人在终端里阅读时，也可以切换到更完整的展示模式。
+## 🎬 功能演示
 
-命令非常短：
+<div align="center">
+  <img src="./.github/assets/zvec-grep-tour.gif" width="1000" alt="安装 Agent 集成、为仓库建索引并让 Agent 使用 zvec-grep 搜索代码" />
+</div>
 
-```bash
-zg query "where query auto update happens"
-```
+只需安装一次集成并为工作区建索引，之后既可以在终端中搜索，也可以直接向
+Agent 提问。
 
-> [!IMPORTANT]
-> **命令接口**
->
-> - **混合代码检索**：可以用自然语言、精确关键词，或两者组合来搜索代码。
-> - **明确的索引生命周期**：新仓库必须显式运行 `zg index --embedding <model>`；agent 不会静默创建索引。
-> - **自动刷新**：已有匿名索引会在普通查询前自动检查并增量更新。
-> - **节省 Token 的输出**：agent 默认输出 `--preview none`；`--human` 默认展示完整源码 preview。
-> - **无索引文本搜索**：`zg query --rg` 提供托管的 ripgrep 搜索，不需要先建索引。
+<a id="features"></a>
 
-## <a id="features"></a>💫 核心特性
+## 💫 为什么选择 zg？
 
-- **语义 + 词法检索**：融合向量检索和全文检索，适合源码、文档、测试、脚本和配置。
-- **仓库本地索引**：匿名索引存放在 `<repo>/.zvec-grep/`，索引状态跟随仓库。
-- **Agent 友好输出**：默认按文件分组，并尽量减少源码 preview，降低上下文成本。
-- **人类阅读模式**：加 `--human` 后更适合终端阅读，并默认展示完整 preview。
-- **托管 ripgrep 通道**：`zg query --rg` 支持常见 `rg` 参数，未建索引仓库也能使用。
-- **显式模型选择**：第一次建索引必须指定模型，例如 `local/embeddinggemma-300m`、`local/qwen3-embedding-0.6b` 或 `qwen/text-embedding-v4`。
-- **Schema 复用**：已有索引再次运行 `zg index` 会复用保存的 embedding schema，除非你显式切换模型。
-- **MCP Server**：运行 `zg serve --mcp`，向 MCP 客户端暴露索引搜索和无索引文本搜索工具；建索引和状态查看仍由 CLI 提供。
-- **库 API**：Node.js 工具、agent 或 MCP server 可以直接使用 `createZvecGrep()`。
+- **开箱即用，零学习成本**：一套引导式安装即可在 macOS、Linux 和 Windows
+  上接入 Agent；直接用自然语言提问，无需学习搜索语法。
+- **一站式检索层**：语义发现、BM25 相关性检索、精确文本与正则搜索
+  都由 zg 统一提供。
+- **对 Agent 和开发者都友好**：为 Agent 提供紧凑、围绕文件组织的上下文，
+  为开发者提供易读的终端输出，双方都能减少无关噪声。
+- **本地优先、权限明确**：ripgrep、索引与本地模型均留在本机；远程 Embedding
+  需要显式授权。
 
-## <a id="installation"></a>📦 安装
+<a id="quickstart"></a>
 
-从 npm 安装 CLI：
+## 🚀 快速开始
 
-```bash
-npm install -g @zvec/zvec-grep
-zg version
-```
+需要 Node.js 22 或更新版本，支持 macOS、Linux 和 Windows。
 
-也可以不全局安装，直接运行：
+### 1. 安装并连接 Agent
 
 ```bash
-npx @zvec/zvec-grep help
-```
-
-从最新源码构建，并将 `zg` 安装为全局命令：
-
-```bash
-git clone https://github.com/zvec-ai/zvec-grep.git
-cd zvec-grep
-npm ci
-npm run build
-npm install -g .
-zg version
-```
-
-运行 stdio MCP server：
-
-```bash
-zg serve --mcp
+npm install -g @zvec/zvec-grep
+zg install
 ```
 
-安装 Codex MCP 集成：
+`zg install` 会检测 Codex、Claude Code、Cursor 和 OpenCode，并配置本地 MCP 集成。
+查看 [Agent 集成指南](./docs/01-agents.md)，了解配置变更、权限和卸载方式。
+也可以明确指定目标：
 
 ```bash
 zg install --target codex --yes
 ```
 
-Codex MCP 工具调用默认超时为 600 秒，可在安装时通过 `--mcp-tool-timeout <秒数>` 覆盖。
-
-### ✅ 运行要求
-
-- Node.js 22 或更新版本
-- macOS、Linux 或 Windows
-- 使用索引检索时需要选择一个支持的 embedding 模型
-
-`zg query --rg` 不需要 embedding 模型，也不需要索引。
-
-## <a id="quickstart"></a>⚡ 快速开始
-
-为仓库建索引，并显式指定 embedding 模型：
-
-```bash
-zg index \
-  --embedding local/embeddinggemma-300m \
-  -g "src/**" \
-  -g "docs/**" \
-  -g "test/**" \
-  -g "!dist/**" \
-  -g "!node_modules/**" \
-  -g "!coverage/**"
-```
-
-查看索引状态：
+### 2. 为仓库建索引
 
 ```bash
-zg status
+cd your-repository
+zg index --embedding local/potion-code-16m-v2
 ```
 
-用自然语言搜索：
+快速开始使用轻量的 [Potion Code v2](./docs/07-embedding.md)，以便快速完成首次建索引。
+第一次运行会下载模型，索引保存在 `.zvec-grep/` 下；后续更新只需运行
+`zg index`。查看 [检索 Pipeline](./docs/04-pipeline.md#indexing)，进一步控制检索范围、
+增量更新和重建。
 
-```bash
-zg query "where query auto update happens"
-```
+### 3. 直接向 Agent 提问
 
-组合语义意图和精确锚点：
-
-```bash
-zg query "GPU fallback" --fts "usingCpuFallback" -g "src/**" -t ts --limit 5
+```text
+每次刷新页面，应用都会忘记深色模式。帮我找出原因。
 ```
 
-不依赖索引，做穷尽文本搜索：
+Agent 会始终通过 zg 完成语义发现、关键词相关性检索与穷尽精确匹配。你无需
+选择或调用其他搜索工具。[MCP 指南](./docs/03-mcp.md)介绍了 Agent 使用的两个工具。
 
-```bash
-zg query --rg -F "ZVEC_GREP_HOME" src
-```
-
-切换到适合人看的输出：
+也可以直接在终端中使用同一个本地检索层。查看 [CLI 指南](./docs/02-cli.md)，了解
+搜索方式、过滤条件和输出控制。
 
 ```bash
-zg query --human "root local index discovery" --limit 3
+zg query --human "theme preference persistence on startup" --limit 3
 ```
 
-在 MCP 客户端中可使用 `zvec_grep_search` 和 `zvec_grep_rg`。MCP 输入使用 JSON 友好的字段，例如 `include: ["src/**"]`；状态查看和建索引请使用 CLI 的 `zg status` 与 `zg index`。Codex installer 会向 `${CODEX_HOME:-$HOME/.codex}/config.toml` 和 `${CODEX_HOME:-$HOME/.codex}/AGENTS.md` 写入由 zvec-grep 管理的配置块。
-
-## <a id="models"></a>🧠 模型
-
-本地模型通过 `node-llama-cpp` 运行，适合把代码检索留在本机：
+<a id="benchmarks"></a>
 
-```bash
-zg index --embedding local/embeddinggemma-300m
-zg index --embedding local/qwen3-embedding-0.6b
-```
+## 📊 性能测试
 
-在 Apple Silicon 上，本地构建默认使用更安静的 llama.cpp CMake 配置，避免无害的 OpenMP 和 ARM native 探测 warning。可以通过 `NODE_LLAMA_CPP_CMAKE_OPTION_<name>` 覆盖任意 llama.cpp CMake 选项，例如设置 `NODE_LLAMA_CPP_CMAKE_OPTION_GGML_NATIVE=ON` 重新启用 native CPU 优化。
+> 🚧 **正在完善中。**
 
-远程 Qwen embedding 适合希望使用托管 embedding 服务，或不想在本机配置模型的场景：
+## 🗺️ Roadmap
 
-```bash
-zg index \
-  --embedding qwen/text-embedding-v4 \
-  --api-key "$DASHSCOPE_API_KEY"
-```
+zg 正在迈向更丰富的多模态格式、更强的混合检索、更开箱即用的体验，以及从
+桌面端到移动端的全平台支持。
 
-索引成功后，通过 CLI 显式传入的全局模型和 provider 参数会保存到 `~/.zvec-grep/config.json`，并使用仅当前用户可读写的权限。已经运行的 `zg` MCP server 会在下一次需要模型时读取新的远程 API key，不需要重启 Codex。只从环境变量读取、没有作为 CLI 参数显式传入的值不会被持久化。
-
-```json
-{
-  "version": 1,
-  "defaults": {
-    "embedding": "qwen/text-embedding-v4"
-  },
-  "providers": {
-    "qwen": {
-      "apiKey": "...",
-      "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings"
-    }
-  }
-}
-```
+查看完整 [Roadmap](./docs/08-roadmap.md)。
 
-配置优先级为：显式 CLI 或库参数、环境变量、全局配置、内置默认值。仓库 root 和文件选择规则仍保存在各仓库自己的 `.zvec-grep` 元数据中，不进入全局配置。
+<a id="community"></a>
 
-对于已有索引，`zg index` 不传 `--embedding` 会复用索引里保存的 schema。只有在你明确想切换模型时，才使用 `--rebuild --embedding <model>`：
-
-```bash
-zg index --rebuild --embedding local/qwen3-embedding-0.6b
-```
-
-## 🔎 查询模式
-
-多个带引号的 query 会作为多个搜索组分别检索：
-
-```bash
-zg query "request validation" "error handling" --limit 5
-```
-
-每个 route 参数只接收一个 query，并且可以重复使用。需要把所有搜索组合并成一个排序结果时，使用 `--fuse`：
-
-```bash
-zg query \
-  --hybrid "authentication flow" \
-  --fts "AuthService" \
-  --vector "where credentials are validated" \
-  --fuse \
-  --limit 10
-```
-
-尽早使用与 ripgrep 一致的路径和文件类型过滤，让结果保持聚焦。普通 glob 表示包含，以 `!` 开头的 glob 表示排除：
-
-```bash
-zg query "cache invalidation" \
-  -g "src/**" \
-  -g "!test/**" \
-  -g "!tests/**" \
-  -g "!fixtures/**" \
-  -g "!dist/**" \
-  -t ts
-```
-
-文件类型过滤会在 glob 过滤之后继续缩小范围。例如，`-g "docs/**" -t ts`
-只会选择 `docs` 目录下的 TypeScript 文件，而不是该目录里的所有文件。
-
-使用 `--preview` 控制索引结果的源码展示量：
-
-```bash
-zg query "plugin lifecycle" --preview none
-zg query "plugin lifecycle" --preview short --limit 5
-zg query "plugin lifecycle" --preview full --limit 2
-```
-
-查精确文本、符号、配置项或错误码时，使用 `--fts` 或 `--rg`：
-
-```bash
-zg query "authentication flow" --fts "AuthService" --fts "ForbiddenError"
-zg query --rg -i -C 2 -g "*.ts" "needle text" src
-```
-
-托管的 rg 模式支持常用的 ripgrep 匹配、上下文、文件类型、glob、ignore、
-深度、大小、符号链接、编码和正则引擎参数。结果格式由 zvec-grep 管理，
-因此 `--json`、`--count`、`--files`、`-l`、`-o`、`--replace` 和
-`--vimgrep` 等会改变输出形态的模式会被拒绝。`.git/**` 和
-`.zvec-grep/**` 始终保持排除。
-
-## <a id="library-api"></a>🛠️ 库 API
-
-```ts
-import { createZvecGrep } from "@zvec/zvec-grep";
-
-const zvecGrep = await createZvecGrep({
-  root: process.cwd(),
-});
-
-const result = await zvecGrep.context({
-  query: "ranking implementation",
-  limit: 5,
-});
-
-for (const item of result.items) {
-  const location =
-    item.range.kind === "text"
-      ? `${item.file.relativePath}:${item.range.startLine}`
-      : item.file.relativePath;
-  console.log(location);
-}
-
-await zvecGrep.close();
-```
-
-显式进行无索引文本搜索：
-
-```ts
-const result = await zvecGrep.context({
-  query: "ZVEC_GREP_HOME",
-  rg: true,
-});
-```
-
-## 🤝 加入 Zvec 社区
+## 🤝 加入社区
 
 <div align="center">
 
-|                                                💬 钉钉群                                                |                                                 📱 微信群                                                 |                                                                       🎮 Discord                                                                        |                                             X (Twitter)                                              |
-| :-----------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: |
-| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](https://x.com/ZvecAI) |
-|                                                扫码加入                                                 |                                                 扫码加入                                                  |                                                                        点击加入                                                                         |                                               点击关注                                               |
+| 💬 钉钉群 | 📱 微信群 | 🎮 Discord | X (Twitter) |
+| :---: | :---: | :---: | :---: |
+| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v1" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
+| 扫码加入 | 扫码加入 | 点击加入 | 点击关注 |
 
 </div>
 
 ## ❤️ 参与贡献
 
-欢迎提交 issue 和 pull request。请保持改动聚焦；如果改变行为，请补充测试，并运行：
-
-```bash
-npm run check
-```
+始终欢迎社区贡献——缺陷修复、新功能和文档改进都会让 zvec-grep 变得更好。
 
-Pull request 标题需遵循 Conventional Commits。
+请查阅我们的[贡献指南](./CONTRIBUTING.md)开始参与！

package/dist/authorization/index.d.ts

@@ -0,0 +1,7 @@
+export { RemoteEmbeddingAuthorizationManager } from "./manager.js";
+export { createRemoteEmbeddingOperationPermit, remoteEmbeddingAuthorizationGuard, withRemoteEmbeddingOperationPermit, } from "./operation.js";
+export { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export { formatRemoteEmbeddingAuthorizationPrompt, remoteEmbeddingDisclosureData, type RemoteEmbeddingAuthorizationPromptInput, } from "./prompt.js";
+export { indexStatusIsFresh, planRemoteIndexAuthorization, planRemoteSearchAuthorization, searchUsesVector, } from "./planner.js";
+export { canonicalizeWorkspaceRoots, createRemoteEmbeddingTarget, remoteEmbeddingTargetFingerprint, workspaceFingerprint, } from "./target.js";
+export type { RemoteEmbeddingAuthorizationPlan, RemoteEmbeddingAuthorizationScope, RemoteEmbeddingAuthorizationStatus, RemoteEmbeddingDataDisclosure, RemoteEmbeddingOperation, RemoteEmbeddingOperationPermit, RemoteEmbeddingTarget, RemoteEmbeddingWorkspaceGrant, } from "./types.js";

package/dist/authorization/index.js

@@ -0,0 +1,7 @@
+export { RemoteEmbeddingAuthorizationManager } from "./manager.js";
+export { createRemoteEmbeddingOperationPermit, remoteEmbeddingAuthorizationGuard, withRemoteEmbeddingOperationPermit, } from "./operation.js";
+export { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export { formatRemoteEmbeddingAuthorizationPrompt, remoteEmbeddingDisclosureData, } from "./prompt.js";
+export { indexStatusIsFresh, planRemoteIndexAuthorization, planRemoteSearchAuthorization, searchUsesVector, } from "./planner.js";
+export { canonicalizeWorkspaceRoots, createRemoteEmbeddingTarget, remoteEmbeddingTargetFingerprint, workspaceFingerprint, } from "./target.js";
+//# sourceMappingURL=index.js.map

package/dist/authorization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/authorization/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,oCAAoC,EACpC,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,wCAAwC,EACxC,6BAA6B,GAE9B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/authorization/manager.d.ts

@@ -0,0 +1,8 @@
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import type { RemoteEmbeddingAuthorizationPlan, RemoteEmbeddingAuthorizationScope, RemoteEmbeddingOperationPermit } from "./types.js";
+export declare class RemoteEmbeddingAuthorizationManager {
+    readonly store: RemoteEmbeddingAuthorizationStore;
+    constructor(store?: RemoteEmbeddingAuthorizationStore);
+    existingWorkspacePermit(plan: RemoteEmbeddingAuthorizationPlan): Promise<RemoteEmbeddingOperationPermit | undefined>;
+    grant(plan: RemoteEmbeddingAuthorizationPlan, scope: RemoteEmbeddingAuthorizationScope): Promise<RemoteEmbeddingOperationPermit>;
+}

package/dist/authorization/manager.js

@@ -0,0 +1,19 @@
+import { createRemoteEmbeddingOperationPermit } from "./operation.js";
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export class RemoteEmbeddingAuthorizationManager {
+    store;
+    constructor(store = new RemoteEmbeddingAuthorizationStore()) {
+        this.store = store;
+    }
+    async existingWorkspacePermit(plan) {
+        if (!(await this.store.hasGrant(plan.target)))
+            return undefined;
+        return createRemoteEmbeddingOperationPermit(plan.target, "workspace");
+    }
+    async grant(plan, scope) {
+        if (scope === "workspace")
+            await this.store.grant(plan.target);
+        return createRemoteEmbeddingOperationPermit(plan.target, scope);
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/authorization/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/authorization/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oCAAoC,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAO/D,MAAM,OAAO,mCAAmC;IACrC,KAAK,CAAoC;IAElD,YAAY,KAAK,GAAG,IAAI,iCAAiC,EAAE;QACzD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,uBAAuB,CAC3B,IAAsC;QAEtC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;QAChE,OAAO,oCAAoC,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,KAAK,CACT,IAAsC,EACtC,KAAwC;QAExC,IAAI,KAAK,KAAK,WAAW;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/D,OAAO,oCAAoC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/authorization/operation.d.ts

@@ -0,0 +1,7 @@
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import { type RemoteEmbeddingAuthorizationScope, type RemoteEmbeddingOperationPermit, type RemoteEmbeddingRequest, type RemoteEmbeddingTarget } from "./types.js";
+export declare function createRemoteEmbeddingOperationPermit(target: RemoteEmbeddingTarget, scope: RemoteEmbeddingAuthorizationScope): RemoteEmbeddingOperationPermit;
+export declare function withRemoteEmbeddingOperationPermit<T>(permit: RemoteEmbeddingOperationPermit | undefined, operation: () => Promise<T>): Promise<T>;
+export declare function remoteEmbeddingAuthorizationGuard(options?: {
+    store?: RemoteEmbeddingAuthorizationStore;
+}): (request: RemoteEmbeddingRequest) => Promise<void>;

package/dist/authorization/operation.js

@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { EngineError } from "../engine/errors.js";
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import { REMOTE_EMBEDDING_CAPABILITY, } from "./types.js";
+const operationPermit = new AsyncLocalStorage();
+export function createRemoteEmbeddingOperationPermit(target, scope) {
+    return {
+        capability: REMOTE_EMBEDDING_CAPABILITY,
+        scope,
+        target,
+        issuedAt: Date.now(),
+        operationId: randomUUID(),
+    };
+}
+export async function withRemoteEmbeddingOperationPermit(permit, operation) {
+    if (!permit)
+        return await operation();
+    return await operationPermit.run(permit, operation);
+}
+export function remoteEmbeddingAuthorizationGuard(options = {}) {
+    const store = options.store ?? new RemoteEmbeddingAuthorizationStore();
+    return async (request) => {
+        const permit = operationPermit.getStore();
+        if (!permit ||
+            permit.capability !== REMOTE_EMBEDDING_CAPABILITY ||
+            permit.target.provider !== request.provider ||
+            permit.target.model !== request.model ||
+            permit.target.endpoint !== request.endpoint) {
+            throw authorizationRequiredError(request);
+        }
+        if (permit.scope === "workspace" &&
+            !(await store.hasGrant(permit.target))) {
+            throw authorizationRequiredError(request, "Workspace grant is missing, invalid, or revoked.");
+        }
+    };
+}
+function authorizationRequiredError(request, detail) {
+    return new EngineError("Remote Embedding authorization is required", {
+        code: "ZVEC_GREP.ENGINE.AUTH.REMOTE_EMBEDDING_REQUIRED",
+        context: [
+            `provider=${request.provider}`,
+            `model=${request.model}`,
+            `endpoint=${request.endpoint}`,
+            `purpose=${request.purpose}`,
+            ...(detail ? [`detail=${detail}`] : []),
+        ].join(" "),
+    });
+}
+//# sourceMappingURL=operation.js.map

package/dist/authorization/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../../src/authorization/operation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,2BAA2B,GAK5B,MAAM,YAAY,CAAC;AAEpB,MAAM,eAAe,GAAG,IAAI,iBAAiB,EAAkC,CAAC;AAEhF,MAAM,UAAU,oCAAoC,CAClD,MAA6B,EAC7B,KAAwC;IAExC,OAAO;QACL,UAAU,EAAE,2BAA2B;QACvC,KAAK;QACL,MAAM;QACN,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE;QACpB,WAAW,EAAE,UAAU,EAAE;KAC1B,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,MAAkD,EAClD,SAA2B;IAE3B,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,SAAS,EAAE,CAAC;IACtC,OAAO,MAAM,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,UAEI,EAAE;IAEN,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,iCAAiC,EAAE,CAAC;IACvE,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;QAC1C,IACE,CAAC,MAAM;YACP,MAAM,CAAC,UAAU,KAAK,2BAA2B;YACjD,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ;YAC3C,MAAM,CAAC,MAAM,CAAC,KAAK,KAAK,OAAO,CAAC,KAAK;YACrC,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,EAC3C,CAAC;YACD,MAAM,0BAA0B,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,IACE,MAAM,CAAC,KAAK,KAAK,WAAW;YAC5B,CAAC,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EACtC,CAAC;YACD,MAAM,0BAA0B,CAC9B,OAAO,EACP,kDAAkD,CACnD,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CACjC,OAA+B,EAC/B,MAAe;IAEf,OAAO,IAAI,WAAW,CAAC,4CAA4C,EAAE;QACnE,IAAI,EAAE,iDAAiD;QACvD,OAAO,EAAE;YACP,YAAY,OAAO,CAAC,QAAQ,EAAE;YAC9B,SAAS,OAAO,CAAC,KAAK,EAAE;YACxB,YAAY,OAAO,CAAC,QAAQ,EAAE;YAC9B,WAAW,OAAO,CAAC,OAAO,EAAE;YAC5B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACxC,CAAC,IAAI,CAAC,GAAG,CAAC;KACZ,CAAC,CAAC;AACL,CAAC"}

package/dist/authorization/planner.d.ts

@@ -0,0 +1,21 @@
+import type { NormalizedSearchInput } from "../mcp/input-normalization.js";
+import type { EmbeddingModelInfo } from "../engine/models/index.js";
+import type { ZvecGrepInfoResult } from "../engine/service/types.js";
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import type { RemoteEmbeddingAuthorizationPlan } from "./types.js";
+export declare function planRemoteIndexAuthorization(input: {
+    info: ZvecGrepInfoResult;
+    model: EmbeddingModelInfo;
+    rebuild?: boolean;
+    needsUpdate?: boolean;
+    store?: RemoteEmbeddingAuthorizationStore;
+}): Promise<RemoteEmbeddingAuthorizationPlan | undefined>;
+export declare function planRemoteSearchAuthorization(input: {
+    info: ZvecGrepInfoResult;
+    model: EmbeddingModelInfo;
+    search: NormalizedSearchInput;
+    runtimeNeedsReconciliation?: boolean;
+    store?: RemoteEmbeddingAuthorizationStore;
+}): Promise<RemoteEmbeddingAuthorizationPlan | undefined>;
+export declare function searchUsesVector(input: Pick<NormalizedSearchInput, "queries" | "routes">): boolean;
+export declare function indexStatusIsFresh(info: ZvecGrepInfoResult): boolean;

package/dist/authorization/planner.js

@@ -0,0 +1,97 @@
+import { createRemoteEmbeddingTarget } from "./target.js";
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export async function planRemoteIndexAuthorization(input) {
+    if (input.model.provider !== "qwen")
+        return undefined;
+    const needsEmbedding = input.rebuild === true ||
+        input.needsUpdate === true ||
+        !input.info.indexed ||
+        !indexStatusIsFresh(input.info);
+    if (!needsEmbedding)
+        return undefined;
+    const endpoint = input.model.endpoint;
+    if (endpoint === undefined) {
+        throw new Error(`Embedding model ${input.model.reference} did not provide a remote endpoint.`);
+    }
+    const target = await createRemoteEmbeddingTarget({
+        roots: workspaceRoots(input.info),
+        provider: input.model.provider,
+        model: input.model.name,
+        endpoint,
+    });
+    const store = input.store ?? new RemoteEmbeddingAuthorizationStore();
+    return {
+        operation: "index",
+        target,
+        disclosure: {
+            queryText: false,
+            workspaceContent: !input.info.indexed || input.rebuild ? "full" : "changed",
+        },
+        reason: input.rebuild
+            ? "index_rebuild"
+            : input.info.indexed
+                ? "index_update"
+                : "index_create",
+        grantPath: store.grantPath(target),
+    };
+}
+export async function planRemoteSearchAuthorization(input) {
+    const schema = input.info.workspaceIndex?.embedding;
+    if (!input.info.indexed || !schema || schema.provider !== "qwen") {
+        return undefined;
+    }
+    if (input.model.provider !== schema.provider ||
+        input.model.name !== schema.model) {
+        throw new Error(`Embedding model ${input.model.reference} does not match indexed model ${schema.provider}/${schema.model}.`);
+    }
+    const usesVector = searchUsesVector(input.search);
+    const needsUpdate = input.runtimeNeedsReconciliation === true ||
+        !indexStatusIsFresh(input.info);
+    const updatesIndex = needsUpdate &&
+        (input.search.autoUpdate || input.search.freshness === "wait_for_fresh");
+    if (!usesVector && !updatesIndex)
+        return undefined;
+    const endpoint = input.model.endpoint;
+    if (endpoint === undefined) {
+        throw new Error(`Embedding model ${input.model.reference} did not provide a remote endpoint.`);
+    }
+    const target = await createRemoteEmbeddingTarget({
+        roots: workspaceRoots(input.info),
+        provider: input.model.provider,
+        model: input.model.name,
+        endpoint,
+    });
+    const store = input.store ?? new RemoteEmbeddingAuthorizationStore();
+    return {
+        operation: usesVector
+            ? updatesIndex
+                ? "query_and_index"
+                : "query"
+            : "index",
+        target,
+        disclosure: {
+            queryText: usesVector,
+            workspaceContent: updatesIndex ? "changed" : "none",
+        },
+        reason: "query",
+        grantPath: store.grantPath(target),
+    };
+}
+export function searchUsesVector(input) {
+    return ((input.queries?.length ?? 0) > 0 ||
+        input.routes.some((route) => route.mode === "vector"));
+}
+export function indexStatusIsFresh(info) {
+    const status = info.status;
+    return Boolean(status &&
+        status.filesAdded === 0 &&
+        status.filesModified === 0 &&
+        status.filesDeleted === 0 &&
+        status.filesPending === 0 &&
+        status.filesFailed === 0);
+}
+function workspaceRoots(info) {
+    const roots = info.workspaceIndex?.rootPaths.map((root) => root.absolutePath) ?? [];
+    return roots.length > 0 ? roots : [info.root];
+}
+//# sourceMappingURL=planner.js.map

package/dist/authorization/planner.js.map

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