aizuchi 0.1.0

package/dist/server/board.js

@@ -0,0 +1,248 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { configSchema, defaultConfig, findMemberViolations, summarizeZodError, taskFrontmatterSchema, } from '../shared/schema.js';
+import { hasApprovalTrace } from './lib/proposal.js';
+import { assertDirInsideKanban, collectKanbanFilesNoSymlink, PathValidationError, readKanbanFile, resolveKanbanReal, statKanbanFile, } from './lib/fs-safe.js';
+import { TaskFileParseError, parseTaskFile } from './lib/task-file.js';
+/**
+ * ボード読込: .kanban/ 配下の全タスクを読み、zod 検証・重複 ID 検出・members 整合を行って
+ * {tasks, config, warnings} を返す (F-6-2)。
+ * 不正ファイルは警告に変換して除外し、ボード自体は落とさない (DoD)。
+ */
+export async function loadConfig(projectRoot) {
+    const configPath = path.join(projectRoot, '.kanban', 'config.json');
+    const relPath = path.relative(projectRoot, configPath);
+    let raw;
+    try {
+        // R17-D: .kanban の realpath 信頼境界を確立 (.kanban 自体が symlink なら throw) してから
+        // config.json を realpath containment + symlink 非追従で読む。symlinked config.json や
+        // .kanban/config.json の中間 dir symlink による外部全文漏洩を防ぐ (symlink / 不在は既定値に倒す)
+        const kanbanReal = await resolveKanbanReal(projectRoot);
+        raw = await readKanbanFile(configPath, kanbanReal);
+    }
+    catch {
+        // config が無い / .kanban or config.json が symlink の場合は既定値で動作する (N-6)
+        return { config: defaultConfig(), warnings: [] };
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return {
+            config: defaultConfig(),
+            warnings: [
+                { kind: 'invalid_config', path: relPath, taskId: null, message: 'config.json が JSON として読めないため既定値で動作中' },
+            ],
+        };
+    }
+    const parsed = configSchema.safeParse(json);
+    if (!parsed.success) {
+        return {
+            config: defaultConfig(),
+            warnings: [
+                {
+                    kind: 'invalid_config',
+                    path: relPath,
+                    taskId: null,
+                    message: `config.json が不正なため既定値で動作中: ${summarizeZodError(parsed.error).join(' / ')}`,
+                },
+            ],
+        };
+    }
+    return { config: parsed.data, warnings: [] };
+}
+/** archive/** のファイル名から ID 集合を作る (重複 ID 検出用) */
+async function collectArchiveIds(kanbanDir, kanbanReal) {
+    const ids = new Set();
+    // R17-D: realpath containment + symlink (dir/file) 非追従の手動再帰で収集する。中間 dir symlink
+    // (archive 自体や入れ子 dir) を捕捉し、symlink で外部 .md を指して id 集合を水増しする攻撃を防ぐ
+    const files = await collectKanbanFilesNoSymlink(path.join(kanbanDir, 'archive'), kanbanReal);
+    for (const abs of files) {
+        ids.add(path.basename(abs).slice(0, -3));
+    }
+    return ids;
+}
+/**
+ * archive/** の全タスクの本文を読む (日次ダイジェストが作業ログを集計するため)。
+ * frontmatter 検証はせず本文を取り出す (アーカイブは所在で表現され様々な status がありうる)。
+ * パース不能なファイルはスキップする。
+ */
+export async function loadArchive(projectRoot) {
+    // R17-D: .kanban の realpath 信頼境界を確立 (.kanban 自体が symlink / 不在なら [] に倒す)
+    let kanbanReal;
+    try {
+        kanbanReal = await resolveKanbanReal(projectRoot);
+    }
+    catch {
+        return [];
+    }
+    const archiveDir = path.join(kanbanReal, 'archive');
+    // R17-D: realpath containment + symlink (dir/file) 非追従の手動再帰で .md を集め、各ファイルも
+    // realpath containment + symlink 非追従で読む。中間 dir symlink (archive 自体を外部 dir への
+    // symlink にする等) を捕捉し、外部ファイル (例 ~/.ssh/id_rsa) のダイジェスト経由漏洩を防ぐ
+    const files = await collectKanbanFilesNoSymlink(archiveDir, kanbanReal);
+    const result = [];
+    for (const abs of files) {
+        try {
+            const raw = await readKanbanFile(abs, kanbanReal);
+            result.push({ id: path.basename(abs).slice(0, -3), body: parseTaskFile(raw).body });
+        }
+        catch {
+            // パース不能 (壊れた archive) / symlink はスキップ
+        }
+    }
+    return result;
+}
+/** 1 ファイルを読み、検証済み TaskView を返す (POST / PATCH / PUT のレスポンス用)。不正なら例外 */
+export async function loadTaskView(projectRoot, filePath) {
+    // stat → read の順にする: 外部編集と並行した場合の不整合を「新内容 + 旧 mtime」(誤 409 側)
+    // に倒す。read → stat だと「旧内容 + 新 mtime」になり、PUT の競合検知をすり抜けて
+    // 外部編集を黙って上書きする危険側に倒れる (N-3)
+    // R17-D: .kanban の realpath 信頼境界を確立し、realpath containment + symlink 非追従で stat/read する。
+    // tasks/<id>.md やその中間 dir (tasks 自体) が symlink で外部ファイルを指していても PathValidationError を
+    // 投げて漏洩させない (loadTaskView は POST/PATCH/PUT のレスポンス生成に使われる)
+    const kanbanReal = await resolveKanbanReal(projectRoot);
+    const stat = await statKanbanFile(filePath, kanbanReal);
+    const raw = await readKanbanFile(filePath, kanbanReal);
+    const parsed = parseTaskFile(raw);
+    const frontmatter = taskFrontmatterSchema.parse(parsed.data);
+    return {
+        frontmatter,
+        path: path.relative(projectRoot, filePath),
+        body: parsed.body,
+        raw,
+        mtimeMs: stat.mtimeMs,
+    };
+}
+export async function loadBoard(projectRoot) {
+    const { config, warnings } = await loadConfig(projectRoot);
+    const tasks = [];
+    // R17-D: .kanban の realpath 信頼境界を確立する (.kanban 自体が symlink / 不在なら空ボード + warning)
+    let kanbanReal;
+    try {
+        kanbanReal = await resolveKanbanReal(projectRoot);
+    }
+    catch {
+        warnings.push({
+            kind: 'invalid_config',
+            path: path.join('.kanban', 'tasks'),
+            taskId: null,
+            message: '.kanban が見つからない / symlink のため読み込めない (aizuchi init が未実行の可能性)',
+        });
+        return { tasks, config, warnings };
+    }
+    const tasksDir = path.join(kanbanReal, 'tasks');
+    let fileNames;
+    try {
+        // R17-D: tasksDir 自体が外部 dir への symlink (A18-2) でないことを realpath で先に検査してから readdir する
+        // (fs.readdir は symlink dir を辿って外部の中身を列挙してしまうため)
+        await assertDirInsideKanban(tasksDir, kanbanReal);
+        fileNames = await fs.readdir(tasksDir);
+    }
+    catch {
+        warnings.push({
+            kind: 'invalid_config',
+            path: path.relative(projectRoot, tasksDir),
+            taskId: null,
+            message: '.kanban/tasks が見つからない / symlink のため読み込めない (aizuchi init が未実行の可能性)',
+        });
+        return { tasks, config, warnings };
+    }
+    const archiveIds = await collectArchiveIds(kanbanReal, kanbanReal);
+    // F-3-4 モード違反検知用: proposal モード時に「ai 種別の created_by かつ status≠proposed」を警告する。
+    // members の ai 種別を逆引きできるようにしておく (自動修正はしない、可視化のみ)
+    const aiMembers = new Set(config.members.filter((m) => m.type === 'ai').map((m) => m.id));
+    const proposalMode = config.aiTaskCreation === 'proposal';
+    for (const name of fileNames.filter((n) => n.endsWith('.md')).sort()) {
+        const filePath = path.join(tasksDir, name);
+        // R17-D: tasksDir は kanbanReal 基準 (macOS の /tmp→/private/tmp 等で projectRoot と realpath 差が出る)
+        // のため、表示用の相対パスは固定の `.kanban/tasks/<name>` で組み立てる (`../` 混入や drift を防ぐ)
+        const relPath = path.join('.kanban', 'tasks', name);
+        const fileId = name.slice(0, -3);
+        let raw;
+        let mtimeMs;
+        try {
+            // R17-D: realpath containment + symlink 非追従で stat → read (loadTaskView と同じ理由: 不整合を誤 409 側に倒す)。
+            // tasks/<id>.md が symlink なら statKanbanFile が PathValidationError を投げる
+            mtimeMs = (await statKanbanFile(filePath, kanbanReal)).mtimeMs;
+            raw = await readKanbanFile(filePath, kanbanReal);
+        }
+        catch (error) {
+            if (error instanceof PathValidationError) {
+                // symlink のタスクは読まずに除外し、可視化のため警告に積む (外部漏洩防止)
+                warnings.push({
+                    kind: 'invalid_task',
+                    path: relPath,
+                    taskId: fileId,
+                    message: 'symlink のため除外しました (.kanban 配下の symlink は許可されていません)',
+                });
+                continue;
+            }
+            continue; // 読込とリスト取得の間に消えた (外部編集との競合)。次の SSE 再取得で整合する
+        }
+        let parsed;
+        try {
+            parsed = parseTaskFile(raw);
+        }
+        catch (error) {
+            warnings.push({
+                kind: 'invalid_task',
+                path: relPath,
+                taskId: fileId,
+                message: error instanceof TaskFileParseError ? error.message : 'ファイルを解析できない',
+            });
+            continue;
+        }
+        const result = taskFrontmatterSchema.safeParse(parsed.data);
+        if (!result.success) {
+            warnings.push({
+                kind: 'invalid_task',
+                path: relPath,
+                taskId: fileId,
+                message: summarizeZodError(result.error).join(' / '),
+            });
+            continue;
+        }
+        const frontmatter = result.data;
+        if (frontmatter.id !== fileId) {
+            warnings.push({
+                kind: 'invalid_task',
+                path: relPath,
+                taskId: fileId,
+                message: `frontmatter の id (${frontmatter.id}) がファイル名 (${fileId}) と一致しない`,
+            });
+            continue;
+        }
+        // members 未登録は警告のみでタスクは表示する (F-6-2: 書式ミスの可視化が目的)
+        for (const violation of findMemberViolations(frontmatter, config)) {
+            warnings.push({ kind: 'unregistered_member', path: relPath, taskId: frontmatter.id, message: violation });
+        }
+        if (archiveIds.has(frontmatter.id)) {
+            warnings.push({
+                kind: 'duplicate_id',
+                path: relPath,
+                taskId: frontmatter.id,
+                message: `archive/ に同じ ID (${frontmatter.id}) のファイルが存在する (自動修復はしない)`,
+            });
+        }
+        // F-3-4: 提案モード中、ai が proposed 以外で起票したタスクを警告する (自動修正なし)。
+        // ただし作業ログに承認痕跡 (`[approve]`) があるものは「proposed→承認された正規タスク」なので
+        // 除外する (R6-1: 承認済み提案の恒久誤検知を防ぐ)
+        if (proposalMode &&
+            aiMembers.has(frontmatter.created_by) &&
+            frontmatter.status !== 'proposed' &&
+            !hasApprovalTrace(parsed.body)) {
+            warnings.push({
+                kind: 'mode_violation',
+                path: relPath,
+                taskId: frontmatter.id,
+                message: `提案モード中に AI (${frontmatter.created_by}) が proposed 以外 (${frontmatter.status}) で起票しています`,
+            });
+        }
+        tasks.push({ frontmatter, path: relPath, body: parsed.body, raw, mtimeMs });
+    }
+    // カード並びは ID 昇順固定 (数値を考慮: TASK-2 < TASK-10)
+    tasks.sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id, 'en', { numeric: true }));
+    return { tasks, config, warnings };
+}

package/dist/server/events.js

@@ -0,0 +1,24 @@
+export function createEventBus() {
+    const listeners = new Set();
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        broadcast(event) {
+            for (const listener of listeners) {
+                try {
+                    listener(event);
+                }
+                catch {
+                    // 1 購読者の失敗が他の購読者へ波及しないようにする
+                }
+            }
+        },
+        size() {
+            return listeners.size;
+        },
+    };
+}

package/dist/server/lib/config-paths.js

@@ -0,0 +1,91 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { hasSafeConfigExt, isHardDeniedConfigPath, isSecretPath, isStrictlyInside, PathValidationError, sanitizeConfigDirEntries, } from './fs-safe.js';
+/** 要求された相対パスが aiConfigPaths のどの許可に該当するかを判定し、正規化済み絶対パスを返す */
+export async function resolveConfigPath(projectRoot, config, requestedRelPath) {
+    const root = path.resolve(projectRoot);
+    // 要求パスを正規化し、プロジェクトルート配下であることを確認する (絶対パス / ../ を弾く)
+    const resolved = path.resolve(root, requestedRelPath);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new PathValidationError('プロジェクトルート外へのアクセスは許可されていません');
+    }
+    // 許可リスト (config 由来) を正規化する。各エントリが root の真の配下であることを強制し
+    // (`.` / `..` / 絶対パスで root 全域を許可リストに載せる攻撃を無効化)。deny-list はここでは効かせず、
+    // 解決後パスに対して下のゲートで 2 層適用する (R14-1 再修正)。
+    const exactFiles = new Set(sanitizeConfigDirEntries(root, [...config.aiConfigPaths.settingsFiles, ...config.aiConfigPaths.rootFiles]));
+    const browseDirs = sanitizeConfigDirEntries(root, config.aiConfigPaths.browseDirs);
+    let kind = null;
+    if (exactFiles.has(resolved)) {
+        kind = 'file';
+    }
+    else if (browseDirs.some((dir) => isStrictlyInside(dir, resolved))) {
+        kind = 'dir';
+    }
+    if (kind === null) {
+        throw new PathValidationError('許可リスト (aiConfigPaths) 外へのアクセスは許可されていません');
+    }
+    // deny-list を解決後パス (lexical) に適用する (R14-1 再修正・残存脆弱性 #2/#4/#7)。
+    // 強い deny (.git/** + 鍵類) は **完全一致 (exactFiles) でも** 遮断する (悪意 config が settingsFiles に
+    // `.git/hooks/pre-commit` / `.env` / `id_rsa` を列挙しても read/write させない = RCE/N-8 防止)。
+    assertNotDenied(resolved, kind);
+    // 親ディレクトリの realpath を解決し、symlink 経由で許可範囲の外へ出ていないか確認する
+    let parentReal;
+    try {
+        parentReal = await fs.realpath(path.dirname(resolved));
+    }
+    catch {
+        throw new PathValidationError('親ディレクトリが存在しません');
+    }
+    const rootReal = await fs.realpath(root).catch(() => root);
+    if (parentReal !== rootReal && !parentReal.startsWith(rootReal + path.sep)) {
+        throw new PathValidationError('symlink 経由でプロジェクトルート外を指しています');
+    }
+    // 接頭辞一致 (browseDirs) の場合、realpath 解決後も許可ディレクトリ配下か再確認する
+    if (kind === 'dir') {
+        const allowedReals = await Promise.all(browseDirs.map((dir) => fs.realpath(dir).catch(() => dir)));
+        const canonicalParent = parentReal;
+        const stillInside = allowedReals.some((dir) => canonicalParent === dir || canonicalParent.startsWith(dir + path.sep));
+        if (!stillInside) {
+            throw new PathValidationError('symlink 経由で許可ディレクトリ外を指しています');
+        }
+    }
+    const canonical = path.join(parentReal, path.basename(resolved));
+    // realpath 解決後の canonical にも deny-list を再適用する (R14-1 再修正)。
+    // 親ディレクトリが symlink で .git や鍵類の置き場へ実体を移していても遮断する (二重適用)。
+    assertNotDenied(canonical, kind);
+    // 対象自体が symlink なら拒否する (symlink 越しの読み書き防止)
+    try {
+        const lst = await fs.lstat(canonical);
+        if (lst.isSymbolicLink()) {
+            throw new PathValidationError('symlink への読み書きは許可されていません');
+        }
+    }
+    catch (error) {
+        if (error instanceof PathValidationError)
+            throw error;
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return { absPath: canonical, kind };
+}
+/**
+ * 解決後パスを allow-list (主ゲート) + deny-list (defense-in-depth) で検査する (R17-E + R14-1 再修正)。
+ * - **allow-list (R17-E・#E-1)**: 拡張子が SAFE_CONFIG_EXT に無ければ完全一致 / 接頭辞一致を問わず拒否。
+ *   deny-list の whack-a-mole を止め、許可拡張子に無い `kubeconfig` / `github_token` / `credentials` /
+ *   `terraform.tfstate` / `.envrc` / `prod.env` 等を一律ブロックする主ゲート。
+ * - `isHardDeniedConfigPath` (.git/** + 鍵類 + 秘匿 dir) は **完全一致 / 接頭辞一致を問わず** 遮断する。
+ * - `isSecretPath` (= さらに settings.local.json) は **接頭辞一致 (browseDirs) のみ** 遮断する
+ *   (完全一致 = settingsFiles 経由の settings.local.json 編集は正規ユースケースのため許す)。
+ */
+function assertNotDenied(targetPath, kind) {
+    // 主ゲート: allow-list 拡張子のみ通す (両 kind に適用)
+    if (!hasSafeConfigExt(targetPath)) {
+        throw new PathValidationError('許可されていない拡張子のファイルにはアクセスできません');
+    }
+    if (isHardDeniedConfigPath(targetPath)) {
+        throw new PathValidationError('秘匿ファイル (.git 配下 / 鍵類) へのアクセスは許可されていません');
+    }
+    if (kind === 'dir' && isSecretPath(targetPath)) {
+        throw new PathValidationError('秘匿ファイルへのアクセスは許可されていません');
+    }
+}

package/dist/server/lib/docs.js

@@ -0,0 +1,154 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { isSecretPath, isStrictlyInside, PathValidationError, readFileNoFollow, sanitizeConfigDirEntries, } from './fs-safe.js';
+/**
+ * 関連資料 (波 VIII) の読取専用ファイル I/O。
+ * config.docsDirs に列挙されたディレクトリ配下の .md のみを対象にする。
+ * - 書込 API は無い (資料は読取専用。逆引きはタスク側 frontmatter から導出する)
+ * - パス検証は resolveConfigPath (config-paths.ts) と同じ多段検査
+ *   (正規化 → ルート配下 → docsDirs 接頭辞 → 親 realpath → realpath 後の接頭辞再確認 → symlink 対象拒否)。
+ *   許可リストの root 配下強制 / 秘匿 deny-list / TOCTOU 回避は共通 util (fs-safe.ts の
+ *   sanitizeConfigDirEntries / isStrictlyInside / isSecretPath / readFileNoFollow) に集約済み
+ *   (N≥3 で extract・LEARN#8b。S-6 監査 R14-1/R14-3/R14-4 で実施)。
+ * - N-8: 資料内容をサーバーログに出さない。
+ */
+/**
+ * config.docsDirs を root 配下の有効なディレクトリ集合 (絶対パス) に正規化する (R14-3)。
+ * - root 自身 / root 外を指すエントリは除外 (`.` / `..` で全 .md を読取公開する攻撃を無効化)
+ * - `.kanban` 配下を指すエントリも除外 (タスクファイル / config が関連資料として読取公開されないように)
+ * - `.git` 配下 / 秘匿パスを指すエントリも除外 (R14-1 再修正 #6: docsDirs:['.git'] で .git/*.md 読取を塞ぐ・
+ *   config-paths の deny-list と対称化)
+ */
+function effectiveDocsDirs(root, config) {
+    const kanbanDir = path.join(root, '.kanban');
+    return sanitizeConfigDirEntries(root, config.docsDirs).filter((dir) => dir !== kanbanDir && !isStrictlyInside(kanbanDir, dir) && !isSecretPath(dir));
+}
+/** 要求された相対パスが docsDirs 配下の .md であることを検証し、正規化済み絶対パスを返す */
+export async function resolveDocPath(projectRoot, config, requestedRelPath) {
+    const root = path.resolve(projectRoot);
+    // .md のみ許可 (資料プレビュー専用 API のため拡張子で先に絞る)
+    if (!requestedRelPath.endsWith('.md')) {
+        throw new PathValidationError('関連資料は .md ファイルのみ参照できます');
+    }
+    // 正規化 + プロジェクトルート配下の確認 (絶対パス / ../ を弾く)
+    const resolved = path.resolve(root, requestedRelPath);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new PathValidationError('プロジェクトルート外へのアクセスは許可されていません');
+    }
+    // docsDirs 接頭辞一致 (root 自身 / .kanban を指す docsDir は effectiveDocsDirs で除外済み・R14-3)
+    const docsDirs = effectiveDocsDirs(root, config);
+    if (!docsDirs.some((dir) => isStrictlyInside(dir, resolved))) {
+        throw new PathValidationError('docsDirs 外へのアクセスは許可されていません');
+    }
+    // 有効 docsDir 配下でも、パスに .git 成分 / 秘匿 basename が含まれれば拒否 (R14-1 再修正 #6・多層防御)
+    if (isSecretPath(resolved)) {
+        throw new PathValidationError('秘匿ファイルへのアクセスは許可されていません');
+    }
+    // 親ディレクトリの realpath が許可範囲内かを確認 (symlink 経由の脱出を防ぐ)
+    let parentReal;
+    try {
+        parentReal = await fs.realpath(path.dirname(resolved));
+    }
+    catch {
+        throw new PathValidationError('親ディレクトリが存在しません');
+    }
+    const rootReal = await fs.realpath(root).catch(() => root);
+    if (parentReal !== rootReal && !parentReal.startsWith(rootReal + path.sep)) {
+        throw new PathValidationError('symlink 経由でプロジェクトルート外を指しています');
+    }
+    const allowedReals = await Promise.all(docsDirs.map((dir) => fs.realpath(dir).catch(() => dir)));
+    const stillInside = allowedReals.some((dir) => parentReal === dir || parentReal.startsWith(dir + path.sep));
+    if (!stillInside) {
+        throw new PathValidationError('symlink 経由で docsDirs 外を指しています');
+    }
+    // 対象自体が symlink なら拒否 (symlink 越しの読出防止)
+    const canonical = path.join(parentReal, path.basename(resolved));
+    // realpath 解決後の canonical にも秘匿 deny を再適用 (親 symlink が .git へ実体を移すケースを塞ぐ)
+    if (isSecretPath(canonical)) {
+        throw new PathValidationError('秘匿ファイルへのアクセスは許可されていません');
+    }
+    try {
+        const lst = await fs.lstat(canonical);
+        if (lst.isSymbolicLink()) {
+            throw new PathValidationError('symlink の参照は許可されていません');
+        }
+    }
+    catch (error) {
+        if (error instanceof PathValidationError)
+            throw error;
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return canonical;
+}
+/** docsDirs 配下の資料本文を読む (読取専用)。許可外は PathValidationError、不在は ENOENT */
+export async function readDoc(projectRoot, config, relPath) {
+    const absPath = await resolveDocPath(projectRoot, config, relPath);
+    // R14-4: resolveDocPath の lstat (symlink 拒否) と readFile の間で対象が symlink に差し替わる
+    // TOCTOU 窓を O_NOFOLLOW で塞ぐ (対象が symlink なら open が ELOOP で失敗する)。
+    const content = await readFileNoFollow(absPath);
+    // absPath は realpath ベースの canonical のため、相対化も realpath 済み root を基準にする
+    // (macOS の /var → /private/var のような root 側 symlink で相対パスがずれないように)
+    const root = path.resolve(projectRoot);
+    const rootReal = await fs.realpath(root).catch(() => root);
+    return { path: path.relative(rootReal, absPath), content };
+}
+/**
+ * docsDirs 配下の .md ファイルツリーを構築する。buildFileTree (files.ts) と同じ手動再帰で
+ * symlink dir/file を辿らない (R8-1 と同型・プロジェクト外漏洩防止)。
+ * .md 以外のファイルは含めず、.md を 1 つも含まないディレクトリは木から除外する。
+ */
+export async function buildDocsTree(projectRoot, config) {
+    const root = path.resolve(projectRoot);
+    const trees = [];
+    // R14-3: root 自身 / root 外 / .kanban を指す docsDir は effectiveDocsDirs で除外する
+    // (`.` で全 .md が、`.kanban` でタスク / config が読取公開されるのを防ぐ)
+    for (const absDir of effectiveDocsDirs(root, config)) {
+        const node = await buildDocsNode(root, absDir);
+        // R13-6: top-level エントリはディレクトリのみ許可。docsDirs に .md ファイル自体が指定されると
+        // ツリーには出るが readDoc (接頭辞 + path.sep 判定) では常に 403 になる不整合を防ぐ
+        if (node && node.type === 'dir')
+            trees.push(node);
+    }
+    return trees;
+}
+async function buildDocsNode(root, absPath) {
+    // R14-1 再々修正 (FIX-6・#1/#4): 走査中の .git 配下 / 秘匿 basename は列挙しない。
+    // FIX-5 は top-level (effectiveDocsDirs) と read (resolveDocPath) のみだったため、正規 docsDir 配下に
+    // 入れ子で置かれた .git/*.md / .env.md がツリーに名前・構造として露出していた。files.ts:100 buildTreeNode と同型化。
+    if (isSecretPath(absPath))
+        return null;
+    let stat;
+    try {
+        stat = await fs.lstat(absPath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink())
+        return null; // symlink は辿らない
+    const rel = path.relative(root, absPath);
+    const name = path.basename(absPath);
+    if (stat.isDirectory()) {
+        let entries = [];
+        try {
+            entries = (await fs.readdir(absPath)).sort();
+        }
+        catch {
+            entries = [];
+        }
+        const children = [];
+        for (const entry of entries) {
+            const child = await buildDocsNode(root, path.join(absPath, entry));
+            if (child)
+                children.push(child);
+        }
+        if (children.length === 0)
+            return null; // .md を含まない dir は出さない
+        return { path: rel, name, type: 'dir', children };
+    }
+    if (stat.isFile() && name.endsWith('.md')) {
+        return { path: rel, name, type: 'file' };
+    }
+    return null;
+}