mdv-live 0.5.5 → 0.5.9

package/bin/mdv.js

@@ -16,66 +16,39 @@ import { parseArgs } from 'node:util';
 import open from 'open';
 
 import { createMdvServer } from '../src/server.js';
+import { resolvePdfOptions, resolveStyle } from '../src/styles/index.js';
 
 const DEFAULT_PORT = 8642;
 const MARP_FRONTMATTER_PATTERN = /^---\s*\n[\s\S]*?marp:\s*true[\s\S]*?\n---/;
 
-const OPTIONS = {
-  port: {
-    type: 'string',
-    short: 'p',
-  },
-  depth: {
-    type: 'string',
-    short: 'd',
-  },
-  'no-browser': {
-    type: 'boolean',
-    default: false
-  },
-  list: {
-    type: 'boolean',
-    short: 'l',
-    default: false
-  },
-  kill: {
-    type: 'boolean',
-    short: 'k',
-    default: false
-  },
-  all: {
-    type: 'boolean',
-    short: 'a',
-    default: false
-  },
-  pdf: {
-    type: 'boolean',
-    default: false
-  },
-  output: {
-    type: 'string',
-    short: 'o',
-  },
-  help: {
-    type: 'boolean',
-    short: 'h',
-    default: false
-  },
-  version: {
-    type: 'boolean',
-    short: 'v',
-    default: false
-  }
+const VIEWER_OPTIONS = {
+  port: { type: 'string', short: 'p' },
+  depth: { type: 'string', short: 'd' },
+  'no-browser': { type: 'boolean', default: false },
+  list: { type: 'boolean', short: 'l', default: false },
+  kill: { type: 'boolean', short: 'k', default: false },
+  all: { type: 'boolean', short: 'a', default: false },
+  help: { type: 'boolean', short: 'h', default: false },
+  version: { type: 'boolean', short: 'v', default: false },
+};
+
+const CONVERT_OPTIONS = {
+  input: { type: 'string', short: 'i' },
+  output: { type: 'string', short: 'o' },
+  style: { type: 'string', short: 's' },
+  'pdf-options': { type: 'string' },
+  help: { type: 'boolean', short: 'h', default: false },
 };
 
 /**
- * Display help message
+ * Display viewer help message
  */
 function showHelp() {
   console.log(`
 MDV - Markdown Viewer with file tree + live preview + Marp support
 
 Usage: mdv [options] [path]
+       mdv convert -i <file.md> -o <file.pdf>
 
 Arguments:
   path                Directory or file path to view (default: current directory)
@@ -90,22 +63,42 @@ Server Management:
   -k, --kill [PID]    Stop server (-k -a for all, -k <PID> for specific)
   -a, --all           Use with -k to stop all servers
 
-PDF Conversion:
-  --pdf               Convert markdown file to PDF
-  -o, --output <file> Output PDF file path
-
 Other:
   -h, --help          Show this help message
   -v, --version       Show version number
 
 Examples:
-  mdv                    Start viewer in current directory
-  mdv /path/to/dir       Start viewer in specified directory
-  mdv README.md          Open specific file
-  mdv --pdf README.md    Convert markdown to PDF
-  mdv -p 3000            Start on port 3000
-  mdv -l                 List running servers
-  mdv -k -a              Stop all servers
+  mdv                          Start viewer in current directory
+  mdv /path/to/dir             Start viewer in specified directory
+  mdv README.md                Open specific file
+  mdv convert -i s.md -o s.pdf Convert markdown to PDF
+  mdv -p 3000                  Start on port 3000
+  mdv -l                       List running servers
+  mdv -k -a                    Stop all servers
+`);
+}
+
+/**
+ * Display convert subcommand help message
+ */
+function showConvertHelp() {
+  console.log(`
+MDV convert - Convert markdown to PDF
+
+Usage: mdv convert -i <input.md> -o <output.pdf> [options]
+
+Options:
+  -i, --input <file>    Input markdown file (.md or .markdown)
+  -o, --output <file>   Output PDF file (default: same name as input)
+  -s, --style <preset>  Built-in preset or custom CSS file path
+                        Built-in presets: default
+  --pdf-options <file>  JSON file with Puppeteer PDF options
+  -h, --help            Show this help message
+
+Examples:
+  mdv convert -i slide.md -o slide.pdf
+  mdv convert -i README.md -s ./src/styles/report.example.css --pdf-options ./src/styles/report.pdf-options.example.json
+  mdv convert -i doc.md -o out.pdf -s ./my-style.css
 `);
 }
 
@@ -244,13 +237,15 @@ function isMarpFile(content) {
 
 /**
  * Convert markdown to PDF using appropriate tool
- * - Marp slides: use marp-cli
- * - Regular markdown: use md-to-pdf for A4 document format
+ * - Marp slides: use marp-cli (style option ignored)
+ * - Regular markdown: use md-to-pdf with optional style preset
  * @param {string} inputPath - Input markdown file path
  * @param {string} [outputPath] - Output PDF file path
+ * @param {string} [styleArg] - Style preset name or CSS file path
+ * @param {string} [pdfOptionsPath] - JSON file with Puppeteer PDF options
  * @returns {Promise<number>} Exit code (0 = success, 1 = error)
  */
-async function convertToPdf(inputPath, outputPath) {
+async function convertToPdf(inputPath, outputPath, styleArg, pdfOptionsPath) {
   const resolved = path.resolve(inputPath);
 
   const fileExists = await fs.access(resolved).then(() => true).catch(() => false);
@@ -275,7 +270,20 @@ async function convertToPdf(inputPath, outputPath) {
   if (isMarp) {
     return convertMarpToPdf(resolved, finalOutput);
   }
-  return convertMarkdownToPdf(resolved, finalOutput);
+
+  let styleConfig;
+  try {
+    styleConfig = await resolveStyle(styleArg);
+    styleConfig = {
+      ...styleConfig,
+      pdfOptions: await resolvePdfOptions(pdfOptionsPath, styleConfig.pdfOptions),
+    };
+  } catch {
+    console.error(`Error: Style or PDF options not found: ${styleArg || pdfOptionsPath}`);
+    return 1;
+  }
+
+  return convertMarkdownToPdf(resolved, finalOutput, styleConfig);
 }
 
 /**
@@ -299,20 +307,35 @@ async function convertMarpToPdf(inputPath, outputPath) {
 }
 
 /**
- * Convert regular markdown to PDF using md-to-pdf (A4 format)
+ * Convert regular markdown to PDF using md-to-pdf
  * @param {string} inputPath - Resolved input file path
  * @param {string} outputPath - Resolved output file path
+ * @param {import('../src/styles/index.js').StyleConfig} styleConfig - Style preset
  * @returns {Promise<number>} Exit code
  */
-async function convertMarkdownToPdf(inputPath, outputPath) {
+async function convertMarkdownToPdf(inputPath, outputPath, styleConfig) {
   console.log('Converting as document (A4 portrait)...');
 
   try {
-    const pdfOptions = '{"format":"A4","margin":{"top":"20mm","right":"20mm","bottom":"20mm","left":"20mm"}}';
-    execFileSync('npx', ['md-to-pdf', inputPath, '--pdf-options', pdfOptions], {
+    const args = ['md-to-pdf', inputPath, '--pdf-options', JSON.stringify(styleConfig.pdfOptions)];
+    const stylesheetPaths = styleConfig.stylesheets ?? (styleConfig.stylesheet ? [styleConfig.stylesheet] : []);
+
+    for (const stylesheetPath of stylesheetPaths) {
+      args.push('--stylesheet', stylesheetPath);
+    }
+
+    if (styleConfig.highlightStyle) {
+      args.push('--highlight-style', styleConfig.highlightStyle);
+    }
+
+    if (styleConfig.css) {
+      args.push('--css', styleConfig.css);
+    }
+
+    execFileSync('npx', args, {
       encoding: 'utf-8',
       stdio: 'inherit',
-      cwd: path.dirname(inputPath)
+      cwd: path.dirname(inputPath),
     });
 
     // md-to-pdf outputs to same directory with .pdf extension
@@ -431,15 +454,34 @@ async function startViewer(targetPath, startPort, openBrowser, depth) {
 }
 
 /**
- * Parse command line arguments safely
+ * Parse arguments for the convert subcommand
  * @returns {{values: object, positionals: string[]}}
  */
-function parseCommandLineArgs() {
+function parseConvertArgs() {
   try {
     return parseArgs({
-      options: OPTIONS,
+      args: process.argv.slice(3), // skip node, mdv.js, "convert"
+      options: CONVERT_OPTIONS,
+      allowPositionals: false,
+      strict: false,
+    });
+  } catch (err) {
+    console.error('Error parsing arguments:', err.message);
+    showConvertHelp();
+    process.exit(1);
+  }
+}
+
+/**
+ * Parse viewer command line arguments safely
+ * @returns {{values: object, positionals: string[]}}
+ */
+function parseViewerArgs() {
+  try {
+    return parseArgs({
+      options: VIEWER_OPTIONS,
       allowPositionals: true,
-      strict: false
+      strict: false,
     });
   } catch (err) {
     console.error('Error parsing arguments:', err.message);
@@ -448,11 +490,38 @@ function parseCommandLineArgs() {
   }
 }
 
+/**
+ * Handle the convert subcommand
+ */
+async function runConvert() {
+  const { values } = parseConvertArgs();
+
+  if (values.help) {
+    showConvertHelp();
+    process.exit(0);
+  }
+
+  if (!values.input) {
+    console.error('Error: -i <file.md> is required');
+    showConvertHelp();
+    process.exit(1);
+  }
+
+  process.exit(await convertToPdf(values.input, values.output, values.style, values['pdf-options']));
+}
+
 /**
  * Main entry point
  */
 async function main() {
-  const { values, positionals } = parseCommandLineArgs();
+  const subcommand = process.argv[2];
+
+  if (subcommand === 'convert') {
+    await runConvert();
+    return;
+  }
+
+  const { values, positionals } = parseViewerArgs();
 
   if (values.help) {
     showHelp();
@@ -477,15 +546,6 @@ async function main() {
     process.exit(killServers(pid, values.all));
   }
 
-  if (values.pdf) {
-    const inputPath = positionals[0];
-    if (!inputPath) {
-      console.error('Error: --pdf requires a markdown file path');
-      process.exit(1);
-    }
-    process.exit(await convertToPdf(inputPath, values.output));
-  }
-
   // Default: start viewer
   const targetPath = positionals[0] || '.';
   const port = parseInt(values.port, 10) || DEFAULT_PORT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdv-live",
-  "version": "0.5.5",
+  "version": "0.5.9",
   "description": "Markdown Viewer - File tree + Live preview + Marp support + Hot reload",
   "main": "src/server.js",
   "bin": {
@@ -45,16 +45,17 @@
     "LICENSE"
   ],
   "dependencies": {
-    "express": "^4.21.2",
-    "ws": "^8.18.0",
+    "@marp-team/marp-core": "^4.0.0",
     "chokidar": "^4.0.3",
+    "express": "^4.21.2",
+    "highlight.js": "^11.10.0",
     "markdown-it": "^14.1.0",
     "markdown-it-task-lists": "^2.1.1",
-    "@marp-team/marp-core": "^4.0.0",
-    "highlight.js": "^11.10.0",
-    "open": "^10.1.0",
+    "md-to-pdf": "^5.2.5",
     "mime-types": "^2.1.35",
-    "multer": "^1.4.5-lts.1"
+    "multer": "^1.4.5-lts.1",
+    "open": "^10.1.0",
+    "ws": "^8.18.0"
   },
   "optionalDependencies": {
     "@marp-team/marp-cli": "^4.0.3"

package/src/api/marpNote/guards.js

@@ -0,0 +1,79 @@
+/**
+ * Common guards / preconditions for the marpNote endpoints.
+ *
+ * Each function returns an Error (with `.code`) on rejection or `null` on
+ * success. The caller then uses `sendError(res, err)` from utils/errors.js.
+ */
+
+import { mkError } from '../../utils/errors.js';
+import { validateNoteText } from '../../rendering/marpNoteWriter.js';
+
+const MAX_SLIDE_INDEX = 1000;
+
+export function buildAllowedHosts(port) {
+  return [`localhost:${port}`, `127.0.0.1:${port}`];
+}
+
+/** Origin / Sec-Fetch-Site judgement (CSRF / DNS rebinding defence). */
+export function checkOrigin(req, allowedHosts) {
+  const origin = req.get('Origin');
+  if (origin) {
+    for (const host of allowedHosts) {
+      if (origin === `http://${host}`) return null;
+    }
+    return mkError('ORIGIN_REJECTED', 'origin not allowed');
+  }
+  if (req.get('Sec-Fetch-Site') === 'same-origin') return null;
+  return mkError('ORIGIN_REJECTED', 'origin not allowed');
+}
+
+export function checkHost(req, allowedHosts) {
+  const host = req.get('Host');
+  if (host && allowedHosts.includes(host)) return null;
+  return mkError('ORIGIN_REJECTED', 'host header not allowed');
+}
+
+export function checkJsonContent(req) {
+  const ct = (req.get('Content-Type') || '').split(';')[0].trim().toLowerCase();
+  if (ct === 'application/json') return null;
+  return mkError('UNSUPPORTED_MEDIA_TYPE', 'Content-Type must be application/json');
+}
+
+export function checkIfMatch(req) {
+  if (req.get('If-Match')) return null;
+  return mkError('IF_MATCH_REQUIRED', 'If-Match header required');
+}
+
+export function parseSlideIndex(req) {
+  const n = Number(req.params.slideIndex);
+  if (!Number.isInteger(n) || n < 0 || n >= MAX_SLIDE_INDEX) {
+    return { error: mkError('OUT_OF_RANGE', 'slideIndex out of range') };
+  }
+  return { value: n };
+}
+
+export function sanitiseRelativePath(decoded) {
+  // Express already decoded :encodedPath route param; do not decode again.
+  if (typeof decoded !== 'string') return null;
+  if (decoded.length === 0 || decoded.length > 1024) return null;
+  if (decoded.includes('\0')) return null;
+  return decoded;
+}
+
+/** Pull and validate the `note` field from the request body. */
+export function extractNote(req) {
+  const body = req.body;
+  if (!body || typeof body !== 'object') {
+    return { error: mkError('INVALID_NOTE', 'body must be JSON object') };
+  }
+  if (!Object.prototype.hasOwnProperty.call(body, 'note')) {
+    return { error: mkError('INVALID_NOTE', 'note required') };
+  }
+  const note = body.note;
+  if (typeof note !== 'string') {
+    return { error: mkError('INVALID_NOTE', 'note must be string') };
+  }
+  const reason = validateNoteText(note);
+  if (reason) return { error: mkError('INVALID_NOTE', reason) };
+  return { value: note };
+}

package/src/api/marpNote/handleGet.js

@@ -0,0 +1,65 @@
+/**
+ * GET /api/marp/decks/:encodedPath  — read-only deck snapshot.
+ */
+
+import { parseDeck, isMarp, renderDeck } from '../../rendering/marpitAdapter.js';
+import { analyseSource } from '../../utils/lineMath.js';
+import { mkError, sendError } from '../../utils/errors.js';
+import { makeEtag } from '../../utils/etag.js';
+import { checkHost, sanitiseRelativePath } from './guards.js';
+import { readDeckSafely } from './readDeck.js';
+
+export function makeGetHandler({ rootDir, allowedHosts }) {
+  return async function handleGet(req, res) {
+    const hostErr = checkHost(req, allowedHosts);
+    if (hostErr) return sendError(res, hostErr);
+    res.setHeader('Cache-Control', 'no-store');
+
+    const rel = sanitiseRelativePath(req.params.encodedPath);
+    if (!rel) return sendError(res, mkError('PATH_INVALID', 'invalid path'));
+
+    let deck;
+    try {
+      deck = await readDeckSafely(rootDir(), rel);
+    } catch (err) {
+      if (err.code === 'PATH_INVALID' || err.code === 'NOT_FOUND') return sendError(res, err);
+      console.error('marpNote GET read error:', err);
+      return sendError(res, mkError('READ_FAILED', 'read failed', { cause: err }));
+    }
+
+    if (!isMarp(deck.rawSource)) {
+      return sendError(res, mkError('NOT_MARP', 'not a Marp file'));
+    }
+
+    const lineInfo = analyseSource(deck.rawSource);
+    const etag = makeEtag(deck.rawSource);
+
+    let parsed;
+    try {
+      parsed = parseDeck(deck.rawSource);
+    } catch (err) {
+      // Adapter contract broken — degrade to read-only (etag null).
+      return res.json({
+        ok: true,
+        degraded: true,
+        etag: null,
+        slideCount: 0,
+        notes: [],
+        notesMultiplicity: [],
+        lineEnding: lineInfo.lineEnding,
+        hasBom: lineInfo.hasBom
+      });
+    }
+
+    const { notes } = renderDeck(deck.rawSource);
+    return res.json({
+      ok: true,
+      etag,
+      slideCount: parsed.slideCount,
+      notes,
+      notesMultiplicity: parsed.notesMultiplicity,
+      lineEnding: lineInfo.lineEnding,
+      hasBom: lineInfo.hasBom
+    });
+  };
+}

package/src/api/marpNote/handlePut.js

@@ -0,0 +1,162 @@
+/**
+ * PUT /api/marp/decks/:encodedPath/slides/:slideIndex/note
+ *
+ * Optimistic locking via If-Match (sha256 etag) + per-path async mutex
+ * for read-check-write atomicity within this process.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { parseDeck, isMarp, renderDeck } from '../../rendering/marpitAdapter.js';
+import { rewriteSlideNote } from '../../rendering/marpNoteWriter.js';
+import { analyseSource } from '../../utils/lineMath.js';
+import { atomicWrite } from '../../utils/atomicWrite.js';
+import { mkError, sendError } from '../../utils/errors.js';
+import { makeEtag } from '../../utils/etag.js';
+import { withLock } from '../../concurrency/pathLock.js';
+import {
+  checkHost, checkOrigin, checkJsonContent, checkIfMatch,
+  parseSlideIndex, sanitiseRelativePath, extractNote
+} from './guards.js';
+import { readDeckSafely } from './readDeck.js';
+
+export function makePutHandler({ rootDir, allowedHosts }) {
+  return async function handlePut(req, res) {
+    const guards = [
+      checkHost(req, allowedHosts),
+      checkOrigin(req, allowedHosts),
+      checkJsonContent(req),
+      checkIfMatch(req)
+    ];
+    for (const err of guards) if (err) return sendError(res, err);
+
+    const idx = parseSlideIndex(req);
+    if (idx.error) return sendError(res, idx.error);
+    const rel = sanitiseRelativePath(req.params.encodedPath);
+    if (!rel) return sendError(res, mkError('PATH_INVALID', 'invalid path'));
+    const noteIn = extractNote(req);
+    if (noteIn.error) return sendError(res, noteIn.error);
+
+    const ifMatch = req.get('If-Match');
+
+    // Resolve realpath BEFORE acquiring the lock so requests against the
+    // same file (via different relative paths) share the same lock key.
+    let earlyDeck;
+    try {
+      earlyDeck = await readDeckSafely(rootDir(), rel);
+    } catch (err) {
+      if (err.code === 'PATH_INVALID' || err.code === 'NOT_FOUND') return sendError(res, err);
+      console.error('marpNote PUT read error:', err);
+      return sendError(res, mkError('READ_FAILED', 'read failed', { cause: err }));
+    }
+
+    // Trampoline: handle the realpath-retarget retry OUTSIDE of any
+    // existing lock. If we re-acquired a new lock while still holding the
+    // old one, two opposite retargets could deadlock. Instead we let the
+    // first attempt return a sentinel, release the old lock by exiting
+    // its withLock callback, then re-acquire on the new realpath.
+    let attemptDeck = earlyDeck;
+    for (let i = 0; i < 2; i++) {
+      const result = await withLock(attemptDeck.realPath, () =>
+        performNoteUpdate({
+          req, res, rootDir, rel,
+          slideIndex: idx.value,
+          note: noteIn.value,
+          ifMatch,
+          earlyDeck: attemptDeck
+        })
+      );
+      if (!result || !result.retargetTo) return result;
+      attemptDeck = result.retargetTo;
+    }
+    return sendError(res, mkError('PATH_INVALID', 'realpath unstable across retries'));
+  };
+}
+
+async function performNoteUpdate({ req, res, rootDir, rel, slideIndex, note, ifMatch, earlyDeck }) {
+  // Re-read inside the lock so the etag check sees writes by predecessors.
+  let deck;
+  try {
+    deck = await readDeckSafely(rootDir(), rel);
+  } catch (err) {
+    if (err.code === 'PATH_INVALID' || err.code === 'NOT_FOUND') return sendError(res, err);
+    console.error('marpNote PUT re-read error:', err);
+    return sendError(res, mkError('READ_FAILED', 'read failed', { cause: err }));
+  }
+
+  if (!isMarp(deck.rawSource)) {
+    return sendError(res, mkError('NOT_MARP', 'not a Marp file'));
+  }
+
+  // If the symlink target changed between pre-lock and in-lock reads, the
+  // mutex we hold doesn't cover the deck we'd write. Return a sentinel so
+  // the caller can release THIS lock first and re-acquire on the new
+  // realpath (preventing nested-lock deadlocks under opposite retargets).
+  if (deck.realPath !== earlyDeck.realPath) {
+    return { retargetTo: deck };
+  }
+
+  const currentEtag = makeEtag(deck.rawSource);
+  if (ifMatch !== currentEtag) {
+    return res.status(412).json({ ok: false, code: 'STALE', currentEtag });
+  }
+
+  let parsed;
+  try {
+    parsed = parseDeck(deck.rawSource);
+  } catch (err) {
+    return sendError(res, mkError('NOT_PARSEABLE', 'failed to parse Marp deck', { cause: err }));
+  }
+
+  const lineInfo = analyseSource(deck.rawSource);
+  let result;
+  try {
+    result = rewriteSlideNote(deck.rawSource, slideIndex, note, parsed, lineInfo);
+  } catch (err) {
+    return sendError(res, err.code ? err : mkError('WRITE_FAILED', err.message, { cause: err }));
+  }
+
+  // Defensive realpath re-resolve (TOCTOU best-effort).
+  // Compare against the realpath observed by the IN-LOCK re-read (`deck`),
+  // NOT the pre-lock read (`earlyDeck`). Otherwise a swap that happens
+  // between the pre-lock and in-lock reads, then reverts before this
+  // check, would slip past — and we'd write contents parsed from the
+  // wrong file into the original path.
+  let realAtWrite;
+  try {
+    realAtWrite = await fs.realpath(path.resolve(rootDir(), rel));
+  } catch (err) {
+    console.error('marpNote PUT realpath at write:', err);
+    return sendError(res, mkError('WRITE_FAILED', 'realpath failed', { cause: err }));
+  }
+  if (realAtWrite !== deck.realPath) {
+    return sendError(res, mkError('PATH_INVALID', 'path resolution changed during request'));
+  }
+
+  try {
+    await atomicWrite(realAtWrite, result.source, deck.stat);
+  } catch (err) {
+    return sendError(res, err.code ? err : mkError('WRITE_FAILED', err.message, { cause: err }));
+  }
+
+  // Re-parse so the client refreshes notes / notesMultiplicity / etag in
+  // one round-trip (no need to wait for the watcher event).
+  let newParsed;
+  try {
+    newParsed = parseDeck(result.source);
+  } catch (err) {
+    return sendError(res, mkError('NOT_PARSEABLE', 'failed to re-parse after rewrite', { cause: err }));
+  }
+  const rendered = renderDeck(result.source);
+
+  return res.json({
+    ok: true,
+    etag: makeEtag(result.source),
+    normalizedNote: note,
+    slideCount: newParsed.slideCount,
+    notes: rendered.notes,
+    notesMultiplicity: newParsed.notesMultiplicity,
+    source: result.source
+  });
+}