@jarkkojs/readseek-api 0.11.4 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +8 -10
  2. package/dist/argv.d.ts +42 -33
  3. package/dist/client-output.d.ts +115 -8
  4. package/dist/client.d.ts +29 -29
  5. package/dist/contract.d.ts +22 -22
  6. package/dist/grep-presentation.d.ts +3 -0
  7. package/dist/index.d.ts +2 -0
  8. package/dist/index.js +484 -241
  9. package/dist/show-presentation.d.ts +1 -1
  10. package/dist/validation.d.ts +1 -0
  11. package/package.json +2 -2
package/README.md CHANGED
@@ -21,7 +21,7 @@ platform binary; plugins declare both packages directly.
21
21
 
22
22
  ```ts
23
23
  import {
24
- buildShowStructureArgs,
24
+ buildTreeArgs,
25
25
  resolveReadSeekBinaryFromPackages,
26
26
  resolveReadSeekBinaryOverride,
27
27
  runReadSeekNodeKdl,
@@ -29,14 +29,13 @@ import {
29
29
 
30
30
  const binary =
31
31
  resolveReadSeekBinaryOverride() ?? resolveReadSeekBinaryFromPackages();
32
- const args = buildShowStructureArgs({ path: "src/index.ts", depth: 2 });
32
+ const args = buildTreeArgs({ path: "src/index.ts", depth: 2 });
33
33
  const result = await runReadSeekNodeKdl(binary, args);
34
34
  ```
35
35
 
36
- The API follows the CLI's verb–object grammar: `showContent`, `showStructure`,
37
- `showMetadata`, `showAssets`, `findNodes`, `findText`, `findDefinitions`,
38
- `findReferences`, `checkSyntax`, `checkRules`, `generateCaption`, `detectObjects`,
39
- `recognizeText`, `editText`, and `renameSymbol`. Selection uses `at`.
36
+ The API follows the CLI's single-word command grammar: `show`, `tree`,
37
+ `meta`, `assets`, `search`, `grep`, `def`, `refs`, `syntax`, `check`,
38
+ `caption`, `objects`, `ocr`, `edit`, and `rename`. Selection uses `at`.
40
39
 
41
40
  Document content and asset results include usable cached image paths. There is no
42
41
  separate extraction step or destination argument. Cache population is an internal
@@ -44,14 +43,13 @@ write; reading never invokes inference. Syntax checks return diagnostics even
44
43
  when the native process exits 1 (findings); exit 2 is a failure.
45
44
 
46
45
  `presentShowResult()` and `formatShowResult()` provide shared readable output for
47
- `show_content`, `show_structure`, `show_metadata`, and `show_assets`. Summaries
46
+ `show`, `tree`, `meta`, and `assets`. Summaries
48
47
  identify selections and counts; bodies contain anchored lines, document sections,
49
48
  structure trees, fields, or asset paths. Notices identify omitted source ranges
50
49
  and how to continue. Formatting never mutates the decoded result.
51
50
 
52
- This is a breaking contract: legacy `inspect`/`extract` methods, selectable facets,
53
- and old command names are removed, not aliased.
54
-
51
+ This is a breaking contract: two-word verb-object methods, legacy `inspect`/`extract`
52
+ methods, and old command names are removed, not aliased.
55
53
  ## Licensing
56
54
 
57
55
  `@jarkkojs/readseek-api` is licensed under the Apache 2.0 license. See
package/dist/argv.d.ts CHANGED
@@ -18,6 +18,8 @@ type ParsedSelector = {
18
18
  kind: SelectorKind;
19
19
  value: string;
20
20
  column?: number;
21
+ endLine?: number;
22
+ explicitKind: boolean;
21
23
  };
22
24
  /** Mirrors core::ParseSelector so wrappers reject the same selectors natively. */
23
25
  export declare function parseSelector(text: string): ParsedSelector;
@@ -26,39 +28,39 @@ export type AccessArgsInput = {
26
28
  stdinName?: string;
27
29
  readseekDir?: string;
28
30
  };
29
- export type ShowContentArgsInput = AccessArgsInput & {
31
+ export type ShowArgsInput = AccessArgsInput & {
30
32
  at?: string;
31
33
  end?: number;
32
34
  limit?: number;
33
35
  language?: string;
34
36
  noAnchors?: boolean;
35
37
  };
36
- export type ShowStructureArgsInput = AccessArgsInput & {
38
+ export type TreeArgsInput = AccessArgsInput & {
37
39
  at?: string;
38
40
  depth?: number;
39
41
  kind?: string;
40
42
  outline?: boolean;
41
43
  language?: string;
42
44
  };
43
- export type ShowMetadataArgsInput = AccessArgsInput & {
45
+ export type MetaArgsInput = AccessArgsInput & {
44
46
  language?: string;
45
47
  };
46
- export type ShowAssetsArgsInput = AccessArgsInput & {
48
+ export type AssetsArgsInput = AccessArgsInput & {
47
49
  at?: string;
48
50
  };
49
- export type CheckSyntaxArgsInput = AccessArgsInput & {
51
+ export type SyntaxArgsInput = AccessArgsInput & {
50
52
  language?: string;
51
53
  };
52
54
  export type VisionArgsInput = AccessArgsInput & {
53
55
  at?: string;
54
56
  level?: VisionLevel;
55
57
  };
56
- export type GenerateCaptionArgsInput = VisionArgsInput & {
58
+ export type CaptionArgsInput = VisionArgsInput & {
57
59
  include?: ("text" | "objects")[];
58
60
  };
59
- export type DetectObjectsArgsInput = VisionArgsInput;
60
- export type RecognizeTextArgsInput = VisionArgsInput;
61
- export type FindNodesArgsInput = AccessArgsInput & GitScopeInput & {
61
+ export type ObjectsArgsInput = VisionArgsInput;
62
+ export type OcrArgsInput = VisionArgsInput;
63
+ export type SearchArgsInput = AccessArgsInput & GitScopeInput & {
62
64
  pattern?: string;
63
65
  context?: string;
64
66
  selector?: string;
@@ -67,29 +69,36 @@ export type FindNodesArgsInput = AccessArgsInput & GitScopeInput & {
67
69
  limit?: number;
68
70
  noAnchors?: boolean;
69
71
  };
70
- export type FindTextArgsInput = {
71
- path: string;
72
- text: string;
72
+ export type GrepArgsInput = GitScopeInput & {
73
+ pattern: string;
74
+ path?: string;
75
+ glob?: string;
76
+ ignoreCase?: boolean;
77
+ literal?: boolean;
78
+ context?: number;
73
79
  limit?: number;
74
- } & GitScopeInput;
75
- export type FindDefinitionsArgsInput = {
80
+ summary?: boolean;
81
+ scope?: "symbol";
82
+ scopeContext?: number;
83
+ };
84
+ export type DefArgsInput = {
76
85
  path: string;
77
86
  name: string;
78
87
  language?: string;
79
88
  noAnchors?: boolean;
80
89
  } & GitScopeInput;
81
- export type FindReferencesArgsInput = {
90
+ export type RefsArgsInput = {
82
91
  path: string;
83
92
  name?: string;
84
93
  at?: string;
85
94
  language?: string;
86
95
  noAnchors?: boolean;
87
96
  } & GitScopeInput;
88
- export type CheckRulesArgsInput = {
97
+ export type CheckArgsInput = {
89
98
  path: string;
90
99
  rules: string;
91
100
  } & GitScopeInput;
92
- export type EditTextArgsInput = {
101
+ export type EditArgsInput = {
93
102
  path: string;
94
103
  apply?: boolean;
95
104
  planHash?: string;
@@ -97,7 +106,7 @@ export type EditTextArgsInput = {
97
106
  requestFromStdin?: boolean;
98
107
  flagOrder?: ApplyPlanHashOrder;
99
108
  } & GitScopeInput;
100
- export type RenameSymbolArgsInput = {
109
+ export type RenameArgsInput = {
101
110
  path: string;
102
111
  to: string;
103
112
  at: string;
@@ -107,19 +116,19 @@ export type RenameSymbolArgsInput = {
107
116
  language?: string;
108
117
  flagOrder?: ApplyPlanHashOrder;
109
118
  } & GitScopeInput;
110
- export declare function buildShowContentArgs(input: ShowContentArgsInput): string[];
111
- export declare function buildShowStructureArgs(input: ShowStructureArgsInput): string[];
112
- export declare function buildShowMetadataArgs(input: ShowMetadataArgsInput): string[];
113
- export declare function buildShowAssetsArgs(input: ShowAssetsArgsInput): string[];
114
- export declare function buildCheckSyntaxArgs(input: CheckSyntaxArgsInput): string[];
115
- export declare function buildGenerateCaptionArgs(input: GenerateCaptionArgsInput): string[];
116
- export declare function buildDetectObjectsArgs(input: DetectObjectsArgsInput): string[];
117
- export declare function buildRecognizeTextArgs(input: RecognizeTextArgsInput): string[];
118
- export declare function buildFindNodesArgs(input: FindNodesArgsInput): string[];
119
- export declare function buildFindTextArgs(input: FindTextArgsInput): string[];
120
- export declare function buildFindDefinitionsArgs(input: FindDefinitionsArgsInput): string[];
121
- export declare function buildFindReferencesArgs(input: FindReferencesArgsInput): string[];
122
- export declare function buildCheckRulesArgs(input: CheckRulesArgsInput): string[];
123
- export declare function buildEditTextArgs(input: EditTextArgsInput): string[];
124
- export declare function buildRenameSymbolArgs(input: RenameSymbolArgsInput): string[];
119
+ export declare function buildShowArgs(input: ShowArgsInput): string[];
120
+ export declare function buildTreeArgs(input: TreeArgsInput): string[];
121
+ export declare function buildMetaArgs(input: MetaArgsInput): string[];
122
+ export declare function buildAssetsArgs(input: AssetsArgsInput): string[];
123
+ export declare function buildSyntaxArgs(input: SyntaxArgsInput): string[];
124
+ export declare function buildCaptionArgs(input: CaptionArgsInput): string[];
125
+ export declare function buildObjectsArgs(input: ObjectsArgsInput): string[];
126
+ export declare function buildOcrArgs(input: OcrArgsInput): string[];
127
+ export declare function buildSearchArgs(input: SearchArgsInput): string[];
128
+ export declare function buildGrepArgs(input: GrepArgsInput): string[];
129
+ export declare function buildDefArgs(input: DefArgsInput): string[];
130
+ export declare function buildRefsArgs(input: RefsArgsInput): string[];
131
+ export declare function buildCheckArgs(input: CheckArgsInput): string[];
132
+ export declare function buildEditArgs(input: EditArgsInput): string[];
133
+ export declare function buildRenameArgs(input: RenameArgsInput): string[];
125
134
  export {};
package/dist/client-output.d.ts CHANGED
@@ -541,37 +541,138 @@ declare const DocumentOutput: import("@sinclair/typebox").TObject<{
541
541
  ocr_requested: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
542
542
  }>>;
543
543
  }>;
544
- declare const TextSearchOutput: import("@sinclair/typebox").TObject<{
544
+ declare const GrepLineSchema: import("@sinclair/typebox").TObject<{
545
+ line: import("@sinclair/typebox").TInteger;
546
+ hash: import("@sinclair/typebox").TString;
545
547
  text: import("@sinclair/typebox").TString;
546
- mode: import("@sinclair/typebox").TLiteral<"literal">;
548
+ kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
549
+ }>;
550
+ declare const GrepHitSchema: import("@sinclair/typebox").TObject<{
551
+ line: import("@sinclair/typebox").TInteger;
552
+ column: import("@sinclair/typebox").TInteger;
553
+ start_byte: import("@sinclair/typebox").TInteger;
554
+ end_byte: import("@sinclair/typebox").TInteger;
555
+ text: import("@sinclair/typebox").TString;
556
+ anchor: import("@sinclair/typebox").TString;
557
+ }>;
558
+ declare const GrepSymbolSchema: import("@sinclair/typebox").TObject<{
559
+ name: import("@sinclair/typebox").TString;
560
+ kind: import("@sinclair/typebox").TString;
561
+ start_line: import("@sinclair/typebox").TInteger;
562
+ end_line: import("@sinclair/typebox").TInteger;
563
+ lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
564
+ line: import("@sinclair/typebox").TInteger;
565
+ hash: import("@sinclair/typebox").TString;
566
+ text: import("@sinclair/typebox").TString;
567
+ kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
568
+ }>>;
569
+ }>;
570
+ declare const GrepSourceResultSchema: import("@sinclair/typebox").TObject<{
571
+ file: import("@sinclair/typebox").TString;
572
+ file_hash: import("@sinclair/typebox").TString;
573
+ language: import("@sinclair/typebox").TString;
574
+ total_matches: import("@sinclair/typebox").TInteger;
575
+ returned_matches: import("@sinclair/typebox").TInteger;
576
+ hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
577
+ line: import("@sinclair/typebox").TInteger;
578
+ column: import("@sinclair/typebox").TInteger;
579
+ start_byte: import("@sinclair/typebox").TInteger;
580
+ end_byte: import("@sinclair/typebox").TInteger;
581
+ text: import("@sinclair/typebox").TString;
582
+ anchor: import("@sinclair/typebox").TString;
583
+ }>>;
584
+ lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
585
+ line: import("@sinclair/typebox").TInteger;
586
+ hash: import("@sinclair/typebox").TString;
587
+ text: import("@sinclair/typebox").TString;
588
+ kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
589
+ }>>;
590
+ symbols: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
591
+ name: import("@sinclair/typebox").TString;
592
+ kind: import("@sinclair/typebox").TString;
593
+ start_line: import("@sinclair/typebox").TInteger;
594
+ end_line: import("@sinclair/typebox").TInteger;
595
+ lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
596
+ line: import("@sinclair/typebox").TInteger;
597
+ hash: import("@sinclair/typebox").TString;
598
+ text: import("@sinclair/typebox").TString;
599
+ kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
600
+ }>>;
601
+ }>>;
602
+ }>;
603
+ declare const GrepDocumentHitSchema: import("@sinclair/typebox").TObject<{
604
+ node_id: import("@sinclair/typebox").TString;
605
+ kind: import("@sinclair/typebox").TString;
606
+ snippet: import("@sinclair/typebox").TString;
607
+ line: import("@sinclair/typebox").TInteger;
608
+ page: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
609
+ }>;
610
+ declare const GrepDocumentResultSchema: import("@sinclair/typebox").TObject<{
611
+ file: import("@sinclair/typebox").TString;
612
+ content_hash: import("@sinclair/typebox").TString;
613
+ total_matches: import("@sinclair/typebox").TInteger;
614
+ returned_matches: import("@sinclair/typebox").TInteger;
615
+ hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
616
+ node_id: import("@sinclair/typebox").TString;
617
+ kind: import("@sinclair/typebox").TString;
618
+ snippet: import("@sinclair/typebox").TString;
619
+ line: import("@sinclair/typebox").TInteger;
620
+ page: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
621
+ }>>;
622
+ }>;
623
+ declare const GrepOutputSchema: import("@sinclair/typebox").TObject<{
624
+ pattern: import("@sinclair/typebox").TString;
625
+ mode: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"regex">, import("@sinclair/typebox").TLiteral<"literal">]>;
626
+ ignore_case: import("@sinclair/typebox").TBoolean;
627
+ summary: import("@sinclair/typebox").TBoolean;
547
628
  total_matches: import("@sinclair/typebox").TInteger;
548
629
  returned_matches: import("@sinclair/typebox").TInteger;
549
630
  truncated: import("@sinclair/typebox").TBoolean;
631
+ count_unit: import("@sinclair/typebox").TLiteral<"lines">;
632
+ scope: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TLiteral<"symbol">>;
550
633
  results: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
551
634
  file: import("@sinclair/typebox").TString;
552
635
  file_hash: import("@sinclair/typebox").TString;
553
- matches: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
636
+ language: import("@sinclair/typebox").TString;
637
+ total_matches: import("@sinclair/typebox").TInteger;
638
+ returned_matches: import("@sinclair/typebox").TInteger;
639
+ hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
554
640
  line: import("@sinclair/typebox").TInteger;
555
641
  column: import("@sinclair/typebox").TInteger;
642
+ start_byte: import("@sinclair/typebox").TInteger;
643
+ end_byte: import("@sinclair/typebox").TInteger;
644
+ text: import("@sinclair/typebox").TString;
645
+ anchor: import("@sinclair/typebox").TString;
646
+ }>>;
647
+ lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
648
+ line: import("@sinclair/typebox").TInteger;
649
+ hash: import("@sinclair/typebox").TString;
556
650
  text: import("@sinclair/typebox").TString;
651
+ kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
652
+ }>>;
653
+ symbols: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
654
+ name: import("@sinclair/typebox").TString;
655
+ kind: import("@sinclair/typebox").TString;
557
656
  start_line: import("@sinclair/typebox").TInteger;
558
657
  end_line: import("@sinclair/typebox").TInteger;
559
- start_byte: import("@sinclair/typebox").TInteger;
560
- end_byte: import("@sinclair/typebox").TInteger;
561
- hashlines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
658
+ lines: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
562
659
  line: import("@sinclair/typebox").TInteger;
563
660
  hash: import("@sinclair/typebox").TString;
564
661
  text: import("@sinclair/typebox").TString;
662
+ kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"match">, import("@sinclair/typebox").TLiteral<"context">]>;
565
663
  }>>;
566
664
  }>>;
567
665
  }>>;
568
666
  documents: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
569
667
  file: import("@sinclair/typebox").TString;
570
668
  content_hash: import("@sinclair/typebox").TString;
669
+ total_matches: import("@sinclair/typebox").TInteger;
670
+ returned_matches: import("@sinclair/typebox").TInteger;
571
671
  hits: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
572
672
  node_id: import("@sinclair/typebox").TString;
573
673
  kind: import("@sinclair/typebox").TString;
574
674
  snippet: import("@sinclair/typebox").TString;
675
+ line: import("@sinclair/typebox").TInteger;
575
676
  page: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
576
677
  }>>;
577
678
  }>>;
@@ -599,7 +700,13 @@ export type ReadSeekDocumentNode = Static<typeof DocumentNode>;
599
700
  export type ReadSeekDocumentAsset = Static<typeof DocumentAsset>;
600
701
  export type ReadSeekDocumentVision = Static<typeof DocumentVision>;
601
702
  export type ReadSeekDocumentOutput = Static<typeof DocumentOutput>;
602
- export type ReadSeekTextSearchOutput = Static<typeof TextSearchOutput>;
703
+ export type GrepOutput = Static<typeof GrepOutputSchema>;
704
+ export type GrepLine = Static<typeof GrepLineSchema>;
705
+ export type GrepHit = Static<typeof GrepHitSchema>;
706
+ export type GrepSymbol = Static<typeof GrepSymbolSchema>;
707
+ export type GrepSourceResult = Static<typeof GrepSourceResultSchema>;
708
+ export type GrepDocumentHit = Static<typeof GrepDocumentHitSchema>;
709
+ export type GrepDocumentResult = Static<typeof GrepDocumentResultSchema>;
603
710
  export type ReadSeekRulesOutput = Static<typeof RulesOutput>;
604
711
  export interface ReadSeekSourceContentOutput {
605
712
  metadata: ReadSeekDetection;
@@ -614,7 +721,7 @@ export type ReadSeekStructureOutputEnvelope = {
614
721
  export declare function parseDocumentOutput(value: unknown): ReadSeekDocumentOutput;
615
722
  export declare function parseContentOutput(value: unknown): ReadSeekContentOutput;
616
723
  export declare function parseStructureEnvelope(value: unknown): ReadSeekStructureOutputEnvelope;
617
- export declare function parseTextSearchOutput(value: unknown): ReadSeekTextSearchOutput;
724
+ export declare function parseGrepOutput(value: unknown): GrepOutput;
618
725
  export declare function parseRulesOutput(value: unknown): ReadSeekRulesOutput;
619
726
  declare const SourceAssetsOutput: import("@sinclair/typebox").TObject<{
620
727
  file: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
package/dist/client.d.ts CHANGED
@@ -13,20 +13,20 @@ export interface ReadSeekRunner {
13
13
  kdl(args: readonly string[], options?: ReadSeekRunOptions): Promise<unknown>;
14
14
  }
15
15
  type Options<T> = Omit<T, "path" | "requestFromStdin" | "flagOrder"> & Omit<ReadSeekRunOptions, "vision">;
16
- export type ReadSeekContentOptions = Options<argv.ShowContentArgsInput>;
17
- export type ReadSeekStructureOptions = Options<argv.ShowStructureArgsInput>;
18
- export type ReadSeekMetadataOptions = Options<argv.ShowMetadataArgsInput>;
19
- export type ReadSeekAssetsOptions = Options<argv.ShowAssetsArgsInput>;
20
- export type ReadSeekSyntaxOptions = Options<argv.CheckSyntaxArgsInput>;
21
- export type ReadSeekRulesOptions = Options<argv.CheckRulesArgsInput>;
22
- export type ReadSeekCaptionOptions = Options<argv.GenerateCaptionArgsInput>;
23
- export type ReadSeekVisionOptions = Options<argv.DetectObjectsArgsInput>;
24
- export type ReadSeekNodesOptions = Options<argv.FindNodesArgsInput>;
25
- export type ReadSeekTextOptions = Options<argv.FindTextArgsInput>;
26
- export type ReadSeekDefinitionsOptions = Options<argv.FindDefinitionsArgsInput>;
27
- export type ReadSeekReferencesOptions = Options<argv.FindReferencesArgsInput>;
28
- export type ReadSeekEditOptions = Options<argv.EditTextArgsInput>;
29
- export type ReadSeekRenameOptions = Options<argv.RenameSymbolArgsInput>;
16
+ export type ReadSeekShowOptions = Options<argv.ShowArgsInput>;
17
+ export type ReadSeekTreeOptions = Options<argv.TreeArgsInput>;
18
+ export type ReadSeekMetaOptions = Options<argv.MetaArgsInput>;
19
+ export type ReadSeekAssetsOptions = Options<argv.AssetsArgsInput>;
20
+ export type ReadSeekSyntaxOptions = Options<argv.SyntaxArgsInput>;
21
+ export type ReadSeekCheckOptions = Options<argv.CheckArgsInput>;
22
+ export type ReadSeekCaptionOptions = Options<argv.CaptionArgsInput>;
23
+ export type ReadSeekVisionOptions = Options<argv.ObjectsArgsInput>;
24
+ export type ReadSeekSearchOptions = Options<argv.SearchArgsInput>;
25
+ export type ReadSeekGrepParams = argv.GrepArgsInput & Omit<ReadSeekRunOptions, "vision">;
26
+ export type ReadSeekDefOptions = Options<argv.DefArgsInput>;
27
+ export type ReadSeekRefsOptions = Options<argv.RefsArgsInput>;
28
+ export type ReadSeekEditOptions = Options<argv.EditArgsInput>;
29
+ export type ReadSeekRenameOptions = Options<argv.RenameArgsInput>;
30
30
  export interface ReadSeekFailure {
31
31
  code: "readseek-not-installed" | "readseek-execution-error";
32
32
  message: string;
@@ -39,20 +39,20 @@ export interface ReadSeekFailure {
39
39
  */
40
40
  export declare function classifyReadSeekFailure(err: unknown): ReadSeekFailure;
41
41
  export interface ReadSeekClient {
42
- showContent(path: string, options?: ReadSeekContentOptions): Promise<output.ReadSeekContentOutput>;
43
- showStructure(path: string, options?: ReadSeekStructureOptions): Promise<output.ReadSeekStructureOutputEnvelope>;
44
- showMetadata(path: string, options?: ReadSeekMetadataOptions): Promise<output.ReadSeekDetection>;
45
- showAssets(path: string, options?: ReadSeekAssetsOptions): Promise<output.ReadSeekAssetsOutput>;
46
- checkSyntax(path: string, options?: ReadSeekSyntaxOptions): Promise<output.ReadSeekCheckOutput>;
47
- checkRules(path: string, options: ReadSeekRulesOptions): Promise<output.ReadSeekRulesOutput>;
48
- generateCaption(path: string, options?: ReadSeekCaptionOptions): Promise<output.ReadSeekContentOutput>;
49
- detectObjects(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
50
- recognizeText(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
51
- findNodes(path: string, options: ReadSeekNodesOptions): Promise<output.ReadSeekSearchOutput>;
52
- findText(path: string, options: ReadSeekTextOptions): Promise<output.ReadSeekTextSearchOutput>;
53
- findDefinitions(path: string, options: ReadSeekDefinitionsOptions): Promise<output.DefLocation[]>;
54
- findReferences(path: string, options: ReadSeekReferencesOptions): Promise<output.ReadSeekReference[]>;
55
- editText(path: string, edits: unknown[], options?: ReadSeekEditOptions): Promise<output.EditOutput>;
56
- renameSymbol(path: string, options: ReadSeekRenameOptions): Promise<output.RenameOutput>;
42
+ show(path: string, options?: ReadSeekShowOptions): Promise<output.ReadSeekContentOutput>;
43
+ tree(path: string, options?: ReadSeekTreeOptions): Promise<output.ReadSeekStructureOutputEnvelope>;
44
+ meta(path: string, options?: ReadSeekMetaOptions): Promise<output.ReadSeekDetection>;
45
+ assets(path: string, options?: ReadSeekAssetsOptions): Promise<output.ReadSeekAssetsOutput>;
46
+ syntax(path: string, options?: ReadSeekSyntaxOptions): Promise<output.ReadSeekCheckOutput>;
47
+ check(path: string, options: ReadSeekCheckOptions): Promise<output.ReadSeekRulesOutput>;
48
+ caption(path: string, options?: ReadSeekCaptionOptions): Promise<output.ReadSeekContentOutput>;
49
+ objects(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
50
+ ocr(path: string, options?: ReadSeekVisionOptions): Promise<output.ReadSeekContentOutput>;
51
+ search(path: string, options: ReadSeekSearchOptions): Promise<output.ReadSeekSearchOutput>;
52
+ grep(params: ReadSeekGrepParams): Promise<output.GrepOutput>;
53
+ def(path: string, options: ReadSeekDefOptions): Promise<output.DefLocation[]>;
54
+ refs(path: string, options: ReadSeekRefsOptions): Promise<output.ReadSeekReference[]>;
55
+ edit(path: string, edits: unknown[], options?: ReadSeekEditOptions): Promise<output.EditOutput>;
56
+ rename(path: string, options: ReadSeekRenameOptions): Promise<output.RenameOutput>;
57
57
  }
58
58
  export declare function createReadSeekClient(runner: ReadSeekRunner): ReadSeekClient;
package/dist/contract.d.ts CHANGED
@@ -4,7 +4,7 @@ export declare const EDIT_VARIANTS: readonly ["set_line", "replace_lines", "inse
4
4
  export type EditVariant = (typeof EDIT_VARIANTS)[number];
5
5
  export declare const GIT_SCOPES: readonly ["tracked", "untracked", "ignored", "all"];
6
6
  export type GitScope = (typeof GIT_SCOPES)[number];
7
- export declare const TOOL_NAMES: readonly ["show_content", "show_structure", "show_metadata", "show_assets", "check_syntax", "check_rules", "generate_caption", "detect_objects", "recognize_text", "find_nodes", "find_text", "find_definitions", "find_references", "edit_text", "rename_symbol", "write_file"];
7
+ export declare const TOOL_NAMES: readonly ["show", "tree", "meta", "assets", "syntax", "check", "caption", "objects", "ocr", "search", "grep", "def", "refs", "edit", "rename", "write"];
8
8
  export type ToolName = (typeof TOOL_NAMES)[number];
9
9
  export declare const PARAM_DESCRIPTIONS: {
10
10
  readonly path: "Absolute or relative file path";
@@ -16,12 +16,12 @@ export declare const PARAM_DESCRIPTIONS: {
16
16
  readonly pattern: "AST pattern (ast-grep style), such as console.log($$$ARGS)";
17
17
  readonly patternContext: "Surrounding code context for sub-statement patterns";
18
18
  readonly selector: "Target AST node kind to extract from pattern context";
19
- readonly grepPattern: "Regex pattern; set literal for exact text";
19
+ readonly grepPattern: "Native regex pattern; set literal for exact text. Empty regex matches every line; empty literal is invalid.";
20
20
  readonly name: "Qualified or unqualified symbol name";
21
21
  readonly refsName: "Identifier to find references for";
22
22
  readonly gitScope: "In a Git repository, which files to search: tracked, untracked, ignored (untracked plus ignored), or all. Defaults to tracked plus untracked.";
23
- readonly at: "Location selector: line:N[:COLUMN], hash:H[:COLUMN], symbol:NAME, page:N, node:ID, or asset:ID";
24
- readonly assetAt: "Document selector: page:N, node:ID, or asset:ID";
23
+ readonly at: "Location selector: N[:COLUMN], START-END, H[:COLUMN], NAME, line:N[:COLUMN], hash:H[:COLUMN], symbol:NAME, page:N, node:ID, or asset:ID";
24
+ readonly assetAt: "Document selector: N, page:N, node:ID, or asset:ID";
25
25
  readonly rule: "KDL node selection rule, @path, or '-' for standard input";
26
26
  readonly rules: "KDL structural checks, @path, or '-' for standard input";
27
27
  readonly stdinName: "File name hint when the target is '-'";
@@ -33,7 +33,6 @@ export declare const PARAM_DESCRIPTIONS: {
33
33
  readonly kind: "Restrict structure to this node kind";
34
34
  readonly outline: "Show outline of document hierarchy or source symbols";
35
35
  readonly noAnchors: "Omit source line anchors";
36
- readonly text: "Literal native text query; adapter find_text also supports regex via pattern";
37
36
  readonly edits: "Use set_line, replace_lines, insert_after, replace_symbol, or replace";
38
37
  readonly editVariant: "Exactly one nested edit variant";
39
38
  readonly setLine: "Replace one line: {\"set_line\":{\"anchor\":\"LINE:HASH\",\"new_text\":\"...\"}}";
@@ -65,27 +64,28 @@ export declare const PARAM_DESCRIPTIONS: {
65
64
  readonly literal: "Treat pattern literally";
66
65
  readonly context: "Surrounding lines for each match";
67
66
  readonly matchLimit: "Maximum matches to return";
67
+ readonly grepLimit: "Maximum matching lines to return; positive integer, defaults to 100";
68
68
  readonly summary: "Return per-file counts";
69
69
  readonly grepScope: "Group matches by enclosing symbol";
70
- readonly scopeContext: "Context lines within each symbol";
70
+ readonly scopeContext: "Non-negative context lines within each symbol; requires scope: symbol";
71
71
  };
72
72
  export declare const TOOL_DESCRIPTIONS: {
73
- readonly show_content: "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.";
74
- readonly show_structure: "Show parsed source or document hierarchy. Use shallow depth for file overviews.";
75
- readonly show_metadata: "Show format, source identity, language, dimensions, or page count without decoding image content or inference.";
76
- readonly show_assets: "Return selected document asset descriptors with usable cached paths. Adapters attach images from those paths.";
77
- readonly check_syntax: "Check parser syntax diagnostics. Exit 0 is clean, 1 has findings, 2 is failure; this is not type checking.";
78
- readonly check_rules: "Evaluate KDL structural assertions. Exit 0 is clean, 1 has findings, 2 is failure.";
79
- readonly generate_caption: "Explicitly infer a caption using an installed model. Include text and objects to request OCR and detection too; never downloads models automatically.";
80
- readonly detect_objects: "Explicitly infer object labels and bounding boxes using an installed model.";
81
- readonly recognize_text: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.";
82
- readonly find_nodes: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `find_text` for text and regex.";
83
- readonly find_text: "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.";
84
- readonly find_definitions: "Find a symbol definition or declaration by qualified or unqualified name.";
85
- readonly find_references: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.";
86
- readonly edit_text: "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.";
87
- readonly rename_symbol: "Rename a symbol at a line or hash cursor with binding-aware edits and stale-plan protection.";
88
- readonly write_file: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit_text` for small changes.";
73
+ 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.";
74
+ readonly tree: "Show parsed source or document hierarchy. Use shallow depth for file overviews.";
75
+ readonly meta: "Show format, source identity, language, dimensions, or page count without decoding image content or inference.";
76
+ readonly assets: "Return selected document asset descriptors with usable cached paths. Adapters attach images from those paths.";
77
+ readonly syntax: "Check parser syntax diagnostics. Exit 0 is clean, 1 has findings, 2 is failure; this is not type checking.";
78
+ readonly check: "Evaluate KDL structural assertions. Exit 0 is clean, 1 has findings, 2 is failure.";
79
+ readonly caption: "Explicitly infer a caption using an installed model. Include text and objects to request OCR and detection too; never downloads models automatically.";
80
+ readonly objects: "Explicitly infer object labels and bounding boxes using an installed model.";
81
+ readonly ocr: "Explicitly recognize text from pixels using an installed model; reading never silently invokes OCR.";
82
+ readonly search: "Find AST nodes by pattern or KDL selection rule. Returns edit-ready anchors. Use `grep` for text and regex.";
83
+ 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.";
84
+ readonly def: "Find a symbol definition or declaration by qualified or unqualified name.";
85
+ readonly refs: "Find identifier-name matches with name, or binding-scoped references with at. Use before renaming or deleting a symbol.";
86
+ 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.";
87
+ readonly rename: "Rename a symbol at a line or hash cursor with binding-aware edits and stale-plan protection.";
88
+ readonly write: "Create or replace a complete text file and return `LINE:HASH` anchors. Use `edit` for small changes.";
89
89
  };
90
90
  export declare function rewriteBacktickedToolNames(text: string, aliases?: Readonly<Partial<Record<ToolName, string>>>): string;
91
91
  export declare function renderToolDescription(name: ToolName, aliases?: Readonly<Partial<Record<ToolName, string>>>): string;
package/dist/grep-presentation.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import type { GrepOutput } from "./client-output.ts";
2
+ /** Render native grep results without re-matching or reading source files. */
3
+ export declare function renderGrepOutput(output: GrepOutput): string;
package/dist/index.d.ts CHANGED
@@ -6,6 +6,8 @@ export * from "./client.ts";
6
6
  export { serializeEditPlan } from "./edit-plan.ts";
7
7
  export * from "./hashline.ts";
8
8
  export * from "./show-presentation.ts";
9
+ export * from "./grep-presentation.ts";
10
+ export { parseGrepOutput } from "./client-output.ts";
9
11
  export { READSEEK_BINARY_ENV, READSEEK_PLATFORM_PACKAGES, readSeekBinaryName, readSeekPlatformKey, resolveReadSeekBinaryFromPackages, resolveReadSeekBinaryOverride, resolveReadSeekCacheDir, type ModuleResolver, type ReadSeekCacheOptions, } from "./platform.ts";
10
12
  export { canonicalPathKey, expandUserPath, isSubPath, resolveScopedPath, resolveToCwd, } from "./path.ts";
11
13
  export { cleanReadSeekErrorText } from "./error.ts";