@jianxx/dsh-cc-tool-notebook-edit 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/core/tool-notebook-edit/README.md
+README.md: 7307c617dab2ba0afc80ecbeb0eba868bfafe4c6
+README.zh.md: 06f4c83e57781420acb7dd4b4a404907a6138e9d

package/README.md

@@ -0,0 +1,65 @@
+# @jianxx/dsh-cc-tool-notebook-edit
+
+English | [中文](README.zh.md)
+
+Model-facing `NotebookEdit` tool that edits Jupyter notebook (.ipynb) cells, aligned to Claude Code's `NotebookEditTool` replace/insert/delete semantics and cell addressing. It registers into `ctx.tools` via the `@jianxx/dsh-cc-tools` `ToolRuntime` and reads/writes through the harness `ctx.fs` seam.
+
+## Tools
+
+### `NotebookEdit`
+
+Edits one cell of a `.ipynb` notebook.
+
+| Arg | Type | Notes |
+|---|---|---|
+| `notebook_path` | string | Absolute path to the `.ipynb` file (must be absolute; non-.ipynb rejected). |
+| `new_source` | string | The new source for the cell. |
+| `cell_id` | string | Optional. The cell to edit; when `edit_mode=insert`, the new cell is inserted after this one (or at the beginning when omitted). |
+| `cell_type` | `code` / `markdown` | Optional. Defaults to the current cell type; required for `insert`. |
+| `edit_mode` | `replace` / `insert` / `delete` | Optional. Defaults to `replace`. |
+
+Cell references address a cell by its real `id` first, then by the legacy zero-based `cell-<index>` form CC displays for id-less cells — so older notebooks (nbformat 4 < 4.5) are editable the same way CC edits them. Replace clears a code cell's `execution_count` and `outputs`; insert mints a fresh id on nbformat >= 4.5; delete removes the cell.
+
+## Read-before-write gate
+
+Matching CC's `validateInput`, the tool refuses to write a notebook the model never read, and refuses a stale write when the file changed since that read. The gate is driven by the harness observation seam: the plugin keeps a `readStates` map on `apply()` and records every present `fs/observed` observation (the event the Read/Write/Edit tools emit on commit), keyed by resolved path. On execute it rejects a path with no observed read, rejects a path whose current `ctx.fs.stat()` version no longer equals the observed one, and after writing re-baselines the map to the write outcome's version — so its own write counts as the latest read. The seam exposes an opaque `FsVersion` freshness token rather than an mtime; comparing that token is the seam's native staleness check and is strictly stronger than CC's mtime comparison.
+
+The tool is `isConcurrencySafe = () => false`: it mutates shared cell state and the read baseline, so it must never overlap a sibling `NotebookEdit` call.
+
+## Configuration
+
+`Config` is schemastery-typed and currently empty (reserved for future caps):
+
+```ts
+export const Config = z.object({})
+```
+
+Each `apply(ctx, config)` call registers the `NotebookEdit` tool into `ctx.tools` and its `fs/observed` listener. Requires a loaded `ctx.tools` and an active `ctx.fs` backend (e.g. `@deepseek-ai/dsh-fs-local`); the plugin stays pending until `inject: ['tools', 'fs']` is satisfied.
+
+## Install / registration
+
+```ts
+import * as ToolNotebookEdit from '@jianxx/dsh-cc-tool-notebook-edit'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+
+await ctx.plugin(SystemPrompt)
+await ctx.plugin(ToolRuntime)            // @jianxx/dsh-cc-tools
+await ctx.plugin(LocalFileSystem, { cwd }) // ctx.fs backend
+await ctx.plugin(ToolNotebookEdit)        // registers the NotebookEdit tool + listener
+```
+
+## Choice of semantics
+
+- **replace / insert / delete** and **cell addressing** mirror CC's `NotebookEditTool` exactly, including the `cell-<n>` fallback for id-less notebooks and the clear-outputs-on-replace behavior.
+- **Read-before-write gate** reproduces CC's "read first" / "modified since read" rejections as typed `NotebookEditError`s with stable codes.
+- **Write re-baselines** so a second edit without a fresh Read is allowed, exactly as CC's `readFileState` is updated by its own write.
+
+## Build order
+
+`tool-notebook-edit` depends on the workspace `@jianxx/dsh-cc-tools` package and harness base packages (`@deepseek-ai/cordis`, `@deepseek-ai/dsh-fs`, `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-invariants`, `@deepseek-ai/schemastery`). It has no dependency on any other workspace package, so it builds as soon as `core/tools` does; `tsc -b` resolves the reference order automatically.
+
+## Known limitations
+
+- The notebook is rewritten as single-space-indented JSON (matching CC's `IPYNB_INDENT = 1`); surrounding formatting is not preserved.
+- `source` arrays in existing cells are replaced with the given `new_source` string rather than preserved as arrays (same as CC).
+- The read baseline is plugin-lifetime: it resets on plugin reload (HMR), so a model that read a notebook before a reload is asked to Read again first.

package/README.zh.md

@@ -0,0 +1,65 @@
+# @jianxx/dsh-cc-tool-notebook-edit
+
+[English](README.md) | 中文
+
+模型侧 `NotebookEdit` 工具：编辑 Jupyter notebook (.ipynb) 单元格，语义对齐 Claude Code 的 `NotebookEditTool` 的 replace/insert/delete 与单元格寻址。通过 `@jianxx/dsh-cc-tools` 的 `ToolRuntime` 注册进 `ctx.tools`，并通过 harness 的 `ctx.fs` seam 读写。
+
+## 工具
+
+### `NotebookEdit`
+
+编辑某个 `.ipynb` notebook 的一个单元格。
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `notebook_path` | string | `.ipynb` 文件的绝对路径（必须为绝对路径；非 `.ipynb` 会被拒绝）。 |
+| `new_source` | string | 该单元格的新源码。 |
+| `cell_id` | string | 可选。要编辑的单元格；当 `edit_mode=insert` 时，新单元格插入到该单元格之后（省略时插到开头）。 |
+| `cell_type` | `code` / `markdown` | 可选。默认沿用当前单元格类型；`insert` 时必须提供。 |
+| `edit_mode` | `replace` / `insert` / `delete` | 可选。默认 `replace`。 |
+
+单元格引用先按真实 `id` 寻址，再按 CC 为无 id 单元格展示的零基 `cell-<index>` 形式寻址——因此较老版本的 notebook（nbformat 4 且 minor < 4.5）也能像 CC 一样被编辑。replace 会清空 code 单元格的 `execution_count` 与 `outputs`；在 nbformat >= 4.5 上 insert 会生成新 id；delete 移除单元格。
+
+## 写前先读（read-before-write）门
+
+与 CC 的 `validateInput` 一致，工具拒绝写入模型从未读过的 notebook，也拒绝在文件自读取后被改动时（stale write）进行写入。该门由 harness 观测 seam 驱动：插件在 `apply()` 中维护一张 `readStates` 表，并记录每条 `present` 的 `fs/observed` 观测（即 Read/Write/Edit 工具在提交时发出的事件），按键为解析后的路径。execute 时：无已观测读记录 → 拒绝；当前 `ctx.fs.stat()` 版本与该观测版本不一致 → 拒绝。写完后用写入结果的版本重新建立基线——因此工具自身的写视为“已读”的最新基线。seam 暴露的是不透明 `FsVersion` 新鲜度令牌而非 mtime；比较该令牌是 seam 原生的陈旧性校验，严格强于 CC 的 mtime 比较。
+
+该工具为 `isConcurrencySafe = () => false`：它会改动共享的单元格状态与读基线，因此绝不可与并行的兄弟 `NotebookEdit` 调用重叠。
+
+## 配置
+
+`Config` 采用 schemastery 类型，当前为空（预留未来上限）：
+
+```ts
+export const Config = z.object({})
+```
+
+每次 `apply(ctx, config)` 都会把 `NotebookEdit` 工具注册进 `ctx.tools`，并注册其 `fs/observed` 监听器。需要已加载的 `ctx.tools` 与活跃的 `ctx.fs` 后端（例如 `@deepseek-ai/dsh-fs-local`）；在 `inject: ['tools', 'fs']` 满足之前，插件保持等待状态。
+
+## 安装 / 注册
+
+```ts
+import * as ToolNotebookEdit from '@jianxx/dsh-cc-tool-notebook-edit'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+
+await ctx.plugin(SystemPrompt)
+await ctx.plugin(ToolRuntime)             // @jianxx/dsh-cc-tools
+await ctx.plugin(LocalFileSystem, { cwd }) // ctx.fs 后端
+await ctx.plugin(ToolNotebookEdit)        // 注册 NotebookEdit 工具 + 监听器
+```
+
+## 语义取舍
+
+- **replace / insert / delete** 与**单元格寻址**完全对齐 CC 的 `NotebookEditTool`，包括无 id notebook 的 `cell-<n>` 回退，以及 replace 时清空 outputs。
+- **写前先读门**将 CC 的“请先读”/“读取后被修改”拒绝复现为带稳定 code 的 `NotebookEditError`。
+- **写后重设基线**：工具的写被视为最新读基线，第二次编辑无需重新 Read——与 CC 的 `readFileState` 被自身写入更新的行为一致。
+
+## 构建顺序
+
+`tool-notebook-edit` 仅依赖工作区 `@jianxx/dsh-cc-tools` 包与 harness 基础包（`@deepseek-ai/cordis`、`@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-llm`、`@deepseek-ai/dsh-invariants`、`@deepseek-ai/schemastery`）。它不依赖任何其它工作区包，因此只要 `core/tools` 构建完成即可构建；`tsc -b` 会自动解析引用顺序。
+
+## 已知限制
+
+- notebook 以单空格缩进的 JSON 重写（与 CC 的 `IPYNB_INDENT = 1` 一致）；不保留原有排版。
+- 现有单元格中的 `source` 数组会被替换为给定的 `new_source` 字符串，而非保留为数组（与 CC 一致）。
+- 读基线存活期为插件实例：插件热重载（HMR）时会重置，因此 reload 前读过 notebook 的模型需要先重新 Read。

package/lib/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Model-facing `NotebookEdit` tool that edits Jupyter notebook (.ipynb) cells
+ * over the `ctx.fs` seam, aligned with Claude Code's NotebookEditTool: the
+ * `replace` / `insert` / `delete` edit modes, `cell-<n>`-and-real-id cell
+ * addressing for id-less notebooks, and a strict read-before-write gate that
+ * refuses to write a notebook the model never read, or one whose file changed
+ * since that read.
+ *
+ * ## Read-before-write gate
+ *
+ * CC's validateInput requires a prior Read and a fresh file before any edit.
+ * This tool reproduces that over the harness observation seam: `apply()` keeps
+ * a plugin-lifetime `readStates` map (path → observed {@link FsVersion}) fed by
+ * the synchronous `fs/observed` event every time a model-facing read/write/edit
+ * commits a present observation. On execute the tool rejects a path with no
+ * observed read, rejects a path whose current `stat()` version no longer
+ * matches the observed one (an external change — CC's stale mtime check), and
+ * after writing re-baselines the map to the write outcome's version, so its own
+ * write counts as the latest read baseline. The seam exposes an authoritative
+ * opaque version token rather than an mtime; comparing that token is the seam's
+ * native staleness check and is strictly stronger than CC's mtime comparison.
+ * @module @jianxx/dsh-cc-tool-notebook-edit
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+export declare const name = "tool-notebook-edit";
+export declare const inject: string[];
+export { presentNotebookEditCall, presentNotebookEditResult } from './render.ts';
+export type { NotebookEditArgs, NotebookEditResult } from './render.ts';
+export { findCellIndex, languageOf, newCellId, parseCellId, parseNotebook, supportsCellIds, } from './notebook.ts';
+export type { NotebookCell, NotebookContent, } from './notebook.ts';
+/** Stable, machine-routable code for one NotebookEdit failure. */
+export type NotebookEditErrorCode = 'NOTEBOOK_NOT_FOUND' | 'NOTEBOOK_NOT_IPYNB' | 'NOTEBOOK_INVALID_MODE' | 'NOTEBOOK_MISSING_CELL_TYPE' | 'NOTEBOOK_INVALID_JSON' | 'NOTEBOOK_MISSING_CELL_ID' | 'NOTEBOOK_INDEX_OUT_OF_RANGE' | 'NOTEBOOK_ID_NOT_FOUND' | 'NOTEBOOK_NOT_READ' | 'NOTEBOOK_STALE';
+/**
+ * Typed NotebookEdit failure carrying a stable code (like `FsError`), so
+ * failure/retry layers can branch on the code rather than parsing messages.
+ */
+export declare class NotebookEditError extends HarnessError {
+    readonly code: NotebookEditErrorCode;
+    constructor(message: string, code: NotebookEditErrorCode, options?: ErrorOptions);
+}
+/** Plugin runtime configuration (reserved for future caps; none today). */
+export interface Config {
+    /** No configuration today. */
+    readonly _?: never;
+}
+/** Runtime configuration schema. */
+export declare const Config: z<Config>;
+/**
+ * Register the NotebookEdit tool and its plugin-lifetime read-state recorder.
+ * A single `fs/observed` listener feeds a `readStates` map (path → observed
+ * version); the tool is registered once and lives for the whole plugin mount,
+ * so there is no per-call state to reconstruct. cordis auto-disposes both the
+ * listener and the tool registration when the plugin's scope disposes.
+ * @param ctx - active Cordis context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAkBnD,eAAO,MAAM,IAAI,uBAAuB,CAAA;AACxC,eAAO,MAAM,MAAM,UAAkB,CAAA;AAErC,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAChF,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,EACL,aAAa,EACb,UAAU,EACV,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,eAAe,CAAA;AACtB,YAAY,EACV,YAAY,EACZ,eAAe,GAChB,MAAM,eAAe,CAAA;AAQtB,kEAAkE;AAClE,MAAM,MAAM,qBAAqB,GAC7B,oBAAoB,GACpB,oBAAoB,GACpB,uBAAuB,GACvB,4BAA4B,GAC5B,uBAAuB,GACvB,0BAA0B,GAC1B,6BAA6B,GAC7B,uBAAuB,GACvB,mBAAmB,GACnB,gBAAgB,CAAA;AAEpB;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,SAAkB,IAAI,EAAE,qBAAqB,CAAA;gBAEjC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,YAAY;CAKjF;AAED,2EAA2E;AAC3E,MAAM,WAAW,MAAM;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,CAAA;CACnB;AAED,oCAAoC;AACpC,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAAgB,CAAA;AAE7C;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA0FxC"}

package/lib/index.js

@@ -0,0 +1,281 @@
+/**
+ * Model-facing `NotebookEdit` tool that edits Jupyter notebook (.ipynb) cells
+ * over the `ctx.fs` seam, aligned with Claude Code's NotebookEditTool: the
+ * `replace` / `insert` / `delete` edit modes, `cell-<n>`-and-real-id cell
+ * addressing for id-less notebooks, and a strict read-before-write gate that
+ * refuses to write a notebook the model never read, or one whose file changed
+ * since that read.
+ *
+ * ## Read-before-write gate
+ *
+ * CC's validateInput requires a prior Read and a fresh file before any edit.
+ * This tool reproduces that over the harness observation seam: `apply()` keeps
+ * a plugin-lifetime `readStates` map (path → observed {@link FsVersion}) fed by
+ * the synchronous `fs/observed` event every time a model-facing read/write/edit
+ * commits a present observation. On execute the tool rejects a path with no
+ * observed read, rejects a path whose current `stat()` version no longer
+ * matches the observed one (an external change — CC's stale mtime check), and
+ * after writing re-baselines the map to the write outcome's version, so its own
+ * write counts as the latest read baseline. The seam exposes an authoritative
+ * opaque version token rather than an mtime; comparing that token is the seam's
+ * native staleness check and is strictly stronger than CC's mtime comparison.
+ * @module @jianxx/dsh-cc-tool-notebook-edit
+ */
+import { extname } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import { defineTool } from '@jianxx/dsh-cc-tools';
+import { findCellIndex, languageOf, newCellId, parseNotebook, supportsCellIds, } from "./notebook.js";
+import { presentNotebookEditCall, presentNotebookEditResult, } from "./render.js";
+export const name = 'tool-notebook-edit';
+export const inject = ['tools', 'fs'];
+export { presentNotebookEditCall, presentNotebookEditResult } from "./render.js";
+export { findCellIndex, languageOf, newCellId, parseCellId, parseNotebook, supportsCellIds, } from "./notebook.js";
+/**
+ * Canonical JSON indentation for the rewritten .ipynb — a single space, the
+ * same `IPYNB_INDENT = 1` CC uses when it writes a notebook back.
+ */
+const IPYNB_INDENT = 1;
+/**
+ * Typed NotebookEdit failure carrying a stable code (like `FsError`), so
+ * failure/retry layers can branch on the code rather than parsing messages.
+ */
+export class NotebookEditError extends HarnessError {
+    code;
+    constructor(message, code, options) {
+        super(message, code, options);
+        this.name = 'NotebookEditError';
+        this.code = code;
+    }
+}
+/** Runtime configuration schema. */
+export const Config = z.object({});
+/**
+ * Register the NotebookEdit tool and its plugin-lifetime read-state recorder.
+ * A single `fs/observed` listener feeds a `readStates` map (path → observed
+ * version); the tool is registered once and lives for the whole plugin mount,
+ * so there is no per-call state to reconstruct. cordis auto-disposes both the
+ * listener and the tool registration when the plugin's scope disposes.
+ * @param ctx - active Cordis context.
+ */
+export function apply(ctx) {
+    const readStates = new Map();
+    // Cordis auto-clears this listener on plugin dispose (the dispose contract
+    // for this tool's subscription).
+    ctx.on('fs/observed', (target, observation) => {
+        // Synchronous recorder (must not throw: fs/observed is an emit event and a
+        // throw would fail the observing tool's already-committed call). Every
+        // present observation — read, write, or edit — becomes the baseline for
+        // that path, matching CC's readFileState being (re)set by Read/Write/Edit.
+        if (observation.kind === 'present') {
+            readStates.set(target.displayPath, observation.version);
+        }
+    });
+    ctx.tools.register(defineTool({
+        name: 'NotebookEdit',
+        description: 'Replace the contents of a specific cell in a Jupyter notebook. '
+            + 'Use edit_mode=insert to add a new cell after the cell specified by cell_id (or at the beginning when cell_id is omitted), '
+            + 'and edit_mode=delete to remove it. Cell references address a cell by its id, '
+            + 'or by its zero-based cell-<index>.',
+        parameters: {
+            notebook_path: {
+                type: 'string',
+                description: 'The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)',
+                required: true,
+            },
+            cell_id: {
+                type: 'string',
+                description: 'The ID of the cell to edit. When inserting a new cell, the new cell will be inserted after the cell with this ID, or at the beginning if not specified.',
+            },
+            new_source: {
+                type: 'string',
+                description: 'The new source for the cell',
+                required: true,
+            },
+            cell_type: {
+                type: 'string',
+                enum: ['code', 'markdown'],
+                description: 'The type of the cell (code or markdown). If not specified, it defaults to the current cell type. If using edit_mode=insert, this is required.',
+            },
+            edit_mode: {
+                type: 'string',
+                enum: ['replace', 'insert', 'delete'],
+                description: 'The type of edit to make (replace, insert, delete). Defaults to replace.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    new_source: { type: 'string', required: true },
+                    cell_id: { type: 'string' },
+                    cell_type: { type: 'string', enum: ['code', 'markdown'], required: true },
+                    language: { type: 'string', required: true },
+                    edit_mode: { type: 'string', required: true },
+                    error: { type: 'string', required: true },
+                    notebook_path: { type: 'string', required: true },
+                    original_file: { type: 'string', required: true },
+                    updated_file: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => {
+                if (value.error !== '') {
+                    return [{ type: 'text', text: value.error }];
+                }
+                switch (value.edit_mode) {
+                    case 'insert':
+                        return [{ type: 'text', text: `Inserted cell ${value.cell_id ?? ''} with ${value.new_source}` }];
+                    case 'delete':
+                        return [{ type: 'text', text: `Deleted cell ${value.cell_id ?? ''}` }];
+                    default:
+                        return [{ type: 'text', text: `Updated cell ${value.cell_id ?? ''} with ${value.new_source}` }];
+                }
+            },
+        },
+        presentCall: presentNotebookEditCall,
+        presentResult: (args, result) => presentNotebookEditResult(args, result),
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            return editNotebook(ctx, readStates, args, exec);
+        },
+    }));
+}
+/**
+ * Run one NotebookEdit call. Lives in a separate function (called from the
+ * registered closure) so the whole validation → read → gate → edit → write →
+ * re-baseline flow is a single testable unit.
+ */
+async function editNotebook(ctx, readStates, args, exec) {
+    const target = await ctx.fs.resolve(args.notebook_path, { signal: exec.signal });
+    // ── static validation (CC validateInput order) ────────────────────────
+    if (extname(target.displayPath) !== '.ipynb') {
+        throw new NotebookEditError('File must be a Jupyter notebook (.ipynb file). For editing other file types, use the FileEdit tool.', 'NOTEBOOK_NOT_IPYNB');
+    }
+    const editMode = args.edit_mode ?? 'replace';
+    if (editMode !== 'replace' && editMode !== 'insert' && editMode !== 'delete') {
+        throw new NotebookEditError('Edit mode must be replace, insert, or delete.', 'NOTEBOOK_INVALID_MODE');
+    }
+    if (editMode === 'insert' && !args.cell_type) {
+        throw new NotebookEditError('Cell type is required when using edit_mode=insert.', 'NOTEBOOK_MISSING_CELL_TYPE');
+    }
+    // ── read-before-write gate ─────────────────────────────────────────────
+    // (a) no observed read → refuse; (b) file changed since that read → refuse.
+    const observed = readStates.get(target.displayPath);
+    if (observed === undefined) {
+        throw new NotebookEditError('File has not been read yet. Read it first before writing to it.', 'NOTEBOOK_NOT_READ');
+    }
+    const info = await ctx.fs.stat(target, exec.signal);
+    if (info === undefined) {
+        throw new NotebookEditError('Notebook file does not exist.', 'NOTEBOOK_NOT_FOUND');
+    }
+    if (info.version !== observed) {
+        throw new NotebookEditError('File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.', 'NOTEBOOK_STALE');
+    }
+    // ── read + parse ───────────────────────────────────────────────────────
+    let content;
+    try {
+        content = await ctx.fs.readText(target, exec.signal);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            throw new NotebookEditError('Notebook file does not exist.', 'NOTEBOOK_NOT_FOUND');
+        }
+        throw error;
+    }
+    const notebook = parseNotebook(content);
+    if (notebook === null) {
+        throw new NotebookEditError('Notebook is not valid JSON.', 'NOTEBOOK_INVALID_JSON');
+    }
+    // ── cell addressing (CC call semantics) ────────────────────────────────
+    let cellIndex;
+    if (args.cell_id === undefined) {
+        if (editMode !== 'insert') {
+            throw new NotebookEditError('Cell ID must be specified when not inserting a new cell.', 'NOTEBOOK_MISSING_CELL_ID');
+        }
+        cellIndex = 0; // CC defaults to inserting at the beginning.
+    }
+    else {
+        const resolved = findCellIndex(notebook.cells, args.cell_id);
+        if (!resolved.found) {
+            const parsed = /^cell-(\d+)$/.exec(args.cell_id);
+            if (parsed !== null && parsed[1] !== undefined) {
+                const index = Number.parseInt(parsed[1], 10);
+                if (!Number.isNaN(index) && index >= notebook.cells.length) {
+                    throw new NotebookEditError(`Cell with index ${index} does not exist in notebook.`, 'NOTEBOOK_INDEX_OUT_OF_RANGE');
+                }
+            }
+            throw new NotebookEditError(`Cell with ID "${args.cell_id}" not found in notebook.`, 'NOTEBOOK_ID_NOT_FOUND');
+        }
+        cellIndex = resolved.index;
+        if (editMode === 'insert')
+            cellIndex += 1; // insert after the addressed cell
+    }
+    // ── apply the edit ─────────────────────────────────────────────────────
+    let appliedMode = editMode;
+    let insertedIndex;
+    if (appliedMode === 'insert') {
+        insertedIndex = cellIndex;
+        spliceInsert(notebook, cellIndex, args.new_source, args.cell_type ?? 'code', supportsCellIds(notebook) ? newCellId() : undefined);
+    }
+    else if (appliedMode === 'delete') {
+        notebook.cells.splice(cellIndex, 1);
+    }
+    else {
+        const targetCell = notebook.cells[cellIndex];
+        if (targetCell === undefined) {
+            throw new NotebookEditError(`Cell with index ${cellIndex} does not exist in notebook.`, 'NOTEBOOK_INDEX_OUT_OF_RANGE');
+        }
+        targetCell.source = args.new_source;
+        if (targetCell.cell_type === 'code') {
+            targetCell.execution_count = null;
+            targetCell.outputs = [];
+        }
+        if (args.cell_type && args.cell_type !== targetCell.cell_type) {
+            targetCell.cell_type = args.cell_type;
+        }
+    }
+    // ── write back + re-baseline ───────────────────────────────────────────
+    const updatedContent = JSON.stringify(notebook, null, IPYNB_INDENT);
+    let outcome;
+    try {
+        outcome = await ctx.fs.writeText(target, updatedContent, undefined, exec.signal);
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            throw new NotebookEditError('Notebook file does not exist.', 'NOTEBOOK_NOT_FOUND');
+        }
+        throw error;
+    }
+    // This tool's write becomes the latest observed baseline (CC: write sets
+    // readFileState to the post-write mtime).
+    readStates.set(target.displayPath, outcome.version);
+    const resultCellId = insertedIndex !== undefined ? notebook.cells[insertedIndex]?.id : args.cell_id;
+    return {
+        new_source: args.new_source,
+        ...(resultCellId !== undefined ? { cell_id: resultCellId } : {}),
+        cell_type: args.cell_type ?? (appliedMode === 'delete'
+            ? 'code'
+            : notebook.cells[insertedIndex ?? cellIndex]?.cell_type ?? 'code'),
+        language: languageOf(notebook),
+        edit_mode: appliedMode,
+        error: '',
+        notebook_path: target.displayPath,
+        original_file: content,
+        updated_file: updatedContent,
+    };
+}
+/** Insert one new cell (mirroring CC's code vs markdown cell construction). */
+function spliceInsert(notebook, index, source, type, id) {
+    const idPart = id !== undefined ? { id } : {};
+    const cell = type === 'markdown'
+        ? { cell_type: 'markdown', ...idPart, source, metadata: {} }
+        : { cell_type: 'code', ...idPart, source, metadata: {}, execution_count: null, outputs: [] };
+    notebook.cells.splice(index, 0, cell);
+}
+/** Whether a thrown error from ctx.fs signals a missing target. */
+function isNotFound(error) {
+    return (error instanceof Error
+        && error.code === 'FS_NOT_FOUND');
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

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

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@jianxx/dsh-cc-tool-notebook-edit`.
+ * @module @jianxx/dsh-cc-tool-notebook-edit/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-notebook-edit-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,iCAAiC,CAAA;AAClD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AASpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/invariant.js

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for `@jianxx/dsh-cc-tool-notebook-edit`.
+ * @module @jianxx/dsh-cc-tool-notebook-edit/invariant
+ */
+const PACKAGE_NAME = '@jianxx/dsh-cc-tool-notebook-edit';
+/** Cordis companion plugin name. */
+export const name = 'tool-notebook-edit-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No durable runtime invariant: the read-before-write baseline lives only in
+ * the plugin's `apply`-registered closure and is torn down with the plugin
+ * scope, so there is no persistent projection a companion could cross-check.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,YAAY,GAAG,mCAAmC,CAAA;AAExD,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,8BAA8B,CAAA;AAClD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAA;AAEpC;;;;GAIG;AACH,MAAM,OAAO,GAAuB,GAAG,EAAE,GAAE,CAAC,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAuB,EAAE,CACzD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AACjE,sBAAsB"}

package/lib/notebook.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Pure Jupyter notebook (.ipynb) model: JSON parsing, cell addressing, and
+ * generation helpers. No I/O — everything here is a function of its inputs, so
+ * the replace/insert/delete round-trips and the cell-address edge cases are
+ * directly unit-testable apart from the fs seam.
+ *
+ * Cell addressing matches Claude Code's NotebookEditTool: a `cell_id` addresses
+ * a cell by its real `id` first; when no cell carries that id, the legacy
+ * `cell-<index>` form addresses the cell at the zero-based `<index>` (the id a
+ * cell without an `id` field is displayed as). See `parseCellId`.
+ * @module
+ */
+/** One callable (code/markdown) notebook cell. */
+export interface NotebookCell {
+    cell_type: 'code' | 'markdown';
+    id?: string;
+    source: string | string[];
+    metadata: Record<string, unknown>;
+    execution_count?: number | null;
+    outputs?: unknown[];
+}
+/** A parsed Jupyter notebook (.ipynb) document. */
+export interface NotebookContent {
+    cells: NotebookCell[];
+    metadata: {
+        language_info?: {
+            name?: string;
+        };
+    };
+    nbformat: number;
+    nbformat_minor: number;
+}
+/**
+ * Parse raw notebook text into the structural subset this tool edits, or
+ * `null` when the text is not valid JSON or lacks a `cells` array. CC rejects a
+ * non-JSON notebook with "Notebook is not valid JSON."; a malformed-but-JSON
+ * body (missing `cells`) is treated as not a valid notebook for the same guard,
+ * because there is no cell list to address.
+ * @param content - the raw file text.
+ * @returns the parsed notebook, or `null` when unparseable.
+ */
+export declare function parseNotebook(content: string): NotebookContent | null;
+/**
+ * Parse a `cell-<index>` cell reference into its zero-based index. Any other
+ * form (including a bare numeric string, which is never a valid ipynb cell
+ * identifier) yields `undefined`.
+ * @param cellId - the cell identifier to parse.
+ * @returns the zero-based index, or `undefined` when not a `cell-<n>` form.
+ */
+export declare function parseCellId(cellId: string): number | undefined;
+/**
+ * Resolve a `cell_id` to a cell position. CC matches the real `id` first, then
+ * falls back to the legacy zero-based `cell-<index>` form. Returns the resolved
+ * index and whether it was found, or -1 / false when the identifier addresses
+ * no cell.
+ * @param cells - the notebook's cell list.
+ * @param cellId - the identifier to resolve.
+ * @returns a found cell index, or `{ index: -1, found: false }`.
+ */
+export declare function findCellIndex(cells: readonly NotebookCell[], cellId: string): {
+    index: number;
+    found: boolean;
+};
+/**
+ * The notebook's programming language, defaulting to `python` when the metadata
+ * does not name one — the same default CC uses in `NotebookEditTool.call()`.
+ * @param notebook - the parsed notebook.
+ * @returns the language_info name, or `'python'`.
+ */
+export declare function languageOf(notebook: NotebookContent): string;
+/**
+ * Whether this notebook's format version carries real cell ids (nbformat > 4,
+ * or 4 with minor >= 5). Only such notebooks receive a freshly minted id on
+ * insert / echo the target id on replace; older notebooks keep their ids as-is
+ * (CC only sets the new id under this version gate).
+ * @param notebook - the parsed notebook.
+ * @returns whether the version supports labelled cell ids.
+ */
+export declare function supportsCellIds(notebook: NotebookContent): boolean;
+/**
+ * Mint a fresh, collision-safe cell id: a base-36 string, matching CC's
+ * `Math.random().toString(36).substring(2, 15)` id generator.
+ * @returns a new cell id.
+ */
+export declare function newCellId(): string;
+//# sourceMappingURL=notebook.d.ts.map

package/lib/notebook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notebook.d.ts","sourceRoot":"","sources":["../src/notebook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACzB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,OAAO,CAAC,EAAE,OAAO,EAAE,CAAA;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,QAAQ,EAAE;QAAE,aAAa,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAA;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAoBrE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,MAAM,GACb;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAQnC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAKlE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC"}

package/lib/notebook.js

@@ -0,0 +1,108 @@
+/**
+ * Pure Jupyter notebook (.ipynb) model: JSON parsing, cell addressing, and
+ * generation helpers. No I/O — everything here is a function of its inputs, so
+ * the replace/insert/delete round-trips and the cell-address edge cases are
+ * directly unit-testable apart from the fs seam.
+ *
+ * Cell addressing matches Claude Code's NotebookEditTool: a `cell_id` addresses
+ * a cell by its real `id` first; when no cell carries that id, the legacy
+ * `cell-<index>` form addresses the cell at the zero-based `<index>` (the id a
+ * cell without an `id` field is displayed as). See `parseCellId`.
+ * @module
+ */
+/**
+ * Parse raw notebook text into the structural subset this tool edits, or
+ * `null` when the text is not valid JSON or lacks a `cells` array. CC rejects a
+ * non-JSON notebook with "Notebook is not valid JSON."; a malformed-but-JSON
+ * body (missing `cells`) is treated as not a valid notebook for the same guard,
+ * because there is no cell list to address.
+ * @param content - the raw file text.
+ * @returns the parsed notebook, or `null` when unparseable.
+ */
+export function parseNotebook(content) {
+    let raw;
+    try {
+        raw = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (raw === null || typeof raw !== 'object')
+        return null;
+    const body = raw;
+    const cells = body['cells'];
+    if (!Array.isArray(cells))
+        return null;
+    const metadata = body['metadata'];
+    const nbformat = Number(body['nbformat']);
+    const nbformatMinor = Number(body['nbformat_minor']);
+    return {
+        cells: cells,
+        metadata: metadata,
+        nbformat,
+        nbformat_minor: nbformatMinor,
+    };
+}
+/**
+ * Parse a `cell-<index>` cell reference into its zero-based index. Any other
+ * form (including a bare numeric string, which is never a valid ipynb cell
+ * identifier) yields `undefined`.
+ * @param cellId - the cell identifier to parse.
+ * @returns the zero-based index, or `undefined` when not a `cell-<n>` form.
+ */
+export function parseCellId(cellId) {
+    const match = /^cell-(\d+)$/.exec(cellId);
+    if (match === null || match[1] === undefined)
+        return undefined;
+    const index = Number.parseInt(match[1], 10);
+    return Number.isNaN(index) ? undefined : index;
+}
+/**
+ * Resolve a `cell_id` to a cell position. CC matches the real `id` first, then
+ * falls back to the legacy zero-based `cell-<index>` form. Returns the resolved
+ * index and whether it was found, or -1 / false when the identifier addresses
+ * no cell.
+ * @param cells - the notebook's cell list.
+ * @param cellId - the identifier to resolve.
+ * @returns a found cell index, or `{ index: -1, found: false }`.
+ */
+export function findCellIndex(cells, cellId) {
+    const byId = cells.findIndex(cell => cell.id === cellId);
+    if (byId !== -1)
+        return { index: byId, found: true };
+    const parsed = parseCellId(cellId);
+    if (parsed !== undefined && parsed < cells.length) {
+        return { index: parsed, found: true };
+    }
+    return { index: -1, found: false };
+}
+/**
+ * The notebook's programming language, defaulting to `python` when the metadata
+ * does not name one — the same default CC uses in `NotebookEditTool.call()`.
+ * @param notebook - the parsed notebook.
+ * @returns the language_info name, or `'python'`.
+ */
+export function languageOf(notebook) {
+    return notebook.metadata.language_info?.name ?? 'python';
+}
+/**
+ * Whether this notebook's format version carries real cell ids (nbformat > 4,
+ * or 4 with minor >= 5). Only such notebooks receive a freshly minted id on
+ * insert / echo the target id on replace; older notebooks keep their ids as-is
+ * (CC only sets the new id under this version gate).
+ * @param notebook - the parsed notebook.
+ * @returns whether the version supports labelled cell ids.
+ */
+export function supportsCellIds(notebook) {
+    return (notebook.nbformat > 4 ||
+        (notebook.nbformat === 4 && notebook.nbformat_minor >= 5));
+}
+/**
+ * Mint a fresh, collision-safe cell id: a base-36 string, matching CC's
+ * `Math.random().toString(36).substring(2, 15)` id generator.
+ * @returns a new cell id.
+ */
+export function newCellId() {
+    return Math.random().toString(36).substring(2, 15);
+}
+//# sourceMappingURL=notebook.js.map

package/lib/notebook.js.map

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

package/lib/render.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure presentation (presentCall / presentResult) for the NotebookEdit tool: a
+ * generic pending card naming the target notebook and the resolved edit mode,
+ * and a generic result card that fences errors so a failure reads distinct
+ * from a success summary.
+ * @module @jianxx/dsh-cc-tool-notebook-edit/render
+ */
+import type { GenericCallView, ToolResult, ToolResultView } from '@jianxx/dsh-cc-tools';
+/** Arguments accepted by the NotebookEdit tool. */
+export interface NotebookEditArgs {
+    /** Absolute path to the Jupyter notebook to edit. */
+    notebook_path: string;
+    /** The cell to edit; omitted inserts at the beginning when mode is insert. */
+    cell_id?: string;
+    /** The new source for the cell. */
+    new_source: string;
+    /** The cell type (code/markdown); required for insert, else defaults. */
+    cell_type?: 'code' | 'markdown';
+    /** replace (default), insert, or delete. */
+    edit_mode?: 'replace' | 'insert' | 'delete';
+}
+/** The canonical result of a NotebookEdit call. */
+export interface NotebookEditResult {
+    new_source: string;
+    cell_id?: string;
+    cell_type: 'code' | 'markdown';
+    language: string;
+    edit_mode: string;
+    error: string;
+    notebook_path: string;
+    original_file: string;
+    updated_file: string;
+}
+/**
+ * Present a NotebookEdit pending call as a generic execute card naming the
+ * target notebook and the requested edit mode.
+ * @param args - validated tool arguments.
+ * @returns a generic card view.
+ */
+export declare function presentNotebookEditCall(args: NotebookEditArgs): GenericCallView;
+/**
+ * Present a NotebookEdit result as a generic card. Success shows the written
+ * cell id and source; a failed value (error text present) is fenced so it reads
+ * distinct from a success summary.
+ * @param _args - validated tool arguments (unused by the presenter).
+ * @param result - the finalized tool result.
+ * @returns a generic card view, or `undefined` for an unexpected shape.
+ */
+export declare function presentNotebookEditResult(_args: unknown, result: ToolResult): ToolResultView | undefined;
+//# sourceMappingURL=render.d.ts.map

package/lib/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,cAAc,EACf,MAAM,sBAAsB,CAAA;AAE7B,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC/B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;CAC5C;AAED,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,GACrB,eAAe,CAiBjB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,UAAU,GACjB,cAAc,GAAG,SAAS,CAW5B"}

package/lib/render.js

@@ -0,0 +1,52 @@
+/**
+ * Pure presentation (presentCall / presentResult) for the NotebookEdit tool: a
+ * generic pending card naming the target notebook and the resolved edit mode,
+ * and a generic result card that fences errors so a failure reads distinct
+ * from a success summary.
+ * @module @jianxx/dsh-cc-tool-notebook-edit/render
+ */
+/**
+ * Present a NotebookEdit pending call as a generic execute card naming the
+ * target notebook and the requested edit mode.
+ * @param args - validated tool arguments.
+ * @returns a generic card view.
+ */
+export function presentNotebookEditCall(args) {
+    const mode = args.edit_mode ?? 'replace';
+    return {
+        card: 'generic',
+        title: 'Editing Notebook',
+        kind: 'execute',
+        rawInput: `${args.notebook_path} (${mode})`,
+        content: [
+            {
+                type: 'text',
+                text: args.cell_id === undefined
+                    ? `${mode} in ${args.notebook_path}`
+                    : `${mode} cell ${args.cell_id} in ${args.notebook_path}`,
+            },
+        ],
+    };
+}
+/**
+ * Present a NotebookEdit result as a generic card. Success shows the written
+ * cell id and source; a failed value (error text present) is fenced so it reads
+ * distinct from a success summary.
+ * @param _args - validated tool arguments (unused by the presenter).
+ * @param result - the finalized tool result.
+ * @returns a generic card view, or `undefined` for an unexpected shape.
+ */
+export function presentNotebookEditResult(_args, result) {
+    const block = result.content.length === 1 ? result.content[0] : undefined;
+    if (block === undefined || block.type !== 'text')
+        return undefined;
+    return result.isError
+        ? {
+            card: 'generic',
+            content: [
+                { type: 'text', text: `\`\`\`\n${block.text.replace(/\n+$/, '')}\n\`\`\`` },
+            ],
+        }
+        : { card: 'generic', content: [{ type: 'text', text: block.text }] };
+}
+//# sourceMappingURL=render.js.map

package/lib/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmCH;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAsB;IAEtB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,IAAI,SAAS,CAAA;IACxC,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,GAAG,IAAI,CAAC,aAAa,KAAK,IAAI,GAAG;QAC3C,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EACF,IAAI,CAAC,OAAO,KAAK,SAAS;oBACxB,CAAC,CAAC,GAAG,IAAI,OAAO,IAAI,CAAC,aAAa,EAAE;oBACpC,CAAC,CAAC,GAAG,IAAI,SAAS,IAAI,CAAC,OAAO,OAAO,IAAI,CAAC,aAAa,EAAE;aAC9D;SACF;KACF,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAc,EACd,MAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACzE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,SAAS,CAAA;IAClE,OAAO,MAAM,CAAC,OAAO;QACnB,CAAC,CAAC;YACE,IAAI,EAAE,SAAS;YACf,OAAO,EAAE;gBACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE;aAC5E;SACF;QACH,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAA;AACxE,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@jianxx/dsh-cc-tool-notebook-edit",
+  "description": "NotebookEdit model tool that edits Jupyter notebook (.ipynb) cells over the ctx.fs seam, aligned with Claude Code's NotebookEditTool replace/insert/delete, cell addressing, and read-before-write semantics",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jianxx/dsh-cc-plugins.git",
+    "directory": "packages/core/tool-notebook-edit"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./render": {
+      "types": "./lib/render.d.ts",
+      "default": "./lib/render.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-fs": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": ">=0.1.1-rc.2",
+    "@deepseek-ai/cordis": ">=0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@jianxx/dsh-cc-tools": "^0.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-fs": "link:../../../../deepseek-harness/packages/fs/fs",
+    "@deepseek-ai/dsh-fs-local": "link:../../../../deepseek-harness/packages/fs/fs-local",
+    "@deepseek-ai/dsh-llm": "link:../../../../deepseek-harness/packages/llm/llm",
+    "@deepseek-ai/dsh-invariants": "link:../../../../deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery",
+    "@deepseek-ai/dsh-system-prompt": "link:../../../../deepseek-harness/packages/core/system-prompt",
+    "@jianxx/dsh-cc-tools": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}