@hncode/hncode 0.4.2 → 0.5.1

package/src/tools/notebook.js

@@ -0,0 +1,113 @@
+// NotebookEdit — read and edit a Jupyter notebook by CELL.
+//
+// WHY A TOOL AND NOT A BRANCH IN `Edit`
+// ------------------------------------
+// `Edit`'s contract is "replace this text with that text", and a notebook has no text to
+// match: the source lives inside a JSON array, so a `old_string` would match in one place in
+// the .ipynb and mean something different in the cell. Expressing the operation as CELL
+// indices removes the ambiguity entirely — there is nothing to match, so nothing to match
+// wrongly.
+//
+// `tools/edit.js` still refuses a .ipynb, and now says to use THIS instead. That refusal is
+// the safety property: a notebook can only be changed through an operation that knows its
+// structure, so the corruption the refusal prevented remains impossible.
+//
+// Everything outside the edited `source` is preserved: outputs, metadata, cell ids, the
+// top-level metadata. See src/notebook.js for why that is an invariant rather than a nicety.
+
+import {
+  loadNotebook, listCells, describeCells, replaceSource, insertCell,
+  deleteCell, checkIndex, cellSource, saveNotebook,
+} from '../notebook.js';
+import { resolvePath } from './utils.js';
+import { checkpointBeforeWrite } from './utils.js';
+
+export const spec = {
+  name: 'NotebookEdit',
+  description: `Read and change a Jupyter notebook (.ipynb) by CELL. Plain Edit refuses .ipynb because a notebook is JSON — use this instead.
+
+Actions:
+- \`list\`: every cell with its index, type, line count and a one-line preview. Do this FIRST unless you already know the indices.
+- \`read\`: one cell's source in full.
+- \`replace\`: replace one cell's source. Everything else about the cell (its outputs, metadata, id) is preserved.
+- \`insert\`: add a cell BEFORE an index; use index = cell count to append.
+- \`delete\`: remove one cell.
+
+Indices are 0-based and refer to the list \`list\` prints. Recent output is kept when a cell's source is replaced, exactly as Jupyter does when you edit without re-running.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the .ipynb file.' },
+      action: { type: 'string', enum: ['list', 'read', 'replace', 'insert', 'delete'], description: 'What to do.' },
+      index: { type: 'integer', description: '0-based cell index. Required for read/replace/insert/delete. For insert, the new cell goes BEFORE this index (cell count to append).' },
+      source: { type: 'string', description: 'The cell source. Required for replace and insert.' },
+      cell_type: { type: 'string', enum: ['code', 'markdown', 'raw'], description: 'Type for an inserted cell; defaults to code.' },
+    },
+    required: ['path', 'action'],
+  },
+
+  async execute(args, ctx) {
+    if (typeof args.path !== 'string' || !args.path.trim()) return 'Error: `path` is required.';
+    const action = String(args.action || '').toLowerCase();
+    if (!['list', 'read', 'replace', 'insert', 'delete'].includes(action)) {
+      return `Error: \`action\` must be one of list, read, replace, insert, delete (got ${JSON.stringify(args.action)}).`;
+    }
+    let abs;
+    try { abs = resolvePath(args.path, ctx); } catch (e) { return e.message; }
+    if (!String(abs).toLowerCase().endsWith('.ipynb')) {
+      return `Error: ${args.path} is not a .ipynb file. Use Edit for ordinary text files.`;
+    }
+    const loaded = loadNotebook(abs);
+    if (!loaded.ok) return `Error: ${loaded.error}`;
+
+    if (action === 'list') {
+      return describeCells(loaded.doc, args.path).join('\n');
+    }
+
+    const idx = checkIndex(loaded.doc, args.index);
+    if (!idx.ok) return `Error: ${idx.error}`;
+
+    if (action === 'read') {
+      const cell = loaded.doc.cells[args.index];
+      const type = cell.cell_type || 'unknown';
+      const src = cellSource(cell);
+      return `cell ${args.index} (${type}, ${src ? src.split('\n').length : 0} line(s)):\n\n${src}`;
+    }
+
+    if (action === 'replace') {
+      if (typeof args.source !== 'string') return 'Error: `source` is required for replace.';
+      const before = cellSource(loaded.doc.cells[args.index]);
+      const r = replaceSource(loaded.doc, args.index, args.source);
+      if (!r.ok) return `Error: ${r.error}`;
+      // A checkpoint BEFORE the write, like Edit does, so /checkpoints and /undo can put
+      // the previous cell content back.
+      try { checkpointBeforeWrite(abs, ctx); } catch { /* best effort */ }
+      const saved = saveNotebook(abs, loaded.doc, loaded.indent);
+      if (!saved.ok) return `Error: saving ${args.path}: ${saved.error}`;
+      const beforeLines = before ? before.split('\n').length : 0;
+      const afterLines = args.source ? args.source.split('\n').length : 0;
+      return `Replaced the source of ${args.path} cell ${args.index} (${beforeLines} -> ${afterLines} line(s)). The cell's outputs and metadata are unchanged.`;
+    }
+
+    if (action === 'insert') {
+      if (typeof args.source !== 'string') return 'Error: `source` is required for insert.';
+      const r = insertCell(loaded.doc, args.index, args.source, args.cell_type);
+      if (!r.ok) return `Error: ${r.error}`;
+      try { checkpointBeforeWrite(abs, ctx); } catch { /* best effort */ }
+      const saved = saveNotebook(abs, loaded.doc, loaded.indent);
+      if (!saved.ok) return `Error: saving ${args.path}: ${saved.error}`;
+      return `Inserted a ${r.cell.cell_type} cell at index ${args.index} in ${args.path}. The notebook now has ${loaded.doc.cells.length} cell(s).`;
+    }
+
+    // delete
+    const r = deleteCell(loaded.doc, args.index);
+    if (!r.ok) return `Error: ${r.error}`;
+    try { checkpointBeforeWrite(abs, ctx); } catch { /* best effort */ }
+    const saved = saveNotebook(abs, loaded.doc, loaded.indent);
+    if (!saved.ok) return `Error: saving ${args.path}: ${saved.error}`;
+    return `Deleted cell ${args.index} from ${args.path}. The notebook now has ${loaded.doc.cells.length} cell(s).`;
+  },
+};
+
+/** Exported for tests: the cell list without touching the filesystem. */
+export { listCells };

package/src/tools/read-media-file.js

@@ -52,8 +52,12 @@ export const spec = {
     let p;
     try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
 
-    if (!fs.existsSync(p)) return `Error: file not found: ${args.path}`;
-    const stat = fs.statSync(p);
+    // Async fs throughout. These calls used to be sync, and an image may be tens
+    // of MB — reading it (plus the base64 encode) blocked the event loop long
+    // enough to freeze the TUI while the Working spinner was animating.
+    let stat;
+    try { stat = await fs.promises.stat(p); }
+    catch { return `Error: file not found: ${args.path}`; }
     if (!stat.isFile()) return `Error: not a file: ${args.path}`;
 
     const ext = path.extname(p).toLowerCase();
@@ -67,7 +71,10 @@ export const spec = {
           + 'Resize it, or raise the limit with HNCODE_MEDIA_MAX_BYTES.';
       }
       const mimeType = IMAGE_MIME[ext];
-      const data = fs.readFileSync(p).toString('base64');
+      let buf;
+      try { buf = await fs.promises.readFile(p); }
+      catch (e) { return `Error: could not read ${args.path}: ${e.message}`; }
+      const data = buf.toString('base64');
       const approxKB = Math.round(data.length / 1024);
       return {
         text: `[image] ${args.path} (${sizeKB}KB, ${mimeType})`,

package/src/tools/shell.js

@@ -15,10 +15,26 @@
 // on which one was found.
 
 import cp from 'node:child_process';
+import fs from 'node:fs';
 
 // The two PowerShell families, by the name they are invoked as.
 export const SHELL_CANDIDATES = ['pwsh', 'powershell'];
 
+// Last-resort Windows fallback. A Windows box always has cmd.exe (%COMSPEC%),
+// so when neither PowerShell exists the Bash tool must still run SOMETHING
+// rather than failing outright. `cmd` is not a PowerShell, so the syntax
+// guidance and the spawn args differ (see cmdSpawnArgs).
+export function findCmdExe() {
+  const fromEnv = process.env.COMSPEC || process.env.ComSpec;
+  if (fromEnv) {
+    try { if (fs.existsSync(fromEnv)) return fromEnv; } catch { /* fall through to the PATH probe */ }
+  }
+  if (process.platform === 'win32') {
+    return whichSync('cmd') || whichSync('cmd.exe') || 'cmd.exe';
+  }
+  return null;
+}
+
 /**
  * Resolve an executable name through PATH without spawning it.
  *
@@ -42,13 +58,15 @@ function whichSync(name) {
 }
 
 /**
- * Find a usable PowerShell: pwsh first, then the built-in powershell.
- * Returns { path, name, edition } or null when neither exists.
+ * Find a usable shell: pwsh, then the built-in powershell, then (on Windows)
+ * cmd.exe as a last resort. Returns { path, name, edition } or null.
  *
  * `edition` drives syntax guidance — see the header. It is inferred from the NAME
  * rather than by running the binary (a spawn per probe is not worth it, and
  * PowerShell 6, also named `pwsh`, is EOL and not a realistic target, so `pwsh`
- * safely implies 7+).
+ * safely implies 7+). `edition: 'cmd'` means neither PowerShell exists and the
+ * Bash tool is running through cmd.exe: it still works, but the command syntax is
+ * cmd's, not PowerShell's.
  */
 export function detectShell() {
   for (const name of SHELL_CANDIDATES) {
@@ -57,6 +75,9 @@ export function detectShell() {
       return { path, name, edition: name === 'pwsh' ? 'core' : 'desktop' };
     }
   }
+  // No PowerShell at all: on Windows, guarantee cmd.exe so the tool is not dead.
+  const cmd = findCmdExe();
+  if (cmd) return { path: cmd, name: 'cmd', edition: 'cmd' };
   return null;
 }
 
@@ -91,16 +112,23 @@ export function resetShellCache() {
  * on every single tool call, and `-NonInteractive` stops a command that prompts
  * from hanging the tool forever with no way to answer.
  *
- * Throws a message naming the fix when no PowerShell is installed, instead of
- * letting the caller hit a bare ENOENT.
+ * When neither PowerShell exists, `edition === 'cmd'` selects cmd.exe args instead
+ * (see detectShell). Throws a message naming the fix only when no shell at all
+ * was found, instead of letting the caller hit a bare ENOENT.
  */
 export function shellSpawnArgs(command) {
   const shell = getShell();
   if (!shell) {
     throw new Error(
-      'No PowerShell found on PATH (tried pwsh, powershell). '
+      'No shell found (tried pwsh, powershell, and cmd.exe). '
       + 'Install PowerShell 7+ or add it to PATH, then retry.',
     );
   }
+  if (shell.edition === 'cmd') {
+    // cmd.exe: `/d` skips AutoRun commands, `/s` makes `/c` quoting behave
+    // predictably. The command is passed as ONE argv element, so Node does the
+    // quoting and we do not wrap it ourselves.
+    return { bin: shell.path, args: ['/d', '/s', '/c', command], shell };
+  }
   return { bin: shell.path, args: ['-NoProfile', '-NonInteractive', '-Command', command], shell };
 }