@wooojin/forgen 0.1.0

package/commands/testing-strategy.md

@@ -0,0 +1,265 @@
+---
+name: testing-strategy
+description: This skill should be used when the user asks to "testing strategy,테스트 전략,test plan,테스트 계획,coverage plan". Test strategy design, coverage analysis, and quality planning
+triggers:
+  - "testing strategy"
+  - "테스트 전략"
+  - "test plan"
+  - "테스트 계획"
+  - "coverage plan"
+---
+<!-- forgen-managed -->
+
+<Purpose>
+테스트 전략을 수립하고 커버리지 계획을 설계합니다.
+TDD 스킬이 Red-Green-Refactor 워크플로우를 다루는 반면,
+이 스킬은 "무엇을 어떻게 테스트할 것인가"의 전략적 관점을 다룹니다.
+테스트 피라미드, 커버리지 갭 분석, 우선순위 결정을 수행합니다.
+</Purpose>
+
+<Steps>
+1. **현재 커버리지 평가**: 기존 테스트 상태를 분석합니다
+   - 라인/브랜치/함수 커버리지 측정
+   - 테스트 피라미드 비율 분석 (unit : integration : e2e)
+   - 테스트 실행 시간 측정
+   - 불안정(flaky) 테스트 식별
+   - 테스트 없는 핵심 경로 식별
+   - 최근 버그의 테스트 커버리지 분석 (커버 되었는가?)
+
+2. **갭 분석**: 테스트가 부족한 영역을 식별합니다
+   - 비즈니스 로직의 테스트 커버리지 확인
+   - 에러 핸들링 경로의 테스트 존재 여부
+   - 엣지 케이스 누락 식별
+     * 빈 입력, null/undefined
+     * 경계값 (최소/최대)
+     * 동시성/경쟁 조건
+     * 타임아웃/네트워크 에러
+   - 보안 관련 로직의 테스트 확인 (인증, 인가, 입력 검증)
+   - 통합 테스트 누락 (모듈 간 상호작용)
+   - 외부 의존성 모킹의 적절성
+
+3. **우선순위 결정**: 테스트 작성 순서를 결정합니다
+   - 위험도 기반 우선순위 매트릭스:
+     * [P0] 결제, 인증, 데이터 무결성 -- 반드시 테스트
+     * [P1] 핵심 비즈니스 로직 -- 높은 우선순위
+     * [P2] 일반 CRUD 작업 -- 중간 우선순위
+     * [P3] 유틸리티, 헬퍼 -- 낮은 우선순위
+   - 변경 빈도가 높은 코드 우선
+   - 최근 버그가 발생한 모듈 우선
+   - 복잡도가 높은 함수 우선
+
+4. **테스트 전략 수립**: 테스트 유형별 전략을 설계합니다
+   - Unit Test 전략:
+     * 순수 함수: 입력/출력 테스트
+     * 사이드 이펙트: 모킹/스터빙
+     * 커버리지 목표: 85%+ (브랜치 기준)
+   - Integration Test 전략:
+     * 모듈 간 상호작용 검증
+     * 외부 서비스 모킹 범위
+     * 데이터베이스 테스트 (인메모리 vs 컨테이너)
+   - E2E Test 전략:
+     * 핵심 사용자 시나리오 선정
+     * 테스트 환경 구성
+     * 데이터 시딩 전략
+   - 성능 Test 전략:
+     * 부하 테스트 시나리오
+     * 성능 기준값 설정
+
+5. **구현 및 추적**: 테스트를 점진적으로 구현합니다
+   - 테스트 작성 태스크 목록 생성
+   - 커버리지 추적 대시보드 설정
+   - CI 파이프라인에 커버리지 게이트 추가
+   - 정기적인 커버리지 리뷰 일정 설정
+   - 뮤테이션 테스트 도입 계획 (핵심 비즈니스 로직)
+</Steps>
+
+## 에이전트 위임
+
+`test-engineer` 에이전트(Opus 모델)에 위임하여 테스트 전략을 수립합니다:
+
+```
+Agent(
+  subagent_type="test-engineer",
+  model="opus",
+  prompt="TESTING STRATEGY TASK
+
+테스트 전략을 수립하고 커버리지 계획을 설계하세요.
+
+Project: [프로젝트 설명]
+Current Coverage: [현재 커버리지 또는 '미측정']
+
+Strategy Checklist:
+1. 현재 커버리지 측정 및 분석
+2. 테스트 갭 식별 (에러 경로, 엣지 케이스)
+3. 위험도 기반 우선순위 결정
+4. 테스트 유형별 전략 (unit/integration/e2e)
+5. 구현 로드맵 및 커버리지 목표
+
+Output: 테스트 전략 문서:
+- 현재 커버리지 분석
+- 갭 분석 결과
+- 우선순위 목록
+- 유형별 전략
+- 커버리지 목표 및 로드맵"
+)
+```
+
+## External Consultation (Optional)
+
+test-engineer 에이전트는 교차 검증을 위해 Claude Task 에이전트에 자문할 수 있습니다.
+
+### Protocol
+1. **자체 전략을 먼저 수립** -- 독립적으로 분석 수행
+2. **검증을 위한 자문** -- Claude Task 에이전트를 통해 전략 교차 확인
+3. **비판적 평가** -- 외부 제안을 맹목적으로 수용하지 않음
+4. **우아한 폴백** -- 위임이 불가능할 경우 절대 차단하지 않음
+
+### 자문이 필요한 경우
+- 복잡한 도메인의 테스트 커버리지 전략
+- 마이크로서비스 간 통합 테스트 설계
+- 성능/부하 테스트 시나리오 설계
+- 뮤테이션 테스트 도입 전략
+
+### 자문을 생략하는 경우
+- 단순 유닛 테스트 계획
+- 명확한 CRUD 테스트
+- 기존 패턴 반복
+- 소규모 모듈의 테스트
+
+## 테스트 피라미드 기준
+
+```
+        /  E2E  \         5~10% (핵심 시나리오만)
+       /----------\
+      / Integration \     15~25% (모듈 간 상호작용)
+     /----------------\
+    /    Unit Tests     \  70~80% (모든 비즈니스 로직)
+   /--------------------\
+```
+
+## 커버리지 목표 가이드
+
+| 코드 유형 | 라인 | 브랜치 | 뮤테이션 |
+|-----------|------|--------|----------|
+| 결제/인증 | 95%+ | 90%+ | 80%+ |
+| 비즈니스 로직 | 85%+ | 80%+ | 70%+ |
+| 유틸리티 | 80%+ | 75%+ | -- |
+| UI 컴포넌트 | 70%+ | 60%+ | -- |
+| 설정/부트스트랩 | 60%+ | -- | -- |
+
+## 테스트 품질 지표
+
+| 지표 | 건강 | 주의 | 위험 |
+|------|------|------|------|
+| 브랜치 커버리지 | > 80% | 60~80% | < 60% |
+| 테스트 실행 시간 | < 30s | 30s~2m | > 2m |
+| Flaky 테스트 비율 | 0% | < 2% | > 2% |
+| 뮤테이션 점수 | > 70% | 50~70% | < 50% |
+
+<Output>
+```
+TESTING STRATEGY / 테스트 전략 문서
+=====================================
+
+Project: [프로젝트명]
+Date: YYYY-MM-DD
+Test Framework: [vitest / jest / playwright]
+
+CURRENT STATE / 현재 상태
+---------------------------
+Line Coverage:    72% (target: 85%)
+Branch Coverage:  58% (target: 80%)
+Test Count:       142 (unit: 120, integration: 18, e2e: 4)
+Execution Time:   24s
+Flaky Tests:      2 (src/api/order.test.ts, src/utils/date.test.ts)
+
+GAP ANALYSIS / 갭 분석
+------------------------
+[P0] CRITICAL GAPS (테스트 없는 핵심 경로):
+  - src/services/payment.ts -- 결제 처리 로직 (0% coverage)
+  - src/middleware/auth.ts -- 인증 미들웨어 에러 경로 (30% branch)
+
+[P1] HIGH GAPS (불충분한 커버리지):
+  - src/services/order.ts -- 할인 계산 엣지 케이스 미테스트
+  - src/utils/validation.ts -- 경계값 테스트 부재
+
+[P2] MEDIUM GAPS:
+  - src/api/users.ts -- 통합 테스트 부재
+  - src/components/Cart.tsx -- 상태 변경 테스트 부족
+
+IMPLEMENTATION ROADMAP / 구현 로드맵
+--------------------------------------
+Week 1: P0 갭 해소 (결제, 인증)
+  - [ ] payment.ts 유닛 테스트 (15개)
+  - [ ] auth.ts 에러 경로 테스트 (8개)
+
+Week 2: P1 갭 해소 (비즈니스 로직)
+  - [ ] order.ts 엣지 케이스 테스트 (10개)
+  - [ ] validation.ts 경계값 테스트 (12개)
+
+Week 3: 통합 테스트 보강
+  - [ ] API 엔드포인트 통합 테스트 (20개)
+  - [ ] E2E 핵심 시나리오 (3개)
+
+TARGET / 목표
+--------------
+Line Coverage:    72% → 85%
+Branch Coverage:  58% → 80%
+Test Count:       142 → 210
+Flaky Tests:      2 → 0
+```
+</Output>
+
+<Policy>
+- 커버리지 숫자보다 테스트 품질을 우선합니다
+- 브랜치 커버리지를 라인 커버리지보다 중요하게 봅니다
+- 핵심 비즈니스 로직에 뮤테이션 테스트를 권장합니다
+- Flaky 테스트는 즉시 수정하거나 격리합니다
+- 테스트는 빠르게 실행되어야 합니다 (전체 30초 이내 목표)
+- 테스트 작성 계획은 스프린트에 통합하여 추적합니다
+</Policy>
+
+## 다른 스킬과의 연동
+
+**TDD 연동:**
+```
+/forgen:tdd 전략에서 식별된 갭 구현
+```
+전략에서 식별된 테스트 갭을 TDD로 구현
+
+**코드 리뷰 연동:**
+```
+/forgen:code-review 테스트 코드 품질 확인
+```
+작성된 테스트 코드의 품질 검증
+
+**CI/CD 연동:**
+```
+/forgen:ci-cd 커버리지 게이트 설정
+```
+CI에서 커버리지 임계값 강제
+
+## Best Practices
+
+- **전략 먼저** -- 무작정 테스트를 쓰기 전에 어디가 중요한지 파악
+- **위험 기반** -- 모든 코드를 균일하게 테스트하지 않음
+- **피라미드 유지** -- E2E에 의존하지 않고 유닛 테스트 기반 구축
+- **Flaky 제로** -- 불안정한 테스트는 신뢰를 해침
+- **지속 추적** -- 커버리지 트렌드를 모니터링
+
+<Arguments>
+## 사용법
+`/forgen:testing-strategy {대상}`
+
+### 예시
+- `/forgen:testing-strategy 전체 프로젝트 커버리지 분석`
+- `/forgen:testing-strategy 결제 모듈 테스트 계획`
+- `/forgen:testing-strategy E2E 테스트 전략 수립`
+- `/forgen:testing-strategy 현재 테스트의 갭 분석`
+
+### 인자
+- 분석 대상 모듈, 테스트 유형, 목표 등을 설명
+- 인자 없으면 프로젝트 전체의 테스트 전략을 수립
+</Arguments>
+
+$ARGUMENTS

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+const nodeVersion = parseInt(process.version.slice(1).split('.')[0], 10);
+if (nodeVersion < 20) {
+    console.error(`[Forgen] Node.js 20 or higher is required. Current: ${process.version}`);
+    process.exit(1);
+}
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { prepareHarness, isFirstRun } from './core/harness.js';
+import { spawnClaude } from './core/spawn.js';
+// global-config is used by harness internally
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgJson = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
+const PKG_VERSION = pkgJson.version ?? '0.0.0';
+const args = process.argv.slice(2);
+const commands = [
+    {
+        name: 'forge',
+        description: 'Personalization profile (--profile|--export|--reset)',
+        handler: async (args) => {
+            const { handleForge } = await import('./forge/cli.js');
+            await handleForge(args);
+        },
+    },
+    {
+        name: 'compound',
+        description: 'Preview/save compound insights and manage accumulated knowledge',
+        handler: async (args) => {
+            const { handleCompound } = await import('./engine/compound-loop.js');
+            await handleCompound(args);
+        },
+    },
+    {
+        name: 'skill',
+        description: 'Skill management (promote|list)',
+        handler: async (args) => {
+            const sub = args[0];
+            if (sub === 'promote' && args[1]) {
+                const { promoteSolution } = await import('./engine/skill-promoter.js');
+                const triggers = args.includes('--trigger')
+                    ? args.slice(args.indexOf('--trigger') + 1).filter(a => !a.startsWith('-'))
+                    : undefined;
+                const result = promoteSolution(args[1], triggers);
+                if (result.success) {
+                    console.log(`\n  ✓ Promoted: ${args[1]} → ${result.skillPath}\n`);
+                }
+                else {
+                    console.log(`\n  ✗ ${result.reason}\n`);
+                }
+            }
+            else if (sub === 'list') {
+                const { listSkills } = await import('./engine/skill-promoter.js');
+                const skills = listSkills();
+                if (skills.length === 0) {
+                    console.log('\n  No promoted skills yet. Use `forgen skill promote <solution-name>`\n');
+                }
+                else {
+                    console.log(`\n  Promoted Skills (${skills.length}):\n`);
+                    for (const s of skills) {
+                        console.log(`    ${s.name} [${s.status}] triggers: ${s.triggers.join(', ')}`);
+                    }
+                    console.log('');
+                }
+            }
+            else {
+                console.log('  Usage:\n    forgen skill promote <solution-name> [--trigger "keyword"]\n    forgen skill list');
+            }
+        },
+    },
+    {
+        name: 'me',
+        description: 'Personal dashboard (→ inspect profile)',
+        handler: async (_args) => {
+            const { handleInspect } = await import('./core/inspect-cli.js');
+            await handleInspect(['profile']);
+        },
+    },
+    {
+        name: 'config',
+        description: 'Configuration (hooks [--regenerate])',
+        handler: async (args) => {
+            const sub = args[0];
+            if (sub === 'hooks') {
+                if (args.includes('--regenerate')) {
+                    const { writeHooksJson } = await import('./hooks/hooks-generator.js');
+                    const hooksDir = path.join(process.cwd(), 'hooks');
+                    const result = writeHooksJson(hooksDir, { cwd: process.cwd() });
+                    console.log(`[forgen] hooks.json regenerated: ${result.active} active, ${result.disabled} disabled`);
+                }
+                else {
+                    const { displayHookStatus } = await import('./core/config-hooks.js');
+                    await displayHookStatus(process.cwd());
+                }
+            }
+            else {
+                console.log('Usage: forgen config hooks [--regenerate]');
+            }
+        },
+    },
+    {
+        name: 'mcp',
+        description: 'MCP server management (list|templates|add|remove)',
+        handler: async (args) => {
+            const { handleMcp } = await import('./core/mcp-config.js');
+            await handleMcp(args);
+        },
+    },
+    {
+        name: 'init',
+        description: 'Initialize project',
+        handler: async (args) => {
+            const { handleInit } = await import('./core/init.js');
+            await handleInit(args);
+        },
+    },
+    {
+        name: 'notepad',
+        description: 'Notepad (show|add|clear)',
+        handler: async (args) => {
+            const { handleNotepad } = await import('./core/notepad.js');
+            await handleNotepad(args);
+        },
+    },
+    {
+        name: 'inspect',
+        description: 'v1 state inspector (profile|rules|evidence|session)',
+        handler: async (args) => {
+            const { handleInspect } = await import('./core/inspect-cli.js');
+            await handleInspect(args);
+        },
+    },
+    {
+        name: 'onboarding',
+        description: 'v1 2-question onboarding flow',
+        handler: async (_args) => {
+            const { runOnboarding } = await import('./forge/onboarding-cli.js');
+            await runOnboarding();
+        },
+    },
+    {
+        name: 'doctor',
+        description: 'Diagnostics',
+        handler: async (_args) => {
+            const { runDoctor } = await import('./core/doctor.js');
+            await runDoctor();
+        },
+    },
+    // install --plugin 제거됨 — postinstall이 유일한 설치 경로
+    // 수동 재설치: node scripts/postinstall.js
+    {
+        name: 'uninstall',
+        description: 'Remove forgen from settings [--force]',
+        handler: async (args) => {
+            const { handleUninstall } = await import('./core/uninstall.js');
+            await handleUninstall(process.cwd(), { force: args.includes('--force') });
+        },
+    },
+];
+/** 최소 편집 거리 (유사 명령 제안용) */
+function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1]
+                ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+function findCommand(name) {
+    return commands.find((c) => c.name === name || (c.aliases?.includes(name)));
+}
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+async function main() {
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+        printHelp();
+        return;
+    }
+    if (args[0] === '--version' || args[0] === '-V') {
+        console.log(PKG_VERSION);
+        return;
+    }
+    const cmd = findCommand(args[0]);
+    if (cmd) {
+        await cmd.handler(args.slice(1));
+        return;
+    }
+    // 등록되지 않은 서브커맨드는 에러 처리
+    // 플래그(--resume 등), 따옴표 프롬프트, 인자 없는 실행은 하네스로 통과
+    if (args[0] && !args[0].startsWith('-') && !args[0].startsWith('"') && !args[0].startsWith("'")) {
+        const suggestion = commands
+            .map(c => ({ name: c.name, dist: levenshtein(args[0], c.name) }))
+            .filter(c => c.dist <= 3)
+            .sort((a, b) => a.dist - b.dist)[0];
+        const hint = suggestion ? `\n  Did you mean: forgen ${suggestion.name}` : '';
+        console.error(`[forgen] Unknown command: ${args[0]}${hint}\n  Run "forgen help" for available commands.`);
+        process.exit(1);
+    }
+    // Default: run Claude Code with harness
+    try {
+        const firstRun = isFirstRun();
+        if (firstRun) {
+            console.log(`
+  ╔══════════════════════════════════════════════╗
+  ║  Welcome to Forgen                          ║
+  ╚══════════════════════════════════════════════╝
+
+  The more you use Claude with Forgen,
+  the better Claude gets at helping YOU.
+
+  Setting up...`);
+        }
+        let context = await prepareHarness(process.cwd());
+        // 첫 실행 또는 프로필 없음 → 자동 온보딩 (interactive 환경)
+        if (context.v1.needsOnboarding && process.stdin.isTTY) {
+            console.log('\n  프로필이 없습니다. 온보딩을 시작합니다.\n');
+            const { runOnboarding } = await import('./forge/onboarding-cli.js');
+            await runOnboarding();
+            // 온보딩 후 harness 재실행 (프로필 반영)
+            context = await prepareHarness(process.cwd());
+        }
+        if (firstRun && !context.v1.needsOnboarding) {
+            console.log(`
+  Setup complete!
+`);
+        }
+        const bold = '\x1b[1m';
+        const cyan = '\x1b[36m';
+        const dim = '\x1b[2m';
+        const reset = '\x1b[0m';
+        console.log(`
+  ${bold}${cyan}█▀▀ █▀█ █▀█ █▀▀ █▀▀ █▄░█${reset}
+  ${bold}${cyan}█▀▀ █▄█ █▀▄ █▄█ ██▄ █░▀█${reset}  ${dim}v${PKG_VERSION}${reset}
+
+  ${dim}Code, forged for you.${reset}
+  ${dim}Scope: v1(${context.v1.session?.quality_pack ?? 'onboarding needed'})${reset}
+`);
+        console.log('[forgen] Starting Claude Code...\n');
+        await spawnClaude(args, context);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('ENOENT') && msg.includes('claude')) {
+            console.error('[forgen] Claude Code not found. Install: npm install -g @anthropic-ai/claude-code');
+        }
+        else {
+            console.error('[forgen] Error:', msg);
+        }
+        process.exit(1);
+    }
+}
+// ---------------------------------------------------------------------------
+// printHelp
+// ---------------------------------------------------------------------------
+function printHelp() {
+    console.log(`
+  Forgen v${PKG_VERSION}
+  The more you use Claude, the better it knows you.
+
+  Usage:
+    forgen                          Start Claude Code (harness mode)
+    forgen "prompt"                 Start with a prompt
+    forgen --resume                 Resume previous session
+
+  Commands:
+    forgen forge                    Personalize your coding profile
+    forgen onboarding               Run 2-question onboarding
+    forgen inspect [profile|rules|evidence|session]
+                                    Inspect v1 state
+    forgen compound                 Manage accumulated knowledge
+    forgen me                       Personal dashboard
+    forgen init                     Initialize project
+    forgen config hooks             Hook management
+    forgen mcp                      MCP server management
+    forgen skill promote|list       Skill management
+    forgen notepad show|add|clear   Session notepad
+    forgen doctor                   System diagnostics
+    forgen uninstall                Remove forgen
+
+  Harness mode (default):
+    Wraps Claude Code with personalization, auto-compound, and safety hooks.
+`);
+}
+main().catch(() => {
+    process.exit(1);
+});

package/dist/core/auto-compound-runner.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Forgen — Auto Compound Runner
+ *
+ * Detached process로 실행. 이전 세션의 transcript를 분석하여:
+ * 1. 재사용 가능한 솔루션 추출 (compound --solution)
+ * 2. 사용자 패턴을 USER.md에 축적
+ *
+ * 호출: session-recovery hook 또는 spawn.ts에서 detached spawn
+ * 인자: [cwd] [transcriptPath] [sessionId]
+ */
+export {};