@wooojin/forgen 0.5.0 → 0.5.6

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

@@ -24,7 +24,23 @@ export interface CodexInstallOptions {
     releaseMode?: boolean;
     /** AGENTS.md 위치 override (default: pkgRoot 기준 자동 resolve). 격리 테스트용. */
     agentsMdPath?: string;
+    /** ADR-016 D1: config.toml 에 forgen notify 폴백 등록 여부 (default true). */
+    registerNotify?: boolean;
 }
+/** ADR-016 D1 — config.toml `notify` 등록 결과. */
+export type CodexNotifyStatus = 
+/** forgen 블록을 새로 썼거나 갱신함 */
+'installed'
+/** 이미 동일한 forgen 블록이 있음 */
+ | 'already-present'
+/** 사용자가 직접 정의한 `notify` 가 있어 건드리지 않음 (단일 argv 라 병합 불가) */
+ | 'user-defined'
+/** forgen 블록의 notify 줄이 손으로 고쳐져(여러 줄 배열 등) 안전하게 다시 쓸 수 없어 그대로 둠 */
+ | 'custom-block'
+/** --no-notify: 블록이 없었음 */
+ | 'skipped'
+/** --no-notify: 기존 forgen 블록을 제거함 */
+ | 'removed';
 export interface CodexInstallResult {
     codexHome: string;
     hooksPath: string;
@@ -44,8 +60,111 @@ export interface CodexInstallResult {
     devGuideSkillsPath: string;
     devGuideSkillsInstalled: number;
     devGuideSkillsRemoved: number;
+    /** ADR-014 D2: ~/.codex/agents/ch-*.toml 커스텀 에이전트 설치 결과 */
+    agentsPath: string;
+    agentsInstalled: number;
+    agentsRemoved: number;
+    /** ADR-014 D4: hooks.json forgen 엔트리 중 config.toml hooks.state 에 신뢰 기록이 있는 수 */
+    hookTrust: CodexHookTrustAudit;
+    /** ADR-014 D2: config.toml `[features] multi_agent = true` 여부 (false 면 ch-* 에이전트 spawn 불가 → 안내) */
+    multiAgentEnabled: boolean;
+    /** ADR-016 D1: config.toml `notify` 폴백 등록 결과 */
+    notify: CodexNotifyStatus;
+}
+export interface CodexHookTrustAudit {
+    /** hooks.json 의 forgen hook 명령 수 (Codex 가 지원하는 이벤트만) */
+    total: number;
+    /** Codex 가 모르는 이벤트라 조용히 무시되는 forgen 엔트리 (`<event>:<i>:<j>`) — trust 대상이 아님 */
+    ignoredByCodex: string[];
+    /** trusted_hash 가 현재 핸들러의 해시와 일치하고 꺼져 있지 않은 수 (Codex 가 실제로 실행하는 훅) */
+    trusted: number;
+    /** 신뢰 기록이 없는 hook 키 (`<event>:<i>:<j>`) */
+    untrusted: string[];
+    /**
+     * ADR-016 D2: 신뢰 기록은 있으나 핸들러가 바뀌어 해시가 어긋난 hook 키. Codex 는 `/hooks` 재승인
+     * 전까지 이 훅도 skip 한다 (이전엔 키 존재만 봐서 "trusted" 로 오표시).
+     */
+    modified: string[];
+    /** 승인돼 있고 해시도 맞지만 사용자가 `/hooks` 에서 끈 훅 (`enabled = false`) — Codex 가 실행하지 않는다 */
+    disabled: string[];
+    /** config.toml 자체가 없거나 hooks.state 가 전혀 없으면 true (Codex 가 아직 한 번도 훅을 review 안 함) */
+    noStateRecorded: boolean;
+}
+/**
+ * config.toml 에 forgen notify 블록을 upsert.
+ *
+ * - Codex 의 `notify` 는 top-level 단일 argv 다. 사용자가 이미 정의했으면 **건드리지 않는다** — 그리고
+ *   forgen 블록이 남아 있으면 제거한다 (중복 키 = config.toml 파싱 실패 → Codex 기동 불가).
+ * - top-level 키는 첫 테이블 헤더 앞에 와야 하므로 블록은 항상 파일 최상단(BOM 뒤)에 둔다.
+ * - 사용자가 forgen 블록의 argv 뒤에 `"--", "<prog>", …` 로 자기 notifier 를 체인해 뒀으면 그 꼬리를 보존.
+ *   블록의 notify 줄을 한 줄 JSON 으로 읽을 수 없으면(여러 줄 배열 등 손편집) 아무것도 바꾸지 않는다.
+ * - 블록 사이에 Codex 가 끼워 넣은 줄(root 키)은 블록 바로 뒤로 옮겨 보존한다.
+ */
+export declare function upsertNotifyBlock(currentToml: string, pkgRoot: string): {
+    content: string;
+    status: CodexNotifyStatus;
+};
+/** forgen notify 블록 제거 (`--no-notify`, uninstall). 블록 사이에 끼어든 다른 줄은 보존. */
+export declare function removeNotifyBlock(currentToml: string): {
+    content: string;
+    removed: boolean;
+};
+interface HooksFile {
+    description?: string;
+    hooks: Record<string, Array<unknown>>;
 }
 export declare function planCodexInstall(opts: CodexInstallOptions): CodexInstallResult;
+/** `[features]` 섹션 안에 `multi_agent = true` 가 있는지 (TOML 라이브러리 없이 섹션 범위만 본다). */
+export declare function isCodexMultiAgentEnabled(configToml: string): boolean;
+/**
+ * Codex 0.153 hooks 공식 이벤트 12종 (learn.chatgpt.com/docs/hooks + binary 문자열). 이 밖의 이벤트
+ * (예: Claude 전용 PostToolUseFailure) 는 Codex 가 조용히 무시하므로 trust 대상이 아니다.
+ */
+export declare const CODEX_SUPPORTED_HOOK_EVENTS: ReadonlySet<string>;
+/** Codex 는 hooks.state 키에 이벤트명을 snake_case 로 쓴다 (PreToolUse → pre_tool_use). */
+export declare function codexHookEventKey(event: string): string;
+/**
+ * ADR-016 D2 — Codex 0.153.4 의 hook trust 해시 재현 (`hook_hash`, discovery.rs).
+ *
+ * 해시는 *핸들러 단위*: `{event_name, matcher?, hooks:[정규화된 핸들러 1개]}` 의 canonical JSON sha256.
+ * 정규화: timeout 은 기본값/clamp 적용 후 항상 포함, async 항상 포함, statusMessage 는 있을 때만,
+ * additionalContextLimit 은 허용 이벤트에서 기본값(2500)이 아닐 때만. 파일 경로·인덱스·미지 필드는 불포함.
+ * `type:"command"` 가 아니면 null (forgen 은 command 훅만 쓴다).
+ */
+export declare function codexHookTrustHash(event: string, matcher: unknown, handler: {
+    type?: unknown;
+    command?: unknown;
+    timeout?: unknown;
+    async?: unknown;
+    statusMessage?: unknown;
+    additionalContextLimit?: unknown;
+}): string | null;
+/**
+ * hooks.json 의 forgen 엔트리 각각을 config.toml 의
+ * `[hooks.state."<hooksPath>:<event>:<groupIdx>:<hookIdx>"] trusted_hash` 와 대조한다 (ADR-014 D4).
+ *
+ * ADR-016 D2: 이전엔 *기록 유무* 만 봤다 — 그래서 핸들러가 바뀌어 Codex 가 `modified` 로 skip 하는 훅을
+ * "trusted" 로 오표시했다. 이제 Codex 와 같은 해시를 계산해 trusted / modified / untrusted 를 구분한다.
+ * 읽기 전용 대조이며 trusted_hash 를 쓰지 않는다 — Codex 의 review 정책을 우회하지 않는다.
+ */
+export declare function auditCodexHookTrust(opts: {
+    hooksPath: string;
+    configTomlPath: string;
+    pkgRoot: string;
+    hooksFile?: HooksFile | null;
+    configToml?: string;
+}): CodexHookTrustAudit;
+/**
+ * Claude agent .md → Codex agent role TOML.
+ * 공식 스키마(필수 name/description/developer_instructions, 선택 model_reasoning_effort/sandbox_mode)
+ * 외 필드는 쓰지 않는다 — Codex 가 unknown field 를 거부 (ADR-014 D2).
+ */
+export declare function renderCodexAgentToml(file: string, raw: string): {
+    name: string;
+    toml: string;
+} | null;
+/** ADR-014 D3 — Codex 스킬에는 `$ARGUMENTS` 치환 변수가 없다. */
+export declare function adaptSkillBodyForCodex(body: string): string;
 export declare function resolveAgentsMdPath(_pkgRoot: string): string;
 export declare function upsertForgenRulesInAgentsMd(opts: {
     agentsMdPath: string;
@@ -54,3 +173,4 @@ export declare function upsertForgenRulesInAgentsMd(opts: {
 }): {
     injected: boolean;
 };
+export {};