simplecadapi 2.2.2__tar.gz → 2.2.3__tar.gz

{simplecadapi-2.2.2 → simplecadapi-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplecadapi
-Version: 2.2.2
+Version: 2.2.3
 Summary: A simplified OCP-native CAD modeling Python API
 Project-URL: Homepage, https://github.com/PhySpace/SimpleCADAPI
 Project-URL: Repository, https://github.com/PhySpace/SimpleCADAPI
@@ -412,23 +412,20 @@ the full crank cycle sweeps clean in the same sim ·
 
 ---
 
-## Update Notes (2.2.2)
+## Update Notes (2.2.3)
 
 > Validate generated definitions, assembly constraints, and manufacturing
 > geometry before production use.
 
-- **Code completion from the SDK.** In the editor, `scad.` (and `scad.ql.`,
-  `scad.std.gear.`) lists the real functions with their signatures and
-  docstrings. Accepting one, or typing `(` after its name, writes the call with
-  every required parameter as `name=`, and Tab moves between them; inside a call
-  the parameters not given yet complete as `name=`.
-- **New notebooks from the workspace tab.** A **new** action starts a part, or
-  an assembly that uses the first two parts, from the SDK's template; an empty
-  workspace opens on that form.
-- **Fix.** The cell editors no longer rebuild their configuration on every
-  render, which dropped a snippet in progress.
-
-Full notes for this version: [`docs/updates/2.2.2.md`](docs/updates/2.2.2.md).
+- **The editor takes in edits made to the notebook file.** An agent's saved change is applied
+  cell by cell (changed cells update and run again, no reload), and is no longer written over by
+  the editor. If a cell was edited in both places, the file's version is kept and your unsaved
+  text goes to the log. Notebooks added to the workspace appear in the list by themselves.
+- **`sca cell` and `sca new`.** `sca cell ls|get|put|insert|rm|run` edits the open notebook's cells
+  through the running editor (the page updates live, each write prints the cell's status and
+  errors); `sca new NAME` creates a notebook the editor then lists.
+
+Full notes for this version: [`docs/updates/2.2.3.md`](docs/updates/2.2.3.md).
 Earlier versions: the [changelog](CHANGELOG.md) and [`docs/updates/`](docs/updates/).
 
 ---
@@ -449,7 +446,7 @@ in a compact public API for creating solids, applying features, tagging semantic
 intent, querying topology, exporting manufacturing files, and translating recorded
 models into FreeCAD workflows.
 
-Current release: `simplecadapi==2.2.2`.
+Current release: `simplecadapi==2.2.3`.
 
 ## What It Provides
 
@@ -964,6 +961,7 @@ and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reco
 
 ## Documentation
 
+- 2.2.3 update notes: [`docs/updates/2.2.3.md`](docs/updates/2.2.3.md)
 - 2.2.2 update notes: [`docs/updates/2.2.2.md`](docs/updates/2.2.2.md)
 - 2.2.1 update notes: [`docs/updates/2.2.1.md`](docs/updates/2.2.1.md)
 - 2.1.3b1 update notes: [`docs/updates/2.1.3b1.md`](docs/updates/2.1.3b1.md)

{simplecadapi-2.2.2 → simplecadapi-2.2.3}/README.md

@@ -149,23 +149,20 @@ the full crank cycle sweeps clean in the same sim ·
 
 ---
 
-## Update Notes (2.2.2)
+## Update Notes (2.2.3)
 
 > Validate generated definitions, assembly constraints, and manufacturing
 > geometry before production use.
 
-- **Code completion from the SDK.** In the editor, `scad.` (and `scad.ql.`,
-  `scad.std.gear.`) lists the real functions with their signatures and
-  docstrings. Accepting one, or typing `(` after its name, writes the call with
-  every required parameter as `name=`, and Tab moves between them; inside a call
-  the parameters not given yet complete as `name=`.
-- **New notebooks from the workspace tab.** A **new** action starts a part, or
-  an assembly that uses the first two parts, from the SDK's template; an empty
-  workspace opens on that form.
-- **Fix.** The cell editors no longer rebuild their configuration on every
-  render, which dropped a snippet in progress.
-
-Full notes for this version: [`docs/updates/2.2.2.md`](docs/updates/2.2.2.md).
+- **The editor takes in edits made to the notebook file.** An agent's saved change is applied
+  cell by cell (changed cells update and run again, no reload), and is no longer written over by
+  the editor. If a cell was edited in both places, the file's version is kept and your unsaved
+  text goes to the log. Notebooks added to the workspace appear in the list by themselves.
+- **`sca cell` and `sca new`.** `sca cell ls|get|put|insert|rm|run` edits the open notebook's cells
+  through the running editor (the page updates live, each write prints the cell's status and
+  errors); `sca new NAME` creates a notebook the editor then lists.
+
+Full notes for this version: [`docs/updates/2.2.3.md`](docs/updates/2.2.3.md).
 Earlier versions: the [changelog](CHANGELOG.md) and [`docs/updates/`](docs/updates/).
 
 ---
@@ -186,7 +183,7 @@ in a compact public API for creating solids, applying features, tagging semantic
 intent, querying topology, exporting manufacturing files, and translating recorded
 models into FreeCAD workflows.
 
-Current release: `simplecadapi==2.2.2`.
+Current release: `simplecadapi==2.2.3`.
 
 ## What It Provides
 
@@ -701,6 +698,7 @@ and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reco
 
 ## Documentation
 
+- 2.2.3 update notes: [`docs/updates/2.2.3.md`](docs/updates/2.2.3.md)
 - 2.2.2 update notes: [`docs/updates/2.2.2.md`](docs/updates/2.2.2.md)
 - 2.2.1 update notes: [`docs/updates/2.2.1.md`](docs/updates/2.2.1.md)
 - 2.1.3b1 update notes: [`docs/updates/2.1.3b1.md`](docs/updates/2.1.3b1.md)

{simplecadapi-2.2.2 → simplecadapi-2.2.3}/docs/landing.md

@@ -195,6 +195,9 @@ each instruction to one action and wait for them.
      these edges by 1 mm"). You read the selection from the file (`selection` cell) or with
      `sca snapshot`, and you can look at `.sca-editor/viewport.png` to see what they see. Then
      you edit the notebook; they see your change in the editor.
+   - **Work through the editor.** Change cells with `sca cell` (`sca cell ls`, `put`, `insert`):
+     the page updates live and nothing the person typed is overwritten. Editing the file works
+     too: the editor takes the change in within a second.
    - **"Change this cell."** Every cell has a copy button that copies a reference such as
      `/path/u_link.py:L47-L48 (cell 02 ...)`. They paste it to you with what they want changed,
      and you edit exactly those lines.

{simplecadapi-2.2.2 → simplecadapi-2.2.3}/docs/skill/SKILL.md

@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
 license: Apache-2.0
 metadata:
   project: simplecadapi
-  version: 2.2.2
+  version: 2.2.3
   package-name: simplecadapi
-  package-version: 2.2.2
+  package-version: 2.2.3
 ---
 
 # SimpleCAD SDK Skill
@@ -50,7 +50,9 @@ Paths are relative to this file's directory.
   selected, and you MUST read
   `references/domains/editor-collaboration.md` first to see what they
   see (selection cell, `sca snapshot`, cell references) and how to
-  hand the work back.
+  hand the work back. While the editor runs, change its notebooks with
+  `sca cell` (or the file; never both blindly): the editor is the
+  file's writer.
 - Creating, installing, updating, or removing a SimpleCADAPI addon (a
   third-party skill+tooling package around `.scadpkg`) enters no
   workflow; you MUST use `references/domains/addon-development.md`
@@ -202,7 +204,7 @@ print(len(rebuilt))
 - `references/inspect/brep-reverse-engineering.md`
 - `references/domains/addon-development.md` — `sca` addon CLI and authoring guide
 - `references/domains/editor-collaboration.md` — working with a person in `sca edit`:
-  selection cell, snapshot, cell references, parameters
+  selection cell, snapshot, cell references, `sca cell` / `sca new`, parameters
 - `references/docs/guides/reconstruction-agent-test-prompt.md`
 - `references/docs/guides/reconstruction-agent-strategy.md`
 - `references/docs/guides/notebook-runtime.md`

{simplecadapi-2.2.2 → simplecadapi-2.2.3}/docs/skill/references/domains/editor-collaboration.md

@@ -6,11 +6,26 @@ edit code. It is not a workflow. The modeling you do still follows the workflow
 you selected; this page says how to see what the person sees and how to hand
 work back.
 
-The notebook file is the only shared state. The editor autosaves every edit to
+The notebook file is the shared state. The editor autosaves every edit to
 it, and every message the person gives you (a selection, a cell reference, a
 tuned value) is also something you can read from disk. Never rely on what the
 person says they selected when the file or the snapshot can tell you.
 
+The editor holds the open notebook in memory and is the one writer of its
+file. You have two safe ways to change it while it runs; use the first:
+
+1. **`sca cell` (preferred).** It edits through the editor: the page shows the
+   change live (no reload, no flicker), the cell runs, and you get its state back.
+2. **Edit the file.** The editor notices a saved change within a second, compares
+   it with its cells and applies only what differs (changed cells are edited in
+   place and run again, added or removed cells appear or go away). A change to the
+   setup cell or an `@app.function` cell restarts the kernel instead. A file that
+   does not parse is ignored until the next save that does.
+
+If the person has the same cell open with unsaved typing, **your version wins**:
+their text is dropped and kept in the editor's log for them. Do not rewrite a
+cell the person is typing in without telling them.
+
 ## Start the editor for a person
 
 ```bash
@@ -28,6 +43,29 @@ sca edit <workspace> --no-browser --port 7180
   the assembly that fixes them together) to `./u_link_motor_mount`, then
   `sca edit ./u_link_motor_mount`.
 
+## Edit cells through the editor: `sca cell`
+
+```bash
+sca cell ls [--code]                 # numbered cells with status, errors and output
+sca cell get 3                       # one cell: code, status, errors, output
+echo 'L = 90' | sca cell put 3       # replace the code of cell 3 and run it (--no-run to only save)
+sca cell insert --after 3 -f new.py  # add a cell (--after start|end|CELL, --name fn_name)
+sca cell rm 4
+sca cell run [CELL ...]              # run cells (default all) and what they feed
+sca new bracket --kind part          # a new notebook; the open editor lists it, the person's view stays
+```
+
+- A cell is named by its number in `sca cell ls`, its `key`, its function name, or its id.
+  Numbers move when cells are added or removed: read the list the command prints back.
+- Each write prints the touched cell's state (`status`, `errors`, `output`). That is the
+  feedback: read it before the next step, as with any other operation.
+- `put` fails with a conflict if you pass a base that is out of date; without one it
+  replaces the cell, so `get` first when the person may have changed it.
+- The commands find the running editor through `<workspace>/.sca-editor/server.json`. With no
+  editor running, or with another notebook open, `ls` and `get` read the file and the write
+  commands refuse: then edit the file directly, nothing else holds it.
+- `@app.function` cells cannot be changed this way; edit them in the file.
+
 ## Read what the person is doing
 
 | Need | Where |
@@ -140,10 +178,12 @@ file first, since every cell is blocked until it compiles.
 
 ## Rules of thumb
 
-- Re-read the file before editing: the person edits and autosaves too, and the
-  editor rewrites the selection cell.
-- Edit by cell. A change that touches many cells at once makes the person's
+- Re-read the cell before editing (`sca cell get`, or the file): the person edits and
+  autosaves too, and the editor rewrites the selection cell.
+- Edit by cell, with `sca cell`. A change that touches many cells at once makes the person's
   screen reflow and loses their place.
+- New notebooks: `sca new`, not a bare file write plus a request to refresh; the editor
+  lists a new file by itself either way.
 - After an edit, say which cells you changed (by reference) and what to look
   at, so the person can run them and judge the result.
 - Never edit `__marimo__/` or `.sca-editor/`; both are generated.

simplecadapi-2.2.3/docs/updates/2.2.3.md

@@ -0,0 +1,37 @@
+# 2.2.3 Update Notes
+
+The editor (`sca edit`) and an agent can now work on the same notebook without overwriting each other.
+
+## The editor takes in edits made to the file
+
+Before, the editor held the open notebook in memory and rewrote the file on each edit, so a change
+an agent saved was overwritten by the editor's next save and never shown. Now the file is watched:
+a saved change is compared with the editor's cells and applied cell by cell. Changed cells are
+updated and run again, added or removed cells appear or go away, and the page does not reload or
+flicker. A change to the setup cell or an `@app.function` cell restarts the kernel instead; a file
+that does not parse is ignored until the next save that does.
+
+If a cell was edited in both places, **the file's version is kept** and the text you had not saved
+goes to the log at the bottom. Notebooks added to or removed from the workspace appear in the list
+by themselves.
+
+## `sca cell` and `sca new`
+
+```bash
+sca cell ls [--code]                 # numbered cells with status, errors and output
+sca cell get 3
+echo 'L = 90' | sca cell put 3       # replace a cell's code and run it
+sca cell insert --after 3 -f new.py
+sca cell rm 4
+sca cell run [CELL ...]
+sca new bracket --kind part          # a new notebook, listed by the running editor
+```
+
+These go through the running editor, found by `<workspace>/.sca-editor/server.json`: the page shows
+the change live and each write prints the touched cell's status, errors and output. With no editor
+running, or another notebook open, `ls` and `get` read the file and the write commands refuse: edit
+the file directly then.
+
+The skill (`editor-collaboration`) and `landing.md` now tell agents to work this way.
+
+See the [changelog](../../CHANGELOG.md) for the complete list.

simplecadapi-2.2.3/docs/updates/2.2.3.zh-CN.md

@@ -0,0 +1,33 @@
+# 2.2.3 更新说明
+
+`sca edit` 编辑器和 agent 现在可以同时处理同一个 notebook，互不覆盖。
+
+## 编辑器会接收对文件的修改
+
+以前编辑器把打开的 notebook 放在内存里，每次编辑都重写文件，agent 保存的修改会被编辑器的下一次保存
+覆盖，也不会显示出来。现在编辑器会监视文件：保存后的修改会与编辑器里的 cell 对比，按 cell 逐个应用。
+变化的 cell 会更新并重新运行，新增或删除的 cell 会出现或消失，页面不会刷新或闪烁。setup cell 或
+`@app.function` cell 的修改会重启 kernel；无法解析的文件会被忽略，直到下一次可解析的保存。
+
+如果同一个 cell 两边都改了，**保留文件里的版本**，你还没保存的文字会记在底部日志里。工作区里新增或删除的
+notebook 会自动出现在列表中。
+
+## `sca cell` 和 `sca new`
+
+```bash
+sca cell ls [--code]                 # 带编号的 cell，含状态、错误和输出
+sca cell get 3
+echo 'L = 90' | sca cell put 3       # 替换 cell 代码并运行
+sca cell insert --after 3 -f new.py
+sca cell rm 4
+sca cell run [CELL ...]
+sca new bracket --kind part          # 新建 notebook，运行中的编辑器会列出它
+```
+
+这些命令通过运行中的编辑器工作（由 `<workspace>/.sca-editor/server.json` 找到）：页面实时显示修改，每次写入
+都会打印被改 cell 的状态、错误和输出。没有运行中的编辑器，或编辑器打开的是别的 notebook 时，`ls` 和 `get`
+读取文件，写命令会拒绝：这时直接编辑文件即可。
+
+skill（`editor-collaboration`）和 `landing.md` 已让 agent 按这种方式工作。
+
+完整列表见[更新日志](../../CHANGELOG.md)。

{simplecadapi-2.2.2 → simplecadapi-2.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplecadapi"
-version = "2.2.2"
+version = "2.2.3"
 description = "A simplified OCP-native CAD modeling Python API"
 readme = "README.md"
 license = { file = "LICENSE" }

simplecadapi-2.2.3/src/simplecadapi/editor/cli.py

@@ -0,0 +1,326 @@
+"""The ``sca edit`` command (see :mod:`simplecadapi.cli`).
+
+::
+
+    sca edit [WORKSPACE]            # open the editor on a directory of notebooks
+    sca edit path/to/model.py       # ... starting at one notebook
+    sca edit --port 7180 --no-browser
+    sca snapshot [WORKSPACE]        # what the person has selected / is looking at
+    sca cell ls|get|put|insert|rm|run   # edit the cells of the notebook the editor has open
+    sca new NAME [--kind part|assembly] # a new notebook; the editor lists it at once
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+DEFAULT_PORT = 7180
+
+
+def configure(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "edit",
+        help="open the web editor on a workspace of SimpleCAD notebooks",
+        description="Serve the code-first CAD editor for WORKSPACE (default: the "
+        "current directory): a directory of notebooks with [tool.simplecadapi] "
+        "headers, or one such notebook.  Needs the 'editor' extra.",
+    )
+    parser.add_argument("workspace", type=Path, nargs="?", default=Path.cwd())
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+    parser.add_argument("--no-browser", action="store_true", help="do not open a browser tab")
+    parser.set_defaults(handler=_execute, printer=lambda report: None)
+
+    snapshot = subparsers.add_parser(
+        "snapshot",
+        help="print what the editor user has selected and is looking at",
+        description="Print the editor's snapshot for WORKSPACE (default: the current "
+        "directory) as JSON: the selection (the ql code is in the notebook's selection "
+        "cell, saved in the file), the cells' state and errors, the parameter values, and "
+        "the path of the viewport image (a PNG an agent can look at).  The editor keeps "
+        "it in WORKSPACE/.sca-editor/ while it runs.",
+    )
+    snapshot.add_argument("workspace", type=Path, nargs="?", default=Path.cwd())
+    snapshot.set_defaults(handler=_snapshot, printer=_print_snapshot)
+
+    cell = subparsers.add_parser(
+        "cell",
+        help="read and edit the cells of a notebook through the running editor",
+        description="Edit a notebook's cells through the editor that has it open: the page "
+        "shows the change live (no reload) and the editor, the one writer of the file, saves "
+        "it, so nothing is overwritten.  Cells are named by number (see `sca cell ls`), by key "
+        "or by id.  When the editor is not running, or has another notebook open, `ls` and "
+        "`get` read the file and the write commands refuse: edit the file directly then, "
+        "nothing else holds it.",
+    )
+    cell_sub = cell.add_subparsers(dest="cell_command", required=True)
+
+    def common(parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("--notebook", "-n", type=Path, default=None, help="the notebook (default: the one the editor has open)")
+        parser.add_argument("--workspace", "-w", type=Path, default=None, help="the workspace the editor serves (default: found from the current directory)")
+
+    ls = cell_sub.add_parser("ls", help="list the cells with their state")
+    common(ls)
+    ls.add_argument("--code", action="store_true", help="include each cell's code")
+    ls.set_defaults(handler=_cell_ls, printer=_print_json)
+    get = cell_sub.add_parser("get", help="print one cell: its code, state, errors and output")
+    common(get)
+    get.add_argument("cell")
+    get.set_defaults(handler=_cell_get, printer=_print_json)
+    put = cell_sub.add_parser("put", help="replace a cell's code (the code comes from --file or stdin) and run it")
+    common(put)
+    put.add_argument("cell")
+    put.add_argument("--file", "-f", type=Path, default=None, help="read the code from this file (default: stdin)")
+    put.add_argument("--no-run", action="store_true", help="save the code without running the cell")
+    put.set_defaults(handler=_cell_put, printer=_print_json)
+    insert = cell_sub.add_parser("insert", help="add a cell (the code comes from --file or stdin)")
+    common(insert)
+    insert.add_argument("--after", default="end", help="a cell, or `start` / `end` (default)")
+    insert.add_argument("--name", default=None, help="the cell's function name")
+    insert.add_argument("--file", "-f", type=Path, default=None)
+    insert.add_argument("--no-run", action="store_true")
+    insert.set_defaults(handler=_cell_insert, printer=_print_json)
+    rm = cell_sub.add_parser("rm", help="delete a cell")
+    common(rm)
+    rm.add_argument("cell")
+    rm.set_defaults(handler=_cell_rm, printer=_print_json)
+    run = cell_sub.add_parser("run", help="run cells (default: all) and what they feed")
+    common(run)
+    run.add_argument("cells", nargs="*")
+    run.set_defaults(handler=_cell_run, printer=_print_json)
+
+    new = subparsers.add_parser(
+        "new",
+        help="create a notebook in the workspace (the running editor lists it at once)",
+        description="Write a new notebook from the template into WORKSPACE (default: the "
+        "current directory).  A running editor on that workspace lists it without a reload.",
+    )
+    new.add_argument("name")
+    new.add_argument("--kind", choices=("part", "assembly"), default="part")
+    new.add_argument("--workspace", "-w", type=Path, default=None)
+    new.set_defaults(handler=_new_notebook, printer=_print_json)
+
+
+def _execute(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    try:
+        from .server import serve_workspace
+    except ModuleNotFoundError as error:
+        raise ValueError(
+            f"the editor needs the 'editor' extra ({error.name} is missing): "
+            'pip install "simplecadapi[editor]"'
+        ) from error
+    target = args.workspace.expanduser().resolve()
+    notebook = None
+    if target.is_file():
+        notebook, target = target, target.parent
+    elif not target.is_dir():
+        raise ValueError(f"{args.workspace}: no such file or directory")
+    code = serve_workspace(
+        target,
+        host=args.host,
+        port=args.port,
+        open_browser=not args.no_browser,
+        notebook=notebook,
+    )
+    return {}, code
+
+
+def _snapshot(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    import json
+
+    root = args.workspace.expanduser().resolve()
+    if root.is_file():
+        root = root.parent
+    path = root / ".sca-editor" / "snapshot.json"
+    if not path.is_file():
+        raise ValueError(f"{root}: no editor snapshot; is `sca edit` running on this workspace?")
+    return json.loads(path.read_text(encoding="utf-8")), 0
+
+
+def _print_snapshot(report: dict[str, Any]) -> None:
+    import json
+
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+
+
+# -- sca cell / sca new ---------------------------------------------------------
+
+
+def _print_json(report: dict[str, Any]) -> None:
+    import json
+
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+
+
+def _find_editor(start: Path) -> tuple[Path, str] | None:
+    """The running editor whose workspace holds *start*: ``(workspace, base url)``."""
+    import json
+    import urllib.request
+
+    here = start.expanduser().resolve()
+    for directory in (here, *here.parents):
+        record = directory / ".sca-editor" / "server.json"
+        if not record.is_file():
+            continue
+        try:
+            url = json.loads(record.read_text(encoding="utf-8"))["url"]
+            with urllib.request.urlopen(f"{url}/api/health", timeout=1.5):
+                pass
+        except (OSError, ValueError, KeyError):
+            continue  # a stale record: the editor is gone
+        return directory, str(url)
+    return None
+
+
+def _call(url: str, path: str, body: dict | None = None) -> dict[str, Any]:
+    import json
+    import urllib.error
+    import urllib.request
+
+    data = None if body is None else json.dumps(body).encode("utf-8")
+    request = urllib.request.Request(
+        url + path, data=data, headers={"Content-Type": "application/json"}, method="GET" if body is None else "POST"
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=300) as response:
+            return json.loads(response.read())
+    except urllib.error.HTTPError as error:
+        try:
+            return json.loads(error.read())
+        except ValueError:
+            return {"error": f"editor answered {error.code}"}
+
+
+def _session(args: argparse.Namespace, *, write: bool) -> tuple[str | None, Path | None, str]:
+    """``(editor url or None, notebook path or None, relative notebook name)`` for a cell command."""
+    start = args.workspace or (args.notebook.parent if args.notebook else Path.cwd())
+    found = _find_editor(start)
+    notebook = args.notebook.expanduser().resolve() if args.notebook else None
+    if found is None:
+        if write:
+            raise ValueError(
+                "no editor is running on this workspace (start `sca edit`), or edit the notebook file "
+                "directly: nothing else holds it"
+            )
+        if notebook is None:
+            raise ValueError("no editor is running here; name the notebook with --notebook")
+        return None, notebook, notebook.name
+    workspace, url = found
+    open_path = _call(url, "/api/cells").get("notebook")
+    if notebook is None:
+        if open_path is None:
+            raise ValueError("the editor has no notebook open")
+        return url, workspace / open_path, open_path
+    relative = notebook.relative_to(workspace).as_posix() if notebook.is_relative_to(workspace) else notebook.name
+    if relative == open_path:
+        return url, notebook, relative
+    if write:
+        raise ValueError(
+            f"the editor has {open_path} open, not {relative}: edit {relative} directly "
+            "(the editor does not hold it), or open it in the editor first"
+        )
+    return None, notebook, relative
+
+
+def _cells_from_file(notebook: Path) -> list[dict[str, Any]]:
+    from ..runtime._marimo import parse_notebook
+
+    parsed = parse_notebook(notebook.read_text(encoding="utf-8"))
+    cells = []
+    for cell in (parsed.cells if parsed is not None else []):
+        if getattr(cell, "name", None) == "setup":
+            continue
+        cells.append({"index": len(cells) + 1, "name": getattr(cell, "name", None), "code": cell.code, "source": "file"})
+    return cells
+
+
+def _slim(report: dict[str, Any], *, code: bool) -> dict[str, Any]:
+    if "cells" not in report:
+        return report
+    keep = ("index", "key", "name", "title", "status", "errors", "output", "ref", "readonly")
+    return {
+        **report,
+        "cells": [
+            {**{k: c[k] for k in keep if k in c and c[k] not in (None, [], False)}, **({"code": c["code"]} if code else {})}
+            for c in report["cells"]
+        ],
+    }
+
+
+def _cell_ls(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    url, notebook, name = _session(args, write=False)
+    if url is None:
+        assert notebook is not None
+        return {"notebook": name, "source": "file", "cells": _cells_from_file(notebook)}, 0
+    return _slim(_call(url, "/api/cells"), code=args.code), 0
+
+
+def _cell_get(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    url, notebook, name = _session(args, write=False)
+    if url is None:
+        assert notebook is not None
+        cells = _cells_from_file(notebook)
+        if not args.cell.isdigit() or not 1 <= int(args.cell) <= len(cells):
+            raise ValueError("without the editor, name a cell by its number (see `sca cell ls`)")
+        return {"notebook": name, "source": "file", **cells[int(args.cell) - 1]}, 0
+    report = _call(url, "/api/cells")
+    for cell in report.get("cells", []):
+        if args.cell in (str(cell["index"]), cell.get("key"), cell["id"]):
+            return {"notebook": report.get("notebook"), **cell}, 0
+    raise ValueError(f"no cell {args.cell!r}; run `sca cell ls`")
+
+
+def _read_code(args: argparse.Namespace) -> str:
+    import sys
+
+    if args.file is not None:
+        return args.file.read_text(encoding="utf-8")
+    if sys.stdin.isatty():
+        raise ValueError("give the code with --file, or on stdin")
+    return sys.stdin.read()
+
+
+def _write_op(args: argparse.Namespace, op: str, body: dict[str, Any]) -> tuple[dict[str, Any], int]:
+    url, _notebook, _name = _session(args, write=True)
+    assert url is not None
+    report = _call(url, f"/api/cells/{op}", body)
+    if "error" in report:
+        return _slim(report, code=False), 1
+    touched = set(report.get("touched", []))
+    report = _slim(report, code=False)
+    # What the change did: the touched cells with their state; the rest as a count.
+    report["cells"] = [c for c in report["cells"] if c.get("index") in touched] or report["cells"]
+    return report, 0
+
+
+def _cell_put(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    return _write_op(args, "edit", {"cell": args.cell, "code": _read_code(args), "run": not args.no_run})
+
+
+def _cell_insert(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    return _write_op(args, "insert", {"after": args.after, "name": args.name, "code": _read_code(args), "run": not args.no_run})
+
+
+def _cell_rm(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    return _write_op(args, "delete", {"cell": args.cell})
+
+
+def _cell_run(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    return _write_op(args, "run", {"cells": args.cells})
+
+
+def _new_notebook(args: argparse.Namespace) -> tuple[dict[str, Any], int]:
+    from .templates import create_notebook
+
+    start = (args.workspace or Path.cwd()).expanduser().resolve()
+    found = _find_editor(start)
+    root = found[0] if found is not None else start
+    # Only the file is written: the running editor lists it on its own and the
+    # person's current notebook stays open.
+    path = create_notebook(root, args.name, args.kind)
+    return {"ok": True, "path": str(path), "editor_listed": found is not None}, 0
+
+
+__all__ = ["configure"]