@jarkkojs/readseek 0.8.18 → 0.8.20

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 +115 -121
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,109 +1,89 @@
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
+ ## CLI tour
32
32
 
33
- ## Plugins
34
-
35
- ### Pi extension
36
-
37
- The bundled [pi-readseek extension](packages/pi-readseek/README.md) adds ReadSeek's
38
- anchored file and structural-code tools to Pi:
33
+ ### Read and inspect
39
34
 
40
35
  ```sh
41
- pi install npm:pi-readseek
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
42
42
  ```
43
43
 
44
- ### OpenCode plugin
44
+ Source reads emit records such as `42:a1b|let value = parse(input);`. The line
45
+ number locates the text; the short hash rejects most stale edits while tolerating
46
+ whitespace-only changes.
45
47
 
46
- The [opencode-readseek plugin](packages/opencode-readseek/README.md) adds the same
47
- tools to OpenCode. Add it to `opencode.json`:
48
+ ### Search and navigate
48
49
 
49
- ```json
50
- {
51
- "plugin": ["opencode-readseek"]
52
- }
50
+ ```sh
51
+ readseek def src run --language rust --format plain
52
+ readseek refs src run --language rust --format plain
53
+ readseek refs src/main.rs run --scope --line 42 --column 8
54
+ readseek search src 'fn $NAME() { $$$BODY }' --language rust
53
55
  ```
54
56
 
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
72
-
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.
57
+ `def`, `refs`, and `search` accept a file or directory. In a Git work tree,
58
+ directory searches include tracked/indexed and untracked non-ignored files by
59
+ default. Use `--git cached`, `--git others`, or both to restrict the set;
60
+ `ignored` requires `others`.
76
61
 
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.
62
+ ### Rename
80
63
 
81
- ## Common commands
64
+ A rename is a dry run unless `--apply` is present:
82
65
 
83
66
  ```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
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
96
70
  ```
97
71
 
98
- Global options must precede the command. For example, write JSON to a file with:
72
+ Rename plans report conflicts and hash-verified edits. Workspace mode extends the
73
+ plan beyond the cursor file.
74
+
75
+ ### Global options and stdin
76
+
77
+ Global options must precede the command:
99
78
 
100
79
  ```sh
101
80
  readseek --output result.json detect src/main.rs
81
+ readseek --readseek-dir /tmp/project-index view report.pdf
102
82
  ```
103
83
 
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`:
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`:
107
87
 
108
88
  ```sh
109
89
  printf '%s\n' 'fn main() {}' | readseek identify stdin:scratch.rs:1 --column 4
@@ -111,73 +91,87 @@ printf '%s\n' 'fn main() {}' | readseek identify stdin:scratch.rs:1 --column 4
111
91
 
112
92
  ## Images and PDFs
113
93
 
114
- `detect` reports image metadata and PDF page counts. `read` returns bounded base64
115
- images by default; select local analysis with `--vision-mode`:
94
+ `detect` reports image metadata and PDF page counts. An image read returns a
95
+ bounded base64 payload by default. Select local analysis explicitly:
116
96
 
117
97
  ```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
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
123
102
  ```
124
103
 
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:
104
+ Vision modes are `none`, `caption`, `objects`, `ocr`, and `all`. Analysis starts
105
+ at the `low` level; use `medium` or `high` only when more detail is needed.
106
+
107
+ PDF reads return page-tagged Markdown plus embedded images. `--page` selects a
108
+ page, and `--vision-mode` applies to its images:
127
109
 
128
110
  ```sh
129
- readseek read photo.jpg --vision-mode caption --vision-level low
130
- readseek read scan.png --vision-mode ocr --vision-level high
111
+ readseek read report.pdf --page 3 --vision-mode ocr
112
+ readseek init
113
+ readseek view report.pdf
114
+ readseek view report.pdf --page 3 --outline
131
115
  ```
132
116
 
133
- Set `RUST_LOG=tracing` to emit vision cache and inference traces on standard error.
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.
120
+
121
+ Image analysis runs locally on the CPU with
122
+ [Qwen3-VL-2B-Instruct](docs/models/qwen3-vl-2b-instruct.md). Its model files are
123
+ downloaded and checksum-verified on first use.
124
+
125
+ ## Cache layout
134
126
 
135
- Run `cargo bench --features vision-bench --bench vision` for data-driven comparisons
136
- defined in `benches/vision.txt`.
127
+ `readseek init [path]` creates `.readseek/` and refreshes its source indexes.
128
+ Commands discover that directory by walking up from the target; use
129
+ `--readseek-dir` to select one explicitly.
137
130
 
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.
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 |
140
138
 
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.
139
+ ## Development
145
140
 
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.
141
+ ```sh
142
+ cargo test
143
+ cargo clippy --all-targets
144
+ cargo fmt --check
145
+ ```
149
146
 
150
- ## Cache
147
+ Integration-specific checks:
151
148
 
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.
149
+ ```sh
150
+ (cd packages/pi-readseek && npm run typecheck && npm test)
151
+ (cd packages/opencode-readseek && bun run typecheck && bun test)
152
+ (cd packages/claude-readseek && npm run typecheck && npm test)
153
+ vim -Nu NONE -n -i NONE -es -S test/readseek.vim
154
+ ```
157
155
 
158
- ## Documentation
156
+ ## Reference
159
157
 
160
- For the complete CLI reference:
158
+ Run `readseek --help` or `readseek <command> --help`. To read the complete local
159
+ manual:
161
160
 
162
161
  ```sh
163
162
  man ./man/man1/readseek.1
164
163
  ```
165
164
 
166
- Pass `--help` to any command for command-specific usage.
167
-
168
- ## Licensing
165
+ ## License
169
166
 
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
167
+ - Native `readseek`: LGPL-2.1-or-later
168
+ - `@jarkkojs/readseek` npm wrapper: Apache-2.0 AND LGPL-2.1-or-later
169
+ - `pi-readseek`, `opencode-readseek`, and `claude-readseek`: Apache-2.0
170
+ - `readseek.vim`: MIT
175
171
 
176
- ### Third Party Attribution
172
+ ### Third-party attribution
177
173
 
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.
174
+ - Qwen3-VL-2B-Instruct: Apache-2.0. Model files are downloaded at runtime and
175
+ are not distributed with ReadSeek.
176
+ - [Dwarf Seek 4](https://github.com/antirez/ds4): MIT. ReadSeek's Q4_K and Q6_K
177
+ 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.18",
4
- "description": "A structural read command",
3
+ "version": "0.8.20",
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.18",
25
- "@jarkkojs/readseek-linux-arm64": "0.8.18",
26
- "@jarkkojs/readseek-linux-x64": "0.8.18",
27
- "@jarkkojs/readseek-win32-x64": "0.8.18"
24
+ "@jarkkojs/readseek-darwin-arm64": "0.8.20",
25
+ "@jarkkojs/readseek-linux-arm64": "0.8.20",
26
+ "@jarkkojs/readseek-linux-x64": "0.8.20",
27
+ "@jarkkojs/readseek-win32-x64": "0.8.20"
28
28
  },
29
29
  "publishConfig": {
30
30
  "access": "public"