mdv-live 0.5.5 → 0.5.8

package/CHANGELOG.md

@@ -5,6 +5,108 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.8] - 2026-05-08
+
+### Fixed
+
+- **Symlink TOCTOU on note auto-save** (codex-loop で 4 round 連鎖修正):
+  - 旧コードの TOCTOU guard が `earlyDeck.realPath` (lock 取得前) と比較
+    していた → 進入後 swap、戻し、書き込みで別ファイル読み出しが original
+    path に書ける race を塞ぐため `deck.realPath` (in-lock) と比較に修正
+  - in-lock で realpath が変わったら mutex 範囲外の書込みになる →
+    detection を入れて再 lock 取得
+  - 再 lock 取得を server-side 自動 retry で実装 (client は STALE 以外を
+    terminal 扱いするため)
+  - retarget retry の入れ子 lock が opposite retarget で deadlock し得る
+    → trampoline で **outer lock 解放後に新 realpath を取得**
+
+### Added
+
+- TOCTOU 正常系の API regression test
+- SaveQueue coalesce/serialize/dropPath/例外耐性 5 件
+- Sec-Fetch-Site=same-origin の B 受理パス + cross-site 拒否
+
+### Architecture (refactor)
+
+- `src/api/marpNote.js` orchestration を 38 行に。実装は `src/api/marpNote/`
+  配下の `guards.js` / `readDeck.js` / `handleGet.js` / `handlePut.js` に分割
+- `src/static/lib/saveQueue.js` (per-deck queue + per-slide coalesce、純 JS)
+- `src/static/lib/tabRegistry.js` (tab close hook → メモリリーク解消)
+- `src/static/lib/apiClient.js` を deck/file/tree/info/pdf 用に拡張、
+  app.js の fetch 直叩きを 13 → 2 (WebSocket / /raw/ のみ残存)
+- `src/concurrency/pathLock.js`: promise-chain ベースの正しい mutex
+  (旧 naive Map 実装の thundering-herd race を排除)
+- `src/utils/errors.js`: mkError + ERROR_STATUS テーブル + sendError SSOT
+- `src/utils/etag.js`: ETag 計算 SSOT
+- placeholder を CSS pseudo-element 化 (`:empty::before`) で
+  contenteditable に placeholder text が混入する罠を構造的に解消
+- STALE 通知時に編集テキストを localStorage に自動退避
+
+### Tests
+
+- 222 → **236 件 (+14)**、全 PASS
+
+## [0.5.7] - 2026-05-08
+
+### Added
+
+- **Presenter View** (Marp スピーカーノート別ウィンドウ表示・編集)
+  - P キー (Cmd/Ctrl 修飾なし) または Marp ナビボタンで起動
+  - Current / Next スライド + Speaker Notes + 経過タイマーを並列表示
+  - パネルサイズはドラッグハンドルで変更可能 (localStorage 永続化)
+  - BroadcastChannel `mdv-marp-presenter` でメイン⇄presenter 双方向同期
+- **スピーカーノートの自動保存**: presenter ノートパネルをクリック→編集→
+  800ms デバウンスでサーバへ PUT。ソース markdown の HTML コメントを書き換え
+- **`/api/marp/decks/:path` エンドポイント** (GET/PUT/OPTIONS)
+  - **ETag 楽観ロック** (`sha256:`) で外部編集との衝突検出
+  - **per-path 非同期 mutex** で同時 PUT を直列化
+  - **Multi-note Guard**: 1 slide に複数ノートがある場合は read-only
+  - **CSRF**: Origin + Sec-Fetch-Site + Content-Type 厳密検証
+  - **PNA preflight 拒否** (localhost 同一オリジン要求)
+  - **128KB body limit + 専用 413 ハンドラ** で情報漏洩防止
+
+### Architecture
+
+- Marp スライド範囲・ノート位置の特定を **Marpit token** に委譲する
+  `marpitAdapter` を新設。regex 再実装の脆弱性を構造的に解消
+- `validatePathReal` + `O_NOFOLLOW` + realpath 二重解決で symlink swap
+  best-effort 防御
+- `atomicWrite` で `O_EXCL` temp + chmod EPERM 限定 + EXDEV 二段 rename +
+  uid+mtime sweep
+- BOM/CRLF/CR/UTF-8 surrogate pair 安全な行↔バイト変換ヘルパに集約
+- 共通 error コード/HTTP status マッピングを `utils/errors.js` に SSOT 化
+- promise-chain ベースの正しい mutex (`concurrency/pathLock.js`) で
+  thundering-herd race を排除
+- HTTP client / BroadcastChannel 名 / message schema を専用ライブラリに分離
+- セキュリティ脆弱性 5 件 (basic-ftp / ip-address / postcss) を `npm audit fix`
+
+### Tests
+
+- 既存 119 → **228 件 (+109)** すべて PASS
+- 性能: 500 slides / 155 KiB ファイルで parseDeck+rewrite 86ms
+
+## [0.5.6] - 2026-04-27
+
+### Added
+
+- Markdown PDF変換用の `mdv convert` サブコマンドを追加
+- `-s <css-file>` によるPDF変換用CSS指定を追加
+- `--pdf-options <json-file>` によるPuppeteer PDF options指定を追加
+- Web UIのStyleパネルを追加
+  - CSSファイルパスを指定可能
+  - PDF options JSONファイルパスを指定可能
+  - 指定CSSをMarkdownプレビューに反映
+  - `Clear` でスタイル指定を解除可能
+- 通常MarkdownのWeb UI PDF exportを `md-to-pdf` に対応
+- PDFスタイル指定のサンプルを追加
+  - `src/styles/report.example.css`
+  - `src/styles/report.pdf-options.example.json`
+
+### Changed
+
+- PDF出力設定をCSSとPDF options JSONに分離
+- Marp PDF出力は従来どおりMarp CLIを使用し、通常Markdown PDF出力のみ `md-to-pdf` を使用
+
 ## [0.5.5] - 2026-04-05
 
 ### Fixed

package/README.md

@@ -10,16 +10,18 @@
 - 📁 左側にフォルダツリー表示（遅延読み込み対応）
 - 📄 Markdownをリアルタイムレンダリング
 - 🎬 **Marp完全対応**（公式テーマ・ディレクティブ・数式）
+- 🎤 **Presenter View**（スピーカーノート別ウィンドウ・自動保存・タイマー） — `P` キーで起動
 - 🔄 ファイル更新時に自動リロード（WebSocket）
 - 🎨 シンタックスハイライト（highlight.js）
 - 📊 Mermaid図のレンダリング
 - 🌙 ダーク/ライトテーマ切り替え
 - ✏️ インラインエディタ（Cmd+E）
 - ✅ タスクリスト（チェックボックス）対応
-- 📥 PDF出力（Cmd+P）
+- 📥 PDF出力（Cmd+P / CLI convert）
+- 🎛️ PDF用CSS・PDF options指定（CLI / Web UI）
 - 🎬 動画/音声ストリーミング再生（Range Request対応）
 - 📤 ファイルアップロード（ドラッグ&ドロップ）
-- 🔒 セキュリティ強化（パストラバーサル防止）
+- 🔒 セキュリティ強化（パストラバーサル防止 + ETag 楽観ロック + CSRF 防御）
 
 ## Installation
 
@@ -59,13 +61,59 @@ mdv -k 12345
 mdv -k -a
 
 # PDFに変換
-mdv --pdf slide.md
-mdv --pdf slide.md -o output.pdf
+mdv convert -i report.md -o report.pdf
+
+# PDFに変換（CSSとPDF optionsを指定）
+mdv convert \
+  -i report.md \
+  -o report.pdf \
+  -s ./src/styles/report.example.css \
+  --pdf-options ./src/styles/report.pdf-options.example.json
 
 # バージョン表示
 mdv -v
 ```
 
+## PDF Export
+
+Markdown ファイルは CLI または Web UI から PDF に変換できます。
+
+### CLI
+
+```bash
+mdv convert -i input.md -o output.pdf
+```
+
+CSS を指定する場合は `-s` に CSS ファイルパスを渡します。
+
+```bash
+mdv convert \
+  -i input.md \
+  -o output.pdf \
+  -s ./src/styles/report.example.css
+```
+
+`printBackground` や余白などの PDF 生成オプションは、CSS と分離して JSON ファイルで指定できます。
+
+```bash
+mdv convert \
+  -i input.md \
+  -o output.pdf \
+  -s ./src/styles/report.example.css \
+  --pdf-options ./src/styles/report.pdf-options.example.json
+```
+
+`src/styles/report.example.css` と `src/styles/report.pdf-options.example.json` はサンプルです。必要に応じて任意の CSS / JSON ファイルを指定してください。
+
+### Web UI
+
+ビューア上部の `Style` から以下を指定できます。
+
+- CSS ファイルパス
+- PDF options JSON ファイルパス
+
+CSS は Markdown プレビューにも反映されます。指定を解除する場合は `Clear` を押してください。
+
 ### ポート自動増分
 
 ポートが使用中の場合、自動的に次のポート番号を試します。
@@ -118,6 +166,8 @@ paginate: true
 
 内容...
 
+<!-- スピーカーノート (Presenter View で表示・編集できます) -->
+
 ---
 
 # 次のスライド
@@ -129,9 +179,55 @@ paginate: true
 ### サポートされるMarp機能
 
 - **テーマ**: default, gaia, uncover
-- **ディレクティブ**: paginate, header, footer, backgroundColor, etc.
+- **ディレクティブ**: paginate, header, footer, backgroundColor, lang, headingDivider, etc.
+- **headingDivider**: scalar (`headingDivider: 2`) / inline-array (`[1, 2]`) / block-array 全形式
+- **スライド区切り**: `---` / `***` / `___` (CommonMark thematic break 全形式)
 - **画像構文**: `![bg]`, `![w:100px]`, `![bg left]`
 - **数式**: KaTeX対応（インライン `$...$`、ブロック `$$...$$`）
+- **スピーカーノート**: HTML コメント (`<!-- ... -->`) で記述
+
+## Presenter View
+
+Marp ファイルを開いた状態で **`P` キー** を押すと、別ウィンドウで登壇者ビューが起動します。
+
+### 機能
+
+- **3 ペインレイアウト**: 現在のスライド (大) / 次のスライド (小) / スピーカーノート
+- **経過タイマー**: 上部に MM:SS 表示、Reset ボタンで 0 にリセット
+- **ノート編集 → 自動保存**: ノートパネルをクリックして編集 → 800ms デバウンスで markdown ソースのコメントを書き戻し
+- **キーボードナビ**: ← / → でスライド移動、メイン画面と双方向同期
+- **レイアウト調整**: ペイン境界をドラッグで自由に変更、ダブルクリックでデフォルト復元 (localStorage 永続化)
+- **Multi-note Guard**: 1 スライドに複数のノートコメントがある場合は自動保存を無効化（先頭ノート消失防止）
+- **STALE 検出**: 外部エディタによる変更を ETag 楽観ロックで検出、編集中テキストを localStorage に自動退避
+
+### スピーカーノートの書き方
+
+```markdown
+# スライドタイトル
+
+スライドの本文
+
+<!-- ここがスピーカーノート。Presenter View で編集すると
+     このコメントが書き換わります。 -->
+```
+
+複数行のノートも OK:
+
+```markdown
+<!--
+- ポイント 1: 〜を強調する
+- ポイント 2: ここで質問を投げかける
+- 想定時間: 2 分
+-->
+```
+
+### Presenter View ショートカット
+
+| キー | 動作 |
+|---|---|
+| `← / →` | スライド移動 |
+| `Space / PageDown` | 次のスライド |
+| `Home / End` | 最初 / 最後のスライド |
 
 ## Keyboard Shortcuts
 
@@ -143,6 +239,10 @@ paginate: true
 | Cmd/Ctrl + P | PDF出力 |
 | Cmd/Ctrl + W | タブを閉じる |
 | ← / → | スライド移動（Marp時） |
+| F | フルスクリーン切替（Marp時） |
+| N | ナビバー表示切替（Marp時） |
+| **P** | **Presenter View 起動（Marp時）** |
+| Esc | フルスクリーン解除 |
 | F2 | ファイル名変更 |
 | Delete | ファイル削除 |
 
@@ -150,7 +250,7 @@ paginate: true
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/api/file` | GET | ファイル内容取得 |
+| `/api/file` | GET | ファイル内容取得 (Marp 時は etag/notes/notesMultiplicity も同梱) |
 | `/api/file` | POST | ファイル保存 |
 | `/api/file` | DELETE | ファイル/ディレクトリ削除 |
 | `/api/tree` | GET | ファイルツリー取得 |
@@ -159,7 +259,12 @@ paginate: true
 | `/api/move` | POST | ファイル移動/リネーム |
 | `/api/download` | GET | ファイルダウンロード |
 | `/api/upload` | POST | ファイルアップロード |
+| `/api/pdf/export` | POST | PDF出力 |
 | `/api/info` | GET | サーバー情報 |
+| `/api/marp/decks/:path` | GET | Marp デッキ情報取得 (etag, notes, notesMultiplicity) |
+| `/api/marp/decks/:path/slides/:N/note` | PUT | スピーカーノート更新 (`If-Match` 必須、ETag 楽観ロック) |
+
+`/api/marp/decks/*` は Origin / Sec-Fetch-Site / Content-Type を厳密に検証し、cross-origin / cross-site / non-JSON リクエストは `403 ORIGIN_REJECTED` または `415 UNSUPPORTED_MEDIA_TYPE` で拒否します（CSRF / DNS rebinding 防御）。
 
 ## Tech Stack
 
@@ -192,28 +297,54 @@ npm test
 
 ```
 mdv/
-├── bin/mdv.js           # CLI entry point
+├── bin/mdv.js                    # CLI entry point
 ├── src/
-│   ├── server.js        # Express server setup
-│   ├── watcher.js       # File watching (chokidar)
+│   ├── server.js                 # Express server setup
+│   ├── watcher.js                # File watching (chokidar)
+│   ├── websocket.js              # WebSocket setup
 │   ├── api/
-│   │   ├── file.js      # File operations API
-│   │   ├── tree.js      # File tree API
-│   │   └── upload.js    # Upload API
+│   │   ├── file.js               # File operations API
+│   │   ├── pdf.js                # PDF export API
+│   │   ├── tree.js               # File tree API
+│   │   ├── upload.js             # Upload API
+│   │   ├── marpNote.js           # Marp note autosave routes (orchestration)
+│   │   └── marpNote/
+│   │       ├── guards.js         # Origin / Host / Content-Type / If-Match guards
+│   │       ├── readDeck.js       # Path-safe deck reader (O_NOFOLLOW + realpath)
+│   │       ├── handleGet.js      # GET /api/marp/decks/:path
+│   │       └── handlePut.js      # PUT /api/marp/decks/:path/slides/:N/note
 │   ├── rendering/
-│   │   ├── index.js     # Rendering entry
-│   │   ├── markdown.js  # Markdown rendering
-│   │   └── marp.js      # Marp rendering
+│   │   ├── index.js              # Rendering entry
+│   │   ├── markdown.js           # Markdown rendering
+│   │   ├── marp.js               # Marp rendering (delegates to adapter)
+│   │   ├── marpitAdapter.js      # Marpit token adapter (SSOT)
+│   │   └── marpNoteWriter.js     # Pure-function note splice
+│   ├── concurrency/
+│   │   └── pathLock.js           # Promise-chain mutex (per-path serialization)
 │   ├── utils/
-│   │   ├── fileTypes.js # File type detection
-│   │   └── path.js      # Path security utilities
-│   └── static/          # Frontend files
-│       ├── index.html
-│       ├── app.js
-│       └── styles.css
+│   │   ├── errors.js             # Error codes / status mapping (SSOT)
+│   │   ├── etag.js               # sha256 ETag (SSOT)
+│   │   ├── lineMath.js           # BOM / CRLF / line ↔ byte conversion
+│   │   ├── atomicWrite.js        # Atomic file write (O_EXCL + EXDEV fallback)
+│   │   ├── fileTypes.js          # File type detection
+│   │   └── path.js               # Path security (validatePath / validatePathReal)
+│   ├── static/                   # Frontend files
+│   │   ├── index.html
+│   │   ├── app.js
+│   │   ├── presenter.html        # Presenter View (3-pane + autosave)
+│   │   ├── styles.css
+│   │   └── lib/
+│   │       ├── apiClient.js      # HTTP client wrapper
+│   │       ├── presenterChannel.js # BroadcastChannel SSOT
+│   │       ├── saveQueue.js      # Per-deck save queue + per-slide coalesce
+│   │       └── tabRegistry.js    # Tab life-cycle hooks
+│   └── styles/
+│       ├── index.js
+│       ├── report.example.css
+│       └── report.pdf-options.example.json
 ├── scripts/
-│   └── setup-macos-app.sh  # macOS app setup
-└── tests/               # Test files
+│   └── setup-macos-app.sh        # macOS app setup
+└── tests/                        # Test files (236 件、全 PASS)
 ```
 
 ## Requirements

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.8",
   "description": "Markdown Viewer - File tree + Live preview + Marp support + Hot reload",
   "main": "src/server.js",
   "bin": {