@helping-ai-workflow/md2doc 1.0.2 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "1.0.2",
+  "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'));