opencode-ipynb 2.0.0 → 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 (46) hide show
  1. package/CHANGELOG.md +150 -0
  2. package/README.md +12 -6
  3. package/dist/domain/cell.d.ts +2 -2
  4. package/dist/domain/notebook.d.ts +5 -2
  5. package/dist/format/notebook.d.ts +0 -1
  6. package/dist/format/outputs.d.ts +0 -1
  7. package/dist/index.js +2969 -717
  8. package/dist/load-document.d.ts +0 -6
  9. package/dist/lsp.d.ts +4 -43
  10. package/dist/lsp.js +45 -2
  11. package/dist/notebook-diagnostics.d.ts +15 -18
  12. package/dist/notebook-hooks.d.ts +0 -5
  13. package/dist/plugin-v2.d.ts +3 -7
  14. package/dist/rpc.d.ts +0 -7
  15. package/dist/services/KernelManager.d.ts +9 -0
  16. package/dist/services/NotebookCleanService.d.ts +4 -0
  17. package/dist/services/NotebookEditService.d.ts +10 -1
  18. package/dist/services/NotebookExecutionService.d.ts +28 -3
  19. package/dist/services/NotebookFileService.d.ts +18 -9
  20. package/dist/services/NotebookInspectService.d.ts +0 -5
  21. package/dist/services/NotebookOutputService.d.ts +3 -0
  22. package/dist/services/PathService.d.ts +5 -1
  23. package/dist/services/PermissionService.d.ts +10 -3
  24. package/dist/services/PythonService.d.ts +5 -15
  25. package/dist/services/index.d.ts +7 -5
  26. package/dist/services/revision.d.ts +2 -8
  27. package/dist/tool.d.ts +1 -22
  28. package/dist/tools/_readPermission.d.ts +0 -6
  29. package/dist/utils/ansi.d.ts +0 -1
  30. package/dist/utils/atomic-replace.d.ts +2 -6
  31. package/dist/utils/execution-order.d.ts +0 -1
  32. package/dist/utils/fence.d.ts +0 -1
  33. package/dist/utils/imports.d.ts +0 -6
  34. package/dist/utils/json-patch.d.ts +58 -0
  35. package/dist/utils/json.d.ts +16 -1
  36. package/dist/utils/limits.d.ts +0 -1
  37. package/dist/utils/markdown-safe.d.ts +0 -5
  38. package/dist/utils/metadata.d.ts +0 -1
  39. package/dist/utils/paths.d.ts +2 -0
  40. package/dist/utils/realpath.d.ts +1 -0
  41. package/dist/utils/rename-hook.d.ts +6 -0
  42. package/dist/utils/warnings.d.ts +15 -0
  43. package/dist/utils/windows.d.ts +2 -3
  44. package/dist/virtual-materialize.d.ts +12 -23
  45. package/package.json +2 -2
  46. package/python/ipynb_runner.py +189 -32
package/CHANGELOG.md CHANGED
@@ -1,5 +1,155 @@
1
1
  # Changelog
2
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
+
3
153
  ## 2.0.0
4
154
 
5
155
  - OpenCode V2-only plugin (`@opencode/plugin` 2.2.2). The V1 `server()` export is removed.
package/README.md CHANGED
@@ -18,7 +18,7 @@ The plugin is **opt-in**, distributed via npm, and does not modify the OpenCode
18
18
 
19
19
  ## Installation
20
20
 
21
- OpenCode 2.x loads plugins from the `plugins` key. Until the V2 line (`2.0.0`) is published, point OpenCode at a checkout directory:
21
+ OpenCode 2.x loads plugins from the `plugins` key. Point OpenCode at a checkout directory for an unreleased change:
22
22
 
23
23
  ```json
24
24
  {
@@ -27,15 +27,17 @@ OpenCode 2.x loads plugins from the `plugins` key. Until the V2 line (`2.0.0`) i
27
27
  }
28
28
  ```
29
29
 
30
- The npm `latest` tag still points at the V1 `0.1.2` package, which does **not** load in OpenCode 2. After the V2 package is published, the versioned form is:
30
+ The V2 line is published from `3.0.0` onward, so the versioned form is:
31
31
 
32
32
  ```json
33
33
  {
34
34
  "$schema": "https://opencode.ai/config.json",
35
- "plugins": ["opencode-ipynb@2.0.0"]
35
+ "plugins": ["opencode-ipynb@3.0.0"]
36
36
  }
37
37
  ```
38
38
 
39
+ Anything below `2.0.0` is the V1 package, which does **not** load in OpenCode 2.
40
+
39
41
  `opencode.example.jsonc` is a machine-independent local example.
40
42
 
41
43
  Or run directly from this repo:
@@ -55,7 +57,7 @@ Then add the **absolute path** to this checkout to the `plugins` array in your `
55
57
  | -------------------- | ------- |
56
58
  | `ipynb_inspect` | Compact summary: kernel/language metadata, cell table, output stats, execution-order warnings, optional missing-package checks. |
57
59
  | `ipynb_read` | Granular read of one cell or a range, with optional outputs/errors/metadata/images and truncation limits. |
58
- | `ipynb_edit` | Safe per-cell source edit with a concise confirmation, output clearing policy, permission gate, and per-file lock. |
60
+ | `ipynb_edit` | Safe per-cell source edit with a concise confirmation, output clearing policy, permission gate, and in-process per-file lock. |
59
61
  | `ipynb_cell_insert` | Insert a code/markdown/raw cell at a target index, or append when the index is omitted. |
60
62
  | `ipynb_cell_delete` | Delete one cell by index and return a preview of the deleted source. |
61
63
  | `ipynb_cell_move` | Move one cell to a new index. |
@@ -124,6 +126,10 @@ ipynb_export({
124
126
 
125
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.
126
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
+
127
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):
128
134
 
129
135
  ```text
@@ -153,7 +159,7 @@ The cell-mapped errors are also available as `metadata.notebookDiagnostics`; `me
153
159
 
154
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`.
155
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.
156
- - `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 to prevent accidental corruption.
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.
157
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.
158
164
 
159
165
  ## Context control
@@ -365,7 +371,7 @@ bun run build
365
371
  npm pack --dry-run
366
372
  ```
367
373
 
368
- The `2.0.0` release is the V2-only line. The npm `latest` tag currently points at the V1 `0.1.2` package; publish `2.0.0` before advertising the package name as a V2 install. 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.
369
375
 
370
376
  ## Effect LSP setup (for development)
371
377
 
@@ -7,7 +7,7 @@ export declare const CodeCellSchema: z.ZodObject<{
7
7
  cell_type: z.ZodLiteral<"code">;
8
8
  id: z.ZodOptional<z.ZodString>;
9
9
  metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
10
- execution_count: z.ZodUnion<readonly [z.ZodNullable<z.ZodNumber>, z.ZodNull]>;
10
+ execution_count: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
11
11
  source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
12
12
  outputs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
13
13
  }, z.core.$loose>;
@@ -32,7 +32,7 @@ export declare const CellSchema: z.ZodUnion<readonly [z.ZodObject<{
32
32
  cell_type: z.ZodLiteral<"code">;
33
33
  id: z.ZodOptional<z.ZodString>;
34
34
  metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
35
- execution_count: z.ZodUnion<readonly [z.ZodNullable<z.ZodNumber>, z.ZodNull]>;
35
+ execution_count: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
36
36
  source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
37
37
  outputs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
38
38
  }, z.core.$loose>, z.ZodObject<{
@@ -26,7 +26,7 @@ export declare const NotebookMetadataSchema: z.ZodObject<{
26
26
  export type NotebookMetadataRaw = z.infer<typeof NotebookMetadataSchema>;
27
27
  export declare const NotebookSchema: z.ZodObject<{
28
28
  nbformat: z.ZodNumber;
29
- nbformat_minor: z.ZodOptional<z.ZodNumber>;
29
+ nbformat_minor: z.ZodNumber;
30
30
  metadata: z.ZodDefault<z.ZodObject<{
31
31
  kernelspec: z.ZodOptional<z.ZodObject<{
32
32
  name: z.ZodOptional<z.ZodString>;
@@ -43,7 +43,7 @@ export declare const NotebookSchema: z.ZodObject<{
43
43
  cell_type: z.ZodLiteral<"code">;
44
44
  id: z.ZodOptional<z.ZodString>;
45
45
  metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
46
- execution_count: z.ZodUnion<readonly [z.ZodNullable<z.ZodNumber>, z.ZodNull]>;
46
+ execution_count: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
47
47
  source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
48
48
  outputs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
49
49
  }, z.core.$loose>, z.ZodObject<{
@@ -63,3 +63,6 @@ export declare const NotebookSchema: z.ZodObject<{
63
63
  export type NotebookRaw = z.infer<typeof NotebookSchema>;
64
64
  export declare const normalizeSource: (source: z.infer<typeof SourceSchema>) => string;
65
65
  export declare const cellSource: (cell: CellRaw) => string;
66
+ export declare const splitSourceLines: (source: string) => string[];
67
+ export declare const formatSourceLike: (previous: z.infer<typeof SourceSchema>, next: string) => z.infer<typeof SourceSchema>;
68
+ export declare const applyNotebookDefaults: (raw: unknown) => NotebookRaw;
@@ -1,7 +1,6 @@
1
1
  export interface MarkdownCellInput {
2
2
  readonly cell_type: "code" | "markdown" | "raw";
3
3
  readonly source: string;
4
- /** Rendered image links appended after a raw-cell fence. */
5
4
  readonly attachments?: ReadonlyArray<string> | undefined;
6
5
  }
7
6
  export interface FormatMarkdownOptions {
@@ -3,7 +3,6 @@ import type { NotebookRaw } from "../domain/notebook.js";
3
3
  import type { ToolAttachment } from "../tool.js";
4
4
  export interface OutputFormatOptions {
5
5
  readonly includeImages: boolean;
6
- /** Use the hard-limit hint when the response cap, not the user, wins. */
7
6
  readonly hardCap?: boolean | undefined;
8
7
  readonly saveImages?: boolean | undefined;
9
8
  readonly maxOutputChars: number;