@helping-ai-workflow/md2doc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 helping-ai-workflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @helping-ai-workflow/md2doc
+
+> Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support.
+
+Two global CLIs (`md2html`, `md2pdf`) you can call from any directory.
+
+## Install
+
+```bash
+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.
+
+## 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
+```
+
+`md2pdf` accepts the same four flags with PDF-output semantics.
+
+### 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. |
+| `--quiet` | Suppress per-file progress messages. |
+| `--version`, `-v` | Print version. |
+| `--help`, `-h` | Print help. |
+
+## Supported diagram types
+
+Embedded in fenced code blocks inside your Markdown:
+
+````markdown
+```mermaid
+graph LR
+A --> B
+```
+
+```wavedrom
+{ "signal": [...] }
+```
+
+```dot
+digraph G { A -> B }
+```
+````
+
+Diagrams render directly in the output (HTML or PDF).
+
+## Why a global CLI
+
+Multiple repos used to ship copies of this script. They drifted. This package centralises the renderer so every repo references the same version. See [`docs/why.md`](https://github.com/helping-ai-workflow/md2doc) for background.
+
+## Licence
+
+MIT.

package/bin/md2html.js

@@ -0,0 +1,134 @@
+#!/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>.${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) {
+    const stem = input.replace(/\.md$/i, '');
+    if (stem === input) {
+        // No .md extension — append .<format>.
+        return input + '.' + format;
+    }
+    return stem + '.' + format;
+}
+
+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 {
+        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`);
+    }
+}
+
+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);
+        if (!args.quiet) {
+            process.stdout.write(`[${FORMAT.toUpperCase()}] ${input} → ${output}\n`);
+        }
+        const r = spawnSync(process.execPath, [LIB, input, output], { stdio: 'inherit' });
+        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

@@ -0,0 +1,133 @@
+#!/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>.${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) {
+    const stem = input.replace(/\.md$/i, '');
+    if (stem === input) {
+        return input + '.' + format;
+    }
+    return stem + '.' + format;
+}
+
+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 {
+        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`);
+    }
+}
+
+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);
+        if (!args.quiet) {
+            process.stdout.write(`[${FORMAT.toUpperCase()}] ${input} → ${output}\n`);
+        }
+        const r = spawnSync(process.execPath, [LIB, input, output], { stdio: 'inherit' });
+        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();