@jarkkojs/readseek-api 0.12.0 → 0.12.1

package/dist/argv.d.ts

@@ -69,11 +69,18 @@ export type SearchArgsInput = AccessArgsInput & GitScopeInput & {
     limit?: number;
     noAnchors?: boolean;
 };
-export type GrepArgsInput = {
-    path: string;
-    text: string;
+export type GrepArgsInput = GitScopeInput & {
+    pattern: string;
+    path?: string;
+    glob?: string;
+    ignoreCase?: boolean;
+    literal?: boolean;
+    context?: number;
     limit?: number;
-} & GitScopeInput;
+    summary?: boolean;
+    scope?: "symbol";
+    scopeContext?: number;
+};
 export type DefArgsInput = {
     path: string;
     name: string;

package/dist/client-output.d.ts

@@ -541,37 +541,138 @@ declare const DocumentOutput: import("@sinclair/typebox").TObject<{
         ocr_requested: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     }>>;
 }>;
-declare const TextSearchOutput: import("@sinclair/typebox").TObject<{
+declare const GrepLineSchema: import("@sinclair/typebox").TObject<{
+    line: import("@sinclair/typebox").TInteger;
+    hash: import("@sinclair/typebox").TString;
     text: import("@sinclair/typebox").TString;
-    mode: import("@sinclair/typebox").TLiteral<"literal">;
+    kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
+}>;
+declare const GrepHitSchema: import("@sinclair/typebox").TObject<{
+    line: import("@sinclair/typebox").TInteger;
+    column: import("@sinclair/typebox").TInteger;
+    start_byte: import("@sinclair/typebox").TInteger;
+    end_byte: import("@sinclair/typebox").TInteger;
+    text: import("@sinclair/typebox").TString;
+    anchor: import("@sinclair/typebox").TString;
+}>;
+declare const GrepSymbolSchema: import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TString;
+    kind: import("@sinclair/typebox").TString;
+    start_line: import("@sinclair/typebox").TInteger;
+    end_line: import("@sinclair/typebox").TInteger;
+    lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        line: import("@sinclair/typebox").TInteger;
+        hash: import("@sinclair/typebox").TString;
+        text: import("@sinclair/typebox").TString;
+        kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
+    }>>;
+}>;
+declare const GrepSourceResultSchema: import("@sinclair/typebox").TObject<{
+    file: import("@sinclair/typebox").TString;
+    file_hash: import("@sinclair/typebox").TString;
+    language: import("@sinclair/typebox").TString;
+    total_matches: import("@sinclair/typebox").TInteger;
+    returned_matches: import("@sinclair/typebox").TInteger;
+    hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        line: import("@sinclair/typebox").TInteger;
+        column: import("@sinclair/typebox").TInteger;
+        start_byte: import("@sinclair/typebox").TInteger;
+        end_byte: import("@sinclair/typebox").TInteger;
+        text: import("@sinclair/typebox").TString;
+        anchor: import("@sinclair/typebox").TString;
+    }>>;
+    lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        line: import("@sinclair/typebox").TInteger;
+        hash: import("@sinclair/typebox").TString;
+        text: import("@sinclair/typebox").TString;
+        kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
+    }>>;
+    symbols: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        name: import("@sinclair/typebox").TString;
+        kind: import("@sinclair/typebox").TString;
+        start_line: import("@sinclair/typebox").TInteger;
+        end_line: import("@sinclair/typebox").TInteger;
+        lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            line: import("@sinclair/typebox").TInteger;
+            hash: import("@sinclair/typebox").TString;
+            text: import("@sinclair/typebox").TString;
+            kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
+        }>>;
+    }>>;
+}>;
+declare const GrepDocumentHitSchema: import("@sinclair/typebox").TObject<{
+    node_id: import("@sinclair/typebox").TString;
+    kind: import("@sinclair/typebox").TString;
+    snippet: import("@sinclair/typebox").TString;
+    line: import("@sinclair/typebox").TInteger;
+    page: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+declare const GrepDocumentResultSchema: import("@sinclair/typebox").TObject<{
+    file: import("@sinclair/typebox").TString;
+    content_hash: import("@sinclair/typebox").TString;
+    total_matches: import("@sinclair/typebox").TInteger;
+    returned_matches: import("@sinclair/typebox").TInteger;
+    hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        node_id: import("@sinclair/typebox").TString;
+        kind: import("@sinclair/typebox").TString;
+        snippet: import("@sinclair/typebox").TString;
+        line: import("@sinclair/typebox").TInteger;
+        page: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    }>>;
+}>;
+declare const GrepOutputSchema: import("@sinclair/typebox").TObject<{
+    pattern: import("@sinclair/typebox").TString;
+    mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"regex">, import("@sinclair/typebox").TLiteral<"literal">]>;
+    ignore_case: import("@sinclair/typebox").TBoolean;
+    summary: import("@sinclair/typebox").TBoolean;
     total_matches: import("@sinclair/typebox").TInteger;
     returned_matches: import("@sinclair/typebox").TInteger;
     truncated: import("@sinclair/typebox").TBoolean;
+    count_unit: import("@sinclair/typebox").TLiteral<"lines">;
+    scope: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TLiteral<"symbol">>;
     results: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         file: import("@sinclair/typebox").TString;
         file_hash: import("@sinclair/typebox").TString;
-        matches: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        language: import("@sinclair/typebox").TString;
+        total_matches: import("@sinclair/typebox").TInteger;
+        returned_matches: import("@sinclair/typebox").TInteger;
+        hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
             line: import("@sinclair/typebox").TInteger;
             column: import("@sinclair/typebox").TInteger;
+            start_byte: import("@sinclair/typebox").TInteger;
+            end_byte: import("@sinclair/typebox").TInteger;
+            text: import("@sinclair/typebox").TString;
+            anchor: import("@sinclair/typebox").TString;
+        }>>;
+        lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            line: import("@sinclair/typebox").TInteger;
+            hash: import("@sinclair/typebox").TString;
             text: import("@sinclair/typebox").TString;
+            kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
+        }>>;
+        symbols: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            name: import("@sinclair/typebox").TString;
+            kind: import("@sinclair/typebox").TString;
             start_line: import("@sinclair/typebox").TInteger;
             end_line: import("@sinclair/typebox").TInteger;
-            start_byte: import("@sinclair/typebox").TInteger;
-            end_byte: import("@sinclair/typebox").TInteger;
-            hashlines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
                 line: import("@sinclair/typebox").TInteger;
                 hash: import("@sinclair/typebox").TString;
                 text: import("@sinclair/typebox").TString;
+                kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
             }>>;
         }>>;
     }>>;
     documents: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         file: import("@sinclair/typebox").TString;
         content_hash: import("@sinclair/typebox").TString;
+        total_matches: import("@sinclair/typebox").TInteger;
+        returned_matches: import("@sinclair/typebox").TInteger;
         hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
             node_id: import("@sinclair/typebox").TString;
             kind: import("@sinclair/typebox").TString;
             snippet: import("@sinclair/typebox").TString;
+            line: import("@sinclair/typebox").TInteger;
             page: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
         }>>;
     }>>;
@@ -599,7 +700,13 @@ export type ReadSeekDocumentNode = Static<typeof DocumentNode>;
 export type ReadSeekDocumentAsset = Static<typeof DocumentAsset>;
 export type ReadSeekDocumentVision = Static<typeof DocumentVision>;
 export type ReadSeekDocumentOutput = Static<typeof DocumentOutput>;
-export type ReadSeekTextSearchOutput = Static<typeof TextSearchOutput>;
+export type GrepOutput = Static<typeof GrepOutputSchema>;
+export type GrepLine = Static<typeof GrepLineSchema>;
+export type GrepHit = Static<typeof GrepHitSchema>;
+export type GrepSymbol = Static<typeof GrepSymbolSchema>;
+export type GrepSourceResult = Static<typeof GrepSourceResultSchema>;
+export type GrepDocumentHit = Static<typeof GrepDocumentHitSchema>;
+export type GrepDocumentResult = Static<typeof GrepDocumentResultSchema>;
 export type ReadSeekRulesOutput = Static<typeof RulesOutput>;
 export interface ReadSeekSourceContentOutput {
     metadata: ReadSeekDetection;
@@ -614,7 +721,7 @@ export type ReadSeekStructureOutputEnvelope = {
 export declare function parseDocumentOutput(value: unknown): ReadSeekDocumentOutput;
 export declare function parseContentOutput(value: unknown): ReadSeekContentOutput;
 export declare function parseStructureEnvelope(value: unknown): ReadSeekStructureOutputEnvelope;
-export declare function parseTextSearchOutput(value: unknown): ReadSeekTextSearchOutput;
+export declare function parseGrepOutput(value: unknown): GrepOutput;
 export declare function parseRulesOutput(value: unknown): ReadSeekRulesOutput;
 declare const SourceAssetsOutput: import("@sinclair/typebox").TObject<{
     file: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

package/dist/client.d.ts

@@ -22,7 +22,7 @@ export type ReadSeekCheckOptions = Options<argv.CheckArgsInput>;
 export type ReadSeekCaptionOptions = Options<argv.CaptionArgsInput>;
 export type ReadSeekVisionOptions = Options<argv.ObjectsArgsInput>;
 export type ReadSeekSearchOptions = Options<argv.SearchArgsInput>;
-export type ReadSeekGrepOptions = Options<argv.GrepArgsInput>;
+export type ReadSeekGrepParams = argv.GrepArgsInput & Omit<ReadSeekRunOptions, "vision">;
 export type ReadSeekDefOptions = Options<argv.DefArgsInput>;
 export type ReadSeekRefsOptions = Options<argv.RefsArgsInput>;
 export type ReadSeekEditOptions = Options<argv.EditArgsInput>;
@@ -49,7 +49,7 @@ export interface ReadSeekClient {
     objects(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
     ocr(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
     search(path: string, options: ReadSeekSearchOptions): Promise<output.ReadSeekSearchOutput>;
-    grep(path: string, options: ReadSeekGrepOptions): Promise<output.ReadSeekTextSearchOutput>;
+    grep(params: ReadSeekGrepParams): Promise<output.GrepOutput>;
     def(path: string, options: ReadSeekDefOptions): Promise<output.DefLocation[]>;
     refs(path: string, options: ReadSeekRefsOptions): Promise<output.ReadSeekReference[]>;
     edit(path: string, edits: unknown[], options?: ReadSeekEditOptions): Promise<output.EditOutput>;

package/dist/contract.d.ts

@@ -16,7 +16,7 @@ export declare const PARAM_DESCRIPTIONS: {
     readonly pattern: "AST pattern (ast-grep style), such as console.log($$$ARGS)";
     readonly patternContext: "Surrounding code context for sub-statement patterns";
     readonly selector: "Target AST node kind to extract from pattern context";
-    readonly grepPattern: "Regex pattern; set literal for exact text";
+    readonly grepPattern: "Native regex pattern; set literal for exact text. Empty regex matches every line; empty literal is invalid.";
     readonly name: "Qualified or unqualified symbol name";
     readonly refsName: "Identifier to find references for";
     readonly gitScope: "In a Git repository, which files to search: tracked, untracked, ignored (untracked plus ignored), or all. Defaults to tracked plus untracked.";
@@ -33,7 +33,6 @@ export declare const PARAM_DESCRIPTIONS: {
     readonly kind: "Restrict structure to this node kind";
     readonly outline: "Show outline of document hierarchy or source symbols";
     readonly noAnchors: "Omit source line anchors";
-    readonly text: "Literal native text query; adapter grep also supports regex via pattern";
     readonly edits: "Use set_line, replace_lines, insert_after, replace_symbol, or replace";
     readonly editVariant: "Exactly one nested edit variant";
     readonly setLine: "Replace one line: {\"set_line\":{\"anchor\":\"LINE:HASH\",\"new_text\":\"...\"}}";
@@ -65,9 +64,10 @@ export declare const PARAM_DESCRIPTIONS: {
     readonly literal: "Treat pattern literally";
     readonly context: "Surrounding lines for each match";
     readonly matchLimit: "Maximum matches to return";
+    readonly grepLimit: "Maximum matching lines to return; positive integer, defaults to 100";
     readonly summary: "Return per-file counts";
     readonly grepScope: "Group matches by enclosing symbol";
-    readonly scopeContext: "Context lines within each symbol";
+    readonly scopeContext: "Non-negative context lines within each symbol; requires scope: symbol";
 };
 export declare const TOOL_DESCRIPTIONS: {
     readonly show: "Read source, document content, or image descriptors without inference. Obtain fresh `LINE:HASH` anchors before edits; use at with a column for cursor context. Document results include typed nodes and cached asset paths.";
@@ -80,7 +80,7 @@ export declare const TOOL_DESCRIPTIONS: {
     readonly objects: "Explicitly infer object labels and bounding boxes using an installed model.";
     readonly ocr: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.";
     readonly search: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `grep` for text and regex.";
-    readonly grep: "Search text or regex and return edit-ready `LINE:HASH` anchors. Native CLI text is literal; adapters preserve regex, glob, context, summary, and symbol grouping.";
+    readonly grep: "Search with native regex or literal matching. Returns matching-line counts, source LINE:HASH anchors, and document node-local locations. Native glob, context, summary, limits, Git scope, and symbol grouping apply; default limit is 100 matching lines.";
     readonly def: "Find a symbol definition or declaration by qualified or unqualified name.";
     readonly refs: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.";
     readonly edit: "Edit existing files with fresh `LINE:HASH` anchors. Each edits item contains exactly one set_line, replace_lines, insert_after, replace_symbol, or replace object. Preview before applying a verified plan.";

package/dist/grep-presentation.d.ts

@@ -0,0 +1,3 @@
+import type { GrepOutput } from "./client-output.ts";
+/** Render native grep results without re-matching or reading source files. */
+export declare function renderGrepOutput(output: GrepOutput): string;

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export * from "./client.ts";
 export { serializeEditPlan } from "./edit-plan.ts";
 export * from "./hashline.ts";
 export * from "./show-presentation.ts";
+export * from "./grep-presentation.ts";
+export { parseGrepOutput } from "./client-output.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 } from "./error.ts";

package/dist/index.js

@@ -36,7 +36,7 @@ var PARAM_DESCRIPTIONS = {
   pattern: "AST pattern (ast-grep style), such as console.log($$$ARGS)",
   patternContext: "Surrounding code context for sub-statement patterns",
   selector: "Target AST node kind to extract from pattern context",
-  grepPattern: "Regex pattern; set literal for exact text",
+  grepPattern: "Native regex pattern; set literal for exact text. Empty regex matches every line; empty literal is invalid.",
   name: "Qualified or unqualified symbol name",
   refsName: "Identifier to find references for",
   gitScope: "In a Git repository, which files to search: tracked, untracked, ignored (untracked plus ignored), or all. Defaults to tracked plus untracked.",
@@ -53,7 +53,6 @@ var PARAM_DESCRIPTIONS = {
   kind: "Restrict structure to this node kind",
   outline: "Show outline of document hierarchy or source symbols",
   noAnchors: "Omit source line anchors",
-  text: "Literal native text query; adapter grep also supports regex via pattern",
   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":"..."}}',
@@ -85,9 +84,10 @@ var PARAM_DESCRIPTIONS = {
   literal: "Treat pattern literally",
   context: "Surrounding lines for each match",
   matchLimit: "Maximum matches to return",
+  grepLimit: "Maximum matching lines to return; positive integer, defaults to 100",
   summary: "Return per-file counts",
   grepScope: "Group matches by enclosing symbol",
-  scopeContext: "Context lines within each symbol"
+  scopeContext: "Non-negative context lines within each symbol; requires scope: symbol"
 };
 var TOOL_DESCRIPTIONS = {
   show: "Read source, document content, or image descriptors without inference. Obtain fresh `LINE:HASH` anchors before edits; use at with a column for cursor context. Document results include typed nodes and cached asset paths.",
@@ -100,7 +100,7 @@ var TOOL_DESCRIPTIONS = {
   objects: "Explicitly infer object labels and bounding boxes using an installed model.",
   ocr: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.",
   search: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `grep` for text and regex.",
-  grep: "Search text or regex and return edit-ready `LINE:HASH` anchors. Native CLI text is literal; adapters preserve regex, glob, context, summary, and symbol grouping.",
+  grep: "Search with native regex or literal matching. Returns matching-line counts, source LINE:HASH anchors, and document node-local locations. Native glob, context, summary, limits, Git scope, and symbol grouping apply; default limit is 100 matching lines.",
   def: "Find a symbol definition or declaration by qualified or unqualified name.",
   refs: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.",
   edit: "Edit existing files with fresh `LINE:HASH` anchors. Each edits item contains exactly one set_line, replace_lines, insert_after, replace_symbol, or replace object. Preview before applying a verified plan.",
@@ -208,7 +208,7 @@ var TOOL_CONTRACTS = [
   tool("objects", "Detect objects", { ...path, ...at, ...stdin, ...level }, ["path"]),
   tool("ocr", "Recognize text", { ...path, ...at, ...stdin, ...level }, ["path"]),
   tool("search", "Search AST nodes", { ...path, ...lang, ...stdin, ...limit, ...gitScopeSchema, ...noAnchors, pattern: string(PARAM_DESCRIPTIONS.pattern), context: string(PARAM_DESCRIPTIONS.patternContext), selector: string(PARAM_DESCRIPTIONS.selector), rule: string(PARAM_DESCRIPTIONS.rule) }, []),
-  tool("grep", "Search text", { ...path, ...limit, ...gitScopeSchema, text: string(PARAM_DESCRIPTIONS.text), pattern: string(PARAM_DESCRIPTIONS.grepPattern), glob: string(PARAM_DESCRIPTIONS.glob), ignoreCase: { type: "boolean", description: PARAM_DESCRIPTIONS.ignoreCase }, literal: { type: "boolean", description: PARAM_DESCRIPTIONS.literal }, context: integer(PARAM_DESCRIPTIONS.context, 0), summary: { type: "boolean", description: PARAM_DESCRIPTIONS.summary }, scope: { type: "string", enum: ["symbol"], description: PARAM_DESCRIPTIONS.grepScope }, scopeContext: integer(PARAM_DESCRIPTIONS.scopeContext, 0) }, []),
+  tool("grep", "Search text", { path: string(PARAM_DESCRIPTIONS.searchPath), limit: { ...integer(PARAM_DESCRIPTIONS.grepLimit), default: 100 }, ...gitScopeSchema, pattern: string(PARAM_DESCRIPTIONS.grepPattern), glob: string(PARAM_DESCRIPTIONS.glob), ignoreCase: { type: "boolean", description: PARAM_DESCRIPTIONS.ignoreCase }, literal: { type: "boolean", description: PARAM_DESCRIPTIONS.literal }, context: integer(PARAM_DESCRIPTIONS.context, 0), summary: { type: "boolean", description: PARAM_DESCRIPTIONS.summary }, scope: { type: "string", enum: ["symbol"], description: PARAM_DESCRIPTIONS.grepScope }, scopeContext: integer(PARAM_DESCRIPTIONS.scopeContext, 0) }, ["pattern"]),
   tool("def", "Find definitions", { ...path, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.name) }, ["name"]),
   tool("refs", "Find references", { ...path, ...at, ...lang, ...gitScopeSchema, ...noAnchors, name: string(PARAM_DESCRIPTIONS.refsName) }, []),
   tool("edit", "Hash-verified edit", { ...path, ...lang, ...gitScopeSchema, ...apply, edits: { type: "array", minItems: 1, items: editItemSchema, description: PARAM_DESCRIPTIONS.edits }, postEditVerify: { type: "boolean", description: PARAM_DESCRIPTIONS.postEditVerify } }, ["path", "edits"]),
@@ -236,7 +236,7 @@ var REPLACEABLE_TOOLS = [
   {
     tool: "grep",
     builtIn: "grep",
-    benefit: "it returns LINE:HASH anchors."
+    benefit: "it runs native regex/literal matching and returns source LINE:HASH anchors or document locations."
   },
   {
     tool: "write",
@@ -275,7 +275,7 @@ var PREFERENCE_LEADS = {
   show: "Preferred for reading source with anchors.",
   edit: "Preferred for editing existing text files with fresh LINE:HASH anchors.",
   write: "Preferred for creating or replacing a complete text file; returns LINE:HASH anchors.",
-  grep: "Preferred text/regex search; returns edit-ready LINE:HASH anchors.",
+  grep: "Preferred native text/regex search; returns edit-ready source LINE:HASH anchors and document node-local locations.",
   search: "Preferred for AST or structural code search with ast-grep-style patterns.",
   def: "Preferred for go-to-definition or declaration lookup by name.",
   refs: "Preferred for finding identifier-name matches or binding-specific references before `rename` or delete.",
@@ -286,7 +286,7 @@ var FALLBACK_TEMPLATES = {
   read: "Prefer `show` with fresh LINE:HASH anchors.",
   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.",
+  grep: "Prefer `grep` for native text/regex search with source anchors and document locations.",
   apply_patch: "Prefer `edit` for existing text files."
 };
 function resolveToolName(name, aliases = {}) {
@@ -367,6 +367,59 @@ function validateReferencesSelection(input) {
     return { ok: false, error: "exactly one of name or at is required" };
   return { ok: true };
 }
+function validateGrepParams(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, error: "grep params must be an object" };
+  }
+  const params = input;
+  const allowed = [
+    "pattern",
+    "path",
+    "glob",
+    "ignoreCase",
+    "literal",
+    "context",
+    "limit",
+    "summary",
+    "scope",
+    "scopeContext",
+    "gitScope",
+    "signal",
+    "stdin",
+    "timeoutMs",
+    "cancelable"
+  ];
+  if (Object.keys(params).some((key) => !allowed.includes(key)))
+    return { ok: false, error: "unknown grep parameter" };
+  if (typeof params.pattern !== "string")
+    return { ok: false, error: "grep requires a pattern string" };
+  if (params.literal === true && params.pattern.length === 0)
+    return { ok: false, error: "literal pattern must not be empty" };
+  for (const key of ["path", "glob"]) {
+    if (params[key] !== undefined && (typeof params[key] !== "string" || params[key].length === 0)) {
+      return { ok: false, error: `${key} must be a non-empty string` };
+    }
+  }
+  for (const key of ["ignoreCase", "literal", "summary"]) {
+    if (params[key] !== undefined && typeof params[key] !== "boolean")
+      return { ok: false, error: `${key} must be a boolean` };
+  }
+  for (const key of ["context", "limit", "scopeContext"]) {
+    const value = params[key];
+    const minimum = key === "limit" ? 1 : 0;
+    if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum)) {
+      return { ok: false, error: `${key} must be a ${minimum === 1 ? "positive" : "non-negative"} integer` };
+    }
+  }
+  if (params.scope !== undefined && params.scope !== "symbol")
+    return { ok: false, error: "scope must be symbol" };
+  if (params.scopeContext !== undefined && params.scope !== "symbol")
+    return { ok: false, error: "scopeContext requires scope" };
+  if (params.gitScope !== undefined && !GIT_SCOPES.includes(params.gitScope)) {
+    return { ok: false, error: "invalid gitScope" };
+  }
+  return { ok: true };
+}
 var VARIANT_FIELDS = {
   set_line: ["anchor", "new_text"],
   replace_lines: ["start_anchor", "end_anchor", "new_text"],
@@ -755,11 +808,29 @@ function buildSearchArgs(input) {
   return finish(args);
 }
 function buildGrepArgs(input) {
-  const args = start("grep", input);
-  args.push("--text", input.text);
-  limit2(args, input.limit);
+  const validated = validateGrepParams(input);
+  if (!validated.ok)
+    throw new Error(validated.error);
+  const args = ["grep", "--kdl", `--pattern=${input.pattern}`];
+  const needsPathTerminator = input.path !== undefined && input.path.startsWith("-") && input.path !== "-";
+  if (input.path !== undefined && !needsPathTerminator)
+    args.push(input.path);
+  if (input.literal)
+    args.push("--literal");
+  if (input.ignoreCase)
+    args.push("--ignore-case");
+  if (input.glob !== undefined)
+    args.push(`--glob=${input.glob}`);
+  pushOptionalNumber(args, "--context", input.context);
+  limit2(args, input.limit ?? 100);
+  if (input.summary)
+    args.push("--summary");
+  pushOptionalString(args, "--scope", input.scope);
+  pushOptionalNumber(args, "--scope-context", input.scopeContext);
   appendGitScopeArgs(args, input);
-  return finish(args);
+  if (input.path !== undefined && needsPathTerminator)
+    args.push("--", input.path);
+  return args;
 }
 function buildDefArgs(input) {
   const args = start("def", input);
@@ -1191,25 +1262,41 @@ var DocumentOutput = Type.Object({
   assets: Type.Array(DocumentAsset, { default: [] }),
   vision: Type.Array(DocumentVision, { default: [] })
 });
-var TextHit = Type.Object({
-  line: Int,
-  column: Int,
+var GrepCount = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+var GrepPosition = Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER });
+var GrepAnchor = Type.String({ pattern: "^[1-9][0-9]*:[0-9a-f]{6}$" });
+var GrepLineSchema = Type.Object({
+  line: GrepPosition,
+  hash: Type.String({ pattern: "^[0-9a-f]{6}$" }),
   text: Str,
-  start_line: Int,
-  end_line: Int,
-  start_byte: Int,
-  end_byte: Int,
-  hashlines: Hashlines
+  kind: Type.Union([Type.Literal("match"), Type.Literal("context")])
 });
-var DocumentHit = Type.Object({ node_id: Str, kind: Str, snippet: Str, page: OptInt });
-var TextSearchOutput = Type.Object({
-  text: Str,
-  mode: Type.Literal("literal"),
-  total_matches: Int,
-  returned_matches: Int,
+var GrepHitSchema = Type.Object({ line: GrepPosition, column: GrepPosition, start_byte: GrepCount, end_byte: GrepCount, text: Str, anchor: GrepAnchor });
+var GrepSymbolSchema = Type.Object({ name: Str, kind: Str, start_line: GrepPosition, end_line: GrepPosition, lines: Type.Array(GrepLineSchema) });
+var GrepSourceResultSchema = Type.Object({
+  file: Str,
+  file_hash: Str,
+  language: Str,
+  total_matches: GrepCount,
+  returned_matches: GrepCount,
+  hits: Type.Array(GrepHitSchema),
+  lines: Type.Array(GrepLineSchema),
+  symbols: Type.Array(GrepSymbolSchema)
+});
+var GrepDocumentHitSchema = Type.Object({ node_id: Str, kind: Str, snippet: Str, line: GrepPosition, page: Type.Optional(GrepPosition) });
+var GrepDocumentResultSchema = Type.Object({ file: Str, content_hash: Str, total_matches: GrepCount, returned_matches: GrepCount, hits: Type.Array(GrepDocumentHitSchema) });
+var GrepOutputSchema = Type.Object({
+  pattern: Str,
+  mode: Type.Union([Type.Literal("regex"), Type.Literal("literal")]),
+  ignore_case: Bool,
+  summary: Bool,
+  total_matches: GrepCount,
+  returned_matches: GrepCount,
   truncated: Bool,
-  results: Type.Array(Type.Object({ file: Str, file_hash: Str, matches: Type.Array(TextHit) })),
-  documents: Type.Array(Type.Object({ file: Str, content_hash: Str, hits: Type.Array(DocumentHit) }))
+  count_unit: Type.Literal("lines"),
+  scope: Type.Optional(Type.Literal("symbol")),
+  results: Type.Array(GrepSourceResultSchema),
+  documents: Type.Array(GrepDocumentResultSchema)
 });
 var RuleFinding = Type.Object({
   name: Str,
@@ -1254,8 +1341,35 @@ function parseStructureEnvelope(value) {
     throw new Error("invalid readseek structure: missing structure");
   return { ...output.metadata !== undefined ? { metadata: parseDetectOutput(output.metadata) } : {}, structure: parseStructureOutput(output.structure) };
 }
-function parseTextSearchOutput(value) {
-  return parse(TextSearchOutput, value, "text search output");
+function parseGrepOutput(value) {
+  const output = parse(GrepOutputSchema, value, "grep output");
+  const invalid = (message) => {
+    throw new Error(`invalid readseek grep output: ${message}`);
+  };
+  const groups = [...output.results, ...output.documents];
+  if (output.returned_matches > output.total_matches || groups.reduce((sum, group) => sum + group.total_matches, 0) !== output.total_matches || groups.reduce((sum, group) => sum + group.returned_matches, 0) !== output.returned_matches)
+    invalid("inconsistent counts");
+  for (const group of groups) {
+    if (group.total_matches === 0 || group.returned_matches > group.total_matches)
+      invalid("inconsistent file counts");
+    if (output.summary ? group.hits.length !== 0 : group.hits.length !== group.returned_matches)
+      invalid("inconsistent hit count");
+  }
+  for (const result of output.results) {
+    if (output.summary && (result.lines.length > 0 || result.symbols.length > 0))
+      invalid("summary contains display entries");
+    if (output.scope !== "symbol" && result.symbols.length > 0)
+      invalid("symbols require symbol scope");
+    for (const hit of result.hits) {
+      if (hit.end_byte < hit.start_byte || Number(hit.anchor.split(":")[0]) !== hit.line)
+        invalid("invalid hit span or anchor");
+    }
+    for (const symbol of result.symbols) {
+      if (symbol.end_line < symbol.start_line || symbol.lines.some((line) => line.line < symbol.start_line || line.line > symbol.end_line))
+        invalid("invalid symbol range");
+    }
+  }
+  return output;
 }
 function parseRulesOutput(value) {
   return parse(RulesOutput, value, "rules output");
@@ -1372,9 +1486,9 @@ function createReadSeekClient(runner) {
       const value = await runner.kdl(buildSearchArgs({ ...options, path }), runOptions(options));
       return parseSearchOutput(value);
     },
-    async grep(path, options) {
-      const value = await runner.kdl(buildGrepArgs({ ...options, path }), runOptions(options));
-      return parseTextSearchOutput(value);
+    async grep(params) {
+      const value = await runner.kdl(buildGrepArgs(params), runOptions(params));
+      return parseGrepOutput(value);
     },
     async def(path, options) {
       const value = await runner.kdl(buildDefArgs({ ...options, path }), runOptions(options));
@@ -1609,6 +1723,31 @@ function formatShowResult(presentation) {
 
 `);
 }
+// src/grep-presentation.ts
+function renderGrepOutput(output) {
+  const rendered = [`${output.returned_matches} of ${output.total_matches} matching lines${output.truncated ? " (truncated)" : ""}`];
+  const displayLine = (line) => `${line.line}:${line.hash}|${line.kind === "match" ? ">>" : "  "}${line.text}`;
+  for (const result of output.results) {
+    rendered.push(`${result.file}: ${result.total_matches} matching lines (${result.returned_matches} returned)`);
+    if (output.summary)
+      continue;
+    rendered.push(...result.lines.map(displayLine));
+    for (const symbol of result.symbols) {
+      rendered.push(`  ${symbol.kind} ${symbol.name} (${symbol.start_line}-${symbol.end_line})`);
+      rendered.push(...symbol.lines.map(displayLine));
+    }
+  }
+  for (const document of output.documents) {
+    rendered.push(`${document.file}: ${document.total_matches} matching lines (${document.returned_matches} returned)`);
+    if (output.summary)
+      continue;
+    for (const hit of document.hits) {
+      rendered.push(`  node:${hit.node_id}${hit.page === undefined ? "" : ` page:${hit.page}`} line:${hit.line} (${hit.kind}): ${hit.snippet}`);
+    }
+  }
+  return rendered.join(`
+`);
+}
 // src/platform.ts
 import { accessSync, constants as fsConstants, existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -1930,6 +2069,46 @@ function search(root) {
     }))
   };
 }
+function grepChildren(node, allowed) {
+  if (node.children.some((child) => !allowed.includes(child.name))) {
+    throw new Error(`invalid readseek KDL grep: unexpected child of ${node.name}`);
+  }
+}
+function grepLine(node) {
+  grepChildren(node, []);
+  const parsed = line(node);
+  if (requireProperty(node, "number") !== parsed.line)
+    throw new Error("invalid readseek KDL grep line number");
+  return { ...parsed, kind: requireProperty(node, "kind") };
+}
+function grep(root) {
+  grepChildren(root, ["match", "document"]);
+  return parseGrepOutput({
+    ...properties(root),
+    results: children(root, "match").map((match) => {
+      grepChildren(match, ["hit", "line", "symbol"]);
+      return {
+        ...properties(match),
+        hits: children(match, "hit").map((hit) => {
+          grepChildren(hit, []);
+          return properties(hit);
+        }),
+        lines: children(match, "line").map(grepLine),
+        symbols: children(match, "symbol").map((symbol) => {
+          grepChildren(symbol, ["line"]);
+          return { ...properties(symbol), lines: children(symbol, "line").map(grepLine) };
+        })
+      };
+    }),
+    documents: children(root, "document").map((document) => {
+      grepChildren(document, ["hit"]);
+      return { ...properties(document), hits: children(document, "hit").map((hit) => {
+        grepChildren(hit, []);
+        return properties(hit);
+      }) };
+    })
+  });
+}
 function references(root) {
   const parsed = children(root, "reference").map((reference) => {
     const sourceLine = child(reference, "line");
@@ -2045,7 +2224,7 @@ function parseReadSeekKdl(text) {
     case "document":
       return root.properties.has("format") ? pdfDocument(root) : sourceDocument(root);
     case "search":
-      return search(root);
+      return ["mode", "ignore_case", "summary", "count_unit"].some((key) => root.properties.has(key)) ? grep(root) : search(root);
     case "check":
       return diagnostics(root);
     case "refs":
@@ -2379,6 +2558,7 @@ export {
   getToolContract,
   isShowTool,
   isSubPath,
+  parseGrepOutput,
   parseLineAnchor,
   parseReadSeekKdl,
   parseSelector,
@@ -2390,6 +2570,7 @@ export {
   readSeekProcessEnvironment,
   renderCompactGuidelines,
   renderFallbackToolDescription,
+  renderGrepOutput,
   renderPreferredToolDescription,
   renderToolDescription,
   renderToolRoutingPolicy,
@@ -2410,5 +2591,6 @@ export {
   serializeEditPlan,
   tryParseLineAnchor,
   validateExactlyOneEditVariant,
+  validateGrepParams,
   validateReferencesSelection
 };

package/dist/validation.d.ts

@@ -9,6 +9,7 @@ export type ReferencesSelectionInput = {
     at?: string;
 };
 export declare function validateReferencesSelection(input: ReferencesSelectionInput): ValidationResult;
+export declare function validateGrepParams(input: unknown): ValidationResult;
 export type SetLineEdit = {
     set_line: {
         anchor: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jarkkojs/readseek-api",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Shared ReadSeek CLI contract, validation, argv builders, and bounded process runners",
   "type": "module",
   "license": "Apache-2.0",
@@ -51,7 +51,7 @@
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.12.0",
+    "@jarkkojs/readseek": "^0.12.1",
     "@bgotink/kdl": "0.4.0",
     "@sinclair/typebox": "0.34.52"
   }