@wooojin/forgen 0.4.0 → 0.4.3

package/dist/host/install-claude.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Claude InstallPlan — feat/codex-support Phase 1 (P1-2)
+ *
+ * `npm install` postinstall.js 의 *Claude 측* 4 작업을 module 로 분리.
+ * `forgen install claude` CLI 가 호출 + (P1-6 에서) postinstall.js 도 위임.
+ *
+ * 4 작업:
+ *   1. Plugin cache: ~/.claude/plugins/cache/forgen-local/forgen/<ver>/ 작성 + installed_plugins.json 등록
+ *   2. Slash commands: ~/.claude/commands/forgen/*.md 생성 (forgen-managed marker)
+ *   3. Settings hooks injection: ~/.claude/settings.json 의 hooks 머지 (forgen entry idempotent)
+ *   4. MCP register: ~/.claude.json 에 mcpServers.forgen-compound 추가
+ *
+ * 사용자 비-forgen 자산 보존 + 재실행 idempotent.
+ */
+export interface ClaudeInstallOptions {
+    pkgRoot: string;
+    /** Override home dir (default: os.homedir()). 격리 테스트용. */
+    homeDir?: string;
+    /** Dry-run: 파일 미작성, 결과만 반환. */
+    dryRun?: boolean;
+    /** MCP forgen-compound 등록 여부 (default true). */
+    registerMcp?: boolean;
+}
+export interface ClaudeInstallResult {
+    homeDir: string;
+    pluginCachePath: string;
+    pluginCacheWritten: boolean;
+    slashCommandsPath: string;
+    slashCommandsCount: number;
+    settingsPath: string;
+    hooksInjected: number;
+    mcpRegistered: boolean;
+    mcpAlreadyPresent: boolean;
+}
+export declare function planClaudeInstall(opts: ClaudeInstallOptions): ClaudeInstallResult;

package/dist/host/install-claude.js

@@ -0,0 +1,238 @@
+/**
+ * Claude InstallPlan — feat/codex-support Phase 1 (P1-2)
+ *
+ * `npm install` postinstall.js 의 *Claude 측* 4 작업을 module 로 분리.
+ * `forgen install claude` CLI 가 호출 + (P1-6 에서) postinstall.js 도 위임.
+ *
+ * 4 작업:
+ *   1. Plugin cache: ~/.claude/plugins/cache/forgen-local/forgen/<ver>/ 작성 + installed_plugins.json 등록
+ *   2. Slash commands: ~/.claude/commands/forgen/*.md 생성 (forgen-managed marker)
+ *   3. Settings hooks injection: ~/.claude/settings.json 의 hooks 머지 (forgen entry idempotent)
+ *   4. MCP register: ~/.claude.json 에 mcpServers.forgen-compound 추가
+ *
+ * 사용자 비-forgen 자산 보존 + 재실행 idempotent.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { generateHooksJson } from '../hooks/hooks-generator.js';
+const PLUGIN_KEY = 'forgen@forgen-local';
+const FORGEN_MANAGED_MARKER = '<!-- forgen-managed -->';
+function readPkgVersion(pkgRoot) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// ── 1. Plugin cache ────────────────────────────────────────────────────
+function writePluginCache(opts) {
+    const { pkgRoot, cacheDir, pluginsDir, version, dryRun } = opts;
+    if (dryRun)
+        return false;
+    const cacheParent = path.dirname(cacheDir);
+    // 이전 잔재 제거 + 디렉토리 작성
+    try {
+        fs.rmSync(cacheParent, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+    fs.mkdirSync(cacheParent, { recursive: true });
+    // 1차: symlink 시도 (개발 환경)
+    let linked = false;
+    try {
+        fs.symlinkSync(pkgRoot, cacheDir, 'dir');
+        linked = true;
+    }
+    catch {
+        // symlink 실패 → cp fallback
+    }
+    if (!linked) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+        const copyDirs = ['.claude-plugin', 'hooks', 'skills', 'assets'];
+        for (const dir of copyDirs) {
+            const src = path.join(pkgRoot, dir);
+            if (fs.existsSync(src))
+                fs.cpSync(src, path.join(cacheDir, dir), { recursive: true });
+        }
+        if (fs.existsSync(path.join(pkgRoot, 'dist'))) {
+            fs.cpSync(path.join(pkgRoot, 'dist'), path.join(cacheDir, 'dist'), { recursive: true });
+        }
+        // core deps
+        const coreDeps = ['js-yaml', '@modelcontextprotocol', 'zod'];
+        fs.mkdirSync(path.join(cacheDir, 'node_modules'), { recursive: true });
+        for (const dep of coreDeps) {
+            const depSrc = path.join(pkgRoot, 'node_modules', dep);
+            if (fs.existsSync(depSrc)) {
+                fs.cpSync(depSrc, path.join(cacheDir, 'node_modules', dep), { recursive: true });
+            }
+        }
+    }
+    // installed_plugins.json 등록
+    const installedPath = path.join(pluginsDir, 'installed_plugins.json');
+    let installed = { version: 2, plugins: {} };
+    if (fs.existsSync(installedPath)) {
+        try {
+            installed = JSON.parse(fs.readFileSync(installedPath, 'utf-8'));
+        }
+        catch { /* ignore */ }
+    }
+    installed.plugins = installed.plugins ?? {};
+    installed.plugins[PLUGIN_KEY] = [{
+            scope: 'user',
+            installPath: cacheDir,
+            version,
+            installedAt: new Date().toISOString(),
+            lastUpdated: new Date().toISOString(),
+        }];
+    fs.mkdirSync(pluginsDir, { recursive: true });
+    fs.writeFileSync(installedPath, `${JSON.stringify(installed, null, 2)}\n`);
+    return true;
+}
+// ── 2. Slash commands ──────────────────────────────────────────────────
+function writeSlashCommands(opts) {
+    const { pkgRoot, targetDir, dryRun } = opts;
+    const sourceDir = path.join(pkgRoot, 'assets', 'claude', 'commands');
+    if (!fs.existsSync(sourceDir))
+        return 0;
+    if (dryRun) {
+        return fs.readdirSync(sourceDir).filter((f) => f.endsWith('.md')).length;
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    let count = 0;
+    for (const file of fs.readdirSync(sourceDir).filter((f) => f.endsWith('.md'))) {
+        const skillContent = fs.readFileSync(path.join(sourceDir, file), 'utf-8');
+        const descMatch = skillContent.match(/description:\s*(.+)/);
+        const desc = descMatch?.[1]?.trim() ?? file.replace(/\.md$/, '');
+        const skillName = file.replace(/\.md$/, '');
+        const out = `# ${desc}\n\n${FORGEN_MANAGED_MARKER}\n\nActivate Forgen "${skillName}" mode for the task: $ARGUMENTS\n\n${skillContent}`;
+        const target = path.join(targetDir, file);
+        if (fs.existsSync(target)) {
+            const existing = fs.readFileSync(target, 'utf-8');
+            if (!existing.includes(FORGEN_MANAGED_MARKER))
+                continue; // 사용자 작성 — skip
+        }
+        fs.writeFileSync(target, out);
+        count += 1;
+    }
+    return count;
+}
+// ── 3. Settings hooks injection ────────────────────────────────────────
+function injectHooksIntoSettings(opts) {
+    const { pkgRoot, settingsPath, dryRun } = opts;
+    // settings.json 컨텍스트는 ${CLAUDE_PLUGIN_ROOT} 미해석 — 절대 경로 박제 (postinstall.js 와 동일 노하우)
+    const generated = generateHooksJson({
+        pluginRoot: path.join(pkgRoot, 'dist'),
+        runtime: 'claude',
+        releaseMode: true,
+    });
+    let count = 0;
+    for (const events of Object.values(generated.hooks)) {
+        for (const group of events) {
+            const g = group;
+            if (Array.isArray(g.hooks))
+                count += g.hooks.length;
+        }
+    }
+    if (dryRun)
+        return count;
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        }
+        catch { /* fallthrough */ }
+    }
+    const hooksConfig = settings.hooks ?? {};
+    // 기존 forgen hook 제거 (path 에 pkgRoot 또는 CLAUDE_PLUGIN_ROOT 포함된 entry)
+    for (const [event, entries] of Object.entries(hooksConfig)) {
+        if (!Array.isArray(entries))
+            continue;
+        const filtered = entries.filter((entry) => {
+            const e = entry;
+            if (!Array.isArray(e.hooks))
+                return true;
+            // forgen-managed entry 식별: pkgRoot 또는 CLAUDE_PLUGIN_ROOT 또는 'forgen' 포함
+            return !e.hooks.some((h) => typeof h.command === 'string' &&
+                (h.command.includes(pkgRoot) || h.command.includes('CLAUDE_PLUGIN_ROOT') || h.command.includes('/forgen-local/forgen/')));
+        });
+        if (filtered.length === 0)
+            delete hooksConfig[event];
+        else
+            hooksConfig[event] = filtered;
+    }
+    // forgen 측 entry 추가
+    for (const [event, entries] of Object.entries(generated.hooks)) {
+        if (!hooksConfig[event])
+            hooksConfig[event] = [];
+        hooksConfig[event].push(...entries);
+    }
+    settings.hooks = hooksConfig;
+    // enabledPlugins 등록
+    const enabled = settings.enabledPlugins ?? {};
+    enabled[PLUGIN_KEY] = true;
+    settings.enabledPlugins = enabled;
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    return count;
+}
+function registerMcpInClaudeJson(opts) {
+    const { pkgRoot, claudeJsonPath, dryRun } = opts;
+    const serverPath = path.join(pkgRoot, 'dist', 'mcp', 'server.js');
+    const desired = { command: 'node', args: [serverPath] };
+    let claudeJson = {};
+    if (fs.existsSync(claudeJsonPath)) {
+        try {
+            claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf-8'));
+        }
+        catch { /* ignore */ }
+    }
+    const mcpServers = claudeJson.mcpServers ?? {};
+    const existing = mcpServers['forgen-compound'];
+    const alreadyPresent = existing !== undefined &&
+        existing.command === 'node' &&
+        Array.isArray(existing.args) &&
+        JSON.stringify(existing.args) === JSON.stringify(desired.args);
+    if (dryRun) {
+        return { registered: !alreadyPresent, alreadyPresent };
+    }
+    mcpServers['forgen-compound'] = desired;
+    claudeJson.mcpServers = mcpServers;
+    fs.mkdirSync(path.dirname(claudeJsonPath), { recursive: true });
+    fs.writeFileSync(claudeJsonPath, `${JSON.stringify(claudeJson, null, 2)}\n`);
+    return { registered: !alreadyPresent, alreadyPresent };
+}
+// ── public ─────────────────────────────────────────────────────────────
+export function planClaudeInstall(opts) {
+    if (!opts.pkgRoot || !fs.existsSync(opts.pkgRoot)) {
+        throw new Error(`planClaudeInstall: invalid pkgRoot ${opts.pkgRoot}`);
+    }
+    const homeDir = opts.homeDir ?? os.homedir();
+    const dryRun = opts.dryRun ?? false;
+    const registerMcp = opts.registerMcp ?? true;
+    const version = readPkgVersion(opts.pkgRoot);
+    const claudeDir = path.join(homeDir, '.claude');
+    const pluginsDir = path.join(claudeDir, 'plugins');
+    const cacheDir = path.join(pluginsDir, 'cache', 'forgen-local', 'forgen', version);
+    const slashCommandsDir = path.join(claudeDir, 'commands', 'forgen');
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const claudeJsonPath = path.join(homeDir, '.claude.json');
+    const pluginCacheWritten = writePluginCache({ pkgRoot: opts.pkgRoot, cacheDir, pluginsDir, version, dryRun });
+    const slashCommandsCount = writeSlashCommands({ pkgRoot: opts.pkgRoot, targetDir: slashCommandsDir, dryRun });
+    const hooksInjected = injectHooksIntoSettings({ pkgRoot: opts.pkgRoot, settingsPath, dryRun });
+    const mcp = registerMcp
+        ? registerMcpInClaudeJson({ pkgRoot: opts.pkgRoot, claudeJsonPath, dryRun })
+        : { registered: false, alreadyPresent: false };
+    return {
+        homeDir,
+        pluginCachePath: cacheDir,
+        pluginCacheWritten,
+        slashCommandsPath: slashCommandsDir,
+        slashCommandsCount,
+        settingsPath,
+        hooksInjected,
+        mcpRegistered: mcp.registered,
+        mcpAlreadyPresent: mcp.alreadyPresent,
+    };
+}

package/dist/host/install-codex.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Codex InstallPlan — Multi-Host Core Design §10 우선순위 3
+ *
+ * `~/.codex/hooks.json` 에 forgen hook 등록(절대경로, idempotent), `~/.codex/config.toml`
+ * 에 forgen-compound MCP 등록(managed marker block). $CODEX_HOME 환경변수 존중.
+ *
+ * 동작 원칙:
+ * - hook 등록은 generateHooksJson({runtime:'codex', pluginRoot, releaseMode}) 결과를 그대로 사용
+ *   — 이미 codex-adapter wrapper + 절대경로 적용됨 (spec §18.5 결정 옵션 1).
+ * - 사용자가 직접 작성한 비-forgen hook 은 보존 (`isForgenHookEntry` pattern).
+ * - MCP 등록은 TOML 라이브러리 없이 marker block 으로 idempotent 관리.
+ * - dryRun 시 파일을 쓰지 않고 결과만 반환 (테스트 + preview 용).
+ */
+export interface CodexInstallOptions {
+    /** forgen package root (build 산출물 dist/ 의 부모). 기본: 호출 시 process.cwd(). */
+    pkgRoot: string;
+    /** codex home (default: $CODEX_HOME ?? ~/.codex). */
+    codexHome?: string;
+    /** dry-run: 파일 미작성, 결과만 반환. */
+    dryRun?: boolean;
+    /** MCP 서버 등록 여부 (default true). */
+    registerMcp?: boolean;
+    /** hooks-generator releaseMode (default true: 환경 독립). */
+    releaseMode?: boolean;
+    /** AGENTS.md 위치 override (default: pkgRoot 기준 자동 resolve). 격리 테스트용. */
+    agentsMdPath?: string;
+}
+export interface CodexInstallResult {
+    codexHome: string;
+    hooksPath: string;
+    hooksWritten: boolean;
+    hooksCount: number;
+    preservedUserHookCount: number;
+    configTomlPath: string;
+    mcpRegistered: boolean;
+    mcpAlreadyPresent: boolean;
+    /** P3-3 (US-013): Codex skills/ 에 install 된 forgen 명령 수 */
+    skillsInstalled: number;
+    skillsPath: string;
+    /** P3-3: AGENTS.md (cwd) 에 forgen rule block 인젝션 여부 */
+    agentsMdPath: string;
+    agentsMdInjected: boolean;
+}
+export declare function planCodexInstall(opts: CodexInstallOptions): CodexInstallResult;

package/dist/host/install-codex.js

@@ -0,0 +1,276 @@
+/**
+ * Codex InstallPlan — Multi-Host Core Design §10 우선순위 3
+ *
+ * `~/.codex/hooks.json` 에 forgen hook 등록(절대경로, idempotent), `~/.codex/config.toml`
+ * 에 forgen-compound MCP 등록(managed marker block). $CODEX_HOME 환경변수 존중.
+ *
+ * 동작 원칙:
+ * - hook 등록은 generateHooksJson({runtime:'codex', pluginRoot, releaseMode}) 결과를 그대로 사용
+ *   — 이미 codex-adapter wrapper + 절대경로 적용됨 (spec §18.5 결정 옵션 1).
+ * - 사용자가 직접 작성한 비-forgen hook 은 보존 (`isForgenHookEntry` pattern).
+ * - MCP 등록은 TOML 라이브러리 없이 marker block 으로 idempotent 관리.
+ * - dryRun 시 파일을 쓰지 않고 결과만 반환 (테스트 + preview 용).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { generateHooksJson } from '../hooks/hooks-generator.js';
+const MCP_MARKER_BEGIN = '# >>> forgen-managed-mcp';
+const MCP_MARKER_END = '# <<< forgen-managed-mcp';
+const FORGEN_SKILL_MARKER = '<!-- forgen-managed -->';
+const AGENTS_MD_BEGIN = '<!-- >>> forgen-managed-rules -->';
+const AGENTS_MD_END = '<!-- <<< forgen-managed-rules -->';
+function resolveCodexHome(opts) {
+    return opts.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+}
+function isForgenManagedHook(entry, pkgRoot) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    if (!Array.isArray(e.hooks))
+        return false;
+    return e.hooks.some((h) => typeof h.command === 'string' && h.command.includes(pkgRoot));
+}
+function readJsonFile(p) {
+    try {
+        if (!fs.existsSync(p))
+            return null;
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function buildMcpBlock(pkgRoot) {
+    // forgen-mcp 는 dist/mcp/server.js. node 경로는 PATH 기반.
+    // `--host=codex` 인자는 server.ts 가 process.env.FORGEN_HOST 로 set 하여
+    // correction-record evidence 박제 시 host:"codex" 로 정확히 태깅되게 한다 (spec §10-5).
+    const serverPath = path.join(pkgRoot, 'dist', 'mcp', 'server.js');
+    return [
+        MCP_MARKER_BEGIN,
+        '[mcp_servers.forgen-compound]',
+        'command = "node"',
+        `args = [${JSON.stringify(serverPath)}, "--host=codex"]`,
+        MCP_MARKER_END,
+    ].join('\n');
+}
+function upsertMcpBlock(currentToml, pkgRoot) {
+    const block = buildMcpBlock(pkgRoot);
+    // marker block 이 있으면 그 사이를 새 block 으로 교체
+    const reMarker = new RegExp(`${MCP_MARKER_BEGIN}[\\s\\S]*?${MCP_MARKER_END}`, 'g');
+    if (reMarker.test(currentToml)) {
+        const replaced = currentToml.replace(reMarker, block);
+        return { content: replaced, alreadyPresent: replaced === currentToml };
+    }
+    // 없으면 끝에 append
+    const trimmed = currentToml.replace(/\s+$/, '');
+    const sep = trimmed.length > 0 ? '\n\n' : '';
+    return { content: `${trimmed}${sep}${block}\n`, alreadyPresent: false };
+}
+export function planCodexInstall(opts) {
+    const codexHome = resolveCodexHome(opts);
+    const hooksPath = path.join(codexHome, 'hooks.json');
+    const configTomlPath = path.join(codexHome, 'config.toml');
+    const releaseMode = opts.releaseMode ?? true;
+    // 1) forgen 측 hook (codex-adapter wrap + 절대경로) 생성
+    const generated = generateHooksJson({
+        pluginRoot: path.join(opts.pkgRoot, 'dist'),
+        runtime: 'codex',
+        releaseMode,
+    });
+    const generatedHooks = generated.hooks;
+    // 2) 기존 hooks.json 읽기 + forgen entry 제거 후 보존
+    const existing = readJsonFile(hooksPath);
+    const existingHooksByEvent = (existing?.hooks ?? {});
+    const preserved = {};
+    let preservedCount = 0;
+    for (const [event, entries] of Object.entries(existingHooksByEvent)) {
+        if (!Array.isArray(entries))
+            continue;
+        const userEntries = entries.filter((e) => !isForgenManagedHook(e, opts.pkgRoot));
+        if (userEntries.length > 0) {
+            preserved[event] = userEntries;
+            preservedCount += userEntries.length;
+        }
+    }
+    // 3) merge: user 보존 + forgen fresh.
+    //    `forgenCount` 는 실제 hook 명령 개수 (matcher group 내부 hooks[] 길이의 합) 로 집계한다.
+    const merged = { ...preserved };
+    let forgenCount = 0;
+    for (const [event, entries] of Object.entries(generatedHooks)) {
+        const list = merged[event] ?? [];
+        list.push(...entries);
+        merged[event] = list;
+        for (const group of entries) {
+            const g = group;
+            if (Array.isArray(g.hooks))
+                forgenCount += g.hooks.length;
+        }
+    }
+    const finalHooksFile = {
+        description: 'forgen Codex hooks (managed; user-authored entries preserved)',
+        hooks: merged,
+    };
+    // 4) MCP 등록
+    const registerMcp = opts.registerMcp ?? true;
+    let mcpAlreadyPresent = false;
+    let mcpRegistered = false;
+    let mcpContentToWrite = null;
+    if (registerMcp) {
+        const currentToml = fs.existsSync(configTomlPath)
+            ? fs.readFileSync(configTomlPath, 'utf-8')
+            : '';
+        const { content, alreadyPresent } = upsertMcpBlock(currentToml, opts.pkgRoot);
+        mcpAlreadyPresent = alreadyPresent;
+        mcpRegistered = !alreadyPresent;
+        mcpContentToWrite = content;
+    }
+    // 5) 실제 쓰기 (dryRun 이면 skip) — hooks.json + config.toml
+    if (!opts.dryRun) {
+        fs.mkdirSync(codexHome, { recursive: true });
+        fs.writeFileSync(hooksPath, `${JSON.stringify(finalHooksFile, null, 2)}\n`, 'utf-8');
+        if (mcpContentToWrite !== null) {
+            fs.writeFileSync(configTomlPath, mcpContentToWrite, 'utf-8');
+        }
+    }
+    // 6) P3-3 (US-013): Codex skills/ 에 forgen 10 commands install
+    //    Codex 의 skills 메커니즘 (codex-rs/core-skills) 구조: <skill-name>/SKILL.md
+    //    + frontmatter (name + description). forgen-managed marker 로 idempotent.
+    const skillsPath = path.join(codexHome, 'skills');
+    const sourceCommandsDir = path.join(opts.pkgRoot, 'assets', 'claude', 'commands');
+    const skillsResult = installCodexSkills({ sourceDir: sourceCommandsDir, targetDir: skillsPath, dryRun: opts.dryRun ?? false });
+    // 7) P3-3 (US-013): cwd/AGENTS.md 에 forgen rules block 인젝션 (managed marker)
+    //    Codex 가 AGENTS.md 를 자동 read (codex-rs/core/src/agents_md.rs 검증).
+    //    pkgRoot 의 git repo root 의 AGENTS.md, 또는 explicit override.
+    const agentsMdPath = opts.agentsMdPath ?? resolveAgentsMdPath(opts.pkgRoot);
+    const agentsResult = upsertForgenRulesInAgentsMd({ agentsMdPath, pkgRoot: opts.pkgRoot, dryRun: opts.dryRun ?? false });
+    return {
+        codexHome,
+        hooksPath,
+        hooksWritten: !opts.dryRun,
+        hooksCount: forgenCount,
+        preservedUserHookCount: preservedCount,
+        configTomlPath,
+        mcpRegistered,
+        mcpAlreadyPresent,
+        skillsInstalled: skillsResult.installed,
+        skillsPath,
+        agentsMdPath,
+        agentsMdInjected: agentsResult.injected,
+    };
+}
+// ── P3-3: Codex skills install ────────────────────────────────────────
+function installCodexSkills(opts) {
+    const { sourceDir, targetDir, dryRun } = opts;
+    if (!fs.existsSync(sourceDir))
+        return { installed: 0 };
+    const files = fs.readdirSync(sourceDir).filter((f) => f.endsWith('.md'));
+    if (dryRun)
+        return { installed: files.length };
+    fs.mkdirSync(targetDir, { recursive: true });
+    let count = 0;
+    for (const file of files) {
+        const skillName = file.replace(/\.md$/, '');
+        const skillDir = path.join(targetDir, skillName);
+        const skillFile = path.join(skillDir, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+            const existing = fs.readFileSync(skillFile, 'utf-8');
+            // Phase 3 critic fix: marker 가 *frontmatter 직후* 위치에 있는지 검증.
+            // 사용자가 forgen 문서를 인용해 본문 안에 marker 가 우연히 포함될 수 있어
+            // includes() 만으론 안전 X. 정규식으로 frontmatter 종결(`---\n`) 다음 빈 줄 다음
+            // 첫 non-blank 줄에 marker 가 있는지 확인.
+            const fmMarkerRe = /^---\n[\s\S]*?\n---\n\s*<!-- forgen-managed -->/;
+            if (!fmMarkerRe.test(existing))
+                continue; // 사용자 작성 또는 손상 — skip
+        }
+        const raw = fs.readFileSync(path.join(sourceDir, file), 'utf-8');
+        const descMatch = raw.match(/description:\s*(.+)/);
+        const desc = descMatch?.[1]?.trim() ?? skillName;
+        const bodyMatch = raw.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+        const body = bodyMatch?.[1]?.trim() ?? raw;
+        const out = `---\nname: ${skillName}\ndescription: ${desc}\n---\n\n${FORGEN_SKILL_MARKER}\n\n${body}\n`;
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.writeFileSync(skillFile, out);
+        count += 1;
+    }
+    return { installed: count };
+}
+// ── P3-3: AGENTS.md inject ────────────────────────────────────────────
+function resolveAgentsMdPath(pkgRoot) {
+    // Phase 3 critic fix: pkgRoot 기반 walk-up 은 `npm install -g` 시 시스템 디렉토리
+    // (예: /usr/local/lib/node_modules/forgen) 에 fallback AGENTS.md 작성 위험.
+    // *cwd 기반* 으로 변경 — 사용자 작업 디렉토리의 git root, 없으면 cwd 자체.
+    // (사용자가 forgen install codex 를 실행하는 위치가 install target 이라는 자연 가정.)
+    // pkgRoot 는 fallback 으로 유지 (cwd 가 git root 를 못 찾고 / 등 시스템 dir 일 때).
+    const cwd = process.cwd();
+    let dir = cwd;
+    for (let depth = 0; depth < 8; depth += 1) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return path.join(dir, 'AGENTS.md');
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // cwd 에서 .git 못 찾음 — cwd 직접 사용 (시스템 dir 가 아닌 한 안전).
+    // 시스템 dir (예: /, /usr) 인 경우 ~/AGENTS.md fallback (사용자 home 안전).
+    if (cwd === '/' || cwd.startsWith('/usr/') || cwd.startsWith('/opt/')) {
+        return path.join(os.homedir(), 'AGENTS.md');
+    }
+    return path.join(cwd, 'AGENTS.md');
+}
+function buildForgenRulesBlock(pkgRoot) {
+    // forgen 의 핵심 규칙 + 사용자 profile 안내 (가벼운 헤더만 — 실 rule 은 hook chain 이 inject)
+    const lines = [
+        AGENTS_MD_BEGIN,
+        '## forgen managed rules',
+        '',
+        '본 블록은 `forgen install codex` 가 자동 관리. 직접 편집 금지 — 다음 install 시 덮어쓰임.',
+        '',
+        '- forgen-compound MCP 가 ~/.codex/config.toml 에 등록됨. 학습된 솔루션을 `compound-search` 로 조회 가능.',
+        '- 사용자 교정은 `correction-record` MCP 도구로 즉시 박제 (kind: fix-now / prefer-from-now / avoid-this).',
+        '- forgen 의 4축 profile (quality_safety / autonomy / judgment_philosophy / communication_style) 이 응답 톤 + 검증 깊이를 가이드.',
+        '- 본 rule 은 cwd 의 AGENTS.md 가 자동 read 되는 Codex 의 user_instructions 경로로 흘러들어감.',
+        `- pkgRoot: ${pkgRoot}`,
+        AGENTS_MD_END,
+    ];
+    return lines.join('\n');
+}
+function upsertForgenRulesInAgentsMd(opts) {
+    const { agentsMdPath, pkgRoot, dryRun } = opts;
+    const block = buildForgenRulesBlock(pkgRoot);
+    let current = '';
+    if (fs.existsSync(agentsMdPath)) {
+        current = fs.readFileSync(agentsMdPath, 'utf-8');
+    }
+    // Phase 3 critic fix #1: RegExp lastIndex 위험 회피 — g flag 제거 + 매번 새 RegExp.
+    const reMarker = new RegExp(`${escapeRegex(AGENTS_MD_BEGIN)}[\\s\\S]*?${escapeRegex(AGENTS_MD_END)}`);
+    const hasBlock = reMarker.test(current);
+    // Phase 3 critic fix #2: AGENTS.md self-heal — begin marker 만 있고 end 손상 시
+    // 누적 방지. begin 부터 파일 끝까지 + AGENTS_MD_END 미존재 = 손상으로 판단,
+    // begin 부터 파일 끝까지를 *전부* 새 block 으로 교체.
+    let newContent;
+    if (hasBlock) {
+        newContent = current.replace(reMarker, block);
+    }
+    else {
+        const beginIdx = current.indexOf(AGENTS_MD_BEGIN);
+        const endIdx = current.indexOf(AGENTS_MD_END);
+        if (beginIdx !== -1 && endIdx === -1) {
+            // 손상: begin 만 있음 → begin 부터 끝까지 교체 (self-heal)
+            newContent = `${current.slice(0, beginIdx).replace(/\s+$/, '')}\n\n${block}\n`;
+        }
+        else {
+            // 깨끗한 신규 또는 둘 다 없음 → 끝에 append
+            newContent = `${current.replace(/\s+$/, '')}${current.length > 0 ? '\n\n' : ''}${block}\n`;
+        }
+    }
+    if (dryRun)
+        return { injected: newContent !== current };
+    fs.mkdirSync(path.dirname(agentsMdPath), { recursive: true });
+    fs.writeFileSync(agentsMdPath, newContent, 'utf-8');
+    return { injected: newContent !== current };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/host/install-orchestrator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Install orchestrator — feat/codex-support P1-3
+ *
+ * `forgen install` CLI 의 분기 처리:
+ *   - 인자 없음    → interactive 3-choice (claude/codex/both/quit)
+ *   - 'claude'    → planClaudeInstall()
+ *   - 'codex'     → planCodexInstall()
+ *   - 'both'      → 둘 다 실행
+ *
+ * 사용자 host 선택 권한이 forgen 측에 위임 (1원칙: Claude default 강요 금지).
+ * Phase 1 Round 2 의 *마이그레이션 정책 C* (기존 entry 보존) 와 함께 동작.
+ */
+import { detectAvailableHosts } from '../core/host-detect.js';
+import { type ClaudeInstallResult } from './install-claude.js';
+import { type CodexInstallResult } from './install-codex.js';
+export type InstallTarget = 'claude' | 'codex' | 'both';
+export interface OrchestratorOptions {
+    /** Sub-command 인자: 'claude'|'codex'|'both' 또는 undefined (interactive). */
+    target?: string;
+    pkgRoot: string;
+    dryRun?: boolean;
+    registerMcp?: boolean;
+}
+export interface OrchestratorResult {
+    target: InstallTarget;
+    claude?: ClaudeInstallResult;
+    codex?: CodexInstallResult;
+    detection: ReturnType<typeof detectAvailableHosts>;
+}
+export declare function runInstall(opts: OrchestratorOptions): Promise<OrchestratorResult | null>;
+/** CLI 출력 포맷터 — orchestrator 결과를 사용자에게 표시. */
+export declare function renderResult(result: OrchestratorResult, dryRun: boolean): string;
+/** pkgRoot resolve from binary location (dist/cli.js → pkgRoot). */
+export declare function resolvePkgRootFromBinary(metaUrl: string): string;