@jarkkojs/readseek 0.8.17 → 0.8.19

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 +140 -119
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,109 +1,99 @@
1
- # readseek
1
+ # ReadSeek
2
2
 
3
- `readseek` reads source files and PDFs for scripts, editors, and coding agents.
4
- It returns compact JSON with stable line/hash anchors, symbol maps, parse
5
- diagnostics, AST matches, references, and rename plans.
3
+ `readseek` turns source files, images, and PDFs into compact structured context for
4
+ scripts, editors, and coding agents. Source output includes stable `LINE:HASH`
5
+ anchors, symbol maps, parse diagnostics, AST matches, definitions, references,
6
+ and verified rename plans.
6
7
 
7
- The screencast above was recorded with a very modest AMD Ryzen 5 PRO 4650 laptop
8
- CPU, and demonstrates the tailored inference engine for Qwen3-VL-2B.
8
+ ## Install
9
9
 
10
- ## Installation
11
-
12
- Install the npm wrapper with a prebuilt binary:
10
+ Choose one installation method:
13
11
 
14
12
  ```sh
15
- npm install -g @jarkkojs/readseek
13
+ npm install -g @jarkkojs/readseek # Node 18+
14
+ cargo install readseek # Rust 1.89+
15
+ make install # build this checkout and install the CLI + man page
16
16
  ```
17
17
 
18
- Or install the native program from crates.io:
19
-
20
- ```sh
21
- cargo install readseek
22
- ```
18
+ `make install` supports `PREFIX` and `DESTDIR`. Prebuilt npm binaries are
19
+ available for macOS ARM64, Linux ARM64/x64, and Windows x64; Linux builds are
20
+ statically linked with musl.
23
21
 
24
- Prebuilt binaries are available for macOS ARM64; Linux ARM64 and x64; and Windows
25
- x64. The Linux binaries are statically linked with musl.
22
+ ## Integrations
26
23
 
27
- To build and install from source:
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` |
28
30
 
29
- ```sh
30
- make install
31
- ```
31
+ For Claude Code, add `https://github.com/jarkkojs/readseek` as the marketplace
32
+ source and install `claude-readseek`. The plugin requires Node 22.18+ and ships
33
+ passive hooks, MCP navigation tools, skills, and a Bash launcher. When no binary
34
+ is available, its `SessionStart` hook starts a background install.
32
35
 
33
- ## Plugins
36
+ The Vim plugin requires Vim 9 with `+job`, `+channel`, `+timers`, `+popupwin`,
37
+ and `+textprop`. Neovim is not supported. Managed binary downloads are explicit
38
+ unless `g:readseek_auto_install` is enabled.
34
39
 
35
- ### Pi extension
40
+ ## CLI tour
36
41
 
37
- The bundled [pi-readseek extension](packages/pi-readseek/README.md) adds ReadSeek's
38
- anchored file and structural-code tools to Pi:
42
+ ### Read and inspect
39
43
 
40
44
  ```sh
41
- pi install npm:pi-readseek
45
+ readseek detect src/main.rs
46
+ readseek read src/main.rs:10 --end 20
47
+ readseek map src/main.rs
48
+ readseek symbol src/main.rs:run --name
49
+ readseek identify src/main.rs:42 --column 8
50
+ readseek check src/main.rs
42
51
  ```
43
52
 
44
- ### OpenCode plugin
53
+ Source reads emit records such as `42:a1b|let value = parse(input);`. The line
54
+ number locates the text; the short hash lets an editor verify that the line has
55
+ not changed before applying an edit.
45
56
 
46
- The [opencode-readseek plugin](packages/opencode-readseek/README.md) adds the same
47
- tools to OpenCode. Add it to `opencode.json`:
57
+ ### Search and navigate
48
58
 
49
- ```json
50
- {
51
- "plugin": ["opencode-readseek"]
52
- }
59
+ ```sh
60
+ readseek def src run --language rust --format plain
61
+ readseek refs src run --language rust --format plain
62
+ readseek refs src/main.rs run --scope --line 42 --column 8
63
+ readseek search src 'fn $NAME() { $$$BODY }' --language rust
53
64
  ```
54
65
 
55
- ### Claude Code plugin
56
-
57
- The [claude-readseek plugin](packages/claude-readseek/README.md) enriches Claude
58
- Code's `Read` and `Grep` with readseek structural context and gates `Edit` against
59
- files that changed on disk since Claude last saw them. It is hooks-only — Claude
60
- Code plugins cannot register tools — so it requires no MCP server. It needs Node
61
- 22.18 or newer, which runs the TypeScript hooks directly with no build step. It
62
- installs the `readseek` binary itself on first session when it isn't already
63
- available, since a marketplace install runs no install step of its own.
64
-
65
- This repository is itself a Claude Code marketplace
66
- ([`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json)). Inside a
67
- Claude Code session, run the `/plugin` command and follow its prompts to add
68
- `https://github.com/jarkkojs/readseek` as a marketplace source and install the
69
- `claude-readseek` plugin.
70
-
71
- ### Vim plugin
66
+ `def`, `refs`, and `search` accept a file or directory. In a Git work tree,
67
+ directory searches include tracked/indexed and untracked non-ignored files by
68
+ default. Use `--git cached`, `--git others`, or both to restrict the set;
69
+ `ignored` requires `others`.
72
70
 
73
- The bundled `readseek.vim` plugin provides anchored reads, structural navigation,
74
- parse diagnostics, search, references, and renames. It requires Vim9 with `+job`,
75
- `+channel`, `+timers`, `+popupwin`, and `+textprop`; Neovim is not supported.
71
+ ### Rename
76
72
 
77
- Install it with a Vim plugin manager, such as `Plug 'jarkkojs/readseek'`, then run
78
- `:ReadSeekInstall` to install the matching prebuilt binary. Downloads are explicit
79
- by default.
80
-
81
- ## Common commands
73
+ A rename is a dry run unless `--apply` is present:
82
74
 
83
75
  ```sh
84
- readseek detect src/main.rs
85
- readseek read src/main.rs:10 --end 20
86
- readseek read report.pdf --page 3
87
- readseek view report.pdf --page 3
88
- readseek map src/main.rs
89
- readseek check src/main.rs
90
- readseek symbol src/main.rs:run --name
91
- readseek identify src/main.rs:42 --column 8
92
- readseek def src run --language rust --format plain
93
- readseek refs src main --language rust --format plain
94
- readseek search src 'fn $NAME() { $$$BODY }' --language rust
95
76
  readseek rename src/main.rs --line 42 --column 8 --to renamed
77
+ readseek rename src/main.rs --line 42 --column 8 --to renamed --apply
78
+ readseek rename src/main.rs --line 42 --to renamed --workspace . --apply
96
79
  ```
97
80
 
98
- Global options must precede the command. For example, write JSON to a file with:
81
+ Rename plans report conflicts and hash-verified edits. Workspace renames remain
82
+ binding-aware in the cursor file and exclude resolvable local shadows elsewhere;
83
+ unsupported cross-file bindings fall back to name matching.
84
+
85
+ ### Global options and stdin
86
+
87
+ Global options must precede the command:
99
88
 
100
89
  ```sh
101
90
  readseek --output result.json detect src/main.rs
91
+ readseek --readseek-dir /tmp/project-index view report.pdf
102
92
  ```
103
93
 
104
- Prefix a target with `stdin:` to analyze an unsaved buffer while retaining a path
105
- for language detection and cursor addressing. This works with `detect`, `read`,
106
- `map`, `check`, `symbol`, and `identify`:
94
+ Prefix a target with `stdin:` to analyze an unsaved buffer while retaining a
95
+ path for language detection and cursor addressing. This works with `detect`,
96
+ `read`, `map`, `check`, `symbol`, and `identify`:
107
97
 
108
98
  ```sh
109
99
  printf '%s\n' 'fn main() {}' | readseek identify stdin:scratch.rs:1 --column 4
@@ -111,73 +101,104 @@ printf '%s\n' 'fn main() {}' | readseek identify stdin:scratch.rs:1 --column 4
111
101
 
112
102
  ## Images and PDFs
113
103
 
114
- `detect` reports image metadata and PDF page counts. `read` returns bounded base64
115
- images by default; select local analysis with `--vision-mode`:
104
+ `detect` reports image metadata and PDF page counts. An image read returns a
105
+ bounded base64 payload by default. Select local analysis explicitly:
116
106
 
117
107
  ```sh
118
- readseek read photo.jpg # default: bounded base64 image
119
- readseek read photo.jpg --vision-mode caption # detailed natural-language caption
120
- readseek read photo.jpg --vision-mode objects # object labels + bounding boxes
121
- readseek read photo.jpg --vision-mode ocr # extracted text
122
- readseek read photo.jpg --vision-mode all # caption, objects, and OCR in one pass
108
+ readseek read photo.jpg --vision-mode caption
109
+ readseek read photo.jpg --vision-mode objects
110
+ readseek read scan.png --vision-mode ocr --vision-level high
111
+ readseek read photo.jpg --vision-mode all
123
112
  ```
124
113
 
125
- Vision analysis uses the `low` level by default. Start at `low`, then increase to
126
- `medium` or `high` only when additional detail is needed:
114
+ Vision modes are `none`, `caption`, `objects`, `ocr`, and `all`. Analysis starts
115
+ at the `low` level; use `medium` or `high` only when more detail is needed.
116
+
117
+ PDF reads return page-tagged Markdown plus embedded images. `--page` selects a
118
+ page, and `--vision-mode` applies to its images:
127
119
 
128
120
  ```sh
129
- readseek read photo.jpg --vision-mode caption --vision-level low
130
- readseek read scan.png --vision-mode ocr --vision-level high
121
+ readseek read report.pdf --page 3 --vision-mode ocr
122
+ readseek init
123
+ readseek view report.pdf
124
+ readseek view report.pdf --page 3 --outline
131
125
  ```
132
126
 
133
- Set `RUST_LOG=tracing` to emit vision cache and inference traces on standard error.
127
+ `view` creates or reuses a structural PDF index and can narrow it by page, node,
128
+ kind, or depth. Line/hash suffixes and source range/language options do not apply
129
+ to images or PDFs.
134
130
 
135
- Run `cargo bench --features vision-bench --bench vision` for data-driven comparisons
136
- defined in `benches/vision.txt`.
131
+ The pinned Qwen3-VL-2B-Instruct Q4_K_M model and Q8_0 multimodal projector are
132
+ downloaded lazily, checksum-verified, and run by ReadSeek's CPU inference engine.
133
+ Set `READSEEK_VISION_THREADS` to override Rayon's worker count. Set
134
+ `RUST_LOG=tracing=trace` for cache and inference traces.
137
135
 
138
- Set `READSEEK_VISION_THREADS` to a positive integer to override Rayon's worker
139
- count. More workers may improve throughput at the cost of CPU and memory.
136
+ For repeatable vision comparisons:
140
137
 
141
- PDF reads return page-tagged Markdown and embedded images. Use `--page` to select a
142
- page; `--vision-mode` applies to each embedded image. After `readseek init`, `view` creates
143
- or reuses a structural PDF index that can be narrowed by page, node, kind, or depth.
144
- Line/hash suffixes, `--end`, `--limit`, and `--language` do not apply to visual files.
138
+ ```sh
139
+ cargo bench --features vision-bench --bench vision
140
+ ```
145
141
 
146
- The Qwen3-VL-2B Q4_K_M model and Q8_0 multimodal projector download lazily to the user
147
- cache and are checksum-verified. Inference uses ReadSeek's built-in CPU engine and
148
- can be slow.
142
+ Benchmark cases live in `benches/vision.txt`.
149
143
 
150
- ## Cache
144
+ ## Cache layout
151
145
 
152
- `readseek init [path]` creates `.readseek/maps/` and `.readseek/def-index/`.
153
- Map-dependent commands update them on demand and find `.readseek/` by walking up
154
- from the target; `--readseek-dir` selects one explicitly. PDF indexes and extracted
155
- assets live in `.readseek/documents/`, while image analysis results are cached under
156
- `.readseek/vision/`. Image cache entries are level-specific.
146
+ `readseek init [path]` creates `.readseek/` and refreshes its source indexes.
147
+ Commands discover that directory by walking up from the target; use
148
+ `--readseek-dir` to select one explicitly.
157
149
 
158
- ## Documentation
150
+ | Path | Contents |
151
+ | --- | --- |
152
+ | `.readseek/maps/` | Content-addressed source maps |
153
+ | `.readseek/def-index/` | Definition index |
154
+ | `.readseek/documents/` | PDF indexes and extracted assets |
155
+ | `.readseek/vision/` | Level-specific image analysis results |
156
+ | User cache `readseek/models/` | Downloaded vision model files |
159
157
 
160
- For the complete CLI reference:
158
+ ## Development
161
159
 
162
160
  ```sh
163
- man ./man/man1/readseek.1
161
+ cargo test
162
+ cargo clippy --all-targets
163
+ cargo fmt --check
164
+ ```
165
+
166
+ Integration-specific checks:
167
+
168
+ ```sh
169
+ (cd packages/pi-readseek && npm run typecheck && npm test)
170
+ (cd packages/opencode-readseek && bun run typecheck && bun test)
171
+ (cd packages/claude-readseek && npm run typecheck && npm test)
172
+ vim -Nu NONE -n -i NONE -es -S test/readseek.vim
173
+ ```
174
+
175
+ The Claude marketplace-install test downloads the pinned npm package but makes
176
+ no API calls, so it runs in CI:
177
+
178
+ ```sh
179
+ cd packages/claude-readseek
180
+ npm run test:install
164
181
  ```
165
182
 
166
- Pass `--help` to any command for command-specific usage.
183
+ ## Reference
184
+
185
+ Run `readseek --help` or `readseek <command> --help`. To read the complete local
186
+ manual:
187
+
188
+ ```sh
189
+ man ./man/man1/readseek.1
190
+ ```
167
191
 
168
- ## Licensing
192
+ ## License
169
193
 
170
- 1. `claude-readseek`: Apache 2.0
171
- 2. `opencode-readseek`: Apache 2.0
172
- 3. `pi-readseek`: Apache 2.0
173
- 4. `readseek`: LGPL 2.1+
174
- 5. `readseek.vim`: Apache 2.0
194
+ - Native `readseek`: LGPL-2.1-or-later
195
+ - `@jarkkojs/readseek` npm wrapper: Apache-2.0 AND LGPL-2.1-or-later
196
+ - `pi-readseek`, `opencode-readseek`, and `claude-readseek`: Apache-2.0
197
+ - `readseek.vim`: MIT
175
198
 
176
- ### Third Party Attribution
199
+ ### Third-party attribution
177
200
 
178
- 1. Qwen3-VL-2B: Apache 2.0
179
- - Downloaded on first use at run-time. The model is not distributed together
180
- with ReadSeek.
181
- 2. [Dwarf Seek 4](https://github.com/antirez/ds4): MIT
182
- - Q4\_K and Q6\_K block decoding and dot-product implementation are derived
183
- works of DS4.
201
+ - Qwen3-VL-2B-Instruct: Apache-2.0. Model files are downloaded at runtime and
202
+ are not distributed with ReadSeek.
203
+ - [Dwarf Seek 4](https://github.com/antirez/ds4): MIT. ReadSeek's Q4_K and Q6_K
204
+ block decoding and dot-product code includes derived work.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@jarkkojs/readseek",
3
- "version": "0.8.17",
4
- "description": "A structural read command",
3
+ "version": "0.8.19",
4
+ "description": "Structural source, image, and PDF reader with stable line hashes",
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.17",
25
- "@jarkkojs/readseek-linux-arm64": "0.8.17",
26
- "@jarkkojs/readseek-linux-x64": "0.8.17",
27
- "@jarkkojs/readseek-win32-x64": "0.8.17"
24
+ "@jarkkojs/readseek-darwin-arm64": "0.8.19",
25
+ "@jarkkojs/readseek-linux-arm64": "0.8.19",
26
+ "@jarkkojs/readseek-linux-x64": "0.8.19",
27
+ "@jarkkojs/readseek-win32-x64": "0.8.19"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public"