@jarkkojs/readseek 0.8.23 → 0.9.0

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 (2) hide show
  1. package/README.md +65 -45
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # ReadSeek
2
2
 
3
- `readseek` turns source files, images, and PDFs into compact structured context for
3
+ `readseek` turns source files, images, and documents into compact structured context for
4
4
  scripts, editors, and coding agents. Source output includes stable `LINE:HASH`
5
5
  anchors, symbol maps, parse diagnostics, AST matches, definitions, references,
6
6
  and verified rename plans.
@@ -21,26 +21,26 @@ statically linked with musl.
21
21
 
22
22
  ## Integrations
23
23
 
24
- | Host | Package | Install |
25
- | --- | --- | --- |
26
- | Pi | [pi-readseek](packages/pi-readseek/README.md) | `pi install npm:pi-readseek` |
27
- | OpenCode | [opencode-readseek](packages/opencode-readseek/README.md) | Add `opencode-readseek` to `opencode.json` |
28
- | Claude Code | [claude-readseek](packages/claude-readseek/README.md) | Add this repository as a `/plugin` marketplace source |
29
- | Vim | [readseek.vim](doc/readseek.txt) | Install this repository with a plugin manager, then run `:ReadSeekInstall` |
24
+ | Host | Package | Install |
25
+ | ----------- | --------------------------------------------------------- | -------------------------------------------------------------------------- |
26
+ | Pi | [pi-readseek](packages/pi-readseek/README.md) | `pi install npm:pi-readseek` |
27
+ | OpenCode | [opencode-readseek](packages/opencode-readseek/README.md) | Add `opencode-readseek` to `opencode.json` |
28
+ | Claude Code | [claude-readseek](packages/claude-readseek/README.md) | Add this repository as a `/plugin` marketplace source |
29
+ | Vim | [readseek.vim](doc/readseek.txt) | Install this repository with a plugin manager, then run `:ReadSeekInstall` |
30
30
 
31
31
  ## CLI tour
32
32
 
33
- ### Read and inspect
33
+ ### Digest
34
34
 
35
35
  ```sh
36
- readseek detect src/main.rs
37
- readseek read src/main.rs:10 --end 20
38
- readseek map src/main.rs
39
- readseek symbol src/main.rs:run --name
40
- readseek identify src/main.rs:42 --column 8
41
- readseek check src/main.rs
36
+ readseek digest src/main.rs --at line:10 --end 20
37
+ readseek digest src/main.rs --at symbol:run
38
+ readseek digest src/main.rs --select metadata,map,diagnostics
42
39
  ```
43
40
 
41
+ `digest` always returns `metadata` plus the requested facets. `content` is the
42
+ default; facets are combined with a comma.
43
+
44
44
  Source reads emit records such as `42:a1b|let value = parse(input);`. The line
45
45
  number locates the text; the short hash rejects most stale edits while tolerating
46
46
  whitespace-only changes.
@@ -50,7 +50,7 @@ whitespace-only changes.
50
50
  ```sh
51
51
  readseek def src run --language rust --format plain
52
52
  readseek refs src run --language rust --format plain
53
- readseek refs src/main.rs run --scope --line 42 --column 8
53
+ readseek refs src/main.rs --at line:42:8
54
54
  readseek search src 'fn $NAME() { $$$BODY }' --language rust
55
55
  ```
56
56
 
@@ -59,14 +59,33 @@ directory searches include tracked/indexed and untracked non-ignored files by
59
59
  default. Use `--git cached`, `--git others`, or both to restrict the set;
60
60
  `ignored` requires `others`.
61
61
 
62
+ ### Edit
63
+
64
+ `edit` verifies all anchors and rejects stale or overlapping operations before
65
+ writing. Requests are JSON files, or JSON on stdin by default:
66
+
67
+ ```sh
68
+ readseek edit src/main.rs --request edits.json
69
+ readseek edit src/main.rs --request edits.json --apply --plan-hash <plan_hash>
70
+ printf '%s' '{"edits":[{"set_line":{"anchor":"42:a1b","new_text":"let value = 2;"}}]}' \
71
+ | readseek edit src/main.rs --apply
72
+ ```
73
+
74
+ A dry run returns the planned content and a `plan_hash`. Passing that hash during
75
+ apply prevents a changed plan from being written.
76
+
77
+ Requests support anchored line replacement, range replacement, insertion, exact
78
+ text replacement, and whole-symbol replacement. An empty `new_text` deletes an
79
+ anchored line or range. `--language` overrides detection for symbol replacement.
80
+
62
81
  ### Rename
63
82
 
64
83
  A rename is a dry run unless `--apply` is present:
65
84
 
66
85
  ```sh
67
- readseek rename src/main.rs --line 42 --column 8 --to renamed
68
- readseek rename src/main.rs --line 42 --column 8 --to renamed --apply
69
- readseek rename src/main.rs --line 42 --to renamed --workspace . --apply
86
+ readseek rename src/main.rs --at line:42:8 --to renamed
87
+ readseek rename src/main.rs --at line:42:8 --to renamed --apply
88
+ readseek rename src/main.rs --at line:42 --to renamed --workspace . --apply
70
89
  ```
71
90
 
72
91
  Rename plans report conflicts and hash-verified edits. Workspace mode extends the
@@ -77,46 +96,47 @@ plan beyond the cursor file.
77
96
  Global options must precede the command:
78
97
 
79
98
  ```sh
80
- readseek --output result.json detect src/main.rs
99
+ readseek --output result.json digest src/main.rs --select metadata
81
100
  readseek --readseek-dir /tmp/project-index view report.pdf
82
101
  ```
83
102
 
84
- Prefix a target with `stdin:` to analyze an unsaved buffer while retaining a
85
- path for language detection and cursor addressing. This works with `detect`,
86
- `read`, `map`, `check`, `symbol`, and `identify`:
103
+ Pass `-` as the path to read standard input. Use `--stdin-name` when a virtual
104
+ path is needed for language detection or reporting. This works with `digest`
105
+ and `view`:
87
106
 
88
107
  ```sh
89
- printf '%s\n' 'fn main() {}' | readseek identify stdin:scratch.rs:1 --column 4
108
+ printf '%s\n' 'fn main() {}' |
109
+ readseek digest - --stdin-name scratch.rs --select identity --at line:1:4
90
110
  ```
91
111
 
92
- ## Images and PDFs
112
+ ## Images and documents
93
113
 
94
- `detect` reports image metadata and PDF page counts. An image read returns a
95
- bounded base64 payload by default. Select local analysis explicitly:
114
+ `digest` reports image metadata and can return a bounded base64 image payload.
115
+ Select local analysis explicitly:
96
116
 
97
117
  ```sh
98
- readseek read photo.jpg --vision-mode caption
99
- readseek read photo.jpg --vision-mode objects
100
- readseek read scan.png --vision-mode ocr --vision-level high
101
- readseek read photo.jpg --vision-mode all
118
+ readseek digest scan.png --vision-mode ocr --vision-level high
102
119
  ```
103
120
 
104
121
  Vision modes are `none`, `caption`, `objects`, `ocr`, and `all`. Analysis starts
105
122
  at the `low` level; use `medium` or `high` only when more detail is needed.
106
123
 
107
- PDF reads return page-tagged Markdown plus embedded images. `--page` selects a
108
- page, and `--vision-mode` applies to its images:
124
+ PDF is the first supported document format. Document digestion ingests the
125
+ whole document into the content-addressed structural cache and returns a JSON
126
+ receipt whose state is `built` or `reused`. This makes `digest` suitable for
127
+ cache-warming jobs. It does not return document pages or assets.
109
128
 
110
129
  ```sh
111
- readseek read report.pdf --page 3 --vision-mode ocr
112
130
  readseek init
113
- readseek view report.pdf
114
- readseek view report.pdf --page 3 --outline
131
+ readseek digest report.pdf
132
+ readseek view report.pdf --page 3
133
+ readseek view report.pdf --page 3 --vision-mode ocr
115
134
  ```
116
135
 
117
- `view` creates or reuses a structural PDF index and can narrow it by page, node,
118
- kind, or depth. Line/hash suffixes and source range/language options do not apply
119
- to images or PDFs.
136
+ `view` is the document-content interface. It creates the same cache on a miss,
137
+ then narrows the indexed structure by page, node, kind, or depth. Vision modes
138
+ analyze the selected cached assets. `--at` and source range/language options do
139
+ not apply to images or documents.
120
140
 
121
141
  Image analysis runs locally on the CPU with
122
142
  [Qwen3-VL-2B-Instruct](docs/models/qwen3-vl-2b-instruct.md). Its model files are
@@ -128,13 +148,13 @@ downloaded and checksum-verified on first use.
128
148
  Commands discover that directory by walking up from the target; use
129
149
  `--readseek-dir` to select one explicitly.
130
150
 
131
- | Path | Contents |
132
- | --- | --- |
133
- | `.readseek/maps/` | Content-addressed source maps |
134
- | `.readseek/def-index/` | Definition index |
135
- | `.readseek/documents/` | PDF indexes and extracted assets |
136
- | `.readseek/vision/` | Level-specific image analysis results |
137
- | User cache `readseek/models/` | Downloaded vision model files |
151
+ | Path | Contents |
152
+ | ----------------------------- | ------------------------------------- |
153
+ | `.readseek/maps/` | Content-addressed source maps |
154
+ | `.readseek/def-index/` | Definition index |
155
+ | `.readseek/documents/` | Document indexes and extracted assets |
156
+ | `.readseek/vision/` | Level-specific image analysis results |
157
+ | User cache `readseek/models/` | Downloaded vision model files |
138
158
 
139
159
  ## Development
140
160
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@jarkkojs/readseek",
3
- "version": "0.8.23",
4
- "description": "Structural source, image, and PDF reader with stable line hashes",
3
+ "version": "0.9.0",
4
+ "description": "Structural digest for source files, images, and documents",
5
5
  "license": "Apache-2.0 AND LGPL-2.1-or-later",
6
6
  "homepage": "https://github.com/jarkkojs/readseek#readme",
7
7
  "repository": {
@@ -21,10 +21,10 @@
21
21
  "LICENSE-LGPL-2.1"
22
22
  ],
23
23
  "optionalDependencies": {
24
- "@jarkkojs/readseek-darwin-arm64": "0.8.23",
25
- "@jarkkojs/readseek-linux-arm64": "0.8.23",
26
- "@jarkkojs/readseek-linux-x64": "0.8.23",
27
- "@jarkkojs/readseek-win32-x64": "0.8.23"
24
+ "@jarkkojs/readseek-darwin-arm64": "0.9.0",
25
+ "@jarkkojs/readseek-linux-arm64": "0.9.0",
26
+ "@jarkkojs/readseek-linux-x64": "0.9.0",
27
+ "@jarkkojs/readseek-win32-x64": "0.9.0"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public"