vexp-cli 2.2.1 → 2.2.3

package/dist/hook-template.js

@@ -58,6 +58,12 @@ esac
  * Error aborts the tool call. Written to `.opencode/plugins/vexp-guard.js` by
  * `vexp setup-agents` (opencode auto-loads that directory at startup).
  *
+ * The SAME file is installed for Kilo Code at `.kilo/plugins/vexp-guard.js`
+ * (installKiloPlugin), because Kilo v7 is opencode vendored — its plugin loader
+ * lives at packages/opencode/src/config/plugin.ts inside Kilo-Org/kilocode, so
+ * the hook name, the `input.tool` ids and the grep/glob arg schemas are the same
+ * code and not merely a compatible API.
+ *
  * It blocks the native `grep`/`glob` tools AND shelled-out tree search
  * (grep/rg/find/... via bash) WHILE the vexp daemon is healthy, and fails OPEN
  * when the daemon is down so search still works without an index — mirroring
@@ -66,16 +72,31 @@ esac
  * The literal body is deliberately ASCII-only and free of backticks, `${...}`
  * and backslash escapes so it can be embedded verbatim in a TS template literal
  * (the VS Code extension keeps a byte-identical copy, enforced by the lockstep
- * test in packages/vexp-cli/test/hook-template.test.ts). Do NOT introduce any
+ * test in packages/vexp-cli/test/guard-lockstep.test.ts — which is where that
+ * guarantee actually lives; this comment used to point at hook-template.test.ts,
+ * which only ever compared the CLI constant with itself). Do NOT introduce any
  * of those characters here without updating that test's un-escape logic.
  */
-export const VEXP_OPENCODE_GUARD = `// vexp-guard - opencode plugin (generated by 'vexp setup-agents').
-// Forces the agent onto vexp's run_pipeline by blocking opencode's native
-// grep/glob (and shelled-out tree search) WHILE the vexp daemon is healthy.
+export const VEXP_OPENCODE_GUARD = `// vexp-guard - opencode / Kilo Code plugin (generated by 'vexp setup-agents'; it is
+// rewritten on every setup, and a modified copy is saved to vexp-guard.js.vexp-bak
+// first). Kilo v7 vendors opencode, so one plugin serves both unchanged.
+//
+// Blocks opencode's native grep/glob ONLY where vexp has a better answer: indexed
+// source inside the workspace, while the daemon is healthy. Two deliberate limits:
+//
+//   1. It never touches bash. Shelling out is the escape hatch for everything vexp
+//      cannot index - runtime logs, build output, files outside the repo. vexp's
+//      Claude Code guard has always matched Grep|Glob|Regex only, and it works
+//      precisely because that valve stays open. Blocking shell search instead
+//      teaches the agent to evade (any prefix defeats it) and strands it when the
+//      answer genuinely is not in the index.
+//   2. It only blocks targets vexp actually indexed. A search aimed at a log file,
+//      at dist/ or node_modules, or outside the workspace has no run_pipeline
+//      answer, so blocking it would be a dead end rather than a redirect.
+//
 // Fails OPEN when the daemon is down, so native search still works with no index.
-// Mirrors vexp's Claude Code PreToolUse guard (.claude/hooks/vexp-guard.sh).
 import { existsSync, readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, relative, isAbsolute, sep } from "node:path";
 
 // Walk up from start to the first ancestor that owns a .vexp dir.
 function findVexpDir(start) {
@@ -108,36 +129,248 @@ function daemonHealthy(vexpDir) {
 }
 
 const SEARCH_TOOLS = new Set(["grep", "glob"]);
-const SHELL_SEARCH_BINS = ["rg", "grep", "egrep", "fgrep", "ag", "ack", "find", "fd", "fdfind"];
 
-// True when a bash command's first token is a tree-search binary (grep/rg/find).
-function isShellSearch(command) {
-  const t = (command || "").trim();
-  for (const b of SHELL_SEARCH_BINS) {
-    if (t === b || t.indexOf(b + " ") === 0) return true;
+// Directory names vexp never indexes: build output and vendored dependencies.
+const NON_INDEXED_DIRS = [
+  "node_modules", "dist", "build", "out", "coverage", "target", "vendor",
+  ".vite", ".next", ".nuxt", ".output", ".turbo", ".cache", ".git", ".vexp"
+];
+
+// File kinds vexp never indexes. Logs are the case agents legitimately grep the
+// most while debugging a running app. "-lock." is not redundant with ".lock":
+// the two commonest JS lockfiles (package-lock.json, pnpm-lock.yaml) have no dot
+// before "lock", so ".lock" alone let yarn.lock and Cargo.lock through while
+// blocking them.
+const NON_INDEXED_HINTS = [".log", ".lock", "-lock.", ".map", ".min.js"];
+
+// Is this search target inside what vexp indexed? Only then is "call
+// run_pipeline instead" real advice rather than a dead end. Anything that cannot
+// be resolved confidently returns false (allow) - under-blocking just leaves the
+// agent on grep, over-blocking strands it with no tool at all.
+function isIndexedTarget(root, target) {
+  if (!target) return true; // no path given: a whole-workspace search is vexp's job
+  const s = String(target);
+  const low = s.toLowerCase();
+  for (const h of NON_INDEXED_HINTS) if (low.indexOf(h) !== -1) return false;
+  let rel;
+  try {
+    rel = relative(root, isAbsolute(s) ? s : join(root, s));
+  } catch (e) {
+    return false;
   }
-  return false;
+  if (rel === "..") return false;
+  if (rel.indexOf(".." + sep) === 0) return false; // escapes the workspace
+  if (isAbsolute(rel)) return false; // different root or drive
+  const segs = rel.split(sep);
+  for (const g of segs) if (NON_INDEXED_DIRS.indexOf(g) !== -1) return false;
+  return true;
+}
+
+// Where a search is aimed. grep carries the regex in its pattern arg (never a
+// path), so only path and the include filter describe its target; for glob the
+// pattern IS the path.
+function searchTargets(tool, args) {
+  if (!args) return [];
+  const out = [];
+  if (args.path) out.push(args.path);
+  if (tool === "glob" && args.pattern) out.push(args.pattern);
+  if (tool === "grep" && args.include) out.push(args.include);
+  return out;
 }
 
 export const VexpGuard = async ({ directory, worktree }) => {
-  const root = worktree || directory || ".";
+  const start = worktree || directory || ".";
   let vexpDir = null;
   return {
     "tool.execute.before": async (input, output) => {
-      if (!vexpDir) vexpDir = findVexpDir(root);
-      if (!daemonHealthy(vexpDir)) return;
-      if (SEARCH_TOOLS.has(input.tool)) {
-        throw new Error(
-          "vexp daemon is running - call run_pipeline instead of " + input.tool +
-          " (pre-indexed, graph-ranked, ~60% fewer tokens)."
-        );
-      }
-      if (input.tool === "bash" && isShellSearch(output && output.args && output.args.command)) {
-        throw new Error(
-          "vexp daemon is running - call run_pipeline instead of shell search (grep/rg/find)."
-        );
+      if (!vexpDir) vexpDir = findVexpDir(start);
+      if (!daemonHealthy(vexpDir)) return; // no live index -> allow
+      if (!SEARCH_TOOLS.has(input.tool)) return; // bash and everything else: never blocked
+      const root = dirname(vexpDir);
+      const targets = searchTargets(input.tool, output && output.args);
+      for (const t of targets) {
+        if (!isIndexedTarget(root, t)) return; // vexp has no answer here -> allow
       }
+      throw new Error(
+        "vexp daemon is running. AGENT INSTRUCTION: call run_pipeline instead of " +
+        input.tool + " - it returns pre-indexed, graph-ranked context in one call." +
+        " This is policy, not a transient failure: do NOT work around it with shell" +
+        " search or by writing a script."
+      );
     },
   };
 };
 `;
+/**
+ * Cursor `preToolUse` hook. Same policy as the Claude Code hook and the
+ * opencode/Kilo plugin — block text search while the vexp daemon is healthy,
+ * never touch the shell, never block a target vexp did not index — expressed in
+ * the third dialect we now have to speak.
+ *
+ * Written in NODE, not bash, and that is deliberate. The Claude Code guard is a
+ * bash script and it silently enforced NOTHING on Windows for several releases
+ * (`[ -S "$SOCK" ]` can never match a named pipe), which is the single most
+ * expensive bug this file has produced. Cursor documents no PowerShell variant
+ * of `command` and does not say which shell runs it on Windows, so a bash guard
+ * here would be that bug again by construction. Anyone who installed vexp has
+ * node on PATH; a node script is the one interpreter we can count on everywhere.
+ *
+ * Denial is emitted on BOTH documented channels — the stdout verdict object and
+ * exit code 2 — because Cursor's docs describe both and we cannot test which one
+ * this build actually honours. Belt and braces on a schema we are trusting on
+ * documentation alone.
+ *
+ * Fails OPEN in every uncertain case: daemon down, unparseable input, an unknown
+ * payload shape. An over-eager guard strands the agent with no way to look at
+ * anything; an under-eager one costs tokens. Those are not symmetric.
+ *
+ * ASCII-only, no backticks and no ${...}: it is embedded verbatim in a TS
+ * template literal in two packages (lockstep test in test/guard-lockstep.test.ts).
+ */
+export const VEXP_CURSOR_GUARD = `#!/usr/bin/env node
+// vexp-guard - Cursor preToolUse hook (generated by 'vexp setup-agents'; rewritten
+// on every setup, and a modified copy is saved to vexp-guard.js.vexp-bak first).
+//
+// Blocks Cursor's Grep tool ONLY where vexp has a better answer: indexed source
+// inside the workspace, while the daemon is healthy. Never blocks Shell - that
+// valve is what keeps the agent able to reach logs, build output and anything
+// outside the repo, and blocking it teaches evasion instead of redirection.
+//
+// NOTE: Cursor's native semantic codebase search is NOT exposed to hooks, so it
+// cannot be redirected. This guard covers text search only.
+const fs = require("node:fs");
+const path = require("node:path");
+
+function findVexpDir(start) {
+  let dir = start;
+  for (;;) {
+    if (fs.existsSync(path.join(dir, ".vexp"))) return path.join(dir, ".vexp");
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function pidAlive(pidFile) {
+  let pid = 0;
+  try { pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10); } catch (e) { return false; }
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return !!(e && e.code === "EPERM"); }
+}
+
+// The daemon writes .vexp/healthy when up and removes it on graceful shutdown.
+// Unix also requires a live socket AND a live pid: healthy + socket both linger
+// after a kill -9, so the pid check is what makes fail-open actually work.
+// Windows has no socket file, so the daemon drops .vexp/daemon.pipe instead.
+function daemonHealthy(vexpDir) {
+  if (!vexpDir || !fs.existsSync(path.join(vexpDir, "healthy"))) return false;
+  if (process.platform === "win32") return fs.existsSync(path.join(vexpDir, "daemon.pipe"));
+  return fs.existsSync(path.join(vexpDir, "daemon.sock")) && pidAlive(path.join(vexpDir, "daemon.pid"));
+}
+
+const NON_INDEXED_DIRS = [
+  "node_modules", "dist", "build", "out", "coverage", "target", "vendor",
+  ".vite", ".next", ".nuxt", ".output", ".turbo", ".cache", ".git", ".vexp"
+];
+const NON_INDEXED_HINTS = [".log", ".lock", "-lock.", ".map", ".min.js"];
+
+// Is this search target inside what vexp indexed? Only then is "call
+// run_pipeline instead" real advice rather than a dead end. Anything that cannot
+// be resolved confidently returns false (allow).
+function isIndexedTarget(root, target) {
+  if (!target) return true; // no path given: a whole-workspace search is vexp's job
+  const s = String(target);
+  const low = s.toLowerCase();
+  for (const h of NON_INDEXED_HINTS) if (low.indexOf(h) !== -1) return false;
+  let rel;
+  try {
+    rel = path.relative(root, path.isAbsolute(s) ? s : path.join(root, s));
+  } catch (e) {
+    return false;
+  }
+  if (rel === "..") return false;
+  if (rel.indexOf(".." + path.sep) === 0) return false; // escapes the workspace
+  if (path.isAbsolute(rel)) return false; // different root or drive
+  const segs = rel.split(path.sep);
+  for (const g of segs) if (NON_INDEXED_DIRS.indexOf(g) !== -1) return false;
+  return true;
+}
+
+function allow() {
+  process.stdout.write(JSON.stringify({ permission: "allow" }));
+  process.exit(0);
+}
+
+function deny(toolName) {
+  const reason =
+    "vexp daemon is running. AGENT INSTRUCTION: call run_pipeline instead of " +
+    toolName + " - it returns pre-indexed, graph-ranked context in one call." +
+    " This is policy, not a transient failure: do NOT work around it with shell" +
+    " search or by writing a script.";
+  // Both documented channels: the verdict object AND exit 2.
+  process.stdout.write(JSON.stringify({
+    permission: "deny",
+    agent_message: reason,
+    user_message: "vexp blocked a text search; the agent was told to use run_pipeline."
+  }));
+  process.stderr.write(reason);
+  process.exit(2);
+}
+
+// Cursor documents tool_input for Shell only; the payload shape for a Grep call
+// appears NOWHERE in its docs. Rather than guess key names - a guess that fires,
+// reads undefined and then blocks everything or nothing - we do not read keys at
+// all. We scan the VALUES of tool_input for anything path-shaped. That is immune
+// to whatever the keys turn out to be called, and to them being renamed later.
+//
+// The search pattern itself is one of those values and may look like a path. It
+// can only ever push us toward ALLOW (a pattern mentioning node_modules reads as
+// a non-indexed target), never toward a wrongful block - which is the direction
+// we want to be wrong in.
+function candidateTargets(toolInput) {
+  if (!toolInput) return [];
+  // MCP hooks receive tool_input as a JSON *string*, so the type is not uniform.
+  let obj = toolInput;
+  if (typeof obj === "string") {
+    try { obj = JSON.parse(obj); } catch (e) { return []; }
+  }
+  if (typeof obj !== "object") return [];
+  // EVERY string value, with no "does this look like a path" pre-filter. An
+  // earlier version required a separator or a dot and therefore missed bare
+  // directory names - "dist", "build", "node_modules" - which are exactly the
+  // targets the carve-out exists to protect. Handing the search pattern itself
+  // to isIndexedTarget is harmless: a pattern that reads as non-indexed only
+  // ever produces an ALLOW, and a pattern that reads as indexed changes nothing.
+  const out = [];
+  for (const v of Object.values(obj)) {
+    if (typeof v === "string" && v) out.push(v);
+  }
+  return out;
+}
+
+function main(input) {
+  const toolName = input && input.tool_name;
+  // Grep only. Shell is never blocked - it is the valve for everything vexp
+  // cannot index - and Read is never blocked because an agent must read to edit.
+  if (toolName !== "Grep") return allow();
+
+  const roots = (input && input.workspace_roots) || [];
+  const start = roots[0] || (input && input.cwd) || process.cwd();
+  const vexpDir = findVexpDir(start);
+  if (!daemonHealthy(vexpDir)) return allow(); // no live index -> allow
+  const root = path.dirname(vexpDir);
+
+  for (const t of candidateTargets(input.tool_input)) {
+    if (!isIndexedTarget(root, t)) return allow(); // vexp has no answer here
+  }
+  deny(toolName);
+}
+
+let raw = "";
+process.stdin.on("data", (c) => { raw += c; });
+process.stdin.on("end", () => {
+  let input;
+  try { input = JSON.parse(raw); } catch (e) { return allow(); }
+  try { main(input); } catch (e) { allow(); } // any surprise -> fail open
+});
+`;

package/dist/workspace-repos.js

@@ -0,0 +1,166 @@
+import * as path from "path";
+import * as fs from "fs";
+import * as os from "os";
+/** Expand a leading `~` — readline input arrives unexpanded, unlike a shell arg. */
+export function expandHome(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\")) {
+        return path.join(os.homedir(), p.slice(2));
+    }
+    return p;
+}
+/**
+ * Resolve a `repos[].path` entry like vexp-core's `resolve_repo_path`:
+ * absolute paths are preserved, relative paths resolve against the workspace
+ * ROOT. Configs written before 2.2.1 stored paths relative to `.vexp/`, so
+ * when the root-relative answer is not a directory we fall back to the legacy
+ * base — same order as the Rust resolver, so list/add agree with the daemon.
+ */
+export function resolveRepoEntryPath(workspaceRoot, raw) {
+    if (path.isAbsolute(raw))
+        return path.normalize(raw);
+    const fromRoot = path.resolve(workspaceRoot, raw);
+    if (fs.existsSync(fromRoot))
+        return fromRoot;
+    const fromLegacy = path.resolve(workspaceRoot, ".vexp", raw);
+    if (fs.existsSync(fromLegacy))
+        return fromLegacy;
+    return fromRoot;
+}
+function readWorkspaceConfig(configPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        if (!parsed || !Array.isArray(parsed.repos))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * If `childRoot` is a secondary repo of a multi-repo workspace, return the
+ * parent workspace info. The link is `.vexp/parent_workspace.json` (written on
+ * add, both by the VS Code plugin and by `addRepoToWorkspace` below).
+ *
+ * Returns null — i.e. "treat this repo as standalone" — unless the parent
+ * config still exists AND still lists this repo: a stale parent_workspace.json
+ * left behind after the repo was disconnected must not hijack the CLI.
+ */
+export function resolveParentWorkspace(childRoot) {
+    let configPath;
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(childRoot, ".vexp", "parent_workspace.json"), "utf-8"));
+        if (typeof raw?.workspace_config !== "string")
+            return null;
+        configPath = raw.workspace_config;
+    }
+    catch {
+        return null;
+    }
+    if (!fs.existsSync(configPath))
+        return null;
+    // workspace.json lives in <parentRoot>/.vexp/
+    const parentRoot = path.dirname(path.dirname(configPath));
+    if (path.resolve(parentRoot) === path.resolve(childRoot))
+        return null;
+    const config = readWorkspaceConfig(configPath);
+    if (!config)
+        return null;
+    const childResolved = path.resolve(childRoot);
+    const listed = config.repos.some((r) => {
+        if (typeof r?.path !== "string")
+            return false;
+        return path.resolve(resolveRepoEntryPath(parentRoot, r.path)) === childResolved;
+    });
+    if (!listed)
+        return null;
+    return {
+        parentRoot,
+        workspaceName: config.name ?? path.basename(parentRoot),
+        configPath,
+    };
+}
+/**
+ * Repos connected to the workspace at `workspaceRoot`. Empty array when there
+ * is no workspace.json (single-repo workspace).
+ */
+export function listWorkspaceRepos(workspaceRoot) {
+    const configPath = path.join(workspaceRoot, ".vexp", "workspace.json");
+    const config = readWorkspaceConfig(configPath);
+    if (!config)
+        return [];
+    const rootResolved = path.resolve(workspaceRoot);
+    return config.repos
+        .filter((r) => typeof r?.path === "string" && typeof r?.alias === "string")
+        .map((r) => {
+        const resolvedPath = resolveRepoEntryPath(workspaceRoot, r.path);
+        return {
+            alias: r.alias,
+            rawPath: r.path,
+            resolvedPath,
+            isPrimary: path.resolve(resolvedPath) === rootResolved,
+            exists: fs.existsSync(resolvedPath),
+        };
+    });
+}
+/**
+ * Connect `newRepoPath` to the workspace at `workspaceRoot` — the exact write
+ * sequence of the VS Code `vexp.setupMultiRepo` command:
+ *   1. plan-limit guard BEFORE writing anything (maxRepos, 0 = unlimited)
+ *   2. read-or-create workspace.json (primary entry is `"."` — the 2.2.1+
+ *      root-relative convention)
+ *   3. append `{ alias, path: <absolute> }` unless already present
+ *   4. write `.vexp/parent_workspace.json` in the child so opening the child
+ *      resolves back to this workspace
+ *
+ * Indexing is NOT triggered here — the caller decides whether to restart the
+ * daemon (mirrors the plugin's "Restart / Later" prompt).
+ */
+export function addRepoToWorkspace(workspaceRoot, newRepoPath, maxRepos) {
+    const resolved = path.resolve(expandHome(newRepoPath.trim()));
+    let stat;
+    try {
+        stat = fs.statSync(resolved);
+    }
+    catch {
+        return { status: "invalid", reason: `Directory not found: ${resolved}` };
+    }
+    if (!stat.isDirectory()) {
+        return { status: "invalid", reason: `Not a directory: ${resolved}` };
+    }
+    if (path.resolve(workspaceRoot) === resolved) {
+        return { status: "invalid", reason: "That is the workspace root itself — it is already the primary repo." };
+    }
+    const configPath = path.join(workspaceRoot, ".vexp", "workspace.json");
+    const alias = path.basename(resolved);
+    // Plan-limit guard: same semantics as the plugin — count existing entries,
+    // block only genuinely-new repos, never after a partial write.
+    let config = readWorkspaceConfig(configPath);
+    const currentCount = config ? config.repos.length : 1; // primary always exists
+    const alreadyExists = config?.repos.some((r) => r.alias === alias ||
+        r.path === resolved ||
+        path.resolve(resolveRepoEntryPath(workspaceRoot, r.path)) === resolved) ?? false;
+    if (alreadyExists) {
+        return { status: "exists", alias };
+    }
+    if (maxRepos > 0 && currentCount >= maxRepos) {
+        return { status: "limit", maxRepos, current: currentCount };
+    }
+    if (!config) {
+        config = {
+            name: path.basename(workspaceRoot),
+            repos: [{ alias: path.basename(workspaceRoot), path: "." }],
+        };
+    }
+    config.repos.push({ alias, path: resolved });
+    fs.mkdirSync(path.join(workspaceRoot, ".vexp"), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    // Bidirectional link in the child, so `vexp` run there targets this
+    // workspace's daemon instead of spawning a conflicting one.
+    const childVexpDir = path.join(resolved, ".vexp");
+    fs.mkdirSync(childVexpDir, { recursive: true });
+    fs.writeFileSync(path.join(childVexpDir, "parent_workspace.json"), JSON.stringify({ workspace_config: configPath }, null, 2));
+    return { status: "added", alias, configPath };
+}