@kybird/llm-wiki 0.2.1 → 0.3.0

package/lib/kanban-wait.js

@@ -0,0 +1,215 @@
+// llm-wiki wait — 보드 활동 로그(doc/kanban/activity.jsonl)의 이벤트를 기다렸다 종료하는
+// 읽기 전용 명령. 무인 루프가 밤새 handoff 판정을 폴링하지 않게 한다 — 호출자는 이 명령을
+// 백그라운드에 걸어 두고 프로세스 종료를 신호로 쓴다. 아무 일이 없으면 아무 비용도 없다.
+//
+// 종료 코드가 이 명령의 계약이다:
+//   0    이벤트 감지 — 해당 이벤트를 stdout 한 줄로 출력
+//   2    타임아웃 — 아무것도 출력하지 않는다. 호출자는 조용히 재무장
+//   1    오류 — 모르는 플래그, 해석 불가능한 --since/--timeout/--stall-min, 파일 접근 불가
+//   130  SIGINT/SIGTERM — 호출자가 죽였다
+//
+// 견고성 규칙(2026-09-12 병합 충돌로 activity.jsonl이 통째로 재작성된 실측에서 나온 것들):
+//   - 바이트 오프셋을 기억하지 않는다. 파일은 10k 줄 캡(appendActivity)이나 병합 수습으로
+//     통째로 다시 쓰인다 — 매번 처음부터 읽고 타임스탬프로 거른다.
+//   - 파일이 없어도 죽지 않는다(init 전·이벤트 0회). 생길 때까지 기다린다.
+//   - JSON 파싱에 실패한 줄은 건너뛴다 — 실제로 병합 충돌 마커가 섞인 적이 있다.
+//   - fs.watch + 저주기 폴링(기본 5초)을 항상 함께 돈다. doc/이 링크 워크트리의 정션
+//     너머에 있으면(find-doc-root) Windows fs.watch가 이벤트를 놓친다.
+const fs = require('fs');
+const path = require('path');
+const { findDocRoot } = require('./find-doc-root');
+const kanban = require('./kanban');
+const { parseArgs, validateFlags, fail } = require('./kanban-cmd');
+
+const POLL_MS_DEFAULT = 5000;
+const FILTERS = ['handoff', 'done', 'any', 'stall'];
+
+// ts 필드를 밀리초로 — ts 없음·해석 불가는 이벤트로 치지 않는다.
+function eventTs(ev) {
+  if (!ev || typeof ev.ts !== 'string') return null;
+  const t = Date.parse(ev.ts);
+  return Number.isNaN(t) ? null : t;
+}
+
+function wait({ rest, json } = {}) {
+  const { positional, flags } = parseArgs(rest || []);
+  if (positional.length) fail(`wait는 위치 인자를 받지 않는다: ${positional.join(' ')}`);
+  validateFlags(flags, {
+    for: 'string',
+    since: 'string',
+    timeout: 'string',
+    'stall-min': 'string',
+  });
+
+  // 단일값 플래그 — 반복 지정(--for a --for b)은 parseArgs가 배열로 누적하므로 거부.
+  const single = (v, name) => {
+    if (Array.isArray(v)) fail(`--${name}은 한 번만 쓸 수 있다`);
+    return v;
+  };
+
+  const filter = flags.for === undefined ? 'handoff' : single(flags.for, 'for');
+  if (!FILTERS.includes(filter)) {
+    fail(`--for은 ${FILTERS.join(' | ')} 중 하나여야 한다 — 받은 값: ${filter}`);
+  }
+
+  const sinceRaw = flags.since === undefined ? new Date().toISOString() : single(flags.since, 'since');
+  const sinceMs = Date.parse(sinceRaw);
+  if (Number.isNaN(sinceMs)) {
+    fail(`--since "${sinceRaw}"를 시각으로 해석할 수 없다 — ISO 8601 형태로 준다 (예: 2026-09-12T00:00:00Z)`);
+  }
+
+  const timeoutSec = flags.timeout === undefined ? null : Number(single(flags.timeout, 'timeout'));
+  if (timeoutSec !== null && (Number.isNaN(timeoutSec) || timeoutSec < 0)) {
+    fail(`--timeout은 0 이상의 숫자(초)여야 한다 — 받은 값: ${single(flags.timeout, 'timeout')} (0 = 기다리지 않는다)`);
+  }
+
+  // 소수 분을 허용한다(예: 0.05 = 3초) — 회귀 테스트가 분 단위를 기다리지 않게.
+  const stallMin = flags['stall-min'] === undefined ? 20 : Number(single(flags['stall-min'], 'stall-min'));
+  if (Number.isNaN(stallMin) || stallMin <= 0) {
+    fail(`--stall-min은 0보다 큰 숫자(분)여야 한다 — 받은 값: ${single(flags['stall-min'], 'stall-min')}`);
+  }
+
+  const activityPath = kanban.kanbanPaths(findDocRoot()).activityPath;
+  const stallMs = stallMin * 60e3;
+  const pollMs = Math.max(50, Number(process.env.LLM_WIKI_WAIT_POLL_MS) || POLL_MS_DEFAULT);
+  const startedAt = Date.now();
+
+  let watcher = null;
+  let pollTimer = null;
+  let timeoutTimer = null;
+  let stallTimer = null;
+  let finished = false;
+  // stall 기준점 — --since 이후 활동이 없으면 since 시각 자체가 마지막 활동이 된다.
+  let lastActivityMs = sinceMs;
+
+  // 종료는 출력 이후에 — Windows 파이프 stdout은 비동기라 쓰기 완료 전에 루프가 마르면
+  // 그 한 줄이 유실된다(이벤트는 감지했는데 호출자가 못 받는 상태). 쓰기 완료 콜백에서
+  // 명시 종료한다. 콜백이 오지 않는 극단적 경우를 대비해 exitCode도 심어둔다.
+  function finish(code, line) {
+    if (finished) return;
+    finished = true;
+    if (watcher) { try { watcher.close(); } catch { /* 이미 닫혔다 */ } }
+    if (pollTimer) clearInterval(pollTimer);
+    if (timeoutTimer) clearTimeout(timeoutTimer);
+    if (stallTimer) clearTimeout(stallTimer);
+    if (line !== undefined) {
+      process.exitCode = code;
+      process.stdout.write(`${line}\n`, () => process.exit(code));
+    } else {
+      process.exit(code);
+    }
+  }
+
+  // activity.jsonl 전체를 매번 다시 읽는다(오프셋 금지 규칙). 깨진 줄은 건너뛴다.
+  function readEvents() {
+    let content;
+    try {
+      content = fs.readFileSync(activityPath, 'utf8');
+    } catch (e) {
+      if (e.code === 'ENOENT') return []; // 아직 없다 — 생길 때까지 기다린다
+      throw e;
+    }
+    const events = [];
+    for (const line of content.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+        // 깨진 줄(병합 충돌 마커·잘린 쓰기)은 건너뛴다.
+      }
+    }
+    return events;
+  }
+
+  // --since 이후(엄격히 초과 — 같은 이벤트에 다시 깨지 않는다)의 이벤트 중 필터에 맞는
+  // 첫 줄을 돌려준다. stall 기준점(lastActivityMs)은 필터와 무관하게 모든 액션이 갱신한다.
+  function scan() {
+    let matched = null;
+    for (const ev of readEvents()) {
+      const t = eventTs(ev);
+      if (t === null || t <= sinceMs) continue;
+      if (t > lastActivityMs) lastActivityMs = t;
+      if (!matched && (filter === 'any' || ev.action === filter)) matched = ev;
+    }
+    return matched;
+  }
+
+  function emitEvent(ev) {
+    finish(0, json
+      ? JSON.stringify(ev)
+      : `${ev.ts} ${ev.action} ${ev.title !== undefined ? ev.title : ''}`.trimEnd());
+  }
+
+  // stall 발사 — 마지막 활동(또는 --since)으로부터 stall-min 분의 침묵이 확인됐다.
+  // 새 활동이 오면 lastActivityMs가 밀리고 check()가 다시 부르므로 마감도 밀린다.
+  function armStall() {
+    if (stallTimer) clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => {
+      finish(0, json
+        ? JSON.stringify({ ts: new Date().toISOString(), action: 'stall', since: sinceRaw, stallMinutes: stallMin })
+        : `stall — ${stallMin}분간 새 이벤트 없음 (since ${sinceRaw})`);
+    }, Math.max(0, lastActivityMs + stallMs - Date.now()));
+  }
+
+  // watch 이벤트는 한 쓰기에 여러 번 터진다 — setImmediate로 한 틱에 모아 한 번 검사한다.
+  let checkScheduled = false;
+  function check() {
+    if (finished || checkScheduled) return;
+    checkScheduled = true;
+    setImmediate(() => {
+      checkScheduled = false;
+      if (finished) return;
+      try {
+        const ev = scan();
+        if (filter === 'stall') armStall();
+        else if (ev) emitEvent(ev);
+      } catch (e) {
+        fail(`activity.jsonl을 읽을 수 없다: ${e.message}`);
+      }
+    });
+  }
+
+  // 진입 검사 — 대기에 들어가기 전에 --since 이후의 기존 이벤트를 먼저 본다. 호출자가
+  // 이전 이벤트를 처리하는 동안 쌓인 것을 놓치지 않는 것이 이 명령의 핵심 계약이다.
+  try {
+    const existing = scan();
+    if (filter !== 'stall' && existing) {
+      emitEvent(existing);
+      return;
+    }
+  } catch (e) {
+    fail(`activity.jsonl을 읽을 수 없다: ${e.message}`);
+  }
+
+  // 대기 진입 알림은 stderr — stdout은 계약상 이벤트 한 줄 전용이다.
+  console.error(`waiting: for=${filter} since=${sinceRaw}` +
+    (timeoutSec !== null ? ` timeout=${timeoutSec}s` : '') +
+    (filter === 'stall' ? ` stall-min=${stallMin}` : '') +
+    ` file=${activityPath} (Ctrl+C to stop)`);
+
+  if (filter === 'stall') armStall(); // lastActivityMs는 진입 검사에서 갱신됐다
+
+  // 감시 대상은 디렉터리다 — activity.jsonl은 통째로 다시 쓰일 수 있어 파일 단위 watch
+  // 핸들이 끊기고, 파일 생성 이벤트도 디렉터리에서 잡힌다.
+  try {
+    watcher = fs.watch(path.dirname(activityPath), (_evt, filename) => {
+      if (filename && path.basename(activityPath) !== filename) return;
+      check();
+    });
+    watcher.on('error', () => { /* 감시 실패 — 아래 폴링이 잡는다 */ });
+  } catch {
+    // 감시 실패(정션 너머 등) — 아래 폴링이 잡는다
+  }
+
+  // 저주기 폴링 폴백 — watch가 이벤트를 놓쳐도 이것이 잡는다(항상 함께 돈다).
+  pollTimer = setInterval(check, pollMs);
+
+  process.on('SIGINT', () => finish(130));
+  process.on('SIGTERM', () => finish(130));
+
+  if (timeoutSec !== null) {
+    timeoutTimer = setTimeout(() => finish(2), Math.max(0, startedAt + timeoutSec * 1000 - Date.now()));
+  }
+}
+
+module.exports = { wait };

package/lib/kanban.js

@@ -52,7 +52,7 @@ function loadConfig(paths) {
   const lines = fs.readFileSync(paths.boardYmlPath, 'utf8').split(/\r?\n/);
   let inWip = false;
   for (const line of lines) {
-    const statusMatch = line.match(/^statuses:\s*\[(.*)\]/);
+    const statusMatch = line.match(/^statuses:\s*\[([^\]]*)\]/);
     if (statusMatch) {
       config.statuses = statusMatch[1].split(',').map(s => s.trim()).filter(Boolean);
       continue;
@@ -86,6 +86,9 @@ function slugify(title) {
 // ── 카드 파싱/직렬화 ─────────────────────────────────────────────────────
 
 // frontmatter의 `key: value` / `key: [a, b]`만 다룬다. 중첩 없음.
+// 값 형태 보존 계약(2026-09-09 리뷰 5-2): 배열은 JSON 꼴로 감싸 원소의 쉼표까지
+// 왕복하고, 배열·따옴표로 보이는 문자열은 역따옴표로 감싸 재파싱에서 변형되지
+// 않게 한다. 따옴표 박리는 짝이 맞을 때만(비대칭 `"a'` → `a'` 문자열 보존).
 function parseFrontmatter(content) {
   const meta = {};
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
@@ -94,11 +97,27 @@ function parseFrontmatter(content) {
     const kv = line.match(/^(\w+):\s*(.*)$/);
     if (!kv) continue;
     const [, key, rawValue] = kv;
-    const listMatch = rawValue.match(/^\[(.*)\]$/);
-    if (listMatch) {
-      meta[key] = listMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+    const trimmed = rawValue.trim();
+    const quoted = trimmed.match(/^("|')([\s\S]*)\1$/);
+    if (quoted) {
+      // 쌍따옴표는 직렬화가 JSON.stringify로 감쌌다 — 역이스케이프까지 왕복하려면
+      // JSON.parse가 정확하다(내부 따옴표 `\"` 등). 실패(비JSON 레거시)면 내부 원문.
+      if (quoted[1] === '"') {
+        try { meta[key] = JSON.parse(trimmed); } catch { meta[key] = quoted[2]; }
+      } else {
+        meta[key] = quoted[2]; // 홑따옴표 — 이스케이프 규약 없음, 내부 그대로
+      }
+    } else if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      // JSON 꼴(원소 따옴표)이면 원소의 쉼표·괄호까지 정확히 왕복한다.
+      try {
+        const arr = JSON.parse(trimmed);
+        meta[key] = Array.isArray(arr) ? arr.map(String) : trimmed;
+      } catch {
+        // 비인용 레거시 `[a, b]` — 쉼표 분해 외에 방법이 없다(원소 쉼표는 원래 손실).
+        meta[key] = trimmed.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+      }
     } else {
-      meta[key] = rawValue.trim().replace(/^["']|["']$/g, '');
+      meta[key] = trimmed;
     }
   }
   return meta;
@@ -107,8 +126,13 @@ function parseFrontmatter(content) {
 function serializeFrontmatter(meta) {
   const lines = ['---'];
   for (const [key, value] of Object.entries(meta)) {
-    if (Array.isArray(value)) lines.push(`${key}: [${value.join(', ')}]`);
-    else if (value !== undefined && value !== '') lines.push(`${key}: ${value}`);
+    if (Array.isArray(value)) {
+      lines.push(`${key}: ${JSON.stringify(value)}`);
+    } else if (value !== undefined && value !== '') {
+      const s = String(value);
+      // `[a, b]` 모양 제목이 재파싱에서 배열로 변형되지 않게 따옴표로 감싼다.
+      lines.push(`${key}: ${s.startsWith('[') || /^["']/.test(s) ? JSON.stringify(s) : s}`);
+    }
   }
   lines.push('---');
   return lines.join('\n');
@@ -127,7 +151,13 @@ function parseBody(content) {
   if (acMatch) {
     for (const line of acMatch[1].split(/\r?\n/)) {
       const ac = line.match(/^-\s+\[( |x)\]\s+#(\d+)\s+(.*)$/);
-      if (ac) card.ac.push({ checked: ac[1] === 'x', idx: Number(ac[2]), text: ac[3] });
+      if (ac) {
+        card.ac.push({ checked: ac[1] === 'x', idx: Number(ac[2]), text: ac[3] });
+      } else if (line.trim() && card.ac.length) {
+        // 센티넬 안의 비-AC 줄(예: AC 텍스트의 줄바꿈 연속행)은 앞 항목에 붙인다 —
+        // 그냥 버리면 왕복에서 소실된다(2026-09-09 리뷰 5-2).
+        card.ac[card.ac.length - 1].text += '\n' + line;
+      }
     }
   }
 
@@ -157,6 +187,21 @@ function parseBody(content) {
   return card;
 }
 
+// CLI가 관리하는 섹션명 — 본문에 이 이름과 정확히 같은 모양의 `## ` 줄이 있으면
+// 다음 파싱에서 진짜 섹션 경계로 오인된다. Notes에 `## Goal`을 적은 경우 뒷줄이
+// 전부 삭제되기까지 했다(2026-09-09 리뷰 5-1-2) — append-only 계약의 정면 반례.
+const MANAGED_SECTIONS = ['Goal', 'Acceptance Criteria', 'Plan', 'Notes', 'Handoff', 'Result'];
+
+// 섹션 본문을 쓸 때 관리 섹션명과 같은 모양의 줄은 앞에 공백을 하나 붙여 이스케이프한다.
+// ` ## Goal`은 `^##\s` 경계와 안 겹치므로 영구히 본문으로 남는다.
+function escapeSectionBody(text) {
+  if (!text) return text || '';
+  return String(text).split(/\r?\n/).map(line => {
+    const header = line.match(/^##\s+(.+?)\s*$/);
+    return header && MANAGED_SECTIONS.includes(header[1]) ? ` ${line}` : line;
+  }).join('\n');
+}
+
 // Goal/AC는 센티넬과 함께, 나머지 섹션은 헤더만으로 직렬화.
 // Notes는 append-only 저널이라 CLI가 줄을 덧붙인다 — 전체를 재조립하지 않는 섹션 단위
 // 재작성을 위해 항상 고정 순서(Goal, AC, Plan, Notes, Handoff, Result, 기타)로 출력.
@@ -177,14 +222,14 @@ function serializeCard(meta, parsed) {
   const order = ['Plan', 'Notes', 'Handoff', 'Result'];
   for (const name of order) {
     out.push(`## ${name}`);
-    out.push(parsed.sections.get(name) || '');
+    out.push(escapeSectionBody(parsed.sections.get(name)));
     out.push('');
   }
   // CLI가 모르는 섹션도 지우지 않는다 — 맨 뒤에 보존.
   for (const [name, bodyText] of parsed.sections) {
     if (order.includes(name)) continue;
     out.push(`## ${name}`);
-    out.push(bodyText || '');
+    out.push(escapeSectionBody(bodyText));
     out.push('');
   }
   return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n+$/, '\n');
@@ -236,10 +281,16 @@ function writeCard(cardObj, newMeta, newParsed) {
 // 종결 이동 — 파일 이동 + frontmatter status를 폴더와 일치시킨다.
 function moveCardTo(cardObj, targetDir, statusValue) {
   fs.mkdirSync(targetDir, { recursive: true });
+  const targetPath = path.join(targetDir, cardObj.fileName);
+  // 종결 폴더의 기록은 지우지 않는다(3.3) — 같은 이름이 이미 있으면 조용히 덮어쓰는
+  // 대신 거부한다(2026-09-09 리뷰 5-1-3: 재생성 카드의 두 번째 done이 아카이브 Result를 소멸시켰다).
+  if (fs.existsSync(targetPath)) {
+    throw new Error(`종결 폴더에 같은 이름의 카드가 이미 있다: ${targetPath} — 아카이브 덮어쓰기를 거부한다. 제목을 바꿔 재생성하라.`);
+  }
   const content = fs.readFileSync(cardObj.filePath, 'utf8');
   const meta = parseFrontmatter(content);
   meta.status = statusValue;
-  fs.writeFileSync(path.join(targetDir, cardObj.fileName), serializeCard(meta, parseBody(content)));
+  fs.writeFileSync(targetPath, serializeCard(meta, parseBody(content)));
   fs.unlinkSync(cardObj.filePath);
 }
 
@@ -277,8 +328,15 @@ function isClaimExpired(cardObj, config, now = Date.now()) {
 
 // ── 파일 락 — 잠금 폴더 mkdir 원자성 (Windows 호환) ─────────────────────
 
+// 모든 카드 변이 명령이 통과하는 공용 락 이름. pick만의 락이 아니라 보드 전체
+// 단일 쓰기자 직렬화다 — pick이 'pick', done이 'done'으로 나뉘면 서로 동시에
+// 돌아 이중 상태(활성+종결 동시 존재)를 만든다.
+const BOARD_LOCK_NAME = 'write';
+
 // mkdir은 이미 존재하면 EEXIST로 실패하는 원자적 연산이라 락으로 쓴다.
 // 락 폴더 안 lock.json에 {pid, at}을 남겨, LOCK_STALE_MS가 지나면 강탈 허용.
+// lock.json 없는 고아 폴더(mkdir과 marker 사이에 죽은 프로세스의 흔적)는
+// 폴더 mtime으로 판정해 강탈한다 — 없으면 영원히 획득 불가능해진다.
 function withLock(paths, name, fn) {
   const lockPath = path.join(paths.lockDir, name);
   fs.mkdirSync(paths.lockDir, { recursive: true });
@@ -291,7 +349,8 @@ function withLock(paths, name, fn) {
       if (e.code !== 'EEXIST') throw e;
       // 이미 락이 있다 — 오래됐으면 강탈 (한 번만)
       const markerPath = path.join(lockPath, 'lock.json');
-      if (!stolen && fs.existsSync(markerPath)) {
+      if (stolen) return false;
+      if (fs.existsSync(markerPath)) {
         try {
           const { at } = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
           if (Date.now() - at > LOCK_STALE_MS) {
@@ -299,6 +358,14 @@ function withLock(paths, name, fn) {
             return acquire(true);
           }
         } catch { /* 판정 불가 — 락 유지로 간주 */ }
+      } else {
+        // 고아 락 폴더 — marker가 없으니 폴더 mtime이 유일한 단서다.
+        try {
+          if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+            fs.rmSync(lockPath, { recursive: true, force: true });
+            return acquire(true);
+          }
+        } catch { /* 판정 불가 — 락 유지로 간주 */ }
       }
       return false;
     }
@@ -307,11 +374,19 @@ function withLock(paths, name, fn) {
   if (!acquire()) {
     throw new Error(`칸반 락 획득 실패: ${name} — 다른 세션이 보드를 고치는 중. 잠시 후 재시도.`);
   }
+  // 반납 이중 보험: 콜백 안의 fail()이 process.exit를 치면 finally가 안 돈다
+  // (실측: 만료 클레임 renew 거부 직후 락이 누출). exit 핸들러는 동기 코드를
+  // 돌리므로 rmSync로 반납을 보장한다.
+  const release = () => {
+    try { fs.rmSync(lockPath, { recursive: true, force: true }); } catch { /* 이미 없음 */ }
+  };
+  process.on('exit', release);
   try {
     fs.writeFileSync(path.join(lockPath, 'lock.json'), JSON.stringify({ pid: process.pid, at: Date.now() }));
     return fn();
   } finally {
-    fs.rmSync(lockPath, { recursive: true, force: true });
+    process.removeListener('exit', release);
+    release();
   }
 }
 
@@ -343,6 +418,7 @@ module.exports = {
   ACTIVE_STATUSES,
   TERMINAL_FOLDERS,
   DEFAULT_CONFIG,
+  BOARD_LOCK_NAME,
   kanbanPaths,
   loadConfig,
   slugify,

package/lib/local-today.js

@@ -0,0 +1,9 @@
+// "오늘"은 현지 날짜로 — raw 로그 헤더·카드 created·not_before 게이트가 전부 현지
+// 날짜로 쓰인다. UTC(toISOString)와 섞으면 KST 자정~9시 사이에 판정이 하루 어긋난다
+// (2026-08-30 lastCompiled 실측 → 4c5f27c, 2026-09-09 칸반 6곳 동일 적용 → 개선계획 5-1-5).
+function localToday(date = new Date()) {
+  const pad = n => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+module.exports = { localToday };