opencode-ipynb 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-ipynb contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+# opencode-ipynb
+
+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.
+
+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.
+
+> Repository: https://github.com/Restodecoca/opencode-ipynb
+> Issues: https://github.com/Restodecoca/opencode-ipynb/issues
+
+## Why a plugin and not core
+
+- Notebooks are large, binary-like artifacts. Dumping them into the agent context burns tokens.
+- Reading outputs and editing cells are high-trust actions that must ask permission every time.
+- The execution flow needs a Python runtime, which is not something every OpenCode user wants installed.
+- A plugin lets the community iterate on these workflows without forcing changes on the OpenCode core.
+
+## Installation
+
+After the package is published on npm, add it to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-ipynb"]
+}
+```
+
+For local development, point OpenCode at a checkout or built tarball:
+
+```json
+{
+  "plugin": ["file:./opencode-ipynb"]
+}
+```
+
+Or run directly from this repo:
+
+```bash
+git clone https://github.com/Restodecoca/opencode-ipynb
+cd opencode-ipynb
+bun install
+bun run build
+```
+
+Then add `"opencode-ipynb"` (or the local path) to your `opencode.json`.
+
+## Tools
+
+| Tool                 | Purpose |
+| -------------------- | ------- |
+| `ipynb_inspect`      | Compact summary: kernel/language metadata, cell table, output stats, execution-order warnings, optional missing-package checks. |
+| `ipynb_read`         | Granular read of one cell or a range, with optional outputs/errors/metadata/images and truncation limits. |
+| `ipynb_edit`         | Safe per-cell source edit with textual diff, output clearing policy, permission gate, and per-file lock. |
+| `ipynb_cell_insert`  | Insert a code/markdown/raw cell before or after a target index. |
+| `ipynb_cell_delete`  | Delete one cell by index and return a preview of the deleted source. |
+| `ipynb_cell_move`    | Move one cell to a new index. |
+| `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. |
+| `ipynb_outputs`      | List / read / read_error / clear_cell / clear_all outputs with pagination and permission gates for writes. |
+| `ipynb_clean`        | Strip outputs, execution counts, widget state, large images, and normalize `source` arrays for Git-friendly diffs. |
+| `ipynb_export`       | Export to Markdown, Python, or summary; optionally write to disk after permission. |
+| `ipynb_doctor`       | Diagnose Python, helper discovery, and required Jupyter dependencies. |
+| `ipynb_repro`        | Reproducibility report: kernel/env info, `pip freeze`, filesystem reads, random seeds, non-determinism, missing packages. |
+| `ipynb_kernel`       | Inspect/restart/shutdown warm kernels when `ipynb.warmKernel: true` is enabled. |
+
+### Examples
+
+Inspect a notebook before doing anything else:
+
+```text
+ipynb_inspect({ filePath: "notebooks/eda.ipynb" })
+```
+
+Read a single cell:
+
+```text
+ipynb_read({ filePath: "notebooks/eda.ipynb", cellIndex: 7 })
+```
+
+Read a range including outputs:
+
+```text
+ipynb_read({
+  filePath: "notebooks/eda.ipynb",
+  start: 0,
+  end: 5,
+  includeOutputs: true,
+  maxOutputChars: 4000
+})
+```
+
+Edit one cell, clear outputs automatically:
+
+```text
+ipynb_edit({
+  filePath: "notebooks/eda.ipynb",
+  cellIndex: 7,
+  source: "import pandas as pd\ndf = pd.read_csv('data.csv')\ndf.head()"
+})
+```
+
+Clean for a clean diff before commit:
+
+```text
+ipynb_clean({ filePath: "notebooks/eda.ipynb" })
+```
+
+Export to a Python script next to the notebook:
+
+```text
+ipynb_export({
+  filePath: "notebooks/eda.ipynb",
+  format: "python",
+  outputPath: "notebooks/eda.py"
+})
+```
+
+## Safety and permissions
+
+- Every write (`ipynb_edit`, `ipynb_clean`, `ipynb_outputs clear_*`, `ipynb_export --outputPath`) calls `context.ask` before touching the disk.
+- Every execution (`ipynb_run`) calls `context.ask` with rich metadata: file path, mode (`cell` / `range` / `all` / `from`), cell range, save flag, working directory, timeout.
+- `PathService` rejects paths that resolve outside of the OpenCode worktree. The lock manager serializes per-file writes to prevent accidental corruption.
+- 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.
+
+## Context control
+
+Notebooks can be enormous. By default the plugin never dumps a full notebook into context:
+
+- `ipynb_inspect` returns a table with the first line of every cell, plus aggregate counts. It never includes the full source.
+- `ipynb_read` defaults to **not** including outputs. Set `includeOutputs: true` to opt in. Images / base64 are always omitted (you only get a size notice).
+- `maxSourceChars` (default 12 000) and `maxOutputChars` (default 6 000) cap the size of any single response.
+- `maxTracebackChars` (default 8 000) caps error tracebacks.
+- Every truncation appends `... (truncated, use maxXxx to increase)`.
+
+The relevant constants live in `src/utils/limits.ts`.
+
+## Python execution
+
+The plugin **never installs Python dependencies automatically**. Running `ipynb_run` is opt-in and requires a Python environment with `nbformat`, `nbclient`, `jupyter_client`, and `ipykernel`. The plugin only detects what is available and tells you how to fix what is missing.
+
+### Preferred: `uv`
+
+```bash
+uv pip install nbformat nbclient jupyter_client ipykernel
+python -m ipykernel install --user
+```
+
+### Alternative: pip in a venv
+
+```bash
+python -m venv .venv
+source .venv/bin/activate            # Windows: .venv\Scripts\activate
+pip install nbformat nbclient jupyter_client ipykernel
+python -m ipykernel install --user
+```
+
+### Alternative: conda
+
+```bash
+conda install -c conda-forge nbformat nbclient jupyter_client ipykernel
+```
+
+### Pointing the plugin at a specific Python
+
+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:
+
+1. Plugin options (in `opencode.json`):
+
+   ```json
+   {
+     "plugin": ["opencode-ipynb"],
+     "ipynb": {
+       "pythonPath": "C:/Users/Gabriel/miniconda3/envs/data/python.exe",
+        "preferUv": true,
+        "defaultTimeoutMs": 120000,
+        "defaultMaxOutputChars": 6000,
+        "warmKernel": false,
+        "allowOutsideWorktree": false
+      }
+   }
+   ```
+
+   - `pythonPath` (string): absolute path to a Python interpreter.
+   - `preferUv` (boolean, default `true`): the doctor and the Python service prefer `uv pip install` over `pip install` in their suggestions.
+   - `defaultTimeoutMs` (number, default `120000`): timeout in milliseconds for `ipynb_run`.
+   - `defaultMaxOutputChars` (number, default `6000`): fallback for `ipynb_read` and `ipynb_outputs read` when the user does not pass `maxOutputChars`.
+   - `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`.
+   - `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.
+
+2. Environment variables (the shell wins over plugin options):
+
+   ```bash
+   OPENCODE_IPYNB_PYTHON=C:/Users/Gabriel/miniconda3/envs/data/python.exe opencode
+   OPENCODE_IPYNB_OPTIONS='{"pythonPath":"/usr/bin/python3","defaultMaxOutputChars":4000}' opencode
+   ```
+
+   `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.
+
+3. PATH fallback: the plugin tries `python`, then `python3`.
+
+### Diagnose first
+
+If anything goes wrong, run:
+
+```text
+ipynb_doctor
+```
+
+It reports the selected interpreter, every Jupyter dependency (`[ok]` / `[missing]`), where the helper script was found, and a copy-pasteable install command. It never installs anything.
+
+## Known limitations
+
+- Python execution depends on the user's local Python/Jupyter environment. The plugin diagnoses missing packages but never installs them.
+- Warm kernels are intentionally limited to `ipynb_run mode=all` and `mode=cell`; `range`, `from`, and `env` use one-shot helper processes.
+- 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.
+- `allowOutsideWorktree` is a power-user escape hatch. Keep it disabled unless you explicitly need cross-worktree notebook access.
+
+## Examples
+
+Three small, runnable notebooks live under `test/integration/` and double
+as both documentation and a smoke test for the plugin's read / run /
+export loop:
+
+- [`test/integration/classification/`](./test/integration/classification/) — `LogisticRegression` on `sklearn.datasets.load_iris` (7 cells, no CSV needed).
+- [`test/integration/timeseries/`](./test/integration/timeseries/) — `numpy` moving average over a noisy sine wave (5 cells, stdlib-friendly).
+- [`test/integration/scraping/`](./test/integration/scraping/) — `urllib.request` + `html.parser` fetch of `https://example.com/` (4 cells, stdlib only, graceful `try/except` on network failure).
+
+Each one ships with `outputs: []` and a matching `README.md` that lists
+the exact `ipynb_inspect` / `ipynb_read` / `ipynb_run` calls plus the
+expected output.
+
+## Release
+
+The published npm tarball contains only the runtime: `dist/`, `python/ipynb_runner.py`, `python/requirements.txt`, `README.md`, and `LICENSE`. Internal developer docs (`AGENTS.md`, `TODO.md`, the helper's dev scripts, the `.github/` workflows) are excluded from the npm package via `.npmignore`, and `AGENTS.md` / `TODO.md` are also gitignored so they are not versioned in this repository. Contributors track their work through GitHub Issues and Discussions.
+
+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:
+
+```bash
+git tag v0.1.0 && git push --tags
+```
+
+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`).
+
+Before publishing, run a local package check:
+
+```bash
+bun run typecheck
+bun test
+bun run build
+npm pack --dry-run
+```
+
+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.
+
+## Effect LSP setup (for development)
+
+This project uses the [Effect Language Service](https://effect.website/docs/getting-started/devtools/) to surface Effect-specific diagnostics at build time and in the editor.
+
+The `tsconfig.json` already includes the plugin:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [{ "name": "@effect/language-service" }]
+  }
+}
+```
+
+### Build-time diagnostics (optional, opt-in)
+
+`effect-language-service patch` modifies the local `node_modules/typescript` so that `tsc --noEmit` reports Effect-specific diagnostics. This is **opt-in** because it mutates your local install.
+
+```bash
+bun run prepare:effect-lsp     # alias for: effect-language-service patch
+bun run typecheck              # now also catches "Effect must be yielded" and similar
+```
+
+The project does NOT add this as a `prepare` script. Patch only when you want it.
+
+### Editor integration
+
+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**.
+
+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:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": {
+    "typescript": {
+      "extensions": [".ts", ".tsx", ".mts", ".cts"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run build
+```
+
+Layout:
+
+```
+src/
+  index.ts                # re-exports the plugin
+  plugin.ts               # Plugin object, registers all 13 tools
+  domain/                 # zod schemas + types for cells, outputs, execution
+  services/               # Effect-style services (Path, Permission, File, ...)
+  format/                 # markdown / output / diagnostic / export formatters
+  tools/                  # one file per tool, thin wrapper over services
+  utils/                  # limits, paths, mime, truncate, json helpers
+python/
+  ipynb_runner.py         # JSON-stdin/stdout runner using nbformat + nbclient
+  requirements.txt
+test/
+  fixtures/               # simple, outputs, error, images
+  unit/                   # bun:test suites
+```
+
+## Roadmap
+
+See `TODO.md` for the full plan and review-fix history (v0.1 → v1.5). Highlights:
+
+- v0.2: polished `ipynb_outputs` UI, full `ipynb_export` polish.
+- v0.3: real `nbclient`-based execution, save outputs, timeout, traceback capture.
+- v0.4: image attachments, reproducibility reports.
+- v1.0: kernel lifecycle management, cross-platform tests, npm publish.
+- v1.1–v1.5: security, Effect, path, packaging, rich-output, and cleanup review fixes.
+
+## License
+
+MIT. See `LICENSE`.

package/dist/domain/cell.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export declare const SourceSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+export type Source = z.infer<typeof SourceSchema>;
+export declare const CellMetadataSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type CellMetadata = z.infer<typeof CellMetadataSchema>;
+export declare const CodeCellSchema: z.ZodObject<{
+    cell_type: z.ZodLiteral<"code">;
+    id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    execution_count: z.ZodUnion<readonly [z.ZodNullable<z.ZodNumber>, z.ZodNull]>;
+    source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    outputs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$loose>;
+export type CodeCellRaw = z.infer<typeof CodeCellSchema>;
+export declare const MarkdownCellSchema: z.ZodObject<{
+    cell_type: z.ZodLiteral<"markdown">;
+    id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    attachments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type MarkdownCellRaw = z.infer<typeof MarkdownCellSchema>;
+export declare const RawCellSchema: z.ZodObject<{
+    cell_type: z.ZodLiteral<"raw">;
+    id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$loose>;
+export type RawCellRaw = z.infer<typeof RawCellSchema>;
+export declare const CellSchema: z.ZodUnion<readonly [z.ZodObject<{
+    cell_type: z.ZodLiteral<"code">;
+    id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    execution_count: z.ZodUnion<readonly [z.ZodNullable<z.ZodNumber>, z.ZodNull]>;
+    source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    outputs: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$loose>, z.ZodObject<{
+    cell_type: z.ZodLiteral<"markdown">;
+    id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    attachments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>, z.ZodObject<{
+    cell_type: z.ZodLiteral<"raw">;
+    id: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    source: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$loose>]>;
+export type CellRaw = z.infer<typeof CellSchema>;
+//# sourceMappingURL=cell.d.ts.map

package/dist/domain/cell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell.d.ts","sourceRoot":"","sources":["../../src/domain/cell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,YAAY,6DAA6C,CAAA;AACtE,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAEjD,eAAO,MAAM,kBAAkB,wCAAoC,CAAA;AACnE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAE7D,eAAO,MAAM,cAAc;;;;;;;iBASX,CAAA;AAChB,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAExD,eAAO,MAAM,kBAAkB;;;;;;iBAQf,CAAA;AAChB,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEhE,eAAO,MAAM,aAAa;;;;;iBAOV,CAAA;AAChB,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEtD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;mBAA+D,CAAA;AACtF,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA"}

package/dist/domain/errors.d.ts

@@ -0,0 +1,119 @@
+import { Effect } from "effect";
+export type NotebookErrorKind = "NotebookNotFound" | "NotebookParse" | "NotebookValidation" | "CellIndexOutOfBounds" | "NotebookWrite" | "NotebookExecution" | "PythonRunner" | "PermissionDenied" | "OutputTooLarge" | "PathOutsideWorktree" | "NotebookNotImplemented" | "NotebookAttachment" | "LockError";
+declare const NotebookNotFoundError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotebookNotFound";
+} & Readonly<A>;
+export declare class NotebookNotFoundError extends NotebookNotFoundError_base<{
+    readonly message: string;
+    readonly filePath: string;
+}> {
+}
+declare const NotebookParseError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotebookParse";
+} & Readonly<A>;
+export declare class NotebookParseError extends NotebookParseError_base<{
+    readonly message: string;
+    readonly filePath: string;
+}> {
+}
+declare const NotebookValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotebookValidation";
+} & Readonly<A>;
+export declare class NotebookValidationError extends NotebookValidationError_base<{
+    readonly message: string;
+    readonly filePath: string;
+    readonly issues: ReadonlyArray<string>;
+}> {
+}
+declare const CellIndexOutOfBoundsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CellIndexOutOfBounds";
+} & Readonly<A>;
+export declare class CellIndexOutOfBoundsError extends CellIndexOutOfBoundsError_base<{
+    readonly message: string;
+    readonly filePath: string;
+    readonly cellIndex: number;
+    readonly total: number;
+}> {
+}
+declare const NotebookWriteError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotebookWrite";
+} & Readonly<A>;
+export declare class NotebookWriteError extends NotebookWriteError_base<{
+    readonly message: string;
+    readonly filePath: string;
+}> {
+}
+declare const NotebookExecutionError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotebookExecution";
+} & Readonly<A>;
+export declare class NotebookExecutionError extends NotebookExecutionError_base<{
+    readonly message: string;
+    readonly filePath: string;
+    readonly cellIndex: number;
+}> {
+}
+declare const PythonRunnerError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PythonRunner";
+} & Readonly<A>;
+export declare class PythonRunnerError extends PythonRunnerError_base<{
+    readonly message: string;
+    readonly detail: string;
+}> {
+}
+declare const PermissionDeniedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PermissionDenied";
+} & Readonly<A>;
+export declare class PermissionDeniedError extends PermissionDeniedError_base<{
+    readonly message: string;
+    readonly action: string;
+}> {
+}
+declare const OutputTooLargeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "OutputTooLarge";
+} & Readonly<A>;
+export declare class OutputTooLargeError extends OutputTooLargeError_base<{
+    readonly message: string;
+    readonly cellIndex: number;
+    readonly bytes: number;
+}> {
+}
+declare const PathOutsideWorktreeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PathOutsideWorktree";
+} & Readonly<A>;
+export declare class PathOutsideWorktreeError extends PathOutsideWorktreeError_base<{
+    readonly message: string;
+    readonly filePath: string;
+    readonly worktree: string;
+}> {
+}
+declare const NotebookNotImplementedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotebookNotImplemented";
+} & Readonly<A>;
+export declare class NotebookNotImplementedError extends NotebookNotImplementedError_base<{
+    readonly message: string;
+    readonly feature: string;
+}> {
+}
+declare const NotebookAttachmentError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NotebookAttachment";
+} & Readonly<A>;
+export declare class NotebookAttachmentError extends NotebookAttachmentError_base<{
+    readonly message: string;
+    readonly mime: string;
+}> {
+}
+declare const LockError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LockError";
+} & Readonly<A>;
+export declare class LockError extends LockError_base<{
+    readonly message: string;
+    readonly filePath: string;
+    readonly cause: string;
+}> {
+}
+export type NotebookError = NotebookNotFoundError | NotebookParseError | NotebookValidationError | CellIndexOutOfBoundsError | NotebookWriteError | NotebookExecutionError | PythonRunnerError | PermissionDeniedError | OutputTooLargeError | PathOutsideWorktreeError | NotebookNotImplementedError | NotebookAttachmentError | LockError;
+export declare const isNotebookError: (u: unknown) => u is NotebookError;
+export declare const errorToMessage: (e: unknown) => string;
+export declare const failWith: <E extends NotebookError>(e: E) => Effect.Effect<never, E, never>;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/domain/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/domain/errors.ts"],"names":[],"mappings":"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"}

package/dist/domain/execution.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+export declare const EnvReportSchema: z.ZodObject<{
+    kernelDisplayName: z.ZodNullable<z.ZodString>;
+    kernelName: z.ZodNullable<z.ZodString>;
+    language: z.ZodNullable<z.ZodString>;
+    pythonVersion: z.ZodString;
+    pythonExecutable: z.ZodString;
+    platform: z.ZodString;
+    pipFreeze: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type EnvReport = z.infer<typeof EnvReportSchema>;
+export declare const RunRequestSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    mode: z.ZodUnion<readonly [z.ZodLiteral<"cell">, z.ZodLiteral<"range">, z.ZodLiteral<"all">, z.ZodLiteral<"from">, z.ZodLiteral<"env">]>;
+    cellIndex: z.ZodOptional<z.ZodNumber>;
+    start: z.ZodOptional<z.ZodNumber>;
+    end: z.ZodOptional<z.ZodNumber>;
+    kernel: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    save: z.ZodOptional<z.ZodBoolean>;
+    workingDirectory: z.ZodOptional<z.ZodString>;
+    maxOutputChars: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type RunRequest = z.infer<typeof RunRequestSchema>;
+export declare const CellExecutionSummarySchema: z.ZodObject<{
+    cellIndex: z.ZodNumber;
+    status: z.ZodUnion<readonly [z.ZodLiteral<"ok">, z.ZodLiteral<"error">, z.ZodLiteral<"timeout">, z.ZodLiteral<"skipped">]>;
+    executionCount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    stdout: z.ZodOptional<z.ZodString>;
+    stderr: z.ZodOptional<z.ZodString>;
+    resultPreview: z.ZodOptional<z.ZodString>;
+    displayData: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mime: z.ZodString;
+        sizeBytes: z.ZodNumber;
+    }, z.core.$strip>>>;
+    rawOutputs: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ename: z.ZodString;
+        evalue: z.ZodString;
+        traceback: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CellExecutionSummary = z.infer<typeof CellExecutionSummarySchema>;
+export declare const RunResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    executedCells: z.ZodArray<z.ZodNumber>;
+    durationMs: z.ZodNumber;
+    saved: z.ZodOptional<z.ZodBoolean>;
+    outputs: z.ZodArray<z.ZodObject<{
+        cellIndex: z.ZodNumber;
+        status: z.ZodUnion<readonly [z.ZodLiteral<"ok">, z.ZodLiteral<"error">, z.ZodLiteral<"timeout">, z.ZodLiteral<"skipped">]>;
+        executionCount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        stdout: z.ZodOptional<z.ZodString>;
+        stderr: z.ZodOptional<z.ZodString>;
+        resultPreview: z.ZodOptional<z.ZodString>;
+        displayData: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            mime: z.ZodString;
+            sizeBytes: z.ZodNumber;
+        }, z.core.$strip>>>;
+        rawOutputs: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            ename: z.ZodString;
+            evalue: z.ZodString;
+            traceback: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    env: z.ZodOptional<z.ZodObject<{
+        kernelDisplayName: z.ZodNullable<z.ZodString>;
+        kernelName: z.ZodNullable<z.ZodString>;
+        language: z.ZodNullable<z.ZodString>;
+        pythonVersion: z.ZodString;
+        pythonExecutable: z.ZodString;
+        platform: z.ZodString;
+        pipFreeze: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        cellIndex: z.ZodNumber;
+        ename: z.ZodString;
+        evalue: z.ZodString;
+        traceback: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RunResponse = z.infer<typeof RunResponseSchema>;
+//# sourceMappingURL=execution.d.ts.map

package/dist/domain/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/domain/execution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,eAAe;;;;;;;;iBAQ1B,CAAA;AACF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAEvD,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAiB3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;iBA0BrC,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAE7E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgB5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA"}