opencode-ipynb 0.1.2 → 3.0.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.
- package/CHANGELOG.md +187 -0
- package/README.md +197 -41
- package/dist/domain/cell.d.ts +4 -3
- package/dist/domain/errors.d.ts +3 -31
- package/dist/domain/execution.d.ts +4 -1
- package/dist/domain/notebook.d.ts +6 -3
- package/dist/domain/output.d.ts +0 -1
- package/dist/format/diagnostics.d.ts +0 -1
- package/dist/format/markdown.d.ts +1 -2
- package/dist/format/{diff.d.ts → notebook.d.ts} +1 -1
- package/dist/format/outputs.d.ts +2 -2
- package/dist/index.d.ts +3 -1
- package/dist/index.js +11294 -28152
- package/dist/load-document.d.ts +10 -0
- package/dist/lsp.d.ts +58 -0
- package/dist/lsp.js +172 -0
- package/dist/notebook-diagnostics.d.ts +52 -0
- package/dist/notebook-hooks.d.ts +18 -0
- package/dist/plugin-options.d.ts +4 -1
- package/dist/plugin-v2.d.ts +31 -0
- package/dist/plugin.d.ts +2 -3
- package/dist/registrations.d.ts +5 -0
- package/dist/rpc.d.ts +134 -0
- package/dist/rpc.js +84 -0
- package/dist/services/KernelManager.d.ts +45 -0
- package/dist/services/NotebookCleanService.d.ts +7 -7
- package/dist/services/NotebookEditService.d.ts +15 -12
- package/dist/services/NotebookExecutionService.d.ts +41 -12
- package/dist/services/NotebookExportService.d.ts +3 -7
- package/dist/services/NotebookFileService.d.ts +31 -16
- package/dist/services/NotebookInspectService.d.ts +15 -19
- package/dist/services/NotebookOutputService.d.ts +7 -10
- package/dist/services/NotebookReadService.d.ts +4 -10
- package/dist/services/PathService.d.ts +10 -8
- package/dist/services/PermissionService.d.ts +13 -8
- package/dist/services/PythonService.d.ts +14 -43
- package/dist/services/index.d.ts +23 -28
- package/dist/services/revision.d.ts +9 -0
- package/dist/tool.d.ts +45 -0
- package/dist/tools/_readPermission.d.ts +2 -0
- package/dist/tools/_resolveOptions.d.ts +13 -2
- package/dist/tools/cell_delete.d.ts +4 -13
- package/dist/tools/cell_insert.d.ts +10 -21
- package/dist/tools/cell_move.d.ts +5 -15
- package/dist/tools/clean.d.ts +8 -21
- package/dist/tools/doctor.d.ts +3 -11
- package/dist/tools/edit.d.ts +10 -21
- package/dist/tools/export.d.ts +12 -23
- package/dist/tools/inspect.d.ts +7 -19
- package/dist/tools/kernel.d.ts +13 -21
- package/dist/tools/lsp.d.ts +9 -0
- package/dist/tools/outputs.d.ts +15 -29
- package/dist/tools/read.d.ts +12 -29
- package/dist/tools/repro.d.ts +6 -14
- package/dist/tools/run.d.ts +17 -34
- package/dist/utils/ansi.d.ts +1 -1
- package/dist/utils/atomic-replace.d.ts +2 -0
- package/dist/utils/attachments.d.ts +2 -3
- package/dist/utils/execution-order.d.ts +7 -0
- package/dist/utils/fence.d.ts +1 -0
- package/dist/utils/i18n.d.ts +1 -2
- package/dist/utils/imports.d.ts +0 -1
- package/dist/utils/json-patch.d.ts +58 -0
- package/dist/utils/json.d.ts +16 -2
- package/dist/utils/limits.d.ts +11 -2
- package/dist/utils/markdown-safe.d.ts +2 -0
- package/dist/utils/metadata.d.ts +2 -0
- package/dist/utils/mime.d.ts +1 -1
- package/dist/utils/paths.d.ts +2 -2
- package/dist/utils/realpath.d.ts +1 -0
- package/dist/utils/rename-hook.d.ts +6 -0
- package/dist/utils/truncate.d.ts +0 -1
- package/dist/utils/warnings.d.ts +15 -0
- package/dist/utils/windows.d.ts +3 -0
- package/dist/virtual-materialize.d.ts +25 -0
- package/package.json +30 -18
- package/python/ipynb_runner.py +418 -31
- package/python/requirements.txt +5 -4
- package/server.js +3 -0
- package/dist/domain/cell.d.ts.map +0 -1
- package/dist/domain/errors.d.ts.map +0 -1
- package/dist/domain/execution.d.ts.map +0 -1
- package/dist/domain/notebook.d.ts.map +0 -1
- package/dist/domain/output.d.ts.map +0 -1
- package/dist/format/diagnostics.d.ts.map +0 -1
- package/dist/format/diff.d.ts.map +0 -1
- package/dist/format/markdown.d.ts.map +0 -1
- package/dist/format/outputs.d.ts.map +0 -1
- package/dist/index.d.ts.map +0 -1
- package/dist/plugin-options.d.ts.map +0 -1
- package/dist/plugin.d.ts.map +0 -1
- package/dist/services/DiffService.d.ts +0 -17
- package/dist/services/DiffService.d.ts.map +0 -1
- package/dist/services/NotebookCleanService.d.ts.map +0 -1
- package/dist/services/NotebookEditService.d.ts.map +0 -1
- package/dist/services/NotebookExecutionService.d.ts.map +0 -1
- package/dist/services/NotebookExportService.d.ts.map +0 -1
- package/dist/services/NotebookFileService.d.ts.map +0 -1
- package/dist/services/NotebookInspectService.d.ts.map +0 -1
- package/dist/services/NotebookOutputService.d.ts.map +0 -1
- package/dist/services/NotebookReadService.d.ts.map +0 -1
- package/dist/services/PathService.d.ts.map +0 -1
- package/dist/services/PermissionService.d.ts.map +0 -1
- package/dist/services/PythonService.d.ts.map +0 -1
- package/dist/services/index.d.ts.map +0 -1
- package/dist/tools/_resolveOptions.d.ts.map +0 -1
- package/dist/tools/cell_delete.d.ts.map +0 -1
- package/dist/tools/cell_insert.d.ts.map +0 -1
- package/dist/tools/cell_move.d.ts.map +0 -1
- package/dist/tools/clean.d.ts.map +0 -1
- package/dist/tools/doctor.d.ts.map +0 -1
- package/dist/tools/edit.d.ts.map +0 -1
- package/dist/tools/export.d.ts.map +0 -1
- package/dist/tools/inspect.d.ts.map +0 -1
- package/dist/tools/kernel.d.ts.map +0 -1
- package/dist/tools/outputs.d.ts.map +0 -1
- package/dist/tools/read.d.ts.map +0 -1
- package/dist/tools/repro.d.ts.map +0 -1
- package/dist/tools/run.d.ts.map +0 -1
- package/dist/utils/ansi.d.ts.map +0 -1
- package/dist/utils/attachments.d.ts.map +0 -1
- package/dist/utils/fiber.d.ts +0 -2
- package/dist/utils/fiber.d.ts.map +0 -1
- package/dist/utils/i18n.d.ts.map +0 -1
- package/dist/utils/imports.d.ts.map +0 -1
- package/dist/utils/json.d.ts.map +0 -1
- package/dist/utils/limits.d.ts.map +0 -1
- package/dist/utils/mime.d.ts.map +0 -1
- package/dist/utils/paths.d.ts.map +0 -1
- package/dist/utils/truncate.d.ts.map +0 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 3.0.0
|
|
4
|
+
|
|
5
|
+
Byte-stable writes, a hardened tool boundary, and measured performance. The one
|
|
6
|
+
breaking change for existing callers is `ipynb_export`'s output extension; it is
|
|
7
|
+
first so it is easy to find.
|
|
8
|
+
|
|
9
|
+
### Breaking
|
|
10
|
+
|
|
11
|
+
- `ipynb_export` refuses an `outputPath` that does not end in `.md`, `.markdown`,
|
|
12
|
+
`.py`, `.txt` or `.rst` (after the win32 trailing dot/space normalization).
|
|
13
|
+
Previously any path that was not a `.ipynb` was written, which let a mistaken
|
|
14
|
+
prompt overwrite `.env`, `package.json` or a key file; the tool description
|
|
15
|
+
states the restriction.
|
|
16
|
+
|
|
17
|
+
### Correctness
|
|
18
|
+
|
|
19
|
+
- Writes are byte-stable (issue #2): the zod schemas validate only, and the raw
|
|
20
|
+
`JSON.parse` object is passed through unchanged (`applyNotebookDefaults` is
|
|
21
|
+
pure and returns a clone), so no write re-emits the notebook in
|
|
22
|
+
schema-declaration order. `src/utils/json-patch.ts` splices only the changed
|
|
23
|
+
values into the stored text, so untouched bytes keep their key order, layout,
|
|
24
|
+
escapes, and number literals.
|
|
25
|
+
- `ipynb_edit` mirrors the stored `source` shape: a notebook that stores line
|
|
26
|
+
arrays keeps line arrays (split like nbformat/`splitlines(keepends=True)`); a
|
|
27
|
+
single-string notebook keeps one string. Inserted cells inherit the shape of
|
|
28
|
+
the notebook's first cell.
|
|
29
|
+
- `ipynb_run save=true` splits the `stream.text`/text-mime strings that
|
|
30
|
+
`nbformat.read` rejoins when the notebook stores `source` as line arrays, so
|
|
31
|
+
saving outputs does not reflow those outputs.
|
|
32
|
+
- `ipynb_run save=true` gives every cell its own share of `maxOutputChars`
|
|
33
|
+
instead of draining one pool: later cells used to be persisted with empty
|
|
34
|
+
`stdout` over real output. Raw MIME bundles are persisted verbatim, so a
|
|
35
|
+
`text/html` or `image/png` display data survives a save instead of being
|
|
36
|
+
replaced by a `text/plain` summary.
|
|
37
|
+
- Defaulted keys (`metadata`, cell `outputs`) are inserted in sorted position
|
|
38
|
+
when the object's keys are already sorted, and appended otherwise, so an
|
|
39
|
+
existing key order is never reordered to make room for a default.
|
|
40
|
+
- A code cell that omits `execution_count` is accepted (nbformat treats the field
|
|
41
|
+
as optional) and a rewrite keeps the key absent instead of injecting it.
|
|
42
|
+
- Union validation failures name the offending field and the accepted values
|
|
43
|
+
(`cells.0.cell_type: expected "markdown"`) instead of collapsing to
|
|
44
|
+
`Invalid input`.
|
|
45
|
+
- Deeply nested values are refused with the depth limit named (512) instead of
|
|
46
|
+
surfacing a `Maximum call stack size exceeded`.
|
|
47
|
+
- A custom JSON Schema is generated with `additionalProperties: false` and the
|
|
48
|
+
`ipynb_read` / `ipynb_outputs` argument rules, so a misspelled argument or a
|
|
49
|
+
call the tool would reject is refused before it runs. A misspelled
|
|
50
|
+
`clear_outputs` used to be dropped and wiped outputs.
|
|
51
|
+
- `truncateMarkdown` no longer emits a lone surrogate when a budget splits an
|
|
52
|
+
astral character.
|
|
53
|
+
- A value JSON cannot represent (`undefined`, `BigInt`, a cycle) is refused with
|
|
54
|
+
an actionable message instead of being dropped and reported as a successful
|
|
55
|
+
write.
|
|
56
|
+
|
|
57
|
+
### Data safety and atomicity
|
|
58
|
+
|
|
59
|
+
- A notebook whose bytes are not valid UTF-8, or that starts with a BOM, is
|
|
60
|
+
rejected at read time instead of being decoded with replacement characters
|
|
61
|
+
and silently rewritten later.
|
|
62
|
+
- A tool call cancelled during the permission prompt writes nothing; a retried
|
|
63
|
+
insert or delete cannot apply twice.
|
|
64
|
+
- A write that another process replaces immediately after the rename fails with
|
|
65
|
+
a concurrent-replacement error instead of reporting success for a change that
|
|
66
|
+
is no longer in the file, and a file deleted right after the rename is
|
|
67
|
+
reported instead of silently succeeding.
|
|
68
|
+
- A write refused by a parent-directory swap no longer leaves the full new
|
|
69
|
+
notebook content behind as a hidden `.tmp`: cleanup tracks wherever the temp
|
|
70
|
+
moved and sweeps the unique name beside the original directory.
|
|
71
|
+
- The notebook write and the export are fsynced (content and directory, on
|
|
72
|
+
POSIX), so a returned success survives a crash.
|
|
73
|
+
- The parent directory is re-resolved and the containment re-checked immediately
|
|
74
|
+
before the rename, for notebook writes and for the LSP sidecar.
|
|
75
|
+
- An unreadable target is refused by the pre-rename revision re-read instead of
|
|
76
|
+
warning and writing anyway.
|
|
77
|
+
- Windows path confinement no longer accepts a drive root, a path on another
|
|
78
|
+
drive, or an outside path whose ancestor is a drive root; the regression was
|
|
79
|
+
found on a real Windows host and CI now runs the suite there.
|
|
80
|
+
|
|
81
|
+
### Performance
|
|
82
|
+
|
|
83
|
+
- `isMultiline` no longer scans to the end of the document per node, which made
|
|
84
|
+
compact notebooks quadratic: a 256k-key compact object fell from 6.8 s to
|
|
85
|
+
0.76 s.
|
|
86
|
+
- `sanitizeTerminal` skips the whole examined window after an unterminated OSC
|
|
87
|
+
introducer: 40 MB of `ESC ]` noise fell from 4.1 s to 0.10 s.
|
|
88
|
+
- `formatOutputs` bounds a JSON dict before serializing it: 1000 sections of
|
|
89
|
+
100k keys fell from 5.6 s to 7 ms and is now constant in the section count.
|
|
90
|
+
- The patcher builds its node tree from offsets and parses the value once
|
|
91
|
+
natively; array nodes store item spans and materialize only the changed ones.
|
|
92
|
+
A one-cell edit in a 17 MB / 64k-cell notebook fell from 1048 ms to roughly
|
|
93
|
+
400-550 ms and the patch allocation from ~240 MB to ~43 MB.
|
|
94
|
+
- Non-ASCII `ensureAscii` escaping uses a lookup table instead of per-character
|
|
95
|
+
concatenation: a 10 MB string fell from 2094 ms / +1992 MB to 485 ms / +282 MB.
|
|
96
|
+
- `realpathWithRetry` stops retrying a genuinely absent path: a missing path
|
|
97
|
+
fell from 8.9 ms to 0.62 ms, and a new notebook several directories deep is
|
|
98
|
+
created in milliseconds.
|
|
99
|
+
- `scripts/bench-alloc.ts` pins the per-patch allocation with a fixed workload
|
|
100
|
+
(42-44 MB against a 60 MB ceiling and 161-171 MB for the previous tree);
|
|
101
|
+
`scripts/bench-writes.ts` asserts time and RSS budgets for a compact notebook,
|
|
102
|
+
a large per-cell output, non-ASCII escaping, an object-heavy patch and a
|
|
103
|
+
17 MB edit.
|
|
104
|
+
|
|
105
|
+
### Kernel and Python helper
|
|
106
|
+
|
|
107
|
+
- A warm-kernel response must echo a per-request nonce: a notebook cell shares
|
|
108
|
+
the helper's stdout, so `os.write(1, '{"id":N,...}')` could settle another
|
|
109
|
+
request (and `save=true` persisted the forged output). Helpers that do not
|
|
110
|
+
advertise the nonce keep working.
|
|
111
|
+
- A kernel that dies under nbclient is torn down and the next request starts a
|
|
112
|
+
fresh kernel instead of failing until an explicit restart.
|
|
113
|
+
- An aborted or timed-out request no longer kills the shared kernel for other
|
|
114
|
+
in-flight requests.
|
|
115
|
+
- A queued `shutdown` preempts a running cell instead of waiting for it.
|
|
116
|
+
- The helper validates `timeoutMs` and `maxOutputChars` and returns a structured
|
|
117
|
+
error instead of a traceback and exit 1; a missing `pip` degrades the `env`
|
|
118
|
+
report to an empty package list instead of failing it; a serve request that
|
|
119
|
+
names a different notebook is refused instead of silently running the init
|
|
120
|
+
notebook.
|
|
121
|
+
- The helper exits when its parent disappears, so a plugin crash no longer
|
|
122
|
+
leaves an orphaned helper and kernel running until the cell ends.
|
|
123
|
+
- `MAX_HELPER_STDOUT_BYTES` is compared against UTF-8 bytes, and an aborted
|
|
124
|
+
oversized line clears its request timer instead of killing the next request.
|
|
125
|
+
|
|
126
|
+
### Tooling, proofs and specs
|
|
127
|
+
|
|
128
|
+
- The silence guard also matches `.catch(() => identifier)` forms; every
|
|
129
|
+
deliberately silent site is inventoried in `docs/contributing.md`.
|
|
130
|
+
- `scripts-vacuity.sh` ships the non-vacuity probes the guide promises: it
|
|
131
|
+
builds a temporary inverse invariant for all 17 checked states and fails when
|
|
132
|
+
TLC does not violate it. `scripts-verify.sh` runs it.
|
|
133
|
+
- Lean: sortedness is modelled over the UTF-16 unit order the shipped comparator
|
|
134
|
+
uses, `MarkdownSafe` records the clamped case and the well-formedness property,
|
|
135
|
+
and `NotebookDefaults` states key/value stability rather than only
|
|
136
|
+
"present implies noop".
|
|
137
|
+
- TLA+: `KernelWarningRing` gained a dishonest twin, and the scope each model
|
|
138
|
+
actually covers (win32 replace, `DeliveredBounded`) is stated in the module.
|
|
139
|
+
- `prepack` now verifies the packed file set (`server.js`,
|
|
140
|
+
`python/ipynb_runner.py`, docs) and greps `dist/index.js` for strings from the
|
|
141
|
+
current sources, so a stale or incomplete package cannot ship.
|
|
142
|
+
- CI: the test job retries up to three times, annotates every failing test and
|
|
143
|
+
uploads every attempt's log; Windows and macOS jobs run the suite.
|
|
144
|
+
- The LSP materialized sidecar is not rewritten when its content is unchanged,
|
|
145
|
+
preserving its mtime. The diagnostics temp file is still rewritten per call.
|
|
146
|
+
|
|
147
|
+
### Documentation
|
|
148
|
+
|
|
149
|
+
- `README`, `CHANGELOG` and `docs/` statements were checked against measured
|
|
150
|
+
behavior: the byte-stability claims, the defaulted-key insertion, the sidecar
|
|
151
|
+
no-rewrite scope, and the inode check's actual reach.
|
|
152
|
+
|
|
153
|
+
## 2.0.0
|
|
154
|
+
|
|
155
|
+
- OpenCode V2-only plugin (`@opencode/plugin` 2.2.2). The V1 `server()` export is removed.
|
|
156
|
+
- 14 native notebook tools with JSON Schema inputs, permission assertions, and V2 result metadata.
|
|
157
|
+
- Real-path path confinement, symlink-alias locking, and atomic notebook writes.
|
|
158
|
+
- Notebook LSP support: virtual Python document, cell mapping, post-edit/on-demand
|
|
159
|
+
pyright diagnostics, and a materialized `.py` sidecar for per-cell hover,
|
|
160
|
+
go-to-definition, find-references, and document symbols through
|
|
161
|
+
`opencode-v2-lsp-support`. Sidecars live next to the notebook
|
|
162
|
+
(`opencode-ipynb-lsp-<hash>.py`) so sibling imports resolve; add
|
|
163
|
+
`opencode-ipynb-lsp-*.py` to `.gitignore`.
|
|
164
|
+
- Token-efficient `ipynb_edit` results (no echoed source or diff).
|
|
165
|
+
- Warm-kernel source reload, per-request timeouts, abort handling, and startup timeouts.
|
|
166
|
+
- `allowOutsideWorktree` escape hatch preserved for notebook reads/writes and exports.
|
|
167
|
+
- Services migrated to Effect **4.0.6**, matching OpenCode 2's plugin SDK.
|
|
168
|
+
- New `docs/architecture.md`, `docs/contributing.md`, a CI workflow, and an
|
|
169
|
+
`opencode.example.jsonc` template.
|
|
170
|
+
|
|
171
|
+
### Breaking changes
|
|
172
|
+
|
|
173
|
+
- V1 OpenCode is no longer supported. Use plugin `0.1.2` with OpenCode 1.
|
|
174
|
+
- `ipynb_edit` no longer returns a textual old/new/diff body; it returns a concise
|
|
175
|
+
confirmation plus diagnostics.
|
|
176
|
+
- LSP diagnostics use a 0-based cell index and 1-based line/character positions in human-readable text.
|
|
177
|
+
- Read-only notebook tools (`ipynb_inspect`, `ipynb_read`, `ipynb_repro`) now declare and assert the V2 `read` action; mixed tools assert `read`/`edit` per branch.
|
|
178
|
+
- `ipynb_kernel restart` stops the current kernel; the next run starts a new one (it does not respawn eagerly).
|
|
179
|
+
- `helperRelativePath` is now resolved only relative to the plugin package or as an absolute path; it is no longer searched in the project cwd/worktree (prevents helper shadowing).
|
|
180
|
+
- `ipynb_run save=true` requires an `edit` permission in addition to `shell`,
|
|
181
|
+
and the edit is asserted before user code runs. A denied edit executes nothing.
|
|
182
|
+
- `ipynb_run` now defaults `maxOutputChars` to `defaultMaxOutputChars` (6000),
|
|
183
|
+
matching the other read tools. Pass `maxOutputChars` explicitly for larger output.
|
|
184
|
+
|
|
185
|
+
## 0.1.2
|
|
186
|
+
|
|
187
|
+
- Final V1 release. See the repository history for the V1 feature set.
|
package/README.md
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
A community [OpenCode](https://opencode.ai) plugin that adds robust support for Jupyter Notebook (`.ipynb`) files: inspect, read, edit, run, outputs, clean, export, reproducibility reports, and warm Python kernels.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
> **OpenCode 2.x only.** The plugin implements the V2 plugin API and does not load on OpenCode 1.x.
|
|
6
|
+
|
|
7
|
+
The plugin is **opt-in**, distributed via npm, and does not modify the OpenCode core. It exposes fourteen agent tools that operate on `.ipynb` files with explicit permissions, granular context control, and a strongly-typed [Effect 4.0.6](https://effect.website) runtime internally, matching OpenCode 2.
|
|
6
8
|
|
|
7
9
|
> Repository: https://github.com/Restodecoca/opencode-ipynb
|
|
8
10
|
> Issues: https://github.com/Restodecoca/opencode-ipynb/issues
|
|
@@ -10,39 +12,44 @@ The plugin is **opt-in**, distributed via npm, and does not modify the OpenCode
|
|
|
10
12
|
## Why a plugin and not core
|
|
11
13
|
|
|
12
14
|
- Notebooks are large, binary-like artifacts. Dumping them into the agent context burns tokens.
|
|
13
|
-
- Reading outputs and editing cells are high-trust actions that
|
|
15
|
+
- Reading outputs and editing cells are high-trust actions that are gated by the host permission system.
|
|
14
16
|
- The execution flow needs a Python runtime, which is not something every OpenCode user wants installed.
|
|
15
17
|
- A plugin lets the community iterate on these workflows without forcing changes on the OpenCode core.
|
|
16
18
|
|
|
17
19
|
## Installation
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
OpenCode 2.x loads plugins from the `plugins` key. Point OpenCode at a checkout directory for an unreleased change:
|
|
20
22
|
|
|
21
23
|
```json
|
|
22
24
|
{
|
|
23
25
|
"$schema": "https://opencode.ai/config.json",
|
|
24
|
-
"
|
|
26
|
+
"plugins": ["/absolute/path/to/opencode-ipynb"]
|
|
25
27
|
}
|
|
26
28
|
```
|
|
27
29
|
|
|
28
|
-
|
|
30
|
+
The V2 line is published from `3.0.0` onward, so the versioned form is:
|
|
29
31
|
|
|
30
32
|
```json
|
|
31
33
|
{
|
|
32
|
-
"
|
|
34
|
+
"$schema": "https://opencode.ai/config.json",
|
|
35
|
+
"plugins": ["opencode-ipynb@3.0.0"]
|
|
33
36
|
}
|
|
34
37
|
```
|
|
35
38
|
|
|
39
|
+
Anything below `2.0.0` is the V1 package, which does **not** load in OpenCode 2.
|
|
40
|
+
|
|
41
|
+
`opencode.example.jsonc` is a machine-independent local example.
|
|
42
|
+
|
|
36
43
|
Or run directly from this repo:
|
|
37
44
|
|
|
38
45
|
```bash
|
|
39
46
|
git clone https://github.com/Restodecoca/opencode-ipynb
|
|
40
47
|
cd opencode-ipynb
|
|
41
48
|
bun install
|
|
42
|
-
bun run build
|
|
49
|
+
bun run build # requires Bun and Node (Node clears dist/)
|
|
43
50
|
```
|
|
44
51
|
|
|
45
|
-
Then add
|
|
52
|
+
Then add the **absolute path** to this checkout to the `plugins` array in your `opencode.json` (package-name resolution only works after the V2 package is published).
|
|
46
53
|
|
|
47
54
|
## Tools
|
|
48
55
|
|
|
@@ -50,17 +57,18 @@ Then add `"opencode-ipynb"` (or the local path) to your `opencode.json`.
|
|
|
50
57
|
| -------------------- | ------- |
|
|
51
58
|
| `ipynb_inspect` | Compact summary: kernel/language metadata, cell table, output stats, execution-order warnings, optional missing-package checks. |
|
|
52
59
|
| `ipynb_read` | Granular read of one cell or a range, with optional outputs/errors/metadata/images and truncation limits. |
|
|
53
|
-
| `ipynb_edit` | Safe per-cell source edit with
|
|
54
|
-
| `ipynb_cell_insert` | Insert a code/markdown/raw cell
|
|
60
|
+
| `ipynb_edit` | Safe per-cell source edit with a concise confirmation, output clearing policy, permission gate, and in-process per-file lock. |
|
|
61
|
+
| `ipynb_cell_insert` | Insert a code/markdown/raw cell at a target index, or append when the index is omitted. |
|
|
55
62
|
| `ipynb_cell_delete` | Delete one cell by index and return a preview of the deleted source. |
|
|
56
63
|
| `ipynb_cell_move` | Move one cell to a new index. |
|
|
57
64
|
| `ipynb_run` | Execute one cell, a range, from a cell, or a full notebook via the Python helper. Supports save-to-notebook and optional warm kernels. |
|
|
58
65
|
| `ipynb_outputs` | List / read / read_error / clear_cell / clear_all outputs with pagination and permission gates for writes. |
|
|
59
66
|
| `ipynb_clean` | Strip outputs, execution counts, widget state, large images, and normalize `source` arrays for Git-friendly diffs. |
|
|
60
|
-
| `ipynb_export` | Export to Markdown, Python, or summary; optionally write to disk after permission. |
|
|
67
|
+
| `ipynb_export` | Export to Markdown, Python, or summary; optionally write to disk after permission. Files are written with full text outputs (images are represented by notices); the tool output is capped by `maxExportChars`. |
|
|
61
68
|
| `ipynb_doctor` | Diagnose Python, helper discovery, and required Jupyter dependencies. |
|
|
62
69
|
| `ipynb_repro` | Reproducibility report: kernel/env info, `pip freeze`, filesystem reads, random seeds, non-determinism, missing packages. |
|
|
63
|
-
| `ipynb_kernel` | Inspect/restart/shutdown warm kernels when `
|
|
70
|
+
| `ipynb_kernel` | Inspect/restart/shutdown warm kernels when the `warmKernel` plugin option is enabled. `restart` stops the current kernel; the next run starts a new one. |
|
|
71
|
+
| `ipynb_lsp` | Run on-demand Python diagnostics, or materialize the virtual `.py` for per-cell LSP navigation. |
|
|
64
72
|
|
|
65
73
|
### Examples
|
|
66
74
|
|
|
@@ -114,11 +122,44 @@ ipynb_export({
|
|
|
114
122
|
})
|
|
115
123
|
```
|
|
116
124
|
|
|
125
|
+
## Edit results and diagnostics
|
|
126
|
+
|
|
127
|
+
`ipynb_edit` returns a concise confirmation (cell, file, type, and whether outputs were cleared) instead of echoing the old/new source or a diff. The model already has the source it sent, so the extra text only spends tokens.
|
|
128
|
+
|
|
129
|
+
**Byte-stable writes.** A write splices only the changed values into the stored JSON, so untouched bytes survive: key order, `source` shape (a line array stays a line array, a string stays a string), indentation (including widths wider than `JSON.stringify`'s 10-space cap), inline vs expanded arrays, line endings (LF/CRLF), `\uXXXX` escapes, number literals, and the trailing newline. If a splice cannot be trusted, the writer falls back to re-serializing the whole notebook, which preserves key order and the file's line endings but normalizes whitespace. A file that `nbformat` itself would reject — a UTF-8 BOM prefix or bytes that are not valid UTF-8 — fails at read time with a parse error (matching `nbformat`'s `NotJSONError`/`UnicodeDecodeError`) and is never silently rewritten. `ipynb_run save=true` also re-splits the `stream.text`/text-mime strings that `nbformat.read` rejoins (when the notebook stores `source` as line arrays), so saving outputs does not reflow those outputs. `ipynb_clean` is the exception by design: `normalizeSource` (default `true`) intentionally rewrites `source` arrays to strings, so pass `normalizeSource: false` when you want a minimal diff.
|
|
130
|
+
|
|
131
|
+
Note that `clearOutputs: "auto"` (the `ipynb_edit` default) sets `execution_count` to `null` on a code cell whose source changed, even when the notebook committed a specific count. Use `clearOutputs: "never"` when editing a notebook exported from a workspace that stores execution counts and you want to preserve them.
|
|
132
|
+
|
|
133
|
+
After code-changing tools, the plugin runs pyright on the notebook's virtual Python document for **Python notebooks only** and appends errors in the same block shape used by [`opencode-v2-lsp-support`](https://github.com/christensenjairus/opencode-v2-lsp-support):
|
|
134
|
+
|
|
135
|
+
```text
|
|
136
|
+
LSP errors detected in this file, please fix:
|
|
137
|
+
<diagnostics file="/absolute/path/notebook.ipynb">
|
|
138
|
+
ERROR [cell 0, line 1:10] Type "Literal['no']" is not assignable to declared type "int"
|
|
139
|
+
</diagnostics>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The cell-mapped errors are also available as `metadata.notebookDiagnostics`; `metadata.diagnostics` is not emitted for custom tools because OpenCode 2 only feeds that field to its native edit renderer. `ipynb_lsp` runs the same check on demand and reports whether it was skipped (timeout, missing pyright, invalid output, not-analyzed, temp-unwritable, aborted, unsupported-language) instead of claiming a clean result.
|
|
143
|
+
|
|
117
144
|
## Safety and permissions
|
|
118
145
|
|
|
119
|
-
- Every write (`ipynb_edit`, `ipynb_clean`, `ipynb_outputs clear_*`, `ipynb_export --outputPath`) calls `
|
|
120
|
-
-
|
|
121
|
-
|
|
146
|
+
- Every write (`ipynb_edit`, `ipynb_cell_insert`, `ipynb_cell_delete`, `ipynb_cell_move`, `ipynb_clean`, `ipynb_outputs clear_*`, `ipynb_export --outputPath`, and `ipynb_lsp operation=materialize` for its sidecar) calls `ctx.permission.assert` before touching the disk, and every execution (`ipynb_run`) asks with rich metadata: file path, mode (`cell` / `range` / `all` / `from`), cell range, save flag, working directory, timeout. When `save=true`, a second `edit` assert covers the notebook write.
|
|
147
|
+
- Permission requests use V2 action names: writes use `edit`, reads use `read`, and execution uses `shell`. Configure them with the ordered `permissions` array, for example `[{ "action": "edit", "resource": "*", "effect": "ask" }, { "action": "shell", "resource": "*", "effect": "ask" }, { "action": "lsp", "resource": "*", "effect": "ask" }]`. **Rules are evaluated in order and the last matching rule wins**: put a specific `deny` after a broad `allow`, otherwise the allow overrides it. The plugin sends absolute, real, and session-relative resource paths so relative rules such as `secrets/*` also apply. For example:
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
"permissions": [
|
|
151
|
+
{ "action": "read", "resource": "*", "effect": "allow" },
|
|
152
|
+
{ "action": "read", "resource": "secrets/*", "effect": "deny" },
|
|
153
|
+
{ "action": "edit", "resource": "*", "effect": "allow" },
|
|
154
|
+
{ "action": "edit", "resource": "secrets/*", "effect": "deny" },
|
|
155
|
+
{ "action": "shell", "resource": "*", "effect": "ask" },
|
|
156
|
+
{ "action": "lsp", "resource": "*", "effect": "ask" }
|
|
157
|
+
]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Note that a tool-level `edit: deny` also removes tools that declare `options.permission: "edit"` from the model catalog; mixed tools remain visible and fail when their write branch asserts `edit`.
|
|
161
|
+
- Tools that always mutate (`ipynb_edit`, `ipynb_cell_insert`, `ipynb_cell_delete`, `ipynb_cell_move`, `ipynb_clean`) declare `options.permission: "edit"`, and `ipynb_run` declares `"shell"`. `ipynb_lsp` declares `"lsp"`; diagnostics asks for `lsp`/`read` on the notebook and `edit` on its temporary analysis file; materialize asks for `read`/`lsp` on the notebook and `edit` on the sidecar path. Read-only tools (`ipynb_inspect`, `ipynb_read`, `ipynb_repro`) declare `"read"` and also assert `read` on the notebook path. When they need Python, they assert `shell` before spawning it: `ipynb_repro` always does, and `ipynb_inspect` only when `checkMissingPackages=true`. This ordering means a denied `shell` action prevents the subprocess entirely. `ipynb_doctor` also asserts `shell` for the interpreter before probing it. Mixed read/write tools (`ipynb_outputs`, `ipynb_export`) do not declare a tool-level permission; their read branches assert `read` and their writes assert `edit`. `ipynb_doctor` declares no permission action. `ipynb_kernel` declares no tool-level action, but `restart`/`shutdown` assert `shell` on the kernel's notebook path before stopping it.
|
|
162
|
+
- `PathService` rejects paths that resolve outside of the OpenCode worktree, and `NotebookFileService` pins the resolved real path inside the worktree before reading or writing. Symlink aliases share a lock and writes update the real target rather than replacing the link. The lock manager keys by real path and serializes per-file writes within one process to prevent accidental corruption. Independent processes do not share the lock: if two of them write the same notebook, the later rename wins, and the writer whose change was replaced now fails with a concurrent-replacement error instead of reporting success. Both a replacing rename and an in-place rewrite (what `nbformat.write` and most editors do) are detected: the write compares the target inode and re-reads the target's text after the rename.
|
|
122
163
|
- The Python execution helper is an opt-in, isolated subprocess; it does not auto-install Jupyter. The user installs `python/requirements.txt` only when they want real execution.
|
|
123
164
|
|
|
124
165
|
## Context control
|
|
@@ -126,12 +167,81 @@ ipynb_export({
|
|
|
126
167
|
Notebooks can be enormous. By default the plugin never dumps a full notebook into context:
|
|
127
168
|
|
|
128
169
|
- `ipynb_inspect` returns a table with the first line of every cell, plus aggregate counts. It never includes the full source.
|
|
129
|
-
- `ipynb_read` defaults to **not** including outputs. Set `includeOutputs: true` to opt in. Images
|
|
130
|
-
- `maxSourceChars` (default 12 000) and `maxOutputChars` (default 6 000) cap
|
|
131
|
-
- `
|
|
132
|
-
-
|
|
170
|
+
- `ipynb_read` defaults to **not** including outputs. Set `includeOutputs: true` to opt in. Images/base64 are omitted by default; set `includeImages: true` to receive them as file attachments (the text block still only contains a size notice).
|
|
171
|
+
- `maxSourceChars` (default 12 000) and `maxOutputChars` (default 6 000) cap per-cell source/output; tracebacks have their own 8 000-character cap.
|
|
172
|
+
- Notebook reads are limited to 50 MB and `ipynb_read` ranges to 500 cells; use `ipynb_inspect` for a compact summary of very large notebooks.
|
|
173
|
+
- `ipynb_run save=true` reports `saved:false` when no code cell was actually written (for example a markdown-only target).
|
|
174
|
+
- Error tracebacks are capped internally at 8 000 characters.
|
|
175
|
+
- Truncation appends `... (truncated, use maxXxx to increase)`; with extremely small budgets the hint itself may exceed the requested maximum, but original content is never included.
|
|
176
|
+
|
|
177
|
+
Most limits live in `src/utils/limits.ts`; the traceback cap is fixed in `src/format/outputs.ts`.
|
|
178
|
+
|
|
179
|
+
## LSP integration
|
|
180
|
+
|
|
181
|
+
The plugin does not ship or require a language server, but it exposes a stable, provider-agnostic bridge so an OpenCode LSP or a third-party plugin can consume notebook edits.
|
|
133
182
|
|
|
134
|
-
The
|
|
183
|
+
The compatibility model is the **file-based virtual document** used by jupyter-lsp, jedi-language-server, Ruff, and Pyrefly: code cells are concatenated into one virtual source file, and positions are mapped back to `(cellIndex, line, character)`. Clients that implement LSP 3.17 `notebookDocument` synchronization can build on the per-cell `text`/`uri` fields; they still need to supply notebook type, versions, and stable cell identity themselves.
|
|
184
|
+
|
|
185
|
+
- `opencode-ipynb/lsp` exports `buildNotebookVirtualDocument()` plus `toCellPosition()` / `toVirtualPosition()` / `makePositionMapper()`. The document also carries `languageId`, `fileExtension`, `kernelName`, and the configured `pythonPath` so a client can select the right environment (including a conda or uv environment) before starting pyright/pylsp/jedi.
|
|
186
|
+
- The `opencode-ipynb` RPC contract (`opencode-ipynb/rpc`) exposes:
|
|
187
|
+
- `document({ filePath })` → `{ filePath, notebookUri, languageId, fileExtension, kernelName, pythonPath, text, sanitizedText, cells }`
|
|
188
|
+
- `changed({ filePath })` → emitted after tools that modify the notebook (`ipynb_edit`, cell insert/delete/move, `ipynb_clean`, output clearing, and `ipynb_run` when `save` is not `false`).
|
|
189
|
+
|
|
190
|
+
The RPC document is client-facing and is not routed through model tool permissions. A third-party server plugin can subscribe to `changed`, call `document`, and feed `sanitizedText` to pyright/jedi (`text` is the raw concatenation; `sanitizedText` blanks IPython magics and `?`/`!!` help syntax). The per-cell `text`/`uri` fields are a starting point for an LSP 3.17 notebook client, which remains responsible for notebook/cell versions and stable cell identity.
|
|
191
|
+
|
|
192
|
+
The plugin also ships a small built-in consumer so diagnostics are useful without a third-party plugin:
|
|
193
|
+
|
|
194
|
+
- After code-changing tools (`ipynb_edit`, cell insert/delete/move), it runs pyright on the virtual document for Python notebooks and appends mapped errors to the tool result in the same wrapper shape used by `opencode-v2-lsp-support` (`LSP errors detected ... <diagnostics file=...>`). The inner error lines add `[cell N, line L:C]`; `opencode-v2-lsp-support` does not parse blocks produced by other plugins.
|
|
195
|
+
- `ipynb_lsp` runs the same check on demand.
|
|
196
|
+
- Non-Python notebooks are left alone; missing pyright is skipped silently, while timeout/invalid-output is reported explicitly.
|
|
197
|
+
- Set `lspDiagnostics: false` to disable the automatic pass, or `pyrightPath` to point at a specific executable. Missing pyright is ignored; the notebook tools keep working.
|
|
198
|
+
|
|
199
|
+
### Per-cell navigation with `opencode-v2-lsp-support`
|
|
200
|
+
|
|
201
|
+
OpenCode 2 has no native LSP runtime; the [`opencode-v2-lsp-support`](https://github.com/christensenjairus/opencode-v2-lsp-support) plugin provides the `lsp` tool and its servers. To use hover, go-to-definition, find-references, or document symbols on a notebook cell, materialize the notebook's virtual document:
|
|
202
|
+
|
|
203
|
+
```text
|
|
204
|
+
ipynb_lsp({ filePath: "notebooks/eda.ipynb", operation: "materialize" })
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
It writes a small, visible `.py` sidecar **next to the notebook** (still inside the session directory, which is the root used by `opencode-v2-lsp-support`) and returns the path plus a cell-to-line map. Writing it beside the notebook is what lets pyright resolve sibling imports such as `notebooks/helpers.py`:
|
|
208
|
+
|
|
209
|
+
```text
|
|
210
|
+
Virtual Python document: /project/notebooks/opencode-ipynb-lsp-4f2c1a9b7d3e5f60.py
|
|
211
|
+
Call the lsp tool from opencode-v2-lsp-support with this path. Positions are 1-based.
|
|
212
|
+
Cell map:
|
|
213
|
+
- cell 0 (code): lines 1-8
|
|
214
|
+
- cell 1 (code): lines 9-12
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Then call the LSP plugin's `lsp` tool with that path and a 1-based line/character from the map:
|
|
218
|
+
|
|
219
|
+
```text
|
|
220
|
+
lsp({ operation: "hover", path: "/project/notebooks/opencode-ipynb-lsp-4f2c1a9b7d3e5f60.py", line: 10, character: 12 })
|
|
221
|
+
lsp({ operation: "goToDefinition", path: "...", line: 10, character: 12 })
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
The result is a normal LSP location (for the virtual file, e.g. `opencode-ipynb-lsp-4f2c1a9b7d3e5f60.py:10:5`); use the cell map to report it as `[cell 1, line 2:5]`. Coordinate contract: tool `cellIndex` is 0-based; the external `lsp` tool's line/character are 1-based; `metadata.notebookDiagnostics` and RPC cells are 0-based LSP positions; the `metadata.cells` start/end lines from `materialize` are 1-based for the external tool (cell indices remain 0-based). The same works for `findReferences`, `documentSymbol`, and the other operations supported by that plugin. The cell map contains code cells only. Materialized files are refreshed automatically after plugin notebook edits (`ipynb_*`); edits made outside the plugin require re-running `materialize`. `ipynb_edit` changes that add or remove source lines, and `ipynb_cell_insert`, `ipynb_cell_delete`, or `ipynb_cell_move`, shift code-cell line numbers. Re-run `materialize` after any such edit if you need an updated cell map. Sidecars are removed when the plugin unloads, so run `materialize` and the `lsp` calls in the same session. Add `opencode-ipynb-lsp-*.py` to `.gitignore` (this repository already does).
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
import { NotebookRpc } from "opencode-ipynb/rpc"
|
|
228
|
+
|
|
229
|
+
export default {
|
|
230
|
+
id: "my-notebook-lsp",
|
|
231
|
+
async setup(ctx: any) {
|
|
232
|
+
const notebook = ctx.rpc(NotebookRpc)
|
|
233
|
+
notebook.events.on("changed", async (event) => {
|
|
234
|
+
const doc = await notebook.document({ filePath: event.data.filePath })
|
|
235
|
+
// Analyze doc.sanitizedText as a virtual .py file, then map diagnostics back with
|
|
236
|
+
// the exported position helpers; or use doc.cells with notebook sync.
|
|
237
|
+
})
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Conda itself does not provide a notebook language server. `conda-lsp`/YAML language servers target conda/YAML files, not Python cells. Use conda or uv to select the interpreter (`pythonPath`/`kernelName`) and a Python language server for the code. Do not add `.ipynb` to pyright's `extensions`: pyright must receive the virtual `.py` text, not the notebook JSON.
|
|
243
|
+
|
|
244
|
+
Known limitations of the virtual-document model: the whole notebook is re-analyzed when any cell changes; Python-bodied cell magics (`%%time`, `%%capture`) keep their body, while shell/non-Python cell magics are blanked; shell assignment forms (`x = !ls`) are not analyzed; top-level `await` and kernel-only state are not understood by static servers; diagnostics may differ from runtime behavior.
|
|
135
245
|
|
|
136
246
|
## Python execution
|
|
137
247
|
|
|
@@ -140,7 +250,7 @@ The plugin **never installs Python dependencies automatically**. Running `ipynb_
|
|
|
140
250
|
### Preferred: `uv`
|
|
141
251
|
|
|
142
252
|
```bash
|
|
143
|
-
uv pip install nbformat nbclient jupyter_client ipykernel
|
|
253
|
+
uv pip install pip nbformat nbclient jupyter_client ipykernel
|
|
144
254
|
python -m ipykernel install --user
|
|
145
255
|
```
|
|
146
256
|
|
|
@@ -161,33 +271,38 @@ conda install -c conda-forge nbformat nbclient jupyter_client ipykernel
|
|
|
161
271
|
|
|
162
272
|
### Pointing the plugin at a specific Python
|
|
163
273
|
|
|
164
|
-
OpenCode may use a different Python interpreter than the one in your terminal.
|
|
274
|
+
OpenCode may use a different Python interpreter than the one in your terminal. The environment variable takes precedence over plugin options; the PATH fallback is used only when neither sets an interpreter. The sections below are ordered from configuration to fallback:
|
|
165
275
|
|
|
166
276
|
1. Plugin options (in `opencode.json`):
|
|
167
277
|
|
|
168
278
|
```json
|
|
169
279
|
{
|
|
170
|
-
"
|
|
171
|
-
|
|
172
|
-
"opencode-ipynb",
|
|
173
|
-
{
|
|
174
|
-
"pythonPath": "
|
|
280
|
+
"plugins": [
|
|
281
|
+
{
|
|
282
|
+
"package": "/absolute/path/to/opencode-ipynb",
|
|
283
|
+
"options": {
|
|
284
|
+
"pythonPath": "/home/gabriel/.venv/bin/python",
|
|
285
|
+
"helperRelativePath": "python/ipynb_runner.py",
|
|
175
286
|
"preferUv": true,
|
|
176
287
|
"defaultTimeoutMs": 120000,
|
|
177
288
|
"defaultMaxOutputChars": 6000,
|
|
178
289
|
"warmKernel": false,
|
|
179
290
|
"allowOutsideWorktree": false
|
|
180
291
|
}
|
|
181
|
-
|
|
292
|
+
}
|
|
182
293
|
]
|
|
183
294
|
}
|
|
184
295
|
```
|
|
185
296
|
|
|
186
|
-
- `pythonPath` (string): absolute path to a Python interpreter.
|
|
297
|
+
- `pythonPath` (string): absolute path to a Python interpreter, or a bare name resolved through `PATH`. Path-like relative values are rejected so the permission resource and the spawned executable cannot diverge.
|
|
298
|
+
- `helperRelativePath` (string, default `python/ipynb_runner.py`): helper path relative to the plugin package, or an absolute path. It is deliberately never resolved from the project cwd, so a repository cannot shadow the shipped helper.
|
|
187
299
|
- `preferUv` (boolean, default `true`): the doctor and the Python service prefer `uv pip install` over `pip install` in their suggestions.
|
|
188
300
|
- `defaultTimeoutMs` (number, default `120000`): timeout in milliseconds for `ipynb_run`.
|
|
189
|
-
- `defaultMaxOutputChars` (number, default `6000`): fallback for `ipynb_read
|
|
301
|
+
- `defaultMaxOutputChars` (number, default `6000`): fallback for `ipynb_read`, `ipynb_outputs read`, and `ipynb_run` when the user does not pass `maxOutputChars`.
|
|
190
302
|
- `warmKernel` (boolean, default `false`): keep a long-lived Python subprocess per notebook path for faster repeated `ipynb_run mode=all` / `mode=cell` calls. Manage it with `ipynb_kernel`.
|
|
303
|
+
- `lspDiagnostics` (boolean, default `true`): after `ipynb_edit`, `ipynb_cell_insert`, `ipynb_cell_delete`, or `ipynb_cell_move`, run pyright on the notebook's virtual Python document and append errors to the tool result. Set `false` to disable the extra pass.
|
|
304
|
+
- `pyrightPath` (string, default `pyright`): pyright executable for the diagnostics pass. Use an absolute path if pyright is not on `PATH`.
|
|
305
|
+
- `diagnosticsTimeoutMs` (number, default `15000`): timeout for the diagnostics pass.
|
|
191
306
|
- `allowOutsideWorktree` (boolean, default `false`): power-user escape hatch — when `true`, the plugin will read and write `.ipynb` files outside the OpenCode worktree. Leave at `false` unless you know why you need it.
|
|
192
307
|
|
|
193
308
|
2. Environment variables (the shell wins over plugin options):
|
|
@@ -197,9 +312,9 @@ OpenCode may use a different Python interpreter than the one in your terminal. T
|
|
|
197
312
|
OPENCODE_IPYNB_OPTIONS='{"pythonPath":"/usr/bin/python3","defaultMaxOutputChars":4000}' opencode
|
|
198
313
|
```
|
|
199
314
|
|
|
200
|
-
`OPENCODE_IPYNB_PYTHON` overrides `
|
|
315
|
+
`OPENCODE_IPYNB_PYTHON` overrides the plugin `pythonPath` option only. `OPENCODE_IPYNB_OPTIONS` overrides the whole plugin options object (a JSON object validated by the same schema). Both are process-level overrides, so prefer the `plugins` object form when you only want to configure one project.
|
|
201
316
|
|
|
202
|
-
3. PATH fallback: the plugin
|
|
317
|
+
3. PATH fallback: the plugin uses the first `python` if present, otherwise `python3`. It does not retry after a broken interpreter, so every spawned interpreter is covered by the shell permission request. Path-like `pythonPath` values must be absolute; bare names are resolved through PATH.
|
|
203
318
|
|
|
204
319
|
### Diagnose first
|
|
205
320
|
|
|
@@ -215,8 +330,9 @@ It reports the selected interpreter, every Jupyter dependency (`[ok]` / `[missin
|
|
|
215
330
|
|
|
216
331
|
- Python execution depends on the user's local Python/Jupyter environment. The plugin diagnoses missing packages but never installs them.
|
|
217
332
|
- Warm kernels are intentionally limited to `ipynb_run mode=all` and `mode=cell`; `range`, `from`, and `env` use one-shot helper processes.
|
|
218
|
-
- Large notebooks and rich outputs are truncated in tool responses to protect context. When `ipynb_run save=true
|
|
219
|
-
- `allowOutsideWorktree` is a power-user escape hatch. Keep it disabled unless you explicitly need cross-worktree notebook access.
|
|
333
|
+
- Large notebooks and rich outputs are truncated in tool responses to protect context. When `ipynb_run save=true` completes successfully, the executed code cells write their nbformat outputs to disk; a failed run returns its error without writing partial results.
|
|
334
|
+
- `allowOutsideWorktree` is a power-user escape hatch. Keep it disabled unless you explicitly need cross-worktree notebook access. Enabling it also bypasses the host's `external_directory` deny rules for plugin tools; restrict the plugin tools themselves if that matters.
|
|
335
|
+
- `ipynb_run` `workingDirectory` controls the one-shot helper process, not the notebook cell cwd; nbclient always runs cells in the notebook directory. Warm kernels reject any non-undefined `workingDirectory`.
|
|
220
336
|
|
|
221
337
|
## Examples
|
|
222
338
|
|
|
@@ -234,26 +350,28 @@ expected output.
|
|
|
234
350
|
|
|
235
351
|
## Release
|
|
236
352
|
|
|
237
|
-
The published npm tarball contains only the runtime: `dist/`, `python/ipynb_runner.py`, `python/requirements.txt`, `README.md`, and `LICENSE`. Internal developer docs, helper dev scripts, and `.github/` workflows are excluded
|
|
353
|
+
The published npm tarball contains only the runtime: `dist/`, `server.js`, `python/ipynb_runner.py`, `python/requirements.txt`, `README.md`, `CHANGELOG.md`, and `LICENSE`. Internal developer docs, helper dev scripts, and `.github/` workflows are excluded by the `files` whitelist in `package.json` (with `.npmignore` as a second guard). `AGENTS.md` and `TODO.md` are local and gitignored; `docs/` is tracked for contributors and is not shipped to npm. Contributors track their work through GitHub Issues and Discussions.
|
|
238
354
|
|
|
239
355
|
Cut a release by tagging the commit and pushing the tag, then publish it on GitHub — the workflow runs only on the `published` release event:
|
|
240
356
|
|
|
241
357
|
```bash
|
|
242
|
-
git tag
|
|
358
|
+
git tag vX.Y.Z && git push --tags
|
|
243
359
|
```
|
|
244
360
|
|
|
245
|
-
Then create a GitHub release at https://github.com/Restodecoca/opencode-ipynb/releases/new pointing at `
|
|
361
|
+
Then create a GitHub release at https://github.com/Restodecoca/opencode-ipynb/releases/new pointing at `vX.Y.Z`. The CI runs `bun run typecheck`, `bun run typecheck:tests`, `bun test`, and `bun run build` before `npm publish --provenance --access public`. The repository must have a single secret configured: `NPM_TOKEN` (an npm automation token with publish rights for the package name in `package.json`).
|
|
246
362
|
|
|
247
363
|
Before publishing, run a local package check:
|
|
248
364
|
|
|
249
365
|
```bash
|
|
250
366
|
bun run typecheck
|
|
367
|
+
bun run typecheck:tests
|
|
251
368
|
bun test
|
|
369
|
+
bun run test:coverage
|
|
252
370
|
bun run build
|
|
253
371
|
npm pack --dry-run
|
|
254
372
|
```
|
|
255
373
|
|
|
256
|
-
The
|
|
374
|
+
The `3.0.0` release is the current V2-only line (`2.0.0` was the first). The npm `latest` tag must point at a `2.0.0`-or-newer package for the bare package name to load in OpenCode 2. If you publish under a scope instead, update `package.json`, the install snippet, and this release tag convention together.
|
|
257
375
|
|
|
258
376
|
## Effect LSP setup (for development)
|
|
259
377
|
|
|
@@ -284,13 +402,14 @@ The project does NOT add this as a `prepare` script. Patch only when you want it
|
|
|
284
402
|
|
|
285
403
|
For VS Code, Cursor, Zed or NVim, make sure the editor uses the workspace TypeScript (not the bundled one). In VS Code / Cursor, open a `.ts` file, click the TypeScript version in the status bar, and select **Use Workspace Version**.
|
|
286
404
|
|
|
287
|
-
The
|
|
405
|
+
The `opencode-v2-lsp-support` TypeScript LSP also picks up the workspace TypeScript and therefore respects the `@effect/language-service` plugin. A minimal `opencode.json` in the project root enables it:
|
|
288
406
|
|
|
289
407
|
```json
|
|
290
408
|
{
|
|
291
409
|
"$schema": "https://opencode.ai/config.json",
|
|
292
410
|
"lsp": {
|
|
293
411
|
"typescript": {
|
|
412
|
+
"command": ["typescript-language-server", "--stdio"],
|
|
294
413
|
"extensions": [".ts", ".tsx", ".mts", ".cts"]
|
|
295
414
|
}
|
|
296
415
|
}
|
|
@@ -302,6 +421,7 @@ The OpenCode TypeScript LSP (built-in) also picks up the workspace TypeScript an
|
|
|
302
421
|
```bash
|
|
303
422
|
bun install
|
|
304
423
|
bun run typecheck
|
|
424
|
+
bun run typecheck:tests
|
|
305
425
|
bun test
|
|
306
426
|
bun run build
|
|
307
427
|
```
|
|
@@ -309,9 +429,19 @@ bun run build
|
|
|
309
429
|
Layout:
|
|
310
430
|
|
|
311
431
|
```
|
|
432
|
+
server.js # V2 local-directory entrypoint (re-exports dist/index.js)
|
|
312
433
|
src/
|
|
313
434
|
index.ts # re-exports the plugin
|
|
314
|
-
plugin.ts #
|
|
435
|
+
plugin.ts # V2 lifecycle: setup(), RPC, hook install, cleanup
|
|
436
|
+
plugin-v2.ts # V2 adapter: JSON Schema inputs, permission.assert, result mapping
|
|
437
|
+
plugin-options.ts # per-instance options + env precedence
|
|
438
|
+
registrations.ts # tool definitions + permission names
|
|
439
|
+
notebook-hooks.ts # pure changed/no-op rules and result helpers
|
|
440
|
+
notebook-diagnostics.ts # pyright virtual-document diagnostics + LSP metadata
|
|
441
|
+
virtual-materialize.ts # safe notebook-adjacent sidecar writer/cleanup
|
|
442
|
+
lsp.ts # virtual notebook document + position mapping for LSPs
|
|
443
|
+
rpc.ts # public RPC contract (document method, changed event)
|
|
444
|
+
tool.ts # internal zod tool contract shared by the 14 tool implementations
|
|
315
445
|
domain/ # zod schemas + types for cells, outputs, execution
|
|
316
446
|
services/ # Effect-style services (Path, Permission, File, ...)
|
|
317
447
|
format/ # markdown / output / diagnostic / export formatters
|
|
@@ -319,10 +449,36 @@ src/
|
|
|
319
449
|
utils/ # limits, paths, mime, truncate, json helpers
|
|
320
450
|
python/
|
|
321
451
|
ipynb_runner.py # JSON-stdin/stdout runner using nbformat + nbclient
|
|
322
|
-
requirements.txt
|
|
452
|
+
requirements.txt # runtime execution deps
|
|
453
|
+
requirements-test.txt # CI/test deps (numpy, matplotlib, scikit-learn)
|
|
323
454
|
test/
|
|
324
455
|
fixtures/ # simple, outputs, error, images
|
|
325
456
|
unit/ # bun:test suites
|
|
457
|
+
docs/
|
|
458
|
+
architecture.md # module map, lifecycle, LSP and file-safety invariants
|
|
459
|
+
contributing.md # setup, commands, adding tools, review/release checklist
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
The plugin targets `@opencode/plugin` 2.2.x (tested with 2.2.2). It is V2-only; there is no V1 `server()` entrypoint.
|
|
463
|
+
|
|
464
|
+
Architecture and contribution notes:
|
|
465
|
+
|
|
466
|
+
- [Architecture](https://github.com/Restodecoca/opencode-ipynb/blob/main/docs/architecture.md)
|
|
467
|
+
- [Contributing](https://github.com/Restodecoca/opencode-ipynb/blob/main/docs/contributing.md)
|
|
468
|
+
- [`opencode.example.jsonc`](https://github.com/Restodecoca/opencode-ipynb/blob/main/opencode.example.jsonc) is the versioned, machine-independent local config example. The real `opencode.jsonc` is intentionally not versioned because it contains machine-specific paths.
|
|
469
|
+
|
|
470
|
+
### Development environment on WSL
|
|
471
|
+
|
|
472
|
+
Use a native Linux Bun inside WSL, not the Windows npm shim. Running `bun install` through Windows Bun against a WSL path can corrupt `node_modules` or fail to replace `bun.lock`.
|
|
473
|
+
|
|
474
|
+
```bash
|
|
475
|
+
curl -fsSL https://bun.sh/install | bash
|
|
476
|
+
export PATH="$HOME/.bun/bin:$PATH"
|
|
477
|
+
|
|
478
|
+
uv venv .venv
|
|
479
|
+
uv pip install --python .venv/bin/python pip -r python/requirements-test.txt
|
|
480
|
+
.venv/bin/python -m ipykernel install --user --name python3
|
|
481
|
+
PATH="$PWD/.venv/bin:$PATH" bun test
|
|
326
482
|
```
|
|
327
483
|
|
|
328
484
|
## License
|