@webpieces/ai-hook-rules 0.4.710 → 0.4.712

package/src/bin/setup.d.ts

@@ -1,10 +1,18 @@
-import { ClaudeSettings } from './hook-registration';
+import { ClaudeSettings, HarnessRegistration } from './hook-registration';
 declare class HookSpec {
     readonly key: string;
     readonly label: string;
-    readonly matcher: string;
     readonly bin: string;
-    constructor(key: string, label: string, matcher: string, bin: string);
+    constructor(key: string, label: string, bin: string);
+    /**
+     * WHICH TOOL NAMES this hook must see, in the harness the target belongs to.
+     *
+     * It is a lookup on the target rather than a field on the spec because the answer is not a property
+     * of the hook: the rules hook matches `Write|Edit|MultiEdit` under Claude Code and `apply_patch`
+     * under Codex, and a single stored matcher is exactly how `.codex/hooks.json` came to be registered
+     * against tool names Codex never emits.
+     */
+    matcherFor(target: InstallTarget): string;
     commandFor(target: InstallTarget, projectRoot: string): string;
 }
 export declare class InstallTarget {
@@ -12,31 +20,58 @@ export declare class InstallTarget {
     readonly label: string;
     readonly settingsPath: string;
     readonly absolute: boolean;
-    constructor(choice: string, label: string, settingsPath: string, absolute: boolean);
+    /**
+     * WHICH HARNESS this file arms — it decides the matcher and the shim anchor written into it.
+     *
+     * REQUIRED, with no default, and the absence of one is the point. A default of
+     * CLAUDE_REGISTRATION would make "omit the harness" mean "Claude Code" — a widening that is an
+     * ABSENCE rather than a token, so a target built for Codex without it would silently carry
+     * `Write|Edit|MultiEdit` and `$CLAUDE_PROJECT_DIR`, which is EXACTLY the silently-unguarded
+     * state this class exists to end, and ungreppable besides.
+     */
+    readonly harness: HarnessRegistration;
+    constructor(choice: string, label: string, settingsPath: string, absolute: boolean, 
+    /**
+     * WHICH HARNESS this file arms — it decides the matcher and the shim anchor written into it.
+     *
+     * REQUIRED, with no default, and the absence of one is the point. A default of
+     * CLAUDE_REGISTRATION would make "omit the harness" mean "Claude Code" — a widening that is an
+     * ABSENCE rather than a token, so a target built for Codex without it would silently carry
+     * `Write|Edit|MultiEdit` and `$CLAUDE_PROJECT_DIR`, which is EXACTLY the silently-unguarded
+     * state this class exists to end, and ungreppable besides.
+     */
+    harness: HarnessRegistration);
 }
 export declare const RULES_HOOK: HookSpec;
 export declare const GUARDS_HOOK: HookSpec;
+/**
+ * Every file the installer can write, keyed by the CHOICE a human makes.
+ *
+ * TWO TARGETS SHARE CHOICE `1`, and that is the design rather than an oversight: "the project, committed,
+ * for the team" is ONE intention, and a repo that is worked on by both harnesses needs both files armed
+ * to mean it. Splitting it into two questions would let a human answer them differently and end up with a
+ * repo where Codex is silently unguarded — which is the state this whole change exists to end. Every
+ * caller selects by choice id (`targets.filter(t => t.choice === answer)`), never by index, so adding a
+ * harness adds a row and changes no numbering.
+ *
+ * `2` (personal) and `3` (global) stay Claude-only because neither has a Codex counterpart: Codex reads
+ * one repo-local `hooks.json` and has no personal or home-scoped hook file.
+ *
+ * `homeDir` is injectable so tests can point the global target at a temp dir instead of the real
+ * ~/.claude/settings.json (a unit test must never write the user's actual global settings).
+ */
 export declare function installTargets(projectRoot: string, homeDir?: string): InstallTarget[];
-type Json = Record<string, unknown>;
-type RuleEntry = Json;
-type Section = Record<string, RuleEntry>;
-interface ConfigFile {
-    extends?: string;
-    rules: Section;
-    hookGuards: Section;
-    commands: Json;
-    excludePaths: string[];
-    'match-rules': Json[];
-    rulesDir: string[];
-}
-interface MigrateResult {
-    config: ConfigFile;
-    changes: string[];
-}
-export declare function migrate(existing: Json): MigrateResult;
 export declare function hasHook(settings: ClaudeSettings, bin: string): boolean;
 export declare function applyHook(hook: HookSpec, chosen: InstallTarget | null, targets: InstallTarget[], projectRoot: string): void;
 export declare function resolveTargetChoice(name: string): string | null;
 export declare function parseTargetArg(args: string[]): string | null;
+/**
+ * Apply ONE choice for one hook: every target that answer selects, or uninstall when it selects none.
+ *
+ * The loop is what lets one choice arm several harnesses (choice `1` writes both the Claude settings
+ * file and the Codex hooks file — see installTargets). `applyHook` scopes its removals to the chosen
+ * target's harness, which is what keeps these calls from undoing one another.
+ */
+export declare function applyChoice(hook: HookSpec, choice: string, targets: InstallTarget[], projectRoot: string): void;
 export declare function main(): Promise<void>;
 export {};