@helping-ai-workflow/md2doc 1.1.1 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support.
 
-Two global CLIs (`md2html`, `md2pdf`) you can call from any directory.
+A single global CLI (`md2doc`) you can call from any directory.
 
 ## Install
 
@@ -43,25 +43,44 @@ npm install -g @helping-ai-workflow/md2doc
 ## Usage
 
 ```bash
-md2html foo.md                     # → foo.html (next to source)
-md2html foo.md bar.md              # batch render
-md2html foo.md --out custom.html   # explicit output (single-file mode)
-md2html foo.md --open              # render then launch viewer
-md2html foo.md --quiet             # suppress progress output
+md2doc foo.md                              # render HTML to OS temp dir, open viewer
+md2doc --pdf foo.md                        # render PDF instead
+md2doc --html --pdf foo.md                 # render both formats
+md2doc *.md                                # batch: each file → temp + open
+
+md2doc foo.md --out bar.html               # write to a specific file (no auto-open)
+md2doc foo.md --out ./build/               # write to ./build/foo.html (no auto-open)
+md2doc *.md --out ./build/                 # batch into ./build/
+md2doc foo.md --out ./build/ --open        # explicit open with --out
 ```
 
-`md2pdf` accepts the same four flags with PDF-output semantics.
+By default, `md2doc` writes to your OS temp directory and launches the platform viewer.
+Pass `--out <path>` to write somewhere specific; doing so disables auto-open unless you
+also pass `--open`.
 
 ### Flags
 
 | Flag | Meaning |
 |---|---|
-| `--out <path>` | Explicit output path. Only valid with exactly one input. |
-| `--open` | Launch the platform viewer (`xdg-open` / `open` / `start`) after render. |
+| `--html` | Render HTML (default if neither `--html` nor `--pdf` is given). |
+| `--pdf` | Render PDF. Combine with `--html` to render both. |
+| `--out <path>` | Output path. Ends with `/` or an existing directory → directory mode. Ends with `.html` / `.pdf` → file mode (single input only). Implies `--no-open` unless `--open` is also passed. |
+| `--open` | Launch the platform viewer (`xdg-open` / `open` / `start`) after render. Default when `--out` is absent. |
+| `--no-open` | Skip the viewer launch. |
 | `--quiet` | Suppress per-file progress messages. |
 | `--version`, `-v` | Print version. |
 | `--help`, `-h` | Print help. |
 
+### Migration from md2html / md2pdf (v1.x → v2.0.0)
+
+| Old | New |
+|---|---|
+| `md2html foo.md` | `md2doc foo.md` |
+| `md2pdf foo.md` | `md2doc --pdf foo.md` |
+| `md2html foo.md --out f.html` | `md2doc foo.md --out f.html` |
+| `md2html foo.md --open` | `md2doc foo.md` (open is default) |
+| `md2html *.md` (output next to source) | `md2doc *.md --out ./build/` (or accept temp output) |
+
 ## Supported diagram types
 
 Embedded in fenced code blocks inside your Markdown:

package/bin/md2doc.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const LIB = path.resolve(__dirname, '..', 'lib', 'md2doc.js');
+const VERSION = require('../package.json').version;
+
+function printHelp() {
+    process.stdout.write([
+        'md2doc — render Markdown to HTML / PDF (WaveDrom / Mermaid / Graphviz supported)',
+        '',
+        'Usage:',
+        '  md2doc <input.md>...                       Render to HTML, write to OS temp dir, open viewer',
+        '  md2doc --pdf <input.md>...                 Render to PDF instead',
+        '  md2doc --html --pdf <input.md>             Render both formats',
+        '  md2doc <input.md> --out <file.html>        Write to a specific file (no auto-open)',
+        '  md2doc <input.md>... --out <dir>/          Write each to <dir>/<stem>.html (no auto-open)',
+        '',
+        'Flags:',
+        '  --html              Render HTML (default if neither --html nor --pdf is given).',
+        '  --pdf               Render PDF.',
+        '  --out <path>        Output path. Ends with \'/\' or existing dir → directory mode.',
+        '                      Ends with .html/.pdf → file mode (single input only).',
+        '                      Implies --no-open unless --open is also passed.',
+        '  --open              Launch the platform viewer after render (default when --out is absent).',
+        '  --no-open           Skip the viewer launch.',
+        '  --quiet             Suppress per-file progress messages.',
+        '  --version, -v       Print version.',
+        '  --help, -h          Print this help.',
+        ''
+    ].join('\n'));
+}
+
+function parseArgs(argv) {
+    const inputs = [];
+    let html = false;
+    let pdf = false;
+    let out = null;
+    let openExplicit = null; // null = unset; true/false = user-specified
+    let quiet = false;
+
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--version' || a === '-v') {
+            process.stdout.write(VERSION + '\n');
+            process.exit(0);
+        }
+        if (a === '--help' || a === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+        if (a === '--html') { html = true; continue; }
+        if (a === '--pdf') { pdf = true; continue; }
+        if (a === '--open') { openExplicit = true; continue; }
+        if (a === '--no-open') { openExplicit = false; continue; }
+        if (a === '--quiet') { quiet = true; continue; }
+        if (a === '--out') {
+            if (out !== null) {
+                process.stderr.write('error: --out specified more than once\n');
+                process.exit(2);
+            }
+            i++;
+            if (i >= argv.length) {
+                process.stderr.write('error: --out requires a value\n');
+                process.exit(2);
+            }
+            out = argv[i];
+            continue;
+        }
+        if (a.startsWith('-')) {
+            process.stderr.write('error: unknown flag ' + a + '\n');
+            process.exit(2);
+        }
+        inputs.push(a);
+    }
+
+    if (inputs.length === 0) {
+        process.stderr.write('error: no input file\n');
+        printHelp();
+        process.exit(2);
+    }
+
+    // Format defaults: neither flag → HTML only.
+    const formats = [];
+    if (html || (!html && !pdf)) formats.push('html');
+    if (pdf) formats.push('pdf');
+
+    // Open default: ON when --out absent, OFF when --out present; user can override either way.
+    let open;
+    if (openExplicit !== null) {
+        open = openExplicit;
+    } else {
+        open = (out === null);
+    }
+
+    return { inputs, formats, out, open, quiet };
+}
+
+function shortHash(absPath) {
+    return crypto.createHash('sha1').update(absPath).digest('hex').slice(0, 6);
+}
+
+function defaultOutputPath(input, format) {
+    const abs = path.resolve(input);
+    const stem = path.basename(input).replace(/\.md$/i, '');
+    const dir = path.join(os.tmpdir(), 'md2doc');
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, stem + '-' + shortHash(abs) + '.' + format);
+}
+
+function classifyOut(outValue) {
+    // Returns { kind: 'dir' | 'file', ext: 'html'|'pdf'|null }
+    if (outValue.endsWith('/') || outValue.endsWith(path.sep)) {
+        return { kind: 'dir', ext: null };
+    }
+    try {
+        if (fs.existsSync(outValue) && fs.statSync(outValue).isDirectory()) {
+            return { kind: 'dir', ext: null };
+        }
+    } catch (_) { /* fall through */ }
+    if (/\.html$/i.test(outValue)) return { kind: 'file', ext: 'html' };
+    if (/\.pdf$/i.test(outValue))  return { kind: 'file', ext: 'pdf' };
+    return { kind: 'ambiguous', ext: null };
+}
+
+function resolveOutputs(args) {
+    const pairs = [];
+    if (args.out === null) {
+        for (const input of args.inputs) {
+            for (const format of args.formats) {
+                pairs.push({ input, format, output: defaultOutputPath(input, format) });
+            }
+        }
+        return pairs;
+    }
+
+    const cls = classifyOut(args.out);
+
+    if (cls.kind === 'ambiguous') {
+        process.stderr.write(
+            'error: --out \'' + args.out + '\' must end with \'/\' to mean a directory ' +
+            'or \'.html\'/\'.pdf\' to mean a file\n'
+        );
+        process.exit(2);
+    }
+
+    if (cls.kind === 'file') {
+        if (args.inputs.length > 1) {
+            process.stderr.write('error: --out file path is only valid with one input\n');
+            process.exit(2);
+        }
+        if (args.formats.length > 1) {
+            process.stderr.write('error: --out file path is not valid when producing both formats\n');
+            process.exit(2);
+        }
+        if (cls.ext !== args.formats[0]) {
+            process.stderr.write(
+                'error: --out \'' + args.out + '\' extension does not match selected format\n'
+            );
+            process.exit(2);
+        }
+        pairs.push({ input: args.inputs[0], format: args.formats[0], output: args.out });
+        return pairs;
+    }
+
+    // cls.kind === 'dir'
+    fs.mkdirSync(args.out, { recursive: true });
+    for (const input of args.inputs) {
+        const stem = path.basename(input).replace(/\.md$/i, '');
+        for (const format of args.formats) {
+            pairs.push({
+                input,
+                format,
+                output: path.join(args.out, stem + '.' + format),
+            });
+        }
+    }
+    return pairs;
+}
+
+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;
+    }
+}
+
+function openViewer(filePath) {
+    const platform = process.platform;
+    let cmd, args;
+    if (platform === 'darwin') {
+        cmd = 'open'; args = [filePath];
+    } else if (platform === 'win32') {
+        cmd = 'cmd'; args = ['/c', 'start', '""', filePath];
+    } else if (isWSL()) {
+        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) {
+        process.stderr.write('warning: could not launch viewer for ' + filePath + ': ' + r.error.message + '\n');
+    }
+}
+
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+
+    for (const input of args.inputs) {
+        if (!fs.existsSync(input)) {
+            process.stderr.write('error: input not found: ' + input + '\n');
+            process.exit(1);
+        }
+    }
+
+    const pairs = resolveOutputs(args);
+    const outputs = [];
+    for (const { input, output } of pairs) {
+        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);
+        }
+        if (!args.quiet) {
+            process.stdout.write(output + '\n');
+        }
+        outputs.push(output);
+    }
+
+    if (args.open) {
+        for (const o of outputs) openViewer(o);
+    }
+}
+
+main();

package/lib/md2doc.js

@@ -412,9 +412,19 @@ ${itemsHtml}
   marked.setOptions({ gfm: true, breaks: false, renderer });
 
   // Pre-process non-standard inline syntax before marked parses
+  const escAttr = (s) => String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
   const mdPre = md
     .replace(/\^([^^]+)\^/g, '<sup>$1</sup>')   // ^a^  → <sup>a</sup>
-    .replace(/~([^~]+)~/g,   '<sub>$1</sub>');   // ~a~  → <sub>a</sub>
+    .replace(/~([^~]+)~/g,   '<sub>$1</sub>')   // ~a~  → <sub>a</sub>
+    .replace(/\[\[([^\]\n]+)\]\]/g, (_, inner) => {  // [[ref-id, §sub]] → clickable citation
+      const body = inner.trim();
+      const slug = body.split(',', 1)[0].trim();
+      return `<a href="#${escAttr(slug)}">[${escAttr(body)}]</a>`;
+    });
 
   bodyHtml = marked.parse(mdPre);
   serializedSections = JSON.stringify(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "1.1.1",
+  "version": "2.0.0",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
   "keywords": [
     "markdown",
@@ -13,8 +13,7 @@
   ],
   "main": "lib/md2doc.js",
   "bin": {
-    "md2html": "bin/md2html.js",
-    "md2pdf": "bin/md2pdf.js"
+    "md2doc": "bin/md2doc.js"
   },
   "files": [
     "lib/",
@@ -32,7 +31,7 @@
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",
-    "test": "node test/md2doc.test.js"
+    "test": "node test/md2doc.test.js && node test/cli.test.js"
   },
   "repository": {
     "type": "git",

package/bin/md2html.js

@@ -1,156 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const path = require('path');
-const fs = require('fs');
-const { spawnSync } = require('child_process');
-
-const FORMAT = 'html';
-const LIB = path.resolve(__dirname, '..', 'lib', 'md2doc.js');
-const VERSION = require('../package.json').version;
-
-function printHelp() {
-    process.stdout.write([
-        `md2${FORMAT} — render Markdown to ${FORMAT.toUpperCase()} (WaveDrom / Mermaid / Graphviz supported)`,
-        '',
-        'Usage:',
-        `  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`,
-        '',
-        'Flags:',
-        '  --out <path>   Explicit output path. Only valid with exactly one input.',
-        '  --open         Launch the platform viewer after render.',
-        '  --quiet        Suppress per-file progress messages.',
-        '  --version, -v  Print version.',
-        '  --help, -h     Print this help.',
-        ''
-    ].join('\n'));
-}
-
-function parseArgs(argv) {
-    const inputs = [];
-    let out = null;
-    let open = false;
-    let quiet = false;
-
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--version' || a === '-v') {
-            process.stdout.write(VERSION + '\n');
-            process.exit(0);
-        }
-        if (a === '--help' || a === '-h') {
-            printHelp();
-            process.exit(0);
-        }
-        if (a === '--out') {
-            if (out !== null) {
-                process.stderr.write('error: --out specified more than once\n');
-                process.exit(2);
-            }
-            i++;
-            if (i >= argv.length) {
-                process.stderr.write('error: --out requires a value\n');
-                process.exit(2);
-            }
-            out = argv[i];
-            continue;
-        }
-        if (a === '--open') { open = true; continue; }
-        if (a === '--quiet') { quiet = true; continue; }
-        if (a.startsWith('-')) {
-            process.stderr.write(`error: unknown flag ${a}\n`);
-            process.exit(2);
-        }
-        inputs.push(a);
-    }
-
-    if (inputs.length === 0) {
-        printHelp();
-        process.exit(2);
-    }
-    if (out !== null && inputs.length !== 1) {
-        process.stderr.write('error: --out is only valid with exactly one input file\n');
-        process.exit(2);
-    }
-    return { inputs, out, open, quiet };
-}
-
-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 _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;
-    }
-}
-
-function openViewer(filePath) {
-    const platform = process.platform;
-    let cmd, args;
-    if (platform === 'darwin') {
-        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' });
-    // 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`);
-    }
-}
-
-function main() {
-    const args = parseArgs(process.argv.slice(2));
-    const outputs = [];
-
-    for (const input of args.inputs) {
-        if (!fs.existsSync(input)) {
-            process.stderr.write(`error: input not found: ${input}\n`);
-            process.exit(1);
-        }
-        const output = (args.out !== null) ? args.out : deriveOutput(input, FORMAT);
-        // 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);
-        }
-        outputs.push(output);
-    }
-
-    if (args.open) {
-        for (const o of outputs) {
-            openViewer(o);
-        }
-    }
-}
-
-main();

package/bin/md2pdf.js

@@ -1,153 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-const path = require('path');
-const fs = require('fs');
-const { spawnSync } = require('child_process');
-
-const FORMAT = 'pdf';
-const LIB = path.resolve(__dirname, '..', 'lib', 'md2doc.js');
-const VERSION = require('../package.json').version;
-
-function printHelp() {
-    process.stdout.write([
-        `md2${FORMAT} — render Markdown to ${FORMAT.toUpperCase()} (WaveDrom / Mermaid / Graphviz supported)`,
-        '',
-        'Usage:',
-        `  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`,
-        '',
-        'Flags:',
-        '  --out <path>   Explicit output path. Only valid with exactly one input.',
-        '  --open         Launch the platform viewer after render.',
-        '  --quiet        Suppress per-file progress messages.',
-        '  --version, -v  Print version.',
-        '  --help, -h     Print this help.',
-        ''
-    ].join('\n'));
-}
-
-function parseArgs(argv) {
-    const inputs = [];
-    let out = null;
-    let open = false;
-    let quiet = false;
-
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--version' || a === '-v') {
-            process.stdout.write(VERSION + '\n');
-            process.exit(0);
-        }
-        if (a === '--help' || a === '-h') {
-            printHelp();
-            process.exit(0);
-        }
-        if (a === '--out') {
-            if (out !== null) {
-                process.stderr.write('error: --out specified more than once\n');
-                process.exit(2);
-            }
-            i++;
-            if (i >= argv.length) {
-                process.stderr.write('error: --out requires a value\n');
-                process.exit(2);
-            }
-            out = argv[i];
-            continue;
-        }
-        if (a === '--open') { open = true; continue; }
-        if (a === '--quiet') { quiet = true; continue; }
-        if (a.startsWith('-')) {
-            process.stderr.write(`error: unknown flag ${a}\n`);
-            process.exit(2);
-        }
-        inputs.push(a);
-    }
-
-    if (inputs.length === 0) {
-        printHelp();
-        process.exit(2);
-    }
-    if (out !== null && inputs.length !== 1) {
-        process.stderr.write('error: --out is only valid with exactly one input file\n');
-        process.exit(2);
-    }
-    return { inputs, out, open, quiet };
-}
-
-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 + '_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;
-    }
-}
-
-function openViewer(filePath) {
-    const platform = process.platform;
-    let cmd, args;
-    if (platform === 'darwin') {
-        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) {
-        process.stderr.write(`warning: could not launch viewer for ${filePath}: ${r.error.message}\n`);
-    }
-}
-
-function main() {
-    const args = parseArgs(process.argv.slice(2));
-    const outputs = [];
-
-    for (const input of args.inputs) {
-        if (!fs.existsSync(input)) {
-            process.stderr.write(`error: input not found: ${input}\n`);
-            process.exit(1);
-        }
-        const output = (args.out !== null) ? args.out : deriveOutput(input, FORMAT);
-        // 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);
-        }
-        outputs.push(output);
-    }
-
-    if (args.open) {
-        for (const o of outputs) {
-            openViewer(o);
-        }
-    }
-}
-
-main();