@hncode/hncode 0.4.2 → 0.5.0

package/src/lsp.js

@@ -0,0 +1,401 @@
+// LSP client: real diagnostics and symbol lookup from a language server.
+//
+// WHY THIS IS NOT AN MCP SERVER
+// ----------------------------
+// `src/mcp.js` already speaks JSON-RPC, and the temptation is to reuse it. But MCP frames
+// messages as NEWLINE-DELIMITED JSON while LSP frames them with a `Content-Length` header —
+// mcp.js says so itself ("MCP's stdio transport is line-delimited (NOT Content-Length
+// framed — that is the LSP convention, and mixing them up is the usual way this breaks)").
+// Sharing the transport would mean one of the two protocols being wrong. So the framing is
+// implemented here, and only the framing: everything above it is plain JSON-RPC.
+//
+// WHAT IT IS FOR
+// --------------
+// A model editing code benefits from the same thing a human does: being told that the line
+// it just wrote does not compile. This gives the agent that, without a build step and
+// without guessing — the compiler's own answer, over the protocol its own tooling speaks.
+//
+// NO SERVER IS NOT AN ERROR
+// -------------------------
+// Most machines have no language server installed. That is the normal case, not a broken
+// one: `findServer` returns null, callers report "no server for this file", and everything
+// else in hncode works exactly as before. A missing server must never make a turn fail.
+
+import cp from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+
+/** A server definition: how to start it and which files it handles. */
+export const SERVERS = [
+  {
+    id: 'rust-analyzer',
+    command: 'rust-analyzer',
+    extensions: ['.rs'],
+    // rust-analyzer only speaks stdio when told to; it otherwise looks for a socket.
+    args: [],
+  },
+  {
+    id: 'typescript',
+    command: 'typescript-language-server',
+    args: ['--stdio'],
+    extensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+  },
+  {
+    id: 'pyright',
+    command: 'pyright-langserver',
+    args: ['--stdio'],
+    extensions: ['.py', '.pyi'],
+  },
+  {
+    id: 'gopls',
+    command: 'gopls',
+    extensions: ['.go'],
+  },
+  {
+    id: 'clangd',
+    command: 'clangd',
+    extensions: ['.c', '.h', '.cc', '.cpp', '.hpp', '.cxx'],
+  },
+];
+
+/** Is `command` runnable? Checked without spawning, so a probe costs nothing. */
+export function commandExists(command) {
+  const dirs = String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const exts = process.platform === 'win32'
+    ? String(process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';').filter(Boolean)
+    : [''];
+  for (const d of dirs) {
+    for (const ext of exts) {
+      try {
+        const p = path.join(d, command + ext);
+        fs.accessSync(p, fs.constants.X_OK);
+        return p;
+      } catch { /* keep looking */ }
+    }
+  }
+  return null;
+}
+
+/**
+ * The server that handles a file, or null.
+ *
+ * @param {string} file
+ * @returns {{id:string, command:string, args:string[], bin:string}|null}
+ */
+export function findServer(file) {
+  const ext = path.extname(String(file || '')).toLowerCase();
+  if (!ext) return null;
+  for (const s of SERVERS) {
+    if (!s.extensions.includes(ext)) continue;
+    const bin = commandExists(s.command);
+    if (bin) return { ...s, bin };
+  }
+  return null;
+}
+
+/** Every server that is actually installed here, for /doctor and the tool's error text. */
+export function availableServers() {
+  return SERVERS.map((s) => ({ id: s.id, command: s.command, bin: commandExists(s.command) }))
+    .filter((s) => s.bin)
+    .map((s) => ({ id: s.id, command: s.command, bin: s.bin }));
+}
+
+// ---- framing ---------------------------------------------------------------
+
+/**
+ * Encode one JSON-RPC message with an LSP `Content-Length` header.
+ *
+ * The length is BYTES, not characters. A message containing a non-ASCII identifier —
+ * a Rust symbol with a Greek letter, a comment in Chinese — would be cut short by a
+ * character count, and the server would then desynchronise on the next frame, which shows
+ * up as every subsequent request hanging.
+ */
+export function encodeMessage(obj) {
+  const json = JSON.stringify(obj);
+  const len = Buffer.byteLength(json, 'utf8');
+  return Buffer.concat([
+    Buffer.from(`Content-Length: ${len}\r\n\r\n`, 'ascii'),
+    Buffer.from(json, 'utf8'),
+  ]);
+}
+
+/**
+ * A streaming decoder for `Content-Length` frames.
+ *
+ * Chunk boundaries are arbitrary, so a frame can arrive split or several at once. State is
+ * kept between calls; `push` returns whatever complete messages are available NOW.
+ */
+export function createDecoder() {
+  let buf = Buffer.alloc(0);
+  return {
+    push(chunk) {
+      buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+      const out = [];
+      for (;;) {
+        const sep = buf.indexOf('\r\n\r\n');
+        if (sep < 0) break;
+        const header = buf.slice(0, sep).toString('ascii');
+        const m = /Content-Length:\s*(\d+)/i.exec(header);
+        if (!m) {
+          // An unparseable header means the stream is lost: drop what we have rather than
+          // spinning on it forever.
+          buf = buf.slice(sep + 4);
+          continue;
+        }
+        const len = Number(m[1]);
+        const start = sep + 4;
+        if (buf.length < start + len) break;      // the rest has not arrived yet
+        const body = buf.slice(start, start + len).toString('utf8');
+        // Advance past the EXACT byte length, which is why the header was byte-counted.
+        buf = buf.slice(start + len);
+        try { out.push(JSON.parse(body)); } catch { /* a malformed frame is skipped */ }
+      }
+      return out;
+    },
+    /** Bytes held back waiting for the rest of a frame. */
+    get pending() { return buf.length; },
+  };
+}
+
+// ---- the client ------------------------------------------------------------
+
+/** How long to wait for a server to answer before giving up. A language server that has
+ *  not indexed a project will not answer at all, and a hung request is worse than an
+ *  honest "no answer". */
+const DEFAULT_TIMEOUT_MS = 20_000;
+/** How long to let the server finish its handshake and initial analysis. */
+const INIT_TIMEOUT_MS = 30_000;
+
+/**
+ * Start a server and complete the LSP handshake.
+ *
+ * @returns {Promise<{ok:true, client:object} | {ok:false, error:string}>}
+ */
+export async function startClient(server, root, opts = {}) {
+  const log = opts.log || (() => {});
+  let child;
+  try {
+    child = cp.spawn(server.bin, server.args || [], {
+      cwd: root,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      // A shell is NOT used: the argv is already resolved, and a shell would let a path
+      // with a space in it split into two arguments.
+      shell: false,
+    });
+  } catch (e) {
+    return { ok: false, error: `could not start ${server.command}: ${e.message}` };
+  }
+
+  const decoder = createDecoder();
+  const pending = new Map();
+  let nextId = 1;
+  let dead = null;
+  let stderrTail = '';
+  const notifications = [];
+
+  child.stdout.on('data', (chunk) => {
+    for (const msg of decoder.push(chunk)) {
+      if (msg.id != null && (msg.result !== undefined || msg.error !== undefined)) {
+        const waiter = pending.get(msg.id);
+        if (waiter) { pending.delete(msg.id); waiter(msg); }
+      } else if (msg.method) {
+        // Server-initiated notifications and requests (publishDiagnostics, and the
+        // registerCapability requests a server sends during init). Requests are answered
+        // with a null result so the server does not block waiting on us.
+        notifications.push(msg);
+        if (msg.id != null) {
+          try { child.stdin.write(encodeMessage({ jsonrpc: '2.0', id: msg.id, result: null })); }
+          catch { /* the pipe is already gone */ }
+        }
+      }
+    }
+  });
+  child.stderr.on('data', (d) => {
+    // Keep only the tail: rust-analyzer is chatty and the useful error is the last line.
+    stderrTail = (stderrTail + d.toString()).slice(-2000);
+  });
+  const onExit = (code, signal) => {
+    dead = `the language server exited (${signal || code})${stderrTail ? `: ${stderrTail.trim().split('\n').slice(-1)[0]}` : ''}`;
+    for (const [, waiter] of pending) waiter({ error: { message: dead } });
+    pending.clear();
+  };
+  child.on('exit', onExit);
+  child.on('error', (e) => { dead = `the language server failed: ${e.message}`; });
+
+  function send(msg) {
+    if (dead) return Promise.reject(new Error(dead));
+    try { child.stdin.write(encodeMessage(msg)); }
+    catch (e) { return Promise.reject(e); }
+    return null;
+  }
+
+  function request(method, params, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    if (dead) return Promise.reject(new Error(dead));
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`${method} timed out after ${Math.round(timeoutMs / 1000)}s`));
+      }, timeoutMs);
+      pending.set(id, (msg) => {
+        clearTimeout(timer);
+        if (msg.error) reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+        else resolve(msg.result);
+      });
+      try { child.stdin.write(encodeMessage({ jsonrpc: '2.0', id, method, params })); }
+      catch (e) { clearTimeout(timer); pending.delete(id); reject(e); }
+    });
+  }
+
+  function notify(method, params) {
+    try { child.stdin.write(encodeMessage({ jsonrpc: '2.0', method, params })); }
+    catch { /* a dead pipe: the exit handler has already recorded why */ }
+  }
+
+  const rootUri = pathToFileURL(path.resolve(root)).href;
+  const capabilities = {
+    textDocument: {
+      synchronization: { dynamicRegistration: false, didSave: true },
+      publishDiagnostics: { relatedInformation: true },
+      hover: { contentFormat: ['plaintext', 'markdown'] },
+      definition: { linkSupport: false },
+      documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+    },
+    workspace: { workspaceFolders: true, configuration: true },
+  };
+
+  try {
+    await request('initialize', {
+      processId: process.pid,
+      rootUri,
+      rootPath: path.resolve(root),
+      workspaceFolders: [{ uri: rootUri, name: path.basename(path.resolve(root)) }],
+      capabilities,
+      initializationOptions: opts.initializationOptions || {},
+    }, INIT_TIMEOUT_MS);
+  } catch (e) {
+    try { child.kill(); } catch { /* already gone */ }
+    return { ok: false, error: `initialize failed: ${e.message}` };
+  }
+  notify('initialized', {});
+
+  return {
+    ok: true,
+    client: {
+      root,
+      serverId: server.id,
+      request,
+      notify,
+      notifications,
+      stderrTail: () => stderrTail,
+      dead: () => dead,
+      async stop() {
+        try { await request('shutdown', null, 3000); } catch { /* shutting down anyway */ }
+        notify('exit', null);
+        setTimeout(() => { try { child.kill(); } catch { /* gone */ } }, 250);
+      },
+      _child: child,
+      _raw: { log },
+    },
+  };
+}
+
+/** Turn a file path into the `file://` URI LSP expects. */
+export function fileUri(file) {
+  return pathToFileURL(path.resolve(file)).href;
+}
+
+/** And back, for the locations a server reports. */
+export function uriToPath(uri) {
+  try { return fileURLToPath(uri); } catch { return String(uri); }
+}
+
+/**
+ * Open a document. LSP has no "read this file" request — a server only knows about
+ * documents the client has TOLD it about, so `didOpen` is mandatory before any query
+ * about a file will answer.
+ */
+export function openDocument(client, file, text, languageId) {
+  client.notify('textDocument/didOpen', {
+    textDocument: {
+      uri: fileUri(file),
+      languageId: languageId || languageFor(file),
+      version: 1,
+      text,
+    },
+  });
+}
+
+/** Re-send a document's content after it changed on disk. */
+export function changeDocument(client, file, text, version) {
+  client.notify('textDocument/didChange', {
+    textDocument: { uri: fileUri(file), version: version || 2 },
+    contentChanges: [{ text }],
+  });
+}
+
+/** The LSP `languageId` for a file, which servers key their behaviour on. */
+export function languageFor(file) {
+  const ext = path.extname(String(file || '')).toLowerCase();
+  return {
+    '.rs': 'rust',
+    '.ts': 'typescript', '.tsx': 'typescriptreact',
+    '.js': 'javascript', '.jsx': 'javascriptreact', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.py': 'python', '.pyi': 'python',
+    '.go': 'go',
+    '.c': 'c', '.h': 'c',
+    '.cc': 'cpp', '.cpp': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp',
+  }[ext] || 'plaintext';
+}
+
+/**
+ * Diagnostics for one file, from the notifications the server has sent.
+ *
+ * LSP has no "give me diagnostics" request: the server PUSHES them as `publishDiagnostics`
+ * when it has computed them, which for a cold server is after it has indexed the project.
+ * So this waits for the notification for this file, up to `waitMs`. Returning `[]` on a
+ * timeout would claim the file is clean when the truth is "not known yet", so the caller
+ * gets `settled` and can say which it was.
+ *
+ * @returns {Promise<{diagnostics: Array, settled: boolean}>}
+ */
+export async function waitForDiagnostics(client, file, waitMs = 15_000) {
+  const want = fileUri(file);
+  const latest = () => {
+    for (let i = client.notifications.length - 1; i >= 0; i--) {
+      const n = client.notifications[i];
+      if (n.method === 'textDocument/publishDiagnostics' && n.params && n.params.uri === want) {
+        return n.params.diagnostics || [];
+      }
+    }
+    return null;
+  };
+  const now = latest();
+  if (now) return { diagnostics: now, settled: true };
+
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    if (client.dead()) return { diagnostics: [], settled: false };
+    await new Promise((r) => setTimeout(r, 100));
+    const got = latest();
+    if (got) return { diagnostics: got, settled: true };
+  }
+  // An empty list IS a valid answer (a clean file), so the caller must be able to tell
+  // "no problems" from "no answer", which is what `settled` is for.
+  return { diagnostics: [], settled: false };
+}
+
+/** Severity numbers LSP uses, in words. */
+export const SEVERITY_NAMES = ['', 'error', 'warning', 'information', 'hint'];
+
+/** One diagnostic as a readable line: `error 12:5  cannot find value \`x\``. */
+export function formatDiagnostic(d, root) {
+  const sev = SEVERITY_NAMES[d.severity || 1] || 'info';
+  const line = (d.range && d.range.start ? d.range.start.line : 0) + 1;
+  const col = (d.range && d.range.start ? d.range.start.character : 0) + 1;
+  const where = root ? path.relative(root, d._file || '').split(path.sep).join('/') : (d._file || '');
+  const src = d.source ? ` [${d.source}]` : '';
+  const msg = String(d.message || '').replace(/\s+/g, ' ').trim();
+  return `${sev.padEnd(7)} ${where}${where ? ':' : ''}${line}:${col}${src}  ${msg}`;
+}

package/src/notebook.js

@@ -0,0 +1,232 @@
+// Jupyter notebook (.ipynb) support: read and edit CELLS rather than the JSON.
+//
+// WHY THIS EXISTS
+// ---------------
+// `tools/edit.js` REFUSED to touch a .ipynb, and the refusal was right: a notebook is JSON,
+// and a snippet replacement inside it either corrupts the structure or lands in the middle
+// of a base64 image. But refusing is only half an answer — it left the model with no way to
+// change a notebook at all, so it would either give up or reach for Bash and do it by hand.
+//
+// What it needs instead is a view of the notebook as cells, and edits expressed against
+// those cells. That is what this module provides:
+//
+//   listCells      -> the cells, with their index, type and a preview
+//   readCell       -> one cell's source, in full
+//   replaceSource  -> replace one cell's source
+//   insertCell     -> add a cell before/after an index
+//   deleteCell     -> remove one cell
+//
+// THE ONE INVARIANT THAT MATTERS
+// ------------------------------
+// Everything OUTSIDE `cells[i].source` is preserved byte-for-byte in intent: cell ids,
+// metadata, outputs, execution_count, nbformat, the top-level metadata. A notebook carries
+// state that is not the code — outputs a user may want to keep, a kernel's metadata, cell
+// ids that Jupyter's collaboration features key on — and a tool that rebuilt the document
+// from the parsed object would silently drop the fields it did not know about.
+//
+// So the JSON is PARSED to find what to change, the change is applied to the parsed value,
+// and the parsed value is serialised back. Every field survives because every field is
+// carried by the same object; `JSON.stringify` is given the ORIGINAL indentation so the
+// file's diff stays about the edit rather than about reformatting.
+//
+// A MALFORMED NOTEBOOK IS NOT REPAIRED
+// ------------------------------------
+// If the file does not parse, or has no `cells` array, every function here refuses and says
+// why. Guessing at a broken notebook's structure is how a tool turns "I could not help" into
+// "I destroyed your work".
+
+import fs from 'node:fs';
+
+/** Notebook formats this understands. A newer nbformat is accepted: the `cells` shape has
+ *  been stable across 4.x, and refusing a 4.6 file because we know 4.5 would be silly. */
+const MIN_NBFORMAT = 4;
+
+/**
+ * Parse a notebook.
+ *
+ * @returns {{ok: true, doc: object, indent: string} | {ok: false, error: string}}
+ */
+export function parseNotebook(text) {
+  let doc;
+  try { doc = JSON.parse(text); }
+  catch (e) { return { ok: false, error: `not valid JSON: ${e.message}` }; }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { ok: false, error: 'the top level is not an object' };
+  }
+  if (!Array.isArray(doc.cells)) {
+    return { ok: false, error: 'there is no `cells` array (is this really a notebook?)' };
+  }
+  const nbf = Number(doc.nbformat);
+  if (Number.isFinite(nbf) && nbf < MIN_NBFORMAT) {
+    return { ok: false, error: `nbformat ${nbf} is older than ${MIN_NBFORMAT}, whose cell shape this understands` };
+  }
+  // Detect the indentation so a re-serialised file does not reformat the whole document.
+  // Jupyter writes one space, but a hand-edited or tool-generated file may differ.
+  const m = /^([ \t]+)"/m.exec(text);
+  return { ok: true, doc, indent: m ? m[1] : ' ' };
+}
+
+/** Read and parse a file. */
+export function loadNotebook(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); }
+  catch (e) { return { ok: false, error: `could not read ${file}: ${e.message}` }; }
+  const parsed = parseNotebook(text);
+  if (!parsed.ok) return { ok: false, error: `${file}: ${parsed.error}` };
+  return { ...parsed, text };
+}
+
+/**
+ * The source of a cell as one string.
+ *
+ * Jupyter stores `source` as an ARRAY of lines (each keeping its own newline) in nbformat 4,
+ * and as a plain string in some hand-written files. Both spellings appear in the wild, and a
+ * caller that only handled the array read `undefined` from the string form.
+ */
+export function cellSource(cell) {
+  if (!cell) return '';
+  const s = cell.source;
+  if (Array.isArray(s)) return s.join('');
+  if (typeof s === 'string') return s;
+  return '';
+}
+
+/** Split a source string into the array form Jupyter writes, keeping the newlines. */
+export function toSourceLines(text) {
+  const s = String(text == null ? '' : text);
+  if (!s) return [];
+  // `split` with a capture keeps the separators, so `"a\nb\n"` -> `["a\n", "b\n"]`.
+  const parts = s.split(/(?<=\n)/);
+  return parts.filter((p) => p !== '');
+}
+
+/** One-line preview of a cell, for `listCells`. */
+function preview(text, max = 60) {
+  const flat = String(text).replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : flat.slice(0, max - 1) + '\u2026';
+}
+
+/**
+ * List the cells.
+ *
+ * @returns {Array<{index:number, id:string, type:string, lines:number, source:string,
+ *   preview:string, outputs:number, executionCount:number|null}>}
+ *   `index` is 0-based and is what every other function here takes.
+ */
+export function listCells(doc) {
+  return (doc.cells || []).map((c, i) => {
+    const src = cellSource(c);
+    return {
+      index: i,
+      id: c.id == null ? '' : String(c.id),
+      type: String(c.cell_type || 'unknown'),
+      lines: src ? src.split('\n').length : 0,
+      source: src,
+      preview: preview(src),
+      outputs: Array.isArray(c.outputs) ? c.outputs.length : 0,
+      executionCount: c.execution_count == null ? null : c.execution_count,
+    };
+  });
+}
+
+/** Render the cell list for a tool result or a panel. */
+export function describeCells(doc, file) {
+  const cells = listCells(doc);
+  const header = file ? `${file} — ${cells.length} cell(s)` : `${cells.length} cell(s)`;
+  if (!cells.length) return [header, '', 'The notebook has no cells.'];
+  const lines = [header, ''];
+  for (const c of cells) {
+    const meta = [];
+    if (c.type === 'code' && c.executionCount != null) meta.push(`[${c.executionCount}]`);
+    if (c.outputs) meta.push(`${c.outputs} output(s)`);
+    lines.push(`  ${String(c.index).padStart(3)}  ${c.type.padEnd(8)} ${c.lines} line(s) ${meta.join(' ')}`);
+    if (c.preview) lines.push(`       ${c.preview}`);
+  }
+  return lines;
+}
+
+/** Serialise a document back, preserving the file's own indentation. */
+export function serializeNotebook(doc, indent = ' ') {
+  // A notebook written by Jupyter ends with a newline; matching that keeps the file's last
+  // line unchanged, so a diff does not show a spurious "".
+  return JSON.stringify(doc, null, indent) + '\n';
+}
+
+/** Save a document, atomically, so a crash cannot leave a half-written notebook. */
+export function saveNotebook(file, doc, indent = ' ') {
+  const text = serializeNotebook(doc, indent);
+  const tmp = `${file}.${process.pid}.nb.tmp`;
+  try {
+    fs.writeFileSync(tmp, text, 'utf8');
+    fs.renameSync(tmp, file);
+    return { ok: true };
+  } catch (e) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    return { ok: false, error: e.message };
+  }
+}
+
+/** True when an index addresses a real cell. Reported by name so the message is actionable. */
+export function checkIndex(doc, index) {
+  const n = (doc.cells || []).length;
+  if (!Number.isInteger(index)) return { ok: false, error: `cell index must be an integer (got ${JSON.stringify(index)})` };
+  if (index < 0 || index >= n) return { ok: false, error: `cell index ${index} is out of range (the notebook has ${n} cell(s): 0-${n - 1})` };
+  return { ok: true };
+}
+
+/**
+ * Replace one cell's source, leaving everything else about it — outputs, metadata, id —
+ * exactly as it was.
+ *
+ * Clearing `outputs` would be the tempting "correct" thing, since the old output no longer
+ * matches the new code. It is the wrong default: the agent is editing SOURCE, and a user who
+ * asked for one line to change does not expect their stored outputs to be dropped. The
+ * unchanged-output state is what Jupyter itself shows when you edit a cell without running
+ * it, so it is also the least surprising.
+ *
+ * @returns {{ok: true, cell: object} | {ok: false, error: string}}
+ */
+export function replaceSource(doc, index, source) {
+  const idx = checkIndex(doc, index);
+  if (!idx.ok) return idx;
+  const cell = doc.cells[index];
+  cell.source = toSourceLines(source);
+  return { ok: true, cell };
+}
+
+/**
+ * Insert a cell.
+ *
+ * @param {number} index insert BEFORE this index; `doc.cells.length` appends.
+ */
+export function insertCell(doc, index, source, type = 'code') {
+  const n = (doc.cells || []).length;
+  if (!Number.isInteger(index) || index < 0 || index > n) {
+    return { ok: false, error: `insert index must be 0-${n} (got ${JSON.stringify(index)})` };
+  }
+  const kind = type === 'markdown' || type === 'raw' ? type : 'code';
+  const cell = { cell_type: kind, metadata: {}, source: toSourceLines(source) };
+  if (kind === 'code') { cell.outputs = []; cell.execution_count = null; }
+  // nbformat 4.5+ requires every cell to carry an id. Adding one keeps a notebook that had
+  // ids from becoming invalid; a notebook that predates them is left alone.
+  const anyId = (doc.cells || []).some((c) => c && c.id);
+  if (anyId || Number(doc.nbformat_minor) >= 5) cell.id = newCellId();
+  doc.cells.splice(index, 0, cell);
+  return { ok: true, cell, index };
+}
+
+/** Remove one cell. */
+export function deleteCell(doc, index) {
+  const idx = checkIndex(doc, index);
+  if (!idx.ok) return idx;
+  const [removed] = doc.cells.splice(index, 1);
+  return { ok: true, removed };
+}
+
+/** A short random id in the shape Jupyter uses (8 lowercase hex/alnum characters). */
+export function newCellId() {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let out = '';
+  for (let i = 0; i < 8; i++) out += alphabet[Math.floor(Math.random() * alphabet.length)];
+  return out;
+}