@ps-neko/nekowork 0.1.0-alpha.0

package/scripts/agents/runners/mock.js

@@ -0,0 +1,107 @@
+// Mock runner: LLM 호출 없이 결정론적 응답 생성. 오케스트레이터 단위 테스트와
+// API 키 / CLI 미설치 환경에서의 dry-run 디폴트.
+//
+// 단계별로 의도된 시나리오를 흉내낸다:
+//   - planner: AC 3개의 PRD 시드
+//   - executor: 작업 완료 보고
+//   - code-reviewer: round 1 에서 high 1 발견 (fix loop 유도), round 2 에서 approve
+//   - codex-reviewer: medium 1 추가 발견 후 approve_with_fixes
+//   - codex-challenger: info 1 발견 후 approve
+//   - doc-writer: ship 보고
+
+export async function runMock({ agent, stage, task, context }) {
+  const round = context.round || 1;
+
+  switch (stage) {
+    case 'ideate':
+      return {
+        decided: `"${task}" 의 후보 접근 비교. 라이브러리 X 채택.`,
+        rejected: '자체 구현(유지보수 부담)',
+        risks: '엣지 케이스 미식별',
+        files: [],
+        remaining: 'planner 에 PRD 시드 핸드오프',
+      };
+
+    case 'plan':
+      return {
+        decided: `${task} 를 AC 3개로 분해. TDD 강제.`,
+        rejected: '범위 확장(키 회전 / 리프레시 토큰 = non-goal)',
+        risks: '의존성 라이브러리 호환',
+        files: ['prd.json'],
+        remaining: 'executor 에 핸드오프',
+        prdSeed: {
+          task,
+          acceptance: [
+            { id: 'AC-001', desc: '핵심 기능 happy path', passes: false },
+            { id: 'AC-002', desc: '실패 케이스 거절', passes: false },
+            { id: 'AC-003', desc: '경계 / 잘못된 입력 거절', passes: false },
+          ],
+          non_goals: ['키 회전', '리프레시 토큰'],
+        },
+      };
+
+    case 'implement':
+      return {
+        decided: `TDD ${context.acCount || 3} 사이클. AC 모두 GREEN. quality-gate 통과.`,
+        files: ['src/<area>/<module>.ts', 'tests/unit/<module>.test.ts'],
+        remaining: 'self-review',
+      };
+
+    case 'self-review':
+      if (round === 1) {
+        return {
+          decided: 'high 1, medium 1 발견. fix loop 진입.',
+          files: ['src/<area>/<module>.ts'],
+          remaining: 'fix loop',
+          issues: [
+            { severity: 'high', category: 'security', file: 'src/<area>/<module>.ts', line: 23,
+              summary: '입력 검증 누락', why: '경계 케이스를 거절하지 않음' },
+            { severity: 'medium', category: 'test', file: 'tests/unit/<module>.test.ts',
+              summary: 'happy path 외 커버리지 부족', why: '실패 케이스 단언 없음' },
+          ],
+          verdict: 'approve_with_fixes',
+          confidence: 0.85,
+        };
+      }
+      return {
+        decided: '이전 high 해결. 추가 발견 0건.',
+        files: ['src/<area>/<module>.ts'],
+        remaining: 'codex-review',
+        verdict: 'approve',
+        confidence: 0.92,
+      };
+
+    case 'codex-review':
+      return {
+        decided: 'self-review 와 일치. 추가 medium 1 (timeout 미설정).',
+        files: ['src/<area>/<module>.ts'],
+        remaining: '--secure 시 단계 6, 아니면 단계 7',
+        issues: [{ severity: 'medium', category: 'correctness',
+          file: 'src/<area>/<module>.ts',
+          summary: 'fetch timeout 미설정', why: '무한 대기 가능' }],
+        verdict: 'approve_with_fixes',
+        confidence: 0.88,
+      };
+
+    case 'codex-challenge':
+      return {
+        decided: '적대적 시나리오 5건 검토. 신규 critical 0, high 0, info 1.',
+        files: [],
+        remaining: 'ship',
+        issues: [{ severity: 'info', category: 'security',
+          summary: 'replay 방어 권장 (현 PRD non-goal)', why: 'jti / replay cache 향후 고려' }],
+        verdict: 'approve',
+        confidence: 0.95,
+      };
+
+    case 'ship':
+      return {
+        decided: 'CHANGELOG 갱신, PR 본문 한국어 초안 작성. 자동 push 안 함 (사용자 룰).',
+        files: ['docs/CHANGELOG.md', 'WORKING-CONTEXT.md'],
+        remaining: '사용자 검토 후 gh pr create 또는 git push 수동',
+      };
+
+    default:
+      throw new Error(`unknown stage: ${stage}`);
+  }
+}

package/scripts/auth/github-import-gh.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Import the already-authenticated GitHub CLI OAuth token into the HARNESS vault.
+// This is an explicit local-session bridge, not a static API-key path.
+
+import { spawnSync } from 'node:child_process';
+import { save, audit, redact } from '../lib/token-vault.js';
+
+function runGh(args) {
+  const r = spawnSync('gh', args, {
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (r.status !== 0) {
+    throw new Error(`gh ${args.join(' ')} failed\n${r.stderr || r.stdout}`);
+  }
+  return r.stdout.trim();
+}
+
+function parseScopes(statusText) {
+  const line = statusText.split(/\r?\n/).find((l) => /Token scopes:/i.test(l));
+  if (!line) return 'unknown';
+  return line
+    .replace(/^.*Token scopes:\s*/i, '')
+    .split(',')
+    .map((s) => s.replace(/['"]/g, '').trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+(async () => {
+  try {
+    audit('auth.github.import_gh.requested', { provider: 'github' });
+    const status = runGh(['auth', 'status']);
+    const token = runGh(['auth', 'token']);
+    const scope = parseScopes(status);
+    const location = await save('github', {
+      access_token: token,
+      token_type: 'token',
+      scope,
+      source: 'gh-cli',
+    });
+    audit('auth.github.import_gh', { provider: 'github', scope, source: 'gh-cli' });
+    process.stdout.write('GitHub gh session imported into HARNESS vault.\n');
+    process.stdout.write(`  backend/path : ${location}\n`);
+    process.stdout.write(`  scope        : ${scope}\n`);
+    process.stdout.write(`  token        : ${redact(token)}\n`);
+  } catch (e) {
+    audit('auth.github.import_gh.failed', { provider: 'github', error: String(e.message || e) });
+    process.stderr.write(`${e.message || e}\n`);
+    process.exit(1);
+  }
+})();

package/scripts/auth/github-login.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// GitHub OAuth Device Flow.
+// 사전 조건: HARNESS_GITHUB_CLIENT_ID 환경변수 (사용자가 자기 OAuth App 등록 후 받은 client_id).
+// 자세한 절차는 docs/AUTH-MIGRATION.md §5.3.
+
+import { save, audit } from '../lib/token-vault.js';
+
+const CLIENT_ID = process.env.HARNESS_GITHUB_CLIENT_ID;
+const SCOPES = (process.env.HARNESS_GITHUB_SCOPES || 'repo workflow').replace(/,/g, ' ');
+
+if (!CLIENT_ID) {
+  process.stderr.write('환경변수 HARNESS_GITHUB_CLIENT_ID 가 필요합니다.\n');
+  process.stderr.write('  1) https://github.com/settings/developers → New OAuth App\n');
+  process.stderr.write('  2) "Enable Device Flow" 체크\n');
+  process.stderr.write('  3) export HARNESS_GITHUB_CLIENT_ID=<your_client_id>\n');
+  process.exit(2);
+}
+
+async function startDevice() {
+  const r = await fetch('https://github.com/login/device/code', {
+    method: 'POST',
+    headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ client_id: CLIENT_ID, scope: SCOPES }),
+  });
+  if (!r.ok) throw new Error(`device/code 실패 ${r.status}: ${await r.text()}`);
+  return r.json();
+}
+
+async function poll(deviceCode, intervalSec) {
+  let interval = intervalSec || 5;
+  while (true) {
+    await new Promise((res) => setTimeout(res, interval * 1000));
+    const r = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        client_id: CLIENT_ID,
+        device_code: deviceCode,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      }),
+    });
+    const data = await r.json();
+    if (data.access_token) return data;
+    if (data.error === 'authorization_pending') continue;
+    if (data.error === 'slow_down') { interval += 5; continue; }
+    if (data.error === 'expired_token' || data.error === 'access_denied') {
+      throw new Error(`인증 실패: ${data.error}`);
+    }
+    throw new Error(`알 수 없는 응답: ${JSON.stringify(data)}`);
+  }
+}
+
+(async () => {
+  try {
+    audit('auth.token_issued.requested', { provider: 'github', scopes: SCOPES });
+    const dev = await startDevice();
+    process.stdout.write('\n=== GitHub OAuth Device Flow ===\n');
+    process.stdout.write(`URL  : ${dev.verification_uri}\n`);
+    process.stdout.write(`코드 : ${dev.user_code}\n`);
+    process.stdout.write(`만료 : ${Math.floor((dev.expires_in || 900) / 60)}분\n`);
+    process.stdout.write('\n브라우저에서 위 URL 을 열고 코드를 입력하세요. 완료될 때까지 폴링합니다...\n\n');
+
+    const tok = await poll(dev.device_code, dev.interval || 5);
+    const file = await save('github', {
+      access_token: tok.access_token,
+      token_type: tok.token_type || 'bearer',
+      scope: tok.scope,
+    });
+    audit('auth.token_issued', { provider: 'github', scope: tok.scope, token_type: tok.token_type });
+
+    process.stdout.write(`✓ 저장됨: ${file}\n`);
+    process.stdout.write(`  scope: ${tok.scope}\n`);
+    process.exit(0);
+  } catch (e) {
+    audit('auth.token_issued.failed', { provider: 'github', error: String(e.message || e) });
+    process.stderr.write(`✗ ${e.message || e}\n`);
+    process.exit(1);
+  }
+})();

package/scripts/auth/github-logout.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// GitHub OAuth 로그아웃. 로컬 vault 만 삭제.
+// 주의: device flow 는 client secret 이 없으므로 GitHub 측 revoke API 호출 불가.
+// GitHub 측에서도 폐기하려면 사용자가 https://github.com/settings/applications 에서 직접 처리.
+
+import { remove, audit } from '../lib/token-vault.js';
+
+(async () => {
+  const ok = await remove('github');
+  audit('auth.token_revoked', { provider: 'github', local_only: true });
+
+  if (ok) {
+    process.stdout.write('✓ 로컬 vault 에서 GitHub token 삭제됨.\n');
+    process.stdout.write('  GitHub 측에서도 폐기하려면:\n');
+    process.stdout.write('  https://github.com/settings/applications → 해당 OAuth App → Revoke\n');
+    process.exit(0);
+  } else {
+    process.stdout.write('GitHub token 이 vault 에 없습니다.\n');
+    process.exit(1);
+  }
+})();

package/scripts/auth/github-status.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// GitHub OAuth 상태 점검. vault 에 토큰이 있고 GitHub API 가 응답하는지 확인.
+
+import { load, redact, backend } from '../lib/token-vault.js';
+
+async function verify(tok) {
+  try {
+    const r = await fetch('https://api.github.com/user', {
+      headers: {
+        'Authorization': `${tok.token_type || 'token'} ${tok.access_token}`,
+        'Accept': 'application/vnd.github+json',
+        'User-Agent': 'harness-cli',
+      },
+    });
+    if (!r.ok) return { ok: false, status: r.status };
+    const u = await r.json();
+    return { ok: true, login: u.login };
+  } catch (e) {
+    return { ok: false, error: String(e.message || e) };
+  }
+}
+
+(async () => {
+  const tok = await load('github');
+  if (!tok) {
+    process.stdout.write('GitHub: 미인증 (`npm run auth:github:login` 필요).\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  process.stdout.write('GitHub 인증 상태:\n');
+  process.stdout.write(`  backend  : ${await backend()}\n`);
+  process.stdout.write(`  scope    : ${tok.scope}\n`);
+  process.stdout.write(`  saved_at : ${tok.saved_at}\n`);
+  process.stdout.write(`  token    : ${redact(tok.access_token)}\n`);
+
+  const v = await verify(tok);
+  if (v.ok) {
+    process.stdout.write(`  user     : ${v.login}\n`);
+    process.stdout.write(`  유효      : ✓\n`);
+    process.exitCode = 0;
+  } else {
+    process.stdout.write(`  유효      : ✗ (${v.status || v.error})\n`);
+    process.exitCode = 2;
+  }
+})();

package/scripts/build-claude.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// 정규 카탈로그 (agents/, skills/, commands/, hooks/) → .claude/ 로 투영.
+// Claude Code 가 인식하는 디렉터리 레이아웃 + .claude-plugin/plugin.json.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildRoots } from './core/build-roots.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const { sourceRoot: ROOT, targetRoot: TARGET_ROOT } = buildRoots(path.resolve(__dirname, '..'));
+const OUT = path.join(TARGET_ROOT, '.claude');
+
+function ensure(dir) { fs.mkdirSync(dir, { recursive: true }); }
+function copy(src, dst) { fs.mkdirSync(path.dirname(dst), { recursive: true }); fs.copyFileSync(src, dst); }
+function copyDir(src, dst) {
+  if (!fs.existsSync(src)) return 0;
+  let n = 0;
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name), d = path.join(dst, e.name);
+    if (e.isDirectory()) n += copyDir(s, d);
+    else { copy(s, d); n++; }
+  }
+  return n;
+}
+
+console.log('=> build-claude');
+ensure(OUT);
+
+// agents/ → .claude/agents/
+const agents = copyDir(path.join(ROOT, 'agents'), path.join(OUT, 'agents'));
+console.log(`  agents     : ${agents}`);
+
+// skills/ → .claude/skills/
+const skills = copyDir(path.join(ROOT, 'skills'), path.join(OUT, 'skills'));
+console.log(`  skills     : ${skills}`);
+
+// commands/ → .claude/commands/
+const cmds = copyDir(path.join(ROOT, 'commands'), path.join(OUT, 'commands'));
+console.log(`  commands   : ${cmds}`);
+
+// hooks/scripts/ → .claude/hooks/
+const hookScripts = copyDir(path.join(ROOT, 'hooks', 'scripts'), path.join(OUT, 'hooks'));
+console.log(`  hooks      : ${hookScripts}`);
+
+// hooks/hooks.json → .claude/hooks.json (Claude Code 형식: top-level)
+const hooksJson = path.join(ROOT, 'hooks', 'hooks.json');
+if (fs.existsSync(hooksJson)) {
+  const def = JSON.parse(fs.readFileSync(hooksJson, 'utf8'));
+  // 경로를 .claude/ 기준으로 재작성: scripts/ → hooks/ (.claude 안에선 hooks/ 디렉터리에 복사돼 있음)
+  const remap = (entries) => (entries || []).map(e => ({
+    ...e,
+    hook: e.hook.replace(/^scripts\//, 'hooks/'),
+  }));
+  const claudeHooks = {
+    version: def.version,
+    PreToolUse: remap(def.PreToolUse),
+    PostToolUse: remap(def.PostToolUse),
+    PreCompact: remap(def.PreCompact),
+    Stop: remap(def.Stop),
+    SessionStart: remap(def.SessionStart),
+    SessionEnd: remap(def.SessionEnd),
+    UserPromptSubmit: remap(def.UserPromptSubmit),
+  };
+  // 빈 키 제거
+  for (const k of Object.keys(claudeHooks)) if (!claudeHooks[k] || claudeHooks[k].length === 0) delete claudeHooks[k];
+  fs.writeFileSync(path.join(OUT, 'hooks.json'), JSON.stringify(claudeHooks, null, 2));
+  console.log('  hooks.json : OK');
+}
+
+// 거버넌스 마크다운 → .claude/ 루트에 그대로
+for (const f of ['CLAUDE.md', 'AGENTS.md', 'RULES.md', 'SOUL.md', 'WORKING-CONTEXT.md', 'REVIEW.md']) {
+  if (fs.existsSync(path.join(ROOT, f))) {
+    copy(path.join(ROOT, f), path.join(OUT, f));
+  }
+}
+console.log('  governance : 6 files');
+
+// .claude-plugin/plugin.json
+const pluginDir = path.join(TARGET_ROOT, '.claude-plugin');
+ensure(pluginDir);
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const plugin = {
+  $schema: 'https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/plugin.schema.json',
+  name: 'harness',
+  version: pkg.version,
+  description: pkg.description,
+  components: {
+    agents: agents,
+    skills: skills,
+    commands: cmds,
+    hooks: hookScripts,
+  },
+};
+// homepage / authors 는 publish 전에 외부 레포 정보로 채울 것 (env 변수 또는 package.json 활용 권장)
+if (process.env.HARNESS_HOMEPAGE) plugin.homepage = process.env.HARNESS_HOMEPAGE;
+if (pkg.author) plugin.authors = Array.isArray(pkg.author) ? pkg.author : [pkg.author];
+fs.writeFileSync(path.join(pluginDir, 'plugin.json'), JSON.stringify(plugin, null, 2));
+console.log('  plugin.json: OK');
+
+console.log('=> .claude 빌드 완료');

package/scripts/build-codemaps.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+// Generate docs/CODEMAPS/<area>.md from repository directories.
+// The maps include a shallow directory tree plus exported JS symbols.
+// They intentionally omit code bodies and are safe to regenerate.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const OUT = path.join(ROOT, 'docs', 'CODEMAPS');
+
+const AREAS = [
+  { area: 'scripts', dir: 'scripts', depth: 3 },
+  { area: 'agents', dir: 'agents', depth: 1 },
+  { area: 'skills', dir: 'skills', depth: 2 },
+  { area: 'hooks', dir: 'hooks', depth: 2 },
+  { area: 'manifests', dir: 'manifests', depth: 1 },
+  { area: 'schemas', dir: 'schemas', depth: 1 },
+  { area: 'bridge', dir: 'bridge', depth: 1 },
+  { area: 'rules', dir: 'rules', depth: 2 },
+  { area: 'tests', dir: 'tests', depth: 2 },
+];
+
+const SKIP = new Set([
+  'node_modules',
+  '.git',
+  '.harness',
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.gemini',
+  '.opencode',
+]);
+
+function parseArgs(argv) {
+  const args = { check: false, verbose: false };
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--check') args.check = true;
+    else if (arg === '--verbose' || arg === '-v') args.verbose = true;
+    else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: node scripts/build-codemaps.js [--check] [--verbose]');
+      process.exit(0);
+    } else {
+      console.error(`unknown argument: ${arg}`);
+      process.exit(2);
+    }
+  }
+  return args;
+}
+
+function toSlash(value) {
+  return value.split(path.sep).join('/');
+}
+
+function directoryTree(dir, maxDepth, prefix = '', depth = 0) {
+  if (depth > maxDepth) return [];
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => !SKIP.has(entry.name) && !entry.name.startsWith('.'))
+    .sort((a, b) => {
+      if (a.isDirectory() !== b.isDirectory()) return a.isDirectory() ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+
+  const lines = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const last = i === entries.length - 1;
+    const branch = last ? '`-- ' : '|-- ';
+    const childPrefix = last ? '    ' : '|   ';
+    const label = entry.isDirectory() ? `${entry.name}/` : entry.name;
+    lines.push(prefix + branch + label);
+    if (entry.isDirectory()) {
+      lines.push(...directoryTree(path.join(dir, entry.name), maxDepth, prefix + childPrefix, depth + 1));
+    }
+  }
+  return lines;
+}
+
+function extractExports(code) {
+  const exports = new Set();
+  const patterns = [
+    /^export\s+(?:async\s+)?function\s+([a-zA-Z_$][\w$]*)/gm,
+    /^export\s+class\s+([a-zA-Z_$][\w$]*)/gm,
+    /^export\s+const\s+([a-zA-Z_$][\w$]*)/gm,
+    /^export\s+let\s+([a-zA-Z_$][\w$]*)/gm,
+    /^export\s+\{([^}]+)\}/gm,
+    /^export\s+default\s+(?:async\s+)?function\s+([a-zA-Z_$][\w$]*)/gm,
+  ];
+
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(code)) !== null) {
+      const raw = match[1];
+      if (raw.includes(',') || raw.includes(' as ')) {
+        for (const part of raw.split(',')) {
+          const name = part.trim().split(/\s+as\s+/)[0].trim();
+          if (name) exports.add(name);
+        }
+      } else if (raw) {
+        exports.add(raw);
+      }
+    }
+  }
+
+  if (/^export\s+default\b/m.test(code) && !exports.has('default')) {
+    exports.add('default');
+  }
+
+  return [...exports].sort();
+}
+
+function leadingComment(code) {
+  const lines = code.split('\n');
+  const collected = [];
+  let started = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!started && (trimmed === '' || trimmed.startsWith('#!'))) continue;
+    if (trimmed.startsWith('//')) {
+      collected.push(trimmed.replace(/^\/\/\s?/, ''));
+      started = true;
+    } else if (started) {
+      break;
+    } else {
+      break;
+    }
+  }
+
+  return collected.join(' ');
+}
+
+function cleanCell(value) {
+  return String(value || '')
+    .normalize('NFKD')
+    .replace(/[^\x20-\x7E]/g, ' ')
+    .replace(/[|]/g, '\\|')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 140);
+}
+
+function collectJsFiles(absDir) {
+  const files = [];
+
+  function walk(dir, rel = '') {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP.has(entry.name) || entry.name.startsWith('.')) continue;
+
+      const abs = path.join(dir, entry.name);
+      const nextRel = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(abs, nextRel);
+      } else if (/\.(m?js|cjs)$/.test(entry.name)) {
+        const code = fs.readFileSync(abs, 'utf8');
+        files.push({
+          rel: nextRel,
+          exports: extractExports(code),
+          comment: cleanCell(leadingComment(code)),
+        });
+      }
+    }
+  }
+
+  walk(absDir);
+  return files.sort((a, b) => a.rel.localeCompare(b.rel));
+}
+
+function buildArea({ area, dir, depth }) {
+  const absDir = path.join(ROOT, dir);
+  if (!fs.existsSync(absDir)) return null;
+
+  const treeLines = directoryTree(absDir, depth);
+  const jsFiles = collectJsFiles(absDir);
+
+  const lines = [
+    `# CODEMAP: ${area}`,
+    '',
+    `> Generated by \`scripts/build-codemaps.js\` from \`${dir}/\`. Do not edit directly.`,
+    '> Directory shape and exported JS symbols only. Code bodies are intentionally omitted.',
+    '',
+    '## Directory Tree',
+    '',
+    '```text',
+    `${dir}/`,
+    ...treeLines,
+    '```',
+    '',
+  ];
+
+  if (jsFiles.length) {
+    lines.push('## JS Exports');
+    lines.push('');
+    lines.push('| File | Exports | Description |');
+    lines.push('|---|---|---|');
+    for (const file of jsFiles) {
+      const exports = file.exports.length
+        ? file.exports.map(name => `\`${name}\``).join(', ')
+        : '_(none)_';
+      lines.push(`| \`${file.rel}\` | ${exports} | ${file.comment} |`);
+    }
+    lines.push('');
+  }
+
+  return {
+    area,
+    content: lines.join('\n') + '\n',
+    fileCount: jsFiles.length,
+  };
+}
+
+function buildIndex() {
+  const lines = [
+    '# CODEMAPS: index',
+    '',
+    '> Generated by `scripts/build-codemaps.js`. Do not edit directly.',
+    '',
+    '| Area | File |',
+    '|---|---|',
+  ];
+
+  for (const area of AREAS) {
+    if (fs.existsSync(path.join(OUT, `${area.area}.md`))) {
+      lines.push(`| ${area.area} | [${area.area}.md](./${area.area}.md) |`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function writeOrCheck(file, content, args) {
+  const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (before === content) return false;
+  if (!args.check) fs.writeFileSync(file, content);
+  return true;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  fs.mkdirSync(OUT, { recursive: true });
+
+  let changed = 0;
+  let total = 0;
+
+  for (const area of AREAS) {
+    const built = buildArea(area);
+    if (!built) {
+      if (args.verbose) console.log(`[SKIP] ${area.area}: ${area.dir}/ not found`);
+      continue;
+    }
+
+    total++;
+    const outFile = path.join(OUT, `${built.area}.md`);
+    if (writeOrCheck(outFile, built.content, args)) {
+      changed++;
+      console.log(`[${args.check ? 'DIFF' : 'WRITE'}] ${toSlash(path.relative(ROOT, outFile))} (${built.fileCount} files)`);
+    } else if (args.verbose) {
+      console.log(`[ OK ] ${toSlash(path.relative(ROOT, outFile))}`);
+    }
+  }
+
+  const indexFile = path.join(OUT, 'README.md');
+  if (writeOrCheck(indexFile, buildIndex(), args)) {
+    changed++;
+    console.log(`[${args.check ? 'DIFF' : 'WRITE'}] ${toSlash(path.relative(ROOT, indexFile))}`);
+  } else if (args.verbose) {
+    console.log(`[ OK ] ${toSlash(path.relative(ROOT, indexFile))}`);
+  }
+
+  if (args.check) {
+    if (changed > 0) {
+      console.error(`${changed} codemap file(s) are outdated. Run: node scripts/build-codemaps.js`);
+      process.exit(1);
+    }
+    console.log('All codemaps are up to date.');
+    return;
+  }
+
+  console.log(`\nprocessed=${total}, changed=${changed}`);
+}
+
+main();