B-144: memoツール入力バリデーション改善 - 調査レポート

1. memoツールのソースコード構造

ファイル構成

scripts/
├── memo.ts                         # エントリーポイント (CLIパース・コマンドディスパッチ)
└── memo/
    ├── types.ts                    # 型定義・normalizeRole・toPartition・isAgentMode
    ├── commands/
    │   ├── create.ts               # createMemo() 関数
    │   ├── read.ts                 # readMemo() / readMemos() / findMemoById() 関数
    │   ├── list.ts                 # listMemos() 関数
    │   └── mark.ts                 # markMemo() 関数
    ├── core/
    │   ├── id.ts                   # generateMemoId() / idFromTimestamp() / timestampFromId()
    │   ├── frontmatter.ts          # formatTimestamp() / serializeFrontmatter()
    │   ├── paths.ts                # getMemoRoot() / memoFilePath() / inboxDir() etc.
    │   ├── parser.ts               # parseMemoFile() (フロントマター・ボディのパース)
    │   ├── scanner.ts              # scanAllMemos() (全メモのスキャン)
    │   └── credential-check.ts    # checkCredentials() (機密情報パターン検出)
    └── __tests__/
        ├── create.test.ts
        ├── read.test.ts
        ├── list.test.ts
        ├── mark.test.ts
        ├── parser.test.ts
        ├── frontmatter.test.ts
        ├── credential-check.test.ts
        ├── id.test.ts
        ├── paths.test.ts
        ├── scanner.test.ts
        └── memo-lint.test.ts

処理フロー概要

1. memo.ts の parseArgs() でCLI引数をパース
2. コマンドに応じて各 commands/*.ts の関数を呼び出す
3. core/ モジュールで低レベル処理（ファイルI/O、パース、バリデーション）

---

2. 現在の --body オプションの処理方法

実装箇所: scripts/memo.ts (194〜205行目)

// Read body from --body flag or stdin
let body: string | undefined = getFlag(flags, "body");
if (body === undefined && !process.stdin.isTTY) {
  body = fs.readFileSync(0, "utf-8");
}

if (!body || body.trim() === "") {
  console.error(
    "Error: body is required. Provide --body or pipe via stdin.",
  );
  process.exit(1);
}

現在の動作

• --body <text> が指定された場合はその値を使用
• --body が省略され、かつ process.stdin.isTTY が false（パイプ入力あり）の場合は、fs.readFileSync(0, "utf-8") で標準入力を読み込む
• どちらも満たされない場合はエラーで終了

問題点

• --body フラグの値がコマンドライン引数として渡されるため、シェルの引数展開・特殊文字エスケープの問題が発生しやすい
• 現在のCLAUDE.mdの create 例では --body オプションを使用しているが、エージェントに --body の代わりにパイプを使うよう明確に指示することで安全性が向上する
• ただし、現状ではパイプが無く --body も無い場合のエラーメッセージは「Provide --body or pipe via stdin」となっており、TTY上でのインタラクティブ入力は未サポートかつ意図しない

---

3. 引数パース・バリデーションの仕組み

parseArgs() 関数 (scripts/memo.ts 19〜57行目)

実装内容

interface ParsedArgs {
  command: string;
  positional: string[];
  flags: Record<string, string | string[]>;
  booleanFlags: Set<string>;
}

const BOOLEAN_FLAGS = new Set(["skip-credential-check"]);

function parseArgs(args: string[]): ParsedArgs {
  // args[0] がコマンド名
  // --key value 形式でフラグをパース
  // --tag は複数値対応（Array）
  // - (short flag) にも対応
  // それ以外は positional に追加
}

特徴・制限

• 自前実装（外部ライブラリ不使用）
• boolean フラグは BOOLEAN_FLAGS に列挙する必要がある
• --tag のみ複数値をサポート（Arrayに集約）。他フラグは上書き
• --tags (複数形) はカンマ区切り文字列として1つの値で受け取る（createコマンド用）
• --tag (単数形) はANDフィルタ用に複数回指定可能（listコマンド用）
• フラグ値が未指定の場合は空文字列 "" になる（バリデーションは各コマンドで行う）

バリデーション

現状のバリデーションは以下の場所で行われている：

項目	場所	内容
from/to の必須チェック	memo.ts createケース	!from || !to || !subject
from/to のロール名バリデーション	memo.ts + create.ts	normalizeRole() を呼び出し
body の必須チェック	memo.ts createケース	!body || body.trim() === ""
body の空チェック	create.ts createMemo()	同上（二重チェック）
機密情報チェック	create.ts createMemo()	checkCredentials()
mark の state バリデーション	mark.ts markMemo()	VALID_STATES.includes(newState)

normalizeRole() の実装 (types.ts)

export function normalizeRole(role: string): string {
  const normalized = role.toLowerCase().replace(/ /g, "-");
  if (!/^[a-z]([a-z-]*[a-z])?$/.test(normalized)) {
    throw new Error(
      `Invalid role: "${role}". Must contain only letters and hyphens, and must not start or end with a hyphen.`,
    );
  }
  return normalized;
}

• ロール名は英小文字・ハイフンのみ許可
• 先頭・末尾のハイフンは不可
• スペースはハイフンに変換

---

4. 既存のテストファイル

全コマンド・コアモジュールに対してテストが存在する。vitestを使用。

テストファイル	対象
create.test.ts	createMemo() - 正常系・異常系・クレデンシャルチェック・ロール正規化
read.test.ts	findMemoById() / readMemo() / readMemos()
list.test.ts	listMemos() - フィルタ・ソート・エージェントモード
mark.test.ts	markMemo() - 状態遷移・エージェントモード制限
parser.test.ts	parseMemoFile() - 各フォーマット・エラーケース
frontmatter.test.ts	formatTimestamp() / serializeFrontmatter()
credential-check.test.ts	checkCredentials() - 各パターン
id.test.ts	generateMemoId() / idFromTimestamp() / timestampFromId()
paths.test.ts	toKebabCase() / memoFilePath() 等
scanner.test.ts	scanAllMemos()
memo-lint.test.ts	lintメモファイルの整合性チェック

テストでは vi.mock('../core/paths.js', ...) で getMemoRoot() を一時ディレクトリにモックして隔離している。

---

5. --body - で標準入力から読む実装パターン（Node.js）

現在の実装

fs.readFileSync(0, "utf-8") で fd=0（stdin）を同期的に読み込む。これは以下のように自動判別される：

if (body === undefined && !process.stdin.isTTY) {
  body = fs.readFileSync(0, "utf-8");
}

--body - パターンへの変換方法

--body - を「標準入力から読む」シグナルとして使う場合、以下のように実装できる：

let body: string | undefined = getFlag(flags, "body");

if (body === "-") {
  // --body - が指定されたら標準入力から読む
  body = fs.readFileSync(0, "utf-8");
} else if (body === undefined && !process.stdin.isTTY) {
  // --body 省略時でパイプがあれば標準入力から読む（後方互換）
  body = fs.readFileSync(0, "utf-8");
}

Node.jsでの標準入力読み込みパターン比較

パターン	実装	特徴
fs.readFileSync(0, "utf-8")	現在の実装	同期・シンプル。小〜中規模データに適する
process.stdin readable stream	for await (const chunk of process.stdin)	非同期・ストリーム処理。大容量データに適する
--body - シグナル	フラグ値が - かどうかで分岐	Unix慣例に従った明示的な指定

推奨実装

現在の自動判別（isTTY チェック）は十分機能しているが、エージェントがパイプで入力するユースケースでは問題ない。ただし、明示的に --body - を受け付けることで意図が明確になり、ドキュメント・テスト・エラーメッセージも整理しやすくなる。

---

6. 改善提案のポイント（プランナー向け）

現状の問題点まとめ

1. --body オプションのリスク: コマンドライン引数として渡されるため、特殊文字・改行・クォートの扱いが困難。エージェントが --body "..." でマルチライン本文を渡すと問題が起きやすい
2. バリデーションの二重化: memo.ts と create.ts 両方に body の空チェックが存在する（一方で整合性は保たれている）
3. 明示的な stdin 読み込みシグナルなし: --body - という Unix慣例パターンに未対応

実装候補

オプションA: --body を廃止しパイプ専用化

• --body フラグを削除し、stdnから読む方式のみにする
• ヘルプメッセージ・CLAUDE.mdの例を更新
• シンプルだが後方互換を壊す

オプションB: --body - を明示サポート

• --body - で stdin 読み込みを明示できるようにする
• 後方互換（--body で直接値渡し・isTTYチェック）も維持
• Unix慣例に従い、ドキュメントが明確になる

オプションC: バリデーション強化のみ

• 現状の仕組みを維持しつつ、エラーメッセージをより詳細化
• --body で空文字列を渡したときのエラーを改善

優先推奨

オプションB（--body - サポート）＋エラーメッセージ改善 が最もバランスが良い。

• 後方互換を壊さない
• Unix慣例に従う
• エージェントへの指示が明確になる
• テストも書きやすい

---

参考: 主要ファイルパス

• scripts/memo.ts - CLIエントリーポイント・引数パース
• scripts/memo/commands/create.ts - メモ作成ロジック
• scripts/memo/types.ts - normalizeRole等
• scripts/memo/core/credential-check.ts - 機密情報検出
• scripts/memo/__tests__/create.test.ts - 作成コマンドのテスト