pi-readseek 0.9.6 → 0.9.8

package/dist/index.ts

@@ -41,6 +41,8 @@ var TOOL_NAMES = [
 ];
 var PARAM_DESCRIPTIONS = {
   path: "Absolute or relative file path",
+  projectPath: "Path relative to the project directory",
+  projectSearchPath: "File or directory to search; defaults to the project directory",
   searchPath: "File or directory to search; defaults to the current directory",
   language: "Language override when auto-detection is ambiguous",
   languageOverride: "Language override",
@@ -94,6 +96,7 @@ var PARAM_DESCRIPTIONS = {
   symbol: "Mapped symbol name",
   newBody: "Complete replacement body for the symbol",
   apply: "When supported by the host, apply the verified plan instead of previewing only",
+  applyDefaultTrue: "Apply the verified edits; defaults to true",
   planHash: "Require the apply plan to match this dry-run plan hash",
   workspace: "Rename across the project",
   to: "New symbol name",
@@ -398,6 +401,90 @@ var TOOL_CONTRACTS = [
     }
   }
 ];
+// ../readseek-api/src/policy.ts
+var REPLACEABLE_TOOLS = [
+  {
+    tool: "digest",
+    builtIn: "read",
+    benefit: "it returns LINE:HASH anchors for safe edits."
+  },
+  {
+    tool: "edit",
+    builtIn: "edit",
+    benefit: "it verifies fresh LINE:HASH anchors."
+  },
+  {
+    tool: "grep",
+    builtIn: "grep",
+    benefit: "it returns LINE:HASH anchors."
+  },
+  {
+    tool: "write",
+    builtIn: "write",
+    benefit: "it returns LINE:HASH anchors."
+  }
+];
+var TOOL_COMPACT_GUIDELINES = {
+  digest: [
+    "Use `digest` for map, diagnostics, and identity facets instead of separate tools."
+  ],
+  edit: [
+    "Prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical."
+  ],
+  grep: [
+    "Use `grep` with summary first for broad searches, then narrow by path, glob, or pattern."
+  ],
+  write: [
+    "Use anchored edits rather than `write` for small changes or appends."
+  ],
+  search: [
+    "Use `search` for AST patterns; use `grep` for plain text."
+  ],
+  refs: [
+    "Use `refs` before changing a symbol; add scope plus line/column to follow one binding."
+  ]
+};
+function resolveToolName(name, aliases = {}) {
+  return aliases[name] ?? name;
+}
+function rewriteBacktickedToolNames(text, aliases = {}) {
+  return TOOL_NAMES.reduce((rewritten, toolName) => rewritten.replaceAll(`\`${toolName}\``, `\`${resolveToolName(toolName, aliases)}\``), text);
+}
+function renderCompactGuidelines(name, aliases = {}) {
+  return (TOOL_COMPACT_GUIDELINES[name] ?? []).map((guideline) => rewriteBacktickedToolNames(guideline, aliases));
+}
+function renderToolRoutingPolicy(options = {}) {
+  const aliases = options.aliases ?? {};
+  const digest = resolveToolName("digest", aliases);
+  const edit = resolveToolName("edit", aliases);
+  const write = resolveToolName("write", aliases);
+  const grep = resolveToolName("grep", aliases);
+  const search = resolveToolName("search", aliases);
+  const def = resolveToolName("def", aliases);
+  const refs = resolveToolName("refs", aliases);
+  const rename = resolveToolName("rename", aliases);
+  const view = resolveToolName("view", aliases);
+  if (options.style === "server") {
+    return [
+      "Structural code navigation, document viewing, and hash-verified edits with readseek.",
+      "For structural questions, prefer these tools to text Grep/Bash: definitions, references, AST search, multi-facet digest (content/map/diagnostics/identity), and document views.",
+      `Use ${edit} for LINE:HASH-anchored mutations (preview with apply=false; apply defaults to true and re-checks plan_hash).`,
+      "Paths resolve against CLAUDE_PROJECT_DIR. Native Read/Grep/Edit hooks provide passive context;",
+      "call MCP tools for active navigation, document questions, or anchored edits."
+    ].join(" ");
+  }
+  const title = options.title ?? "ReadSeek tool policy:";
+  const bullets = [];
+  if (options.preferOverBuiltIns) {
+    bullets.push("- Prefer ReadSeek tools over built-ins when they can do the job.");
+  }
+  bullets.push(`- Read with ${digest} first; ${edit} needs fresh LINE:HASH anchors.`, `- Use ${grep} for text/regex, ${search} for AST patterns, and ${digest}/${def}/${refs} for symbol navigation.`, `- Use ${edit} for existing files, ${write} for whole-file creation or replacement, and ${rename} for symbol renames.`, `- Use ${view} for document structure; run ${digest} with select diagnostics after source edits for a quick syntax check.`);
+  if (options.demoteBuiltIns && options.demoteBuiltIns.length > 0) {
+    bullets.push(`- Do not use built-in ${options.demoteBuiltIns.join(", ")} when a ReadSeek tool can do the job.`);
+  }
+  return [title, ...bullets].join(`
+`);
+}
 // ../readseek-api/src/validation.ts
 function validateGitSelection(input) {
   if (input.ignored && !input.others) {
@@ -768,48 +855,7 @@ async function runReadSeekNodeJson(binaryPath, args, options = {}) {
   return parseSuccessfulJson(await runReadSeekNode(binaryPath, args, options));
 }
 // src/tool-prompt-metadata.ts
-var REPLACEABLE_TOOL_GUIDELINES = {
-  "digest.md": {
-    readSeekName: "readSeek_digest",
-    builtInName: "read",
-    benefit: "it returns LINE:HASH anchors for safe edits."
-  },
-  "edit.md": {
-    readSeekName: "readSeek_edit",
-    builtInName: "edit",
-    benefit: "it verifies fresh LINE:HASH anchors."
-  },
-  "grep.md": {
-    readSeekName: "readSeek_grep",
-    builtInName: "grep",
-    benefit: "it returns LINE:HASH anchors."
-  },
-  "write.md": {
-    readSeekName: "readSeek_write",
-    builtInName: "write",
-    benefit: "it returns LINE:HASH anchors."
-  }
-};
-var COMPACT_GUIDELINES = {
-  "digest.md": [
-    "Use readSeek_digest for map, diagnostics, and identity facets instead of separate tools."
-  ],
-  "edit.md": [
-    "Prefer set_line, replace_lines, and insert_after; use replace only when anchors are impractical."
-  ],
-  "grep.md": [
-    "Use readSeek_grep with summary first for broad searches, then narrow by path, glob, or pattern."
-  ],
-  "write.md": [
-    "Use anchored edits rather than readSeek_write for small changes or appends."
-  ],
-  "search.md": [
-    "Use readSeek_search for AST patterns; use readSeek_grep for plain text."
-  ],
-  "refs.md": [
-    "Use readSeek_refs before changing a symbol; add scope plus line/column to follow one binding."
-  ]
-};
+var REPLACEABLE_BY_TOOL = new Map(REPLACEABLE_TOOLS.map((entry) => [entry.tool, entry]));
 function toolNameFromPrompt(fileName) {
   const name = fileName.replace(/\.md$/, "");
   if (!TOOL_NAMES.includes(name))
@@ -819,28 +865,32 @@ function toolNameFromPrompt(fileName) {
 function promptFileName(promptUrl) {
   return promptUrl.pathname.split("/").pop() ?? "";
 }
-function rewriteToolAliases(value, toolAliases) {
+function rewriteRegisteredToolNames(value, toolAliases) {
   if (!toolAliases)
     return value;
   return Object.entries(toolAliases).reduce((rewritten, [canonicalName, registeredName]) => rewritten.replaceAll(canonicalName, registeredName), value);
 }
-function defineToolPromptMetadata(options) {
-  const fileName = promptFileName(options.promptUrl);
-  const toolName = toolNameFromPrompt(fileName);
-  const replaceable = REPLACEABLE_TOOL_GUIDELINES[fileName];
-  const registeredName = options.registeredName ?? replaceable?.readSeekName;
-  const preferenceGuideline = replaceable && registeredName ? registeredName === replaceable.readSeekName ? `Prefer ${registeredName} over ${replaceable.builtInName} when both are available; ${replaceable.benefit}` : `Use ${registeredName}; ${replaceable.benefit}` : undefined;
-  const aliases = Object.fromEntries(TOOL_NAMES.map((name) => {
+function descriptionAliases(toolName, registeredName, toolAliases) {
+  return Object.fromEntries(TOOL_NAMES.map((name) => {
     const readSeekName = `readSeek_${name}`;
-    const alias = name === toolName && registeredName ? registeredName : options.toolAliases?.[readSeekName] ?? readSeekName;
+    const alias = name === toolName && registeredName ? registeredName : toolAliases?.[readSeekName] ?? readSeekName;
     return [name, alias];
   }));
+}
+function defineToolPromptMetadata(options) {
+  const fileName = promptFileName(options.promptUrl);
+  const toolName = toolNameFromPrompt(fileName);
+  const replaceable = REPLACEABLE_BY_TOOL.get(toolName);
+  const defaultReadSeekName = `readSeek_${toolName}`;
+  const registeredName = options.registeredName ?? (replaceable ? defaultReadSeekName : undefined);
+  const preferenceGuideline = replaceable && registeredName ? registeredName === defaultReadSeekName ? `Prefer ${registeredName} over ${replaceable.builtIn} when both are available; ${replaceable.benefit}` : `Use ${registeredName}; ${replaceable.benefit}` : undefined;
+  const aliases = descriptionAliases(toolName, registeredName, options.toolAliases);
   return {
     description: renderToolDescription(toolName, aliases),
-    promptSnippet: rewriteToolAliases(options.promptSnippet, options.toolAliases),
+    promptSnippet: rewriteRegisteredToolNames(options.promptSnippet, options.toolAliases),
     promptGuidelines: [
       ...preferenceGuideline ? [preferenceGuideline] : [],
-      ...(COMPACT_GUIDELINES[fileName] ?? []).map((guideline) => rewriteToolAliases(registeredName && replaceable ? guideline.replaceAll(replaceable.readSeekName, registeredName) : guideline, options.toolAliases))
+      ...renderCompactGuidelines(toolName, aliases)
     ]
   };
 }
@@ -2972,7 +3022,7 @@ function optionalIntOrString(description) {
   return Type.Optional(Type.Union([Type.Number({ description }), Type.String({ description })]));
 }
 function filePathParam() {
-  return Type.String({ description: "Absolute or relative file path" });
+  return Type.String({ description: PARAM_DESCRIPTIONS.path });
 }
 function registerReadSeekTool(pi, tool) {
   pi.registerTool(tool);
@@ -2982,42 +3032,42 @@ function registerReadSeekTool(pi, tool) {
 // src/edit.ts
 var hashlineEditItemSchema = Type2.Object({
   set_line: Type2.Optional(Type2.Object({
-    anchor: Type2.String({ description: "Fresh LINE:HASH anchor for the line to replace" }),
-    new_text: Type2.String({ description: "Replacement text; use an empty string to delete the line" })
-  }, { additionalProperties: false, description: 'Replace one line: {"set_line":{"anchor":"LINE:HASH","new_text":"..."}}' })),
+    anchor: Type2.String({ description: PARAM_DESCRIPTIONS.anchor }),
+    new_text: Type2.String({ description: PARAM_DESCRIPTIONS.newTextLine })
+  }, { additionalProperties: false, description: PARAM_DESCRIPTIONS.setLine })),
   replace_lines: Type2.Optional(Type2.Object({
-    start_anchor: Type2.String({ description: "Fresh LINE:HASH anchor for the first line in the range" }),
-    end_anchor: Type2.String({ description: "Fresh LINE:HASH anchor for the last line in the range" }),
-    new_text: Type2.String({ description: "Replacement text; use an empty string to delete the range" })
-  }, { additionalProperties: false, description: 'Replace a range: {"replace_lines":{"start_anchor":"LINE:HASH","end_anchor":"LINE:HASH","new_text":"..."}}' })),
+    start_anchor: Type2.String({ description: PARAM_DESCRIPTIONS.startAnchor }),
+    end_anchor: Type2.String({ description: PARAM_DESCRIPTIONS.endAnchor }),
+    new_text: Type2.String({ description: PARAM_DESCRIPTIONS.newTextRange })
+  }, { additionalProperties: false, description: PARAM_DESCRIPTIONS.replaceLines })),
   insert_after: Type2.Optional(Type2.Object({
-    anchor: Type2.String({ description: "Fresh LINE:HASH anchor for the line after which to insert" }),
-    new_text: Type2.String({ description: "Text to insert after the anchored line" })
-  }, { additionalProperties: false, description: 'Insert text: {"insert_after":{"anchor":"LINE:HASH","new_text":"..."}}' })),
+    anchor: Type2.String({ description: PARAM_DESCRIPTIONS.insertAnchor }),
+    new_text: Type2.String({ description: PARAM_DESCRIPTIONS.newTextInsert })
+  }, { additionalProperties: false, description: PARAM_DESCRIPTIONS.insertAfter })),
   replace: Type2.Optional(Type2.Object({
-    old_text: Type2.String({ description: "Exact text to find" }),
-    new_text: Type2.String({ description: "Replacement text" }),
-    all: Type2.Optional(Type2.Boolean({ description: "Replace every exact match" }))
-  }, { additionalProperties: false, description: 'Replace text: {"replace":{"old_text":"...","new_text":"..."}}' })),
+    old_text: Type2.String({ description: PARAM_DESCRIPTIONS.oldText }),
+    new_text: Type2.String({ description: PARAM_DESCRIPTIONS.newText }),
+    all: Type2.Optional(Type2.Boolean({ description: PARAM_DESCRIPTIONS.all }))
+  }, { additionalProperties: false, description: PARAM_DESCRIPTIONS.replace })),
   replace_symbol: Type2.Optional(Type2.Object({
-    symbol: Type2.String({ description: "Mapped symbol name" }),
-    new_body: Type2.String({ description: "Complete replacement body for the symbol" })
-  }, { additionalProperties: false, description: 'Replace a symbol: {"replace_symbol":{"symbol":"name","new_body":"..."}}' }))
+    symbol: Type2.String({ description: PARAM_DESCRIPTIONS.symbol }),
+    new_body: Type2.String({ description: PARAM_DESCRIPTIONS.newBody })
+  }, { additionalProperties: false, description: PARAM_DESCRIPTIONS.replaceSymbol }))
 }, {
   additionalProperties: false,
   minProperties: 1,
   maxProperties: 1,
-  description: "Exactly one nested edit variant"
+  description: PARAM_DESCRIPTIONS.editVariant
 });
 var hashlineEditSchema = Type2.Object({
   path: filePathParam(),
-  language: Type2.Optional(Type2.String({ description: "Language override for symbol replacement" })),
+  language: Type2.Optional(Type2.String({ description: PARAM_DESCRIPTIONS.languageSymbol })),
   edits: Type2.Array(hashlineEditItemSchema, {
     minItems: 1,
-    description: "Use set_line, replace_lines, insert_after, replace_symbol, or replace"
+    description: PARAM_DESCRIPTIONS.edits
   }),
   postEditVerify: Type2.Optional(Type2.Boolean({
-    description: "Read back and verify persisted content"
+    description: PARAM_DESCRIPTIONS.postEditVerify
   }))
 }, { additionalProperties: false });
 function buildEditError(path3, code, message, hint, errorDetails) {
@@ -3724,18 +3774,18 @@ function validateIgnoredRequiresOthers(tool, params) {
 
 // src/grep.ts
 var grepSchema = Type4.Object({
-  pattern: Type4.String({ description: "Regex pattern; set literal for exact text" }),
+  pattern: Type4.String({ description: PARAM_DESCRIPTIONS.grepPattern }),
   path: searchPathParam(),
-  glob: Type4.Optional(Type4.String({ description: "File-name glob, such as *.ts" })),
-  ignoreCase: Type4.Optional(Type4.Boolean({ description: "Ignore case" })),
-  literal: Type4.Optional(Type4.Boolean({ description: "Treat pattern literally" })),
-  context: optionalIntOrString("Surrounding lines for each match"),
-  limit: optionalIntOrString("Maximum matches to return"),
-  summary: Type4.Optional(Type4.Boolean({ description: "Return per-file counts" })),
+  glob: Type4.Optional(Type4.String({ description: PARAM_DESCRIPTIONS.glob })),
+  ignoreCase: Type4.Optional(Type4.Boolean({ description: PARAM_DESCRIPTIONS.ignoreCase })),
+  literal: Type4.Optional(Type4.Boolean({ description: PARAM_DESCRIPTIONS.literal })),
+  context: optionalIntOrString(PARAM_DESCRIPTIONS.context),
+  limit: optionalIntOrString(PARAM_DESCRIPTIONS.matchLimit),
+  summary: Type4.Optional(Type4.Boolean({ description: PARAM_DESCRIPTIONS.summary })),
   scope: Type4.Optional(Type4.Literal("symbol", {
-    description: "Group matches by enclosing symbol"
+    description: PARAM_DESCRIPTIONS.grepScope
   })),
-  scopeContext: optionalIntOrString("Context lines within each symbol")
+  scopeContext: optionalIntOrString(PARAM_DESCRIPTIONS.scopeContext)
 });
 var MATCH_LINE_RE = /^(.*?):(\d+): (.*)$/;
 var CONTEXT_LINE_RE = /^(.*?)-(\d+)- (.*)$/;
@@ -4539,11 +4589,11 @@ var RENAME_PROMPT_METADATA = defineToolPromptMetadata({
 });
 var renameSchema = Type7.Object({
   path: filePathParam(),
-  line: Type7.Integer({ minimum: 1, description: "One-based cursor line of the symbol to rename" }),
-  column: Type7.Optional(Type7.Integer({ minimum: 1, description: "One-based cursor byte column for disambiguation" })),
-  to: Type7.String({ description: "New symbol name" }),
-  workspace: Type7.Optional(Type7.Boolean({ description: "Rename across the project" })),
-  apply: Type7.Optional(Type7.Boolean({ description: "Apply the verified edits; defaults to true" }))
+  line: Type7.Integer({ minimum: 1, description: PARAM_DESCRIPTIONS.renameLine }),
+  column: Type7.Optional(Type7.Integer({ minimum: 1, description: PARAM_DESCRIPTIONS.column })),
+  to: Type7.String({ description: PARAM_DESCRIPTIONS.to }),
+  workspace: Type7.Optional(Type7.Boolean({ description: PARAM_DESCRIPTIONS.workspace })),
+  apply: Type7.Optional(Type7.Boolean({ description: PARAM_DESCRIPTIONS.applyDefaultTrue }))
 });
 async function executeRename(opts) {
   const { params, signal, cwd, onFileMutated } = opts;
@@ -4975,7 +5025,7 @@ function registerWriteTool(pi, options = {}) {
     promptGuidelines: promptMetadata.promptGuidelines,
     parameters: Type8.Object({
       path: filePathParam(),
-      content: Type8.String({ description: "Complete text file content" })
+      content: Type8.String({ description: PARAM_DESCRIPTIONS.content })
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const cwd = ctx?.cwd ?? process.cwd();
@@ -5540,14 +5590,11 @@ var READSEEK_TOOL_ENTRIES = [
 function formatSettingsWarning(warning) {
   return `${warning.message} (${warning.source})`;
 }
-function editingPolicy(readName, editName, writeName) {
-  return [
-    "ReadSeek editing policy:",
-    `- Read first with ${readName} when preparing to edit; ${editName} needs fresh LINE:HASH anchors.`,
-    `- Use ${editName} for existing files, ${writeName} for whole-file creation or replacement, and readSeek_rename for symbol renames.`,
-    `- Run ${readName} with select diagnostics after source edits for a quick syntax check.`
-  ].join(`
-`);
+function toolRoutingPolicy(aliases) {
+  return renderToolRoutingPolicy({
+    aliases,
+    title: "ReadSeek tool policy:"
+  });
 }
 function piReadSeekExtension(pi) {
   const sessionAnchors = new SessionAnchors;
@@ -5568,6 +5615,10 @@ function piReadSeekExtension(pi) {
     readSeek_grep: grepName,
     readSeek_write: writeName
   };
+  const policyAliases = Object.fromEntries(TOOL_NAMES.map((name) => {
+    const readSeekName = `readSeek_${name}`;
+    return [name, toolAliases[readSeekName] ?? readSeekName];
+  }));
   registerEditTool(pi, { wasReadInSession: hasFreshAnchors, onFileMutated: forgetAnchors, name: editName, toolAliases });
   registerGrepTool(pi, { onFileAnchored: markAnchored, name: grepName });
   registerSearchTool(pi, { onFileAnchored: markAnchored });
@@ -5582,7 +5633,7 @@ function piReadSeekExtension(pi) {
       return;
     return { systemPrompt: `${event.systemPrompt}
 
-${editingPolicy(readName, editName, writeName)}` };
+${toolRoutingPolicy(policyAliases)}` };
   });
   pi.on("session_start", (_event, ctx) => {
     sessionAnchors.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Pi extension for LINE:HASH-anchored file operations and structural code navigation",
   "type": "module",
   "exports": {
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.9.6",
+    "@jarkkojs/readseek": "^0.9.8",
     "diff": "^9.0.0",
     "xxhash-wasm": "^1.1.0"
   },