@jarkkojs/readseek-api 0.9.6 → 0.9.8

package/README.md

@@ -1,8 +1,8 @@
 # @jarkkojs/readseek-api
 
-Shared, host-agnostic ReadSeek API pieces for CLI contract metadata, parameter
-validation, pure argv builders, platform package resolution, and bounded Node
-or Bun process invocation.
+Shared, host-agnostic ReadSeek API pieces for CLI contract metadata, agent
+routing policy, parameter validation, pure argv builders, platform package
+resolution, and bounded Node or Bun process invocation.
 
 This package intentionally excludes host permissions, cache management, install
 flows, session state, and TUI rendering.
@@ -22,6 +22,7 @@ npm install @jarkkojs/readseek-api
 ## Exports
 
 - Contract: tool descriptions, shared parameter text, and enums
+- Policy: host-agnostic tool routing, preference/fallback lead-ins, and compact guidelines
 - Validation: git selection, refs name/scope, vision level/mode, edit variants
 - Argv builders: `digest`, `view`, `search`, `def`, `refs`, `edit`, `rename`, line locations
 - Platform: binary name, platform package map, and default or caller-injected module resolution

package/dist/contract.d.ts

@@ -16,6 +16,8 @@ export declare const TOOL_NAMES: readonly ["digest", "edit", "write", "grep", "v
 export type ToolName = (typeof TOOL_NAMES)[number];
 export declare const PARAM_DESCRIPTIONS: {
     readonly path: "Absolute or relative file path";
+    readonly projectPath: "Path relative to the project directory";
+    readonly projectSearchPath: "File or directory to search; defaults to the project directory";
     readonly searchPath: "File or directory to search; defaults to the current directory";
     readonly language: "Language override when auto-detection is ambiguous";
     readonly languageOverride: "Language override";
@@ -69,6 +71,7 @@ export declare const PARAM_DESCRIPTIONS: {
     readonly symbol: "Mapped symbol name";
     readonly newBody: "Complete replacement body for the symbol";
     readonly apply: "When supported by the host, apply the verified plan instead of previewing only";
+    readonly applyDefaultTrue: "Apply the verified edits; defaults to true";
     readonly planHash: "Require the apply plan to match this dry-run plan hash";
     readonly workspace: "Rename across the project";
     readonly to: "New symbol name";
@@ -108,3 +111,4 @@ export type ToolContract = {
     inputSchema: JsonSchema;
 };
 export declare const TOOL_CONTRACTS: readonly ToolContract[];
+export declare function getToolContract(name: ToolName): ToolContract;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { DIGEST_FACETS, DOCUMENT_NODE_KINDS, EDIT_VARIANTS, GIT_SELECTION_FLAGS, PARAM_DESCRIPTIONS, TOOL_CONTRACTS, TOOL_DESCRIPTIONS, TOOL_NAMES, renderToolDescription, VISION_ANALYSIS_MODES, VISION_LEVELS, VISION_MODES, type DigestFacet, type DocumentNodeKind, type EditVariant, type GitSelectionFlag, type JsonSchema, type ToolContract, type ToolName, type VisionAnalysisMode, type VisionLevel, type VisionMode, } from "./contract.ts";
+export { DIGEST_FACETS, DOCUMENT_NODE_KINDS, EDIT_VARIANTS, GIT_SELECTION_FLAGS, PARAM_DESCRIPTIONS, TOOL_CONTRACTS, getToolContract, TOOL_DESCRIPTIONS, TOOL_NAMES, renderToolDescription, VISION_ANALYSIS_MODES, VISION_LEVELS, VISION_MODES, type DigestFacet, type DocumentNodeKind, type EditVariant, type GitSelectionFlag, type JsonSchema, type ToolContract, type ToolName, type VisionAnalysisMode, type VisionLevel, type VisionMode, } from "./contract.ts";
+export { BUILTIN_FALLBACKS, REPLACEABLE_TOOLS, TOOL_COMPACT_GUIDELINES, fallbackToolDescriptionMap, preferredToolDescriptionMap, renderCompactGuidelines, renderFallbackToolDescription, renderPreferredToolDescription, renderToolRoutingPolicy, resolveToolName, rewriteBacktickedToolNames, type ReplaceableTool, type ToolAliasMap, type ToolRoutingPolicyOptions, } from "./policy.ts";
 export { validateExactlyOneEditVariant, validateGitSelection, validateRefsNameVsScope, validateVisionLevelVsMode, type EditObject, type GitSelectionInput, type RefsScopeInput, type ValidationResult, type VisionInput, } from "./validation.ts";
 export { appendApplyAndPlanHash, appendGitSelectionArgs, buildDefArgs, buildDigestArgs, buildEditArgs, buildLineLocation, buildRefsArgs, buildRenameArgs, buildSearchArgs, buildViewArgs, type ApplyPlanHashInput, type ApplyPlanHashOrder, type DefArgsInput, type DigestArgsInput, type EditArgsInput, type RefsArgsInput, type RenameArgsInput, type SearchArgsInput, type ViewArgsInput, } from "./argv.ts";
 export { READSEEK_PLATFORM_PACKAGES, readSeekBinaryName, readSeekPlatformKey, resolveReadSeekBinaryFromPackages, type ModuleResolver, } from "./platform.ts";

package/dist/index.js

@@ -42,6 +42,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",
@@ -95,6 +97,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",
@@ -399,6 +402,139 @@ var TOOL_CONTRACTS = [
     }
   }
 ];
+function getToolContract(name) {
+  const contract = TOOL_CONTRACTS.find((entry) => entry.name === name);
+  if (!contract)
+    throw new Error(`missing tool contract: ${name}`);
+  return contract;
+}
+// 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."
+  ]
+};
+var BUILTIN_FALLBACKS = {
+  read: "digest",
+  edit: "edit",
+  write: "write",
+  grep: "grep",
+  apply_patch: "edit"
+};
+var PREFERENCE_LEADS = {
+  digest: "Preferred for reading source with anchors and facets.",
+  edit: "Preferred for editing existing text files with fresh LINE:HASH anchors.",
+  write: "Preferred for creating or replacing a complete text file; returns LINE:HASH anchors.",
+  grep: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
+  search: "Preferred for AST or structural code search with ast-grep-style patterns.",
+  def: "Preferred for go-to-definition or declaration lookup by name.",
+  refs: "Preferred for finding identifier-name matches or binding-specific references before rename or delete.",
+  rename: "Preferred for renaming a symbol with binding-aware, verified edits.",
+  view: "Preferred for digesting document structure or selected content."
+};
+var FALLBACK_TEMPLATES = {
+  read: "Fallback only. Prefer `digest` with fresh LINE:HASH anchors.",
+  edit: "Fallback only. Prefer `edit` with fresh LINE:HASH anchors.",
+  write: "Fallback only. Prefer `write` so the result returns LINE:HASH anchors.",
+  grep: "Fallback only. Prefer `grep` for text/regex search with edit-ready anchors.",
+  apply_patch: "Fallback only. Prefer `edit` for existing text files."
+};
+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 renderPreferredToolDescription(name, aliases = {}) {
+  return rewriteBacktickedToolNames(PREFERENCE_LEADS[name], aliases);
+}
+function renderFallbackToolDescription(builtIn, aliases = {}) {
+  const template = FALLBACK_TEMPLATES[builtIn];
+  if (!template)
+    return;
+  return rewriteBacktickedToolNames(template, 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(`
+`);
+}
+function preferredToolDescriptionMap(aliases = {}) {
+  return Object.fromEntries(TOOL_NAMES.map((name) => [resolveToolName(name, aliases), renderPreferredToolDescription(name, aliases)]));
+}
+function fallbackToolDescriptionMap(builtIns = Object.keys(BUILTIN_FALLBACKS), aliases = {}) {
+  return Object.fromEntries(builtIns.flatMap((builtIn) => {
+    const description = renderFallbackToolDescription(builtIn, aliases);
+    return description ? [[builtIn, description]] : [];
+  }));
+}
 // src/validation.ts
 function validateGitSelection(input) {
   if (input.ignored && !input.others) {
@@ -890,13 +1026,22 @@ export {
   runReadSeekBunText,
   runReadSeekBunJson,
   runReadSeekBun,
+  rewriteBacktickedToolNames,
+  resolveToolName,
   resolveReadSeekBinaryFromPackages,
   resolveProcessLimits,
+  renderToolRoutingPolicy,
   renderToolDescription,
+  renderPreferredToolDescription,
+  renderFallbackToolDescription,
+  renderCompactGuidelines,
   readSeekPlatformKey,
   readSeekBinaryName,
+  preferredToolDescriptionMap,
   parseSuccessfulJson,
   parseReadSeekJson,
+  getToolContract,
+  fallbackToolDescriptionMap,
   failureFromProcessResult,
   ensureSuccessfulStdout,
   cleanReadSeekErrorText,
@@ -916,6 +1061,8 @@ export {
   TOOL_NAMES,
   TOOL_DESCRIPTIONS,
   TOOL_CONTRACTS,
+  TOOL_COMPACT_GUIDELINES,
+  REPLACEABLE_TOOLS,
   READSEEK_PLATFORM_PACKAGES,
   PARAM_DESCRIPTIONS,
   GIT_SELECTION_FLAGS,
@@ -923,5 +1070,6 @@ export {
   DOCUMENT_NODE_KINDS,
   DIGEST_FACETS,
   DEFAULT_READSEEK_TIMEOUT_MS,
-  DEFAULT_MAX_OUTPUT_BYTES
+  DEFAULT_MAX_OUTPUT_BYTES,
+  BUILTIN_FALLBACKS
 };

package/dist/policy.d.ts

@@ -0,0 +1,25 @@
+import { type ToolName } from "./contract.ts";
+export type ToolAliasMap = Readonly<Partial<Record<ToolName, string>>>;
+export type ReplaceableTool = {
+    tool: ToolName;
+    builtIn: string;
+    benefit: string;
+};
+export declare const REPLACEABLE_TOOLS: readonly ReplaceableTool[];
+export declare const TOOL_COMPACT_GUIDELINES: Readonly<Partial<Record<ToolName, readonly string[]>>>;
+export declare const BUILTIN_FALLBACKS: Readonly<Record<string, ToolName>>;
+export declare function resolveToolName(name: ToolName, aliases?: ToolAliasMap): string;
+export declare function rewriteBacktickedToolNames(text: string, aliases?: ToolAliasMap): string;
+export declare function renderCompactGuidelines(name: ToolName, aliases?: ToolAliasMap): string[];
+export declare function renderPreferredToolDescription(name: ToolName, aliases?: ToolAliasMap): string;
+export declare function renderFallbackToolDescription(builtIn: string, aliases?: ToolAliasMap): string | undefined;
+export type ToolRoutingPolicyOptions = {
+    aliases?: ToolAliasMap;
+    title?: string;
+    preferOverBuiltIns?: boolean;
+    demoteBuiltIns?: readonly string[];
+    style?: "bullets" | "server";
+};
+export declare function renderToolRoutingPolicy(options?: ToolRoutingPolicyOptions): string;
+export declare function preferredToolDescriptionMap(aliases?: ToolAliasMap): Readonly<Record<string, string>>;
+export declare function fallbackToolDescriptionMap(builtIns?: readonly string[], aliases?: ToolAliasMap): Readonly<Record<string, string>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarkkojs/readseek-api",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Shared ReadSeek CLI contract, validation, argv builders, and bounded process runners",
   "type": "module",
   "license": "Apache-2.0",
@@ -45,7 +45,7 @@
     "hashline"
   ],
   "dependencies": {
-    "@jarkkojs/readseek": "^0.9.6"
+    "@jarkkojs/readseek": "^0.9.8"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",