@jarkkojs/readseek-api 0.9.5

package/dist/index.js

@@ -0,0 +1,952 @@
+// src/contract.ts
+var DIGEST_FACETS = [
+  "metadata",
+  "content",
+  "map",
+  "diagnostics",
+  "identity"
+];
+var VISION_MODES = ["none", "all", "ocr", "caption", "objects"];
+var VISION_ANALYSIS_MODES = ["all", "ocr", "caption", "objects"];
+var VISION_LEVELS = ["low", "medium", "high"];
+var DOCUMENT_NODE_KINDS = [
+  "artifact",
+  "footer",
+  "header",
+  "heading",
+  "marginal_label",
+  "page",
+  "page_number",
+  "paragraph",
+  "section",
+  "structural_section"
+];
+var EDIT_VARIANTS = [
+  "set_line",
+  "replace_lines",
+  "insert_after",
+  "replace",
+  "replace_symbol"
+];
+var GIT_SELECTION_FLAGS = ["cached", "others", "ignored"];
+var TOOL_NAMES = [
+  "read",
+  "edit",
+  "write",
+  "grep",
+  "digest",
+  "view",
+  "search",
+  "def",
+  "refs",
+  "rename"
+];
+var PARAM_DESCRIPTIONS = {
+  path: "Absolute or relative file path",
+  searchPath: "File or directory to search; defaults to the current directory",
+  language: "Language override when auto-detection is ambiguous",
+  languageOverride: "Language override",
+  languageSymbol: "Language override for symbol replacement",
+  pattern: "AST pattern (ast-grep style), such as console.log($$$ARGS)",
+  grepPattern: "Regex pattern; set literal for exact text",
+  name: "Qualified or unqualified symbol name",
+  refsName: "Identifier to find references for",
+  scope: "Restrict results to the binding at the cursor",
+  line: "One-based cursor line; required with scope",
+  renameLine: "One-based cursor line of the symbol to rename",
+  column: "One-based cursor byte column for disambiguation",
+  cached: "In a Git repository, search tracked/indexed files",
+  others: "In a Git repository, search untracked files",
+  ignored: "With others=true, include ignored untracked files",
+  select: "Facets: metadata, content, map, diagnostics, identity (default content)",
+  selectComma: "Comma-separated facets: metadata, content, map, diagnostics, identity",
+  at: "Location: line:N[:COLUMN], hash:HASH[:COLUMN], or symbol:NAME",
+  end: "Last line to include",
+  limit: "Maximum number of lines to include",
+  offset: "One-based starting line",
+  readLimit: "Maximum lines to return",
+  symbolRead: "Symbol name to read",
+  bundle: "Include related symbols from the same file; requires symbol",
+  image: "Standalone image mode: none, all, ocr, caption, objects. Required for standalone images.",
+  visionModeDigest: "Standalone image mode: none, all, caption, objects, or ocr",
+  visionModeView: "Analyze selected assets: all, ocr, caption, or objects",
+  visionLevel: "Vision inference level: low (default), medium, or high",
+  node: "Node ID to use as the view root",
+  page: "One-based source page",
+  kind: "Node kind filter",
+  depth: "Maximum depth below selected roots",
+  outline: "Return outline nodes only",
+  edits: "Use set_line, replace_lines, insert_after, replace_symbol, or replace",
+  editVariant: "Exactly one nested edit variant",
+  setLine: 'Replace one line: {"set_line":{"anchor":"LINE:HASH","new_text":"..."}}',
+  replaceLines: 'Replace a range: {"replace_lines":{"start_anchor":"LINE:HASH","end_anchor":"LINE:HASH","new_text":"..."}}',
+  insertAfter: 'Insert text: {"insert_after":{"anchor":"LINE:HASH","new_text":"..."}}',
+  replace: 'Replace text: {"replace":{"old_text":"...","new_text":"..."}}',
+  replaceSymbol: 'Replace a symbol: {"replace_symbol":{"symbol":"name","new_body":"..."}}',
+  anchor: "Fresh LINE:HASH anchor for the line to replace",
+  startAnchor: "Fresh LINE:HASH anchor for the first line in the range",
+  endAnchor: "Fresh LINE:HASH anchor for the last line in the range",
+  insertAnchor: "Fresh LINE:HASH anchor for the line after which to insert",
+  newTextLine: "Replacement text; use an empty string to delete the line",
+  newTextRange: "Replacement text; use an empty string to delete the range",
+  newTextInsert: "Text to insert after the anchored line",
+  oldText: "Exact text to find",
+  newText: "Replacement text",
+  all: "Replace every exact match",
+  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",
+  planHash: "Require the apply plan to match this dry-run plan hash",
+  workspace: "Rename across the project",
+  to: "New symbol name",
+  postEditVerify: "Read back and verify persisted content",
+  content: "Complete text file content",
+  glob: "File-name glob, such as *.ts",
+  ignoreCase: "Ignore case",
+  literal: "Treat pattern literally",
+  context: "Surrounding lines for each match",
+  matchLimit: "Maximum matches to return",
+  summary: "Return per-file counts",
+  grepScope: "Group matches by enclosing symbol",
+  scopeContext: "Context lines within each symbol"
+};
+var TOOL_DESCRIPTIONS = {
+  read: "Read anchored text by range or symbol. Standalone images require an explicit mode. Use it before edits to obtain fresh `LINE:HASH` anchors; use `view` for documents and `digest` with the map facet for structural outlines.",
+  edit: 'Edit existing text files with fresh `LINE:HASH` anchors. Read or search first when no fresh anchors are available. Each `edits[]` item must use exactly one nested object: `{"set_line":{"anchor":"LINE:HASH","new_text":"..."}}`, `{"replace_lines":{"start_anchor":"LINE:HASH","end_anchor":"LINE:HASH","new_text":"..."}}`, `{"insert_after":{"anchor":"LINE:HASH","new_text":"..."}}`, `{"replace_symbol":{"symbol":"name","new_body":"..."}}`, or `{"replace":{"old_text":"...","new_text":"..."}}`.',
+  write: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit` for small changes to an existing file.",
+  grep: "Search text or regex in files and return edit-ready `LINE:HASH` anchors. Use for identifiers, strings, configuration, errors, comments, and documentation.",
+  digest: "Digest source content and images into the native CLI envelope. Returns metadata plus requested facets unchanged from `readseek digest`; use for structural maps, diagnostics, and cursor identity.",
+  view: "Digest a document's structure or selected content. Start with the overview, then narrow by page, node, kind, or depth instead of reading the whole document. PDF is the first supported document format.",
+  search: "Search code by AST structure using ast-grep-style patterns. Results include line hashes usable as `LINE:HASH` anchors. Use `grep` for identifiers, strings, comments, configuration, documentation, or other plain text and regex.",
+  def: "Go to a symbol definition or declaration by name. Accepts qualified or unqualified names; use this instead of text search for functions, methods, classes, types, and other declarations.",
+  refs: "Find references or usages of an identifier by name or cursor binding. Results include enclosing symbols and line hashes usable as `LINE:HASH` anchors. Without cursor scope, results are identifier-name matches; with scope, they follow one binding and exclude shadows. Use text search for literals, and use this before renaming or deleting a symbol.",
+  rename: "Rename a symbol at a source location. Resolvable same-named bindings are preserved; verified edits apply by default. Set `apply: false` to preview the plan before changing files."
+};
+function renderToolDescription(name, aliases = {}) {
+  return TOOL_NAMES.reduce((description, toolName) => description.replaceAll(`\`${toolName}\``, `\`${aliases[toolName] ?? toolName}\``), TOOL_DESCRIPTIONS[name]);
+}
+var gitFlagsSchema = {
+  cached: {
+    type: "boolean",
+    description: PARAM_DESCRIPTIONS.cached
+  },
+  others: {
+    type: "boolean",
+    description: PARAM_DESCRIPTIONS.others
+  },
+  ignored: {
+    type: "boolean",
+    description: PARAM_DESCRIPTIONS.ignored
+  }
+};
+var editItemSchema = {
+  type: "object",
+  additionalProperties: false,
+  minProperties: 1,
+  maxProperties: 1,
+  properties: {
+    set_line: {
+      type: "object",
+      additionalProperties: false,
+      required: ["anchor", "new_text"],
+      properties: {
+        anchor: { type: "string", description: PARAM_DESCRIPTIONS.anchor },
+        new_text: { type: "string", description: PARAM_DESCRIPTIONS.newTextLine }
+      },
+      description: PARAM_DESCRIPTIONS.setLine
+    },
+    replace_lines: {
+      type: "object",
+      additionalProperties: false,
+      required: ["start_anchor", "end_anchor", "new_text"],
+      properties: {
+        start_anchor: { type: "string", description: PARAM_DESCRIPTIONS.startAnchor },
+        end_anchor: { type: "string", description: PARAM_DESCRIPTIONS.endAnchor },
+        new_text: { type: "string", description: PARAM_DESCRIPTIONS.newTextRange }
+      },
+      description: PARAM_DESCRIPTIONS.replaceLines
+    },
+    insert_after: {
+      type: "object",
+      additionalProperties: false,
+      required: ["anchor", "new_text"],
+      properties: {
+        anchor: { type: "string", description: PARAM_DESCRIPTIONS.insertAnchor },
+        new_text: { type: "string", description: PARAM_DESCRIPTIONS.newTextInsert }
+      },
+      description: PARAM_DESCRIPTIONS.insertAfter
+    },
+    replace: {
+      type: "object",
+      additionalProperties: false,
+      required: ["old_text", "new_text"],
+      properties: {
+        old_text: { type: "string", description: PARAM_DESCRIPTIONS.oldText },
+        new_text: { type: "string", description: PARAM_DESCRIPTIONS.newText },
+        all: { type: "boolean", description: PARAM_DESCRIPTIONS.all }
+      },
+      description: PARAM_DESCRIPTIONS.replace
+    },
+    replace_symbol: {
+      type: "object",
+      additionalProperties: false,
+      required: ["symbol", "new_body"],
+      properties: {
+        symbol: { type: "string", description: PARAM_DESCRIPTIONS.symbol },
+        new_body: { type: "string", description: PARAM_DESCRIPTIONS.newBody }
+      },
+      description: PARAM_DESCRIPTIONS.replaceSymbol
+    }
+  },
+  description: PARAM_DESCRIPTIONS.editVariant
+};
+var TOOL_CONTRACTS = [
+  {
+    name: "read",
+    title: "Read anchored text",
+    description: TOOL_DESCRIPTIONS.read,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: PARAM_DESCRIPTIONS.path },
+        offset: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.offset },
+        limit: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.readLimit },
+        symbol: { type: "string", description: PARAM_DESCRIPTIONS.symbolRead },
+        bundle: {
+          type: "string",
+          enum: ["local"],
+          description: PARAM_DESCRIPTIONS.bundle
+        },
+        image: {
+          type: "string",
+          enum: [...VISION_MODES],
+          description: PARAM_DESCRIPTIONS.image
+        }
+      },
+      required: ["path"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "edit",
+    title: "Hash-verified edit",
+    description: TOOL_DESCRIPTIONS.edit,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: PARAM_DESCRIPTIONS.path },
+        edits: {
+          type: "array",
+          minItems: 1,
+          description: PARAM_DESCRIPTIONS.edits,
+          items: editItemSchema
+        },
+        language: { type: "string", description: PARAM_DESCRIPTIONS.languageSymbol },
+        apply: { type: "boolean", description: PARAM_DESCRIPTIONS.apply },
+        planHash: { type: "string", description: PARAM_DESCRIPTIONS.planHash },
+        postEditVerify: { type: "boolean", description: PARAM_DESCRIPTIONS.postEditVerify }
+      },
+      required: ["path", "edits"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "write",
+    title: "Write file",
+    description: TOOL_DESCRIPTIONS.write,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: PARAM_DESCRIPTIONS.path },
+        content: { type: "string", description: PARAM_DESCRIPTIONS.content }
+      },
+      required: ["path", "content"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "grep",
+    title: "Text search",
+    description: TOOL_DESCRIPTIONS.grep,
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: PARAM_DESCRIPTIONS.grepPattern },
+        path: { type: "string", description: PARAM_DESCRIPTIONS.searchPath },
+        glob: { type: "string", description: PARAM_DESCRIPTIONS.glob },
+        ignoreCase: { type: "boolean", description: PARAM_DESCRIPTIONS.ignoreCase },
+        literal: { type: "boolean", description: PARAM_DESCRIPTIONS.literal },
+        context: { type: "integer", minimum: 0, description: PARAM_DESCRIPTIONS.context },
+        limit: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.matchLimit },
+        summary: { type: "boolean", description: PARAM_DESCRIPTIONS.summary },
+        scope: {
+          type: "string",
+          enum: ["symbol"],
+          description: PARAM_DESCRIPTIONS.grepScope
+        },
+        scopeContext: {
+          type: "integer",
+          minimum: 0,
+          description: PARAM_DESCRIPTIONS.scopeContext
+        }
+      },
+      required: ["pattern"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "digest",
+    title: "Digest source",
+    description: TOOL_DESCRIPTIONS.digest,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: PARAM_DESCRIPTIONS.path },
+        select: { type: "string", description: PARAM_DESCRIPTIONS.select },
+        at: { type: "string", description: PARAM_DESCRIPTIONS.at },
+        end: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.end },
+        limit: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.limit },
+        language: { type: "string", description: PARAM_DESCRIPTIONS.languageOverride },
+        visionMode: {
+          type: "string",
+          enum: [...VISION_MODES],
+          description: PARAM_DESCRIPTIONS.visionModeDigest
+        },
+        visionLevel: {
+          type: "string",
+          enum: [...VISION_LEVELS],
+          description: PARAM_DESCRIPTIONS.visionLevel
+        }
+      },
+      required: ["path"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "view",
+    title: "View document",
+    description: TOOL_DESCRIPTIONS.view,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: PARAM_DESCRIPTIONS.path },
+        node: { type: "string", description: PARAM_DESCRIPTIONS.node },
+        page: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.page },
+        kind: {
+          type: "string",
+          enum: [...DOCUMENT_NODE_KINDS],
+          description: PARAM_DESCRIPTIONS.kind
+        },
+        depth: { type: "integer", minimum: 0, description: PARAM_DESCRIPTIONS.depth },
+        outline: { type: "boolean", description: PARAM_DESCRIPTIONS.outline },
+        visionMode: {
+          type: "string",
+          enum: [...VISION_ANALYSIS_MODES],
+          description: PARAM_DESCRIPTIONS.visionModeView
+        },
+        visionLevel: {
+          type: "string",
+          enum: [...VISION_LEVELS],
+          description: PARAM_DESCRIPTIONS.visionLevel
+        }
+      },
+      required: ["path"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "search",
+    title: "AST search",
+    description: TOOL_DESCRIPTIONS.search,
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: PARAM_DESCRIPTIONS.pattern },
+        path: { type: "string", description: PARAM_DESCRIPTIONS.searchPath },
+        language: { type: "string", description: PARAM_DESCRIPTIONS.language },
+        ...gitFlagsSchema
+      },
+      required: ["pattern"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "def",
+    title: "Find definition",
+    description: TOOL_DESCRIPTIONS.def,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: PARAM_DESCRIPTIONS.name },
+        path: { type: "string", description: PARAM_DESCRIPTIONS.searchPath },
+        language: { type: "string", description: PARAM_DESCRIPTIONS.language },
+        ...gitFlagsSchema
+      },
+      required: ["name"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "refs",
+    title: "Find references",
+    description: TOOL_DESCRIPTIONS.refs,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: PARAM_DESCRIPTIONS.refsName },
+        path: { type: "string", description: PARAM_DESCRIPTIONS.searchPath },
+        language: { type: "string", description: PARAM_DESCRIPTIONS.language },
+        scope: { type: "boolean", description: PARAM_DESCRIPTIONS.scope },
+        line: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.line },
+        column: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.column },
+        ...gitFlagsSchema
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "rename",
+    title: "Rename symbol",
+    description: TOOL_DESCRIPTIONS.rename,
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: PARAM_DESCRIPTIONS.path },
+        line: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.renameLine },
+        column: { type: "integer", minimum: 1, description: PARAM_DESCRIPTIONS.column },
+        to: { type: "string", description: PARAM_DESCRIPTIONS.to },
+        workspace: { type: "boolean", description: PARAM_DESCRIPTIONS.workspace },
+        apply: { type: "boolean", description: PARAM_DESCRIPTIONS.apply },
+        planHash: { type: "string", description: PARAM_DESCRIPTIONS.planHash }
+      },
+      required: ["path", "line", "to"],
+      additionalProperties: false
+    }
+  }
+];
+// src/validation.ts
+function validateGitSelection(input) {
+  if (input.ignored && !input.others) {
+    return { ok: false, error: "ignored requires others=true" };
+  }
+  return { ok: true };
+}
+function validateRefsNameVsScope(input) {
+  if (input.scope) {
+    if (input.line === undefined) {
+      return { ok: false, error: "scope requires line" };
+    }
+    return { ok: true };
+  }
+  if (input.line !== undefined || input.column !== undefined) {
+    return { ok: false, error: "line/column require scope=true" };
+  }
+  if (typeof input.name !== "string" || input.name.length === 0) {
+    return { ok: false, error: "name is required when scope is not set" };
+  }
+  return { ok: true };
+}
+function validateVisionLevelVsMode(input) {
+  if (input.outline && (input.visionMode !== undefined || input.visionLevel !== undefined)) {
+    return { ok: false, error: "Cannot combine outline with visionMode or visionLevel" };
+  }
+  if (input.visionLevel !== undefined && input.visionMode === undefined) {
+    return { ok: false, error: "visionLevel requires visionMode" };
+  }
+  return { ok: true };
+}
+function validateExactlyOneEditVariant(edits) {
+  if (!Array.isArray(edits) || edits.length === 0) {
+    return { ok: false, error: "edits must contain at least one edit" };
+  }
+  const normalized = [];
+  for (let index = 0;index < edits.length; index++) {
+    const item = edits[index];
+    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);
+  }
+  return { ok: true, edits: normalized };
+}
+// src/argv.ts
+function buildLineLocation(line, column) {
+  return column === undefined ? `line:${line}` : `line:${line}:${column}`;
+}
+function appendGitSelectionArgs(args, input) {
+  const validated = validateGitSelection(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(","));
+  }
+  return args;
+}
+function pushOptionalString(args, flag, value) {
+  if (value !== undefined)
+    args.push(flag, value);
+}
+function pushOptionalNumber(args, flag, value) {
+  if (value !== undefined)
+    args.push(flag, String(value));
+}
+function appendApplyAndPlanHash(args, input) {
+  const order = input.flagOrder ?? "apply-first";
+  if (order === "plan-hash-first") {
+    pushOptionalString(args, "--plan-hash", input.planHash);
+    if (input.apply)
+      args.push("--apply");
+    return args;
+  }
+  if (input.apply)
+    args.push("--apply");
+  pushOptionalString(args, "--plan-hash", input.planHash);
+  return args;
+}
+function selectArg(select) {
+  if (select === undefined)
+    return;
+  return Array.isArray(select) ? select.join(",") : select;
+}
+function buildDigestArgs(input) {
+  const vision = validateVisionLevelVsMode({
+    visionMode: input.visionMode,
+    visionLevel: input.visionLevel
+  });
+  if (!vision.ok)
+    throw new Error(vision.error);
+  const args = [];
+  if (input.readseekDir !== undefined)
+    args.push("--readseek-dir", input.readseekDir);
+  args.push("digest", input.path);
+  const select = selectArg(input.select);
+  if (select !== undefined)
+    args.push("--select", select);
+  pushOptionalString(args, "--at", input.at);
+  pushOptionalNumber(args, "--end", input.end);
+  pushOptionalNumber(args, "--limit", input.limit);
+  pushOptionalString(args, "--language", input.language);
+  pushOptionalString(args, "--vision-mode", input.visionMode);
+  pushOptionalString(args, "--vision-level", input.visionLevel);
+  pushOptionalString(args, "--stdin-name", input.stdinName);
+  return args;
+}
+function buildViewArgs(input) {
+  const vision = validateVisionLevelVsMode({
+    visionMode: input.visionMode,
+    visionLevel: input.visionLevel,
+    outline: input.outline
+  });
+  if (!vision.ok)
+    throw new Error(vision.error);
+  const args = [];
+  if (input.readseekDir !== undefined)
+    args.push("--readseek-dir", input.readseekDir);
+  args.push("view", input.path);
+  if (input.format !== undefined)
+    args.push("--format", input.format);
+  pushOptionalString(args, "--node", input.node);
+  pushOptionalNumber(args, "--page", input.page);
+  pushOptionalString(args, "--kind", input.kind);
+  pushOptionalNumber(args, "--depth", input.depth);
+  if (input.outline)
+    args.push("--outline");
+  pushOptionalString(args, "--vision-mode", input.visionMode);
+  pushOptionalString(args, "--vision-level", input.visionLevel);
+  return args;
+}
+function buildSearchArgs(input) {
+  const args = ["search", input.path, input.pattern];
+  pushOptionalString(args, "--language", input.language);
+  return appendGitSelectionArgs(args, input);
+}
+function buildDefArgs(input) {
+  const args = ["def", input.path];
+  if (input.format !== undefined)
+    args.push("--format", input.format);
+  args.push(input.name);
+  pushOptionalString(args, "--language", input.language);
+  return appendGitSelectionArgs(args, input);
+}
+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) {
+    args.push(input.name);
+  }
+  if (input.format !== undefined)
+    args.push("--format", input.format);
+  pushOptionalString(args, "--language", input.language);
+  return appendGitSelectionArgs(args, input);
+}
+function buildEditArgs(input) {
+  const args = ["edit", input.path];
+  appendApplyAndPlanHash(args, {
+    apply: input.apply,
+    planHash: input.planHash,
+    flagOrder: input.flagOrder ?? "apply-first"
+  });
+  pushOptionalString(args, "--language", input.language);
+  if (input.requestFromStdin)
+    args.push("--request", "-");
+  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);
+  appendApplyAndPlanHash(args, {
+    apply: input.apply,
+    planHash: input.planHash,
+    flagOrder: input.flagOrder ?? "plan-hash-first"
+  });
+  pushOptionalString(args, "--language", input.language);
+  return appendGitSelectionArgs(args, input);
+}
+// src/platform.ts
+import { createRequire } from "node:module";
+import path from "node:path";
+var READSEEK_PLATFORM_PACKAGES = {
+  "darwin-arm64": "@jarkkojs/readseek-darwin-arm64",
+  "linux-arm64": "@jarkkojs/readseek-linux-arm64",
+  "linux-x64": "@jarkkojs/readseek-linux-x64",
+  "win32-x64": "@jarkkojs/readseek-win32-x64"
+};
+var resolveFromPackage = createRequire(import.meta.url).resolve;
+function readSeekBinaryName(platform = process.platform) {
+  return platform === "win32" ? "readseek.exe" : "readseek";
+}
+function readSeekPlatformKey(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`;
+}
+function resolveReadSeekBinaryFromPackages(resolver = resolveFromPackage, options = {}) {
+  const resolve = typeof resolver === "function" ? resolver : resolver.resolve.bind(resolver);
+  const platform = options.platform ?? process.platform;
+  const arch = options.arch ?? process.arch;
+  const key = readSeekPlatformKey(platform, arch);
+  const platformPackage = READSEEK_PLATFORM_PACKAGES[key];
+  if (!platformPackage) {
+    const supported = Object.keys(READSEEK_PLATFORM_PACKAGES).join(", ");
+    throw new Error(`@jarkkojs/readseek ships no binary for ${key}; it supports ${supported}`);
+  }
+  const metaPackage = options.metaPackage ?? "@jarkkojs/readseek";
+  const metaPackageJson = resolve(`${metaPackage}/package.json`);
+  const metaPackageDir = path.dirname(metaPackageJson);
+  const packageJsonPath = resolve(`${platformPackage}/package.json`, {
+    paths: [metaPackageDir]
+  });
+  return path.join(path.dirname(packageJsonPath), "bin", readSeekBinaryName(platform));
+}
+// src/json.ts
+var READSEEK_USAGE_HINT = /\n\s*Run readseek(?: [\w-]+)* --help for more information\.?\s*$/;
+function cleanReadSeekErrorText(stderr) {
+  return stderr.replace(READSEEK_USAGE_HINT, "").replace(/^error:\s*/i, "").replace(/\s*\n\s*/g, " ").trim();
+}
+function parseReadSeekJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    const preview = stdout.trim().slice(0, 200);
+    throw new Error(`readseek returned invalid JSON: ${preview}`);
+  }
+}
+// src/process.ts
+var DEFAULT_READSEEK_TIMEOUT_MS = 120000;
+var DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+function resolveProcessLimits(options = {}) {
+  return {
+    timeoutMs: options.timeoutMs ?? DEFAULT_READSEEK_TIMEOUT_MS,
+    maxOutputBytes: options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
+    cancelable: options.cancelable !== false
+  };
+}
+function readSeekCancellationError(signal) {
+  const reason = signal?.reason;
+  return reason instanceof Error && reason.name !== "AbortError" ? reason : new Error("readseek cancelled");
+}
+function failureFromProcessResult(result, options = {}) {
+  if (options.overflow) {
+    return new Error(`readseek ${options.overflow} exceeded the ${options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES}-byte output limit`);
+  }
+  if (options.timedOut) {
+    return new Error(`readseek timed out after ${options.timeoutMs ?? DEFAULT_READSEEK_TIMEOUT_MS} ms`);
+  }
+  const cleaned = cleanReadSeekErrorText(result.stderr);
+  if (cleaned)
+    return new Error(cleaned);
+  if (result.signal)
+    return new Error(`readseek killed by signal ${result.signal}`);
+  return new Error(`readseek exited with status ${result.exitCode}`);
+}
+function ensureSuccessfulStdout(result) {
+  if (result.exitCode === 0)
+    return result.stdout;
+  throw failureFromProcessResult(result);
+}
+function parseSuccessfulJson(result) {
+  return parseReadSeekJson(ensureSuccessfulStdout(result));
+}
+// src/process-node.ts
+import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+function attachBoundedStream(stream, maxOutputBytes, onOverflow) {
+  const decoder = new StringDecoder("utf8");
+  let text = "";
+  let bytes = 0;
+  let overflowed = false;
+  stream.on("data", (chunk) => {
+    if (overflowed)
+      return;
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    bytes += buffer.length;
+    if (bytes > maxOutputBytes) {
+      overflowed = true;
+      onOverflow();
+      return;
+    }
+    text += decoder.write(buffer);
+  });
+  return {
+    text: () => text + decoder.end()
+  };
+}
+async function runReadSeekNode(binaryPath, args, options = {}) {
+  const limits = resolveProcessLimits(options);
+  if (limits.cancelable && options.signal?.aborted) {
+    throw readSeekCancellationError(options.signal);
+  }
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    let child;
+    let timer;
+    const finish = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      if (timer !== undefined)
+        clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      resolve(result);
+    };
+    const fail = (error) => {
+      if (settled)
+        return;
+      settled = true;
+      if (timer !== undefined)
+        clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    const terminate = (error) => {
+      if (settled)
+        return;
+      fail(error);
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+    };
+    const onAbort = () => {
+      terminate(readSeekCancellationError(options.signal));
+    };
+    try {
+      child = spawn(binaryPath, [...args], {
+        cwd: options.cwd,
+        env: process.env,
+        shell: false,
+        stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+        windowsHide: true
+      });
+    } catch (error) {
+      fail(error);
+      return;
+    }
+    const stdout = attachBoundedStream(child.stdout, limits.maxOutputBytes, () => {
+      terminate(failureFromProcessResult({ stdout: "", stderr: "", exitCode: null, signal: null }, { overflow: "stdout", maxOutputBytes: limits.maxOutputBytes }));
+    });
+    const stderr = attachBoundedStream(child.stderr, limits.maxOutputBytes, () => {
+      terminate(failureFromProcessResult({ stdout: "", stderr: "", exitCode: null, signal: null }, { overflow: "stderr", maxOutputBytes: limits.maxOutputBytes }));
+    });
+    timer = setTimeout(() => {
+      terminate(failureFromProcessResult({ stdout: "", stderr: "", exitCode: null, signal: null }, { timedOut: true, timeoutMs: limits.timeoutMs }));
+    }, limits.timeoutMs);
+    timer.unref?.();
+    if (limits.cancelable && options.signal) {
+      options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    if (options.stdin !== undefined) {
+      child.stdin.on("error", (error) => {
+        if (error.code !== "EPIPE")
+          fail(error);
+      });
+      child.stdin.end(options.stdin, "utf8");
+    }
+    child.on("error", fail);
+    child.on("close", (code, signal) => {
+      finish({
+        stdout: stdout.text(),
+        stderr: stderr.text(),
+        exitCode: code,
+        signal
+      });
+    });
+  });
+}
+async function runReadSeekNodeText(binaryPath, args, options = {}) {
+  return ensureSuccessfulStdout(await runReadSeekNode(binaryPath, args, options));
+}
+async function runReadSeekNodeJson(binaryPath, args, options = {}) {
+  return parseSuccessfulJson(await runReadSeekNode(binaryPath, args, options));
+}
+// src/process-bun.ts
+function getBunSpawn() {
+  const bunGlobal = globalThis;
+  const spawn2 = bunGlobal.Bun?.spawn;
+  if (typeof spawn2 !== "function") {
+    throw new Error("Bun.spawn is unavailable in this runtime");
+  }
+  return spawn2;
+}
+async function readBoundedText(stream, streamName, maxOutputBytes, onOverflow) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let totalBytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      totalBytes += value.byteLength;
+      if (totalBytes > maxOutputBytes) {
+        onOverflow();
+        await reader.cancel().catch(() => {
+          return;
+        });
+        throw failureFromProcessResult({ stdout: "", stderr: "", exitCode: null, signal: null }, { overflow: streamName, maxOutputBytes });
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return new TextDecoder().decode(bytes);
+}
+async function runReadSeekBun(binaryPath, args, options = {}) {
+  const limits = resolveProcessLimits(options);
+  if (limits.cancelable && options.signal?.aborted) {
+    throw readSeekCancellationError(options.signal);
+  }
+  const spawn2 = getBunSpawn();
+  const stdin = options.stdin === undefined ? undefined : new TextEncoder().encode(options.stdin);
+  const spawnOptions = {
+    cwd: options.cwd,
+    env: process.env,
+    stderr: "pipe",
+    stdin,
+    stdout: "pipe"
+  };
+  const child = spawn2([binaryPath, ...args], limits.cancelable && options.signal ? { ...spawnOptions, killSignal: "SIGKILL", signal: options.signal } : spawnOptions);
+  const killForOverflow = () => {
+    try {
+      child.kill("SIGKILL");
+    } catch {}
+  };
+  let timeout;
+  const timeoutResult = new Promise((_resolve, reject) => {
+    timeout = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+      reject(failureFromProcessResult({ stdout: "", stderr: "", exitCode: null, signal: null }, { timedOut: true, timeoutMs: limits.timeoutMs }));
+    }, limits.timeoutMs);
+    timeout.unref?.();
+  });
+  const pending = Promise.all([
+    readBoundedText(child.stdout, "stdout", limits.maxOutputBytes, killForOverflow),
+    readBoundedText(child.stderr, "stderr", limits.maxOutputBytes, killForOverflow),
+    child.exited
+  ]);
+  try {
+    const [stdout, stderr, exitCode] = await Promise.race([pending, timeoutResult]);
+    if (limits.cancelable && options.signal?.aborted)
+      throw readSeekCancellationError(options.signal);
+    return { stdout, stderr, exitCode, signal: null };
+  } finally {
+    if (timeout !== undefined)
+      clearTimeout(timeout);
+  }
+}
+async function runReadSeekBunText(binaryPath, args, options = {}) {
+  return ensureSuccessfulStdout(await runReadSeekBun(binaryPath, args, options));
+}
+async function runReadSeekBunJson(binaryPath, args, options = {}) {
+  return parseSuccessfulJson(await runReadSeekBun(binaryPath, args, options));
+}
+export {
+  validateVisionLevelVsMode,
+  validateRefsNameVsScope,
+  validateGitSelection,
+  validateExactlyOneEditVariant,
+  runReadSeekNodeText,
+  runReadSeekNodeJson,
+  runReadSeekNode,
+  runReadSeekBunText,
+  runReadSeekBunJson,
+  runReadSeekBun,
+  resolveReadSeekBinaryFromPackages,
+  resolveProcessLimits,
+  renderToolDescription,
+  readSeekPlatformKey,
+  readSeekBinaryName,
+  parseSuccessfulJson,
+  parseReadSeekJson,
+  failureFromProcessResult,
+  ensureSuccessfulStdout,
+  cleanReadSeekErrorText,
+  buildViewArgs,
+  buildSearchArgs,
+  buildRenameArgs,
+  buildRefsArgs,
+  buildLineLocation,
+  buildEditArgs,
+  buildDigestArgs,
+  buildDefArgs,
+  appendGitSelectionArgs,
+  appendApplyAndPlanHash,
+  VISION_MODES,
+  VISION_LEVELS,
+  VISION_ANALYSIS_MODES,
+  TOOL_NAMES,
+  TOOL_DESCRIPTIONS,
+  TOOL_CONTRACTS,
+  READSEEK_PLATFORM_PACKAGES,
+  PARAM_DESCRIPTIONS,
+  GIT_SELECTION_FLAGS,
+  EDIT_VARIANTS,
+  DOCUMENT_NODE_KINDS,
+  DIGEST_FACETS,
+  DEFAULT_READSEEK_TIMEOUT_MS,
+  DEFAULT_MAX_OUTPUT_BYTES
+};