@jarkkojs/readseek-api 0.9.12 → 0.9.14

package/README.md

@@ -1,48 +1,31 @@
 # @jarkkojs/readseek-api
 
-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.
-
-Repository plugins consume this source directly: Pi and OpenCode inline it into
-their published bundles, and the Claude marketplace plugin imports the monorepo
-sibling sources. External consumers install the published package.
+Shared ReadSeek contracts, validation, argument builders, binary resolution, and
+bounded Node/Bun process runners.
 
 ## Install
 
-```bash
+```sh
 npm install @jarkkojs/readseek-api
 ```
 
-`@jarkkojs/readseek` arrives as a dependency.
-
-## 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
-- Process: Node and Bun runners with timeout, cancellation, stdin, cwd, hard
-  stdout/stderr caps, no shell, and strict JSON/error cleanup
-
 ## Example
 
 ```ts
 import {
   buildDigestArgs,
   resolveReadSeekBinaryFromPackages,
+  resolveReadSeekBinaryOverride,
   runReadSeekNodeJson,
 } from "@jarkkojs/readseek-api";
 
-const binary = resolveReadSeekBinaryFromPackages();
+const binary =
+  resolveReadSeekBinaryOverride() ?? resolveReadSeekBinaryFromPackages();
 const args = buildDigestArgs({ path: "src/index.ts", select: "map" });
-const envelope = await runReadSeekNodeJson(binary, args);
+const result = await runReadSeekNodeJson(binary, args);
 ```
 
-## License
 
-Apache-2.0
+## Licensing
+
+[Apache 2.0](../../LICENSE-APACHE-2.0).

package/dist/argv.d.ts

@@ -31,7 +31,7 @@ export type ViewArgsInput = {
     outline?: boolean;
     visionMode?: VisionAnalysisMode;
     visionLevel?: VisionLevel;
-    format?: "json" | "text";
+    format?: "json" | "plain";
     readseekDir?: string;
 };
 export declare function buildViewArgs(input: ViewArgsInput): string[];
@@ -39,6 +39,7 @@ export type SearchArgsInput = {
     path: string;
     pattern: string;
     language?: string;
+    limit?: number;
 } & GitSelectionInput;
 export declare function buildSearchArgs(input: SearchArgsInput): string[];
 export type DefArgsInput = {

package/dist/client.d.ts

@@ -16,11 +16,13 @@ export interface ReadSeekReadOutput {
 export interface ReadSeekSymbol {
     kind: string;
     name: string;
-    qualified_name: string;
+    qualified_name?: string;
     start_line: number;
     end_line: number;
-    start_hash: string;
-    end_hash: string;
+    start_hash?: string;
+    end_hash?: string;
+    start_anchor?: string;
+    end_anchor?: string;
 }
 export interface ReadSeekMapOutput {
     file: string;
@@ -66,6 +68,7 @@ export interface ReadSeekDiagnostic {
     end_line: number;
 }
 export interface ReadSeekCheckOutput {
+    file_hash?: string;
     errorCount: number;
     missingCount: number;
     diagnostics: ReadSeekDiagnostic[];
@@ -259,6 +262,7 @@ export interface ReadSeekRunner {
 }
 interface ReadSeekSearchOptions {
     language?: string;
+    limit?: number;
     cached?: boolean;
     others?: boolean;
     ignored?: boolean;

package/dist/hashline.d.ts

@@ -0,0 +1,13 @@
+export declare const HASH_LEN = 6;
+export type LineAnchor = {
+    line: number;
+    hash: string;
+};
+export declare function tryParseLineAnchor(anchor: string): {
+    ok: true;
+    anchor: LineAnchor;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseLineAnchor(anchor: string): LineAnchor;

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 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 { coerceBoolean, coerceNonNegativeInt, coerceObviousBase10Int, coerceOptionalString, coercePositiveInt, validateExactlyOneEditVariant, validateGitSelection, validateRefsNameVsScope, validateVisionLevelVsMode, type CoercedIntResult, type EditItem, type EditObject, type GitSelectionInput, type InsertAfterEdit, type RefsScopeInput, type ReplaceEdit, type ReplaceLinesEdit, type ReplaceSymbolEdit, type SetLineEdit, type ValidationResult, type VisionInput, } from "./validation.ts";
+export { HASH_LEN, parseLineAnchor, tryParseLineAnchor, type LineAnchor, } from "./hashline.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, resolveReadSeekBinaryFromPath, type ModuleResolver, } from "./platform.ts";
+export { READSEEK_BINARY_ENV, READSEEK_PLATFORM_PACKAGES, readSeekBinaryName, readSeekPlatformKey, resolveReadSeekBinaryFromPackages, resolveReadSeekBinaryOverride, resolveReadSeekCacheDir, type ModuleResolver, type ReadSeekCacheOptions, } from "./platform.ts";
+export { canonicalPathKey, expandUserPath, isSubPath, resolveScopedPath, resolveToCwd, } from "./path.ts";
 export { cleanReadSeekErrorText, parseReadSeekJson, } from "./json.ts";
 export { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_READSEEK_TIMEOUT_MS, ensureSuccessfulStdout, failureFromProcessResult, parseSuccessfulJson, resolveProcessLimits, type ProcessRunOptions, type ProcessRunResult, } from "./process.ts";
 export { runReadSeekNode, runReadSeekNodeJson, runReadSeekNodeText, } from "./process-node.ts";

package/dist/index.js

@@ -535,6 +535,31 @@ function fallbackToolDescriptionMap(builtIns = Object.keys(BUILTIN_FALLBACKS), a
     return description ? [[builtIn, description]] : [];
   }));
 }
+// src/hashline.ts
+var HASH_LEN = 6;
+var LINE_ANCHOR_RE = /^(\d+):([0-9a-fA-F]{6})$/;
+function tryParseLineAnchor(anchor) {
+  const match = LINE_ANCHOR_RE.exec(anchor.trim());
+  if (!match) {
+    return { ok: false, error: `invalid LINE:HASH anchor: ${anchor}` };
+  }
+  const digits = match[1];
+  const line = Number.parseInt(digits, 10);
+  if (!Number.isSafeInteger(line)) {
+    return { ok: false, error: `Line number must be a safe integer, got ${digits} in "${anchor}".` };
+  }
+  if (line < 1) {
+    return { ok: false, error: `Line number must be >= 1, got ${line} in "${anchor}".` };
+  }
+  return { ok: true, anchor: { line, hash: match[2].toLowerCase() } };
+}
+function parseLineAnchor(anchor) {
+  const parsed = tryParseLineAnchor(anchor);
+  if (!parsed.ok)
+    throw new Error(parsed.error);
+  return parsed.anchor;
+}
+
 // src/validation.ts
 function validateGitSelection(input) {
   if (input.ignored && !input.others) {
@@ -566,6 +591,54 @@ function validateVisionLevelVsMode(input) {
   }
   return { ok: true };
 }
+var VARIANT_FIELDS = {
+  set_line: ["anchor", "new_text"],
+  replace_lines: ["start_anchor", "end_anchor", "new_text"],
+  insert_after: ["anchor", "new_text"],
+  replace: ["old_text", "new_text"],
+  replace_symbol: ["symbol", "new_body"]
+};
+function isEditVariant(value) {
+  return EDIT_VARIANTS.includes(value);
+}
+function parseEditItem(item, index) {
+  const keys = Object.keys(item);
+  const variant = keys[0];
+  if (keys.length !== 1 || variant === undefined || !isEditVariant(variant)) {
+    return {
+      ok: false,
+      error: `edits[${index}] must contain exactly one of: ${EDIT_VARIANTS.join(", ")}. Got: [${keys.join(", ")}]`
+    };
+  }
+  const payload = item[variant];
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return { ok: false, error: `edits[${index}].${variant} must be an object` };
+  }
+  const expected = VARIANT_FIELDS[variant];
+  const allowed = variant === "replace" ? [...expected, "all"] : [...expected];
+  const actual = Object.keys(payload);
+  if (actual.some((field) => !allowed.includes(field)) || expected.some((field) => !actual.includes(field))) {
+    return { ok: false, error: `edits[${index}].${variant} contains invalid fields` };
+  }
+  const values = payload;
+  for (const field of expected) {
+    if (typeof values[field] !== "string") {
+      return { ok: false, error: `edits[${index}].${variant}.${field} must be a string` };
+    }
+  }
+  if (variant === "replace" && values.all !== undefined && typeof values.all !== "boolean") {
+    return { ok: false, error: `edits[${index}].replace.all must be a boolean` };
+  }
+  for (const field of expected) {
+    if (!field.endsWith("anchor"))
+      continue;
+    const parsed = tryParseLineAnchor(values[field]);
+    if (!parsed.ok) {
+      return { ok: false, error: `edits[${index}].${variant}.${field}: ${parsed.error}` };
+    }
+  }
+  return { ok: true, edit: item };
+}
 function validateExactlyOneEditVariant(edits) {
   if (!Array.isArray(edits) || edits.length === 0) {
     return { ok: false, error: "edits must contain at least one edit" };
@@ -576,17 +649,71 @@ function validateExactlyOneEditVariant(edits) {
     if (!item || typeof item !== "object" || Array.isArray(item)) {
       return { ok: false, error: `edits[${index}] must be an edit object` };
     }
-    const keys = Object.keys(item);
-    if (keys.length !== 1 || !EDIT_VARIANTS.includes(keys[0])) {
-      return {
-        ok: false,
-        error: `edits[${index}] must contain exactly one of: ${EDIT_VARIANTS.join(", ")}`
-      };
-    }
-    normalized.push(item);
+    const parsed = parseEditItem(item, index);
+    if (!parsed.ok)
+      return parsed;
+    normalized.push(parsed.edit);
   }
   return { ok: true, edits: normalized };
 }
+var BASE10_INT_RE = /^-?\d+$/;
+var MIN_SAFE_INTEGER = BigInt(Number.MIN_SAFE_INTEGER);
+var MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
+function formatReceived(value) {
+  if (typeof value === "number" || typeof value === "bigint")
+    return String(value);
+  return JSON.stringify(value) ?? String(value);
+}
+function invalidInteger(value, name) {
+  return {
+    ok: false,
+    message: `Invalid ${name}: expected a safe base-10 integer, received ${formatReceived(value)}.`
+  };
+}
+function coerceObviousBase10Int(value, name) {
+  if (value === undefined || typeof value === "string" && value.trim() === "") {
+    return { ok: true, value: undefined };
+  }
+  if (typeof value === "number") {
+    if (Number.isSafeInteger(value)) {
+      return { ok: true, value };
+    }
+    return invalidInteger(value, name);
+  }
+  if (typeof value === "string" && BASE10_INT_RE.test(value)) {
+    const parsed = BigInt(value);
+    if (parsed >= MIN_SAFE_INTEGER && parsed <= MAX_SAFE_INTEGER) {
+      return { ok: true, value: Number(parsed) };
+    }
+  }
+  return invalidInteger(value, name);
+}
+function coerceOptionalString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function coerceBoolean(value) {
+  return value === true;
+}
+function coercePositiveInt(value) {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1)
+    return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) {
+    const n = Number(value);
+    if (Number.isSafeInteger(n) && n >= 1)
+      return n;
+  }
+  return;
+}
+function coerceNonNegativeInt(value) {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+    return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) {
+    const n = Number(value);
+    if (Number.isSafeInteger(n) && n >= 0)
+      return n;
+  }
+  return;
+}
 // src/argv.ts
 function buildLineLocation(line, column) {
   return column === undefined ? `line:${line}` : `line:${line}:${column}`;
@@ -596,14 +723,12 @@ function appendGitSelectionArgs(args, input) {
   if (!validated.ok) {
     throw new Error(validated.error);
   }
-  const selection = [
-    input.cached ? "cached" : undefined,
-    input.others ? "others" : undefined,
-    input.ignored ? "ignored" : undefined
-  ].filter((value) => value !== undefined);
-  if (selection.length > 0) {
-    args.push("--git", selection.join(","));
-  }
+  if (input.cached)
+    args.push("--cached");
+  if (input.others)
+    args.push("--others");
+  if (input.ignored)
+    args.push("--ignored");
   return args;
 }
 function pushOptionalString(args, flag, value) {
@@ -680,15 +805,17 @@ function buildViewArgs(input) {
   return args;
 }
 function buildSearchArgs(input) {
-  const args = ["search", input.path, input.pattern];
+  const args = ["search", input.pattern];
+  pushOptionalString(args, "--path", input.path);
   pushOptionalString(args, "--language", input.language);
+  pushOptionalNumber(args, "--limit", input.limit);
   return appendGitSelectionArgs(args, input);
 }
 function buildDefArgs(input) {
-  const args = ["def", input.path];
+  const args = ["def", input.name];
+  pushOptionalString(args, "--path", input.path);
   if (input.format !== undefined)
     args.push("--format", input.format);
-  args.push(input.name);
   pushOptionalString(args, "--language", input.language);
   return appendGitSelectionArgs(args, input);
 }
@@ -696,11 +823,14 @@ function buildRefsArgs(input) {
   const validated = validateRefsNameVsScope(input);
   if (!validated.ok)
     throw new Error(validated.error);
-  const args = ["refs", input.path];
-  if (input.scope) {
-    args.push("--at", buildLineLocation(input.line, input.column));
-  } else if (input.name !== undefined) {
+  const args = ["refs"];
+  if (input.name !== undefined)
     args.push(input.name);
+  pushOptionalString(args, "--path", input.path);
+  if (input.scope) {
+    args.push("--scope");
+    pushOptionalNumber(args, "--line", input.line);
+    pushOptionalNumber(args, "--column", input.column);
   }
   if (input.format !== undefined)
     args.push("--format", input.format);
@@ -716,13 +846,13 @@ function buildEditArgs(input) {
   });
   pushOptionalString(args, "--language", input.language);
   if (input.requestFromStdin)
-    args.push("--request", "-");
+    args.push("--edits", "-");
   return args;
 }
 function buildRenameArgs(input) {
   const args = ["rename", input.path, "--at", buildLineLocation(input.line, input.column), "--to", input.to];
   if (input.workspace !== undefined)
-    args.push("--workspace", input.workspace);
+    args.push(`--workspace=${input.workspace}`);
   appendApplyAndPlanHash(args, {
     apply: input.apply,
     planHash: input.planHash,
@@ -732,9 +862,11 @@ function buildRenameArgs(input) {
   return appendGitSelectionArgs(args, input);
 }
 // src/platform.ts
-import { accessSync, constants as fsConstants } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
 import path from "node:path";
+var READSEEK_BINARY_ENV = "READSEEK_BINARY";
 var READSEEK_PLATFORM_PACKAGES = {
   "darwin-arm64": "@jarkkojs/readseek-darwin-arm64",
   "linux-arm64": "@jarkkojs/readseek-linux-arm64",
@@ -748,6 +880,24 @@ function readSeekBinaryName(platform = process.platform) {
 function readSeekPlatformKey(platform = process.platform, arch = process.arch) {
   return `${platform}-${arch}`;
 }
+function resolveReadSeekBinaryOverride(environment = process.env) {
+  const binaryPath = environment[READSEEK_BINARY_ENV];
+  if (binaryPath === undefined)
+    return null;
+  if (!path.isAbsolute(binaryPath)) {
+    throw new Error(`${READSEEK_BINARY_ENV} must be an absolute path to the readseek executable`);
+  }
+  try {
+    if (!statSync(binaryPath).isFile())
+      throw new Error("not a regular file");
+    accessSync(binaryPath, fsConstants.X_OK);
+  } catch (error) {
+    throw new Error(`${READSEEK_BINARY_ENV} does not point to an executable file: ${binaryPath}`, {
+      cause: error
+    });
+  }
+  return binaryPath;
+}
 function resolveReadSeekBinaryFromPackages(resolver = resolveFromPackage, options = {}) {
   const resolve = typeof resolver === "function" ? resolver : resolver.resolve.bind(resolver);
   const platform = options.platform ?? process.platform;
@@ -773,18 +923,68 @@ function resolveReadSeekBinaryFromPackages(resolver = resolveFromPackage, option
   accessSync(binaryPath, fsConstants.X_OK);
   return binaryPath;
 }
-function resolveReadSeekBinaryFromPath(pathEnv = process.env.PATH) {
-  const name = readSeekBinaryName();
-  for (const dir of (pathEnv ?? "").split(path.delimiter)) {
-    if (!dir)
-      continue;
-    const candidate = path.join(dir, name);
-    try {
-      accessSync(candidate, fsConstants.X_OK);
-      return candidate;
-    } catch {}
+function resolveReadSeekCacheDir(subPath, options = {}) {
+  const env = options.environment ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const home = options.homedir ? options.homedir() : homedir();
+  const cwd = options.cwd ?? process.cwd();
+  const localDirName = options.localDirName ?? ".readseek";
+  if (localDirName && localDirName.length > 0) {
+    const local = path.join(cwd, localDirName);
+    if (existsSync(local))
+      return local;
+  }
+  let base;
+  if (platform === "win32") {
+    base = env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+  } else {
+    const xdg = env.XDG_CACHE_HOME?.trim();
+    base = xdg && path.isAbsolute(xdg) ? xdg : path.join(home, ".cache");
+  }
+  const pathModule = platform === "win32" ? path.win32 : path;
+  if (subPath === undefined) {
+    return pathModule.join(base, "readseek");
+  }
+  const parts = Array.isArray(subPath) ? subPath : [subPath];
+  return pathModule.join(base, ...parts);
+}
+// src/path.ts
+import { realpathSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import path2 from "node:path";
+var UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+function canonicalPathKey(cwd, filePath) {
+  const resolved = path2.resolve(cwd, filePath);
+  try {
+    return realpathSync.native(resolved);
+  } catch {
+    return resolved;
   }
-  return null;
+}
+function expandUserPath(filePath, homedirFn = homedir2) {
+  const withoutAt = filePath.startsWith("@") ? filePath.slice(1) : filePath;
+  const normalized = withoutAt.replace(UNICODE_SPACES, " ");
+  if (normalized === "~")
+    return homedirFn();
+  if (normalized.startsWith("~/"))
+    return homedirFn() + normalized.slice(1);
+  return normalized;
+}
+function resolveToCwd(filePath, cwd, homedirFn = homedir2) {
+  const expanded = expandUserPath(filePath, homedirFn);
+  return path2.isAbsolute(expanded) ? expanded : path2.resolve(cwd, expanded);
+}
+function isSubPath(parent, candidate) {
+  const relative = path2.relative(parent, candidate);
+  return relative === "" || !relative.startsWith(`..${path2.sep}`) && relative !== ".." && !path2.isAbsolute(relative);
+}
+function resolveScopedPath(root, rawPath, fallback = ".") {
+  const canonicalRoot = canonicalPathKey(root, ".");
+  const candidate = canonicalPathKey(canonicalRoot, rawPath ?? fallback);
+  if (!isSubPath(canonicalRoot, candidate)) {
+    return { ok: false, error: `path escapes project root (${canonicalRoot}): ${rawPath ?? fallback}` };
+  }
+  return { ok: true, path: candidate };
 }
 // src/json.ts
 var READSEEK_USAGE_HINT = /\n\s*Run readseek(?: [\w-]+)* --help for more information\.?\s*$/;
@@ -1207,6 +1407,7 @@ function parseCheckOutput(value) {
   if (!Array.isArray(output.diagnostics))
     throw new Error("invalid readseek diagnostics");
   return {
+    file_hash: optionalString(output.file_hash, "file_hash"),
     errorCount: requireNumber(output.error_count, "error_count"),
     missingCount: requireNumber(output.missing_count, "missing_count"),
     diagnostics: output.diagnostics.map((diagnostic) => {
@@ -1611,6 +1812,7 @@ function createReadSeekClient(runner) {
         path: target,
         pattern,
         language: options.language,
+        limit: options.limit,
         cached: options.cached,
         others: options.others,
         ignored: options.ignored
@@ -1676,7 +1878,8 @@ function createReadSeekClient(runner) {
         path: filePath,
         apply: options.apply,
         planHash: options.planHash,
-        language: options.language
+        language: options.language,
+        requestFromStdin: true
       });
       return parseEditOutput(await runner.json(args, {
         signal: options.signal,
@@ -1707,6 +1910,7 @@ export {
   validateRefsNameVsScope,
   validateGitSelection,
   validateExactlyOneEditVariant,
+  tryParseLineAnchor,
   runReadSeekNodeText,
   runReadSeekNodeJson,
   runReadSeekNode,
@@ -1715,7 +1919,10 @@ export {
   runReadSeekBun,
   rewriteBacktickedToolNames,
   resolveToolName,
-  resolveReadSeekBinaryFromPath,
+  resolveToCwd,
+  resolveScopedPath,
+  resolveReadSeekCacheDir,
+  resolveReadSeekBinaryOverride,
   resolveReadSeekBinaryFromPackages,
   resolveProcessLimits,
   renderToolRoutingPolicy,
@@ -1728,13 +1935,22 @@ export {
   preferredToolDescriptionMap,
   parseSuccessfulJson,
   parseReadSeekJson,
+  parseLineAnchor,
+  isSubPath,
   getToolContract,
   fallbackToolDescriptionMap,
   failureFromProcessResult,
+  expandUserPath,
   ensureSuccessfulStdout,
   createReadSeekClient,
+  coercePositiveInt,
+  coerceOptionalString,
+  coerceObviousBase10Int,
+  coerceNonNegativeInt,
+  coerceBoolean,
   cleanReadSeekErrorText,
   classifyReadSeekFailure,
+  canonicalPathKey,
   buildViewArgs,
   buildSearchArgs,
   buildRenameArgs,
@@ -1754,7 +1970,9 @@ export {
   TOOL_COMPACT_GUIDELINES,
   REPLACEABLE_TOOLS,
   READSEEK_PLATFORM_PACKAGES,
+  READSEEK_BINARY_ENV,
   PARAM_DESCRIPTIONS,
+  HASH_LEN,
   GIT_SELECTION_FLAGS,
   EDIT_VARIANTS,
   DOCUMENT_NODE_KINDS,

package/dist/path.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Canonical cache key for a file as seen by independent tool producers.
+ *
+ * Resolve against `cwd`, then collapse symlinks. Falls back to the
+ * resolved-but-unresolved-symlink form when the file does not exist —
+ * `realpathSync` throws ENOENT, and a lookup for a since-deleted file must
+ * not fail.
+ */
+export declare function canonicalPathKey(cwd: string, filePath: string): string;
+export declare function expandUserPath(filePath: string, homedirFn?: () => string): string;
+export declare function resolveToCwd(filePath: string, cwd: string, homedirFn?: () => string): string;
+export declare function isSubPath(parent: string, candidate: string): boolean;
+export declare function resolveScopedPath(root: string, rawPath: string | undefined, fallback?: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/platform.d.ts

@@ -1,3 +1,4 @@
+export declare const READSEEK_BINARY_ENV = "READSEEK_BINARY";
 export declare const READSEEK_PLATFORM_PACKAGES: Readonly<Record<string, string>>;
 export type ModuleResolver = {
     resolve: (specifier: string, options?: {
@@ -6,14 +7,17 @@ export type ModuleResolver = {
 };
 export declare function readSeekBinaryName(platform?: string): string;
 export declare function readSeekPlatformKey(platform?: string, arch?: string): string;
+export declare function resolveReadSeekBinaryOverride(environment?: Readonly<Record<string, string | undefined>>): string | null;
 export declare function resolveReadSeekBinaryFromPackages(resolver?: ModuleResolver["resolve"] | ModuleResolver, options?: {
     platform?: string;
     arch?: string;
     metaPackage?: string;
 }): string;
-/**
- * Find an executable readseek on PATH, or null. PATH is the way a user-managed
- * install (package manager, `npm i -g`, cargo) makes itself known; plugins must
- * not grow their own binary-path settings on top of it.
- */
-export declare function resolveReadSeekBinaryFromPath(pathEnv?: string | undefined): string | null;
+export type ReadSeekCacheOptions = {
+    cwd?: string;
+    localDirName?: string;
+    environment?: Readonly<Record<string, string | undefined>>;
+    platform?: string;
+    homedir?: () => string;
+};
+export declare function resolveReadSeekCacheDir(subPath?: string | readonly string[], options?: ReadSeekCacheOptions): string;

package/dist/validation.d.ts

@@ -23,11 +23,56 @@ export type VisionInput = {
     outline?: boolean;
 };
 export declare function validateVisionLevelVsMode(input: VisionInput): ValidationResult;
-export type EditObject = Record<string, unknown>;
+export type SetLineEdit = {
+    set_line: {
+        anchor: string;
+        new_text: string;
+    };
+};
+export type ReplaceLinesEdit = {
+    replace_lines: {
+        start_anchor: string;
+        end_anchor: string;
+        new_text: string;
+    };
+};
+export type InsertAfterEdit = {
+    insert_after: {
+        anchor: string;
+        new_text: string;
+    };
+};
+export type ReplaceEdit = {
+    replace: {
+        old_text: string;
+        new_text: string;
+        all?: boolean;
+    };
+};
+export type ReplaceSymbolEdit = {
+    replace_symbol: {
+        symbol: string;
+        new_body: string;
+    };
+};
+export type EditItem = SetLineEdit | ReplaceLinesEdit | InsertAfterEdit | ReplaceEdit | ReplaceSymbolEdit;
+export type EditObject = EditItem;
 export declare function validateExactlyOneEditVariant(edits: unknown): {
     ok: true;
-    edits: EditObject[];
+    edits: EditItem[];
 } | {
     ok: false;
     error: string;
 };
+export type CoercedIntResult = {
+    ok: true;
+    value: number | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function coerceObviousBase10Int(value: unknown, name: string): CoercedIntResult;
+export declare function coerceOptionalString(value: unknown): string | undefined;
+export declare function coerceBoolean(value: unknown): boolean;
+export declare function coercePositiveInt(value: unknown): number | undefined;
+export declare function coerceNonNegativeInt(value: unknown): number | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarkkojs/readseek-api",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "description": "Shared ReadSeek CLI contract, validation, argv builders, and bounded process runners",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,7 +22,6 @@
   },
   "files": [
     "dist/",
-    "LICENSE",
     "README.md"
   ],
   "scripts": {
@@ -45,7 +44,7 @@
     "hashline"
   ],
   "dependencies": {
-    "@jarkkojs/readseek": "^0.9.12"
+    "@jarkkojs/readseek": "^0.9.14"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/LICENSE

@@ -1,176 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS