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
@@ -12,6 +12,7 @@ import { type NotebookExportServiceShape } from "./NotebookExportService.js";
12
12
  import { type NotebookExecutionServiceShape } from "./NotebookExecutionService.js";
13
13
  import { type PythonServiceShape } from "./PythonService.js";
14
14
  import { type KernelManagerShape } from "./KernelManager.js";
15
+ import type { WarningSink } from "../utils/warnings.js";
15
16
  export { type PathServiceShape, type PathEnv, makePathService } from "./PathService.js";
16
17
  export { type PermissionServiceShape, type PermissionRequest, type PermissionKind, makePermissionService } from "./PermissionService.js";
17
18
  export { type NotebookFileServiceShape, makeNotebookFileService } from "./NotebookFileService.js";
@@ -30,10 +31,9 @@ export interface NotebookServices {
30
31
  readonly file: NotebookFileServiceShape;
31
32
  readonly python: PythonServiceShape;
32
33
  readonly kernel: KernelManagerShape;
33
- /** Interpreter selected from plugin options/env, when configured. */
34
34
  readonly pythonPath: string | undefined;
35
- /** Invalid pythonPath configuration, surfaced by Python-dependent tools. */
36
35
  readonly pythonPathError: string | undefined;
36
+ readonly envOptionsError: string | undefined;
37
37
  readonly inspect: ReturnType<typeof makeInspectImpl>;
38
38
  readonly read: NotebookReadServiceShape;
39
39
  readonly edit: NotebookEditServiceShape;
@@ -43,6 +43,8 @@ export interface NotebookServices {
43
43
  readonly execution: NotebookExecutionServiceShape;
44
44
  }
45
45
  export declare const disposeSharedKernelManager: (scope?: object) => Promise<void>;
46
- export declare const buildServices: (ctx: ToolContext) => NotebookServices;
47
- declare const resolveOptionsFromEnv: (instanceOptions?: unknown) => PluginOptions;
48
- export { resolveOptionsFromEnv };
46
+ export interface BuildServicesOptions {
47
+ readonly warningSink?: WarningSink | undefined;
48
+ }
49
+ export declare const buildServices: (ctx: ToolContext, options?: BuildServicesOptions) => NotebookServices;
50
+ export declare const resolveOptionsFromEnv: (instanceOptions?: unknown) => PluginOptions;
@@ -1,15 +1,9 @@
1
1
  import { Effect } from "effect";
2
- import { NotebookNotFoundError, NotebookValidationError, PathOutsideWorktreeError } from "../domain/errors.js";
2
+ import { NotebookNotFoundError, NotebookParseError, NotebookValidationError, PathOutsideWorktreeError } from "../domain/errors.js";
3
3
  import type { NotebookFileServiceShape } from "./NotebookFileService.js";
4
- type RevisionError = NotebookNotFoundError | NotebookValidationError | PathOutsideWorktreeError;
5
- /** Resolve the canonical target before prompting; I/O uses this pinned path. */
4
+ type RevisionError = NotebookNotFoundError | NotebookParseError | NotebookValidationError | PathOutsideWorktreeError;
6
5
  export declare const pinRealPath: (filePath: string) => Effect.Effect<string, never>;
7
- /** SHA-256 of the exact bytes on disk, used to detect external edits. */
8
6
  export declare const contentHash: (text: string) => string;
9
7
  export declare const readRevision: (fileSvc: NotebookFileServiceShape, absPath: string) => Effect.Effect<string, RevisionError>;
10
- /**
11
- * Fail instead of overwriting a notebook that changed while the tool held it
12
- * open (for example during an interactive permission prompt).
13
- */
14
8
  export declare const assertRevisionUnchanged: (fileSvc: NotebookFileServiceShape, absPath: string, expected: string) => Effect.Effect<void, RevisionError>;
15
9
  export {};
package/dist/tool.d.ts CHANGED
@@ -1,25 +1,15 @@
1
1
  import { Effect } from "effect";
2
2
  import type { z } from "zod";
3
- /**
4
- * Minimal tool contract used by the notebook implementations.
5
- *
6
- * The plugin is V2-only, but keeping this small internal helper lets every
7
- * tool declare zod args once and share the same result/context shape. The V2
8
- * adapter converts the zod args to JSON Schema and maps results to V2 content.
9
- */
10
3
  export interface ToolContext {
11
4
  readonly sessionID: string;
12
5
  readonly messageID: string;
13
6
  readonly agent: string;
14
- /** Current project directory for this session. */
15
7
  readonly directory: string;
16
- /** Project worktree root for this session. */
17
8
  readonly worktree: string;
18
9
  readonly abort: AbortSignal;
19
- /** Options from this plugin instance. */
20
10
  readonly pluginOptions?: unknown;
21
- /** Identity of the plugin instance, used to scope warm-kernel cleanup. */
22
11
  readonly pluginScope?: object;
12
+ readonly warningSink?: import("./utils/warnings.js").WarningSink | undefined;
23
13
  metadata(input: {
24
14
  title?: string;
25
15
  metadata?: Record<string, any>;
@@ -51,16 +41,5 @@ export interface ToolDefinition<Args extends z.ZodRawShape = z.ZodRawShape> {
51
41
  }
52
42
  export type AnyToolDefinition = ToolDefinition<z.ZodRawShape>;
53
43
  export declare const tool: <Args extends z.ZodRawShape>(definition: ToolDefinition<Args>) => ToolDefinition<Args>;
54
- /**
55
- * Run an Effect from a tool executor while preserving typed failures.
56
- *
57
- * `Effect.runPromiseExit` preserves the typed failure, so permission errors
58
- * can be rethrown as the V2 host expects.
59
- */
60
44
  export declare const runToolEffect: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
61
- /**
62
- * V2 permission.assert rejections must propagate to the host instead of being
63
- * converted into normal tool output. When the permission service preserved the
64
- * original host error, rethrow that; otherwise rethrow the tagged error.
65
- */
66
45
  export declare const rethrowPermissionDenied: (error: unknown) => void;
@@ -1,8 +1,2 @@
1
1
  import type { ToolContext } from "../tool.js";
2
- /**
3
- * Custom V2 tools are not automatically covered by the host's native `read`
4
- * action. Ask explicitly before handing notebook content to a read-only tool.
5
- * The lexical and resolved paths are both requested so a symlink alias cannot
6
- * bypass a deny rule on the real notebook.
7
- */
8
2
  export declare const assertReadPermission: (context: ToolContext, filePath: string) => Promise<void>;
@@ -1,4 +1,3 @@
1
1
  export declare const stripAnsi: (text: string) => string;
2
- /** Remove terminal control sequences/bytes while keeping newlines and tabs. */
3
2
  export declare const sanitizeTerminal: (text: string) => string;
4
3
  export declare const hasAnsi: (text: string) => boolean;
@@ -1,6 +1,2 @@
1
- /**
2
- * Rename `temp` over `target`. On Windows rename fails when the target
3
- * exists; move the original to a backup first and restore it if the second
4
- * rename fails, so a failed replace never deletes the only copy.
5
- */
6
- export declare const replaceFile: (temp: string, target: string) => Promise<void>;
1
+ import { type WarningSink } from "./warnings.js";
2
+ export declare const replaceFile: (temp: string, target: string, sink?: WarningSink) => Promise<void>;
@@ -4,5 +4,4 @@ export interface ExecutionOrderEntry {
4
4
  readonly executionCount: number;
5
5
  readonly previousCount: number;
6
6
  }
7
- /** Cells whose execution_count is lower than a previous non-null count. */
8
7
  export declare const analyzeExecutionOrder: (notebook: NotebookRaw) => ReadonlyArray<ExecutionOrderEntry>;
@@ -1,2 +1 @@
1
- /** Fence long enough that backticks inside the content cannot close it. */
2
1
  export declare const codeFence: (text: string) => string;
@@ -1,9 +1,3 @@
1
1
  export declare const isStdlibModule: (name: string) => boolean;
2
2
  export declare const isRelativeImport: (name: string) => boolean;
3
- /**
4
- * Extract the top-level modules imported by Python source. For
5
- * `from pandas import DataFrame` the module is `pandas`, not `DataFrame`.
6
- * This is intentionally a lightweight parser (not a Python AST); it handles
7
- * aliases, comments, dotted modules, and parenthesized from-imports.
8
- */
9
3
  export declare const extractImportNames: (source: string) => string[];
@@ -0,0 +1,58 @@
1
+ export interface JsonTextStyle {
2
+ readonly newline: "\n" | "\r\n";
3
+ readonly itemSeparator: string;
4
+ readonly keySeparator: string;
5
+ readonly ensureAscii: boolean;
6
+ readonly unit: string;
7
+ }
8
+ interface LiteralNode {
9
+ readonly kind: "literal";
10
+ readonly start: number;
11
+ readonly end: number;
12
+ readonly value: unknown;
13
+ }
14
+ interface ItemSpan {
15
+ readonly start: number;
16
+ readonly end: number;
17
+ }
18
+ interface ArrayNode {
19
+ readonly kind: "array";
20
+ readonly start: number;
21
+ readonly end: number;
22
+ readonly items: ReadonlyArray<ItemSpan>;
23
+ readonly value: ReadonlyArray<unknown>;
24
+ }
25
+ interface ObjectEntry {
26
+ readonly key: string;
27
+ readonly keyStart: number;
28
+ readonly value: JsonNode;
29
+ }
30
+ interface ObjectNode {
31
+ readonly kind: "object";
32
+ readonly start: number;
33
+ readonly end: number;
34
+ readonly entries: ReadonlyArray<ObjectEntry>;
35
+ readonly value: Record<string, unknown>;
36
+ }
37
+ export type JsonNode = LiteralNode | ArrayNode | ObjectNode;
38
+ export declare const MAX_JSON_DEPTH = 512;
39
+ export declare const jsonEqual: (left: unknown, right: unknown) => boolean;
40
+ interface Edit {
41
+ readonly start: number;
42
+ readonly end: number;
43
+ readonly text: string;
44
+ }
45
+ export declare const applyEdits: (text: string, edits: ReadonlyArray<Edit>) => string | undefined;
46
+ export interface PatchOptions {
47
+ readonly style: JsonTextStyle;
48
+ }
49
+ export type PatchFailureReason = "parse-failed" | "patch-threw" | "overlapping-edits" | "not-representable" | "verification-failed" | "too-deep";
50
+ export interface PatchResult {
51
+ readonly text?: string;
52
+ readonly reason?: PatchFailureReason;
53
+ }
54
+ export declare const patchJsonTextDetailed: (text: string, next: unknown, options: PatchOptions) => PatchResult;
55
+ export declare const patchJsonText: (text: string, next: unknown, options: PatchOptions) => string | undefined;
56
+ export declare const jsonDepth: (value: unknown, depth?: number) => number;
57
+ export declare const formatJsonValue: (value: unknown, style: JsonTextStyle, multiline?: boolean) => string;
58
+ export {};
@@ -1,4 +1,19 @@
1
1
  import { Effect } from "effect";
2
2
  import { NotebookParseError } from "../domain/errors.js";
3
+ import { type JsonTextStyle, type PatchFailureReason } from "./json-patch.js";
4
+ export { MAX_JSON_DEPTH } from "./json-patch.js";
5
+ export type { PatchFailureReason };
3
6
  export declare const safeParseJson: (text: string, filePath: string) => Effect.Effect<unknown, NotebookParseError>;
4
- export declare const stringifyNotebook: (notebook: unknown) => string;
7
+ export interface NotebookFormat extends JsonTextStyle {
8
+ readonly trailingNewline: boolean;
9
+ }
10
+ export declare const DEFAULT_NOTEBOOK_FORMAT: NotebookFormat;
11
+ export declare const detectNotebookFormat: (text: string) => NotebookFormat;
12
+ export declare const stringifyNotebook: (notebook: unknown, format?: NotebookFormat) => string;
13
+ export type WriteMode = "patched" | "fallback";
14
+ export interface RewriteResult {
15
+ readonly text: string;
16
+ readonly mode: WriteMode;
17
+ readonly reason?: PatchFailureReason;
18
+ }
19
+ export declare const rewriteNotebookTextDetailed: (previousText: string, notebook: unknown, format: NotebookFormat) => RewriteResult;
@@ -7,7 +7,6 @@ export declare const DEFAULT_RUN_TIMEOUT_MS = 120000;
7
7
  export declare const DEFAULT_INSPECT_PREVIEW_CHARS = 240;
8
8
  export declare const MAX_NOTEBOOK_BYTES: number;
9
9
  export declare const MAX_READ_CELLS = 500;
10
- /** Hard caps that protect the host context from pathological notebooks. */
11
10
  export declare const MAX_INSPECT_CELLS = 1000;
12
11
  export declare const MAX_METADATA_CHARS = 20000;
13
12
  export declare const MAX_RUN_RESPONSE_CHARS = 120000;
@@ -1,7 +1,2 @@
1
- /** Single-line label safe inside markdown table/labels. */
2
1
  export declare const sanitizeInline: (text: string) => string;
3
- /**
4
- * Truncate rendered markdown without leaving a code fence open. Any fence
5
- * opened before the cut is closed before the truncation hint is appended.
6
- */
7
2
  export declare const truncateMarkdown: (text: string, maxChars: number, hint: string) => string;
@@ -1,3 +1,2 @@
1
1
  import type { NotebookDiagnostic } from "../notebook-diagnostics.js";
2
- /** Cap diagnostics metadata by both entry count and serialized bytes. */
3
2
  export declare const capDiagnosticMetadata: (diagnostics: ReadonlyArray<NotebookDiagnostic>) => ReadonlyArray<NotebookDiagnostic>;
@@ -3,6 +3,7 @@ export interface NormalizeOptions {
3
3
  readonly resolveAbsolute?: (p: string) => string;
4
4
  }
5
5
  export declare const normalizeSlashes: (p: string, platform?: NodeJS.Platform) => string;
6
+ export declare const absoluteDriveRoot: (value: string, platform?: NodeJS.Platform) => string;
6
7
  export declare const isAbsolutePath: (p: string) => boolean;
7
8
  export declare const hasIpynbExtension: (p: string) => boolean;
8
9
  export interface ResolveInput {
@@ -18,3 +19,4 @@ export interface RelativeOptions {
18
19
  }
19
20
  export declare const makeRelative: (from: string, to: string, opts?: RelativeOptions) => string;
20
21
  export declare const toForwardSlashes: (p: string) => string;
22
+ export declare const pathInside: (root: string, target: string, platform?: NodeJS.Platform) => boolean;
@@ -0,0 +1 @@
1
+ export declare const realpathWithRetry: (target: string) => Promise<string>;
@@ -0,0 +1,6 @@
1
+ type RenameHook = (target: string) => Promise<void> | void;
2
+ export declare const setBeforeRenameHook: (next: RenameHook | undefined) => void;
3
+ export declare const setAfterRenameHook: (next: RenameHook | undefined) => void;
4
+ export declare const beforeRenameHook: (target: string) => Promise<void>;
5
+ export declare const afterRenameHook: (target: string) => Promise<void>;
6
+ export {};
@@ -0,0 +1,15 @@
1
+ import { Effect } from "effect";
2
+ export type WarningSource = "atomic-replace" | "cleanup" | "json-patch" | "lock" | "permission-alias" | "path-resolution" | "python-probe" | "revision-check" | "shell-command" | "sidecar-cleanup" | "temp-unlink";
3
+ export interface Warning {
4
+ readonly source: WarningSource;
5
+ readonly message: string;
6
+ readonly detail?: string;
7
+ }
8
+ export interface WarningSink {
9
+ readonly add: (warning: Warning) => void;
10
+ readonly drain: () => ReadonlyArray<Warning>;
11
+ }
12
+ export declare const makeWarningSink: () => WarningSink;
13
+ export declare const warningFrom: (source: WarningSource, error: unknown, context?: string) => Warning;
14
+ export declare const ignoreExpectedFailure: <A>(sink: WarningSink | undefined, source: WarningSource, context: string, effect: Effect.Effect<A, unknown>) => Effect.Effect<A | undefined>;
15
+ export declare const bestEffort: (sink: WarningSink | undefined, source: WarningSource, context: string, action: () => Promise<unknown>) => Promise<void>;
@@ -1,4 +1,3 @@
1
- /** Absolute taskkill path so CreateProcess never searches the project cwd. */
1
+ import { type WarningSink } from "./warnings.js";
2
2
  export declare const taskkillPath: () => string;
3
- /** Best-effort taskkill with an error listener (never crashes the host). */
4
- export declare const killWindowsTree: (pid: number) => void;
3
+ export declare const killWindowsTree: (pid: number, sink?: WarningSink) => void;
@@ -1,36 +1,25 @@
1
1
  import type { NotebookVirtualDocument } from "./lsp.js";
2
+ import { type Warning, type WarningSink } from "./utils/warnings.js";
2
3
  export interface MaterializedCell {
3
4
  readonly cellIndex: number;
4
5
  readonly cellType: string;
5
- /** First line in the materialized file, 1-based and inclusive. */
6
6
  readonly startLine: number;
7
- /** Last line in the materialized file, 1-based and inclusive. */
8
7
  readonly endLine: number;
9
8
  }
10
9
  export interface MaterializedDocument {
11
10
  readonly path: string;
12
11
  readonly text: string;
13
12
  readonly cells: ReadonlyArray<MaterializedCell>;
13
+ readonly warnings?: ReadonlyArray<Warning>;
14
+ }
15
+ export interface MaterializeOptions {
16
+ readonly warningSink?: WarningSink | undefined;
17
+ }
18
+ export interface CleanupOptions {
19
+ readonly warningSink?: WarningSink;
14
20
  }
15
- /** Path of the materialized sidecar for a notebook. */
16
21
  export declare const materializedPath: (filePath: string, root?: string) => string;
17
- /**
18
- * Write the notebook's virtual Python document beside the notebook so an
19
- * external LSP plugin can open it with its own `lsp` tool. The path must stay
20
- * inside the session/worktree (opencode-v2-lsp-support rejects paths outside
21
- * its root), and living next to the notebook lets pyright resolve sibling
22
- * imports exactly like the notebook itself.
23
- *
24
- * IPython magics are blanked exactly like the diagnostics path, preserving
25
- * line/column positions so hover and definitions still map to cells.
26
- */
27
- export declare const materializeVirtualDocument: (document: NotebookVirtualDocument, worktree: string) => Promise<MaterializedDocument>;
28
- /**
29
- * Refresh an already materialized document after an edit. Does nothing until
30
- * the notebook has been materialized at least once.
31
- */
32
- export declare const refreshMaterializedDocument: (document: NotebookVirtualDocument, worktree: string) => Promise<boolean>;
33
- /** True when this notebook already has a materialized sidecar. */
34
- export declare const hasMaterializedDocument: (worktree: string, filePath: string) => Promise<boolean>;
35
- /** Remove only this plugin's materialized documents. */
36
- export declare const cleanupVirtualDocuments: (worktree: string) => Promise<void>;
22
+ export declare const materializeVirtualDocument: (document: NotebookVirtualDocument, worktree: string, options?: MaterializeOptions) => Promise<MaterializedDocument>;
23
+ export declare const refreshMaterializedDocument: (document: NotebookVirtualDocument, worktree: string, options?: MaterializeOptions) => Promise<boolean>;
24
+ export declare const hasMaterializedDocument: (worktree: string, filePath: string, options?: MaterializeOptions) => Promise<boolean>;
25
+ export declare const cleanupVirtualDocuments: (worktree: string, options?: CleanupOptions) => Promise<void>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-ipynb",
3
- "version": "2.0.0",
3
+ "version": "3.0.0",
4
4
  "description": "OpenCode community plugin that adds robust .ipynb (Jupyter Notebook) support: inspect, read, edit, run, outputs, clean, export, reproducibility reports, and warm kernels.",
5
5
  "type": "module",
6
6
  "packageManager": "bun@1.4.4",
@@ -52,7 +52,7 @@
52
52
  "test": "bun test",
53
53
  "lint:effect": "tsc --noEmit",
54
54
  "prepare:effect-lsp": "effect-language-service patch",
55
- "prepack": "node -e \"for (const f of ['dist/index.js','dist/index.d.ts','dist/lsp.js','dist/lsp.d.ts','dist/rpc.js','dist/rpc.d.ts']) if (!require('node:fs').existsSync(f)) { console.error(f + ' is missing; run: bun run build'); process.exit(1) }\"",
55
+ "prepack": "bun run scripts/prepack-check.ts",
56
56
  "test:coverage": "bun test --coverage"
57
57
  },
58
58
  "keywords": [