@omnidev-ai/core 0.8.0 → 0.10.0

package/src/hooks/merger.ts

@@ -0,0 +1,157 @@
+/**
+ * Hook configuration merging
+ *
+ * Merges hooks from multiple capabilities into a single configuration.
+ * Used when generating provider settings from all active capabilities.
+ */
+
+import { HOOK_EVENTS } from "./constants.js";
+import type { HooksConfig, HookMatcher, CapabilityHooks, HookEvent } from "./types.js";
+
+/**
+ * Merge hooks from multiple capabilities into a single HooksConfig.
+ *
+ * Strategy:
+ * - All matchers from all capabilities are collected
+ * - Hooks are not deduplicated to preserve execution order and capability-specific behavior
+ * - Description field is omitted in merged config (it's per-capability metadata)
+ */
+export function mergeHooksConfigs(capabilityHooks: CapabilityHooks[]): HooksConfig {
+	const result: HooksConfig = {};
+
+	for (const event of HOOK_EVENTS) {
+		const allMatchers: HookMatcher[] = [];
+
+		for (const capHooks of capabilityHooks) {
+			const matchers = capHooks.config[event];
+			if (matchers && matchers.length > 0) {
+				allMatchers.push(...matchers);
+			}
+		}
+
+		if (allMatchers.length > 0) {
+			result[event] = allMatchers;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Options for deduplication
+ */
+export interface DeduplicateOptions {
+	/** Deduplicate identical commands across matchers (default: false) */
+	deduplicateCommands?: boolean;
+}
+
+/**
+ * Merge and deduplicate hooks from multiple capability hooks.
+ *
+ * When deduplicateCommands is true:
+ * - Commands that are exactly identical are kept only once per event
+ * - The first occurrence is kept, subsequent duplicates removed
+ *
+ * This is useful when multiple capabilities might register the same hook
+ * (e.g., a common formatting hook).
+ */
+export function mergeAndDeduplicateHooks(
+	capabilityHooks: CapabilityHooks[],
+	options?: DeduplicateOptions,
+): HooksConfig {
+	const merged = mergeHooksConfigs(capabilityHooks);
+
+	if (!options?.deduplicateCommands) {
+		return merged;
+	}
+
+	// Deduplicate commands within each event
+	const result: HooksConfig = {};
+
+	for (const event of HOOK_EVENTS) {
+		const matchers = merged[event];
+		if (!matchers || matchers.length === 0) {
+			continue;
+		}
+
+		const seenCommands = new Set<string>();
+		const deduplicatedMatchers: HookMatcher[] = [];
+
+		for (const matcher of matchers) {
+			const deduplicatedHooks = matcher.hooks.filter((hook) => {
+				if (hook.type !== "command") {
+					// Prompt hooks are not deduplicated
+					return true;
+				}
+
+				const key = hook.command;
+				if (seenCommands.has(key)) {
+					return false;
+				}
+				seenCommands.add(key);
+				return true;
+			});
+
+			// Only include matcher if it has hooks remaining
+			if (deduplicatedHooks.length > 0) {
+				deduplicatedMatchers.push({
+					...matcher,
+					hooks: deduplicatedHooks,
+				});
+			}
+		}
+
+		if (deduplicatedMatchers.length > 0) {
+			result[event] = deduplicatedMatchers;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Check if a merged config has any hooks defined
+ */
+export function hasAnyHooks(config: HooksConfig): boolean {
+	for (const event of HOOK_EVENTS) {
+		const matchers = config[event];
+		if (matchers && matchers.length > 0) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Count total number of hook definitions across all events
+ */
+export function countHooks(config: HooksConfig): number {
+	let count = 0;
+
+	for (const event of HOOK_EVENTS) {
+		const matchers = config[event];
+		if (matchers) {
+			for (const matcher of matchers) {
+				count += matcher.hooks.length;
+			}
+		}
+	}
+
+	return count;
+}
+
+/**
+ * Get all events that have hooks defined
+ */
+export function getEventsWithHooks(config: HooksConfig): HookEvent[] {
+	const events: HookEvent[] = [];
+
+	for (const event of HOOK_EVENTS) {
+		const matchers = config[event];
+		if (matchers && matchers.length > 0) {
+			events.push(event);
+		}
+	}
+
+	return events;
+}

package/src/hooks/types.ts

@@ -0,0 +1,212 @@
+/**
+ * Hook system types
+ *
+ * Provides TypeScript types for the hooks configuration system,
+ * including validation result types and type guards.
+ */
+
+import {
+	HOOK_EVENTS,
+	HOOK_TYPES,
+	MATCHER_EVENTS,
+	PROMPT_HOOK_EVENTS,
+	type NOTIFICATION_MATCHERS,
+	type SESSION_START_MATCHERS,
+	type PRE_COMPACT_MATCHERS,
+	type VARIABLE_MAPPINGS,
+} from "./constants.js";
+
+// ============ Core Type Derivations ============
+
+/** All supported hook event names */
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+
+/** Hook execution types: command or prompt */
+export type HookType = (typeof HOOK_TYPES)[number];
+
+/** Events that support matcher patterns */
+export type MatcherEvent = (typeof MATCHER_EVENTS)[number];
+
+/** Events that support prompt-type hooks */
+export type PromptHookEvent = (typeof PROMPT_HOOK_EVENTS)[number];
+
+// Matcher types for specific events
+export type NotificationMatcher = (typeof NOTIFICATION_MATCHERS)[number];
+export type SessionStartMatcher = (typeof SESSION_START_MATCHERS)[number];
+export type PreCompactMatcher = (typeof PRE_COMPACT_MATCHERS)[number];
+
+// Variable types
+export type OmnidevVariable = keyof typeof VARIABLE_MAPPINGS;
+export type ClaudeVariable = (typeof VARIABLE_MAPPINGS)[OmnidevVariable];
+
+// ============ Hook Definitions ============
+
+/** Command-type hook that executes a shell command */
+export interface HookCommand {
+	type: "command";
+	/** Shell command to execute */
+	command: string;
+	/** Timeout in seconds (default: 60) */
+	timeout?: number;
+}
+
+/** Prompt-type hook that uses LLM evaluation */
+export interface HookPrompt {
+	type: "prompt";
+	/** Prompt text to send to LLM (use $ARGUMENTS for input) */
+	prompt: string;
+	/** Timeout in seconds (default: 30) */
+	timeout?: number;
+}
+
+/** Union of all hook types */
+export type Hook = HookCommand | HookPrompt;
+
+/** Hook matcher entry - groups hooks by matcher pattern */
+export interface HookMatcher {
+	/**
+	 * Regex pattern to match tool/event names
+	 * - Use "*" or "" to match all
+	 * - Supports regex: "Edit|Write", "Bash.*"
+	 */
+	matcher?: string;
+	/** Array of hooks to execute when pattern matches */
+	hooks: Hook[];
+}
+
+// ============ Configuration Structure ============
+
+/** Full hooks configuration from hooks.toml */
+export interface HooksConfig {
+	/** Optional description of the hooks */
+	description?: string;
+
+	// Events with matchers
+	PreToolUse?: HookMatcher[];
+	PostToolUse?: HookMatcher[];
+	PermissionRequest?: HookMatcher[];
+	Notification?: HookMatcher[];
+	SessionStart?: HookMatcher[];
+	PreCompact?: HookMatcher[];
+
+	// Events without matchers (matcher field ignored if present)
+	UserPromptSubmit?: HookMatcher[];
+	Stop?: HookMatcher[];
+	SubagentStop?: HookMatcher[];
+	SessionEnd?: HookMatcher[];
+}
+
+// ============ Validation Types ============
+
+export type ValidationSeverity = "error" | "warning";
+
+/** Validation error codes for consistent reporting */
+export type HookValidationCode =
+	| "HOOKS_INVALID_TOML"
+	| "HOOKS_UNKNOWN_EVENT"
+	| "HOOKS_INVALID_TYPE"
+	| "HOOKS_PROMPT_NOT_ALLOWED"
+	| "HOOKS_MISSING_COMMAND"
+	| "HOOKS_MISSING_PROMPT"
+	| "HOOKS_INVALID_TIMEOUT"
+	| "HOOKS_INVALID_MATCHER"
+	| "HOOKS_SCRIPT_NOT_FOUND"
+	| "HOOKS_SCRIPT_NOT_EXECUTABLE"
+	| "HOOKS_CLAUDE_VARIABLE"
+	| "HOOKS_EMPTY_ARRAY"
+	| "HOOKS_DUPLICATE_COMMAND"
+	| "HOOKS_INVALID_HOOKS_ARRAY";
+
+export interface HookValidationIssue {
+	severity: ValidationSeverity;
+	/** Validation error code */
+	code: HookValidationCode;
+	/** Which event the issue is in */
+	event?: HookEvent;
+	/** Which matcher index (0-based) */
+	matcherIndex?: number;
+	/** Which hook index within the matcher (0-based) */
+	hookIndex?: number;
+	/** Human-readable error message */
+	message: string;
+	/** File path if applicable (for script validation) */
+	path?: string;
+	/** Suggestion for fixing the issue */
+	suggestion?: string;
+}
+
+export interface HookValidationResult {
+	valid: boolean;
+	errors: HookValidationIssue[];
+	warnings: HookValidationIssue[];
+}
+
+// ============ Capability Integration ============
+
+// TODO: Add programmatic export support for hooks in CapabilityExport interface
+// This would allow capabilities to define hooks in index.ts alongside other exports
+
+/** Hooks metadata attached to a capability */
+export interface CapabilityHooks {
+	/** Source capability name */
+	capabilityName: string;
+	/** Source capability path */
+	capabilityPath: string;
+	/** The hooks configuration */
+	config: HooksConfig;
+	/** Validation result */
+	validation: HookValidationResult;
+}
+
+// ============ Doctor Types ============
+
+export type DoctorCheckStatus = "pass" | "fail" | "warn";
+
+export interface HooksDoctorCheck {
+	name: string;
+	status: DoctorCheckStatus;
+	message: string;
+	details?: string[];
+}
+
+export interface HooksDoctorResult {
+	checks: HooksDoctorCheck[];
+	summary: {
+		total: number;
+		passed: number;
+		failed: number;
+		warnings: number;
+	};
+}
+
+// ============ Type Guards ============
+
+/** Check if a hook is a command hook */
+export function isHookCommand(hook: Hook): hook is HookCommand {
+	return hook.type === "command";
+}
+
+/** Check if a hook is a prompt hook */
+export function isHookPrompt(hook: Hook): hook is HookPrompt {
+	return hook.type === "prompt";
+}
+
+/** Check if an event supports matchers */
+export function isMatcherEvent(event: string): event is MatcherEvent {
+	return (MATCHER_EVENTS as readonly string[]).includes(event);
+}
+
+/** Check if an event supports prompt-type hooks */
+export function isPromptHookEvent(event: string): event is PromptHookEvent {
+	return (PROMPT_HOOK_EVENTS as readonly string[]).includes(event);
+}
+
+/** Check if a string is a valid hook event */
+export function isHookEvent(event: string): event is HookEvent {
+	return (HOOK_EVENTS as readonly string[]).includes(event);
+}
+
+/** Check if a string is a valid hook type */
+export function isHookType(type: string): type is HookType {
+	return (HOOK_TYPES as readonly string[]).includes(type);
+}