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
@@ -5,12 +5,6 @@ export interface LoadDocumentContext {
5
5
  readonly worktree: string;
6
6
  readonly allowOutsideWorktree?: boolean;
7
7
  readonly options: PluginOptions;
8
- /** Materialization/RPC do not need a Python interpreter. */
9
8
  readonly resolvePython?: boolean;
10
9
  }
11
- /**
12
- * Resolve, confine, read, and project a notebook onto its virtual Python
13
- * document. Shared by the RPC hook and ipynb_lsp so both use exactly the same
14
- * real-path and option rules.
15
- */
16
10
  export declare const loadNotebookDocument: (context: LoadDocumentContext, filePath: string) => Promise<NotebookVirtualDocument>;
package/dist/lsp.d.ts CHANGED
@@ -1,10 +1,3 @@
1
- /**
2
- * Minimal notebook shape accepted by the virtual-document builder.
3
- *
4
- * It is structurally compatible with the plugin's parsed `NotebookRaw`, but
5
- * keeping it local means the `opencode-ipynb/lsp` entry has no zod/Effect
6
- * dependency and stays lightweight for third-party LSP plugins.
7
- */
8
1
  export interface NotebookLike {
9
2
  readonly metadata: {
10
3
  readonly language_info?: unknown;
@@ -15,43 +8,22 @@ export interface NotebookLike {
15
8
  readonly source: string | ReadonlyArray<string>;
16
9
  }>;
17
10
  }
18
- /**
19
- * A code cell projected into the notebook's virtual document.
20
- *
21
- * Line numbers are zero-based, matching LSP positions. `startLine` is the
22
- * first virtual line for the cell and `endLine` is exclusive.
23
- */
24
11
  export interface NotebookCellDocument {
25
12
  readonly cellIndex: number;
26
13
  readonly cellType: "code" | "markdown" | "raw";
27
- /** LSP language id for this cell (`python`, `markdown`, `plaintext`). */
28
14
  readonly languageId: string;
29
- /** Cell source, useful for native LSP 3.17 notebook sync. */
30
15
  readonly text: string;
31
- /** Stable cell document URI when the caller provides one. */
32
16
  readonly uri?: string;
33
17
  readonly startLine: number;
34
18
  readonly endLine: number;
35
19
  readonly lineCount: number;
36
20
  }
37
- /**
38
- * A single virtual document containing the notebook's code cells.
39
- *
40
- * Language servers do not understand `.ipynb` JSON, so tools can send `text`
41
- * as a normal document and use `cells` to map positions back to the notebook.
42
- * This is intentionally provider-agnostic: pyright, jedi-language-server, or a
43
- * future OpenCode notebook LSP can all consume it.
44
- */
45
21
  export interface NotebookVirtualDocument {
46
22
  readonly filePath: string;
47
- /** Notebook URI (for clients that model notebook documents explicitly). */
48
23
  readonly notebookUri?: string;
49
24
  readonly languageId: string;
50
- /** Native language file extension from kernel metadata, e.g. `.py`. */
51
25
  readonly fileExtension?: string;
52
- /** Jupyter kernelspec name, when present, so an LSP can select the right env. */
53
26
  readonly kernelName?: string;
54
- /** Configured Python interpreter, when the plugin has one. */
55
27
  readonly pythonPath?: string;
56
28
  readonly text: string;
57
29
  readonly cells: ReadonlyArray<NotebookCellDocument>;
@@ -67,31 +39,20 @@ export interface VirtualPosition {
67
39
  }
68
40
  export interface VirtualDocumentOptions {
69
41
  readonly filePath?: string;
70
- /** Include markdown/raw cells in the concatenated text. Defaults to false. */
71
42
  readonly includeMarkdown?: boolean;
72
- /** Python interpreter configured for this plugin instance. */
73
43
  readonly pythonPath?: string;
74
- /** URI representing the notebook itself. */
75
44
  readonly notebookUri?: string;
76
- /** Stable URI for a cell document (native LSP 3.17 notebook sync). */
77
45
  readonly cellUri?: (cellIndex: number) => string;
78
46
  }
79
47
  export interface PositionMapper {
80
48
  readonly toCellPosition: (line: number, character: number) => CellPosition | undefined;
81
49
  readonly toVirtualPosition: (cellIndex: number, line: number, character: number) => VirtualPosition | undefined;
82
50
  }
83
- /**
84
- * Build a virtual document from a parsed notebook.
85
- *
86
- * Code cells are separated by a newline, which preserves the cell-local line
87
- * count and lets `toCellPosition`/`toVirtualPosition` map both directions.
88
- * Each cell also carries its own text and optional URI so a client that
89
- * supports LSP 3.17 notebook synchronization can use cell documents directly.
90
- */
91
51
  export declare const buildNotebookVirtualDocument: (notebook: NotebookLike, options?: VirtualDocumentOptions) => NotebookVirtualDocument;
92
- /** Map a zero-based position in the virtual document back to a cell position. */
52
+ export declare const cellsAroundIndex: (document: NotebookVirtualDocument, cellIndex: number) => {
53
+ readonly current: NotebookCellDocument;
54
+ readonly previous: NotebookCellDocument | undefined;
55
+ } | undefined;
93
56
  export declare const toCellPosition: (document: NotebookVirtualDocument, line: number, character: number) => CellPosition | undefined;
94
- /** Map a zero-based position inside a cell to the virtual document. */
95
57
  export declare const toVirtualPosition: (document: NotebookVirtualDocument, cellIndex: number, line: number, character: number) => VirtualPosition | undefined;
96
- /** Convenience mapper bound to a built document. */
97
58
  export declare const makePositionMapper: (document: NotebookVirtualDocument) => PositionMapper;
package/dist/lsp.js CHANGED
@@ -101,8 +101,49 @@ var buildNotebookVirtualDocument = (notebook, options = {}) => {
101
101
  cells
102
102
  };
103
103
  };
104
+ var cellCoveringLine = (cells, line) => {
105
+ let low = 0;
106
+ let high = cells.length - 1;
107
+ let candidate;
108
+ while (low <= high) {
109
+ const mid = low + high >> 1;
110
+ const cell = cells[mid];
111
+ if (cell.startLine <= line) {
112
+ candidate = cell;
113
+ low = mid + 1;
114
+ } else {
115
+ high = mid - 1;
116
+ }
117
+ }
118
+ return candidate !== undefined && line < candidate.endLine ? candidate : undefined;
119
+ };
120
+ var cellPositionOfIndex = (cells, cellIndex) => {
121
+ let low = 0;
122
+ let high = cells.length - 1;
123
+ while (low <= high) {
124
+ const mid = low + high >> 1;
125
+ const cell = cells[mid];
126
+ if (cell.cellIndex === cellIndex)
127
+ return mid;
128
+ if (cell.cellIndex < cellIndex) {
129
+ low = mid + 1;
130
+ } else {
131
+ high = mid - 1;
132
+ }
133
+ }
134
+ return -1;
135
+ };
136
+ var cellsAroundIndex = (document, cellIndex) => {
137
+ const position = cellPositionOfIndex(document.cells, cellIndex);
138
+ if (position < 0)
139
+ return;
140
+ return {
141
+ current: document.cells[position],
142
+ previous: position > 0 ? document.cells[position - 1] : undefined
143
+ };
144
+ };
104
145
  var toCellPosition = (document, line, character) => {
105
- const cell = document.cells.find((candidate) => line >= candidate.startLine && line < candidate.endLine);
146
+ const cell = cellCoveringLine(document.cells, line);
106
147
  if (!cell)
107
148
  return;
108
149
  return {
@@ -112,7 +153,8 @@ var toCellPosition = (document, line, character) => {
112
153
  };
113
154
  };
114
155
  var toVirtualPosition = (document, cellIndex, line, character) => {
115
- const cell = document.cells.find((candidate) => candidate.cellIndex === cellIndex);
156
+ const position = cellPositionOfIndex(document.cells, cellIndex);
157
+ const cell = position >= 0 ? document.cells[position] : undefined;
116
158
  if (!cell || line < 0 || line >= cell.lineCount)
117
159
  return;
118
160
  return { line: cell.startLine + line, character };
@@ -123,6 +165,7 @@ var makePositionMapper = (document) => ({
123
165
  });
124
166
  export {
125
167
  buildNotebookVirtualDocument,
168
+ cellsAroundIndex,
126
169
  makePositionMapper,
127
170
  toCellPosition,
128
171
  toVirtualPosition
@@ -1,4 +1,5 @@
1
1
  import { type NotebookVirtualDocument } from "./lsp.js";
2
+ import { type Warning, type WarningSink } from "./utils/warnings.js";
2
3
  export interface NotebookDiagnostic {
3
4
  readonly cellIndex: number;
4
5
  readonly line: number;
@@ -8,48 +9,44 @@ export interface NotebookDiagnostic {
8
9
  readonly severity: "error";
9
10
  readonly message: string;
10
11
  readonly rule?: string;
12
+ /** pyright reported this for the whole file and supplied no position. */
13
+ readonly fileLevel?: boolean;
11
14
  }
12
15
  export interface NotebookDiagnosticsOptions {
13
16
  readonly filePath: string;
14
17
  readonly document: NotebookVirtualDocument;
15
18
  readonly displayPath?: string;
16
- /** Heading used in the report; defaults to displayPath. */
17
19
  readonly where?: string;
18
20
  readonly tempFilePath?: string;
19
- /** True when the plugin owns the temp file and may reuse/truncate it. */
20
21
  readonly ownedTempFile?: boolean;
21
- /** Ask the host for permission before writing the system-temp fallback. */
22
22
  readonly requestFallbackPermission?: () => Promise<void>;
23
23
  readonly pythonPath?: string;
24
24
  readonly pyrightPath?: string;
25
25
  readonly timeoutMs?: number;
26
26
  readonly signal?: AbortSignal;
27
+ readonly warningSink?: WarningSink;
27
28
  }
28
29
  export interface NotebookDiagnosticsResult {
29
30
  readonly filePath: string;
30
31
  readonly diagnostics: ReadonlyArray<NotebookDiagnostic>;
31
32
  readonly text: string;
32
- readonly skipped?: "pyright-not-found" | "timeout" | "aborted" | "invalid-output" | "not-analyzed" | "temp-unwritable" | "pyright-not-executable";
33
+ readonly warnings?: ReadonlyArray<Warning>;
34
+ readonly skipped?: "pyright-not-found" | "timeout" | "aborted" | "invalid-output" | "not-analyzed" | "temp-unwritable" | "pyright-not-executable" | "unsafe-shell-command";
33
35
  }
34
- /**
35
- * IPython magics and shell escapes are not valid Python. Blank them while
36
- * preserving line and column positions so diagnostics on other lines stay
37
- * correctly mapped. Python-bodied cell magics (`%%time`, `%%capture`, ...)
38
- * keep their body; non-Python cell magics (`%%bash`, `%%html`, ...) blank the
39
- * whole cell.
40
- */
36
+ export declare class ShellCommandError extends Error {
37
+ }
38
+ export declare const hasShellMetacharacters: (value: string) => boolean;
39
+ export declare const shellCommandRefusal: (command: string, args: ReadonlyArray<string>, shell: boolean) => ShellCommandError | undefined;
40
+ export declare const diagnosticsSkipReason: (error: unknown) => NonNullable<NotebookDiagnosticsResult["skipped"]>;
41
41
  export declare const sanitizeNotebookText: (document: NotebookVirtualDocument) => string;
42
42
  export declare const resolvePyrightCommand: (configured: string | undefined) => {
43
43
  readonly command: string;
44
44
  readonly shell: boolean;
45
45
  };
46
- /**
47
- * Cheap availability check used before asking permission or creating a temp
48
- * file. Absolute paths are checked without spawning; a bare command is probed
49
- * once per TTL. This avoids permission prompts when pyright is not installed.
50
- */
51
- export declare const isPyrightAvailable: (configured: string | undefined, timeoutMs?: number, signal?: AbortSignal) => Promise<boolean>;
46
+ export interface PyrightAvailabilityOptions {
47
+ readonly warningSink?: WarningSink | undefined;
48
+ }
49
+ export declare const isPyrightAvailable: (configured: string | undefined, timeoutMs?: number, signal?: AbortSignal, options?: PyrightAvailabilityOptions) => Promise<boolean>;
52
50
  export declare const diagnosticTempPath: (filePath: string) => string;
53
- /** Fallback used when the notebook directory is not writable. */
54
51
  export declare const diagnosticFallbackTempPath: (filePath: string) => string;
55
52
  export declare const diagnoseNotebook: (options: NotebookDiagnosticsOptions) => Promise<NotebookDiagnosticsResult>;
@@ -1,8 +1,3 @@
1
- /**
2
- * Pure helpers for the notebook `execute.after` hook. Keeping the tool-name
3
- * normalization and changed/no-op rules here makes the plugin entrypoint
4
- * mostly lifecycle wiring and gives the tests a small unit to target.
5
- */
6
1
  export declare const notebookMutatingTools: Set<string>;
7
2
  export declare const diagnosableTools: Set<string>;
8
3
  export declare function toolName(tool: string): string;
@@ -1,3 +1,4 @@
1
+ import { type WarningSink } from "./utils/warnings.js";
1
2
  import type { Plugin } from "@opencode/plugin";
2
3
  import type { AnyToolDefinition, ToolContext, ToolResult } from "./tool.js";
3
4
  type V2ToolEditor = Parameters<Plugin.Context["tool"]["transform"]>[0] extends (editor: infer Editor) => void ? Editor : never;
@@ -23,13 +24,8 @@ export interface V2ToolResult {
23
24
  readonly metadata?: Record<string, unknown>;
24
25
  }
25
26
  export declare const toV2Result: (result: ToolResult) => V2ToolResult;
26
- /**
27
- * V2 custom tools do not receive the V1 ToolContext shape. Adapt the V2 tool
28
- * execution context, and route ctx.ask through the V2 permission domain so
29
- * every write and execution still prompts (or is denied by explicit rules).
30
- */
31
- export declare const toToolContext: (pluginContext: Plugin.Context, context: V2ToolContext, pluginOptions: unknown) => ToolContext;
32
- export declare const toV2Tool: (pluginContext: Plugin.Context, registration: V2ToolRegistration, pluginOptions?: unknown) => V2ToolInfo;
27
+ export declare const toToolContext: (pluginContext: Plugin.Context, context: V2ToolContext, pluginOptions: unknown, warningSink?: WarningSink) => ToolContext;
28
+ export declare const toV2Tool: (pluginContext: Plugin.Context, registration: V2ToolRegistration, pluginOptions?: unknown, warningSink?: WarningSink) => V2ToolInfo;
33
29
  export declare const registerV2Tools: (context: Plugin.Context, registrations: ReadonlyArray<V2ToolRegistration>, pluginOptions?: unknown) => Promise<import("@opencode/plugin/promise/registration").Registration>;
34
30
  export type V2Registration = Awaited<ReturnType<typeof registerV2Tools>>;
35
31
  export {};
package/dist/rpc.d.ts CHANGED
@@ -1,10 +1,3 @@
1
- /**
2
- * Public RPC contract for notebook/LSP integration.
3
- *
4
- * Other plugins can import this contract from `opencode-ipynb/rpc`, call
5
- * `document` to get a provider-agnostic virtual document, and subscribe to
6
- * `changed` to refresh diagnostics after the plugin edits a notebook.
7
- */
8
1
  export declare const NotebookRpc: {
9
2
  readonly id: "opencode-ipynb";
10
3
  readonly methods: {
@@ -1,11 +1,16 @@
1
1
  import { Effect } from "effect";
2
2
  import { type NotebookError } from "../domain/errors.js";
3
3
  import { type RunRequest, type RunResponse } from "../domain/execution.js";
4
+ import { type Warning, type WarningSink } from "../utils/warnings.js";
4
5
  export interface KernelManagerOptions {
5
6
  readonly pythonPath: string;
6
7
  readonly helperPath: string;
7
8
  readonly workingDirectory: string | undefined;
8
9
  readonly defaultTimeoutMs: number;
10
+ readonly warningSink?: WarningSink;
11
+ readonly sinkTarget?: {
12
+ sink?: WarningSink | undefined;
13
+ };
9
14
  }
10
15
  export interface KernelRuntimeOptions {
11
16
  readonly pythonPath: string;
@@ -17,15 +22,18 @@ export interface KernelInfo {
17
22
  readonly lastUsedAt: number;
18
23
  readonly requestsHandled: number;
19
24
  readonly stderrTail: string;
25
+ readonly warnings?: ReadonlyArray<Warning>;
20
26
  }
21
27
  export interface KernelManagerStats {
22
28
  readonly liveKernels: number;
23
29
  readonly totalRequests: number;
24
30
  }
31
+ export declare const killPidTree: (pid: number | undefined, signal?: NodeJS.Signals, notify?: (error: unknown) => void) => void;
25
32
  export declare const makeKernelManager: (opts: KernelManagerOptions) => KernelManagerShape;
26
33
  export interface KernelManagerShape {
27
34
  readonly execute: (filePath: string, request: RunRequest, runtime?: KernelRuntimeOptions, options?: {
28
35
  readonly signal?: AbortSignal;
36
+ readonly warningSink?: WarningSink;
29
37
  }) => Effect.Effect<RunResponse, NotebookError>;
30
38
  readonly isRunning: (filePath: string) => boolean;
31
39
  readonly list: () => ReadonlyArray<KernelInfo>;
@@ -33,4 +41,5 @@ export interface KernelManagerShape {
33
41
  readonly shutdown: (filePath: string) => Effect.Effect<void, never>;
34
42
  readonly disposeAll: () => Effect.Effect<void, never>;
35
43
  readonly stats: () => KernelManagerStats;
44
+ readonly setWarningSink?: (sink: WarningSink | undefined) => void;
36
45
  }
@@ -4,6 +4,7 @@ import type { NotebookFileServiceShape } from "./NotebookFileService.js";
4
4
  import type { PathServiceShape } from "./PathService.js";
5
5
  import { type PermissionServiceShape } from "./PermissionService.js";
6
6
  import type { NotebookRaw } from "../domain/notebook.js";
7
+ import type { PatchFailureReason, WriteMode } from "../utils/json.js";
7
8
  export interface CleanOptions {
8
9
  readonly clearOutputs: boolean;
9
10
  readonly clearExecutionCount: boolean;
@@ -20,7 +21,10 @@ export interface CleanResult {
20
21
  readonly removedExecutionCounts: number;
21
22
  readonly removedWidgets: number;
22
23
  readonly removedImages: number;
24
+ readonly normalizedSources: number;
23
25
  readonly notebook: NotebookRaw;
26
+ readonly writeMode: WriteMode | undefined;
27
+ readonly writeModeReason?: PatchFailureReason | undefined;
24
28
  }
25
29
  export interface NotebookCleanServiceShape {
26
30
  readonly clean: (filePath: string, options?: Partial<CleanOptions>) => Effect.Effect<CleanResult, NotebookNotFoundError | NotebookParseError | NotebookValidationError | NotebookWriteError | PathOutsideWorktreeError | PermissionDeniedError>;
@@ -1,6 +1,7 @@
1
1
  import { Effect } from "effect";
2
2
  import { CellIndexOutOfBoundsError, NotebookNotFoundError, NotebookParseError, NotebookValidationError, NotebookWriteError, PathOutsideWorktreeError, PermissionDeniedError } from "../domain/errors.js";
3
- import type { NotebookFileServiceShape } from "./NotebookFileService.js";
3
+ import type { NotebookFileServiceShape, WriteMode } from "./NotebookFileService.js";
4
+ import type { PatchFailureReason } from "../utils/json.js";
4
5
  import type { PathServiceShape } from "./PathService.js";
5
6
  import { type PermissionServiceShape } from "./PermissionService.js";
6
7
  import { type NotebookRaw } from "../domain/notebook.js";
@@ -17,6 +18,8 @@ export interface EditResult {
17
18
  readonly clearedOutputs: boolean;
18
19
  readonly changed: boolean;
19
20
  readonly notebook: NotebookRaw;
21
+ readonly writeMode: WriteMode | undefined;
22
+ readonly writeModeReason?: PatchFailureReason | undefined;
20
23
  }
21
24
  export interface InsertResult {
22
25
  readonly displayPath: string;
@@ -25,6 +28,8 @@ export interface InsertResult {
25
28
  readonly cellType: "code" | "markdown" | "raw";
26
29
  readonly totalCells: number;
27
30
  readonly preview: string;
31
+ readonly writeMode: WriteMode;
32
+ readonly writeModeReason?: PatchFailureReason | undefined;
28
33
  }
29
34
  export interface DeleteResult {
30
35
  readonly displayPath: string;
@@ -33,6 +38,8 @@ export interface DeleteResult {
33
38
  readonly deletedType: "code" | "markdown" | "raw";
34
39
  readonly deletedPreview: string;
35
40
  readonly totalCells: number;
41
+ readonly writeMode: WriteMode;
42
+ readonly writeModeReason?: PatchFailureReason | undefined;
36
43
  }
37
44
  export interface MoveResult {
38
45
  readonly displayPath: string;
@@ -41,6 +48,8 @@ export interface MoveResult {
41
48
  readonly toIndex: number;
42
49
  readonly cellType: CellType;
43
50
  readonly totalCells: number;
51
+ readonly writeMode: WriteMode | undefined;
52
+ readonly writeModeReason?: PatchFailureReason | undefined;
44
53
  }
45
54
  export type CellType = "code" | "markdown" | "raw";
46
55
  export type EditCellError = NotebookNotFoundError | NotebookParseError | NotebookValidationError | CellIndexOutOfBoundsError | NotebookWriteError | PathOutsideWorktreeError | PermissionDeniedError;
@@ -1,12 +1,16 @@
1
1
  import { Effect } from "effect";
2
- import { type NotebookError } from "../domain/errors.js";
2
+ import { CellIndexOutOfBoundsError, type NotebookError } from "../domain/errors.js";
3
3
  import type { NotebookFileServiceShape } from "./NotebookFileService.js";
4
4
  import type { PathServiceShape } from "./PathService.js";
5
+ import type { PatchFailureReason, WriteMode } from "../utils/json.js";
5
6
  import { type PermissionServiceShape } from "./PermissionService.js";
6
7
  import { type PythonServiceShape } from "./PythonService.js";
7
8
  import type { KernelManagerShape } from "./KernelManager.js";
9
+ import type { CellRaw, CodeCellRaw } from "../domain/cell.js";
8
10
  import type { RunResponse, CellExecutionSummary, EnvReport } from "../domain/execution.js";
9
11
  import { type TruncationHintKey } from "../utils/i18n.js";
12
+ import { type NotebookRaw } from "../domain/notebook.js";
13
+ import { type Warning, type WarningSink } from "../utils/warnings.js";
10
14
  export type ExecutionMode = "cell" | "range" | "all" | "from";
11
15
  export interface ExecutionRequest {
12
16
  readonly mode: ExecutionMode;
@@ -27,32 +31,53 @@ export interface ExecutionResult {
27
31
  readonly durationMs: number;
28
32
  readonly saved: boolean;
29
33
  readonly response: RunResponse;
34
+ readonly warnings?: ReadonlyArray<Warning>;
35
+ readonly writeMode?: WriteMode | undefined;
36
+ readonly writeModeReason?: PatchFailureReason | undefined;
30
37
  }
31
38
  export interface NotebookExecutionServiceShape {
32
39
  readonly execute: (filePath: string, request: ExecutionRequest, options?: {
33
40
  readonly signal?: AbortSignal;
41
+ readonly warningSink?: WarningSink;
34
42
  }) => Effect.Effect<ExecutionResult, NotebookError>;
35
43
  readonly reportEnv: (filePath: string, options?: ReportEnvOptions) => Effect.Effect<EnvReport, NotebookError>;
36
44
  }
37
45
  export interface ReportEnvOptions {
38
46
  readonly timeoutMs?: number | undefined;
39
47
  readonly signal?: AbortSignal | undefined;
40
- /** The caller already asserted shell for the probe and helper. */
41
48
  readonly skipShellPermission?: boolean | undefined;
49
+ readonly warningSink?: WarningSink | undefined;
42
50
  }
43
51
  export interface ExecutionOptions {
44
52
  readonly kernelManager?: KernelManagerShape | undefined;
45
53
  readonly warmKernel: boolean;
46
54
  readonly defaultTimeoutMs: number;
47
- /** Configured interpreter, used for the pre-probe shell permission. */
48
55
  readonly pythonPath?: string | undefined;
56
+ readonly warningSink?: WarningSink | undefined;
49
57
  }
50
58
  declare const truncateText: (text: string | undefined, maxChars: number, locale?: string, hintKey?: TruncationHintKey) => string | undefined;
51
59
  declare const truncateTraceback: (tb: ReadonlyArray<string>, maxChars: number) => ReadonlyArray<string>;
52
60
  export declare const cellSummaryChars: (summary: CellExecutionSummary) => number;
53
61
  declare const truncateCellSummary: (summary: CellExecutionSummary, maxOutputChars: number) => CellExecutionSummary;
54
62
  declare const truncateRunResponse: (response: RunResponse, maxOutputChars: number) => RunResponse;
63
+ export type TextShape = "arrays" | "strings";
64
+ export declare const textShapeOfCell: (cell: CellRaw, fallback: TextShape) => TextShape;
65
+ export interface OutputTextShapes {
66
+ readonly text: TextShape | undefined;
67
+ readonly data: ReadonlyMap<string, TextShape>;
68
+ }
69
+ export type CellValueShapes = ReadonlyArray<OutputTextShapes>;
70
+ export declare const captureValueShapes: (cell: CellRaw) => CellValueShapes;
71
+ export declare const restoreValueShapes: (outputs: ReadonlyArray<Record<string, unknown>>, previous: CellValueShapes | undefined, cellShape: TextShape) => Array<Record<string, unknown>>;
72
+ export declare const notebookTextShape: (notebook: NotebookRaw) => TextShape;
73
+ export declare const notebookUsesLineArrays: (notebook: NotebookRaw) => boolean;
55
74
  export declare const buildPersistedOutputs: (summary: CellExecutionSummary) => Array<Record<string, unknown>>;
75
+ export interface MergeShapeInputs {
76
+ readonly fallback: TextShape;
77
+ readonly beforeShapes: ReadonlyMap<number, TextShape> | undefined;
78
+ readonly beforeValueShapes: ReadonlyMap<number, CellValueShapes> | undefined;
79
+ }
80
+ export declare const mergeExecutedOutputs: (filePath: string, cells: ReadonlyArray<CellRaw>, executedCells: ReadonlyArray<number>, summaries: ReadonlyArray<CellExecutionSummary>, shapes: MergeShapeInputs) => Effect.Effect<Map<number, CodeCellRaw>, CellIndexOutOfBoundsError>;
56
81
  declare const makeExecutionImpl: (pathSvc: PathServiceShape, fileSvc: NotebookFileServiceShape, permSvc: PermissionServiceShape, pythonSvc: PythonServiceShape, execOpts?: ExecutionOptions) => NotebookExecutionServiceShape;
57
82
  export { makeExecutionImpl };
58
83
  export { truncateText, truncateTraceback, truncateCellSummary, truncateRunResponse };
@@ -1,24 +1,33 @@
1
1
  import { Effect } from "effect";
2
2
  import { NotebookNotFoundError, NotebookParseError, NotebookValidationError, NotebookWriteError, PathOutsideWorktreeError } from "../domain/errors.js";
3
- import { NotebookSchema, type NotebookRaw } from "../domain/notebook.js";
4
- interface NotebookFileServiceOptions {
5
- /** When set, real paths are pinned and checked against this worktree. */
3
+ import { type NotebookRaw } from "../domain/notebook.js";
4
+ import { type PatchFailureReason, type WriteMode } from "../utils/json.js";
5
+ import { type WarningSink } from "../utils/warnings.js";
6
+ export type { WriteMode };
7
+ export interface WriteOutcome {
8
+ readonly mode: WriteMode;
9
+ readonly reason?: PatchFailureReason | undefined;
10
+ }
11
+ import { type NotebookFormat } from "../utils/json.js";
12
+ export interface NotebookFileServiceOptions {
6
13
  readonly worktree?: string;
14
+ readonly warningSink?: WarningSink | undefined;
15
+ readonly signal?: AbortSignal | undefined;
7
16
  }
8
17
  export interface NotebookFileServiceShape {
9
18
  readonly read: (filePath: string) => Effect.Effect<NotebookRaw, NotebookNotFoundError | NotebookParseError | NotebookValidationError | PathOutsideWorktreeError>;
10
- readonly readText: (filePath: string) => Effect.Effect<string, NotebookNotFoundError | NotebookValidationError | PathOutsideWorktreeError>;
19
+ readonly readText: (filePath: string) => Effect.Effect<string, NotebookNotFoundError | NotebookParseError | NotebookValidationError | PathOutsideWorktreeError>;
11
20
  readonly readWithText: (filePath: string) => Effect.Effect<{
12
21
  readonly notebook: NotebookRaw;
13
22
  readonly text: string;
23
+ readonly format: NotebookFormat;
14
24
  }, NotebookNotFoundError | NotebookParseError | NotebookValidationError | PathOutsideWorktreeError>;
15
25
  readonly writeAtomic: (filePath: string, notebook: NotebookRaw, options?: {
16
26
  readonly noFollowFinal?: boolean;
17
- }) => Effect.Effect<void, NotebookParseError | NotebookValidationError | NotebookWriteError | PathOutsideWorktreeError>;
27
+ readonly format?: NotebookFormat;
28
+ readonly previousText?: string;
29
+ readonly trusted?: boolean;
30
+ }) => Effect.Effect<WriteOutcome, NotebookParseError | NotebookValidationError | NotebookWriteError | PathOutsideWorktreeError>;
18
31
  readonly withFileLock: <A, E, R>(filePath: string, program: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
19
32
  }
20
33
  export declare const makeNotebookFileService: (options?: NotebookFileServiceOptions) => NotebookFileServiceShape;
21
- export declare const _schemas: {
22
- readonly NotebookSchema: typeof NotebookSchema;
23
- };
24
- export {};
@@ -44,11 +44,6 @@ export declare const analyzeMissingPackages: (notebook: NotebookRaw, options: An
44
44
  export declare const analyzeReproducibility: (notebook: NotebookRaw) => ReadonlyArray<string>;
45
45
  export declare const analyzeExecutionOrderWarnings: (notebook: NotebookRaw) => ReadonlyArray<string>;
46
46
  declare const build: (pathSvc: PathServiceShape, fileSvc: NotebookFileServiceShape) => NotebookInspectServiceShape;
47
- /**
48
- * Standalone Effect: detect imports that the user's Python cannot resolve.
49
- * Pass the result of `pythonSvc.probe()` for `pythonPath`; the analyzer skips
50
- * itself when the probe says "none" (no Python on PATH).
51
- */
52
47
  export declare const analyzeMissingPackagesForPython: (notebook: NotebookRaw, pythonPath: string, checkImport: (pythonPath: string, module: string) => Effect.Effect<{
53
48
  name: string;
54
49
  available: boolean;
@@ -3,6 +3,7 @@ import { CellIndexOutOfBoundsError, NotebookNotFoundError, NotebookParseError, N
3
3
  import type { NotebookFileServiceShape } from "./NotebookFileService.js";
4
4
  import type { PathServiceShape } from "./PathService.js";
5
5
  import { type PermissionServiceShape } from "./PermissionService.js";
6
+ import type { PatchFailureReason, WriteMode } from "../utils/json.js";
6
7
  export type OutputOperation = "list" | "read" | "read_error" | "clear_cell" | "clear_all";
7
8
  export interface OutputListEntry {
8
9
  readonly cellIndex: number;
@@ -42,6 +43,8 @@ export interface ClearOutputsResult {
42
43
  readonly clearedCells: number;
43
44
  readonly removedOutputs: number;
44
45
  readonly removedExecutionCounts: number;
46
+ readonly writeMode: WriteMode | undefined;
47
+ readonly writeModeReason?: PatchFailureReason | undefined;
45
48
  }
46
49
  export interface NotebookOutputServiceShape {
47
50
  readonly listOutputs: (filePath: string, offset?: number | undefined, limit?: number | undefined) => Effect.Effect<ListOutputsResult, NotebookNotFoundError | NotebookParseError | NotebookValidationError | PathOutsideWorktreeError>;
@@ -1,4 +1,5 @@
1
1
  import { Effect } from "effect";
2
+ import { type WarningSink } from "../utils/warnings.js";
2
3
  import { NotebookNotFoundError, NotebookWriteError, PathOutsideWorktreeError } from "../domain/errors.js";
3
4
  export interface PathEnv {
4
5
  readonly directory: string;
@@ -6,6 +7,9 @@ export interface PathEnv {
6
7
  readonly platform: NodeJS.Platform;
7
8
  readonly allowOutsideWorktree?: boolean | undefined;
8
9
  }
10
+ export interface PathServiceOptions extends PathEnv {
11
+ readonly warningSink?: WarningSink | undefined;
12
+ }
9
13
  export interface PathServiceShape {
10
14
  readonly env: PathEnv;
11
15
  readonly resolve: (inputPath: string) => Effect.Effect<string, never>;
@@ -21,4 +25,4 @@ export interface PathServiceShape {
21
25
  }, never>;
22
26
  readonly toDisplay: (absPath: string) => string;
23
27
  }
24
- export declare const makePathService: (env: PathEnv) => PathServiceShape;
28
+ export declare const makePathService: (options: PathServiceOptions) => PathServiceShape;
@@ -1,8 +1,12 @@
1
1
  import { Effect } from "effect";
2
2
  import type { ToolContext } from "../tool.js";
3
3
  import { PermissionDeniedError } from "../domain/errors.js";
4
- export declare const resolveDeepReal: (target: string) => Promise<string>;
5
- export declare const permissionAliases: (filePath: string, bases?: ReadonlyArray<string>) => Promise<ReadonlyArray<string>>;
4
+ import { type WarningSink } from "../utils/warnings.js";
5
+ export interface AliasResolutionOptions {
6
+ readonly warningSink?: WarningSink | undefined;
7
+ }
8
+ export declare const resolveDeepReal: (target: string, options?: AliasResolutionOptions) => Promise<string>;
9
+ export declare const permissionAliases: (filePath: string, bases?: ReadonlyArray<string>, options?: AliasResolutionOptions) => Promise<ReadonlyArray<string>>;
6
10
  export type PermissionKind = "edit" | "shell" | "read";
7
11
  export interface PermissionRequest {
8
12
  readonly kind: PermissionKind;
@@ -15,4 +19,7 @@ export interface PermissionServiceShape {
15
19
  readonly ask: (req: PermissionRequest) => Effect.Effect<void, PermissionDeniedError>;
16
20
  readonly aliases: (filePath: string) => Effect.Effect<ReadonlyArray<string>, never>;
17
21
  }
18
- export declare const makePermissionService: (ctx: ToolContext) => PermissionServiceShape;
22
+ export interface PermissionServiceOptions {
23
+ readonly warningSink?: WarningSink | undefined;
24
+ }
25
+ export declare const makePermissionService: (ctx: ToolContext, options?: PermissionServiceOptions) => PermissionServiceShape;
@@ -1,13 +1,7 @@
1
1
  import { Effect } from "effect";
2
2
  import { PermissionDeniedError } from "../domain/errors.js";
3
- /**
4
- * Environment for the Python helper process. The helper runs first-party
5
- * code and imports stdlib/nbclient modules before it can trust the request,
6
- * so project-controlled PYTHONPATH/PYTHONHOME values must not reach it.
7
- * Notebook kernels get the original values back through `kernelEnv`.
8
- */
3
+ import { type WarningSink } from "../utils/warnings.js";
9
4
  export declare const helperSpawnEnv: () => NodeJS.ProcessEnv;
10
- /** Original Python env values to restore only inside the notebook kernel. */
11
5
  export declare const kernelEnvOverrides: () => Record<string, string> | undefined;
12
6
  export interface PythonProbeResult {
13
7
  readonly pythonPath: string;
@@ -34,12 +28,14 @@ export interface PythonServiceOptions {
34
28
  readonly helperRelativePath: string;
35
29
  readonly pythonSource?: "options" | "env" | undefined;
36
30
  }
31
+ export interface ProbeOptions {
32
+ readonly warningSink?: WarningSink | undefined;
33
+ }
37
34
  export interface PythonServiceShape {
38
- readonly probe: () => Effect.Effect<PythonProbeResult, never>;
35
+ readonly probe: (options?: ProbeOptions) => Effect.Effect<PythonProbeResult, never>;
39
36
  readonly candidates: () => Effect.Effect<ReadonlyArray<PythonProbeResult>, never>;
40
37
  readonly checkDependencies: (pythonPath: string) => Effect.Effect<ReadonlyArray<DependencyCheck>, never>;
41
38
  readonly checkImport: (pythonPath: string, module: string) => Effect.Effect<DependencyCheck, never>;
42
- /** Batch variant: one Python process for many imports. */
43
39
  readonly checkImports?: (pythonPath: string, modules: ReadonlyArray<string>, signal?: AbortSignal) => Effect.Effect<ReadonlyArray<DependencyCheck>, never>;
44
40
  readonly findHelper: () => Effect.Effect<string | undefined, never>;
45
41
  readonly doctor: (beforeDependencies?: (selected: PythonProbeResult) => Effect.Effect<void, PermissionDeniedError>) => Effect.Effect<PythonDoctor, PermissionDeniedError>;
@@ -48,13 +44,7 @@ export interface _PythonServiceForTest {
48
44
  readonly _invalidateDepsCache: (pythonPath?: string) => void;
49
45
  }
50
46
  declare const REQUIRED_DEPS: readonly ["nbformat", "nbclient", "jupyter_client", "ipykernel"];
51
- /**
52
- * Absolute PATH candidates for the Python names the plugin probes. Resolving
53
- * them without executing lets the first shell assert cover the interpreter a
54
- * PATH lookup will actually spawn.
55
- */
56
47
  export declare const pythonInterpreterResources: (configured?: string) => ReadonlyArray<string>;
57
- /** Back-compat: realpath-resolved PATH candidates only. */
58
48
  export declare const pathPythonCandidates: () => ReadonlyArray<string>;
59
49
  declare const findHelper: (rel: string) => string | undefined;
60
50
  export declare const makePythonService: (opts: PythonServiceOptions) => PythonServiceShape;