@moretea-labs/forge 1.5.0-rc.1

package/src/cli/installer/managed-entries.ts

@@ -0,0 +1,78 @@
+/**
+ * Host adapter "managed entry" helpers — shared between Codex and Claude
+ * targets because the entry shape is identical:
+ *
+ *   { matcher?: string, hooks: [{ type: 'command', command: string }] }
+ *
+ * The `MANAGED_TAG` substring inside each command string identifies entries
+ * the forge installer wrote, so install can be idempotent and uninstall
+ * can remove only its own entries (leaving sibling user hooks intact —
+ * verified for Claude in Phase 0: `~/.claude/settings.json` already had a
+ * non-forge `rtk hook claude` entry that must survive install).
+ *
+ * Command shape includes the `command -v forge || exit 0` shim
+ * (Codex consult constraint #5: CLI-missing fallback — adapter must not
+ * fail when CLI is uninstalled or not on PATH).
+ */
+
+import { ROUTES, type Route } from '../hook/route-registry';
+
+export const MANAGED_TAG = 'forge hook';
+
+export interface HookCommand {
+  type: 'command';
+  command: string;
+  timeout: number;
+}
+
+export interface HookEntry {
+  matcher?: string;
+  hooks: HookCommand[];
+}
+
+export type HooksByEvent = Record<string, HookEntry[]>;
+export type HookHost = 'claude' | 'codex';
+
+export function buildHookCommand(route: Route, host: HookHost): string {
+  return `if command -v forge-hook >/dev/null 2>&1; then HOOK_HOST=${host} forge-hook ${route.event} --route ${route.routeId} && exit 0; fi; command -v forge >/dev/null 2>&1 || exit 0; HOOK_HOST=${host} exec forge hook ${route.event} --route ${route.routeId}`;
+}
+
+export function buildHookEntry(route: Route, host: HookHost): HookEntry {
+  const entry: HookEntry = {
+    hooks: [{ type: 'command', command: buildHookCommand(route, host), timeout: 30 }],
+  };
+  if (route.matcher !== undefined) entry.matcher = route.matcher;
+  return entry;
+}
+
+export function isManagedEntry(entry: HookEntry): boolean {
+  if (!entry || !Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(MANAGED_TAG));
+}
+
+export function buildManagedHooks(host: HookHost): HooksByEvent {
+  const out: HooksByEvent = {};
+  for (const route of ROUTES) {
+    if (!out[route.event]) out[route.event] = [];
+    out[route.event].push(buildHookEntry(route, host));
+  }
+  return out;
+}
+
+export function stripManagedEntries(existing: HooksByEvent | undefined): HooksByEvent {
+  if (!existing) return {};
+  const out: HooksByEvent = {};
+  for (const [event, entries] of Object.entries(existing)) {
+    const kept = (entries ?? []).filter((e) => !isManagedEntry(e));
+    if (kept.length > 0) out[event] = kept;
+  }
+  return out;
+}
+
+export function mergeHooks(existing: HooksByEvent, managed: HooksByEvent): HooksByEvent {
+  const out: HooksByEvent = { ...existing };
+  for (const [event, managedEntries] of Object.entries(managed)) {
+    out[event] = [...(out[event] ?? []), ...managedEntries];
+  }
+  return out;
+}

package/src/cli/installer/shared.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared installer helpers: atomic JSON writes, idempotent unchanged detection.
+ *
+ * Atomic writes prevent partial-write corruption visible to the host process
+ * (Claude Code auto-reloads `~/.claude/settings.json` via ConfigChange and
+ * could race a non-atomic write — see docs/architecture/global-hook-runtime.md).
+ *
+ * Deep equality is used so re-installing with identical adapter content
+ * returns `action: 'unchanged'`. Critical because Codex hashes adapter
+ * entries by content + position; a byte-identical re-write avoids spurious
+ * trust prompts (verified Phase 0).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function atomicWriteFileSync(filePath: string, content: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, content, 'utf-8');
+  fs.renameSync(tmp, filePath);
+}
+
+export function readJsonOrEmpty<T = Record<string, unknown>>(filePath: string): T {
+  if (!fs.existsSync(filePath)) return {} as T;
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  if (raw.trim() === '') return {} as T;
+  return JSON.parse(raw) as T;
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  const oa = a as Record<string, unknown>;
+  const ob = b as Record<string, unknown>;
+  const ka = Object.keys(oa).sort();
+  const kb = Object.keys(ob).sort();
+  if (ka.length !== kb.length) return false;
+  for (let i = 0; i < ka.length; i++) {
+    if (ka[i] !== kb[i]) return false;
+    if (!deepEqual(oa[ka[i]], ob[kb[i]])) return false;
+  }
+  return true;
+}
+
+/**
+ * Format JSON with 2-space indent + trailing newline — matches the style
+ * `.codex/hooks.json` and `.claude/settings.json` use in this repo, so the
+ * deep-equal check against on-disk content lines up byte-for-byte after a
+ * round-trip read/serialize.
+ */
+export function formatJson(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}

package/src/cli/installer/targets/claude.ts

@@ -0,0 +1,136 @@
+/**
+ * Claude Code hook-runtime target.
+ *
+ * Writes 8 managed adapter entries under the `hooks` field of either
+ * ~/.claude/settings.json (--location global) or .claude/settings.json
+ * (--location local, project-scoped). Phase 0 verified Claude auto-reloads
+ * settings.json via ConfigChange seconds after a write, no restart needed.
+ *
+ * Both locations are supported because Claude documents user-level +
+ * project-level scopes with merging precedence
+ * (managed > local > project > user) — verified Phase 0.
+ *
+ * `settings.json` carries non-hook config too (themes, MCP, etc.), so the
+ * installer must merge into the existing object rather than overwrite.
+ * Tag-based managed entries leave sibling user-authored hook entries intact
+ * (Phase 0 baseline showed a sibling `rtk hook claude` entry that must survive).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import type {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from '../types';
+import {
+  atomicWriteFileSync,
+  deepEqual,
+  formatJson,
+  readJsonOrEmpty,
+} from '../shared';
+import {
+  buildManagedHooks,
+  isManagedEntry,
+  mergeHooks,
+  stripManagedEntries,
+  type HooksByEvent,
+} from '../managed-entries';
+
+interface SettingsFile {
+  hooks?: HooksByEvent;
+  [key: string]: unknown;
+}
+
+function userConfigPath(): string {
+  // Prefer $HOME env so tests can isolate via temp dirs; os.homedir() is
+  // cached and ignores runtime $HOME mutations in some Node/Bun versions.
+  return path.join(process.env.HOME ?? os.homedir(), '.claude', 'settings.json');
+}
+
+function projectConfigPath(cwd: string): string {
+  return path.join(cwd, '.claude', 'settings.json');
+}
+
+function resolvePath(loc: Location, cwd: string): string {
+  return loc === 'global' ? userConfigPath() : projectConfigPath(cwd);
+}
+
+class ClaudeTarget implements AgentTarget {
+  readonly id = 'claude' as const;
+  readonly displayName = 'Claude Code';
+  readonly docsUrl = 'https://code.claude.com';
+
+  supportsLocation(_loc: Location): boolean {
+    return true;
+  }
+
+  detect(loc: Location): DetectionResult {
+    const filePath = resolvePath(loc, process.cwd());
+    const installed = fs.existsSync(path.dirname(filePath));
+    let alreadyConfigured = false;
+    if (fs.existsSync(filePath)) {
+      try {
+        const data = readJsonOrEmpty<SettingsFile>(filePath);
+        for (const entries of Object.values(data.hooks ?? {})) {
+          if ((entries ?? []).some(isManagedEntry)) {
+            alreadyConfigured = true;
+            break;
+          }
+        }
+      } catch {
+        // Invalid JSON: leave alreadyConfigured false.
+      }
+    }
+    return { installed, alreadyConfigured, configPath: filePath };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    const filePath = resolvePath(loc, process.cwd());
+    const data = readJsonOrEmpty<SettingsFile>(filePath);
+    const cleaned = stripManagedEntries(data.hooks);
+    const managed = buildManagedHooks('claude');
+    const merged = mergeHooks(cleaned, managed);
+    const next: SettingsFile = { ...data, hooks: merged };
+    const nextContent = formatJson(next);
+
+    const created = !fs.existsSync(filePath);
+    if (!created) {
+      const current = fs.readFileSync(filePath, 'utf-8');
+      if (current === nextContent) {
+        return { files: [{ path: filePath, action: 'unchanged' }] };
+      }
+    }
+    atomicWriteFileSync(filePath, nextContent);
+    return {
+      files: [{ path: filePath, action: created ? 'created' : 'updated' }],
+      notes: created
+        ? ['Claude Code will pick up hooks on next ConfigChange event; no restart needed.']
+        : ['Claude Code auto-reloads settings.json on write (verified Phase 0).'],
+    };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    const filePath = resolvePath(loc, process.cwd());
+    if (!fs.existsSync(filePath)) {
+      return { files: [{ path: filePath, action: 'not-found' }] };
+    }
+    const data = readJsonOrEmpty<SettingsFile>(filePath);
+    const cleaned = stripManagedEntries(data.hooks);
+    if (deepEqual(cleaned, data.hooks ?? {})) {
+      return { files: [{ path: filePath, action: 'not-found' }] };
+    }
+    const next: SettingsFile = { ...data, hooks: cleaned };
+    atomicWriteFileSync(filePath, formatJson(next));
+    return { files: [{ path: filePath, action: 'removed' }] };
+  }
+
+  describePaths(loc: Location): string[] {
+    return [resolvePath(loc, process.cwd())];
+  }
+}
+
+export const claudeTarget: AgentTarget = new ClaudeTarget();

package/src/cli/installer/targets/codex.ts

@@ -0,0 +1,174 @@
+/**
+ * Codex CLI hook-runtime target.
+ *
+ * Writes 8 managed adapter entries to ~/.codex/hooks.json (Phase 0 verified
+ * Codex 0.130.0+ supports user-level hooks at this path; trust prompt fires
+ * once per new (command, key) tuple, byte-identical re-runs hash-skip).
+ *
+ * supportsLocation('local') returns false — Codex has no project-local hook
+ * config concept (verified Phase 0 2026-05-28). The installer skips Codex
+ * cleanly when the user picks --location local.
+ *
+ * Tag-based managed entries (`MANAGED_TAG` from managed-entries.ts) ensure
+ * uninstall removes only what install wrote, preserving any sibling
+ * user-authored hook entries on the same file.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import type {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from '../types';
+import {
+  atomicWriteFileSync,
+  deepEqual,
+  formatJson,
+  readJsonOrEmpty,
+} from '../shared';
+import {
+  buildManagedHooks,
+  isManagedEntry,
+  mergeHooks,
+  stripManagedEntries,
+  type HooksByEvent,
+} from '../managed-entries';
+
+interface HooksFile {
+  hooks?: HooksByEvent;
+  [key: string]: unknown;
+}
+
+function globalConfigPath(): string {
+  // Prefer $HOME env so tests can isolate via temp dirs; os.homedir() is
+  // cached and ignores runtime $HOME mutations in some Node/Bun versions.
+  return path.join(process.env.HOME ?? os.homedir(), '.codex', 'hooks.json');
+}
+
+function globalTomlConfigPath(): string {
+  return path.join(process.env.HOME ?? os.homedir(), '.codex', 'config.toml');
+}
+
+function ensureRequestUserInputToml(): WriteResult['files'][number] {
+  const filePath = globalTomlConfigPath();
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const desiredLine = 'default_mode_request_user_input = true';
+  if (!fs.existsSync(filePath)) {
+    atomicWriteFileSync(filePath, `${desiredLine}\n`);
+    return { path: filePath, action: 'created' };
+  }
+
+  const current = fs.readFileSync(filePath, 'utf-8');
+  if (/^default_mode_request_user_input\s*=\s*true\s*$/m.test(current)) {
+    return { path: filePath, action: 'unchanged' };
+  }
+
+  let next: string;
+  if (/^default_mode_request_user_input\s*=/m.test(current)) {
+    next = current.replace(/^default_mode_request_user_input\s*=.*$/m, desiredLine);
+  } else if (/^\[/m.test(current)) {
+    next = current.replace(/^\[/m, `${desiredLine}\n\n[`);
+  } else {
+    next = `${current.replace(/\s*$/, '')}\n${desiredLine}\n`;
+  }
+
+  if (next === current) {
+    return { path: filePath, action: 'unchanged' };
+  }
+  atomicWriteFileSync(filePath, next);
+  return { path: filePath, action: 'updated' };
+}
+
+class CodexTarget implements AgentTarget {
+  readonly id = 'codex' as const;
+  readonly displayName = 'Codex CLI';
+  readonly docsUrl = 'https://github.com/openai/codex';
+
+  supportsLocation(loc: Location): boolean {
+    return loc === 'global';
+  }
+
+  detect(loc: Location): DetectionResult {
+    if (loc !== 'global') {
+      return { installed: false, alreadyConfigured: false };
+    }
+    const filePath = globalConfigPath();
+    const installed = fs.existsSync(path.dirname(filePath));
+    let alreadyConfigured = false;
+    if (fs.existsSync(filePath)) {
+      try {
+        const data = readJsonOrEmpty<HooksFile>(filePath);
+        for (const entries of Object.values(data.hooks ?? {})) {
+          if ((entries ?? []).some(isManagedEntry)) {
+            alreadyConfigured = true;
+            break;
+          }
+        }
+      } catch {
+        // Invalid JSON: surface configPath but report not-configured.
+      }
+    }
+    return { installed, alreadyConfigured, configPath: filePath };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    if (loc !== 'global') {
+      throw new Error(
+        'codexTarget.install: Codex has no project-local hook config; use --location global',
+      );
+    }
+    const filePath = globalConfigPath();
+    const data = readJsonOrEmpty<HooksFile>(filePath);
+    const cleaned = stripManagedEntries(data.hooks);
+    const managed = buildManagedHooks('codex');
+    const merged = mergeHooks(cleaned, managed);
+    const next: HooksFile = { ...data, hooks: merged };
+    const nextContent = formatJson(next);
+    const tomlResult = ensureRequestUserInputToml();
+
+    const created = !fs.existsSync(filePath);
+    if (!created) {
+      const current = fs.readFileSync(filePath, 'utf-8');
+      if (current === nextContent) {
+        return { files: [{ path: filePath, action: 'unchanged' }, tomlResult] };
+      }
+    }
+    atomicWriteFileSync(filePath, nextContent);
+    return {
+      files: [{ path: filePath, action: created ? 'created' : 'updated' }, tomlResult],
+      notes: created
+        ? ['Restart Codex to register new hook trust hashes.']
+        : ['Existing hash entries stay trusted; only new (command, key) tuples re-prompt.'],
+    };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    if (loc !== 'global') return { files: [] };
+    const filePath = globalConfigPath();
+    if (!fs.existsSync(filePath)) {
+      return { files: [{ path: filePath, action: 'not-found' }] };
+    }
+    const data = readJsonOrEmpty<HooksFile>(filePath);
+    const cleaned = stripManagedEntries(data.hooks);
+    if (deepEqual(cleaned, data.hooks ?? {})) {
+      return { files: [{ path: filePath, action: 'not-found' }] };
+    }
+    const next: HooksFile = { ...data, hooks: cleaned };
+    atomicWriteFileSync(filePath, formatJson(next));
+    return {
+      files: [{ path: filePath, action: 'removed' }],
+      notes: ['~/.codex/config.toml [hooks.state] entries are not GC-ed by Codex; remove manually if desired.'],
+    };
+  }
+
+  describePaths(loc: Location): string[] {
+    return loc === 'global' ? [globalConfigPath(), globalTomlConfigPath()] : [];
+  }
+}
+
+export const codexTarget: AgentTarget = new CodexTarget();

package/src/cli/installer/targets/registry.ts

@@ -0,0 +1,28 @@
+/**
+ * Registry of all known forge install targets.
+ *
+ * Adding a new target = create targets/<id>.ts exporting an AgentTarget,
+ * then add it to ALL_TARGETS below. Order here is the order targets
+ * appear in `--target=all` and help listings — keep it stable.
+ *
+ * Modeled after _ref/codegraph/src/installer/targets/registry.ts:20-29.
+ * Phase 1A intentionally omits resolveTargetFlag / detectAll helpers —
+ * those land with the install command in Phase 1B.
+ */
+
+import type { AgentTarget, TargetId } from '../types';
+import { codexTarget } from './codex';
+import { claudeTarget } from './claude';
+
+export const ALL_TARGETS: readonly AgentTarget[] = Object.freeze([
+  codexTarget,
+  claudeTarget,
+]);
+
+export function getTarget(id: string): AgentTarget | undefined {
+  return ALL_TARGETS.find((t) => t.id === id);
+}
+
+export function listTargetIds(): TargetId[] {
+  return ALL_TARGETS.map((t) => t.id);
+}

package/src/cli/installer/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Target abstraction for the forge hook-runtime installer.
+ *
+ * Each host (Codex CLI, Claude Code) implements AgentTarget so the
+ * installer orchestrator can write the right hook config without
+ * baking host-specific paths into core code. Adding a new host =
+ * one new file in targets/ + one entry in registry.ts.
+ *
+ * Modeled after _ref/codegraph/src/installer/targets/types.ts:15,51-62
+ * but scoped to hook-runtime installation (Codex hooks.json + Claude
+ * settings.json), not MCP server registration.
+ */
+
+export type Location = 'global' | 'local';
+
+/**
+ * Stable id for the --target CLI flag and registry lookup.
+ * Phase 1 supports codex + claude only; more hosts can be added in
+ * Phase 2+ by appending to this union and registry.ts.
+ */
+export type TargetId = 'codex' | 'claude';
+
+export interface DetectionResult {
+  installed: boolean;
+  alreadyConfigured: boolean;
+  /** Path inspected; surfaced in diagnostic / dry-run output. */
+  configPath?: string;
+}
+
+/**
+ * What target.install(location) actually changed on disk. The
+ * orchestrator renders one log line per file using `action`.
+ *
+ * `unchanged` means the file content already matched what we'd write
+ * — used for byte-identical idempotent re-runs.
+ */
+export interface WriteResult {
+  files: Array<{
+    path: string;
+    action: 'created' | 'updated' | 'unchanged' | 'removed' | 'not-found' | 'kept';
+  }>;
+  /**
+   * Optional short one-liner notes the orchestrator surfaces verbatim
+   * — e.g. "Restart Codex to register the hook trust hash." Keep these
+   * short; long-form goes in README / Phase 1E docs.
+   */
+  notes?: string[];
+}
+
+/**
+ * Reserved for Phase 1B/1C install/migrate flags (dry-run, force, etc.).
+ * Phase 1A keeps the parameter shape but ships no flags so call sites
+ * don't have to change later.
+ */
+export interface InstallOptions {}
+
+export interface AgentTarget {
+  readonly id: TargetId;
+  readonly displayName: string;
+  readonly docsUrl?: string;
+  /**
+   * Whether this target supports the given install location. Codex
+   * returns false for 'local' (no project-local hook concept verified
+   * Phase 0 2026-05-28); Claude returns true for both.
+   */
+  supportsLocation(loc: Location): boolean;
+  detect(loc: Location): DetectionResult;
+  install(loc: Location, opts: InstallOptions): WriteResult;
+  uninstall(loc: Location): WriteResult;
+  /** Filesystem paths this target would write to at this location. */
+  describePaths(loc: Location): string[];
+}