memd-cli 1.1.1 → 1.2.0

package/main.js

@@ -102,7 +102,7 @@ function shouldUsePager(text, options) {
 function spawnPager(text, options) {
   // Respect $PAGER environment variable (like glow, bat, mdcat)
   const pagerCmd = process.env.PAGER || 'less';
-  const pagerArgs = pagerCmd === 'less' ? ['-R'] : [];
+  const pagerArgs = pagerCmd === 'less' ? ['-R', ...(options.mouse !== false ? ['--mouse'] : [])] : [];
 
   const pager = spawn(pagerCmd, pagerArgs, {
     stdio: ['pipe', 'inherit', 'inherit']
@@ -133,6 +133,7 @@ async function main() {
     .description('Render markdown with mermaid diagrams to terminal output')
     .argument('[files...]', 'markdown file(s) to render')
     .option('--no-pager', 'disable pager (less)')
+    .option('--no-mouse', 'disable mouse scroll in pager')
     .option('--no-color', 'disable colored output')
     .option('--no-highlight', 'disable syntax highlighting')
     .option('--width <number>', 'terminal width override', Number)

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "memd-cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "main": "main.js",
   "bin": {
     "memd": "main.js"
   },
+  "scripts": {
+    "test": "vitest run"
+  },
   "dependencies": {
     "beautiful-mermaid": "^0.1.3",
     "cli-highlight": "^2.1.11",
@@ -17,5 +20,13 @@
     "type": "git",
     "url": "https://github.com/ktrysmt/memd.git"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "packageManager": "pnpm@10.15.1",
+  "devDependencies": {
+    "tuistory": "^0.0.16",
+    "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild", "node-pty"]
+  }
 }

package/plan.md

@@ -0,0 +1,283 @@
+# memd TUI Outline Sidebar 設計案
+
+## 背景
+
+memd は現在 `less` (または `$PAGER`) をフルスクリーンページャーとして使用している。
+Markdown の見出し構造をサイドバーにアウトラインとして表示し、ナビゲーション可能にする機能を追加する。
+
+## TUI ライブラリ選定
+
+| ライブラリ | 判定 | 理由 |
+|---|---|---|
+| blessed-contrib | 不採用 | 放棄済み (最終更新4年前)、未修正の Prototype Pollution 脆弱性 |
+| Ink | 保留 | 最も活発だが React 依存が重い。軽量 CLI には過剰 |
+| terminal-kit | 採用 | Node 18/20/22 対応、純 JS、既知脆弱性修正済み、ドキュメント良好 |
+
+リスク: メンテナ1名、更新頻度低下傾向、79件のオープンイシュー積み残し。
+terminal-kit 依存は `lib/tui.js` に閉じ込め、将来の差し替えに備える。
+
+## ディレクトリ構成
+
+```
+memd/
+  main.js              # エントリーポイント (CLI 解析 + モード分岐のみ)
+  lib/
+    markdown.js         # Markdown 処理 (既存ロジックの抽出)
+    outline.js          # 見出し抽出・アウトラインデータ生成
+    pager.js            # 既存の less/pager ロジック
+    tui.js              # terminal-kit TUI モード (新規)
+  test/
+    test1.md
+    test2.md
+  package.json
+```
+
+## モジュール設計
+
+### main.js -- エントリーポイント
+
+CLI 解析 (commander) とモード分岐のみ。
+
+```
+CLI 解析
+  |
+  +-- --outline あり & TTY  --> tui.js (TUI モード)
+  +-- パイプ / --no-pager / 短い出力 --> stdout 直接出力
+  +-- 長い出力              --> pager.js (less モード)
+```
+
+追加オプション:
+
+```js
+.option('--outline', 'show outline sidebar (TUI mode)')
+```
+
+分岐ロジック:
+
+```js
+if (options.outline && process.stdout.isTTY) {
+  launchTui(markdown, renderedText, options);
+} else if (shouldUsePager(renderedText, options)) {
+  spawnPager(renderedText, options);
+} else {
+  process.stdout.write(renderedText);
+}
+```
+
+### lib/markdown.js -- Markdown 処理
+
+既存の `main.js` から抽出する pure function 群。
+
+```js
+export function readMarkdownFile(filePath)
+// 現在の readMarkdownFile と同一
+
+export function configureMarked(options)
+// marked.use(...) の設定を集約
+
+export function convertMermaidToAscii(markdown, options)
+// 現在と同一
+
+export function renderToString(markdown, options)
+// 現在と同一
+
+export function readStdin()
+// 現在と同一
+```
+
+### lib/outline.js -- アウトライン抽出
+
+terminal-kit に依存しない pure function。テスト容易。
+
+```js
+/**
+ * Markdown ソースから見出しを抽出
+ * @param {string} markdown - 生の Markdown テキスト
+ * @returns {Array<{level: number, text: string, line: number}>}
+ *
+ * 例: [
+ *   { level: 1, text: "Hello", line: 0 },
+ *   { level: 2, text: "Section A", line: 15 },
+ *   { level: 3, text: "Subsection A-1", line: 28 },
+ * ]
+ */
+export function extractHeadings(markdown)
+
+/**
+ * レンダリング済みテキスト内で各見出しが何行目に対応するか算出
+ * (スクロール位置ジャンプに使用)
+ * @param {string} renderedText - marked で変換済みの ANSI 文字列
+ * @param {Array} headings - extractHeadings の結果
+ * @returns {Array<{...heading, renderedLine: number}>}
+ */
+export function mapHeadingsToRenderedLines(renderedText, headings)
+```
+
+### lib/pager.js -- Pager 処理
+
+```js
+export function shouldUsePager(text, options)
+// 現在と同一
+
+export function spawnPager(text, options)
+// 現在と同一
+```
+
+### lib/tui.js -- TUI モード (新規コア)
+
+terminal-kit 依存はこのファイルに閉じ込める。
+`--outline` 指定時のみ動的 import で読み込み、通常利用時のロード時間に影響しない。
+
+```js
+import termkit from 'terminal-kit';
+
+/**
+ * TUI モードを起動
+ * @param {string} markdown - 生の Markdown ソース
+ * @param {string} renderedText - レンダリング済みテキスト
+ * @param {object} options - CLI オプション
+ */
+export function launchTui(markdown, renderedText, options)
+```
+
+内部関数:
+
+```
+launchTui(markdown, renderedText, options)
+  |
+  +-- createLayout(term)
+  |     ターミナル幅を取得し、左右のカラム幅を決定
+  |     左: サイドバー (幅の 25%, 最小 20, 最大 40)
+  |     右: コンテンツ (残り)
+  |     戻り値: { sidebarWidth, contentWidth, height }
+  |
+  +-- renderSidebar(term, headings, selectedIndex, scrollOffset, layout)
+  |     アウトラインを左カラムに描画
+  |     選択中の見出しをハイライト
+  |     インデント: level に応じて 2*(level-1) スペース
+  |
+  +-- renderContent(term, lines, scrollOffset, layout)
+  |     レンダリング済みテキストを右カラムに描画
+  |     contentWidth に合わせて行を切り詰め
+  |
+  +-- renderStatusBar(term, state, layout)
+  |     最下行にステータス表示
+  |     "[q]quit  [j/k]navigate  [Enter]jump  [Tab]toggle sidebar"
+  |
+  +-- setupKeyBindings(term, state)
+        キー入力ハンドラ登録
+```
+
+キーバインド:
+
+| キー | 動作 |
+|---|---|
+| j / Down | 次の見出し |
+| k / Up | 前の見出し |
+| Enter | 選択した見出しの位置にコンテンツをスクロール |
+| g / G | 先頭 / 末尾 |
+| Ctrl+D / Ctrl+U | 半ページスクロール |
+| Tab | サイドバーフォーカス切替 |
+| q / Ctrl+C | 終了 |
+
+## 画面レイアウト
+
+```
++-- Outline (25%) --+-- Content (75%) --------------------------+
+| # Hello           | # Hello                                   |
+|   ## Section A    |                                            |
+|   ## Section B    | This is **markdown** printed in the        |
+| > ## Section C  < | `terminal`.                                |
+|     ### C-1       |                                            |
+|     ### C-2       | ## Section C                               |
+|   ## Section D    |                                            |
+|                   | Lorem ipsum dolor sit amet...              |
+|                   | ...                                        |
++-------------------+--------------------------------------------+
+  [q]quit [j/k]move [Enter]jump [Tab]focus       Section C  3/6
+```
+
+## データフロー
+
+```
+                  markdown (raw)
+                       |
+          +------------+------------+
+          |                         |
+   extractHeadings()         configureMarked()
+          |                  renderToString()
+          |                         |
+       headings[]            renderedText
+          |                         |
+   mapHeadingsToRenderedLines()     |
+          |                         |
+    headings[] with                 |
+    renderedLine                    |
+          |                         |
+          +-------+  +--------------+
+                  |  |
+              launchTui()
+              or spawnPager()
+              or stdout.write()
+```
+
+## 設計上のポイント
+
+1. **既存モードへの影響ゼロ** -- `--outline` なしなら従来通り `less` または stdout。TUI は `--outline` 時のみ動的ロードする
+2. **モジュール分割は最小限** -- `tui.js` + `outline.js` の 2 ファイル追加のみ。`main.js` の既存ロジック (markdown 処理, pager) はそのまま残す。小さな CLI に不要な分割はしない
+3. **outline.js は pure function** -- TUI ライブラリに依存しない。単体テスト可能
+4. **TUI 依存は tui.js に閉じ込める** -- 将来別ライブラリに差し替える場合も tui.js だけ書き換えればよい
+
+## レビュー指摘事項 (2026-03-07)
+
+### terminal-kit 選定リスクの再評価
+
+メンテナ1名 + 79件のオープンイシュー積み残しは「リスク」ではなく「既に問題化」に近い。
+memd の TUI は比較的シンプル (2カラムレイアウト + キー入力) なので、以下の代替案も検討する:
+
+- **案A: terminal-kit 採用** (現行案) -- 機能は豊富だがメンテナンス不安
+- **案B: 自前 ANSI 実装** -- `process.stdout.write` + ANSI エスケープ + `readline` rawMode で実現。依存ゼロ。memd の TUI 要件 (2カラム描画, キー入力, カーソル制御) は Node.js 標準 API で十分カバー可能
+
+### mapHeadingsToRenderedLines の実装方針
+
+ANSI エスケープ付きレンダリング済みテキストから見出し位置を特定する必要がある。
+marked-terminal の出力には以下の複雑性がある:
+
+- ANSI カラーコード
+- reflowText による折り返し
+- テーブル・コードブロックの展開
+
+実装方針: レンダリング後テキストを `strip-ansi` して各行を走査し、見出しテキスト (extractHeadings の結果) と前方一致でマッチさせる。
+完全一致が困難な場合は、marked のレンダリング時にカスタム renderer で見出し行にマーカー文字列を埋め込み、レンダリング後にマーカーで検索する方式をフォールバックとする。
+
+### コンテンツ描画時の ANSI 対応
+
+- 行の切り詰め (truncate) 時に ANSI エスケープシーケンスの途中で切断すると表示が崩れる
+- `strip-ansi` + `string-width` を利用して表示幅を正確に算出し、ANSI シーケンスを壊さない切り詰め処理が必要
+- TUI モードでは marked-terminal の `width` オプションをコンテンツカラム幅に合わせて設定する (全幅ではなく右カラム幅)
+
+### ターミナルリサイズ対応
+
+`process.stdout.on('resize', ...)` (SIGWINCH) でリサイズイベントを検知し、レイアウトを再計算して再描画する。
+
+### Tab フォーカス切替時の UX 定義
+
+- サイドバーフォーカス時: j/k で見出し間を移動、Enter でコンテンツをジャンプ
+- コンテンツフォーカス時: j/k で 1 行単位スクロール、g/G で先頭/末尾
+
+## モジュール分割方針 (修正)
+
+`main.js` の既存ロジック (readMarkdownFile, convertMermaidToAscii, renderToString, readStdin, shouldUsePager, spawnPager) はそのまま残す。
+新規追加は以下の 2 ファイルのみ:
+
+```
+memd/
+  main.js              # エントリーポイント (既存 + --outline 分岐追加)
+  lib/
+    outline.js          # 見出し抽出・アウトラインデータ生成 (pure function, 新規)
+    tui.js              # TUI モード (新規)
+  test/
+    test1.md
+    test2.md
+  package.json
+```

package/planb.md

@@ -0,0 +1,186 @@
+# 案B: 自前 ANSI 実装による TUI モード設計
+
+## 方針
+
+terminal-kit を使わず、Node.js 標準 API + ANSI エスケープシーケンスのみで TUI を実装する。
+memd の TUI 要件 (2カラム描画 + キー入力 + スクロール) は限定的であり、外部依存なしで実現可能。
+
+## 使用する Node.js 標準 API
+
+| 用途 | API |
+|---|---|
+| 画面描画 | `process.stdout.write` + ANSI エスケープシーケンス |
+| キー入力 | `readline.emitKeypressEvents` + `process.stdin.setRawMode(true)` |
+| 画面サイズ | `process.stdout.columns` / `process.stdout.rows` |
+| リサイズ検知 | `process.stdout.on('resize', ...)` |
+
+外部依存は `strip-ansi` と `string-width` のみ (いずれも marked-terminal の transitive dep として既存)。
+
+## ANSI エスケープの基本操作
+
+```js
+const ESC = '\x1b[';
+const cursor = {
+  moveTo: (x, y) => `${ESC}${y + 1};${x + 1}H`,
+  hide: `${ESC}?25l`,
+  show: `${ESC}?25h`,
+  clearScreen: `${ESC}2J`,
+  clearLine: `${ESC}2K`,
+};
+const style = {
+  reverse: `${ESC}7m`,
+  reset: `${ESC}0m`,
+  dim: `${ESC}2m`,
+  bold: `${ESC}1m`,
+};
+```
+
+## モジュール構成
+
+```
+memd/
+  main.js              # エントリーポイント (既存 + --outline 分岐追加)
+  lib/
+    outline.js          # 見出し抽出・アウトラインデータ生成 (pure function, 新規)
+    tui.js              # TUI モード (新規, 自前 ANSI 実装)
+  test/
+    test1.md
+    test2.md
+  package.json
+```
+
+## tui.js の内部構造
+
+```
+launchTui(markdown, renderedText, headings, options)
+  |
+  +-- state = {
+  |     sidebarFocused: true,
+  |     selectedHeading: 0,
+  |     contentScroll: 0,
+  |     sidebarScroll: 0,
+  |     layout: computeLayout(),
+  |   }
+  |
+  +-- computeLayout()
+  |     cols = process.stdout.columns
+  |     rows = process.stdout.rows
+  |     sidebarWidth = clamp(Math.floor(cols * 0.25), 20, 40)
+  |     contentWidth = cols - sidebarWidth - 1  // 1 for separator
+  |     height = rows - 1  // 1 for status bar
+  |
+  +-- render(state)
+  |     buf = ''
+  |     buf += cursor.hide
+  |     buf += renderSidebar(state)
+  |     buf += renderSeparator(state)
+  |     buf += renderContent(state)
+  |     buf += renderStatusBar(state)
+  |     process.stdout.write(buf)  // 1回の write でフリッカー軽減
+  |
+  +-- renderSidebar(state)
+  |     各見出しを sidebarWidth 内に収めて描画
+  |     選択行は reverse video で表示
+  |     level に応じて 2*(level-1) スペースでインデント
+  |
+  +-- renderSeparator(state)
+  |     縦線 '|' を各行の sidebarWidth 位置に描画
+  |
+  +-- renderContent(state)
+  |     renderedText を行分割済み配列として保持
+  |     contentScroll から height 行分を描画
+  |     各行を contentWidth でスライス (ANSI 対応)
+  |
+  +-- renderStatusBar(state)
+  |     最下行にキーバインドヘルプ + 現在位置表示
+  |
+  +-- handleKeypress(key, state)
+        keypress イベントから state を更新し render() を呼ぶ
+```
+
+## キー入力の実装
+
+```js
+import readline from 'readline';
+
+readline.emitKeypressEvents(process.stdin);
+process.stdin.setRawMode(true);
+process.stdin.on('keypress', (str, key) => {
+  if (key.name === 'q' || (key.ctrl && key.name === 'c')) {
+    cleanup();
+    process.exit(0);
+  }
+  handleKeypress(key, state);
+  render(state);
+});
+```
+
+### キーバインド
+
+| キー | サイドバーフォーカス時 | コンテンツフォーカス時 |
+|---|---|---|
+| j / Down | 次の見出し | 1行下スクロール |
+| k / Up | 前の見出し | 1行上スクロール |
+| Enter | 選択した見出しの位置にコンテンツをスクロール | -- |
+| g / G | 先頭 / 末尾 | 先頭 / 末尾 |
+| Ctrl+D / Ctrl+U | -- | 半ページスクロール |
+| Tab | コンテンツへフォーカス移動 | サイドバーへフォーカス移動 |
+| q / Ctrl+C | 終了 | 終了 |
+
+## フリッカー対策
+
+- 毎フレーム `clearScreen` せず、各行を `moveTo` + `clearLine` + 描画で上書き
+- 全描画内容を文字列バッファに溜めてから1回の `process.stdout.write(buf)` で出力
+
+## ANSI 対応の行スライス
+
+コンテンツ行を `contentWidth` に切り詰める際の処理:
+
+```js
+function sliceAnsiLine(line, maxWidth) {
+  // 1. ANSI エスケープを位置情報付きで分離
+  // 2. 表示文字の幅を string-width で計測しながら maxWidth まで切り詰め
+  // 3. 切り詰め後に開いたままの ANSI シーケンスを reset で閉じる
+}
+```
+
+## cleanup 処理
+
+```js
+function cleanup() {
+  process.stdout.write(cursor.show);
+  process.stdout.write(cursor.clearScreen);
+  process.stdout.write(cursor.moveTo(0, 0));
+  process.stdin.setRawMode(false);
+}
+// 異常終了時もクリーンアップ
+process.on('exit', cleanup);
+process.on('SIGINT', () => { cleanup(); process.exit(0); });
+```
+
+## ターミナルリサイズ対応
+
+```js
+process.stdout.on('resize', () => {
+  state.layout = computeLayout();
+  render(state);
+});
+```
+
+## mapHeadingsToRenderedLines の実装方針
+
+ANSI 付きレンダリング済みテキストから見出し位置を特定する:
+
+1. レンダリング後テキストを `strip-ansi` して各行を走査
+2. `extractHeadings` の結果と前方一致でマッチさせる
+3. フォールバック: marked のカスタム renderer で見出し行にマーカー文字列を埋め込み、レンダリング後にマーカーで検索
+
+## 案A (terminal-kit) との比較
+
+| | 案A (terminal-kit) | 案B (自前 ANSI) |
+|---|---|---|
+| 外部依存 | +1 (terminal-kit, ~2MB) | +0 (strip-ansi, string-width は既存 transitive dep) |
+| 実装量 | 少ない (API 呼ぶだけ) | 中程度 (~200行の描画コード) |
+| メンテリスク | メンテナ1名、更新頻度低下 | 自前なので自己責任 |
+| 機能カバー | 豊富 (使わない機能も多い) | 必要最小限 |
+| インストール速度 | native module なし、影響軽微 | 影響なし |

package/test/memd.test.js

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest'
+import { launchTerminal } from 'tuistory'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const MAIN = path.join(__dirname, '..', 'main.js')
+
+async function run(args, { waitFor = null } = {}) {
+  const session = await launchTerminal({
+    command: 'node',
+    args: [MAIN, ...args],
+    cols: 80,
+    rows: 30,
+    waitForData: false,
+  })
+  const waitText = waitFor ?? (t => t.trim().length > 0)
+  const output = await session.text({ waitFor: waitText, timeout: 8000 })
+  return output.trim()
+}
+
+describe('memd CLI', () => {
+  it('--version', async () => {
+    const output = await run(['-v'])
+    expect(output).toContain('1.1.1')
+  })
+
+  it('--help', async () => {
+    const output = await run(['--help'])
+    expect(output).toContain('Usage: memd')
+    expect(output).toContain('--no-pager')
+    expect(output).toContain('--no-color')
+    expect(output).toContain('--ascii')
+  })
+
+  it('renders test1.md (basic markdown + mermaid)', async () => {
+    const output = await run(
+      ['--no-pager', '--no-color', '--width', '80', 'test/test1.md'],
+      { waitFor: t => t.includes('More text.') },
+    )
+    expect(output).toMatchInlineSnapshot(`
+      "# Hello
+
+      This is markdown with mermaid:
+
+          ┌───┐     ┌───┐
+          │   │     │   │
+          │ A ├────►│ B │
+          │   │     │   │
+          └───┘     └───┘
+      More text."
+    `)
+  })
+
+  it('renders test2.md (complex mermaid diagram)', async () => {
+    const output = await run(
+      ['--no-pager', '--no-color', '--width', '80', 'test/test2.md'],
+      { waitFor: t => t.includes('More text after the diagram.') },
+    )
+    expect(output).toContain('Start')
+    expect(output).toContain('Decision?')
+    expect(output).toContain('Action')
+    expect(output).toContain('End')
+    expect(output).toContain('More text after the diagram.')
+  })
+
+  it('--ascii renders ASCII-only diagram', async () => {
+    const output = await run(
+      ['--no-pager', '--no-color', '--width', '80', '--ascii', 'test/test1.md'],
+      { waitFor: t => t.includes('More text.') },
+    )
+    expect(output).toContain('+---+')
+    expect(output).toContain('---->')
+    expect(output).not.toContain('┌')
+    expect(output).not.toContain('►')
+  })
+
+  it('--no-color strips ANSI escape codes', async () => {
+    const output = await run(
+      ['--no-pager', '--no-color', '--width', '80', 'test/test1.md'],
+      { waitFor: t => t.includes('More text.') },
+    )
+    // eslint-disable-next-line no-control-regex
+    expect(output).not.toMatch(/\x1b\[[\d;]*m/)
+  })
+
+  it('error on missing file', async () => {
+    const session = await launchTerminal({
+      command: 'node',
+      args: [MAIN, '--no-pager', 'test/nonexistent.md'],
+      cols: 80,
+      rows: 10,
+      waitForData: false,
+    })
+    const output = (await session.text({
+      waitFor: t => t.includes('Error'),
+      timeout: 8000,
+    })).trim()
+    expect(output).toContain('Error reading file')
+    expect(output).toContain('nonexistent.md')
+  })
+
+  it('reads markdown from stdin via shell', async () => {
+    const session = await launchTerminal({
+      command: 'sh',
+      args: ['-c', `echo '# stdin test' | node ${MAIN} --no-pager --no-color`],
+      cols: 80,
+      rows: 10,
+      waitForData: false,
+    })
+    const output = (await session.text({
+      waitFor: t => t.includes('stdin test'),
+      timeout: 8000,
+    })).trim()
+    expect(output).toContain('stdin test')
+  })
+})