@wooojin/forgen 0.1.0

package/dist/hooks/shared/atomic-write.js

@@ -0,0 +1,148 @@
+/**
+ * 훅 공유 유틸: 원자적 파일 쓰기
+ *
+ * write → rename 패턴으로 동시 세션에서의 상태 파일 손상을 방지합니다.
+ *
+ * 보안 모델:
+ *   - mode 옵션이 0o600인 파일은 같은 호스트의 다른 user로부터 보호.
+ *   - tmp 파일은 PID + randomBytes(6) suffix → 같은 process가 동시 atomic write를
+ *     하더라도 tmp 충돌 없음. symlink TOCTOU도 방지.
+ *
+ * Windows 한계:
+ *   - fchmodSync/chmodSync는 Windows에서 read-only 비트만 영향. 0o600 같은
+ *     POSIX 권한은 의미가 없으며, 보안은 OS-level ACL과 사용자 home 격리에 의존.
+ *   - 민감 데이터는 Windows에서 추가 보호가 필요할 수 있다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { STATE_DIR } from '../../core/paths.js';
+// L1 hardening: O_NOFOLLOW로 symlink 공격 차단 (POSIX only).
+// Windows에는 정의되지 않으므로 0으로 fallback (no-op flag).
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+/**
+ * 부모 디렉터리 생성. 민감한 cache 디렉터리는 0o700으로 강제.
+ *
+ * H13 fix (security review): caller가 dirMode를 명시 안 해도, STATE_DIR
+ * 하위 경로는 자동으로 0o700으로 강제한다. 50+ caller가 dirMode를 매번
+ * 명시할 필요 없이 STATE_DIR 권한 보장.
+ *
+ * 호출자가 명시한 mode가 있으면 그 값을 우선한다.
+ */
+function ensureDir(dir, mode) {
+    // STATE_DIR 자동 감지: caller가 mode 미지정 시에만 0o700 default.
+    // STATE_DIR이 undefined인 환경(테스트 mock 등)에선 자동 감지를 skip한다.
+    const isStateDir = typeof STATE_DIR === 'string'
+        && (dir === STATE_DIR || dir.startsWith(STATE_DIR + path.sep));
+    const effectiveMode = mode ?? (isStateDir ? 0o700 : undefined);
+    fs.mkdirSync(dir, { recursive: true, ...(effectiveMode !== undefined ? { mode: effectiveMode } : {}) });
+    if (effectiveMode !== undefined && process.platform !== 'win32') {
+        // mkdirSync mode는 umask 영향을 받으므로 chmod로 강제 (POSIX only)
+        try {
+            fs.chmodSync(dir, effectiveMode);
+        }
+        catch { /* non-fatal — ACL 환경 등 */ }
+    }
+}
+/**
+ * tmp 파일 경로 생성. PID + random suffix로 충돌 방지 (M17 fix).
+ * 같은 process가 같은 디렉터리에 동시 atomic write 해도 안전.
+ */
+function makeTmpPath(filePath) {
+    const suffix = randomBytes(6).toString('hex');
+    return `${filePath}.tmp.${process.pid}.${suffix}`;
+}
+/**
+ * JSON 데이터를 원자적으로 파일에 기록 (tmp → rename)
+ *
+ * @param options.pretty 들여쓴 포맷으로 직렬화
+ * @param options.mode   생성될 파일의 권한 (예: 0o600). 기본값은 umask 의존(보통 0o644).
+ *                       민감한 캐시(컨텍스트 식별자/태그 포함)에 대해서는 0o600 권장.
+ * @param options.dirMode 부모 디렉터리 mode. cache는 0o700 권장.
+ *
+ * 권한 보장 (M6+M16+M17 fix):
+ *   1. tmp 파일이 random suffix → 다른 fd 충돌 없음 (Promise.all 안전).
+ *   2. fd 단위 fchmodSync로 새 inode 권한 강제.
+ *   3. post-rename chmodSync 실패는 throw — 느슨한 권한 침묵 방지.
+ *   4. Windows에서는 위 mode가 무효일 수 있으나, OS-level ACL이 일반적으로 user 격리.
+ */
+export function atomicWriteJSON(filePath, data, options) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir, options?.dirMode);
+    const tmpFile = makeTmpPath(filePath);
+    try {
+        const json = options?.pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+        // O_EXCL: 새 inode 생성 보장 / O_NOFOLLOW: symlink 공격 차단 (POSIX only)
+        const fd = fs.openSync(tmpFile, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, options?.mode ?? 0o644);
+        try {
+            fs.writeFileSync(fd, json);
+            if (options?.mode !== undefined) {
+                // fd 단위 fchmod로 새 inode 권한 강제 (POSIX only — Windows no-op)
+                try {
+                    fs.fchmodSync(fd, options.mode);
+                }
+                catch { /* Windows fallback */ }
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmpFile, filePath);
+        if (options?.mode !== undefined && process.platform !== 'win32') {
+            // POSIX: rename 후에도 명시적 chmod로 보장. 실패 시 throw (M6).
+            // Windows: chmodSync가 read-only 비트만 영향. 의미 없으므로 skip.
+            fs.chmodSync(filePath, options.mode);
+        }
+    }
+    catch (e) {
+        // rename 실패 시 tmp 파일 정리
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch { /* tmp file cleanup — leftover .tmp file is harmless if unlink fails */ }
+        throw e;
+    }
+}
+/** 텍스트를 원자적으로 파일에 기록 (tmp → rename) */
+export function atomicWriteText(filePath, content, options) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir, options?.dirMode);
+    const tmpFile = makeTmpPath(filePath);
+    try {
+        // O_EXCL: 새 inode 생성 보장 / O_NOFOLLOW: symlink 공격 차단 (POSIX only)
+        const fd = fs.openSync(tmpFile, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, options?.mode ?? 0o644);
+        try {
+            fs.writeFileSync(fd, content, 'utf-8');
+            if (options?.mode !== undefined) {
+                try {
+                    fs.fchmodSync(fd, options.mode);
+                }
+                catch { /* Windows fallback */ }
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmpFile, filePath);
+        if (options?.mode !== undefined && process.platform !== 'win32') {
+            fs.chmodSync(filePath, options.mode);
+        }
+    }
+    catch (e) {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch { /* cleanup */ }
+        throw e;
+    }
+}
+/** JSON 파일을 안전하게 읽기 (파싱 실패 시 fallback 반환) */
+export function safeReadJSON(filePath, fallback) {
+    try {
+        if (fs.existsSync(filePath)) {
+            return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+    }
+    catch { /* JSON parse failure — return fallback */ }
+    return fallback;
+}

package/dist/hooks/shared/context-budget.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Forgen — Adaptive Context Budget
+ *
+ * 다른 플러그인이 감지되면 forgen의 컨텍스트 주입량을 동적으로 조절합니다.
+ * "양보 원칙": 컨텍스트 경쟁 시 forgen가 먼저 축소합니다.
+ *
+ * 버짓 계산:
+ *   - 다른 플러그인 없음: factor = 1.0 (INJECTION_CAPS 그대로)
+ *   - 훅 기반 메모리 플러그인 감지 (OMC, claude-mem 등): factor = 0.5 (50% 축소)
+ *
+ * 설계 결정:
+ *   - 감지 결과는 plugin-detector에서 캐시 (1시간 TTL)
+ *   - 하드캡(INJECTION_CAPS)을 초과하지 않음
+ *   - MCP 기반 플러그인(Playwright, Context7 등)은 온디맨드 호출이므로
+ *     상시 컨텍스트를 점유하지 않아 factor에 영향 없음
+ */
+export interface ContextBudget {
+    /** solution-injector 세션 총 주입 상한 (chars) */
+    solutionSessionMax: number;
+    /** solution 하나당 최대 글자 수 */
+    solutionMax: number;
+    /** 프롬프트당 최대 솔루션 수 */
+    solutionsPerPrompt: number;
+    /** notepad-injector 최대 글자 수 */
+    notepadMax: number;
+    /** skill-injector 스킬당 최대 글자 수 */
+    skillContentMax: number;
+    /** 축소 계수 (1.0 = 전체, 0.5 = 반) */
+    factor: number;
+    /** 다른 플러그인 감지 여부 */
+    otherPluginsDetected: boolean;
+}
+/**
+ * 현재 환경에 맞는 컨텍스트 버짓을 계산합니다.
+ * 다른 플러그인이 감지되면 주입량을 축소합니다.
+ */
+export declare function calculateBudget(cwd?: string): ContextBudget;

package/dist/hooks/shared/context-budget.js

@@ -0,0 +1,45 @@
+/**
+ * Forgen — Adaptive Context Budget
+ *
+ * 다른 플러그인이 감지되면 forgen의 컨텍스트 주입량을 동적으로 조절합니다.
+ * "양보 원칙": 컨텍스트 경쟁 시 forgen가 먼저 축소합니다.
+ *
+ * 버짓 계산:
+ *   - 다른 플러그인 없음: factor = 1.0 (INJECTION_CAPS 그대로)
+ *   - 훅 기반 메모리 플러그인 감지 (OMC, claude-mem 등): factor = 0.5 (50% 축소)
+ *
+ * 설계 결정:
+ *   - 감지 결과는 plugin-detector에서 캐시 (1시간 TTL)
+ *   - 하드캡(INJECTION_CAPS)을 초과하지 않음
+ *   - MCP 기반 플러그인(Playwright, Context7 등)은 온디맨드 호출이므로
+ *     상시 컨텍스트를 점유하지 않아 factor에 영향 없음
+ */
+import { INJECTION_CAPS } from './injection-caps.js';
+import { hasContextInjectingPlugins } from '../../core/plugin-detector.js';
+// ── 버짓 계산 ──
+/**
+ * 현재 환경에 맞는 컨텍스트 버짓을 계산합니다.
+ * 다른 플러그인이 감지되면 주입량을 축소합니다.
+ */
+export function calculateBudget(cwd) {
+    let otherPluginsDetected = false;
+    let factor = 1.0;
+    try {
+        otherPluginsDetected = hasContextInjectingPlugins(cwd);
+        if (otherPluginsDetected)
+            factor = 0.5;
+    }
+    catch {
+        // 감지 실패 시 보수적 기본값 (충돌 없음으로 간주하면 위험)
+        factor = 0.7;
+    }
+    return {
+        solutionSessionMax: Math.floor(INJECTION_CAPS.solutionSessionMax * factor),
+        solutionMax: factor < 1.0 ? 800 : INJECTION_CAPS.solutionMax,
+        solutionsPerPrompt: factor < 1.0 ? 2 : 3,
+        notepadMax: Math.floor(INJECTION_CAPS.notepadMax * factor),
+        skillContentMax: Math.floor(INJECTION_CAPS.skillContentMax * factor),
+        factor,
+        otherPluginsDetected,
+    };
+}

package/dist/hooks/shared/file-lock.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 파일 단위 advisory lock — read-modify-write race 방지
+ *
+ * 문제:
+ *   - injection cache를 여러 hook(solution-injector / pre-tool-use / backfill)이
+ *     read → modify → write 패턴으로 갱신하지만 락이 없어서 last-writer-wins.
+ *   - rename atomicity는 찢어진 JSON만 막을 뿐, 동시 mutator의 변경을 보존하지 못한다.
+ *
+ * 해결:
+ *   - O_EXCL로 `${target}.lock` 파일 생성 → exclusive lock.
+ *   - withFileLock() 안에서 호출되는 fn은 fresh re-read 후 mutate해야 함.
+ *   - lock holder가 죽어 stale lock이 남으면 mtime + PID 검증으로 안전 회수.
+ *   - lock 파일에 randomBytes token 기록, release 시 token 일치할 때만 unlink
+ *     → cascade lock loss 방지 (H4+H7 fix).
+ *
+ * 외부 의존성 없음. 다중 OS 호환 (POSIX + Windows).
+ *
+ * Windows 한계:
+ *   - file-lock 자체는 동작하지만, 같은 process의 다른 fd가 lock 파일을 read하지
+ *     못하게 막지는 않는다 (advisory lock).
+ *   - lock 파일 mode 0o600은 POSIX에서만 의미. Windows는 ACL 기반.
+ */
+export interface FileLockOptions {
+    /** 락 획득 최대 대기 시간 (ms). 초과 시 throw. */
+    timeoutMs?: number;
+    /** 이만큼 오래된 lock 파일은 stale로 간주하고 강제 회수 (ms). */
+    staleMs?: number;
+}
+/**
+ * file-lock 자체 결함 (Sentinel).
+ * caller try/catch가 lock 결함과 fn 실패를 구분할 수 있도록 별도 클래스.
+ */
+export declare class FileLockError extends Error {
+    readonly cause: NodeJS.ErrnoException;
+    readonly lockPath: string;
+    constructor(cause: NodeJS.ErrnoException, lockPath: string);
+}
+/**
+ * 락을 획득한 후 fn을 실행하고, 끝나면 락을 해제한다.
+ *
+ * fn은 동기 또는 async 모두 지원. 예외가 발생해도 락은 항상 해제된다.
+ *
+ * release 시 lock token을 검증해 자기가 만든 lock만 unlink한다 (H4+H7 fix).
+ *
+ * 사용 예:
+ * ```ts
+ * await withFileLock(cachePath, () => {
+ *   const fresh = readCacheFromDisk(cachePath); // lock 안에서 fresh re-read
+ *   const merged = mergeWithUpdates(fresh);
+ *   atomicWriteJSON(cachePath, merged, { mode: 0o600 });
+ * });
+ * ```
+ */
+export declare function withFileLock<T>(targetPath: string, fn: () => T | Promise<T>, options?: FileLockOptions): Promise<T>;
+/** 동기 버전 — async fn을 받지 않음. setTimeout 대신 짧은 spin으로 대기. */
+export declare function withFileLockSync<T>(targetPath: string, fn: () => T, options?: FileLockOptions): T;

package/dist/hooks/shared/file-lock.js

@@ -0,0 +1,253 @@
+/**
+ * 파일 단위 advisory lock — read-modify-write race 방지
+ *
+ * 문제:
+ *   - injection cache를 여러 hook(solution-injector / pre-tool-use / backfill)이
+ *     read → modify → write 패턴으로 갱신하지만 락이 없어서 last-writer-wins.
+ *   - rename atomicity는 찢어진 JSON만 막을 뿐, 동시 mutator의 변경을 보존하지 못한다.
+ *
+ * 해결:
+ *   - O_EXCL로 `${target}.lock` 파일 생성 → exclusive lock.
+ *   - withFileLock() 안에서 호출되는 fn은 fresh re-read 후 mutate해야 함.
+ *   - lock holder가 죽어 stale lock이 남으면 mtime + PID 검증으로 안전 회수.
+ *   - lock 파일에 randomBytes token 기록, release 시 token 일치할 때만 unlink
+ *     → cascade lock loss 방지 (H4+H7 fix).
+ *
+ * 외부 의존성 없음. 다중 OS 호환 (POSIX + Windows).
+ *
+ * Windows 한계:
+ *   - file-lock 자체는 동작하지만, 같은 process의 다른 fd가 lock 파일을 read하지
+ *     못하게 막지는 않는다 (advisory lock).
+ *   - lock 파일 mode 0o600은 POSIX에서만 의미. Windows는 ACL 기반.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { randomBytes } from 'node:crypto';
+// L1 hardening: O_NOFOLLOW로 symlink 공격 차단 (POSIX only).
+// Windows에는 정의되지 않으므로 0으로 fallback (no-op flag).
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const DEFAULT_TIMEOUT_MS = 2000;
+/**
+ * staleMs는 fn 실행 시간 상한 + 안전 여유. 5초는 너무 짧아서 정상 holder가
+ * 5.x초 fn 실행 중일 때 다른 holder가 stale로 가로챌 수 있었다 (M13).
+ * 30초로 늘려 일반 cache 갱신은 안전 마진 확보.
+ *
+ * backfill 같은 짧은 fn은 호출자가 staleMs를 단축할 수 있다.
+ */
+const DEFAULT_STALE_MS = 30000;
+const RETRY_MIN_MS = 5;
+const RETRY_MAX_MS = 25;
+/**
+ * file-lock 자체 결함 (Sentinel).
+ * caller try/catch가 lock 결함과 fn 실패를 구분할 수 있도록 별도 클래스.
+ */
+export class FileLockError extends Error {
+    cause;
+    lockPath;
+    constructor(cause, lockPath) {
+        // PR2c-4 (security M-3): basename만 노출. 전체 path는 sessionId를 포함하므로
+        // 로그에 남으면 정보 노출 위험. 디버그 시 caller가 e.lockPath로 명시 접근 가능.
+        super(`File lock failure on ${path.basename(lockPath)}: ${cause.code ?? cause.message}`);
+        this.cause = cause;
+        this.lockPath = lockPath;
+        this.name = 'FileLockError';
+    }
+}
+/**
+ * lock 파일 내용을 파싱한다. 손상된 lock은 null 반환.
+ */
+function readLockMeta(lockPath) {
+    try {
+        const raw = fs.readFileSync(lockPath, 'utf-8');
+        const meta = JSON.parse(raw);
+        if (typeof meta.pid !== 'number' || typeof meta.ts !== 'number' || typeof meta.token !== 'string') {
+            return null;
+        }
+        return meta;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * PID가 살아있는지 확인한다 (POSIX).
+ * Windows에서는 process.kill(pid, 0)이 동작하지 않으므로 항상 true 반환.
+ */
+function isPidAlive(pid) {
+    if (process.platform === 'win32')
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        const code = e.code;
+        return code !== 'ESRCH';
+    }
+}
+/**
+ * stale lock이면 안전하게 회수 시도. 회수 성공하면 true.
+ * - mtime 기반 + PID alive 검증으로 false positive 줄임.
+ * - 다른 holder가 그 사이에 lock을 잡은 경우는 회수하지 않음.
+ *
+ * Race window 분석 (R-M1 주석 보강):
+ *   statSync(102)와 readLockMeta(108) 사이에 holder 교체가 일어날 수 있다.
+ *   즉, mtime이 stale 기준을 통과한 시점에 첫 holder가 release하고 두 번째
+ *   holder가 lock을 잡으면, 우리가 읽는 meta는 새 holder의 것이다.
+ *   그러나 새 holder의 PID는 보통 alive이므로 isPidAlive 가드에서 false 반환
+ *   → 회수 안 함. fail-safe 방향으로 동작한다.
+ *   PID가 dead인 케이스에만 unlink하므로 잘못된 회수 위험은 매우 낮다.
+ */
+function tryRecoverStaleLock(lockPath, staleMs) {
+    let lockStat;
+    try {
+        lockStat = fs.statSync(lockPath);
+    }
+    catch {
+        return true; // lock 사라짐 — 즉시 재시도
+    }
+    if (Date.now() - lockStat.mtimeMs <= staleMs)
+        return false;
+    const meta = readLockMeta(lockPath);
+    // PID 살아있으면 회수 안 함 (정상 long-running holder).
+    // stat-meta race에서 새 holder를 본 경우에도 여기서 fail-safe로 차단.
+    if (meta && isPidAlive(meta.pid))
+        return false;
+    // 회수 시도. 그 사이 다른 holder가 잡았을 수 있으므로 unlink는 best-effort.
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch { /* 이미 회수됐을 수 있음 */ }
+    return true;
+}
+/**
+ * 락을 획득한 후 fn을 실행하고, 끝나면 락을 해제한다.
+ *
+ * fn은 동기 또는 async 모두 지원. 예외가 발생해도 락은 항상 해제된다.
+ *
+ * release 시 lock token을 검증해 자기가 만든 lock만 unlink한다 (H4+H7 fix).
+ *
+ * 사용 예:
+ * ```ts
+ * await withFileLock(cachePath, () => {
+ *   const fresh = readCacheFromDisk(cachePath); // lock 안에서 fresh re-read
+ *   const merged = mergeWithUpdates(fresh);
+ *   atomicWriteJSON(cachePath, merged, { mode: 0o600 });
+ * });
+ * ```
+ */
+export async function withFileLock(targetPath, fn, options) {
+    const lockPath = `${targetPath}.lock`;
+    const timeout = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const stale = options?.staleMs ?? DEFAULT_STALE_MS;
+    const start = Date.now();
+    const myToken = randomBytes(16).toString('hex');
+    let acquired = false;
+    while (!acquired) {
+        try {
+            // O_EXCL: 파일이 이미 존재하면 EEXIST 반환
+            // O_NOFOLLOW: symlink 공격 차단 (POSIX only, Windows는 0으로 fallback)
+            const fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
+            try {
+                const meta = { pid: process.pid, ts: Date.now(), token: myToken };
+                fs.writeSync(fd, JSON.stringify(meta));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            acquired = true;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== 'EEXIST') {
+                // EACCES, EXDEV, ENOSPC 등 — sentinel error로 wrap (H5 fix)
+                throw new FileLockError(e, lockPath);
+            }
+            // 이미 lock이 있음 — stale 검증 후 회수 시도
+            if (tryRecoverStaleLock(lockPath, stale)) {
+                continue;
+            }
+            if (Date.now() - start > timeout) {
+                throw new Error(`File lock timeout after ${timeout}ms`);
+            }
+            // 짧은 backoff (jitter 포함)
+            const wait = RETRY_MIN_MS + Math.floor(Math.random() * (RETRY_MAX_MS - RETRY_MIN_MS));
+            await new Promise(r => setTimeout(r, wait));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // H4+H7 fix: token 검증 후에만 unlink. stale recovery로 다른 holder가
+        // 잡은 lock을 우리가 지우지 않도록 보장.
+        try {
+            const meta = readLockMeta(lockPath);
+            if (meta && meta.token === myToken) {
+                fs.unlinkSync(lockPath);
+            }
+            // token 다르면 stale로 회수당한 후 다른 holder가 잡은 것 — 건드리지 않음
+        }
+        catch { /* lock 이미 사라짐 */ }
+    }
+}
+/** 동기 버전 — async fn을 받지 않음. setTimeout 대신 짧은 spin으로 대기. */
+export function withFileLockSync(targetPath, fn, options) {
+    const lockPath = `${targetPath}.lock`;
+    const timeout = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const stale = options?.staleMs ?? DEFAULT_STALE_MS;
+    const start = Date.now();
+    const myToken = randomBytes(16).toString('hex');
+    let acquired = false;
+    while (!acquired) {
+        try {
+            // M-1 fix: sync 경로도 async와 동일하게 O_NOFOLLOW로 symlink 차단
+            const fd = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
+            try {
+                const meta = { pid: process.pid, ts: Date.now(), token: myToken };
+                fs.writeSync(fd, JSON.stringify(meta));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            acquired = true;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== 'EEXIST') {
+                throw new FileLockError(e, lockPath);
+            }
+            if (tryRecoverStaleLock(lockPath, stale)) {
+                continue;
+            }
+            if (Date.now() - start > timeout) {
+                throw new Error(`File lock timeout after ${timeout}ms`);
+            }
+            // 동기 spin: Atomics.wait로 짧게 대기 (이벤트 루프 블로킹은 의도된 것)
+            const wait = RETRY_MIN_MS + Math.floor(Math.random() * (RETRY_MAX_MS - RETRY_MIN_MS));
+            try {
+                const sab = new SharedArrayBuffer(4);
+                const view = new Int32Array(sab);
+                Atomics.wait(view, 0, 0, wait);
+            }
+            catch {
+                // SharedArrayBuffer/Atomics 미지원 환경 — bounded busy wait로 폴백
+                // (Cloudflare Workers 등에서 throw 후 즉시 다음 iteration 진입 방지)
+                const end = Date.now() + wait;
+                while (Date.now() < end) { /* bounded busy wait */ }
+            }
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            const meta = readLockMeta(lockPath);
+            if (meta && meta.token === myToken) {
+                fs.unlinkSync(lockPath);
+            }
+        }
+        catch { /* skip */ }
+    }
+}

package/dist/hooks/shared/hook-response.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Forgen — Hook Response Utilities
+ *
+ * Claude Code Plugin SDK 공식 형식에 맞는 훅 응답 생성.
+ *
+ * 공식 형식 (검증 완료 — claude-code 소스 기반):
+ *   hookSpecificOutput은 discriminated union이며 hookEventName이 필수.
+ *   - PreToolUse: { hookEventName, permissionDecision, permissionDecisionReason? }
+ *   - UserPromptSubmit: { hookEventName, additionalContext? }
+ *   - SessionStart: { hookEventName, additionalContext?, initialUserMessage? }
+ *
+ * 주의:
+ *   systemMessage 필드는 UI 표시용으로만 사용되며 모델에 전달되지 않음.
+ *   모델에 컨텍스트를 주입하려면 반드시 additionalContext를 사용해야 함.
+ */
+/** 통과 응답 (컨텍스트 없음, 모든 이벤트 공통) */
+export declare function approve(): string;
+/**
+ * 통과 + 모델에 컨텍스트 주입.
+ * UserPromptSubmit, SessionStart 이벤트에서만 모델에 도달함.
+ */
+export declare function approveWithContext(context: string, eventName: string): string;
+/**
+ * 통과 + UI 경고 표시 (모델에는 전달되지 않음).
+ * PostToolUse, PreToolUse 경고 등 모델 도달이 불필요한 경우 사용.
+ */
+export declare function approveWithWarning(warning: string): string;
+/** 차단 응답 (PreToolUse 전용) */
+export declare function deny(reason: string): string;
+/** 사용자 확인 요청 (PreToolUse 전용) */
+export declare function ask(reason: string): string;
+/** fail-open: 에러 시 안전하게 통과 */
+export declare function failOpen(): string;

package/dist/hooks/shared/hook-response.js

@@ -0,0 +1,62 @@
+/**
+ * Forgen — Hook Response Utilities
+ *
+ * Claude Code Plugin SDK 공식 형식에 맞는 훅 응답 생성.
+ *
+ * 공식 형식 (검증 완료 — claude-code 소스 기반):
+ *   hookSpecificOutput은 discriminated union이며 hookEventName이 필수.
+ *   - PreToolUse: { hookEventName, permissionDecision, permissionDecisionReason? }
+ *   - UserPromptSubmit: { hookEventName, additionalContext? }
+ *   - SessionStart: { hookEventName, additionalContext?, initialUserMessage? }
+ *
+ * 주의:
+ *   systemMessage 필드는 UI 표시용으로만 사용되며 모델에 전달되지 않음.
+ *   모델에 컨텍스트를 주입하려면 반드시 additionalContext를 사용해야 함.
+ */
+/** 통과 응답 (컨텍스트 없음, 모든 이벤트 공통) */
+export function approve() {
+    return JSON.stringify({ continue: true });
+}
+/**
+ * 통과 + 모델에 컨텍스트 주입.
+ * UserPromptSubmit, SessionStart 이벤트에서만 모델에 도달함.
+ */
+export function approveWithContext(context, eventName) {
+    return JSON.stringify({
+        continue: true,
+        hookSpecificOutput: { hookEventName: eventName, additionalContext: context },
+    });
+}
+/**
+ * 통과 + UI 경고 표시 (모델에는 전달되지 않음).
+ * PostToolUse, PreToolUse 경고 등 모델 도달이 불필요한 경우 사용.
+ */
+export function approveWithWarning(warning) {
+    return JSON.stringify({ continue: true, suppressOutput: false, systemMessage: warning });
+}
+/** 차단 응답 (PreToolUse 전용) */
+export function deny(reason) {
+    return JSON.stringify({
+        continue: false,
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    });
+}
+/** 사용자 확인 요청 (PreToolUse 전용) */
+export function ask(reason) {
+    return JSON.stringify({
+        continue: true,
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'ask',
+            permissionDecisionReason: reason,
+        },
+    });
+}
+/** fail-open: 에러 시 안전하게 통과 */
+export function failOpen() {
+    return JSON.stringify({ continue: true });
+}

package/dist/hooks/shared/injection-caps.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Forgen — Injection Caps
+ *
+ * 컨텍스트 주입 하드캡 상수. 다른 플러그인과 공존 시 컨텍스트 윈도우를
+ * 과도하게 점유하지 않도록 각 훅의 최대 주입량을 제한합니다.
+ *
+ * 이 값들은 어댑티브 버짓 시스템의 "절대 상한"이며,
+ * 실제 주입량은 context-budget.ts에서 동적으로 조절됩니다.
+ */
+export declare const INJECTION_CAPS: {
+    /** notepad-injector: 노트패드 최대 주입 글자 수 (현재: 무제한 → 2000) */
+    readonly notepadMax: 2000;
+    /** skill-injector: 스킬 파일 하나당 최대 글자 수 (현재: 무제한 → 3000) */
+    readonly skillContentMax: 3000;
+    /** solution-injector: 솔루션 하나당 최대 글자 수 (기존 값 유지) */
+    readonly solutionMax: 1500;
+    /** solution-injector: 세션 전체 주입 상한 (기존 값 유지) */
+    readonly solutionSessionMax: 8000;
+};
+/**
+ * .claude/rules/ 자동생성 파일의 사이즈 하드캡.
+ * rules 파일은 Claude Code가 세션 시작 시 전부 로드하므로
+ * 무제한 성장을 방지해야 합니다.
+ *
+ * 근거: Claude Code 공식 권장 — "CLAUDE.md 파일당 200줄 이하",
+ * "길수록 지시 준수율 저하". 3000자 ≈ 60~80줄.
+ */
+export declare const RULE_FILE_CAPS: {
+    /** .claude/rules/ 파일 1개당 최대 글자 수 */
+    readonly perRuleFile: 3000;
+    /** .claude/rules/에 forgen가 쓸 수 있는 총량 (글자) */
+    readonly totalRuleFiles: 15000;
+    /** compound.md에 포함할 rule summary 최대 수 */
+    readonly maxRuleSummaries: 10;
+};
+/** truncation 시 끝에 추가되는 표시 */
+export declare const TRUNCATION_SUFFIX = "\n... (truncated)";
+/** 주어진 content를 maxChars로 잘라서 반환. 초과 시 truncation suffix 추가. */
+export declare function truncateContent(content: string, maxChars: number): string;