@jarkkojs/readseek 0.9.12 → 0.9.14
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.
- package/README.md +17 -224
- package/package.json +8 -5
package/README.md
CHANGED
|
@@ -1,237 +1,30 @@
|
|
|
1
1
|
# ReadSeek
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
3
|
+
ReadSeek is a structural code and document navigation tool.
|
|
7
4
|
|
|
8
5
|
## Install
|
|
9
6
|
|
|
10
|
-
|
|
7
|
+
Install the command-line tool from npm:
|
|
11
8
|
|
|
12
9
|
```sh
|
|
13
|
-
npm install
|
|
14
|
-
|
|
15
|
-
make install # build this checkout and install the CLI + man page
|
|
10
|
+
npm install --global @jarkkojs/readseek
|
|
11
|
+
readseek --version
|
|
16
12
|
```
|
|
17
13
|
|
|
18
|
-
|
|
19
|
-
available for macOS ARM64, Linux ARM64/x64, and Windows x64; Linux builds are
|
|
20
|
-
statically linked with musl.
|
|
14
|
+
## Editor and agent integrations
|
|
21
15
|
|
|
22
|
-
|
|
16
|
+
| Integration | Package | Documentation |
|
|
17
|
+
| -------------- | ------------------------ | -------------------------------------------------------------------- |
|
|
18
|
+
| Claude Code | `claude-readseek` | [`packages/claude-readseek`](packages/claude-readseek/README.md) |
|
|
19
|
+
| OpenCode | `opencode-readseek` | [`packages/opencode-readseek`](packages/opencode-readseek/README.md) |
|
|
20
|
+
| Pi | `pi-readseek` | [`packages/pi-readseek`](packages/pi-readseek/README.md) |
|
|
21
|
+
| TypeScript API | `@jarkkojs/readseek-api` | [`packages/readseek-api`](packages/readseek-api/README.md) |
|
|
22
|
+
| Vim 9 | `readseek.vim` | [`doc/readseek.txt`](doc/readseek.txt) |
|
|
23
23
|
|
|
24
|
-
|
|
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
|
+
## Licensing
|
|
30
25
|
|
|
31
|
-
|
|
26
|
+
`readseek` is free software under the GNU Lesser General Public License
|
|
27
|
+
version 2.1 or later (LGPL-2.1+). See [LICENSE-LGPL-2.1](LICENSE-LGPL-2.1).
|
|
32
28
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
- Prefer ReadSeek over regular read, edit, and grep tool commands.
|
|
37
|
-
- Use ReadSeek extensively and proactively.
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## CLI tour
|
|
41
|
-
|
|
42
|
-
### Digest
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
readseek digest src/main.rs --at line:10 --end 20
|
|
46
|
-
readseek digest src/main.rs --at symbol:run
|
|
47
|
-
readseek digest src/main.rs --select metadata,map,diagnostics
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
`digest` always returns `metadata` plus the requested facets. `content` is the
|
|
51
|
-
default; facets are combined with a comma.
|
|
52
|
-
|
|
53
|
-
Source reads emit records such as `42:a1b|let value = parse(input);`. The line
|
|
54
|
-
number locates the text; the short hash rejects most stale edits while tolerating
|
|
55
|
-
whitespace-only changes.
|
|
56
|
-
|
|
57
|
-
### Search and navigate
|
|
58
|
-
|
|
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 --at line:42:8
|
|
63
|
-
readseek search src 'fn $NAME() { $$$BODY }' --language rust
|
|
64
|
-
readseek search manual.pdf 'revocation' --limit 20
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
`def`, `refs`, and `search` accept a file or directory. In a Git work tree,
|
|
68
|
-
directory searches include tracked/indexed and untracked non-ignored files by
|
|
69
|
-
default. Use `--git cached`, `--git others`, or both to restrict the set;
|
|
70
|
-
`ignored` requires `others`.
|
|
71
|
-
|
|
72
|
-
### Edit
|
|
73
|
-
|
|
74
|
-
`edit` verifies all anchors and rejects stale or overlapping operations before
|
|
75
|
-
writing. Requests are JSON files, or JSON on stdin by default:
|
|
76
|
-
|
|
77
|
-
```sh
|
|
78
|
-
readseek edit src/main.rs --request edits.json
|
|
79
|
-
readseek edit src/main.rs --request edits.json --apply --plan-hash <plan_hash>
|
|
80
|
-
printf '%s' '{"edits":[{"set_line":{"anchor":"42:a1b","new_text":"let value = 2;"}}]}' \
|
|
81
|
-
| readseek edit src/main.rs --apply
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
A dry run returns the planned content and a `plan_hash`. Passing that hash during
|
|
85
|
-
apply prevents a changed plan from being written.
|
|
86
|
-
|
|
87
|
-
Requests support anchored line replacement, range replacement, insertion, exact
|
|
88
|
-
text replacement, and whole-symbol replacement. An empty `new_text` deletes an
|
|
89
|
-
anchored line or range. `--language` overrides detection for symbol replacement.
|
|
90
|
-
|
|
91
|
-
### Rename
|
|
92
|
-
|
|
93
|
-
A rename is a dry run unless `--apply` is present:
|
|
94
|
-
|
|
95
|
-
```sh
|
|
96
|
-
readseek rename src/main.rs --at line:42:8 --to renamed
|
|
97
|
-
readseek rename src/main.rs --at line:42:8 --to renamed --apply
|
|
98
|
-
readseek rename src/main.rs --at line:42 --to renamed --workspace . --apply
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
Rename plans report conflicts and hash-verified edits. Workspace mode extends the
|
|
102
|
-
plan beyond the cursor file.
|
|
103
|
-
|
|
104
|
-
### Global options and stdin
|
|
105
|
-
|
|
106
|
-
Global options must precede the command:
|
|
107
|
-
|
|
108
|
-
```sh
|
|
109
|
-
readseek --output result.json digest src/main.rs --select metadata
|
|
110
|
-
readseek --readseek-dir /tmp/project-index view report.pdf
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
Pass `-` as the path to read standard input. Use `--stdin-name` when a virtual
|
|
114
|
-
path is needed for language detection or reporting. This works with `digest`
|
|
115
|
-
and `view`:
|
|
116
|
-
|
|
117
|
-
```sh
|
|
118
|
-
printf '%s\n' 'fn main() {}' |
|
|
119
|
-
readseek digest - --stdin-name scratch.rs --select identity --at line:1:4
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
## Images and documents
|
|
123
|
-
|
|
124
|
-
`digest` reports image metadata and can return a bounded base64 image payload.
|
|
125
|
-
Select local analysis explicitly:
|
|
126
|
-
|
|
127
|
-
```sh
|
|
128
|
-
readseek digest scan.png --vision-mode ocr --vision-level high
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
Vision modes are `none`, `caption`, `objects`, `ocr`, and `all`. Analysis starts
|
|
132
|
-
at the `low` level; use `medium` or `high` only when more detail is needed.
|
|
133
|
-
|
|
134
|
-
PDF is the first supported document format. Document digestion ingests the
|
|
135
|
-
whole document into the content-addressed structural cache and returns a JSON
|
|
136
|
-
receipt whose state is `built` or `reused`. This makes `digest` suitable for
|
|
137
|
-
cache-warming jobs. It does not return document pages or assets.
|
|
138
|
-
|
|
139
|
-
```sh
|
|
140
|
-
readseek init
|
|
141
|
-
readseek digest report.pdf
|
|
142
|
-
readseek view report.pdf --page 3
|
|
143
|
-
readseek view report.pdf --page 3 --vision-mode ocr
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
`view` is the document-content interface. It creates the same cache on a miss,
|
|
147
|
-
then narrows the indexed structure by page, node, kind, or depth. Vision modes
|
|
148
|
-
analyze the selected cached assets. `--at` and source range/language options do
|
|
149
|
-
not apply to images or documents.
|
|
150
|
-
|
|
151
|
-
Image analysis runs locally on the CPU with
|
|
152
|
-
[Qwen3-VL-2B-Instruct](docs/models/qwen3-vl-2b-instruct.md). Its model files are
|
|
153
|
-
downloaded and checksum-verified on first use.
|
|
154
|
-
|
|
155
|
-
## Cache layout
|
|
156
|
-
|
|
157
|
-
`readseek init [path]` creates `.readseek/` and refreshes its source indexes.
|
|
158
|
-
Commands discover that directory by walking up from the target; use
|
|
159
|
-
`--readseek-dir` to select one explicitly.
|
|
160
|
-
|
|
161
|
-
| Path | Contents |
|
|
162
|
-
| ----------------------------- | ------------------------------------- |
|
|
163
|
-
| `.readseek/maps/` | Content-addressed source maps |
|
|
164
|
-
| `.readseek/def-index/` | Definition index |
|
|
165
|
-
| `.readseek/documents/` | Document indexes and extracted assets |
|
|
166
|
-
| `.readseek/vision/` | Level-specific image analysis results |
|
|
167
|
-
| User cache `readseek/models/` | Downloaded vision model files |
|
|
168
|
-
|
|
169
|
-
## Development
|
|
170
|
-
|
|
171
|
-
### Check
|
|
172
|
-
|
|
173
|
-
```sh
|
|
174
|
-
make ci
|
|
175
|
-
CI_MSRV=1 make ci # optional MSRV check
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
### Package
|
|
179
|
-
|
|
180
|
-
Packages the **highest semver tag reachable from HEAD** on the current branch
|
|
181
|
-
(not necessarily the tip). Source is built from a detached worktree at that
|
|
182
|
-
tag; this packaging script stays on tip so tooling fixes apply without a new
|
|
183
|
-
tag. Artifacts land in `npm/*/bin` and `artifacts/` on the caller tree.
|
|
184
|
-
|
|
185
|
-
Linux x64/arm64 and Windows x64 use [`cross`](https://github.com/cross-rs/cross)
|
|
186
|
-
and Docker. On Apple Silicon with Dory, x86_64 images run under FEX; packaging
|
|
187
|
-
reaps the container if FEX leaves it stuck after cargo finishes.
|
|
188
|
-
Cross builds default to `CARGO_BUILD_JOBS=1` on Darwin to avoid FEX/virtiofs
|
|
189
|
-
rlib corruption (override with `CARGO_BUILD_JOBS`).
|
|
190
|
-
|
|
191
|
-
`darwin-arm64` builds with host `cargo` when packaging on darwin-arm64. From
|
|
192
|
-
Linux, the same platform uses the local osxcross image
|
|
193
|
-
`ghcr.io/cross-rs/aarch64-apple-darwin-cross:local` (Apple SDK; not redistributed).
|
|
194
|
-
|
|
195
|
-
```sh
|
|
196
|
-
make package
|
|
197
|
-
make package PLATFORMS='linux-x64 win32-x64'
|
|
198
|
-
PACKAGE_STRICT=1 make package
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
### Release
|
|
202
|
-
|
|
203
|
-
After `scripts/release.sh <version>` and pushing the tag:
|
|
204
|
-
|
|
205
|
-
```sh
|
|
206
|
-
make ci
|
|
207
|
-
PACKAGE_STRICT=1 make package
|
|
208
|
-
make publish
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
`make publish` uses the highest semver tag reachable from HEAD (tip may be
|
|
212
|
-
ahead). It publishes crates.io from that tagged tree, npm from local
|
|
213
|
-
`npm/*/bin` artifacts, then uploads GitLab release tarballs when `glab` is
|
|
214
|
-
available.
|
|
215
|
-
|
|
216
|
-
## Reference
|
|
217
|
-
|
|
218
|
-
Run `readseek --help` or `readseek <command> --help`. To read the complete local
|
|
219
|
-
manual:
|
|
220
|
-
|
|
221
|
-
```sh
|
|
222
|
-
man ./man/man1/readseek.1
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
## License
|
|
226
|
-
|
|
227
|
-
- Native `readseek`: LGPL-2.1-or-later
|
|
228
|
-
- `@jarkkojs/readseek` npm wrapper: Apache-2.0 AND LGPL-2.1-or-later
|
|
229
|
-
- `pi-readseek`, `opencode-readseek`, and `claude-readseek`: Apache-2.0
|
|
230
|
-
- `readseek.vim`: MIT
|
|
231
|
-
|
|
232
|
-
### Third-party attribution
|
|
233
|
-
|
|
234
|
-
- Qwen3-VL-2B-Instruct: Apache-2.0. Model files are downloaded at runtime and
|
|
235
|
-
are not distributed with ReadSeek.
|
|
236
|
-
- [Dwarf Seek 4](https://github.com/antirez/ds4): MIT. ReadSeek's Q4_K and Q6_K
|
|
237
|
-
block decoding and dot-product code includes derived work.
|
|
29
|
+
Coding and text editor plugins use Apache 2.0. See
|
|
30
|
+
[LICENSE-APACHE-2.0](LICENSE-APACHE-2.0).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jarkkojs/readseek",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.14",
|
|
4
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://gitlab.com/jarkkojs/readseek#readme",
|
|
@@ -20,11 +20,14 @@
|
|
|
20
20
|
"LICENSE-APACHE-2.0",
|
|
21
21
|
"LICENSE-LGPL-2.1"
|
|
22
22
|
],
|
|
23
|
+
"workspaces": [
|
|
24
|
+
"packages/*"
|
|
25
|
+
],
|
|
23
26
|
"optionalDependencies": {
|
|
24
|
-
"@jarkkojs/readseek-darwin-arm64": "0.9.
|
|
25
|
-
"@jarkkojs/readseek-linux-arm64": "0.9.
|
|
26
|
-
"@jarkkojs/readseek-linux-x64": "0.9.
|
|
27
|
-
"@jarkkojs/readseek-win32-x64": "0.9.
|
|
27
|
+
"@jarkkojs/readseek-darwin-arm64": "0.9.14",
|
|
28
|
+
"@jarkkojs/readseek-linux-arm64": "0.9.14",
|
|
29
|
+
"@jarkkojs/readseek-linux-x64": "0.9.14",
|
|
30
|
+
"@jarkkojs/readseek-win32-x64": "0.9.14"
|
|
28
31
|
},
|
|
29
32
|
"publishConfig": {
|
|
30
33
|
"access": "public"
|