@jarkkojs/readseek-api 0.9.9 → 0.9.10

package/dist/client.d.ts

@@ -0,0 +1,358 @@
+import type { DigestFacet, VisionAnalysisMode, VisionLevel, VisionMode } from "./contract.ts";
+export interface ReadSeekHashline {
+    line: number;
+    hash: string;
+    text: string;
+}
+export interface ReadSeekReadOutput {
+    file: string;
+    language: string;
+    line_count: number;
+    file_hash: string;
+    start_line: number;
+    end_line: number;
+    hashlines: ReadSeekHashline[];
+}
+export interface ReadSeekSymbol {
+    kind: string;
+    name: string;
+    qualified_name: string;
+    start_line: number;
+    end_line: number;
+    start_hash: string;
+    end_hash: string;
+}
+export interface ReadSeekMapOutput {
+    file: string;
+    language: string;
+    line_count: number;
+    file_hash: string;
+    symbols: ReadSeekSymbol[];
+}
+export interface ReadSeekSearchCapture {
+    name: string;
+    start_line: number;
+    end_line: number;
+    start_hash: string;
+    end_hash: string;
+    hashlines: ReadSeekHashline[];
+}
+export interface ReadSeekSearchMatch {
+    pattern_index: number;
+    start_line: number;
+    end_line: number;
+    start_hash: string;
+    end_hash: string;
+    hashlines: ReadSeekHashline[];
+    captures: ReadSeekSearchCapture[];
+}
+export interface ReadSeekSearchFileOutput {
+    file: string;
+    language: string;
+    file_hash: string;
+    matches: ReadSeekSearchMatch[];
+}
+export interface ReadSeekReference {
+    file: string;
+    line: number;
+    column: number;
+    line_hash: string;
+    text: string;
+    enclosingSymbol?: string;
+}
+export interface ReadSeekDiagnostic {
+    kind: "error" | "missing";
+    start_line: number;
+    end_line: number;
+}
+export interface ReadSeekCheckOutput {
+    errorCount: number;
+    missingCount: number;
+    diagnostics: ReadSeekDiagnostic[];
+}
+export type ReadSeekOcrText = string;
+export interface ReadSeekDetectedObject {
+    label: string;
+    bbox: [number, number, number, number];
+}
+export type ReadSeekImageMode = VisionAnalysisMode;
+export interface ReadSeekPreparedImage {
+    mime: string;
+    encoding: "base64";
+    data: string;
+}
+export interface ReadSeekDocumentCache {
+    content_hash: string;
+    state: "built" | "reused";
+}
+export type ReadSeekDetection = {
+    kind: "source";
+    type: string;
+    file: string;
+    language: string;
+    engine?: string;
+    supported: boolean;
+    mime?: string;
+    syntax?: string;
+} | {
+    kind: "image";
+    type: string;
+    file: string;
+    mime?: string;
+    format: string;
+    width: number;
+    height: number;
+    animated: boolean;
+    encoding?: "base64";
+    data?: string;
+    ocr?: ReadSeekOcrText;
+    caption?: string;
+    objects?: ReadSeekDetectedObject[];
+} | {
+    kind: "text";
+    type: string;
+    file: string;
+    mime?: string;
+} | {
+    kind: "pdf";
+    type: "application/pdf";
+    file: string;
+    mime?: string;
+    format: "pdf";
+    pages: number;
+};
+export type ReadSeekImageDetection = Extract<ReadSeekDetection, {
+    kind: "image";
+}>;
+export interface IdentifierOutput {
+    text: string;
+    start_column: number;
+    end_column: number;
+    start_byte: number;
+    end_byte: number;
+}
+export interface IdentifyOutput {
+    file: string;
+    language: string;
+    engine?: string;
+    line_count: number;
+    file_hash: string;
+    line: number;
+    column: number;
+    line_hash: string;
+    identifier?: IdentifierOutput;
+    symbol?: {
+        name: string;
+        kind: string;
+        qualified_name: string;
+        start_line: number;
+        end_line: number;
+    };
+}
+export interface EditOutput {
+    file: string;
+    before_hash: string;
+    file_hash: string;
+    plan_hash: string;
+    applied: boolean;
+    changed: boolean;
+    edit_count: number;
+    before_content?: string;
+    content?: string;
+}
+export interface RenameConflict {
+    line: number;
+    column: number;
+    reason: string;
+}
+export interface RenameEdit {
+    line: number;
+    start_column: number;
+    end_column: number;
+    start_byte: number;
+    end_byte: number;
+    occurrence: string;
+    line_hash: string;
+    text: string;
+}
+export interface RenameFileOutput {
+    file: string;
+    language: string;
+    engine?: string;
+    file_hash: string;
+    conflicts: RenameConflict[];
+    edits: RenameEdit[];
+}
+export interface RenameOutput {
+    file: string;
+    language: string;
+    engine?: string;
+    file_hash: string;
+    old_name: string;
+    new_name: string;
+    applied: boolean;
+    conflicts: RenameConflict[];
+    edits: RenameEdit[];
+    others: RenameFileOutput[];
+}
+export interface DefLocation {
+    file: string;
+    line: number;
+    column: number;
+    line_hash: string;
+    text: string;
+    kind?: string;
+    name?: string;
+    qualified_name?: string;
+}
+export interface ReadSeekDigestOptions {
+    select?: DigestFacet | DigestFacet[];
+    at?: string;
+    end?: number;
+    limit?: number;
+    language?: string;
+    visionMode?: VisionMode;
+    visionLevel?: VisionLevel;
+    stdin?: string;
+    stdinName?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Route through the runner's vision path (serialized, long timeout). */
+    vision?: boolean;
+}
+export interface ReadSeekDigestOutput {
+    metadata: ReadSeekDetection;
+    cache?: ReadSeekDocumentCache;
+    content?: unknown;
+    map?: ReadSeekMapOutput;
+    diagnostics?: ReadSeekCheckOutput;
+    identity?: IdentifyOutput;
+}
+export interface ReadSeekFailure {
+    code: "readseek-not-installed" | "readseek-execution-error";
+    message: string;
+    hint?: string;
+}
+/**
+ * Classify an error thrown while invoking readseek into the shared failure
+ * taxonomy: a missing binary or package (`readseek-not-installed`, with an
+ * install hint) versus any other execution error.
+ */
+export declare function classifyReadSeekFailure(err: unknown): ReadSeekFailure;
+export interface ReadSeekRunOptions {
+    signal?: AbortSignal;
+    stdin?: string;
+    timeoutMs?: number;
+    cancelable?: boolean;
+    /** Set by callers that read a vision payload; the runner may serialize and lengthen timeouts. */
+    vision?: boolean;
+}
+/**
+ * Host-supplied spawn seam: resolve the binary and run it, returning stdout as
+ * text or parsed JSON. The plugin owns binary resolution, cache-dir decoration,
+ * cwd, timeout settings, and any vision serialization queue; the client owns
+ * argv construction and output parsing.
+ */
+export interface ReadSeekRunner {
+    text(args: readonly string[], options?: ReadSeekRunOptions): Promise<string>;
+    json(args: readonly string[], options?: ReadSeekRunOptions): Promise<unknown>;
+}
+interface ReadSeekSearchOptions {
+    language?: string;
+    cached?: boolean;
+    others?: boolean;
+    ignored?: boolean;
+    signal?: AbortSignal;
+}
+interface ReadSeekRefsOptions {
+    name?: string;
+    scope?: boolean;
+    line?: number;
+    column?: number;
+    language?: string;
+    cached?: boolean;
+    others?: boolean;
+    ignored?: boolean;
+    signal?: AbortSignal;
+}
+interface DefOptions {
+    name: string;
+    language?: string;
+    cached?: boolean;
+    others?: boolean;
+    ignored?: boolean;
+    signal?: AbortSignal;
+}
+interface EditOptions {
+    apply?: boolean;
+    planHash?: string;
+    language?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    cancelable?: boolean;
+}
+interface RenameOptions {
+    to: string;
+    line: number;
+    column?: number;
+    workspace?: string;
+    apply?: boolean;
+    language?: string;
+    cached?: boolean;
+    others?: boolean;
+    ignored?: boolean;
+    signal?: AbortSignal;
+}
+interface IdentifyOptions {
+    line?: number;
+    column?: number;
+    language?: string;
+    signal?: AbortSignal;
+}
+export interface ReadSeekViewOptions {
+    node?: string;
+    page?: number;
+    kind?: string;
+    depth?: number;
+    outline?: boolean;
+    visionMode?: ReadSeekImageMode;
+    visionLevel?: VisionLevel;
+    signal?: AbortSignal;
+}
+export interface ReadSeekClient {
+    view(filePath: string, options?: ReadSeekViewOptions): Promise<string>;
+    digestRaw(target: string, options?: ReadSeekDigestOptions): Promise<unknown>;
+    digest(target: string, options?: ReadSeekDigestOptions): Promise<ReadSeekDigestOutput>;
+    digestContent(filePath: string, options?: {
+        startLine?: number;
+        endLine?: number;
+        visionMode?: "none" | ReadSeekImageMode;
+        signal?: AbortSignal;
+        vision?: boolean;
+    }): Promise<{
+        metadata: ReadSeekDetection;
+        cache?: ReadSeekDocumentCache;
+        text?: ReadSeekReadOutput;
+        image?: ReadSeekImageDetection;
+    }>;
+    image(filePath: string, modes: ReadSeekImageMode[], options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadSeekDetection>;
+    preparedImage(filePath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadSeekPreparedImage>;
+    search(target: string, pattern: string, options?: ReadSeekSearchOptions): Promise<ReadSeekSearchFileOutput[]>;
+    refs(target: string, options?: ReadSeekRefsOptions): Promise<ReadSeekReference[]>;
+    def(target: string, options: DefOptions): Promise<DefLocation[]>;
+    check(filePath: string, content: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadSeekCheckOutput>;
+    identify(filePath: string, content: string, options?: IdentifyOptions): Promise<IdentifyOutput>;
+    detect(filePath: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ReadSeekDetection>;
+    edit(filePath: string, edits: unknown[], options?: EditOptions): Promise<EditOutput>;
+    rename(filePath: string, options: RenameOptions): Promise<RenameOutput>;
+}
+export declare function createReadSeekClient(runner: ReadSeekRunner): ReadSeekClient;
+export {};

package/dist/index.d.ts

@@ -2,8 +2,9 @@ export { DIGEST_FACETS, DOCUMENT_NODE_KINDS, EDIT_VARIANTS, GIT_SELECTION_FLAGS,
 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";
+export { READSEEK_PLATFORM_PACKAGES, readSeekBinaryName, readSeekPlatformKey, resolveReadSeekBinaryFromPackages, resolveReadSeekBinaryFromPath, type ModuleResolver, } from "./platform.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";
 export { runReadSeekBun, runReadSeekBunJson, runReadSeekBunText, } from "./process-bun.ts";
+export { classifyReadSeekFailure, createReadSeekClient, type DefLocation, type EditOutput, type IdentifierOutput, type IdentifyOutput, type ReadSeekCheckOutput, type ReadSeekClient, type ReadSeekDetection, type ReadSeekDetectedObject, type ReadSeekDiagnostic, type ReadSeekDigestOptions, type ReadSeekDigestOutput, type ReadSeekDocumentCache, type ReadSeekFailure, type ReadSeekHashline, type ReadSeekImageDetection, type ReadSeekImageMode, type ReadSeekMapOutput, type ReadSeekOcrText, type ReadSeekPreparedImage, type ReadSeekReadOutput, type ReadSeekReference, type ReadSeekRunOptions, type ReadSeekRunner, type RenameConflict, type RenameEdit, type RenameFileOutput, type RenameOutput, type ReadSeekSearchCapture, type ReadSeekSearchFileOutput, type ReadSeekSearchMatch, type ReadSeekSymbol, type ReadSeekViewOptions, } from "./client.ts";

package/dist/index.js

@@ -410,11 +410,6 @@ function getToolContract(name) {
 }
 // src/policy.ts
 var REPLACEABLE_TOOLS = [
-  {
-    tool: "digest",
-    builtIn: "read",
-    benefit: "it returns LINE:HASH anchors for safe edits."
-  },
   {
     tool: "edit",
     builtIn: "edit",
@@ -452,7 +447,6 @@ var TOOL_COMPACT_GUIDELINES = {
   ]
 };
 var BUILTIN_FALLBACKS = {
-  read: "digest",
   edit: "edit",
   write: "write",
   grep: "grep",
@@ -470,11 +464,10 @@ var PREFERENCE_LEADS = {
   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."
+  edit: "Prefer `edit` with fresh LINE:HASH anchors.",
+  write: "Prefer `write` so the result returns LINE:HASH anchors.",
+  grep: "Prefer `grep` for text/regex search with edit-ready anchors.",
+  apply_patch: "Prefer `edit` for existing text files."
 };
 function resolveToolName(name, aliases = {}) {
   return aliases[name] ?? name;
@@ -732,6 +725,7 @@ function buildRenameArgs(input) {
   return appendGitSelectionArgs(args, input);
 }
 // src/platform.ts
+import { accessSync, constants as fsConstants } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 var READSEEK_PLATFORM_PACKAGES = {
@@ -765,6 +759,19 @@ function resolveReadSeekBinaryFromPackages(resolver = resolveFromPackage, option
   });
   return path.join(path.dirname(packageJsonPath), "bin", readSeekBinaryName(platform));
 }
+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 {}
+  }
+  return null;
+}
 // src/json.ts
 var READSEEK_USAGE_HINT = /\n\s*Run readseek(?: [\w-]+)* --help for more information\.?\s*$/;
 function cleanReadSeekErrorText(stderr) {
@@ -1015,6 +1022,672 @@ async function runReadSeekBunText(binaryPath, args, options = {}) {
 async function runReadSeekBunJson(binaryPath, args, options = {}) {
   return parseSuccessfulJson(await runReadSeekBun(binaryPath, args, options));
 }
+// src/client.ts
+function classifyReadSeekFailure(err) {
+  const failure = err;
+  const message = String(failure?.message ?? err);
+  const missing = failure?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
+  if (missing) {
+    return { code: "readseek-not-installed", message, hint: "Run npm install to install @jarkkojs/readseek." };
+  }
+  return { code: "readseek-execution-error", message };
+}
+function requireNumber(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value))
+    throw new Error(`invalid readseek ${field}: expected safe integer`);
+  return value;
+}
+function requireString(value, field) {
+  if (typeof value !== "string")
+    throw new Error(`invalid readseek ${field}`);
+  return value;
+}
+function requireBoolean(value, field) {
+  if (typeof value !== "boolean")
+    throw new Error(`invalid readseek ${field}: expected boolean`);
+  return value;
+}
+function optionalString(value, field) {
+  if (value === undefined || value === null)
+    return;
+  return requireString(value, field);
+}
+function parseHashline(value, field) {
+  if (!value || typeof value !== "object")
+    throw new Error(`invalid readseek ${field}`);
+  const item = value;
+  return {
+    line: requireNumber(item.line, `${field}.line`),
+    hash: requireString(item.hash, `${field}.hash`),
+    text: requireString(item.text, `${field}.text`)
+  };
+}
+function parseSearchHashlines(value, field) {
+  if (!Array.isArray(value))
+    throw new Error(`invalid readseek ${field}`);
+  return value.map((line) => parseHashline(line, field));
+}
+function parseReadOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek read output");
+  const output = value;
+  const hashlines = output.hashlines;
+  if (!Array.isArray(hashlines))
+    throw new Error("invalid readseek hashlines");
+  return {
+    file: requireString(output.file, "file"),
+    language: requireString(output.language, "language"),
+    line_count: requireNumber(output.line_count, "line_count"),
+    file_hash: requireString(output.file_hash, "file_hash"),
+    start_line: requireNumber(output.start_line, "start_line"),
+    end_line: requireNumber(output.end_line, "end_line"),
+    hashlines: hashlines.map((line) => parseHashline(line, "hashline"))
+  };
+}
+function parseMapOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek map output");
+  const output = value;
+  const symbols = output.symbols;
+  if (!Array.isArray(symbols))
+    throw new Error("invalid readseek symbols");
+  return {
+    file: requireString(output.file, "file"),
+    language: requireString(output.language, "language"),
+    line_count: requireNumber(output.line_count, "line_count"),
+    file_hash: requireString(output.file_hash, "file_hash"),
+    symbols: symbols.map((symbol) => {
+      if (!symbol || typeof symbol !== "object")
+        throw new Error("invalid readseek symbol");
+      const item = symbol;
+      return {
+        kind: requireString(item.kind, "symbol.kind"),
+        name: requireString(item.name, "symbol.name"),
+        qualified_name: requireString(item.qualified_name, "symbol.qualified_name"),
+        start_line: requireNumber(item.start_line, "symbol.start_line"),
+        end_line: requireNumber(item.end_line, "symbol.end_line"),
+        start_hash: requireString(item.start_hash, "symbol.start_hash"),
+        end_hash: requireString(item.end_hash, "symbol.end_hash")
+      };
+    })
+  };
+}
+function parseSearchOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek search output");
+  const output = value;
+  if (!Array.isArray(output.results))
+    throw new Error("invalid readseek search results");
+  return output.results.map((result) => {
+    if (!result || typeof result !== "object")
+      throw new Error("invalid readseek search result");
+    const file = result;
+    if (!Array.isArray(file.matches))
+      throw new Error("invalid readseek search matches");
+    return {
+      file: requireString(file.file, "search.file"),
+      language: requireString(file.language, "search.language"),
+      file_hash: requireString(file.file_hash, "search.file_hash"),
+      matches: file.matches.map((match) => {
+        if (!match || typeof match !== "object")
+          throw new Error("invalid readseek search match");
+        const item = match;
+        if (!Array.isArray(item.captures))
+          throw new Error("invalid readseek search captures");
+        return {
+          pattern_index: item.pattern_index === undefined ? 0 : requireNumber(item.pattern_index, "search.match.pattern_index"),
+          start_line: requireNumber(item.start_line, "search.match.start_line"),
+          end_line: requireNumber(item.end_line, "search.match.end_line"),
+          start_hash: requireString(item.start_hash, "search.match.start_hash"),
+          end_hash: requireString(item.end_hash, "search.match.end_hash"),
+          hashlines: parseSearchHashlines(item.hashlines, "search.match.hashlines"),
+          captures: item.captures.map((capture) => {
+            if (!capture || typeof capture !== "object")
+              throw new Error("invalid readseek search capture");
+            const captureItem = capture;
+            return {
+              name: requireString(captureItem.name, "search.capture.name"),
+              start_line: requireNumber(captureItem.start_line, "search.capture.start_line"),
+              end_line: requireNumber(captureItem.end_line, "search.capture.end_line"),
+              start_hash: requireString(captureItem.start_hash, "search.capture.start_hash"),
+              end_hash: requireString(captureItem.end_hash, "search.capture.end_hash"),
+              hashlines: parseSearchHashlines(captureItem.hashlines, "search.capture.hashlines")
+            };
+          })
+        };
+      })
+    };
+  });
+}
+function parseRefsOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek refs output");
+  const output = value;
+  if (!Array.isArray(output.references))
+    throw new Error("invalid readseek references");
+  return output.references.map((reference) => {
+    if (!reference || typeof reference !== "object")
+      throw new Error("invalid readseek reference");
+    const item = reference;
+    const symbol = item.symbol;
+    const enclosing = symbol && typeof symbol === "object" ? optionalString(symbol.qualified_name, "reference.symbol.qualified_name") : undefined;
+    return {
+      file: requireString(item.file, "reference.file"),
+      line: requireNumber(item.line, "reference.line"),
+      column: requireNumber(item.column, "reference.column"),
+      line_hash: requireString(item.line_hash, "reference.line_hash"),
+      text: requireString(item.text, "reference.text"),
+      enclosingSymbol: enclosing
+    };
+  });
+}
+function parseDiagnosticKind(value) {
+  if (value === "error" || value === "missing")
+    return value;
+  throw new Error("invalid readseek diagnostic.kind");
+}
+function parseCheckOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek check output");
+  const output = value;
+  if (!Array.isArray(output.diagnostics))
+    throw new Error("invalid readseek diagnostics");
+  return {
+    errorCount: requireNumber(output.error_count, "error_count"),
+    missingCount: requireNumber(output.missing_count, "missing_count"),
+    diagnostics: output.diagnostics.map((diagnostic) => {
+      if (!diagnostic || typeof diagnostic !== "object")
+        throw new Error("invalid readseek diagnostic");
+      const item = diagnostic;
+      return {
+        kind: parseDiagnosticKind(item.kind),
+        start_line: requireNumber(item.start_line, "diagnostic.start_line"),
+        end_line: requireNumber(item.end_line, "diagnostic.end_line")
+      };
+    })
+  };
+}
+function parseDetectedObjects(value) {
+  if (value === undefined || value === null)
+    return;
+  if (!Array.isArray(value))
+    throw new Error("invalid readseek detect objects");
+  return value.map((object) => {
+    if (!object || typeof object !== "object")
+      throw new Error("invalid readseek detect object");
+    const item = object;
+    const bbox = item.bbox;
+    if (!Array.isArray(bbox) || bbox.length !== 4)
+      throw new Error("invalid readseek detect object.bbox");
+    return {
+      label: requireString(item.label, "object.label"),
+      bbox: bbox.map((n, i) => requireNumber(n, `object.bbox[${i}]`))
+    };
+  });
+}
+function parseImageEncoding(value) {
+  if (value === "base64")
+    return value;
+  throw new Error("invalid image encoding");
+}
+function parseDetectOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek detect output");
+  const output = value;
+  const type = requireString(output.type, "type");
+  const file = requireString(output.file, "file");
+  const mime = optionalString(output.mime, "mime");
+  if (type === "application/pdf") {
+    if (output.format !== "pdf")
+      throw new Error("invalid readseek PDF format");
+    return {
+      kind: "pdf",
+      type,
+      file,
+      mime,
+      format: output.format,
+      pages: requireNumber(output.pages, "pages")
+    };
+  }
+  if (output.width !== undefined || output.height !== undefined) {
+    return {
+      kind: "image",
+      type,
+      file,
+      mime,
+      format: requireString(output.format, "format"),
+      width: requireNumber(output.width, "width"),
+      height: requireNumber(output.height, "height"),
+      animated: requireBoolean(output.animated, "animated"),
+      encoding: output.encoding === undefined ? undefined : parseImageEncoding(output.encoding),
+      data: output.data === undefined ? undefined : requireString(output.data, "data"),
+      ocr: optionalString(output.ocr, "ocr"),
+      caption: optionalString(output.caption, "caption"),
+      objects: parseDetectedObjects(output.objects)
+    };
+  }
+  if (output.language !== undefined) {
+    return {
+      kind: "source",
+      type,
+      file,
+      language: requireString(output.language, "language"),
+      engine: optionalString(output.engine, "engine"),
+      supported: requireBoolean(output.supported, "supported"),
+      mime,
+      syntax: optionalString(output.syntax, "syntax")
+    };
+  }
+  return { kind: "text", type, file, mime };
+}
+function parseDocumentCache(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek document cache");
+  const cache = value;
+  const state = requireString(cache.state, "cache.state");
+  if (state !== "built" && state !== "reused")
+    throw new Error("invalid readseek cache.state");
+  return {
+    content_hash: requireString(cache.content_hash, "cache.content_hash"),
+    state
+  };
+}
+function parseIdentifyOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek identify output");
+  const output = value;
+  const identifier = output.identifier;
+  const symbol = output.symbol;
+  return {
+    file: requireString(output.file, "file"),
+    language: requireString(output.language, "language"),
+    engine: optionalString(output.engine, "engine"),
+    line_count: requireNumber(output.line_count, "line_count"),
+    file_hash: requireString(output.file_hash, "file_hash"),
+    line: requireNumber(output.line, "line"),
+    column: requireNumber(output.column, "column"),
+    line_hash: requireString(output.line_hash, "line_hash"),
+    identifier: identifier && typeof identifier === "object" ? {
+      text: requireString(identifier.text, "identifier.text"),
+      start_column: requireNumber(identifier.start_column, "identifier.start_column"),
+      end_column: requireNumber(identifier.end_column, "identifier.end_column"),
+      start_byte: requireNumber(identifier.start_byte, "identifier.start_byte"),
+      end_byte: requireNumber(identifier.end_byte, "identifier.end_byte")
+    } : undefined,
+    symbol: symbol && typeof symbol === "object" ? {
+      name: requireString(symbol.name, "symbol.name"),
+      kind: requireString(symbol.kind, "symbol.kind"),
+      qualified_name: requireString(symbol.qualified_name, "symbol.qualified_name"),
+      start_line: requireNumber(symbol.start_line, "symbol.start_line"),
+      end_line: requireNumber(symbol.end_line, "symbol.end_line")
+    } : undefined
+  };
+}
+function parseImageContent(value) {
+  const detection = parseDetectOutput(value);
+  if (detection.kind !== "image")
+    throw new Error("invalid readseek image content");
+  return detection;
+}
+function parseTextContent(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek content");
+  const output = value;
+  if (output.hashlines !== undefined && output.start_line === undefined) {
+    const hashlines = parseSearchHashlines(output.hashlines, "content.hashlines");
+    const first = hashlines[0];
+    const last = hashlines[hashlines.length - 1];
+    return {
+      file: requireString(output.file, "file"),
+      language: requireString(output.language, "language"),
+      line_count: requireNumber(output.line_count, "line_count"),
+      file_hash: requireString(output.file_hash, "file_hash"),
+      start_line: first?.line ?? 1,
+      end_line: last?.line ?? 0,
+      hashlines
+    };
+  }
+  return parseReadOutput(value);
+}
+function parseDigestEnvelope(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek digest output");
+  const output = value;
+  if (output.metadata === undefined)
+    throw new Error("invalid readseek digest metadata");
+  const result = {
+    metadata: parseDetectOutput(output.metadata)
+  };
+  if (output.cache !== undefined)
+    result.cache = parseDocumentCache(output.cache);
+  if (output.content !== undefined)
+    result.content = output.content;
+  if (output.map !== undefined)
+    result.map = parseMapOutput(output.map);
+  if (output.diagnostics !== undefined)
+    result.diagnostics = parseCheckOutput(output.diagnostics);
+  if (output.identity !== undefined)
+    result.identity = parseIdentifyOutput(output.identity);
+  return result;
+}
+function parseEditOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek edit output");
+  const output = value;
+  return {
+    file: requireString(output.file, "file"),
+    before_hash: requireString(output.before_hash, "before_hash"),
+    file_hash: requireString(output.file_hash, "file_hash"),
+    plan_hash: requireString(output.plan_hash, "plan_hash"),
+    applied: requireBoolean(output.applied, "applied"),
+    changed: requireBoolean(output.changed, "changed"),
+    edit_count: requireNumber(output.edit_count, "edit_count"),
+    before_content: optionalString(output.before_content, "before_content"),
+    content: optionalString(output.content, "content")
+  };
+}
+function parseRenameConflicts(value, field) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value))
+    throw new Error(`invalid readseek ${field}`);
+  return value.map((item) => {
+    if (!item || typeof item !== "object")
+      throw new Error(`invalid readseek ${field} entry`);
+    const c = item;
+    return {
+      line: requireNumber(c.line, `${field}.line`),
+      column: requireNumber(c.column, `${field}.column`),
+      reason: requireString(c.reason, `${field}.reason`)
+    };
+  });
+}
+function parseRenameEdits(value, field) {
+  if (value === undefined)
+    return [];
+  if (!Array.isArray(value))
+    throw new Error(`invalid readseek ${field} entry`);
+  return value.map((item) => {
+    if (!item || typeof item !== "object")
+      throw new Error(`invalid readseek ${field} entry`);
+    const e = item;
+    return {
+      line: requireNumber(e.line, `${field}.line`),
+      start_column: requireNumber(e.start_column, `${field}.start_column`),
+      end_column: requireNumber(e.end_column, `${field}.end_column`),
+      start_byte: requireNumber(e.start_byte, `${field}.start_byte`),
+      end_byte: requireNumber(e.end_byte, `${field}.end_byte`),
+      occurrence: requireString(e.occurrence, `${field}.occurrence`),
+      line_hash: requireString(e.line_hash, `${field}.line_hash`),
+      text: requireString(e.text, `${field}.text`)
+    };
+  });
+}
+function parseRenameOutput(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek rename output");
+  const output = value;
+  const others = output.others;
+  if (others !== undefined && !Array.isArray(others))
+    throw new Error("invalid readseek others");
+  return {
+    file: requireString(output.file, "file"),
+    language: requireString(output.language, "language"),
+    engine: optionalString(output.engine, "engine"),
+    file_hash: requireString(output.file_hash, "file_hash"),
+    old_name: requireString(output.old_name, "old_name"),
+    new_name: requireString(output.new_name, "new_name"),
+    applied: requireBoolean(output.applied, "applied"),
+    conflicts: parseRenameConflicts(output.conflicts, "conflicts"),
+    edits: parseRenameEdits(output.edits, "edits"),
+    others: others?.map((entry) => {
+      if (!entry || typeof entry !== "object")
+        throw new Error("invalid readseek other");
+      const o = entry;
+      return {
+        file: requireString(o.file, "other.file"),
+        language: requireString(o.language, "other.language"),
+        engine: optionalString(o.engine, "other.engine"),
+        file_hash: requireString(o.file_hash, "other.file_hash"),
+        conflicts: parseRenameConflicts(o.conflicts, "other.conflicts"),
+        edits: parseRenameEdits(o.edits, "other.edits")
+      };
+    }) ?? []
+  };
+}
+function parseDefCompact(value) {
+  if (!value || typeof value !== "object")
+    throw new Error("invalid readseek def output");
+  const output = value;
+  const locations = output.locations;
+  if (!Array.isArray(locations))
+    throw new Error("invalid readseek def locations");
+  return locations.map((loc) => {
+    if (!loc || typeof loc !== "object")
+      throw new Error("invalid readseek def location");
+    const item = loc;
+    return {
+      file: requireString(item.file, "location.file"),
+      line: requireNumber(item.line, "location.line"),
+      column: requireNumber(item.column, "location.column"),
+      line_hash: requireString(item.line_hash, "location.line_hash"),
+      text: requireString(item.text, "location.text"),
+      kind: optionalString(item.kind, "location.kind"),
+      name: optionalString(item.name, "location.name"),
+      qualified_name: optionalString(item.qualified_name, "location.qualified_name")
+    };
+  });
+}
+function createReadSeekClient(runner) {
+  function digestArgs(target, options) {
+    return buildDigestArgs({
+      path: target,
+      select: options.select ?? "content",
+      at: options.at,
+      end: options.end,
+      limit: options.limit,
+      language: options.language,
+      visionMode: options.visionMode,
+      visionLevel: options.visionLevel,
+      stdinName: options.stdin !== undefined && target === "-" ? options.stdinName ?? target : undefined
+    });
+  }
+  async function runDigestRaw(target, options = {}) {
+    const args = digestArgs(target, options);
+    const runOptions = {
+      signal: options.signal,
+      stdin: options.stdin,
+      timeoutMs: options.timeoutMs,
+      vision: options.vision
+    };
+    return runner.json(args, runOptions);
+  }
+  async function digest(target, options = {}) {
+    return parseDigestEnvelope(await runDigestRaw(target, options));
+  }
+  function requireDigestContent(envelope, field) {
+    if (envelope.content === undefined)
+      throw new Error(`invalid readseek ${field}: missing content`);
+    return envelope.content;
+  }
+  async function digestContent(filePath, options = {}) {
+    const envelope = await digest(filePath, {
+      select: "content",
+      at: options.startLine !== undefined ? buildLineLocation(options.startLine) : undefined,
+      end: options.endLine,
+      visionMode: options.visionMode,
+      signal: options.signal,
+      vision: options.vision
+    });
+    if (envelope.metadata.kind === "pdf") {
+      return { metadata: envelope.metadata, cache: envelope.cache };
+    }
+    const content = requireDigestContent(envelope, "content");
+    if (envelope.metadata.kind === "image") {
+      return { metadata: envelope.metadata, image: parseImageContent(content) };
+    }
+    return { metadata: envelope.metadata, text: parseTextContent(content) };
+  }
+  return {
+    async view(filePath, options = {}) {
+      const args = buildViewArgs({
+        path: filePath,
+        node: options.node,
+        page: options.page,
+        kind: options.kind,
+        depth: options.depth,
+        outline: options.outline,
+        visionMode: options.visionMode,
+        visionLevel: options.visionLevel
+      });
+      return runner.text(args, {
+        signal: options.signal,
+        vision: options.visionMode !== undefined
+      });
+    },
+    digestRaw(target, options = {}) {
+      return runDigestRaw(target, options);
+    },
+    digest,
+    digestContent,
+    async image(filePath, modes, options = {}) {
+      const requestedModes = modes.length > 1 ? ["all"] : modes;
+      const results = await Promise.allSettled(requestedModes.map(async (mode) => {
+        const digested = await digestContent(filePath, {
+          visionMode: mode,
+          signal: options.signal,
+          vision: true
+        });
+        if (!digested.image)
+          throw new Error(`readseek returned no image analysis for ${filePath}`);
+        return digested.image;
+      }));
+      let merged;
+      for (const result of results) {
+        if (result.status !== "fulfilled")
+          continue;
+        const detection = result.value;
+        merged = merged === undefined ? detection : {
+          ...merged,
+          ocr: detection.ocr ?? merged.ocr,
+          caption: detection.caption ?? merged.caption,
+          objects: detection.objects ?? merged.objects
+        };
+      }
+      if (merged !== undefined)
+        return merged;
+      const failure = results.find((result) => result.status === "rejected");
+      if (failure?.status === "rejected")
+        throw failure.reason;
+      throw new Error(`readseek returned no image analysis for ${filePath}`);
+    },
+    async preparedImage(filePath, options = {}) {
+      const digested = await digestContent(filePath, {
+        visionMode: "none",
+        signal: options.signal
+      });
+      const output = digested.image;
+      if (!output || output.encoding !== "base64" || output.data === undefined || output.mime === undefined) {
+        throw new Error(`readseek returned no prepared image for ${filePath}`);
+      }
+      return { mime: output.mime, encoding: output.encoding, data: output.data };
+    },
+    async search(target, pattern, options = {}) {
+      const args = buildSearchArgs({
+        path: target,
+        pattern,
+        language: options.language,
+        cached: options.cached,
+        others: options.others,
+        ignored: options.ignored
+      });
+      return parseSearchOutput(await runner.json(args, { signal: options.signal }));
+    },
+    async refs(target, options = {}) {
+      const args = buildRefsArgs({
+        path: target,
+        name: options.name,
+        scope: options.scope,
+        line: options.line,
+        column: options.column,
+        language: options.language,
+        cached: options.cached,
+        others: options.others,
+        ignored: options.ignored
+      });
+      return parseRefsOutput(await runner.json(args, { signal: options.signal }));
+    },
+    async def(target, options) {
+      const args = buildDefArgs({
+        path: target,
+        name: options.name,
+        format: "plain",
+        language: options.language,
+        cached: options.cached,
+        others: options.others,
+        ignored: options.ignored
+      });
+      return parseDefCompact(await runner.json(args, { signal: options.signal }));
+    },
+    async check(filePath, content, options = {}) {
+      const envelope = await digest("-", {
+        select: "diagnostics",
+        stdin: content,
+        stdinName: filePath,
+        signal: options.signal
+      });
+      if (!envelope.diagnostics)
+        throw new Error("invalid readseek diagnostics: missing diagnostics facet");
+      return envelope.diagnostics;
+    },
+    async identify(filePath, content, options = {}) {
+      const envelope = await digest("-", {
+        select: "identity",
+        stdin: content,
+        stdinName: filePath,
+        at: options.line !== undefined ? buildLineLocation(options.line, options.column) : undefined,
+        language: options.language,
+        signal: options.signal
+      });
+      if (!envelope.identity)
+        throw new Error("invalid readseek identity: missing identity facet");
+      return envelope.identity;
+    },
+    async detect(filePath, options = {}) {
+      const envelope = await digest(filePath, { select: "metadata", signal: options.signal });
+      return envelope.metadata;
+    },
+    async edit(filePath, edits, options = {}) {
+      const args = buildEditArgs({
+        path: filePath,
+        apply: options.apply,
+        planHash: options.planHash,
+        language: options.language
+      });
+      return parseEditOutput(await runner.json(args, {
+        signal: options.signal,
+        stdin: JSON.stringify({ edits }),
+        timeoutMs: options.timeoutMs,
+        cancelable: options.cancelable
+      }));
+    },
+    async rename(filePath, options) {
+      const args = buildRenameArgs({
+        path: filePath,
+        to: options.to,
+        line: options.line,
+        column: options.column,
+        workspace: options.workspace,
+        apply: options.apply,
+        language: options.language,
+        cached: options.cached,
+        others: options.others,
+        ignored: options.ignored
+      });
+      return parseRenameOutput(await runner.json(args, { signal: options.signal }));
+    }
+  };
+}
 export {
   validateVisionLevelVsMode,
   validateRefsNameVsScope,
@@ -1028,6 +1701,7 @@ export {
   runReadSeekBun,
   rewriteBacktickedToolNames,
   resolveToolName,
+  resolveReadSeekBinaryFromPath,
   resolveReadSeekBinaryFromPackages,
   resolveProcessLimits,
   renderToolRoutingPolicy,
@@ -1044,7 +1718,9 @@ export {
   fallbackToolDescriptionMap,
   failureFromProcessResult,
   ensureSuccessfulStdout,
+  createReadSeekClient,
   cleanReadSeekErrorText,
+  classifyReadSeekFailure,
   buildViewArgs,
   buildSearchArgs,
   buildRenameArgs,

package/dist/platform.d.ts

@@ -11,3 +11,9 @@ export declare function resolveReadSeekBinaryFromPackages(resolver?: ModuleResol
     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;

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@jarkkojs/readseek-api",
-  "version": "0.9.9",
+  "version": "0.9.10",
   "description": "Shared ReadSeek CLI contract, validation, argv builders, and bounded process runners",
   "type": "module",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/jarkkojs/readseek/tree/main/packages/readseek-api#readme",
+  "homepage": "https://gitlab.com/jarkkojs/readseek/-/tree/main/packages/readseek-api#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jarkkojs/readseek.git",
+    "url": "git+https://gitlab.com/jarkkojs/readseek.git",
     "directory": "packages/readseek-api"
   },
   "bugs": {
-    "url": "https://github.com/jarkkojs/readseek/issues"
+    "url": "https://gitlab.com/jarkkojs/readseek/-/issues"
   },
   "exports": {
     ".": {
@@ -45,7 +45,7 @@
     "hashline"
   ],
   "dependencies": {
-    "@jarkkojs/readseek": "^0.9.9"
+    "@jarkkojs/readseek": "^0.9.10"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",