@hncode/hncode 0.4.2 → 0.5.1

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;
+}

package/src/output-styles.js

@@ -0,0 +1,183 @@
+// Output styles, loaded from FILES — the way Claude Code's `.claude/output-styles/`
+// works (a file's NAME is the style, its BODY is the instructions).
+//
+// Why files rather than another picker entry: an output style is a paragraph of
+// prompting that a user iterates on. Editing a TOML string inside config.toml for
+// that is unpleasant, and it makes the style unreviewable in a diff. A directory of
+// Markdown files means the style is editable with $EDITOR, diffable, and shareable
+// by copying one file.
+//
+// File format (all parts optional except the body):
+//
+//     ---
+//     name: Terse reviewer
+//     description: Reviews code, states findings, no praise
+//     ---
+//     You answer only in short declarative sentences. Never open with praise…
+//
+// A file with no frontmatter is valid: the name then comes from the filename
+// (`terse-reviewer.md` -> `Terse Reviewer`), which is what makes ad-hoc styles
+// cheap to add.
+//
+// The style is INJECTED as a system-ish reminder on each request rather than baked
+// into the system prompt, so switching styles does not invalidate the prompt cache
+// and reverting is a matter of clearing a flag.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Where styles are read from, most specific first.
+ *
+ * `home` is the `.hncode` DIRECTORY, matching how config.js resolves every other
+ * per-user path (`path.join(homeDir(), '.hncode', …)`). Deriving it independently
+ * here — `process.env.HNCODE_HOME || ~/.hncode` — got it wrong under HNCODE_HOME,
+ * which points at the PARENT of `.hncode`: styles then lived in
+ * `<HNCODE_HOME>/output-styles` while the rest of the app looked in
+ * `<HNCODE_HOME>/.hncode/…`, so a user with HNCODE_HOME set could never see a style.
+ * The caller passes `config.hncodeDir()`, so both agree by construction.
+ */
+export function styleDirs(cwd, home) {
+  const base = home || defaultHncodeDir();
+  const dirs = [path.join(base, 'output-styles')];
+  // Project-level styles override the personal ones of the same name, so a repo can
+  // pin its own style for everyone working in it.
+  if (cwd) dirs.push(path.join(cwd, '.hncode', 'output-styles'));
+  return dirs;
+}
+
+// The per-user .hncode directory, resolved exactly as config.js does it:
+//   path.join(HNCODE_HOME || os.homedir(), '.hncode')
+// HNCODE_HOME stands in for the HOME directory — it is how a test or a user keeping
+// config on another drive relocates the whole thing — so `.hncode` is appended to
+// it. Appending it to a value that ALREADY contained `.hncode` put the styles one
+// directory too deep and made them invisible.
+function defaultHncodeDir() {
+  return path.join(process.env.HNCODE_HOME || os.homedir(), '.hncode');
+}
+
+/** `terse-reviewer` -> `Terse Reviewer`. The fallback name when a file has none. */
+export function nameFromFile(file) {
+  const base = path.basename(String(file || ''), '.md');
+  return base.split(/[-_]+/).filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * Split a style file into { meta, body }.
+ *
+ * Only a leading `---` fence is treated as frontmatter — the same rule as Jekyll's,
+ * chosen because a style BODY will often contain `---` (a horizontal rule in
+ * Markdown), and treating a later one as a fence would swallow the instructions.
+ */
+export function parseStyle(raw, file = '') {
+  const text = String(raw == null ? '' : raw).replace(/\r\n/g, '\n');
+  const lines = text.split('\n');
+  const meta = {};
+  let body = text;
+  if (lines[0] !== undefined && lines[0].trim() === '---') {
+    // Find the CLOSING fence; everything between is metadata.
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+      if (lines[i].trim() === '---') { end = i; break; }
+    }
+    if (end > 0) {
+      for (let i = 1; i < end; i++) {
+        const m = /^\s*([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[i]);
+        if (!m) continue;
+        // Strip one layer of quotes if present; a description with a colon is
+        // otherwise fine because only the FIRST colon separates the key.
+        meta[m[1].toLowerCase()] = m[2].trim().replace(/^(['"])(.*)\1$/, '$2');
+      }
+      body = lines.slice(end + 1).join('\n');
+    }
+  }
+  const name = meta.name || nameFromFile(file);
+  return { name, description: meta.description || '', body: body.trim(), meta };
+}
+
+/** Every style readable right now, sorted by name. Missing directories are not an error. */
+export function listStyles(cwd, home) {
+  const found = new Map();   // name (lowercased) -> style
+  for (const dir of styleDirs(cwd, home)) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+    for (const f of entries.sort()) {
+      if (!f.endsWith('.md')) continue;
+      let raw = '';
+      try { raw = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+      const style = parseStyle(raw, f);
+      if (!style.body) continue;                 // a style with no body does nothing
+      // The LATER directory wins (project over personal): this loop runs home first.
+      found.set(style.name.toLowerCase(), { ...style, file: path.join(dir, f), dir });
+    }
+  }
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** One style by name (case-insensitive), or null. */
+export function findStyle(name, cwd, home) {
+  // A trailing `.md` is dropped, since `ls` shows the extension and typing it is the
+  // obvious thing to do after looking at the directory.
+  const want = String(name == null ? '' : name).trim().toLowerCase().replace(/\.md$/, '');
+  if (!want) return null;
+  const all = listStyles(cwd, home);
+  // Every spelling a user might type, most exact first:
+  //   1. the display name (`Terse Reviewer`)
+  //   2. the FILE name without .md (`terse-reviewer`) — this is what `ls` shows and
+  //      what a user types after seeing the directory, and without it the lookup
+  //      failed for the very style they just created.
+  //   3. a prefix of either, so `/output-style terse` is enough to disambiguate.
+  const fileOf = (s) => String(s.file || '').replace(/^.*[\\/]/, '').replace(/\.md$/, '').toLowerCase();
+  return all.find((s) => s.name.toLowerCase() === want)
+    || all.find((s) => fileOf(s) === want)
+    || all.find((s) => s.name.toLowerCase().startsWith(want))
+    || all.find((s) => fileOf(s).startsWith(want))
+    || null;
+}
+
+/**
+ * The reminder text that carries a style into a request.
+ *
+ * Deliberately wrapped in the same `<system-reminder>` envelope the harness uses
+ * elsewhere, and placed so the model reads it as an instruction about FORM rather
+ * than as content to answer. It says the style overrides earlier formatting
+ * requests, because a system prompt already contains output rules and the later
+ * instruction is the one a model follows.
+ */
+export function styleReminder(style) {
+  if (!style || !style.body) return '';
+  return [
+    '<system-reminder>',
+    `The user has selected the "${style.name}" output style. It governs the FORM of`,
+    'your replies and takes precedence over any earlier formatting instruction.',
+    '',
+    style.body,
+    '</system-reminder>',
+  ].join('\n');
+}
+
+/** Create a starter file so /output-style new gives the user something to edit. */
+export function writeStyleTemplate(dir, name) {
+  fs.mkdirSync(dir, { recursive: true });
+  const slug = String(name || 'my-style').trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'my-style';
+  const file = path.join(dir, `${slug}.md`);
+  if (fs.existsSync(file)) return { file, created: false };
+  const body = [
+    '---',
+    `name: ${nameFromFile(file)}`,
+    'description: what this style is for',
+    '---',
+    '',
+    'Write your style instructions here. They describe the FORM of every reply:',
+    'length, tone, structure, what to leave out. They are added to each request as',
+    'a system reminder, so they take precedence over the default formatting rules.',
+    '',
+  ].join('\n');
+  fs.writeFileSync(file, body, 'utf8');
+  return { file, created: true };
+}
+
+export default { styleDirs, listStyles, findStyle, parseStyle, styleReminder, nameFromFile, writeStyleTemplate };

package/src/patch.js

@@ -0,0 +1,248 @@
+// Symbol-level patching — let a plugin wrap ANY exported function or class method
+// in hncode's own source, without editing that source.
+//
+// WHY THIS EXISTS
+// --------------
+// The original `api.patch(seam, fn)` only exposed nine hand-picked "seams"
+// (systemPrompt, llmRequest, …). Everything else — Agent.send, LLM.chat, any of
+// the ~340 exported functions — was unreachable from a plugin. This module makes
+// every symbol patchable by rewriting the target module's SOURCE at load time.
+//
+// HOW IT WORKS (and why it is safe)
+// ---------------------------------
+// ESM exports are read-only bindings, so a plugin cannot monkey-patch them at
+// runtime (verified: `Cannot assign to read only property`). But a module CAN
+// reassign its OWN bindings, and Node's `module.registerHooks({ load })` lets us
+// rewrite a module's source as it is loaded. So for each requested target we:
+//
+//   1. leave the original declaration untouched (no body parsing at all), and
+//   2. append a small footer that reassigns the symbol through our wrapper:
+//        foo = __hncodePatch("file.js#foo", foo);
+//        Klass.prototype.m = __hncodePatch("file.js#Klass.m", Klass.prototype.m);
+//
+// For an `export const` target we also rewrite that one declaration line
+// (`const` → `let`) so it can be reassigned — still a single-line change, still
+// no function-body analysis. This was chosen over an AST rewriter (acorn) to keep
+// hncode's zero-runtime-dependency promise; it relies only on the fact that the
+// target's declaration line is well-formed, which holds for every export in src/.
+//
+// ORDERING (important)
+// --------------------
+// The load hook only sees modules that are imported AFTER it is registered;
+// already-cached modules are left alone (verified). hncode's entry therefore
+// registers this loader and loads plugins BEFORE importing the business modules
+// (see src/bootstrap.js). A module that has already been imported cannot be
+// patched — patching it is reported as a skipped target, not a silent no-op.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import module from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+// Registry: { "file.js#symbol": [handler, …] }. The loader reads it per module.
+const registry = new Map();
+
+// The nine legacy abstract seams, kept so `api.patch('systemPrompt', fn)` from an
+// existing plugin keeps working. These are handled by plugin.js's chain runner,
+// NOT by this module; listed here so api.patch can tell the two target kinds apart.
+export const LEGACY_SEAMS = new Set([
+  'systemPrompt', 'llmRequest', 'llmHeaders', 'llmBody', 'llmResponse',
+  'toolDispatch', 'toolResult', 'beforeRender', 'afterRender',
+]);
+
+let loaderInstalled = false;
+let loaderActive = false;
+const patchedFiles = new Set();
+
+// A target is "file.js#symbol" (a plain export) or "file.js#Class.method".
+const TARGET_RE = /^([^#]+)#([A-Za-z_$][\w$]*)(?:\.([A-Za-z_$][\w$]*))?$/;
+
+/** Normalise a user-supplied target into { file, base, method|null } or null. */
+export function parseTarget(target) {
+  const m = TARGET_RE.exec(String(target || '').trim());
+  if (!m) return null;
+  return { file: m[1], base: m[2], method: m[3] || null, id: `${m[1]}#${m[2]}${m[3] ? '.' + m[3] : ''}` };
+}
+
+/** Register one handler for a symbol target. Returns an unregister function. */
+export function addPatch(target, handler) {
+  const info = parseTarget(target);
+  if (!info) throw new Error(`patch: bad target "${target}" (want "file.js#symbol" or "file.js#Class.method")`);
+  if (!handler || typeof handler !== 'object') throw new Error('patch: handler must be an object like { before, after, around }');
+  if (!info.method && patchedFiles.has(info.file) && !registry.get(info.id)) {
+    // Allow it anyway; the loader may not have run yet for this file.
+  }
+  const list = registry.get(info.id) || [];
+  list.push(handler);
+  registry.set(info.id, list);
+  return () => {
+    const arr = registry.get(info.id);
+    if (!arr) return;
+    const i = arr.indexOf(handler);
+    if (i >= 0) arr.splice(i, 1);
+    if (!arr.length) registry.delete(info.id);
+  };
+}
+
+/** All registered target ids (for /plugins-style introspection). */
+export function listPatchTargets() { return [...registry.keys()]; }
+
+/** Remove every handler (used by _resetPlugins and tests). */
+export function clearPatches() { registry.clear(); }
+
+// ---------------------------------------------------------------------------
+// The runtime wrapper applied in the module footer.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap `fn` so every handler registered for `id` runs around it.
+ * - before(...args): if it returns an array, that replaces the argument list.
+ * - after(result, args): if it returns non-undefined, that replaces the result.
+ * - around(original, args, thisArg): full control; its return value is the result.
+ * Handler `this` is the call's `this` (so a class method can read its instance).
+ */
+export function applyPatches(id, fn) {
+  const handlers = registry.get(id);
+  if (!handlers || !handlers.length) return fn;
+
+  function wrapped(...args) {
+    let finalArgs = args;
+    for (const h of handlers) {
+      if (typeof h.before === 'function') {
+        const r = h.before.apply(this, finalArgs);
+        if (Array.isArray(r)) finalArgs = r;
+      }
+    }
+
+    // `around` takes over the call entirely; otherwise call the original.
+    const aroundHandler = handlers.filter((h) => typeof h.around === 'function').pop();
+    const aroundFn = aroundHandler && aroundHandler.around;
+    const invoke = () => (aroundFn ? aroundFn.call(this, fn, finalArgs, this) : fn.apply(this, finalArgs));
+
+    const finish = (result) => {
+      let out = result;
+      for (const h of handlers) {
+        if (typeof h.after === 'function') {
+          const r = h.after.call(this, out, finalArgs);
+          if (r !== undefined) out = r;
+        }
+      }
+      return out;
+    };
+
+    const r = invoke();
+    // Preserve asyncness: only then-ables get the after-chain deferred.
+    if (r && typeof r.then === 'function') return r.then(finish);
+    return finish(r);
+  }
+  return wrapped;
+}
+
+// Expose to rewritten modules (they run in their own scope and cannot import us
+// without a cycle). One global, set once.
+function installGlobal() {
+  if (!globalThis.__hncodePatch) {
+    globalThis.__hncodePatch = (id, fn) => applyPatches(id, fn);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The load hook: rewrite a module's source to append the patch footers.
+// ---------------------------------------------------------------------------
+
+/** Build the footer source for the targets whose file matches `base`. */
+function footerFor(base, ids) {
+  const lines = ['', '/* hncode:patch-footer (auto-generated) */', ';(() => {', '  const P = globalThis.__hncodePatch;', '  if (!P) return;'];
+  for (const id of ids) {
+    const info = parseTarget(id);
+    if (!info) continue;
+    const ref = info.method ? `${info.base}.prototype.${info.method}` : info.base;
+    lines.push(`  try { ${ref} = P(${JSON.stringify(id)}, ${ref}); } catch (e) { console.error('[hncode-patch] ${id}:', e.message); }`);
+  }
+  lines.push('})();', '');
+  return lines.join('\n');
+}
+
+/**
+ * In `src`, make target `file#symbol` reassignable:
+ *  - `export const NAME = …` → `export let NAME = …`   (only for a plain target)
+ * The declaration line is matched literally; function bodies are never touched.
+ */
+function makeReassignable(src, info) {
+  if (info.method) return src; // class methods are patched via the prototype
+  const re = new RegExp(`^(\\s*)export const (${info.base})\\b`, 'm');
+  return src.replace(re, '$1export let $2');
+}
+
+/** Rewrite one module's source, or return it unchanged when it has no targets. */
+export function rewriteSource(filename, src) {
+  const base = filename.split(/[\\/]/).pop();
+  const ids = [...registry.keys()].filter((id) => parseTarget(id)?.file === base);
+  if (!ids.length) return null;
+
+  let out = src;
+  for (const id of ids) {
+    const info = parseTarget(id);
+    // A plain target declares a top-level function/const; make it mutable if const.
+    out = makeReassignable(out, info);
+  }
+  return out + footerFor(base, ids);
+}
+
+/**
+ * Register the Node load hook. Idempotent and NON-FATAL: if the runtime has no
+ * `module.registerHooks` (added in Node 22.15; hncode still declares engines
+ * >=20) or registration throws, symbol patching is simply disabled. It must
+ * never throw — a throw here would propagate through bootstrap and stop hncode
+ * from starting at all, which is far worse than a missing optional feature.
+ * Returns true when the loader is active.
+ */
+export function installPatchLoader() {
+  installGlobal();
+  if (loaderInstalled) return loaderActive;
+  loaderInstalled = true;
+
+  if (typeof module.registerHooks !== 'function') {
+    // Older Node: patching is unavailable. Everything else keeps working.
+    console.error('[hncode-patch] module.registerHooks is unavailable on this Node — symbol patching disabled.');
+    return (loaderActive = false);
+  }
+
+  let srcDir;
+  try { srcDir = path.dirname(fileURLToPath(import.meta.url)); } catch { return (loaderActive = false); }
+
+  try {
+    module.registerHooks({
+      load(url, context, nextLoad) {
+        const r = nextLoad(url, context);
+        // Only hncode's own src/*.js files, and only when something targets them.
+        if (!url.startsWith('file:') || !url.includes('/src/') || typeof r.source === 'undefined') return r;
+        let file;
+        try { file = fileURLToPath(url); } catch { return r; }
+        if (path.dirname(file) !== srcDir) return r;
+        try {
+          const s = typeof r.source === 'string' ? r.source : Buffer.from(r.source).toString('utf8');
+          const rewritten = rewriteSource(file, s);
+          if (rewritten == null) return r;
+          patchedFiles.add(path.basename(file));
+          return { ...r, source: rewritten, format: r.format || 'module' };
+        } catch (e) {
+          // A rewrite failure must not break the module load — return it as-is
+          // and report, rather than taking hncode down.
+          console.error(`[hncode-patch] failed to rewrite ${url}:`, e && e.message);
+          return r;
+        }
+      },
+    });
+    loaderActive = true;
+  } catch (e) {
+    console.error('[hncode-patch] could not install the load hook — symbol patching disabled:', e && e.message);
+    loaderActive = false;
+  }
+  return loaderActive;
+}
+
+/** Whether the load hook is actually active (installed AND usable). index.js uses
+ *  this to decide whether plugins still need loading — if patching is disabled,
+ *  bootstrap already loaded them, so it must NOT be treated as "installed". */
+export function isLoaderInstalled() { return loaderActive; }