@helping-ai-workflow/md2doc 2.8.1 → 2.10.0

package/lib/editor/open.js

@@ -0,0 +1,59 @@
+'use strict';
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+
+function isWSL() {
+    if (process.platform !== 'linux') return false;
+    if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
+    try {
+        return fs.existsSync('/proc/sys/fs/binfmt_misc/WSLInterop');
+    } catch (_) {
+        return false;
+    }
+}
+
+const URL_RE = /^https?:\/\//i;
+
+function defaultWslpath(target) {
+    return spawnSync('wslpath', ['-w', target], { encoding: 'utf8' });
+}
+
+// Pure decision helper: given a target (file path or URL) and injectable
+// environment probes, returns the { cmd, args } to spawn. No side effects
+// beyond the injected wslpathFn (which itself may spawn `wslpath`).
+//
+// WSL note: `wslpath -w '<a URL>'` does NOT fail — it mangles the string
+// into a garbage Windows-flavoured path (e.g. 'http://127.0.0.1:1234/edit/0'
+// -> 'http\127.0.0.11234\edit\0') and still exits 0. So a URL target must be
+// detected up front and routed straight to explorer.exe, which accepts URLs
+// directly on Windows; the wslpath conversion path is for real file paths
+// only.
+function resolveViewerCommand(target, { platform = process.platform, wsl = isWSL(), wslpathFn = defaultWslpath } = {}) {
+    if (platform === 'darwin') {
+        return { cmd: 'open', args: [target] };
+    }
+    if (platform === 'win32') {
+        return { cmd: 'cmd', args: ['/c', 'start', '""', target] };
+    }
+    if (wsl) {
+        if (URL_RE.test(target)) {
+            return { cmd: 'explorer.exe', args: [target] };
+        }
+        const r = wslpathFn(target);
+        if (r.status === 0 && r.stdout) {
+            return { cmd: 'explorer.exe', args: [r.stdout.trim()] };
+        }
+        return { cmd: 'xdg-open', args: [target] };
+    }
+    return { cmd: 'xdg-open', args: [target] };
+}
+
+function openViewer(filePath) {
+    const { cmd, args } = resolveViewerCommand(filePath);
+    const r = spawnSync(cmd, args, { stdio: 'ignore' });
+    if (r.error) {
+        process.stderr.write('warning: could not launch viewer for ' + filePath + ': ' + r.error.message + '\n');
+    }
+}
+
+module.exports = { openViewer, isWSL, resolveViewerCommand };

package/lib/editor/server.js

@@ -0,0 +1,190 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+const { renderMarkdown } = require('../md2doc.js');
+
+const LINEOPS_SRC = fs.readFileSync(path.join(__dirname, 'lineops.js'), 'utf8');
+const INLINE_MD_SRC = fs.readFileSync(path.join(__dirname, 'inline-md.js'), 'utf8');
+const TABLE_MD_SRC = fs.readFileSync(path.join(__dirname, 'table-md.js'), 'utf8');
+// Task 4 (Phase 3): list-md.js's browser factory reads `root.md2docInlineMd`
+// directly (same pattern table-md.js uses) — must land after inline-md.js,
+// same as table-md.js above. Order relative to table-md.js itself doesn't
+// matter (list-md.js never reads window.md2docTableMd), but it's injected
+// right after it to keep the two sibling serializers grouped together.
+const LIST_MD_SRC = fs.readFileSync(path.join(__dirname, 'list-md.js'), 'utf8');
+const HISTORY_SRC = fs.readFileSync(path.join(__dirname, 'history.js'), 'utf8');
+
+function readJson(req, limitBytes = 50 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    // Accumulate raw Buffers and decode ONCE at the end. Per-chunk string
+    // concatenation (`buf += chunk`) decodes each chunk independently, so a
+    // multi-byte UTF-8 character straddling a TCP chunk boundary becomes
+    // U+FFFD — on a multi-MB CJK document that silently corrupts one
+    // character per unlucky chunk boundary (seen in the wild: 9 mangled
+    // chars in one zero-edit save).
+    const chunks = [];
+    let total = 0;
+    req.on('data', (c) => {
+      chunks.push(c);
+      total += c.length;
+      if (total > limitBytes) { reject(new Error('payload too large')); req.destroy(); }
+    });
+    req.on('end', () => {
+      try { resolve(JSON.parse(Buffer.concat(chunks).toString('utf8'))); } catch (e) { reject(e); }
+    });
+  });
+}
+
+function send(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(body);
+}
+
+async function createEditorServer({ files, idleTimeoutMs = 30000, clientJs = '', listenPort = 0 }) {
+  const absFiles = files.map((f) => path.resolve(f));
+  let idleTimer = null;
+  let started = false;
+
+  function bumpIdle(server) {
+    if (!started) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => server.close(), idleTimeoutMs);
+    if (idleTimer.unref) idleTimer.unref();
+  }
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      const editMatch = url.pathname.match(/^\/edit\/(\d+)$/);
+
+      // Cross-origin defense for every state-changing POST route: a
+      // cross-site "simple" POST (form submission, no CORS preflight) cannot
+      // set a non-simple content-type header like application/json, so
+      // requiring it here means a browser blocks the request before it ever
+      // reaches this server — this server never sends CORS headers, so the
+      // browser would otherwise let the request fire-and-forget cross-origin.
+      // /api/ping is included; lib/editor/client.js's fetch calls already
+      // send this header for render, save, and ping.
+      const STATE_CHANGING_POST_PATHS = new Set(['/api/render', '/api/save', '/api/ping']);
+      if (req.method === 'POST' && STATE_CHANGING_POST_PATHS.has(url.pathname)) {
+        const contentType = String(req.headers['content-type'] || '');
+        if (!/^application\/json\b/i.test(contentType)) {
+          return send(res, 415, { error: 'content-type must be application/json' });
+        }
+      }
+
+      if (req.method === 'GET' && editMatch) {
+        const fileId = Number(editMatch[1]);
+        const file = absFiles[fileId];
+        if (!file || !fs.existsSync(file)) return send(res, 404, { error: 'unknown file' });
+        const mdText = fs.readFileSync(file, 'utf8');
+        const mtimeMs = fs.statSync(file).mtimeMs;
+        const { html, blocks } = await renderMarkdown(mdText, file, { editMode: true });
+        const payload = JSON.stringify({
+          fileId, mtimeMs, lines: mdText.split('\n'), blocks,
+        });
+        const inject =
+          `<script>window.__ED__ = ${payload.replace(/</g, '\\u003c')}</script>\n` +
+          `<script>${LINEOPS_SRC}</script>\n` +
+          `<script>${INLINE_MD_SRC}</script>\n` +
+          `<script>${TABLE_MD_SRC}</script>\n` +
+          `<script>${LIST_MD_SRC}</script>\n` +
+          `<script>${HISTORY_SRC}</script>\n` +
+          `<script>${clientJs}</script>\n`;
+        // Splice at the LAST "</body>" — the document's real closing tag.
+        // The first occurrence can sit inside an inlined diagram bundle's JS
+        // string literal (mermaid's DOMPurify source contains "</body>");
+        // String.replace would inject __ED__ mid-bundle and break every
+        // script on the page. Also avoids replace()'s "$" substitution rules.
+        const bodyAt = html.lastIndexOf('</body>');
+        const out = bodyAt !== -1
+          ? html.slice(0, bodyAt) + inject + html.slice(bodyAt)
+          : html + inject;
+        started = true;
+        bumpIdle(server);
+        // no-store: the page embeds a snapshot of the client runtime AND the
+        // file's lines/mtime — a cached copy is stale code + a guaranteed
+        // mtime conflict after any external edit.
+        res.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'cache-control': 'no-store',
+        });
+        return res.end(out);
+      }
+
+      if (req.method === 'POST' && url.pathname === '/api/render') {
+        const { fileId, content } = await readJson(req);
+        const file = absFiles[fileId];
+        if (!file) return send(res, 404, { error: 'unknown file' });
+        const { bodyHtml, blocks } = await renderMarkdown(content, file, { editMode: true });
+        bumpIdle(server);
+        return send(res, 200, { bodyHtml, blocks });
+      }
+
+      if (req.method === 'POST' && url.pathname === '/api/save') {
+        const { fileId, content, baseMtimeMs } = await readJson(req);
+        const file = absFiles[fileId];
+        if (!file) return send(res, 404, { error: 'unknown file' });
+        // baseMtimeMs is REQUIRED, not optional: skipping the compare when
+        // it's missing would let a stale editor tab silently clobber a
+        // newer on-disk edit (the whole point of the mtime guard).
+        if (baseMtimeMs === undefined || baseMtimeMs === null) {
+          return send(res, 400, { error: 'baseMtimeMs is required' });
+        }
+        const cur = fs.statSync(file).mtimeMs;
+        if (cur !== baseMtimeMs) {
+          return send(res, 409, { error: 'mtime-conflict', mtimeMs: cur });
+        }
+        const tmp = file + '.md2doc-tmp';
+        fs.writeFileSync(tmp, content, 'utf8');
+        fs.renameSync(tmp, file);
+        bumpIdle(server);
+        return send(res, 200, { mtimeMs: fs.statSync(file).mtimeMs });
+      }
+
+      if (req.method === 'POST' && url.pathname === '/api/ping') {
+        bumpIdle(server);
+        res.writeHead(204);
+        return res.end();
+      }
+
+      return send(res, 404, { error: 'not found' });
+    } catch (e) {
+      return send(res, 500, { error: String((e && e.message) || e) });
+    }
+  });
+
+  // EADDRINUSE (or any other listen-time error, e.g. a pinned --port that's
+  // already taken) previously fired as an uncaught 'error' event on `server`
+  // with nothing listening, since a plain `server.listen(..., resolve)`
+  // Promise never rejects — it only ever resolves on the 'listening' event.
+  // That crashed the whole process, bypassing bin's `.catch`. Listen for
+  // 'error' too and reject the promise so the caller gets a normal rejection.
+  await new Promise((resolve, reject) => {
+    function onError(err) {
+      server.removeListener('listening', onListening);
+      reject(err);
+    }
+    function onListening() {
+      server.removeListener('error', onError);
+      resolve();
+    }
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(listenPort, '127.0.0.1');
+  });
+  const port = server.address().port;
+  return {
+    server,
+    port,
+    urlFor(absPath) {
+      const i = absFiles.indexOf(path.resolve(absPath));
+      return i === -1 ? null : `http://127.0.0.1:${port}/edit/${i}`;
+    },
+    close() { if (idleTimer) clearTimeout(idleTimer); server.close(); },
+  };
+}
+
+module.exports = { createEditorServer };

package/lib/editor/table-md.js

@@ -0,0 +1,169 @@
+'use strict';
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory(require('./inline-md.js'));
+  } else {
+    root.md2docTableMd = factory(root.md2docInlineMd);
+  }
+})(typeof self !== 'undefined' ? self : this, function (inlineMd) {
+
+  // table-md.js — table DOM -> minimal-form GFM markdown (Phase-2 Task 5).
+  //
+  // ── Renderer finding (verified against lib/md2doc.js's renderer.table,
+  //    ~line 650, BEFORE writing serializeTable below — required by the
+  //    task brief) ───────────────────────────────────────────────────────
+  // Per-column alignment: renderer.table's `alignStyle(cell)` helper emits
+  // `style="text-align:<left|right|center>"` on BOTH <th> and <td> for that
+  // column ONLY when marked's lexed `cell.align` is truthy (an explicit GFM
+  // `:---` / `---:` / `:---:` separator was used). A column with the plain
+  // `---` separator (marked's `cell.align === null`) gets NO style
+  // attribute at all — not `style="text-align:left"`, nothing. So
+  // alignment must be read from the PRESENCE/VALUE of the `style`
+  // attribute — read here from the header row's <th> cells, since
+  // alignStyle() is applied identically per-column to every row — never
+  // from a class or an `align=` attribute; renderer.table emits neither.
+  //
+  // classifyColumns() (same file) ALSO stamps `class="cell-narrow"` /
+  // `class="cell-prose"` per column — those are rendering-WIDTH hints (see
+  // `.content table col.col-narrow { width: 1% }` in the CSS block) with
+  // nothing to do with text alignment. Reading them as alignment would be a
+  // bug; they are deliberately never consulted below.
+  //
+  // ── Emission form (spec §4 / task-5 brief) ─────────────────────────────
+  // '| a | b |' rows (single-space padding); '|---|' separator row — no
+  // padding around the dashes, ':' alignment variants (':---' / '---:' /
+  // ':---:'), dashes never stretched to content width; literal '|' inside
+  // a cell -> '&#124;'; a cell newline is the literal '<br>' inline-md.js's
+  // serializeInline() already emits for both a real <br> node and a
+  // contenteditable <div> line-split boundary — AND (final-review Finding 1
+  // defense-in-depth) any raw '\n'/'\r' that still reaches a text node is
+  // collapsed to '<br>' here too, via escapeNewlines() below, so a cell can
+  // never split serializeTable()'s output into more physical lines than
+  // it has rows. No trailing whitespace on any emitted line (every row/
+  // separator line is built as '|'-delimited fields, so it always ends in
+  // '|', never in whitespace, by construction). A '|' inside a <code> span
+  // has no faithful gate-safe emission — see cellHasCodePipe() below —
+  // and reports 'CODE' unsupported instead of corrupting it.
+  //
+  // Constrained (same as inline-md.js, and for the same reason: the node
+  // test drives this with the hand-rolled element stub from
+  // test/inline-md.test.js) to childNodes / nodeType / nodeName /
+  // textContent / getAttribute — NO querySelector/querySelectorAll.
+
+  function elementChildren(node) {
+    const out = [];
+    for (let i = 0; i < node.childNodes.length; i++) {
+      const c = node.childNodes[i];
+      if (c.nodeType === 1) out.push(c);
+    }
+    return out;
+  }
+
+  function firstChildNamed(node, name) {
+    const kids = elementChildren(node);
+    for (let i = 0; i < kids.length; i++) {
+      if (kids[i].nodeName === name) return kids[i];
+    }
+    return null;
+  }
+
+  function childrenNamed(node, name) {
+    return elementChildren(node).filter((c) => c.nodeName === name);
+  }
+
+  function isCell(node) {
+    return node.nodeName === 'TH' || node.nodeName === 'TD';
+  }
+
+  // '&#124;' — the postprocess literal-pipe escape (spec §4). Applied AFTER
+  // inline serialization: inline-md.js's own escaping table has no reason
+  // to know about the table-cell delimiter, so it never touches a bare '|'.
+  function escapePipes(s) {
+    return s.split('|').join('&#124;');
+  }
+
+  // Finding 1 (final-review, defense in depth): inline-md.js's escapeText()
+  // and serializeCode() never touch '\n' — a text node carrying a raw
+  // embedded newline (e.g. a paste path that bypassed client.js's own
+  // <br>-segmentation, or any future caller of serializeInline()) would
+  // otherwise leak a literal line break into this cell's md, splitting one
+  // table row into an orphan-cell-line the gate can't parse. Collapse any
+  // raw newline sequence to the same literal '<br>' token a real <br>
+  // element already serializes to (case 4 in table-md.test.js / gate-compat
+  // .test.js) — applied at the same postprocess spot as escapePipes().
+  function escapeNewlines(s) {
+    return s.replace(/\r\n|\r|\n/g, '<br>');
+  }
+
+  // Finding 4: a '|' inside a <code> span has no faithful gate-safe
+  // emission — escapePipes() above runs on the WHOLE cell's serialized md
+  // and can't tell a code span's content from plain text, so naively
+  // applying it would corrupt the code span (turning `` `a|b` `` into the
+  // broken `` `a&#124;b` ``, which never decodes back inside a code span).
+  // `\|` (some other renderers' escape) is the gate's documented trap, so
+  // there's no safe escape at all here — degrade-never-lose: detect a CODE
+  // element anywhere in the cell whose textContent contains '|' and report
+  // it unsupported instead, same signal an IMG/SPAN/etc. already uses to
+  // degrade the whole table to raw-edit (see canWysiwygForTable() in
+  // client.js). Recurses through the cell's element children looking for
+  // CODE — constrained to childNodes/nodeType/nodeName like the rest of
+  // this file (no querySelector, per the node-test stub).
+  function cellHasCodePipe(node) {
+    const kids = elementChildren(node);
+    for (let i = 0; i < kids.length; i++) {
+      const k = kids[i];
+      if (k.nodeName === 'CODE') {
+        if (k.textContent.indexOf('|') !== -1) return true;
+      } else if (cellHasCodePipe(k)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  function cellAlign(cell) {
+    const style = cell.getAttribute('style');
+    if (!style) return null;
+    const m = /text-align\s*:\s*(left|right|center)/.exec(style);
+    return m ? m[1] : null;
+  }
+
+  function sepCellFor(align) {
+    if (align === 'left') return ':---';
+    if (align === 'right') return '---:';
+    if (align === 'center') return ':---:';
+    return '---';
+  }
+
+  function serializeRow(cells, unsupported) {
+    const parts = cells.map((cell) => {
+      if (cellHasCodePipe(cell)) unsupported.push('CODE');
+      const res = inlineMd.serializeInline(cell);
+      res.unsupported.forEach((u) => unsupported.push(u));
+      return escapeNewlines(escapePipes(res.md));
+    });
+    return '| ' + parts.join(' | ') + ' |';
+  }
+
+  function serializeTable(tableEl) {
+    const unsupported = [];
+    const thead = firstChildNamed(tableEl, 'THEAD');
+    const tbody = firstChildNamed(tableEl, 'TBODY');
+    const headerRow = thead ? firstChildNamed(thead, 'TR') : null;
+    const headerCells = headerRow ? elementChildren(headerRow).filter(isCell) : [];
+
+    const lines = [];
+    lines.push(serializeRow(headerCells, unsupported));
+    lines.push('|' + headerCells.map((c) => sepCellFor(cellAlign(c))).join('|') + '|');
+
+    const bodyRows = tbody ? childrenNamed(tbody, 'TR') : [];
+    bodyRows.forEach((tr) => {
+      const cells = elementChildren(tr).filter(isCell);
+      lines.push(serializeRow(cells, unsupported));
+    });
+
+    return { md: lines.join('\n'), unsupported };
+  }
+
+  return { serializeTable };
+});