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.
Files changed (130) hide show
  1. package/CHANGELOG.md +187 -0
  2. package/README.md +197 -41
  3. package/dist/domain/cell.d.ts +4 -3
  4. package/dist/domain/errors.d.ts +3 -31
  5. package/dist/domain/execution.d.ts +4 -1
  6. package/dist/domain/notebook.d.ts +6 -3
  7. package/dist/domain/output.d.ts +0 -1
  8. package/dist/format/diagnostics.d.ts +0 -1
  9. package/dist/format/markdown.d.ts +1 -2
  10. package/dist/format/{diff.d.ts → notebook.d.ts} +1 -1
  11. package/dist/format/outputs.d.ts +2 -2
  12. package/dist/index.d.ts +3 -1
  13. package/dist/index.js +11294 -28152
  14. package/dist/load-document.d.ts +10 -0
  15. package/dist/lsp.d.ts +58 -0
  16. package/dist/lsp.js +172 -0
  17. package/dist/notebook-diagnostics.d.ts +52 -0
  18. package/dist/notebook-hooks.d.ts +18 -0
  19. package/dist/plugin-options.d.ts +4 -1
  20. package/dist/plugin-v2.d.ts +31 -0
  21. package/dist/plugin.d.ts +2 -3
  22. package/dist/registrations.d.ts +5 -0
  23. package/dist/rpc.d.ts +134 -0
  24. package/dist/rpc.js +84 -0
  25. package/dist/services/KernelManager.d.ts +45 -0
  26. package/dist/services/NotebookCleanService.d.ts +7 -7
  27. package/dist/services/NotebookEditService.d.ts +15 -12
  28. package/dist/services/NotebookExecutionService.d.ts +41 -12
  29. package/dist/services/NotebookExportService.d.ts +3 -7
  30. package/dist/services/NotebookFileService.d.ts +31 -16
  31. package/dist/services/NotebookInspectService.d.ts +15 -19
  32. package/dist/services/NotebookOutputService.d.ts +7 -10
  33. package/dist/services/NotebookReadService.d.ts +4 -10
  34. package/dist/services/PathService.d.ts +10 -8
  35. package/dist/services/PermissionService.d.ts +13 -8
  36. package/dist/services/PythonService.d.ts +14 -43
  37. package/dist/services/index.d.ts +23 -28
  38. package/dist/services/revision.d.ts +9 -0
  39. package/dist/tool.d.ts +45 -0
  40. package/dist/tools/_readPermission.d.ts +2 -0
  41. package/dist/tools/_resolveOptions.d.ts +13 -2
  42. package/dist/tools/cell_delete.d.ts +4 -13
  43. package/dist/tools/cell_insert.d.ts +10 -21
  44. package/dist/tools/cell_move.d.ts +5 -15
  45. package/dist/tools/clean.d.ts +8 -21
  46. package/dist/tools/doctor.d.ts +3 -11
  47. package/dist/tools/edit.d.ts +10 -21
  48. package/dist/tools/export.d.ts +12 -23
  49. package/dist/tools/inspect.d.ts +7 -19
  50. package/dist/tools/kernel.d.ts +13 -21
  51. package/dist/tools/lsp.d.ts +9 -0
  52. package/dist/tools/outputs.d.ts +15 -29
  53. package/dist/tools/read.d.ts +12 -29
  54. package/dist/tools/repro.d.ts +6 -14
  55. package/dist/tools/run.d.ts +17 -34
  56. package/dist/utils/ansi.d.ts +1 -1
  57. package/dist/utils/atomic-replace.d.ts +2 -0
  58. package/dist/utils/attachments.d.ts +2 -3
  59. package/dist/utils/execution-order.d.ts +7 -0
  60. package/dist/utils/fence.d.ts +1 -0
  61. package/dist/utils/i18n.d.ts +1 -2
  62. package/dist/utils/imports.d.ts +0 -1
  63. package/dist/utils/json-patch.d.ts +58 -0
  64. package/dist/utils/json.d.ts +16 -2
  65. package/dist/utils/limits.d.ts +11 -2
  66. package/dist/utils/markdown-safe.d.ts +2 -0
  67. package/dist/utils/metadata.d.ts +2 -0
  68. package/dist/utils/mime.d.ts +1 -1
  69. package/dist/utils/paths.d.ts +2 -2
  70. package/dist/utils/realpath.d.ts +1 -0
  71. package/dist/utils/rename-hook.d.ts +6 -0
  72. package/dist/utils/truncate.d.ts +0 -1
  73. package/dist/utils/warnings.d.ts +15 -0
  74. package/dist/utils/windows.d.ts +3 -0
  75. package/dist/virtual-materialize.d.ts +25 -0
  76. package/package.json +30 -18
  77. package/python/ipynb_runner.py +418 -31
  78. package/python/requirements.txt +5 -4
  79. package/server.js +3 -0
  80. package/dist/domain/cell.d.ts.map +0 -1
  81. package/dist/domain/errors.d.ts.map +0 -1
  82. package/dist/domain/execution.d.ts.map +0 -1
  83. package/dist/domain/notebook.d.ts.map +0 -1
  84. package/dist/domain/output.d.ts.map +0 -1
  85. package/dist/format/diagnostics.d.ts.map +0 -1
  86. package/dist/format/diff.d.ts.map +0 -1
  87. package/dist/format/markdown.d.ts.map +0 -1
  88. package/dist/format/outputs.d.ts.map +0 -1
  89. package/dist/index.d.ts.map +0 -1
  90. package/dist/plugin-options.d.ts.map +0 -1
  91. package/dist/plugin.d.ts.map +0 -1
  92. package/dist/services/DiffService.d.ts +0 -17
  93. package/dist/services/DiffService.d.ts.map +0 -1
  94. package/dist/services/NotebookCleanService.d.ts.map +0 -1
  95. package/dist/services/NotebookEditService.d.ts.map +0 -1
  96. package/dist/services/NotebookExecutionService.d.ts.map +0 -1
  97. package/dist/services/NotebookExportService.d.ts.map +0 -1
  98. package/dist/services/NotebookFileService.d.ts.map +0 -1
  99. package/dist/services/NotebookInspectService.d.ts.map +0 -1
  100. package/dist/services/NotebookOutputService.d.ts.map +0 -1
  101. package/dist/services/NotebookReadService.d.ts.map +0 -1
  102. package/dist/services/PathService.d.ts.map +0 -1
  103. package/dist/services/PermissionService.d.ts.map +0 -1
  104. package/dist/services/PythonService.d.ts.map +0 -1
  105. package/dist/services/index.d.ts.map +0 -1
  106. package/dist/tools/_resolveOptions.d.ts.map +0 -1
  107. package/dist/tools/cell_delete.d.ts.map +0 -1
  108. package/dist/tools/cell_insert.d.ts.map +0 -1
  109. package/dist/tools/cell_move.d.ts.map +0 -1
  110. package/dist/tools/clean.d.ts.map +0 -1
  111. package/dist/tools/doctor.d.ts.map +0 -1
  112. package/dist/tools/edit.d.ts.map +0 -1
  113. package/dist/tools/export.d.ts.map +0 -1
  114. package/dist/tools/inspect.d.ts.map +0 -1
  115. package/dist/tools/kernel.d.ts.map +0 -1
  116. package/dist/tools/outputs.d.ts.map +0 -1
  117. package/dist/tools/read.d.ts.map +0 -1
  118. package/dist/tools/repro.d.ts.map +0 -1
  119. package/dist/tools/run.d.ts.map +0 -1
  120. package/dist/utils/ansi.d.ts.map +0 -1
  121. package/dist/utils/attachments.d.ts.map +0 -1
  122. package/dist/utils/fiber.d.ts +0 -2
  123. package/dist/utils/fiber.d.ts.map +0 -1
  124. package/dist/utils/i18n.d.ts.map +0 -1
  125. package/dist/utils/imports.d.ts.map +0 -1
  126. package/dist/utils/json.d.ts.map +0 -1
  127. package/dist/utils/limits.d.ts.map +0 -1
  128. package/dist/utils/mime.d.ts.map +0 -1
  129. package/dist/utils/paths.d.ts.map +0 -1
  130. 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
- The plugin is **opt-in**, distributed via npm, and does not modify the OpenCode core. It exposes thirteen agent tools that operate on `.ipynb` files with explicit permissions, granular context control, and a strongly-typed [Effect](https://effect.website) runtime internally.
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 must ask permission every time.
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
- After the package is published on npm, add it to your `opencode.json`:
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
- "plugin": ["opencode-ipynb"]
26
+ "plugins": ["/absolute/path/to/opencode-ipynb"]
25
27
  }
26
28
  ```
27
29
 
28
- For local development, point OpenCode at a checkout or built tarball:
30
+ The V2 line is published from `3.0.0` onward, so the versioned form is:
29
31
 
30
32
  ```json
31
33
  {
32
- "plugin": ["file:./opencode-ipynb"]
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 `"opencode-ipynb"` (or the local path) to your `opencode.json`.
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 textual diff, output clearing policy, permission gate, and per-file lock. |
54
- | `ipynb_cell_insert` | Insert a code/markdown/raw cell before or after a target index. |
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 `ipynb.warmKernel: true` is enabled. |
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 `context.ask` before touching the disk.
120
- - Every execution (`ipynb_run`) calls `context.ask` with rich metadata: file path, mode (`cell` / `range` / `all` / `from`), cell range, save flag, working directory, timeout.
121
- - `PathService` rejects paths that resolve outside of the OpenCode worktree. The lock manager serializes per-file writes to prevent accidental corruption.
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 / base64 are always omitted (you only get a size notice).
130
- - `maxSourceChars` (default 12 000) and `maxOutputChars` (default 6 000) cap the size of any single response.
131
- - `maxTracebackChars` (default 8 000) caps error tracebacks.
132
- - Every truncation appends `... (truncated, use maxXxx to increase)`.
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 relevant constants live in `src/utils/limits.ts`.
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. Three ways to tell the plugin which one to use, in priority order:
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
- "plugin": [
171
- [
172
- "opencode-ipynb",
173
- {
174
- "pythonPath": "C:/Users/Gabriel/miniconda3/envs/data/python.exe",
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` and `ipynb_outputs read` when the user does not pass `maxOutputChars`.
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 `ipynb.pythonPath` only. `OPENCODE_IPYNB_OPTIONS` overrides the whole `ipynb.*` block (a JSON object validated by the same schema as `opencode.json`). These are both set by the plugin on first load if they are not already set in the environment, so an explicit shell value always wins.
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 tries `python`, then `python3`.
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`, full nbformat outputs are preserved on disk.
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 from the npm package via `.npmignore` and are also gitignored so they are not versioned in this repository. Contributors track their work through GitHub Issues and Discussions.
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 v0.1.0 && git push --tags
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 `v0.1.0`. The CI runs `bun run typecheck`, `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`).
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 package name `opencode-ipynb` is currently available on npm. If you publish under a scope instead, update `package.json`, the install snippet, and this release tag convention together.
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 OpenCode TypeScript LSP (built-in) also picks up the workspace TypeScript and therefore respects the `@effect/language-service` plugin. A minimal `opencode.json` in the project root enables it:
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 # Plugin object, registers all 13 tools
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