@helping-ai-workflow/md2doc 1.0.1 → 1.0.3

package/README.md

@@ -6,11 +6,39 @@ Two global CLIs (`md2html`, `md2pdf`) you can call from any directory.
 
 ## Install
 
+Requires Node.js 18 or higher. The first install pulls puppeteer (≈ 170 MB Chromium download); subsequent installs reuse it.
+
+### Recommended: install via nvm
+
+If you do not yet have Node.js — or your system Node lives under `/usr/local` and `npm install -g` fails with `EACCES` — install Node through [nvm](https://github.com/nvm-sh/nvm) first. nvm puts Node under `~/.nvm`, so global packages never need `sudo`.
+
 ```bash
+sudo apt install -y curl     # Debian / Ubuntu only; skip if curl is already installed
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
+source ~/.zshrc              # or: source ~/.bashrc
+nvm install --lts
+nvm use --lts
 npm install -g @helping-ai-workflow/md2doc
 ```
 
-Requires Node.js 18 or higher. The first install pulls puppeteer (≈ 170 MB Chromium download); subsequent installs reuse it.
+### Already have Node.js
+
+```bash
+npm install -g @helping-ai-workflow/md2doc
+```
+
+### Troubleshooting
+
+**`EACCES: permission denied, mkdir '/usr/local/lib/node_modules'`**
+Your system Node is owned by root. Do **not** run `sudo npm install -g` — puppeteer's postinstall would download Chromium as root and break later runs. Instead, switch to nvm using the steps above.
+
+**`Failed to set up chrome ...! Set "PUPPETEER_SKIP_DOWNLOAD" env variable to skip download.`**
+An earlier install left a half-finished Chromium download in `~/.cache/puppeteer`. md2doc ≥ 1.0.3 cleans this automatically; on older versions, clear the cache and retry:
+
+```bash
+rm -rf ~/.cache/puppeteer
+npm install -g @helping-ai-workflow/md2doc
+```
 
 ## Usage
 

package/bin/md2html.js

@@ -14,7 +14,7 @@ function printHelp() {
         `md2${FORMAT} — render Markdown to ${FORMAT.toUpperCase()} (WaveDrom / Mermaid / Graphviz supported)`,
         '',
         'Usage:',
-        `  md2${FORMAT} <input.md> [<input2.md> ...]      # render each to <stem>.${FORMAT} next to source`,
+        `  md2${FORMAT} <input.md> [<input2.md> ...]      # render each to <stem>_gen.${FORMAT} next to source`,
         `  md2${FORMAT} <input.md> --out <path.${FORMAT}>    # explicit output (single-file mode)`,
         `  md2${FORMAT} <input.md> --open                # render then open viewer`,
         `  md2${FORMAT} <input.md> --quiet               # suppress progress output`,
@@ -79,12 +79,23 @@ function parseArgs(argv) {
 }
 
 function deriveOutput(input, format) {
+    // Default suffix matches the workspace Makefile convention: <stem>_gen.<format>.
     const stem = input.replace(/\.md$/i, '');
     if (stem === input) {
-        // No .md extension — append .<format>.
-        return input + '.' + format;
+        // No .md extension — append _gen.<format>.
+        return input + '_gen.' + format;
+    }
+    return stem + '_gen.' + format;
+}
+
+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;
     }
-    return stem + '.' + format;
 }
 
 function openViewer(filePath) {
@@ -94,12 +105,23 @@ function openViewer(filePath) {
         cmd = 'open'; args = [filePath];
     } else if (platform === 'win32') {
         cmd = 'cmd'; args = ['/c', 'start', '""', filePath];
+    } else if (isWSL()) {
+        // Convert the WSL Linux path to a Windows-side path then launch via explorer.exe,
+        // which uses Windows file associations (.html → default browser, .pdf → default reader).
+        const r = spawnSync('wslpath', ['-w', filePath], { encoding: 'utf8' });
+        if (r.status === 0 && r.stdout) {
+            cmd = 'explorer.exe'; args = [r.stdout.trim()];
+        } else {
+            cmd = 'xdg-open'; args = [filePath];
+        }
     } else {
         cmd = 'xdg-open'; args = [filePath];
     }
     const r = spawnSync(cmd, args, { stdio: 'ignore' });
-    if (r.error || r.status !== 0) {
-        process.stderr.write(`warning: could not launch viewer for ${filePath}\n`);
+    // explorer.exe returns exit code 1 on success (Windows quirk via WSL interop),
+    // so a non-zero exit is not necessarily a failure when launching via explorer.
+    if (r.error) {
+        process.stderr.write(`warning: could not launch viewer for ${filePath}: ${r.error.message}\n`);
     }
 }
 
@@ -113,10 +135,10 @@ function main() {
             process.exit(1);
         }
         const output = (args.out !== null) ? args.out : deriveOutput(input, FORMAT);
-        if (!args.quiet) {
-            process.stdout.write(`[${FORMAT.toUpperCase()}] ${input} → ${output}\n`);
-        }
-        const r = spawnSync(process.execPath, [LIB, input, output], { stdio: 'inherit' });
+        // lib/md2doc.js prints its own "[FORMAT] input → output" line; redirect its stdout
+        // when --quiet so neither layer emits progress.
+        const stdio = args.quiet ? ['inherit', 'ignore', 'inherit'] : 'inherit';
+        const r = spawnSync(process.execPath, [LIB, input, output], { stdio });
         if (r.status !== 0) {
             process.stderr.write(`error: render failed for ${input} (exit ${r.status})\n`);
             process.exit(r.status || 1);

package/bin/md2pdf.js

@@ -14,7 +14,7 @@ function printHelp() {
         `md2${FORMAT} — render Markdown to ${FORMAT.toUpperCase()} (WaveDrom / Mermaid / Graphviz supported)`,
         '',
         'Usage:',
-        `  md2${FORMAT} <input.md> [<input2.md> ...]      # render each to <stem>.${FORMAT} next to source`,
+        `  md2${FORMAT} <input.md> [<input2.md> ...]      # render each to <stem>_gen.${FORMAT} next to source`,
         `  md2${FORMAT} <input.md> --out <path.${FORMAT}>    # explicit output (single-file mode)`,
         `  md2${FORMAT} <input.md> --open                # render then open viewer`,
         `  md2${FORMAT} <input.md> --quiet               # suppress progress output`,
@@ -79,11 +79,22 @@ function parseArgs(argv) {
 }
 
 function deriveOutput(input, format) {
+    // Default suffix matches the workspace Makefile convention: <stem>_gen.<format>.
     const stem = input.replace(/\.md$/i, '');
     if (stem === input) {
-        return input + '.' + format;
+        return input + '_gen.' + format;
+    }
+    return stem + '_gen.' + format;
+}
+
+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;
     }
-    return stem + '.' + format;
 }
 
 function openViewer(filePath) {
@@ -93,12 +104,21 @@ function openViewer(filePath) {
         cmd = 'open'; args = [filePath];
     } else if (platform === 'win32') {
         cmd = 'cmd'; args = ['/c', 'start', '""', filePath];
+    } else if (isWSL()) {
+        // Convert the WSL Linux path to a Windows-side path then launch via explorer.exe,
+        // which uses Windows file associations (.html → default browser, .pdf → default reader).
+        const r = spawnSync('wslpath', ['-w', filePath], { encoding: 'utf8' });
+        if (r.status === 0 && r.stdout) {
+            cmd = 'explorer.exe'; args = [r.stdout.trim()];
+        } else {
+            cmd = 'xdg-open'; args = [filePath];
+        }
     } else {
         cmd = 'xdg-open'; args = [filePath];
     }
     const r = spawnSync(cmd, args, { stdio: 'ignore' });
-    if (r.error || r.status !== 0) {
-        process.stderr.write(`warning: could not launch viewer for ${filePath}\n`);
+    if (r.error) {
+        process.stderr.write(`warning: could not launch viewer for ${filePath}: ${r.error.message}\n`);
     }
 }
 
@@ -112,10 +132,10 @@ function main() {
             process.exit(1);
         }
         const output = (args.out !== null) ? args.out : deriveOutput(input, FORMAT);
-        if (!args.quiet) {
-            process.stdout.write(`[${FORMAT.toUpperCase()}] ${input} → ${output}\n`);
-        }
-        const r = spawnSync(process.execPath, [LIB, input, output], { stdio: 'inherit' });
+        // lib/md2doc.js prints its own "[FORMAT] input → output" line; redirect its stdout
+        // when --quiet so neither layer emits progress.
+        const stdio = args.quiet ? ['inherit', 'ignore', 'inherit'] : 'inherit';
+        const r = spawnSync(process.execPath, [LIB, input, output], { stdio });
         if (r.status !== 0) {
             process.stderr.write(`error: render failed for ${input} (exit ${r.status})\n`);
             process.exit(r.status || 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
   "keywords": ["markdown", "html", "pdf", "renderer", "wavedrom", "mermaid", "graphviz"],
   "main": "lib/md2doc.js",
@@ -11,6 +11,7 @@
   "files": [
     "lib/",
     "bin/",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],
@@ -22,6 +23,7 @@
     "puppeteer": "^24.15.0"
   },
   "scripts": {
+    "preinstall": "node scripts/preinstall.js",
     "test": "node test/md2doc.test.js"
   },
   "repository": {

package/scripts/preinstall.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+
+// Remove stale puppeteer browser-cache folders that exist but are missing
+// the actual binary. An interrupted prior download leaves @puppeteer/browsers
+// in a state where it sees the version folder and refuses to redownload,
+// failing puppeteer's postinstall with:
+//   The browser folder (.../chrome/<platform>-<ver>) exists but the
+//   executable (.../chrome-<platform>/chrome) is missing
+// We run before puppeteer's postinstall and clean those husks so the
+// download proceeds fresh.
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const BINARY_NAMES = new Set([
+  'chrome',
+  'chrome.exe',
+  'chrome-headless-shell',
+  'chrome-headless-shell.exe',
+  'Google Chrome for Testing',
+]);
+const MIN_BINARY_BYTES = 1_000_000;
+const MAX_DEPTH        = 4;
+
+function hasBinary(rootDir) {
+  const stack = [[rootDir, 0]];
+  while (stack.length) {
+    const [dir, depth] = stack.pop();
+    if (depth > MAX_DEPTH) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isFile() && BINARY_NAMES.has(ent.name)) {
+        try {
+          if (fs.statSync(full).size >= MIN_BINARY_BYTES) return true;
+        } catch { /* ignore */ }
+      } else if (ent.isDirectory()) {
+        stack.push([full, depth + 1]);
+      }
+    }
+  }
+  return false;
+}
+
+function cleanStaleVersionDirs(parentDir) {
+  if (!fs.existsSync(parentDir)) return;
+  let entries;
+  try { entries = fs.readdirSync(parentDir, { withFileTypes: true }); }
+  catch { return; }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const versionDir = path.join(parentDir, ent.name);
+    if (hasBinary(versionDir)) continue;
+    console.log(`[md2doc preinstall] removing stale puppeteer cache: ${versionDir}`);
+    try { fs.rmSync(versionDir, { recursive: true, force: true }); }
+    catch (e) {
+      console.log(`[md2doc preinstall] failed to remove ${versionDir}: ${e.message}`);
+    }
+  }
+}
+
+const cacheRoot = process.env.PUPPETEER_CACHE_DIR
+  || path.join(os.homedir(), '.cache', 'puppeteer');
+
+cleanStaleVersionDirs(path.join(cacheRoot, 'chrome'));
+cleanStaleVersionDirs(path.join(cacheRoot, 'chrome-headless-shell'));