@moreih29/nexus-core 0.13.0 → 0.14.0

package/scripts/build-hooks.ts

@@ -1,584 +0,0 @@
-/**
- * scripts/build-hooks.ts
- *
- * Build pipeline for the nexus hook system.
- *
- * Five stages:
- *   1. Load assets/hooks/*\/meta.yml + HookMetaSchema zod validation (strict)
- *   2. Load capability-matrix.yml + validate capability IDs referenced by hooks
- *   3. Warn on event ↔ capability mismatch
- *   4. Compute harness portability with fallback policy enforcement
- *   5. Emit dist/hooks/*.js (tsc), dist/manifests/*.json, portability-report.json
- *
- * 결정 참조: plan.json Issue #5 (빌드 검증 5단계)
- */
-
-import { HookMetaSchema } from "../src/hooks/types.js";
-import type { HookMeta } from "../src/hooks/types.js";
-import {
-  readFileSync,
-  readdirSync,
-  existsSync,
-  mkdirSync,
-  writeFileSync,
-} from "node:fs";
-import { join, resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { execSync } from "node:child_process";
-import { parse as parseYaml } from "yaml";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = resolve(__dirname, "..");
-const HOOKS_DIR = join(ROOT, "assets/hooks");
-const CAPABILITY_MATRIX_PATH = join(HOOKS_DIR, "capability-matrix.yml");
-const TOOL_NAME_MAP_PATH = join(ROOT, "assets/tools/tool-name-map.yml");
-const DIST_HOOKS_DIR = join(ROOT, "dist/hooks");
-const DIST_MANIFESTS_DIR = join(ROOT, "dist/manifests");
-
-const HARNESSES = ["claude", "codex", "opencode"] as const;
-type Harness = (typeof HARNESSES)[number];
-type CapabilityValue = boolean | "partial";
-
-// ---------------------------------------------------------------------------
-// Data shapes
-// ---------------------------------------------------------------------------
-
-interface HookEntry {
-  name: string;
-  meta: HookMeta;
-  handlerPath: string;
-}
-
-interface CapabilityMatrix {
-  capabilities: Record<
-    string,
-    { claude: CapabilityValue; codex: CapabilityValue; opencode: CapabilityValue; note?: string }
-  >;
-}
-
-interface ExclusionRecord {
-  harness: Harness;
-  missing: string[];
-  reason: string;
-}
-
-interface PortabilityPlan {
-  name: string;
-  meta: HookMeta;
-  tier: "core" | "extended" | "experimental" | "harness-specific";
-  registeredIn: Harness[];
-  excludedFrom: ExclusionRecord[];
-  capabilitiesRequired: string[];
-}
-
-interface ToolNameMap {
-  tools: Record<
-    string,
-    {
-      claude: string | string[] | null;
-      codex: string | string[] | null | { primary: string; aliases: string[] };
-      opencode: string | string[] | null;
-    }
-  >;
-}
-
-// ---------------------------------------------------------------------------
-// Stage 1: Load + validate meta.yml files
-// ---------------------------------------------------------------------------
-
-function loadAllHooks(): HookEntry[] {
-  const entries = readdirSync(HOOKS_DIR, { withFileTypes: true });
-  const result: HookEntry[] = [];
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-
-    const metaPath = join(HOOKS_DIR, entry.name, "meta.yml");
-    const handlerPath = join(HOOKS_DIR, entry.name, "handler.ts");
-
-    if (!existsSync(metaPath) || !existsSync(handlerPath)) continue;
-
-    const metaRaw = parseYaml(readFileSync(metaPath, "utf-8"));
-
-    // HookMetaSchema is .strict() — portability_tier and other unknown fields
-    // will throw a ZodError here (Acceptance Criteria #5)
-    let meta: HookMeta;
-    try {
-      meta = HookMetaSchema.parse(metaRaw);
-    } catch (err) {
-      throw new Error(
-        `[build-hooks] meta.yml validation failed for "${entry.name}": ${String(err)}`,
-      );
-    }
-
-    result.push({ name: entry.name, meta, handlerPath });
-  }
-
-  // Sort by priority descending
-  result.sort((a, b) => b.meta.priority - a.meta.priority);
-
-  return result;
-}
-
-// ---------------------------------------------------------------------------
-// Stage 2: Load capability matrix + validate capability IDs
-// ---------------------------------------------------------------------------
-
-function loadCapabilityMatrix(): CapabilityMatrix {
-  const raw = readFileSync(CAPABILITY_MATRIX_PATH, "utf-8");
-  return parseYaml(raw) as CapabilityMatrix;
-}
-
-function validateCapabilityIds(hooks: HookEntry[], matrix: CapabilityMatrix): void {
-  const knownIds = new Set(Object.keys(matrix.capabilities));
-
-  for (const hook of hooks) {
-    for (const capId of hook.meta.requires_capabilities) {
-      if (!knownIds.has(capId)) {
-        // Acceptance Criteria #6: unknown capability ID → build failure
-        throw new Error(
-          `[build-hooks] "${hook.name}" requires unknown capability "${capId}". ` +
-            `Known IDs: ${[...knownIds].join(", ")}`,
-        );
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Stage 3: Event ↔ capability mismatch warnings
-// ---------------------------------------------------------------------------
-
-type HookEventName =
-  | "SessionStart"
-  | "UserPromptSubmit"
-  | "PreToolUse"
-  | "PostToolUse"
-  | "SubagentStart"
-  | "SubagentStop";
-
-/** Capability prefix → events it belongs to */
-const CAP_EVENT_MAP: Array<{ prefix: string; events: HookEventName[] }> = [
-  { prefix: "event.session_start", events: ["SessionStart" as const] },
-  { prefix: "event.user_prompt_submit", events: ["UserPromptSubmit" as const] },
-  { prefix: "event.pre_tool_use", events: ["PreToolUse" as const] },
-  { prefix: "event.post_tool_use", events: ["PostToolUse" as const] },
-  { prefix: "event.subagent_start", events: ["SubagentStart" as const] },
-  { prefix: "event.subagent_stop", events: ["SubagentStop" as const] },
-  {
-    prefix: "output.additional_context.session_start",
-    events: ["SessionStart" as const, "SubagentStart" as const],
-  },
-  { prefix: "output.additional_context.user_prompt", events: ["UserPromptSubmit" as const] },
-  { prefix: "output.additional_context.subagent_stop", events: ["SubagentStop" as const] },
-  { prefix: "output.additional_context.post_tool", events: ["PostToolUse" as const] },
-  { prefix: "output.additional_context.pre_tool", events: ["PreToolUse" as const] },
-];
-
-function warnOnMismatch(hooks: HookEntry[]): void {
-  for (const hook of hooks) {
-    const hookEvents = new Set(hook.meta.events);
-
-    for (const capId of hook.meta.requires_capabilities) {
-      for (const mapping of CAP_EVENT_MAP) {
-        if (!capId.startsWith(mapping.prefix)) continue;
-
-        const capEvents = new Set(mapping.events);
-        const overlap = mapping.events.some((e) => hookEvents.has(e));
-
-        if (!overlap) {
-          process.stderr.write(
-            `[build-hooks] WARN mismatch: hook "${hook.name}" listens on [${hook.meta.events.join(", ")}] ` +
-              `but capability "${capId}" applies to [${mapping.events.join(", ")}]\n`,
-          );
-        }
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Stage 4: Harness portability computation + fallback policy
-// ---------------------------------------------------------------------------
-
-function computePortability(hooks: HookEntry[], matrix: CapabilityMatrix): PortabilityPlan[] {
-  const plans: PortabilityPlan[] = [];
-
-  for (const hook of hooks) {
-    const registeredIn: Harness[] = [];
-    const excludedFrom: ExclusionRecord[] = [];
-
-    for (const harness of HARNESSES) {
-      const missingCaps: string[] = [];
-
-      for (const capId of hook.meta.requires_capabilities) {
-        const capEntry = matrix.capabilities[capId];
-        if (!capEntry) continue; // already caught in validateCapabilityIds
-
-        const support = capEntry[harness];
-        // Only `true` counts as fully supported; false and partial are unsupported
-        if (support !== true) {
-          missingCaps.push(capId);
-        }
-      }
-
-      if (missingCaps.length === 0) {
-        registeredIn.push(harness);
-      } else {
-        // Determine reason string from capability notes
-        const reasons = missingCaps
-          .map((capId) => {
-            const entry = matrix.capabilities[capId];
-            if (!entry?.note) return capId;
-            // Trim the note to a concise first sentence
-            const note = entry.note.trim().split(/\.\s/)[0]?.trim() ?? capId;
-            return note;
-          })
-          .join("; ");
-
-        // Apply fallback policy (Acceptance Criteria #7)
-        if (hook.meta.fallback === "error") {
-          throw new Error(
-            `[build-hooks] Hook "${hook.name}" fallback=error but harness "${harness}" ` +
-              `is missing capabilities: ${missingCaps.join(", ")}`,
-          );
-        }
-
-        if (hook.meta.fallback === "warn") {
-          process.stderr.write(
-            `[build-hooks] WARN: hook "${hook.name}" excluded from "${harness}" ` +
-              `(missing: ${missingCaps.join(", ")})\n`,
-          );
-        }
-        // fallback=skip: no warning, silently excluded
-
-        excludedFrom.push({ harness, missing: missingCaps, reason: reasons });
-      }
-    }
-
-    const tier = deriveTier(registeredIn, hook.meta.fallback);
-
-    plans.push({
-      name: hook.name,
-      meta: hook.meta,
-      tier,
-      registeredIn,
-      excludedFrom,
-      capabilitiesRequired: hook.meta.requires_capabilities,
-    });
-  }
-
-  return plans;
-}
-
-function deriveTier(
-  registeredIn: Harness[],
-  fallback: HookMeta["fallback"],
-): PortabilityPlan["tier"] {
-  const count = registeredIn.length;
-  if (count === 3) return "core";
-  if (count === 2) return "extended";
-  if (count === 1) {
-    // harness-specific: intentional skip-only registration in one harness
-    if (fallback === "skip") return "harness-specific";
-    return "experimental";
-  }
-  // count === 0: excluded everywhere — still experimental (build already failed if fallback=error)
-  return "experimental";
-}
-
-// ---------------------------------------------------------------------------
-// Stage 5a: Compile handlers via tsc
-//
-// Each handler.ts imports from src/ (types, shared utilities), so rootDir
-// cannot be scoped to assets/hooks alone. We compile the full project tree
-// (rootDir=.) into a temporary directory, then copy only the handler outputs
-// to dist/hooks/<name>.js — preserving the flat dist/hooks/<name>.js layout
-// required by the manifests.
-// ---------------------------------------------------------------------------
-
-function compileHandlers(hooks: HookEntry[]): void {
-  mkdirSync(DIST_HOOKS_DIR, { recursive: true });
-
-  // Compile each handler as a standalone bundle using bun build.
-  // This resolves cross-directory imports (src/hooks/types.js etc.) cleanly
-  // and produces a single-file output per hook at dist/hooks/<name>.js.
-  for (const hook of hooks) {
-    const outFile = join(DIST_HOOKS_DIR, `${hook.name}.js`);
-    try {
-      execSync(
-        `bun build ${hook.handlerPath} --outfile ${outFile} --target node --format esm`,
-        { cwd: ROOT, stdio: "inherit" },
-      );
-    } catch {
-      throw new Error(
-        `[build-hooks] Handler compilation failed for "${hook.name}" (bun build exit non-zero)`,
-      );
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Stage 5b: Write harness manifests
-// ---------------------------------------------------------------------------
-
-function loadToolNameMap(): ToolNameMap {
-  const raw = readFileSync(TOOL_NAME_MAP_PATH, "utf-8");
-  return parseYaml(raw) as ToolNameMap;
-}
-
-/**
- * Translate a nexus PascalCase matcher token to the harness-native tool name(s).
- * Returns the original token if no mapping is found.
- *
- * Acceptance Criteria #8: Bash → shell/bash per harness.
- */
-function translateMatcherToken(token: string, harness: Harness, toolMap: ToolNameMap): string {
-  const entry = toolMap.tools[token];
-  if (!entry) return token;
-
-  const harnessValue = entry[harness];
-  if (harnessValue === null || harnessValue === undefined) return token;
-
-  if (typeof harnessValue === "string") return harnessValue;
-
-  if (Array.isArray(harnessValue)) {
-    return harnessValue.join("|");
-  }
-
-  // Codex primary/aliases shape
-  if (typeof harnessValue === "object" && "primary" in harnessValue) {
-    return (harnessValue as { primary: string }).primary;
-  }
-
-  return token;
-}
-
-/**
- * Translate a pipe-separated matcher string to harness-native names.
- * e.g. "Edit|Write|MultiEdit|ApplyPatch" → "Edit|Write|MultiEdit" (claude)
- *                                        → "apply_patch" (codex, deduped)
- *                                        → "edit|write|apply_patch" (opencode, deduped)
- */
-function translateMatcher(matcher: string, harness: Harness, toolMap: ToolNameMap): string {
-  if (matcher === "*") return "*";
-
-  const tokens = matcher.split("|").map((t) => t.trim());
-  const translated = new Set<string>();
-
-  for (const token of tokens) {
-    const native = translateMatcherToken(token, harness, toolMap);
-    // native may itself be pipe-separated (Array case collapsed above)
-    for (const part of native.split("|")) {
-      if (part.trim()) translated.add(part.trim());
-    }
-  }
-
-  return [...translated].join("|");
-}
-
-function hookCommand(hookName: string, harness: Harness): string {
-  if (harness === "opencode") {
-    // OpenCode uses mountHooks JS API — command field contains the module reference
-    return `${hookName}`;
-  }
-  return `node \${CLAUDE_PLUGIN_ROOT}/dist/hooks/${hookName}.js`;
-}
-
-type ClaudeHooksJson = {
-  hooks: Record<
-    string,
-    Array<{ matcher: string; hooks: Array<{ type: string; command: string; timeout: number }> }>
-  >;
-};
-
-function buildClaudeManifest(plans: PortabilityPlan[], toolMap: ToolNameMap): ClaudeHooksJson {
-  const hooks: ClaudeHooksJson["hooks"] = {};
-
-  for (const plan of plans) {
-    if (!plan.registeredIn.includes("claude")) continue;
-
-    for (const event of plan.meta.events) {
-      if (!hooks[event]) hooks[event] = [];
-
-      const matcher = translateMatcher(plan.meta.matcher, "claude", toolMap);
-      hooks[event].push({
-        matcher,
-        hooks: [
-          {
-            type: "command",
-            command: hookCommand(plan.name, "claude"),
-            timeout: plan.meta.timeout,
-          },
-        ],
-      });
-    }
-  }
-
-  // Sort events' hook arrays by priority descending (already sorted at plan level)
-  return { hooks };
-}
-
-type CodexHooksJson = {
-  hooks: Record<
-    string,
-    Array<{ matcher?: string; command: string; timeout: number }>
-  >;
-};
-
-function buildCodexManifest(plans: PortabilityPlan[], toolMap: ToolNameMap): CodexHooksJson {
-  const hooks: CodexHooksJson["hooks"] = {};
-
-  for (const plan of plans) {
-    if (!plan.registeredIn.includes("codex")) continue;
-
-    for (const event of plan.meta.events) {
-      if (!hooks[event]) hooks[event] = [];
-
-      const matcher = translateMatcher(plan.meta.matcher, "codex", toolMap);
-      const entry: { matcher?: string; command: string; timeout: number } = {
-        command: hookCommand(plan.name, "codex"),
-        timeout: plan.meta.timeout,
-      };
-      if (matcher !== "*") entry.matcher = matcher;
-      hooks[event].push(entry);
-    }
-  }
-
-  return { hooks };
-}
-
-type OpenCodeHooksJson = {
-  mountHooks: Array<{
-    event: string;
-    matcher?: string;
-    module: string;
-    timeout: number;
-  }>;
-};
-
-function buildOpenCodeManifest(plans: PortabilityPlan[], toolMap: ToolNameMap): OpenCodeHooksJson {
-  const mountHooks: OpenCodeHooksJson["mountHooks"] = [];
-
-  for (const plan of plans) {
-    if (!plan.registeredIn.includes("opencode")) continue;
-
-    for (const event of plan.meta.events) {
-      const matcher = translateMatcher(plan.meta.matcher, "opencode", toolMap);
-      const entry: OpenCodeHooksJson["mountHooks"][number] = {
-        event,
-        module: `./dist/hooks/${plan.name}.js`,
-        timeout: plan.meta.timeout,
-      };
-      if (matcher !== "*") entry.matcher = matcher;
-      mountHooks.push(entry);
-    }
-  }
-
-  return { mountHooks };
-}
-
-function writeManifests(plans: PortabilityPlan[]): void {
-  mkdirSync(DIST_MANIFESTS_DIR, { recursive: true });
-
-  const toolMap = loadToolNameMap();
-
-  const claude = buildClaudeManifest(plans, toolMap);
-  const codex = buildCodexManifest(plans, toolMap);
-  const opencode = buildOpenCodeManifest(plans, toolMap);
-
-  writeFileSync(
-    join(DIST_MANIFESTS_DIR, "claude-hooks.json"),
-    JSON.stringify(claude, null, 2) + "\n",
-  );
-  writeFileSync(
-    join(DIST_MANIFESTS_DIR, "codex-hooks.json"),
-    JSON.stringify(codex, null, 2) + "\n",
-  );
-  writeFileSync(
-    join(DIST_MANIFESTS_DIR, "opencode-hooks.json"),
-    JSON.stringify(opencode, null, 2) + "\n",
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Stage 5c: Write portability report
-// ---------------------------------------------------------------------------
-
-type PortabilityReport = Record<
-  string,
-  {
-    tier: PortabilityPlan["tier"];
-    registered_in: Harness[];
-    excluded_from: Array<{ harness: Harness; missing: string[]; reason: string }>;
-    capabilities_required: string[];
-  }
->;
-
-function writePortabilityReport(plans: PortabilityPlan[]): void {
-  mkdirSync(DIST_MANIFESTS_DIR, { recursive: true });
-
-  const report: PortabilityReport = {};
-
-  for (const plan of plans) {
-    report[plan.name] = {
-      tier: plan.tier,
-      registered_in: plan.registeredIn,
-      excluded_from: plan.excludedFrom,
-      capabilities_required: plan.capabilitiesRequired,
-    };
-  }
-
-  writeFileSync(
-    join(DIST_MANIFESTS_DIR, "portability-report.json"),
-    JSON.stringify(report, null, 2) + "\n",
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Main entry point
-// ---------------------------------------------------------------------------
-
-export async function buildHooks(): Promise<void> {
-  // Stage 1
-  const hooks = loadAllHooks();
-  console.log(`[build-hooks] Loaded ${hooks.length} hooks`);
-
-  // Stage 2
-  const matrix = loadCapabilityMatrix();
-  validateCapabilityIds(hooks, matrix);
-
-  // Stage 3
-  warnOnMismatch(hooks);
-
-  // Stage 4
-  const plans = computePortability(hooks, matrix);
-
-  // Stage 5
-  compileHandlers(hooks);
-  writeManifests(plans);
-  writePortabilityReport(plans);
-
-  console.log(`[build-hooks] ${hooks.length} hooks processed`);
-  for (const plan of plans) {
-    console.log(
-      `  ${plan.name}: tier=${plan.tier} registered=[${plan.registeredIn.join(",")}]`,
-    );
-  }
-}
-
-// Run when executed directly (bun run scripts/build-hooks.ts)
-if (
-  import.meta.url === `file://${process.argv[1]}` ||
-  process.argv[1]?.endsWith("build-hooks.ts") ||
-  process.argv[1]?.endsWith("build-hooks.js")
-) {
-  buildHooks().catch((err: unknown) => {
-    process.stderr.write(`[build-hooks] FATAL: ${String(err)}\n`);
-    process.exit(1);
-  });
-}