@h-rig/hook-kit 0.0.6-alpha.8 → 0.0.6-alpha.81

package/dist/src/context.d.ts

@@ -0,0 +1,35 @@
+/** Read build-time baked config. Exported for use by sibling modules in hook-kit. */
+export declare function readBuildConfigForKit(): Record<string, string>;
+export declare const BAKED_PROJECT_ROOT: string;
+export declare const BAKED_TASK_ID: string;
+export declare const BAKED_STATE_DIR: string;
+export declare const BAKED_BUN_PATH: string;
+export declare const BAKED_TASK_CONFIG: string;
+export declare const BAKED_POLICY_CONTENT: string;
+export declare const BAKED_TASK_SCOPES: string;
+export type HookContext = {
+    taskId: string;
+    role: string;
+    scopes: string[];
+    validation: string[];
+    hostProjectRoot?: string | undefined;
+    monorepoMainRoot?: string | undefined;
+    stateDir: string;
+    policyFile: string;
+};
+/** Load HookContext from the runtime context JSON file, or return null. */
+export declare function loadHookContextFromEnv(): HookContext | null;
+/** Resolve the project root from HookContext, baked constant, env, or CWD heuristic. */
+export declare function resolveProjectRoot(): string;
+/** Resolve the current task ID from HookContext, baked constant, or env vars. */
+export declare function resolveTaskIdForHook(_projectRoot: string): string;
+/** Get task config from HookContext, baked constant, or disk. */
+export declare function resolveTaskConfig(_projectRoot: string, _taskId: string): Promise<{
+    scope?: string[];
+    validation?: string[];
+    role?: string;
+}>;
+/** Get scope globs from HookContext, baked constant, or disk config. */
+export declare function resolveTaskScopes(projectRoot: string, taskId: string): Promise<string[]>;
+/** Get policy content from HookContext, baked constant, or disk. */
+export declare function resolvePolicyContent(projectRoot: string): string;

package/dist/src/guard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Block the current action, log the trip, and exit non-zero.
+ *
+ * Writes a BLOCKED message to stdout (so Claude Code sees it immediately),
+ * appends to the hook_trips.log in stateDir, and calls `process.exit(1)`.
+ *
+ * After 3 trips for the same hookName an escalation line is appended to the
+ * message. The escalation text is intentionally generic so Rig plugins can
+ * override the CLAUDE.md reference.
+ */
+export declare function block(hookName: string, message: string, projectRoot: string): never;

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export type { HookInput, ParsedHookInput } from "./io";
+export { readHookInput } from "./io";
+export type { HookContext } from "./context";
+export { BAKED_PROJECT_ROOT, BAKED_TASK_ID, BAKED_STATE_DIR, BAKED_BUN_PATH, BAKED_TASK_CONFIG, BAKED_POLICY_CONTENT, BAKED_TASK_SCOPES, resolveProjectRoot, resolveTaskIdForHook, resolveTaskConfig, resolveTaskScopes, resolvePolicyContent, } from "./context";
+export { block } from "./guard";
+export type { TypedHookOptions } from "./typed";
+export { buildPluginHookContext, hookResultToProtocol, runTypedHook, } from "./typed";
+export { extractToolFilePaths, isTestFilePath } from "./tools";
+export { resolveBunCli, resolveBunCliInvocation } from "./runtime";
+export { escapeRegExp } from "./utils";

package/dist/src/index.js

@@ -294,6 +294,9 @@ function block(hookName, message, projectRoot) {
 `);
   process.exit(1);
 }
+// packages/hook-kit/src/typed.ts
+import { writeSync as writeSync2 } from "fs";
+
 // packages/hook-kit/src/tools.ts
 function extractToolFilePaths(toolName, input) {
   const paths = [];
@@ -318,6 +321,60 @@ function extractToolFilePaths(toolName, input) {
 function isTestFilePath(path) {
   return /\.(test|spec)\.(ts|tsx|js|jsx)$/.test(path) || /\/(__tests__|tests|test)\//.test(path);
 }
+
+// packages/hook-kit/src/typed.ts
+function buildPluginHookContext(parsed, opts) {
+  const toolName = parsed.input.tool_name;
+  const toolInput = parsed.input.tool_input ?? {};
+  return {
+    event: opts.event,
+    toolName,
+    toolInput,
+    filePaths: toolName ? extractToolFilePaths(toolName, toolInput) : [],
+    projectRoot: opts.projectRoot,
+    taskId: opts.taskId
+  };
+}
+function hookResultToProtocol(result) {
+  if (result.decision === "block") {
+    const lines = [`BLOCKED: ${result.reason ?? "blocked by plugin hook"}`];
+    if (result.systemMessage) {
+      lines.push(result.systemMessage);
+    }
+    return { exitCode: 1, stdout: `${lines.join(`
+`)}
+` };
+  }
+  return {
+    exitCode: 0,
+    stdout: result.systemMessage ? `${result.systemMessage}
+` : ""
+  };
+}
+async function runTypedHook(fn, opts) {
+  const parsed = await readHookInput();
+  const projectRoot = opts.projectRoot ?? resolveProjectRoot();
+  const taskId = opts.taskId ?? resolveTaskIdForHook(projectRoot);
+  const ctx = buildPluginHookContext(parsed, {
+    event: opts.event,
+    projectRoot,
+    taskId
+  });
+  let result;
+  try {
+    result = await fn(ctx);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    writeSync2(2, `[rig hook] typed hook threw: ${message}
+`);
+    process.exit(0);
+  }
+  const { exitCode, stdout } = hookResultToProtocol(result);
+  if (stdout) {
+    writeSync2(1, stdout);
+  }
+  process.exit(exitCode);
+}
 // packages/hook-kit/src/runtime.ts
 import { existsSync as existsSync3, realpathSync } from "fs";
 import { resolve as resolve3 } from "path";
@@ -401,6 +458,7 @@ function resolveBunCliInvocation() {
   return { command: "bun", env: {} };
 }
 export {
+  runTypedHook,
   resolveTaskScopes,
   resolveTaskIdForHook,
   resolveTaskConfig,
@@ -410,8 +468,10 @@ export {
   resolveBunCli,
   readHookInput,
   isTestFilePath,
+  hookResultToProtocol,
   extractToolFilePaths,
   escapeRegExp,
+  buildPluginHookContext,
   block,
   BAKED_TASK_SCOPES,
   BAKED_TASK_ID,

package/dist/src/io.d.ts

@@ -0,0 +1,14 @@
+/** JSON shape of a Claude Code hook payload. */
+export type HookInput = {
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    command?: string;
+};
+/** Wrapper around `HookInput` with parse-success flags. */
+export type ParsedHookInput = {
+    input: HookInput;
+    valid: boolean;
+    hadPayload: boolean;
+};
+/** Read and parse the JSON hook payload from stdin or `RIG_HOOK_INPUT_FILE`. */
+export declare function readHookInput(): Promise<ParsedHookInput>;

package/dist/src/runtime.d.ts

@@ -0,0 +1,7 @@
+/** Returns the bun binary path string. */
+export declare function resolveBunCli(): string;
+/** Returns `{ command, env }` for spawning bun. */
+export declare function resolveBunCliInvocation(): {
+    command: string;
+    env: Record<string, string>;
+};

package/dist/src/tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tool-input helpers for hook binaries.
+ *
+ * Moved from packages/runtime/src/control-plane/hooks/shared.ts
+ * in Phase 5 Task 5.3 of the Rig extraction.
+ */
+/** Extract file path candidates from tool input for pre-guard worktree checks. */
+export declare function extractToolFilePaths(toolName: string, input: Record<string, unknown>): string[];
+/** Check whether a file path looks like a test file. */
+export declare function isTestFilePath(path: string): boolean;

package/dist/src/typed.d.ts

@@ -0,0 +1,33 @@
+import type { HookContext as PluginHookContext, HookEvent, HookImplementation, HookResult } from "@rig/contracts";
+import { type ParsedHookInput } from "./io";
+export interface TypedHookOptions {
+    /** The lifecycle event this hook is registered for (from its metadata). */
+    event: HookEvent;
+    /** Project root override; resolved via `resolveProjectRoot()` when absent. */
+    projectRoot?: string;
+    /** Task id override; resolved via `resolveTaskIdForHook()` when absent. */
+    taskId?: string;
+}
+/**
+ * Build the typed-hook input from a parsed Claude Code hook payload.
+ * Pure — exported for tests and for the plugin-testkit helpers.
+ */
+export declare function buildPluginHookContext(parsed: ParsedHookInput, opts: {
+    event: HookEvent;
+    projectRoot: string;
+    taskId: string;
+}): PluginHookContext;
+/**
+ * Serialize a HookResult to the Claude Code hook protocol. Pure — the
+ * exit/stdout side effects happen in `runTypedHook`.
+ */
+export declare function hookResultToProtocol(result: HookResult): {
+    exitCode: 0 | 1;
+    stdout: string;
+};
+/**
+ * Run a typed hook implementation against the current process's hook
+ * invocation: parse stdin into a HookContext, call the function, write the
+ * protocol output, and exit. Never returns.
+ */
+export declare function runTypedHook(fn: HookImplementation, opts: TypedHookOptions): Promise<never>;

package/dist/src/typed.js

@@ -0,0 +1,247 @@
+// @bun
+// packages/hook-kit/src/typed.ts
+import { writeSync } from "fs";
+
+// packages/hook-kit/src/io.ts
+import { readFileSync } from "fs";
+async function readHookInput() {
+  let text = "";
+  const inputFile = process.env.RIG_HOOK_INPUT_FILE?.trim();
+  if (inputFile) {
+    text = readFileSync(inputFile, "utf-8");
+  } else {
+    try {
+      text = readFileSync("/dev/stdin", "utf-8");
+    } catch {
+      text = readFileSync(0, "utf-8");
+    }
+  }
+  if (!text.trim()) {
+    return { input: {}, valid: true, hadPayload: false };
+  }
+  try {
+    return {
+      input: JSON.parse(text),
+      valid: true,
+      hadPayload: true
+    };
+  } catch {
+    return { input: {}, valid: false, hadPayload: true };
+  }
+}
+
+// packages/hook-kit/src/tools.ts
+function extractToolFilePaths(toolName, input) {
+  const paths = [];
+  const add = (value) => {
+    if (typeof value === "string" && value.trim()) {
+      paths.push(value.trim());
+    }
+  };
+  if (toolName === "Read" || toolName === "Write" || toolName === "Edit" || toolName === "MultiEdit") {
+    add(input.file_path);
+    add(input.path);
+  } else if (toolName === "Glob") {
+    add(input.path);
+  } else if (toolName === "Grep") {
+    add(input.path);
+  } else {
+    add(input.file_path);
+    add(input.path);
+  }
+  return paths;
+}
+
+// packages/hook-kit/src/context.ts
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { resolve } from "path";
+var RIG_DEFINITION_DIRNAME = "rig";
+var RIG_STATE_DIRNAME = ".rig";
+function normalizeBuildConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
+function readBuildConfigForKit() {
+  if (typeof __RIG_BUILD_CONFIG__ !== "undefined") {
+    return normalizeBuildConfig(__RIG_BUILD_CONFIG__);
+  }
+  const raw = process.env.RIG_BUILD_CONFIG_JSON?.trim();
+  if (!raw) {
+    return {};
+  }
+  try {
+    return normalizeBuildConfig(JSON.parse(raw));
+  } catch {
+    return {};
+  }
+}
+var BUILD_CONFIG = readBuildConfigForKit();
+var BAKED_PROJECT_ROOT = BUILD_CONFIG.AGENT_PROJECT_ROOT ?? "";
+var BAKED_TASK_ID = BUILD_CONFIG.AGENT_TASK_ID ?? "";
+var BAKED_STATE_DIR = BUILD_CONFIG.AGENT_STATE_DIR ?? "";
+var BAKED_BUN_PATH = BUILD_CONFIG.AGENT_BUN_PATH ?? "";
+var BAKED_TASK_CONFIG = BUILD_CONFIG.AGENT_TASK_CONFIG ?? "";
+var BAKED_POLICY_CONTENT = BUILD_CONFIG.AGENT_POLICY_CONTENT ?? "";
+var BAKED_TASK_SCOPES = BUILD_CONFIG.AGENT_TASK_SCOPES ?? "";
+var RUNTIME_CONTEXT_ENV = "RIG_RUNTIME_CONTEXT_FILE";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function loadHookContextFromEnv() {
+  const contextFile = process.env[RUNTIME_CONTEXT_ENV]?.trim();
+  let filePath = contextFile || "";
+  if (!filePath) {
+    let current = resolve(process.cwd());
+    while (true) {
+      const candidate = resolve(current, "runtime-context.json");
+      if (existsSync(candidate)) {
+        filePath = candidate;
+        break;
+      }
+      const parent = resolve(current, "..");
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  if (!filePath || !existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const raw = JSON.parse(readFileSync2(filePath, "utf-8"));
+    if (!isPlainObject(raw)) {
+      return null;
+    }
+    const taskId = typeof raw.taskId === "string" ? raw.taskId : "";
+    const role = typeof raw.role === "string" ? raw.role : "";
+    const scopes = isStringArray(raw.scopes) ? raw.scopes : [];
+    const validation = isStringArray(raw.validation) ? raw.validation : [];
+    const hostProjectRoot = typeof raw.hostProjectRoot === "string" ? raw.hostProjectRoot : undefined;
+    const monorepoMainRoot = typeof raw.monorepoMainRoot === "string" ? raw.monorepoMainRoot : undefined;
+    const stateDir = typeof raw.stateDir === "string" ? raw.stateDir : "";
+    const policyFile = typeof raw.policyFile === "string" ? raw.policyFile : "";
+    if (!taskId || !stateDir) {
+      return null;
+    }
+    return {
+      taskId,
+      role,
+      scopes,
+      validation,
+      hostProjectRoot,
+      monorepoMainRoot,
+      stateDir,
+      policyFile
+    };
+  } catch {
+    return null;
+  }
+}
+var cachedContext;
+function getContext() {
+  if (cachedContext !== undefined) {
+    return cachedContext;
+  }
+  cachedContext = loadHookContextFromEnv();
+  return cachedContext;
+}
+function resolveProjectRoot() {
+  const ctx = getContext();
+  if (ctx?.hostProjectRoot)
+    return ctx.hostProjectRoot;
+  if (BAKED_PROJECT_ROOT) {
+    return BAKED_PROJECT_ROOT;
+  }
+  if (process.env.PROJECT_RIG_ROOT) {
+    return process.env.PROJECT_RIG_ROOT;
+  }
+  const candidates = [process.cwd(), resolve(import.meta.dirname, "../..")];
+  for (const candidate of candidates) {
+    if (existsSync(resolve(candidate, RIG_DEFINITION_DIRNAME)) || existsSync(resolve(candidate, RIG_STATE_DIRNAME))) {
+      return candidate;
+    }
+  }
+  return resolve(import.meta.dirname, "../..");
+}
+function resolveTaskIdForHook(_projectRoot) {
+  const ctx = getContext();
+  if (ctx)
+    return ctx.taskId;
+  if (BAKED_TASK_ID) {
+    return BAKED_TASK_ID;
+  }
+  const fromEnv = (process.env.RIG_TASK_ID || "").trim();
+  if (fromEnv) {
+    return fromEnv;
+  }
+  const runtimeId = (process.env.RIG_TASK_RUNTIME_ID || "").trim();
+  if (runtimeId.startsWith("task-") && runtimeId.length > "task-".length) {
+    return runtimeId.slice("task-".length);
+  }
+  return "";
+}
+
+// packages/hook-kit/src/typed.ts
+function buildPluginHookContext(parsed, opts) {
+  const toolName = parsed.input.tool_name;
+  const toolInput = parsed.input.tool_input ?? {};
+  return {
+    event: opts.event,
+    toolName,
+    toolInput,
+    filePaths: toolName ? extractToolFilePaths(toolName, toolInput) : [],
+    projectRoot: opts.projectRoot,
+    taskId: opts.taskId
+  };
+}
+function hookResultToProtocol(result) {
+  if (result.decision === "block") {
+    const lines = [`BLOCKED: ${result.reason ?? "blocked by plugin hook"}`];
+    if (result.systemMessage) {
+      lines.push(result.systemMessage);
+    }
+    return { exitCode: 1, stdout: `${lines.join(`
+`)}
+` };
+  }
+  return {
+    exitCode: 0,
+    stdout: result.systemMessage ? `${result.systemMessage}
+` : ""
+  };
+}
+async function runTypedHook(fn, opts) {
+  const parsed = await readHookInput();
+  const projectRoot = opts.projectRoot ?? resolveProjectRoot();
+  const taskId = opts.taskId ?? resolveTaskIdForHook(projectRoot);
+  const ctx = buildPluginHookContext(parsed, {
+    event: opts.event,
+    projectRoot,
+    taskId
+  });
+  let result;
+  try {
+    result = await fn(ctx);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    writeSync(2, `[rig hook] typed hook threw: ${message}
+`);
+    process.exit(0);
+  }
+  const { exitCode, stdout } = hookResultToProtocol(result);
+  if (stdout) {
+    writeSync(1, stdout);
+  }
+  process.exit(exitCode);
+}
+export {
+  runTypedHook,
+  hookResultToProtocol,
+  buildPluginHookContext
+};

package/dist/src/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * General utility helpers for hook binaries.
+ *
+ * Moved from packages/runtime/src/control-plane/hooks/shared.ts
+ * in Phase 5 Task 5.3 of the Rig extraction.
+ */
+/** Escape special regex characters in a string. */
+export declare function escapeRegExp(value: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@h-rig/hook-kit",
-  "version": "0.0.6-alpha.8",
+  "version": "0.0.6-alpha.81",
   "type": "module",
   "description": "Rig package",
   "license": "UNLICENSED",
@@ -10,6 +10,7 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
     }
   },
@@ -18,8 +19,9 @@
   },
   "main": "./dist/src/index.js",
   "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "dependencies": {
-    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.8",
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.81",
     "effect": "4.0.0-beta.78"
   }
 }