repowisestage 0.0.47 → 0.0.48

package/dist/bin/repowise.js

@@ -1316,6 +1316,7 @@ var init_sidecar_client = __esm({
 // ../listener/dist/lsp/lsp-tools.js
 var lsp_tools_exports = {};
 __export(lsp_tools_exports, {
+  emptyLspResult: () => emptyLspResult,
   lspCallHierarchy: () => lspCallHierarchy,
   lspDefinition: () => lspDefinition,
   lspDocumentSymbol: () => lspDocumentSymbol,
@@ -1357,6 +1358,25 @@ function pickAvailableConfig(configs, isAvailable) {
   }
   return null;
 }
+function emptyLspResult(reason, details) {
+  if (reason === "unsupported-language") {
+    return {
+      ok: false,
+      reason,
+      isError: true,
+      error: "unsupported-language" + (details?.language ? `: ${details.language}` : "") + " \u2014 no LSP server registered for this file extension.",
+      hint: "RepoWise auto-installs LSP servers for known languages (TS/JS, Python, Go, Rust, Ruby, etc.). For an unsupported language fall back to graph-only tools: `find_symbol`, `find_callers`, `find_references`, `get_call_graph`."
+    };
+  }
+  const triedFrag = details?.tried && details.tried.length > 0 ? ` (tried: ${details.tried.join(", ")})` : "";
+  return {
+    ok: false,
+    reason,
+    isError: true,
+    error: `no-server-available${triedFrag} \u2014 the LSP binary for this language isn't on PATH or in the listener's install dir.`,
+    hint: "The listener auto-installs npm-based LSP servers (pyright, typescript-language-server, etc.) on boot. If the install failed, check listener stderr for the underlying npm error. Non-npm servers (gopls, rust-analyzer, sourcekit-lsp, ruby-lsp) need manual install \u2014 see the listener log for the per-language hint. Until then, use graph-only tools (`find_symbol`, `find_callers`, etc.) for this file."
+  };
+}
 function toOneIndexed(pos) {
   return { line: pos.line + 1, column: pos.character + 1 };
 }
@@ -1419,13 +1439,13 @@ function normalizeLocations(raw, repoRoot) {
 async function getSession(deps, file) {
   const language = detectLanguage(file);
   if (!language)
-    return { ok: false, reason: "unsupported-language" };
+    return emptyLspResult("unsupported-language");
   const configs = LSP_REGISTRY[language];
   const config2 = pickAvailableConfig(configs, deps.binaryAvailable);
   if (!config2) {
-    const tried = configs.map((c) => c.command).join(", ");
-    console.warn(`[lsp:${language}] no server available on PATH \u2014 tried: ${tried}`);
-    return { ok: false, reason: "no-server-available" };
+    const tried = configs.map((c) => c.command);
+    console.warn(`[lsp:${language}] no server available on PATH \u2014 tried: ${tried.join(", ")}`);
+    return emptyLspResult("no-server-available", { language, tried });
   }
   const session = await deps.workspaces.getOrOpen({
     repoRoot: deps.repoRoot,
@@ -1438,7 +1458,7 @@ async function getSession(deps, file) {
 async function lspDefinition(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/definition", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position)
@@ -1448,7 +1468,7 @@ async function lspDefinition(deps, req) {
 async function lspReferences(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/references", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position),
@@ -1459,7 +1479,7 @@ async function lspReferences(deps, req) {
 async function lspHover(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/hover", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position)
@@ -1502,7 +1522,7 @@ function normalizeHoverContents(contents) {
 async function lspCallHierarchy(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const limit = req.limit ?? 200;
   const prepared = await got.session.client.request("textDocument/prepareCallHierarchy", {
     textDocument: { uri: got.uri },
@@ -1541,7 +1561,7 @@ async function lspCallHierarchy(deps, req) {
 async function lspImplementation(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const result = await got.session.client.request("textDocument/implementation", {
     textDocument: { uri: got.uri },
     position: toZeroIndexed(req.position)
@@ -1551,7 +1571,7 @@ async function lspImplementation(deps, req) {
 async function lspTypeHierarchy(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const limit = req.limit ?? 200;
   const prepared = await got.session.client.request("textDocument/prepareTypeHierarchy", {
     textDocument: { uri: got.uri },
@@ -1587,8 +1607,11 @@ async function lspTypeHierarchy(deps, req) {
 }
 async function lspWorkspaceSymbol(deps, req) {
   const sessions = deps.workspaces.activeSessions().filter((s) => !req.language || s.language === req.language);
-  if (sessions.length === 0)
-    return { ok: false, reason: "no-server-available" };
+  if (sessions.length === 0) {
+    return emptyLspResult("no-server-available", {
+      language: req.language
+    });
+  }
   const symbols = [];
   for (const session of sessions) {
     const raw = await session.client.request("workspace/symbol", { query: req.query });
@@ -1616,7 +1639,7 @@ async function lspWorkspaceSymbol(deps, req) {
 async function lspDocumentSymbol(deps, req) {
   const got = await getSession(deps, req.file);
   if (!got.ok)
-    return { ok: false, reason: got.reason };
+    return got;
   const raw = await got.session.client.request("textDocument/documentSymbol", {
     textDocument: { uri: got.uri }
   });
@@ -4333,8 +4356,8 @@ var TOOL_CATALOG = [
   },
   {
     name: "search_pattern",
-    description: "Regex-match symbol names across the graph.",
-    whenToUse: 'Use when the user asks for a pattern rather than a literal substring \u2014 e.g. "anything ending in `Repository`", "every `handle*` function". For plain substring search use `find_symbol`.',
+    description: "JavaScript-flavor regex match against symbol names. Uses `new RegExp(pattern, flags)` \u2014 no Python-only constructs (`(?P<name>...)`, `(?i)`-style inline flags, `\\A` / `\\Z` anchors).",
+    whenToUse: 'Use when the user asks for a pattern rather than a literal substring \u2014 e.g. "anything ending in `Repository`", "every `handle*` function". For plain substring search use `find_symbol`. For case-insensitive matching set `flags: "i"`, NOT a `(?i)` prefix.',
     inputSchema: {
       type: "object",
       properties: {
@@ -4801,16 +4824,31 @@ function listEdges(graphJson, req) {
     freshness: freshnessEnvelope(graph)
   };
 }
+function detectCommonRegexMistake(pattern) {
+  if (/\(\?P</.test(pattern)) {
+    return "Python named groups `(?P<name>\u2026)` aren't supported. Use `(?<name>\u2026)` (JS named-group syntax) or just `(\u2026)`.";
+  }
+  if (/^\(\?[ims]+\)/.test(pattern)) {
+    return 'Python-style inline flags `(?i)` aren\'t supported. Pass them as the `flags` parameter, e.g. `flags: "i"`.';
+  }
+  if (/\\A|\\Z/.test(pattern)) {
+    return "Python anchors `\\A` / `\\Z` are valid JS regex but match LITERAL `A` / `Z`, not start-of-string / end-of-string. Use `^` / `$` (JS anchors) with the `m` flag for multiline.";
+  }
+  return void 0;
+}
 var MAX_PATTERN_LENGTH = 200;
 var REDOS_PATTERN = /(\([^)]*[+*]\)|\[[^\]]*[+*]\])[+*?]/;
 function searchPattern(graphJson, req) {
   const graph = graphJson;
   if (!req.pattern || req.pattern.length > MAX_PATTERN_LENGTH) {
+    const reason = !req.pattern ? "Empty pattern \u2014 pass a non-empty regex string." : `Pattern exceeds ${MAX_PATTERN_LENGTH.toString()} chars (${req.pattern.length.toString()} chars). Use a tighter expression or filter via \`kind\` / \`language\` / \`file\`.`;
     return {
       matches: [],
       coverage: coverageEnvelope(graph, 0),
       freshness: freshnessEnvelope(graph),
-      unsafePattern: true
+      unsafePattern: true,
+      error: reason,
+      isError: true
     };
   }
   if (REDOS_PATTERN.test(req.pattern)) {
@@ -4818,19 +4856,26 @@ function searchPattern(graphJson, req) {
       matches: [],
       coverage: coverageEnvelope(graph, 0),
       freshness: freshnessEnvelope(graph),
-      unsafePattern: true
+      unsafePattern: true,
+      error: "Pattern rejected by ReDoS guard \u2014 nested quantifiers like `(a+)+` or `[\u2026]*+` can cause catastrophic backtracking. Flatten the quantifiers or split into multiple calls.",
+      isError: true
     };
   }
   const flags = (req.flags ?? "").replace(/g/g, "");
   let re;
   try {
     re = new RegExp(req.pattern, flags);
-  } catch {
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const hint = detectCommonRegexMistake(req.pattern);
     return {
       matches: [],
       coverage: coverageEnvelope(graph, 0),
       freshness: freshnessEnvelope(graph),
-      invalidPattern: true
+      invalidPattern: true,
+      error: msg,
+      ...hint ? { hint } : {},
+      isError: true
     };
   }
   const kinds = normaliseFilter(req.kind);
@@ -4866,10 +4911,12 @@ function searchPattern(graphJson, req) {
       return bScore - aScore;
     return a.id.localeCompare(b.id);
   });
+  const proactiveHint = matches.length === 0 ? detectCommonRegexMistake(req.pattern) : void 0;
   return {
     matches: matches.slice(0, limit),
     coverage: coverageEnvelope(graph, matches.length),
-    freshness: freshnessEnvelope(graph)
+    freshness: freshnessEnvelope(graph),
+    ...proactiveHint ? { hint: proactiveHint } : {}
   };
 }
 function batchQuery(graphJson, req) {
@@ -4893,11 +4940,7 @@ function batchQuery(graphJson, req) {
     try {
       switch (toolName) {
         case "find_symbol":
-          return {
-            ok: true,
-            tool: toolName,
-            result: findSymbol(graph, args)
-          };
+          return { ok: true, tool: toolName, result: findSymbol(graph, args) };
         case "get_symbol":
           return { ok: true, tool: toolName, result: getSymbol(graph, args) };
         case "get_impact":
@@ -4910,11 +4953,47 @@ function batchQuery(graphJson, req) {
             tool: toolName,
             result: searchPattern(graph, args)
           };
+        // The 7 graph tools below were advertised by the schema's
+        // whenToUse but missing from the switch — Claude calling
+        // batch_query with `find_callers` etc. used to hit the
+        // "unsupported sub-query tool" branch and bail. Wired up here
+        // so the catalog promise matches the implementation.
+        case "find_callers":
+          return {
+            ok: true,
+            tool: toolName,
+            result: findCallers(graph, args)
+          };
+        case "find_references":
+          return {
+            ok: true,
+            tool: toolName,
+            result: findReferences(graph, args)
+          };
+        case "get_deps":
+          return { ok: true, tool: toolName, result: getDeps(graph, args) };
+        case "get_call_graph":
+          return {
+            ok: true,
+            tool: toolName,
+            result: getCallGraph(graph, args)
+          };
+        case "find_tests_for_symbol":
+          return {
+            ok: true,
+            tool: toolName,
+            result: findTestsForSymbol(graph, args)
+          };
+        case "get_todos":
+          return { ok: true, tool: toolName, result: getTodos(graph, args) };
+        case "get_freshness":
+          return { ok: true, tool: toolName, result: getFreshness(graph) };
         default:
           return {
             ok: false,
             tool: toolName,
-            error: `unsupported sub-query tool: ${String(toolName)}`
+            error: `unsupported sub-query tool: ${String(toolName)}`,
+            hint: `Supported tools: find_symbol, get_symbol, get_impact, list_edges, search_pattern, find_callers, find_references, get_deps, get_call_graph, find_tests_for_symbol, get_todos, get_freshness.`
           };
       }
     } catch (err) {
@@ -4925,7 +5004,15 @@ function batchQuery(graphJson, req) {
       };
     }
   });
-  return { results, freshness: freshnessEnvelope(graph), droppedCount };
+  const failedCount = results.filter((r) => !r.ok).length;
+  const isError = queries.length > 0 && failedCount === queries.length;
+  return {
+    results,
+    freshness: freshnessEnvelope(graph),
+    droppedCount,
+    failedCount,
+    ...isError ? { isError: true } : {}
+  };
 }
 function findCallers(graphJson, req) {
   const graph = graphJson;
@@ -5181,62 +5268,73 @@ function handleRequest(req, res, options, sessions, secretCtx) {
     }).catch((err) => sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) }));
     return;
   }
-  function validationError(msg) {
-    return { __validationError: msg };
+  function validationError(error, hint) {
+    return { __validationError: { error, hint } };
   }
   function isValidationError(v) {
     return typeof v === "object" && v !== null && "__validationError" in v;
   }
+  const HINT_USE_FIND_SYMBOL_FIRST = "To get a valid `id`, call `find_symbol` (fuzzy name match) or `search_pattern` (regex) first; pass the resulting `matches[].id` here.";
   const toolDispatch = {
     "/mcp/tools/find_symbol": (g, b) => {
-      if (typeof b["query"] !== "string")
-        return validationError("query required (string)");
+      if (typeof b["query"] !== "string") {
+        return validationError("query required (string)", "Pass a name or substring to fuzzy-match against. For regex use `search_pattern`.");
+      }
       return findSymbol(g, b);
     },
     "/mcp/tools/get_symbol": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return getSymbol(g, b);
     },
     "/mcp/tools/get_impact": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return getImpact(g, b);
     },
     "/mcp/tools/list_edges": (g, b) => listEdges(g, b),
     "/mcp/tools/search_pattern": (g, b) => {
-      if (typeof b["pattern"] !== "string")
-        return validationError("pattern required (string)");
+      if (typeof b["pattern"] !== "string") {
+        return validationError("pattern required (string)", "Pattern is a JavaScript regex string (no Python `(?P<>` / `(?i)` syntax). For literal substring search use `find_symbol` instead.");
+      }
       return searchPattern(g, b);
     },
     "/mcp/tools/batch_query": (g, b) => {
-      if (!Array.isArray(b["queries"]))
-        return validationError("queries required (array)");
+      if (!Array.isArray(b["queries"])) {
+        return validationError("queries required (array)", "Pass an array of `{tool, params}` (or `{tool, arguments}`) objects. Up to 10 sub-queries per batch. See the schema for valid `tool` values.");
+      }
       return batchQuery(g, b);
     },
     "/mcp/tools/find_callers": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return findCallers(g, b);
     },
     "/mcp/tools/find_references": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return findReferences(g, b);
     },
     "/mcp/tools/get_deps": (g, b) => {
-      if (typeof b["file"] !== "string")
-        return validationError("file required (string)");
+      if (typeof b["file"] !== "string") {
+        return validationError("file required (string)", "Pass a repo-relative file path (e.g., `src/main.py`, NOT an absolute path or symbol id).");
+      }
       return getDeps(g, b);
     },
     "/mcp/tools/get_call_graph": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return getCallGraph(g, b);
     },
     "/mcp/tools/find_tests_for_symbol": (g, b) => {
-      if (typeof b["id"] !== "string")
-        return validationError("id required (string)");
+      if (typeof b["id"] !== "string") {
+        return validationError("id required (string)", HINT_USE_FIND_SYMBOL_FIRST);
+      }
       return findTestsForSymbol(g, b);
     },
     "/mcp/tools/get_todos": (g, b) => getTodos(g, b),
@@ -5297,11 +5395,11 @@ function handleRequest(req, res, options, sessions, secretCtx) {
       const root = getRepoIdToRoot().get(session.repoId) ?? fallbackRoot;
       if (!root) {
         return {
-          ok: false,
-          status: 400,
-          body: {
+          ok: true,
+          value: {
             error: "unknown_repo",
-            message: `no workspace root registered for repoId ${session.repoId}`
+            hint: `LSP tool dispatch needs a workspace root for repoId ${session.repoId}, but none is registered. This usually means the listener hasn't yet reconciled the repo's localPath. Use graph-only tools (find_symbol, find_callers, etc.) until reconcile completes.`,
+            isError: true
           }
         };
       }
@@ -5315,11 +5413,25 @@ function handleRequest(req, res, options, sessions, secretCtx) {
     dispatchSessionTool(req, res, url, sessions, options.mcpLogger, async (session, body) => {
       const graph = options.graphCache.peek(session.repoId);
       if (!graph) {
-        return { ok: false, status: 503, body: { error: "graph_not_loaded" } };
+        return {
+          ok: true,
+          value: {
+            error: "graph_not_loaded",
+            hint: "The graph for this repo is still downloading or has been invalidated. Retry in a few seconds; if the problem persists, the listener may not have completed the initial sync.",
+            isError: true
+          }
+        };
       }
       const raw = handler(graph, body);
       if (isValidationError(raw)) {
-        return { ok: false, status: 400, body: { error: raw.__validationError } };
+        return {
+          ok: true,
+          value: {
+            error: raw.__validationError.error,
+            hint: raw.__validationError.hint,
+            isError: true
+          }
+        };
       }
       const resolved = await Promise.race([
         raw instanceof Promise ? raw : Promise.resolve(raw),
@@ -5396,12 +5508,18 @@ function dispatchSessionTool(req, res, url, sessions, logger, handler) {
       });
       logToStdout("error", tool, session.repoId, Date.now() - startedAt, safeMsg);
       if (isTimeout) {
-        return sendJson(res, 504, { error: "tool-timeout", tool });
+        return sendJson(res, 200, {
+          error: `tool-timeout: ${tool} exceeded its execution budget`,
+          hint: "The tool was killed at its per-tool timeout. Try a narrower query (smaller limit, depth, or filter) or split into multiple calls.",
+          isError: true,
+          tool
+        });
       }
-      return sendJson(res, 500, {
-        error: "tool_error",
-        tool,
-        message: safeMsg
+      return sendJson(res, 200, {
+        error: `tool_error: ${safeMsg}`,
+        hint: "The tool threw an unexpected exception. This is a server-side bug \u2014 file an issue with the tool name and the error text.",
+        isError: true,
+        tool
       });
     }
   }).catch((err) => {
@@ -10738,11 +10856,13 @@ async function routeMessage(endpoint, repoId, message, postJson, getJson, header
       sessionState.sessionId = fresh;
       result = await callTool(fresh);
     }
+    const inner = result ?? {};
     return {
       jsonrpc: "2.0",
       id: rpcId,
       result: {
-        content: [{ type: "text", text: JSON.stringify(result) }]
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        ...inner.isError === true ? { isError: true } : {}
       }
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repowisestage",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "type": "module",
   "description": "AI-optimized codebase context generator",
   "bin": {