aizuchi 0.3.0 → 0.5.0

package/dist/server/lib/related-docs-validate.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { isSecretPath, isStrictlyInside, PathValidationError, sanitizeConfigDirEntries, } from './fs-safe.js';
+/**
+ * 資料からの起票 (波 VIII) で frontmatter に保存して良い related_docs パスかを検証する純ロジック。
+ *
+ * - 対象ディレクトリ = config.docsDirs ∪ config.docsWriteDirs を sanitizeConfigDirEntries で
+ *   root 配下に正規化し、.kanban 配下 / 秘匿パスを除外したもの (docs.ts の effectiveDocsDirs と同思想)。
+ * - 各要素は「.md 拡張子」「root 配下の相対パス (絶対 / .. を弾く)」「許可ディレクトリ配下」
+ *   「秘匿パスでない」を満たす必要がある。1 つでも違反すれば PathValidationError を投げる。
+ * - 同期判定のみ (fs.realpath は呼ばない): これは「読取」ではなく「frontmatter に書いて良い参照値か」の
+ *   妥当性チェック。symlink / TOCTOU 防御は読取時 (docs.ts resolveDocPath / readFileNoFollow) が担保する。
+ */
+export function assertRelatedDocsAllowed(projectRoot, config, docs) {
+    if (docs.length === 0)
+        return;
+    const root = path.resolve(projectRoot);
+    const kanbanDir = path.join(root, '.kanban');
+    const allowedDirs = sanitizeConfigDirEntries(root, [...config.docsDirs, ...config.docsWriteDirs]).filter((dir) => dir !== kanbanDir && !isStrictlyInside(kanbanDir, dir) && !isSecretPath(dir));
+    for (const rel of docs) {
+        if (!rel.endsWith('.md')) {
+            throw new PathValidationError('related_docs は .md ファイルのみ指定できます');
+        }
+        if (path.isAbsolute(rel)) {
+            throw new PathValidationError('related_docs に絶対パスは指定できません');
+        }
+        const resolved = path.resolve(root, rel);
+        if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+            throw new PathValidationError('related_docs にプロジェクトルート外のパスは指定できません');
+        }
+        if (isSecretPath(resolved)) {
+            throw new PathValidationError('related_docs に秘匿ファイルは指定できません');
+        }
+        if (!allowedDirs.some((dir) => isStrictlyInside(dir, resolved))) {
+            throw new PathValidationError('related_docs は docsDirs / docsWriteDirs 配下の資料のみ指定できます');
+        }
+    }
+}

package/dist/server/lib/task-ops.js

@@ -100,6 +100,7 @@ export class TaskOps {
                     created_by: parsed.data.created_by,
                     priority: parsed.data.priority ?? 'medium',
                     labels: parsed.data.labels ?? [],
+                    related_docs: parsed.data.related_docs,
                     blocked_type: null,
                     blocked_reason: null,
                     created: now,

package/dist/shared/ai-health.js

@@ -0,0 +1,78 @@
+/**
+ * AI オンボーディング診断 (TASK-023)。
+ * board の warnings を AI メンバー別に集計し、各 warning kind に「直し方」の説明を付けた
+ * 構造を返す純関数。新データ源・新依存・永続化なし。
+ *
+ * now は引数注入 (Date.now ハードコード禁止・テスト再現性)。
+ */
+/**
+ * warnings を AI メンバー別・kind 別に group-by する。
+ *
+ * - warning が特定の AI メンバーに紐付くか判定: taskId が null でない場合はタスクのパスから
+ *   直接判定できないため、メンバー ID を message 内から照合する (unregistered_member / mode_violation)。
+ *   それ以外の kind (invalid_task / duplicate_id / invalid_config) は AI に特定紐付けできないため
+ *   全 AI メンバーに共通の「設定上の問題」として集約する。
+ * - assignee / created_by 別の精細な帰属は taskView へのアクセスが必要で pure fn では難しいため、
+ *   警告の message 文字列に含まれる member id を照合する簡易戦略を取る。
+ *
+ * @param warnings  board.warnings (GET /api/board の warnings)
+ * @param members   config.members (全メンバー)
+ */
+export function deriveAiHealth(warnings, members) {
+    const aiMembers = members.filter((m) => m.type === 'ai');
+    if (aiMembers.length === 0) {
+        return { members: [], noAiMembers: true };
+    }
+    const results = aiMembers.map((member) => {
+        // このメンバーに紐付く warning を収集する
+        const memberWarnings = warnings.filter((w) => isWarningForMember(w, member.id));
+        // kind 別にグループ化する
+        const kindMap = new Map();
+        for (const w of memberWarnings) {
+            const existing = kindMap.get(w.kind);
+            if (existing) {
+                existing.push(w);
+            }
+            else {
+                kindMap.set(w.kind, [w]);
+            }
+        }
+        const groups = Array.from(kindMap.entries()).map(([kind, ws]) => ({
+            kind,
+            warnings: ws,
+        }));
+        return {
+            member,
+            groups,
+            totalWarnings: memberWarnings.length,
+        };
+    });
+    return { members: results, noAiMembers: false };
+}
+/**
+ * warning が特定のメンバー ID に関係するか判定する。
+ *
+ * 帰属ルール:
+ * - `mode_violation`: message に memberId が含まれる (board.ts が `AI (${created_by})` と書く)
+ * - `unregistered_member`: message に `"${memberId}"` が含まれる (board.ts が `created_by "${id}"` / `assignee "${id}"` と書く)
+ * - `invalid_task` / `duplicate_id`: タスク起票者を message から特定できないが、メンバーが 1 人なら
+ *   そのメンバーに帰属させる。複数の AI メンバーがいる場合は全員に共通の問題として扱う (= 全員に紐付ける)
+ * - `invalid_config`: config 全体の問題なので全 AI メンバーに共通 (= 全員に紐付ける)
+ */
+function isWarningForMember(warning, memberId) {
+    switch (warning.kind) {
+        case 'mode_violation':
+            // board.ts: `AI (${frontmatter.created_by}) が ...`
+            return warning.message.includes(`(${memberId})`);
+        case 'unregistered_member':
+            // board.ts: `created_by "${id}" は config.members に未登録` / `assignee "${id}" ...`
+            return warning.message.includes(`"${memberId}"`);
+        case 'invalid_task':
+        case 'duplicate_id':
+        case 'invalid_config':
+            // task/config 全体の問題。AI メンバー全員に共通の診断事項として表示する
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/shared/schema.js

@@ -15,6 +15,11 @@ export const UI_LANGS = ['en', 'ja'];
 export const DEFAULT_PORT = 5151;
 /** overview モードの既定ポート (波 VII)。serve の 5151 と衝突しない値・1 箇所集約 */
 export const DEFAULT_OVERVIEW_PORT = 5152;
+/**
+ * serve のポート自動フォールバック試行回数。起点 (--port 明示時を除く) が使用中なら
+ * 起点〜起点+この数-1 まで順に空きを探す。複数プロジェクトの同時 serve 用 (例: 5151〜5170)。
+ */
+export const PORT_FALLBACK_ATTEMPTS = 20;
 // 日付は文字列のまま扱い、Date 化しない (js-yaml JSON_SCHEMA エンジンと対になる規則)。
 // zod の datetime({ offset: true }) を使い、月 13 / 時 25 のような実在しない日時を弾く
 // (自前正規表現は桁数だけ見て実在性を見ず、経過時間表示が NaN になりうる — PM Round 1 Minor #8)。
@@ -145,6 +150,9 @@ export const configSchema = z.object({
     views: z.array(z.object({ id: z.string().min(1), hidden: z.boolean().optional() })).default([]),
     // 関連資料ディレクトリ (波 VIII)。プロジェクトルートからの相対パス。既定は空 = 機能オフ (UI 非表示)
     docsDirs: z.array(z.string().min(1)).default([]),
+    // 資料の書込先ディレクトリ (資料エディタ MVP)。読取 (docsDirs) と分離し、既定は空 = 書込オフ。
+    // 書込 API (POST/PUT/DELETE /api/docs) はこの配下のみ許可する (root 配下相対)。
+    docsWriteDirs: z.array(z.string().min(1)).default([]),
     // ごみ箱 (.kanban/.trash) の同 id あたり退避世代の保持件数。任意・後方互換 (未設定は DEFAULT_TRASH_KEEP)。
     // 破壊的書込の直前に旧版を .trash へコピー退避し、この件数を超えた古い世代を刈り取る (誤上書きの安全網)
     trashKeep: z.number().int().positive().optional(),
@@ -275,6 +283,9 @@ export const newTaskInputSchema = z
     labels: z.array(z.string().min(1)).optional(),
     // 本文 (波 VI: テンプレートからのプリフィル用)。省略時はサーバーが既定本文テンプレートを使う
     body: z.string().optional(),
+    // 波 VIII: 関連資料 (プロジェクトルートからの相対パス配列)。任意・後方互換。
+    // 範囲 (docsDirs / docsWriteDirs 配下か) はサーバー側 assertRelatedDocsAllowed が検証する
+    related_docs: z.array(z.string().min(1)).optional(),
 })
     .strict();
 /**

package/dist/shared/task-setters.js

@@ -0,0 +1,132 @@
+/**
+ * task frontmatter の 1 フィールドだけを byte 保全で書き換える純関数。
+ * setRelatedDocsInRaw (related-docs.ts) と同じ行差し替え方式を採用する。
+ *
+ * - setDependsOnInRaw: frontmatter の depends_on 配列だけを置換/追加する
+ * - setPriorityInRaw:  frontmatter の priority スカラだけを置換/追加する
+ *
+ * 本文・他フィールド・改行コード・コメントは完全に保全する。
+ * frontmatter が見つからない raw はそのまま返す。
+ */
+// frontmatter 境界: 先頭の `---` 行 (行末空白を許容、parseTaskFile / setRelatedDocsInRaw と同じ規約)
+const FM_OPEN = /^---[ \t]*\r?\n/;
+// 閉じ `---` 行 (行末空白許容)
+const FM_CLOSE = /^---[ \t]*$/;
+// BOM は literal 禁止 (LEARN#13: invisible unicode は \uXXXX escape で書く)
+const BOM = '\uFEFF';
+// ---------------------------------------------------------------------------
+// 内部ユーティリティ
+// ---------------------------------------------------------------------------
+/**
+ * raw から BOM を剥がし、処理後に復元するラッパー。
+ * setRelatedDocsInRaw と同じ規約 (R13-1)。
+ */
+function withBomHandling(raw, fn) {
+    const hasBom = raw.startsWith(BOM);
+    const body = hasBom ? raw.slice(1) : raw;
+    const result = fn(body);
+    return hasBom ? BOM + result : result;
+}
+/**
+ * frontmatter 内の指定 key の行 (flow 1 行 or block 形式 key+続く`- `行) を除去し、
+ * フロントマターの行配列 (開き`---`を除く、閉じ`---`を除く範囲) を返す。
+ * また閉じ `---` のインデックスと全行配列も返す。
+ */
+function parseFrontmatterLines(raw) {
+    if (!FM_OPEN.test(raw))
+        return null;
+    const lines = raw.split('\n');
+    let closeIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (FM_CLOSE.test(lines[i].replace(/\r$/, ''))) {
+            closeIdx = i;
+            break;
+        }
+    }
+    if (closeIdx === -1)
+        return null;
+    return { lines, closeIdx };
+}
+/**
+ * frontmatter 内の指定 key の行 (flow or block) を除去した行配列を返す。
+ * kept は開き `---` の次から closeIdx の手前までの内容 (閉じ `---` は含まない)。
+ */
+function removeKeyLines(lines, closeIdx, key) {
+    const keyPattern = new RegExp(`^${key}\\s*:`);
+    const kept = [];
+    let i = 1;
+    while (i < closeIdx) {
+        const line = lines[i].replace(/\r$/, '');
+        if (keyPattern.test(line)) {
+            i++;
+            // block 形式: 続く `- ` 行も取り除く (ゼロインデントも対象。setRelatedDocsInRaw R13-4 と同方式)
+            while (i < closeIdx && /^\s*-\s/.test(lines[i].replace(/\r$/, '')))
+                i++;
+            continue;
+        }
+        kept.push(lines[i]);
+        i++;
+    }
+    return kept;
+}
+/**
+ * `kept` 行配列にフィールドを挿入し、raw 全体を再組み立てして返す。
+ * 挿入位置: created: 行の直前、なければ末尾 (setRelatedDocsInRaw と同じ規約)。
+ * newLine が null の場合は挿入しない (フィールド除去のみ)。
+ */
+function rebuildRaw(lines, closeIdx, kept, newLine) {
+    if (newLine !== null) {
+        const createdIdx = kept.findIndex((l) => /^created\s*:/.test(l.replace(/\r$/, '')));
+        if (createdIdx !== -1) {
+            kept.splice(createdIdx, 0, newLine);
+        }
+        else {
+            kept.push(newLine);
+        }
+    }
+    const head = [lines[0], ...kept].join('\n');
+    const tail = lines.slice(closeIdx).join('\n');
+    return `${head}\n${tail}`;
+}
+// ---------------------------------------------------------------------------
+// 公開 API
+// ---------------------------------------------------------------------------
+/**
+ * raw (frontmatter + 本文) の depends_on 行を ids で差し替えた raw を返す。
+ * - ids が空: depends_on 行 (flow 1 行 or block 形式) を除去する
+ * - ids が非空: JSON.stringify 済み flow 形式 1 行
+ *   (`depends_on: ["TASK-001", "TASK-002"]`) に置換/挿入する。
+ *   setRelatedDocsInRaw と同じ表現スタイルに統一する (仕様「配列表現は existing に合わせる」)。
+ * - frontmatter が無い raw はそのまま返す
+ */
+export function setDependsOnInRaw(raw, ids) {
+    return withBomHandling(raw, (body) => setDependsOnInner(body, ids));
+}
+function setDependsOnInner(raw, ids) {
+    const parsed = parseFrontmatterLines(raw);
+    if (!parsed)
+        return raw;
+    const { lines, closeIdx } = parsed;
+    const kept = removeKeyLines(lines, closeIdx, 'depends_on');
+    // setRelatedDocsInRaw と同じ JSON.stringify flow 形式 (YAML double-quoted として常に valid)
+    const newLine = ids.length > 0 ? `depends_on: [${ids.map((id) => JSON.stringify(id)).join(', ')}]` : null;
+    return rebuildRaw(lines, closeIdx, kept, newLine);
+}
+/**
+ * raw (frontmatter + 本文) の priority 行を priority で差し替えた raw を返す。
+ * - フィールドが無ければ created: 行の直前 (無ければ閉じ `---` の直前) に追加する
+ * - フィールドが既にあれば値だけ置換する
+ * - frontmatter が無い raw はそのまま返す
+ */
+export function setPriorityInRaw(raw, priority) {
+    return withBomHandling(raw, (body) => setPriorityInner(body, priority));
+}
+function setPriorityInner(raw, priority) {
+    const parsed = parseFrontmatterLines(raw);
+    if (!parsed)
+        return raw;
+    const { lines, closeIdx } = parsed;
+    const kept = removeKeyLines(lines, closeIdx, 'priority');
+    const newLine = `priority: ${priority}`;
+    return rebuildRaw(lines, closeIdx, kept, newLine);
+}