@wooojin/forgen 0.4.9 → 0.4.11

package/dist/core/stats-cli.js

@@ -198,8 +198,125 @@ export function computeStats() {
         lastExtraction: readLastExtraction(),
         assistToday: computeAssistToday(),
         philosophy: computePhilosophy(),
+        solutionHealth: computeSolutionHealth(),
+        topRules7d: computeTopRules7d(realBlocks),
+        weeklyTrend: computeWeeklyTrend(realBlocks),
     };
 }
+function computeSolutionHealth() {
+    const byStatus = {};
+    let total = 0;
+    let confidenceSum = 0;
+    const localNames = new Set();
+    try {
+        if (!fs.existsSync(SOLUTIONS_DIR))
+            return { total: 0, byStatus: {}, avgConfidence: 0, utilization7d: 0 };
+        const files = fs.readdirSync(SOLUTIONS_DIR).filter(f => f.endsWith('.md'));
+        for (const f of files) {
+            try {
+                const content = fs.readFileSync(path.join(SOLUTIONS_DIR, f), 'utf-8');
+                const statusMatch = content.match(/status:\s*"?([a-z]+)"?/);
+                const confMatch = content.match(/confidence:\s*([0-9.]+)/);
+                const st = statusMatch?.[1] ?? 'unknown';
+                byStatus[st] = (byStatus[st] ?? 0) + 1;
+                confidenceSum += parseFloat(confMatch?.[1] ?? '0');
+                localNames.add(f.replace(/\.md$/, ''));
+                total++;
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* fail-open */ }
+    const cutoff7d = Date.now() - 7 * MS_PER_DAY;
+    const matchLog = readJsonl(path.join(STATE_DIR, 'match-eval-log.jsonl'));
+    const matchedLocalNames = new Set();
+    for (const e of matchLog) {
+        const ts = typeof e.ts === 'string' ? Date.parse(e.ts) : NaN;
+        if (!Number.isFinite(ts) || ts < cutoff7d)
+            continue;
+        const ranked = e.rankedTopN;
+        if (Array.isArray(ranked)) {
+            for (const r of ranked) {
+                let name = null;
+                if (typeof r === 'string')
+                    name = r;
+                else if (typeof r === 'object' && r !== null && typeof r.name === 'string') {
+                    name = r.name;
+                }
+                // Only count matches against LOCAL solutions to avoid skew from
+                // starter-pack/team-pack matches that aren't in this user's me/solutions/.
+                if (name && localNames.has(name)) {
+                    matchedLocalNames.add(name);
+                }
+            }
+        }
+    }
+    return {
+        total,
+        byStatus,
+        avgConfidence: total > 0 ? confidenceSum / total : 0,
+        utilization7d: total > 0 ? matchedLocalNames.size / total : 0,
+    };
+}
+function computeTopRules7d(violations) {
+    const cutoff = Date.now() - 7 * MS_PER_DAY;
+    const counts = new Map();
+    for (const v of violations) {
+        const ts = typeof v.at === 'string' ? Date.parse(v.at) : NaN;
+        if (!Number.isFinite(ts) || ts < cutoff)
+            continue;
+        const rule = typeof v.rule === 'string' ? v.rule
+            : typeof v.guard === 'string' ? v.guard
+                : typeof v.source === 'string' ? v.source
+                    : 'unknown';
+        counts.set(rule, (counts.get(rule) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([name, count]) => ({ name, count }));
+}
+function computeWeeklyTrend(violations) {
+    const now = Date.now();
+    const thisWeekStart = now - 7 * MS_PER_DAY;
+    const lastWeekStart = now - 14 * MS_PER_DAY;
+    const blocksThisWeek = countWithin(violations, 7);
+    let blocksLastWeek = 0;
+    for (const v of violations) {
+        const ts = typeof v.at === 'string' ? Date.parse(v.at) : NaN;
+        if (Number.isFinite(ts) && ts >= lastWeekStart && ts < thisWeekStart)
+            blocksLastWeek++;
+    }
+    const matchLog = readJsonl(path.join(STATE_DIR, 'match-eval-log.jsonl'));
+    let recallsThisWeek = 0;
+    let recallsLastWeek = 0;
+    for (const e of matchLog) {
+        const ts = typeof e.ts === 'string' ? Date.parse(e.ts) : NaN;
+        if (!Number.isFinite(ts))
+            continue;
+        if (ts >= thisWeekStart)
+            recallsThisWeek++;
+        else if (ts >= lastWeekStart)
+            recallsLastWeek++;
+    }
+    let extractionsThisWeek = 0;
+    let extractionsLastWeek = 0;
+    try {
+        if (fs.existsSync(SOLUTIONS_DIR)) {
+            for (const f of fs.readdirSync(SOLUTIONS_DIR)) {
+                if (!f.endsWith('.md'))
+                    continue;
+                const mtime = fs.statSync(path.join(SOLUTIONS_DIR, f)).mtimeMs;
+                if (mtime >= thisWeekStart)
+                    extractionsThisWeek++;
+                else if (mtime >= lastWeekStart)
+                    extractionsLastWeek++;
+            }
+        }
+    }
+    catch { /* fail-open */ }
+    return { blocksThisWeek, blocksLastWeek, recallsThisWeek, recallsLastWeek, extractionsThisWeek, extractionsLastWeek };
+}
 function padNum(n, width = 4) {
     return String(n).padStart(width);
 }
@@ -256,6 +373,38 @@ export function renderStats(s) {
         }
     }
     catch { /* fail-open: git 없거나 비-repo 환경 */ }
+    // v0.5.0: Solution health
+    if (s.solutionHealth.total > 0) {
+        const sh = s.solutionHealth;
+        const statusParts = Object.entries(sh.byStatus).map(([k, v]) => `${k}:${v}`).join(' ');
+        lines.push('  Solutions');
+        lines.push(`    Total               ${padNum(sh.total)}    ${statusParts}`);
+        lines.push(`    Avg confidence      ${sh.avgConfidence.toFixed(2)}`);
+        lines.push(`    Utilization (7d)    ${Math.round(sh.utilization7d * 100)}%   — matched at least once`);
+        lines.push('');
+    }
+    // v0.5.0: Top rules (7d)
+    if (s.topRules7d.length > 0) {
+        lines.push('  Top rules (7d)');
+        for (const r of s.topRules7d) {
+            lines.push(`    ${padNum(r.count)}x  ${r.name}`);
+        }
+        lines.push('');
+    }
+    // v0.5.0: Weekly trend
+    const wt = s.weeklyTrend;
+    const trendArrow = (curr, prev) => {
+        if (curr > prev)
+            return `+${curr - prev}`;
+        if (curr < prev)
+            return `${curr - prev}`;
+        return '=';
+    };
+    lines.push('  Weekly trend (this vs last)');
+    lines.push(`    Blocks       ${padNum(wt.blocksThisWeek)} → ${padNum(wt.blocksLastWeek, 2)} prev   (${trendArrow(wt.blocksThisWeek, wt.blocksLastWeek)})`);
+    lines.push(`    Recalls      ${padNum(wt.recallsThisWeek)} → ${padNum(wt.recallsLastWeek, 2)} prev   (${trendArrow(wt.recallsThisWeek, wt.recallsLastWeek)})`);
+    lines.push(`    Extractions  ${padNum(wt.extractionsThisWeek)} → ${padNum(wt.extractionsLastWeek, 2)} prev   (${trendArrow(wt.extractionsThisWeek, wt.extractionsLastWeek)})`);
+    lines.push('');
     lines.push(`  Last extraction: ${s.lastExtraction}`);
     lines.push('');
     return lines.join('\n');

package/dist/core/watch-cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * forgen watch — real-time hook event stream.
+ *
+ * Tails hook-timing.jsonl, enforcement/violations.jsonl, and
+ * match-eval-log.jsonl to show live forgen activity in a terminal pane.
+ */
+export declare function handleWatch(): Promise<void>;

package/dist/core/watch-cli.js

@@ -0,0 +1,185 @@
+/**
+ * forgen watch — real-time hook event stream.
+ *
+ * Tails hook-timing.jsonl, enforcement/violations.jsonl, and
+ * match-eval-log.jsonl to show live forgen activity in a terminal pane.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR } from './paths.js';
+const isTTY = process.stdout.isTTY;
+const C = {
+    reset: isTTY ? '\x1b[0m' : '',
+    dim: isTTY ? '\x1b[2m' : '',
+    cyan: isTTY ? '\x1b[36m' : '',
+    yellow: isTTY ? '\x1b[33m' : '',
+    green: isTTY ? '\x1b[32m' : '',
+    red: isTTY ? '\x1b[31m' : '',
+    magenta: isTTY ? '\x1b[35m' : '',
+};
+function formatTimestamp(isoOrMs) {
+    try {
+        const d = typeof isoOrMs === 'number' ? new Date(isoOrMs) : new Date(isoOrMs);
+        return d.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+    }
+    catch {
+        return '??:??:??';
+    }
+}
+function formatHookTiming(e) {
+    const hook = String(e.hook ?? '');
+    const ms = Number(e.ms ?? 0);
+    const event = String(e.event ?? '');
+    const ts = formatTimestamp(e.at);
+    const speedColor = ms > 500 ? C.yellow : ms > 1000 ? C.red : C.dim;
+    return `${C.dim}${ts}${C.reset} ${C.cyan}hook${C.reset} ${hook} ${C.dim}(${event})${C.reset} ${speedColor}${ms}ms${C.reset}`;
+}
+function formatViolation(e) {
+    const rule = String(e.rule ?? e.guard ?? e.source ?? 'unknown');
+    const kind = String(e.kind ?? 'block');
+    const ts = formatTimestamp(String(e.at ?? ''));
+    const icon = kind === 'block' ? `${C.red}BLOCK${C.reset}` : `${C.yellow}${kind}${C.reset}`;
+    return `${C.dim}${ts}${C.reset} ${icon} ${C.magenta}${rule}${C.reset}`;
+}
+function formatMatchEval(e) {
+    const source = String(e.source ?? '');
+    const ranked = e.rankedTopN;
+    const ts = formatTimestamp(String(e.ts ?? ''));
+    if (!ranked || !Array.isArray(ranked) || ranked.length === 0)
+        return null;
+    // rankedTopN entries can be strings (names) or objects {name: ...}
+    const names = ranked.slice(0, 3).map(r => {
+        if (typeof r === 'string')
+            return r;
+        if (typeof r === 'object' && r !== null && 'name' in r) {
+            return String(r.name);
+        }
+        return '?';
+    }).filter(Boolean).join(', ');
+    if (!names)
+        return null;
+    return `${C.dim}${ts}${C.reset} ${C.green}match${C.reset} ${C.dim}(${source})${C.reset} ${names}`;
+}
+function tailFile(filePath, fromEnd) {
+    try {
+        if (!fs.existsSync(filePath))
+            return [];
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.trim().split('\n');
+        const tail = lines.slice(-fromEnd);
+        const out = [];
+        for (const line of tail) {
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip */ }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function watchFile(filePath, onLine) {
+    let lastSize = 0;
+    try {
+        if (fs.existsSync(filePath)) {
+            lastSize = fs.statSync(filePath).size;
+        }
+    }
+    catch { /* ok */ }
+    try {
+        return fs.watch(filePath, () => {
+            try {
+                const stat = fs.statSync(filePath);
+                if (stat.size <= lastSize) {
+                    lastSize = stat.size;
+                    return;
+                }
+                const fd = fs.openSync(filePath, 'r');
+                const buf = Buffer.alloc(stat.size - lastSize);
+                fs.readSync(fd, buf, 0, buf.length, lastSize);
+                fs.closeSync(fd);
+                lastSize = stat.size;
+                const chunk = buf.toString('utf-8');
+                for (const line of chunk.split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        onLine(JSON.parse(line));
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            catch { /* fail-open */ }
+        });
+    }
+    catch {
+        return null;
+    }
+}
+export async function handleWatch() {
+    const sources = [
+        {
+            label: 'hooks',
+            path: path.join(STATE_DIR, 'hook-timing.jsonl'),
+            format: formatHookTiming,
+        },
+        {
+            label: 'enforcement',
+            path: path.join(STATE_DIR, 'enforcement', 'violations.jsonl'),
+            format: formatViolation,
+        },
+        {
+            label: 'matches',
+            path: path.join(STATE_DIR, 'match-eval-log.jsonl'),
+            format: formatMatchEval,
+        },
+    ];
+    console.log(`\n  ${C.cyan}forgen watch${C.reset} — real-time event stream`);
+    console.log(`  ${C.dim}Watching: hook-timing, violations, match-eval-log${C.reset}`);
+    console.log(`  ${C.dim}Press Ctrl+C to stop${C.reset}\n`);
+    // Show recent events (last 10 per source)
+    const recent = [];
+    for (const src of sources) {
+        const entries = tailFile(src.path, 10);
+        for (const e of entries) {
+            const line = src.format(e);
+            if (!line)
+                continue;
+            const ts = typeof e.at === 'number' ? e.at
+                : typeof e.at === 'string' ? Date.parse(e.at)
+                    : typeof e.ts === 'string' ? Date.parse(e.ts)
+                        : 0;
+            recent.push({ ts, line });
+        }
+    }
+    recent.sort((a, b) => a.ts - b.ts);
+    if (recent.length > 0) {
+        console.log(`  ${C.dim}── recent ──${C.reset}`);
+        for (const r of recent.slice(-15)) {
+            console.log(`  ${r.line}`);
+        }
+        console.log(`  ${C.dim}── live ──${C.reset}\n`);
+    }
+    // Watch for new events
+    const watchers = [];
+    for (const src of sources) {
+        const watcher = watchFile(src.path, (entry) => {
+            const line = src.format(entry);
+            if (line)
+                console.log(`  ${line}`);
+        });
+        if (watcher)
+            watchers.push(watcher);
+    }
+    // Keep process alive
+    await new Promise((resolve) => {
+        process.on('SIGINT', () => {
+            for (const w of watchers)
+                w.close();
+            console.log(`\n  ${C.dim}watch stopped${C.reset}\n`);
+            resolve();
+        });
+    });
+}

package/dist/core/workflows-cli.d.ts

@@ -0,0 +1,26 @@
+/**
+ * forgen workflows — dynamic-workflow 템플릿 설치/조회 (ADR-009 §3).
+ *
+ * dynamic workflows 는 플러그인 매니페스트로 번들할 수 없고(research preview,
+ * `.claude/workflows/` 에만 저장됨), forgen 은 철학을 인코딩한 canonical 템플릿을
+ * `assets/claude/workflows/*.js` 로 동봉한다. 이 명령이 그것을 사용자의
+ * `.claude/workflows/` 로 복사한다 → `/<name>` 으로 실행 가능.
+ *
+ * forgen-verify 에이전트(verify 스테이지용)는 플러그인 `agents` 키로 자동 배포되므로
+ * 별도 설치가 필요 없다.
+ *
+ *   forgen workflows install            ~/.claude/workflows/ (개인, 모든 프로젝트)
+ *   forgen workflows install --project  <cwd>/.claude/workflows/ (저장소 공유)
+ *   forgen workflows list               동봉 템플릿 + 설치 여부
+ */
+/** forgen pkg root 의 assets/claude/workflows 디렉토리. invoke-agent 와 동일 walk-up. */
+export declare function findTemplatesDir(): string;
+/** 템플릿 파일명(.js) 목록. 실패 시 []. */
+export declare function listTemplates(templatesDir: string): string[];
+export interface InstallResult {
+    installed: string[];
+    targetDir: string;
+}
+/** 템플릿을 targetDir 로 복사 (DI — 테스트 주입용). 기존 파일은 덮어쓴다. */
+export declare function installWorkflows(templatesDir: string, targetDir: string): InstallResult;
+export declare function handleWorkflows(args: string[]): Promise<void>;

package/dist/core/workflows-cli.js

@@ -0,0 +1,120 @@
+/**
+ * forgen workflows — dynamic-workflow 템플릿 설치/조회 (ADR-009 §3).
+ *
+ * dynamic workflows 는 플러그인 매니페스트로 번들할 수 없고(research preview,
+ * `.claude/workflows/` 에만 저장됨), forgen 은 철학을 인코딩한 canonical 템플릿을
+ * `assets/claude/workflows/*.js` 로 동봉한다. 이 명령이 그것을 사용자의
+ * `.claude/workflows/` 로 복사한다 → `/<name>` 으로 실행 가능.
+ *
+ * forgen-verify 에이전트(verify 스테이지용)는 플러그인 `agents` 키로 자동 배포되므로
+ * 별도 설치가 필요 없다.
+ *
+ *   forgen workflows install            ~/.claude/workflows/ (개인, 모든 프로젝트)
+ *   forgen workflows install --project  <cwd>/.claude/workflows/ (저장소 공유)
+ *   forgen workflows list               동봉 템플릿 + 설치 여부
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const isTTY = process.stdout.isTTY;
+const C = {
+    reset: isTTY ? '\x1b[0m' : '',
+    bold: isTTY ? '\x1b[1m' : '',
+    dim: isTTY ? '\x1b[2m' : '',
+    green: isTTY ? '\x1b[32m' : '',
+    cyan: isTTY ? '\x1b[36m' : '',
+};
+/** forgen pkg root 의 assets/claude/workflows 디렉토리. invoke-agent 와 동일 walk-up. */
+export function findTemplatesDir() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth += 1) {
+        const pkgJson = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgJson)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+                if (pkg.name === '@wooojin/forgen') {
+                    const candidate = path.join(dir, 'assets', 'claude', 'workflows');
+                    if (fs.existsSync(candidate))
+                        return candidate;
+                }
+            }
+            catch { /* fallthrough */ }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('forgen workflows: pkg root + assets/claude/workflows/ not found');
+}
+/** 템플릿 파일명(.js) 목록. 실패 시 []. */
+export function listTemplates(templatesDir) {
+    try {
+        return fs.readdirSync(templatesDir).filter((f) => f.endsWith('.js')).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** 템플릿을 targetDir 로 복사 (DI — 테스트 주입용). 기존 파일은 덮어쓴다. */
+export function installWorkflows(templatesDir, targetDir) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    const installed = [];
+    for (const file of listTemplates(templatesDir)) {
+        fs.copyFileSync(path.join(templatesDir, file), path.join(targetDir, file));
+        installed.push(file);
+    }
+    return { installed, targetDir };
+}
+function resolveTargetBase(projectScope) {
+    return projectScope ? process.cwd() : os.homedir();
+}
+export async function handleWorkflows(args) {
+    const sub = args[0] ?? 'list';
+    const projectScope = args.includes('--project');
+    let templatesDir;
+    try {
+        templatesDir = findTemplatesDir();
+    }
+    catch {
+        console.log(`\n  ${C.dim}워크플로우 템플릿을 찾을 수 없습니다 (forgen 설치 확인).${C.reset}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (sub === 'install') {
+        const targetDir = path.join(resolveTargetBase(projectScope), '.claude', 'workflows');
+        const { installed } = installWorkflows(templatesDir, targetDir);
+        if (installed.length === 0) {
+            console.log(`\n  ${C.dim}동봉된 템플릿이 없습니다.${C.reset}\n`);
+            return;
+        }
+        console.log(`\n  ${C.green}✓${C.reset} ${installed.length} workflow templates → ${C.cyan}${targetDir}${C.reset}`);
+        for (const f of installed)
+            console.log(`      /${f.replace(/\.js$/, '')}`);
+        console.log(`\n  ${C.dim}Claude Code 에서 /<name> 으로 실행. verify 스테이지는 forgen-verify 에이전트 사용.${C.reset}\n`);
+        return;
+    }
+    if (sub === 'list') {
+        const templates = listTemplates(templatesDir);
+        const homeDir = path.join(os.homedir(), '.claude', 'workflows');
+        const projDir = path.join(process.cwd(), '.claude', 'workflows');
+        console.log(`\n  ${C.bold}forgen workflow templates${C.reset}\n`);
+        for (const f of templates) {
+            const name = f.replace(/\.js$/, '');
+            const inHome = fs.existsSync(path.join(homeDir, f));
+            const inProj = fs.existsSync(path.join(projDir, f));
+            const where = [inHome && 'user', inProj && 'project'].filter(Boolean).join('+') || 'not installed';
+            console.log(`    ${inHome || inProj ? C.green + '✓' + C.reset : C.dim + '·' + C.reset} /${name}  ${C.dim}(${where})${C.reset}`);
+        }
+        console.log(`\n  ${C.dim}install: forgen workflows install [--project]${C.reset}\n`);
+        return;
+    }
+    console.log(`
+  ${C.bold}forgen workflows${C.reset} — dynamic-workflow 템플릿 (ADR-009 §3)
+
+  Usage:
+    forgen workflows install [--project]   템플릿을 .claude/workflows/ 로 복사
+    forgen workflows list                  동봉 템플릿 + 설치 여부
+`);
+}

package/dist/engine/compound-export.d.ts

@@ -50,6 +50,18 @@ export declare function exportKnowledge(outputPath?: string): ExportResult;
  * added.
  */
 export declare function importKnowledge(archivePath: string): ImportResult;
+/**
+ * Selective export — filter to specific categories.
+ * `--only solutions,rules` exports only those two directories.
+ */
+export declare function exportKnowledgeSelective(categories: string[], outputPath?: string): ExportResult;
+/**
+ * Import with merge mode — updates existing files instead of skipping them.
+ * Newer files in the archive overwrite older local files.
+ */
+export declare function importKnowledgeMerge(archivePath: string): ImportResult & {
+    merged: number;
+};
 /** CLI handler: forgen compound export */
 export declare function handleExport(args: string[]): Promise<void>;
 /** CLI handler: forgen compound import */