vexp-cli 2.2.1 → 2.2.2

package/dist/agent-config.js

@@ -376,6 +376,60 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
 export function getAgentList() {
     return [...AGENT_DETECTORS];
 }
+/** Fold a name to its comparable form: case, spaces, dots and dashes carry no
+ *  meaning here ("claude-code", "Claude Code" and "claudecode" are one agent). */
+function foldAgentName(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/**
+ * Canonicalize a name given to `--agents`, or null if it names no agent.
+ *
+ * `configureSelectedAgents` matches with `Array.includes` on the exact string,
+ * so "opencode" silently configured nothing while "Opencode" worked — nobody
+ * can be expected to know the capitalization, and the failure was invisible.
+ */
+export function resolveAgentName(input) {
+    const want = foldAgentName(input);
+    if (!want)
+        return null;
+    return AGENT_DETECTORS.find((d) => foldAgentName(d.agent) === want)?.agent ?? null;
+}
+/** Levenshtein distance, for "did you mean" on an unknown --agents name. */
+function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    const cur = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev.splice(0, prev.length, ...cur);
+    }
+    return prev[b.length];
+}
+/**
+ * The known agent an unknown name most likely meant, or null when nothing is
+ * close enough to be worth suggesting. Substring hits win (a bare "copilot"
+ * means "GitHub Copilot"); otherwise allow a couple of typos.
+ */
+export function suggestAgentName(input) {
+    const want = foldAgentName(input);
+    if (!want)
+        return null;
+    const contained = AGENT_DETECTORS.find((d) => {
+        const f = foldAgentName(d.agent);
+        return f.includes(want) || want.includes(f);
+    });
+    if (contained)
+        return contained.agent;
+    let best = null;
+    for (const d of AGENT_DETECTORS) {
+        const dist = editDistance(want, foldAgentName(d.agent));
+        if (!best || dist < best.d)
+            best = { name: d.agent, d: dist };
+    }
+    return best && best.d <= 3 ? best.name : null;
+}
 /**
  * Configure specific agents selected by the user.
  * Unlike configureAgents which auto-detects, this forces configuration
@@ -1358,10 +1412,38 @@ export function installOpencodePlugin(workspaceRoot) {
         const current = fs.readFileSync(pluginPath, "utf-8");
         if (current === VEXP_OPENCODE_GUARD)
             return null; // identical - skip
+        // Content differs: either an older vexp guard, or a copy the user tuned by
+        // hand. We refresh either way — refusing to touch a hand-edited plugin would
+        // freeze that user on a stale guard forever — but their version stays
+        // recoverable at vexp-guard.js.vexp-bak instead of being silently discarded.
+        backupConfig(pluginPath);
     }
     fs.writeFileSync(pluginPath, VEXP_OPENCODE_GUARD, "utf-8");
     return existed ? "updated" : "created";
 }
+/**
+ * The single highest-leverage instruction we ship, and for a long time the one
+ * most agents never saw.
+ *
+ * vexp retrieval is identifier/path-first: FTS supplies the candidate pool and
+ * the semantic layer only RE-RANKS it, so a symbol that no query token reaches
+ * never enters the running at all. A task written as prose ("why does the proxy
+ * fail?") therefore ranks far worse than the same task anchored on the symbols
+ * and paths it is actually about — the difference between a useful pivot set and
+ * "the vexp result wasn't relevant".
+ *
+ * This shipped only in the Claude Code and Cursor templates, while the AGENTS.md
+ * example (`"task": "fix auth bug"`) actively modelled the weak mode — so two
+ * independent field reports ("the index seems not very useful") came from users
+ * whose instructions never told them the one thing that makes retrieval land.
+ * Shared by every prose template so the wording cannot drift again. ASCII only
+ * (these land in files that get read on Windows).
+ */
+const QUERY_SHAPE = `### Query shape (do this)
+- Anchor the task on real identifiers (ClassName, functionName) or file paths:
+  \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
+- A pure natural-language question ("why does login fail?") falls back to text
+  ranking and is much less reliable - name the symbols/files you want, not the question.`;
 function generateAgentConfig(template, vars) {
     switch (template) {
         case "claude-code":
@@ -1403,6 +1485,12 @@ uses fewer tokens than manual searching. Prefer \`get_skeleton\` over Read to
 inspect files (detail: minimal/standard/detailed, 70-90% token savings).
 Only use Read when you need exact raw content to edit a specific line.
 
+The hook denies Grep/Glob while the daemon is up. That is policy, not a transient
+failure: call \`run_pipeline\` instead - do NOT work around it by shelling out or
+writing a script. vexp only covers indexed source inside the workspace: for runtime
+logs, build output (dist/, .vite/, node_modules/) or files outside the repo it has
+no answer - use Bash/Read there, those are never blocked.
+
 ### Primary Tool
 - \`run_pipeline\` - **USE THIS FOR EVERYTHING**. Single call that runs
   capsule + impact + memory server-side. Returns compressed results.
@@ -1418,6 +1506,8 @@ Only use Read when you need exact raw content to edit a specific line.
 - \`index_status\` - indexing status and health check
 - \`expand_vexp_ref\` - expand V-REF hash placeholders in v2 compact output
 
+${QUERY_SHAPE}
+
 ### Workflow
 1. \`run_pipeline("your task")\` - ALWAYS FIRST. Returns pivots + impact + memories in 1 call
 2. Need more detail on a file? Use \`get_skeleton({ files: [...], detail: "detailed" })\` - avoid Read unless editing
@@ -1438,9 +1528,6 @@ Only use Read when you need exact raw content to edit a specific line.
 - **Session Memory**: auto-captures observations; memories auto-surfaced in results
 - **LSP Bridge**: VS Code captures type-resolved call edges
 - **Change Coupling**: co-changed files included as related context
-- **Query tips**: include real identifiers (ClassName, function_name) or file paths
-  in the task for precise matches - pure natural-language phrasing falls back to
-  text ranking and is less reliable
 
 ### Advanced Parameters
 - \`preset: "debug"\` - forces debug mode (capsule+tests+impact+memory)
@@ -1471,19 +1558,19 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
   rather than letting them search the codebase independently
 
 ### Tips
-- Include real identifiers (class/function names) or file paths in the task - literal
-  matches rank best; pure natural-language phrasing falls back to text ranking
 - Add \`include_tests: true\` when debugging
 - Use \`preset: "refactor"\` for deep impact analysis
 
@@ -1511,11 +1598,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1560,11 +1649,13 @@ When working on this codebase:
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - token-efficient file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1590,11 +1681,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1620,11 +1713,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1650,13 +1745,20 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Auto-detects intent. Includes file content. Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
+- If a search tool is denied, that is policy, not a transient failure: call \`run_pipeline\`
+  instead. Do NOT work around it with shell search or by writing a script.
+- vexp only covers indexed source inside the workspace. For runtime logs, build output
+  (dist/, .vite/, node_modules/) or files outside the repo it has no answer - use your
+  normal tools there; those searches are never blocked.
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
   rather than letting them search the codebase independently
 
@@ -1680,11 +1782,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ## Available vexp tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ## Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`
@@ -1710,11 +1814,13 @@ vexp returns pre-indexed, graph-ranked context in a single call.
 
 ### Available MCP tools
 - \`run_pipeline\` - **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call.
-  Example: \`run_pipeline({ "task": "fix auth bug" })\`
+  Example: \`run_pipeline({ "task": "fix JWT expiry in AuthService.validateToken" })\`
 - \`get_skeleton\` - compact file structure
 - \`index_status\` - indexing status
 - \`expand_vexp_ref\` - expand V-REF placeholders in v2 output
 
+${QUERY_SHAPE}
+
 ### Agentic search
 - Do NOT use built-in file search, grep, or codebase indexing - always call \`run_pipeline\` first
 - If you spawn sub-agents or background tasks, pass them the context from \`run_pipeline\`

package/dist/cli.js

@@ -8,7 +8,7 @@ import * as fs from "fs";
 import * as net from "net";
 import { checkbox, confirm } from "@inquirer/prompts";
 import { getBinaryPath, getInstalledVersion, getMcpServerPath, binaryEnv } from "./binary.js";
-import { detectAgents, getAgentList, configureSelectedAgents } from "./agent-config.js";
+import { detectAgents, getAgentList, configureSelectedAgents, resolveAgentName, suggestAgentName } from "./agent-config.js";
 import { CLI_VERSION } from "./version.js";
 import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, } from "./license.js";
 import { checkForUpdate } from "./update-check.js";
@@ -555,8 +555,24 @@ program
         const detectedNames = new Set(detected.map((a) => a.agent));
         let selectedNames;
         if (typeof opts.agents === "string") {
-            // Explicit list from --agents flag
-            selectedNames = opts.agents.split(",").map((s) => s.trim());
+            // Explicit list from --agents flag. Resolve every name BEFORE writing
+            // anything: matching is exact downstream, so an unrecognised name used
+            // to configure nothing while setup still reported success — the worst
+            // possible outcome for the flag whose whole point is automation.
+            const requested = opts.agents.split(",").map((s) => s.trim()).filter(Boolean);
+            const unknown = requested.filter((n) => resolveAgentName(n) === null);
+            if (unknown.length > 0 || requested.length === 0) {
+                console.error(chalk.red(`\n✖ Unknown agent: ${unknown.map((u) => `"${u}"`).join(", ") || "(empty --agents list)"}`));
+                for (const u of unknown) {
+                    const hint = suggestAgentName(u);
+                    if (hint)
+                        console.error(chalk.yellow(`  Did you mean: ${hint}?`));
+                }
+                console.error(chalk.dim(`  Valid agents: ${allAgents.map((a) => a.agent).join(", ")}`));
+                console.error(chalk.dim("  Names are matched ignoring case and punctuation.\n"));
+                process.exit(1);
+            }
+            selectedNames = requested.map((n) => resolveAgentName(n));
             console.log(chalk.dim(`  Agents (from flag): ${selectedNames.join(", ")}`));
         }
         else {

package/dist/hook-template.js

@@ -69,13 +69,25 @@ esac
  * test in packages/vexp-cli/test/hook-template.test.ts). 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 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).
+//
+// 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,35 +120,74 @@ 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."
+      );
     },
   };
 };