@omnidev-ai/core 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -138,6 +138,171 @@ interface CapabilityExport {
 	/** Additional exports for extensibility */
 	[key: string]: unknown;
 }
+/**
+* Hook system constants
+*
+* All constants are defined as readonly arrays/objects to enable
+* TypeScript literal type inference.
+*/
+/** All supported hook events */
+declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PermissionRequest", "UserPromptSubmit", "Stop", "SubagentStop", "Notification", "SessionStart", "SessionEnd", "PreCompact"];
+/** Events that support matchers (regex patterns to filter tool names) */
+declare const MATCHER_EVENTS: readonly ["PreToolUse", "PostToolUse", "PermissionRequest", "Notification", "SessionStart", "PreCompact"];
+/** Events that support prompt-type hooks (LLM evaluation) */
+declare const PROMPT_HOOK_EVENTS: readonly ["Stop", "SubagentStop", "UserPromptSubmit", "PreToolUse", "PermissionRequest"];
+/** Hook execution types */
+declare const HOOK_TYPES: readonly ["command", "prompt"];
+/**
+* Common tool matchers (for validation hints, not exhaustive)
+* These are the tools available in Claude Code that hooks commonly target.
+*/
+declare const COMMON_TOOL_MATCHERS: readonly ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "Task", "WebFetch", "WebSearch", "NotebookEdit", "LSP", "TodoWrite", "AskUserQuestion"];
+/** Notification type matchers */
+declare const NOTIFICATION_MATCHERS: readonly ["permission_prompt", "idle_prompt", "auth_success", "elicitation_dialog"];
+/** SessionStart source matchers */
+declare const SESSION_START_MATCHERS: readonly ["startup", "resume", "clear", "compact"];
+/** PreCompact trigger matchers */
+declare const PRE_COMPACT_MATCHERS: readonly ["manual", "auto"];
+/** Default timeout for command hooks (in seconds) */
+declare const DEFAULT_COMMAND_TIMEOUT = 60;
+/** Default timeout for prompt hooks (in seconds) */
+declare const DEFAULT_PROMPT_TIMEOUT = 30;
+/**
+* Environment variable mappings between OmniDev and Claude Code
+*
+* When capabilities define hooks, they use OMNIDEV_ prefixed variables.
+* When writing to .claude/settings.json, these are transformed to CLAUDE_ variables.
+* When importing external capabilities, CLAUDE_ variables are transformed to OMNIDEV_.
+*/
+declare const VARIABLE_MAPPINGS: {
+	readonly OMNIDEV_CAPABILITY_ROOT: "CLAUDE_PLUGIN_ROOT";
+	readonly OMNIDEV_PROJECT_DIR: "CLAUDE_PROJECT_DIR";
+};
+/** The hooks configuration filename within a capability */
+declare const HOOKS_CONFIG_FILENAME = "hooks.toml";
+/** The hooks directory name within a capability */
+declare const HOOKS_DIRECTORY = "hooks";
+/** All supported hook event names */
+type HookEvent = (typeof HOOK_EVENTS)[number];
+/** Hook execution types: command or prompt */
+type HookType = (typeof HOOK_TYPES)[number];
+/** Events that support matcher patterns */
+type MatcherEvent = (typeof MATCHER_EVENTS)[number];
+/** Events that support prompt-type hooks */
+type PromptHookEvent = (typeof PROMPT_HOOK_EVENTS)[number];
+type NotificationMatcher = (typeof NOTIFICATION_MATCHERS)[number];
+type SessionStartMatcher = (typeof SESSION_START_MATCHERS)[number];
+type PreCompactMatcher = (typeof PRE_COMPACT_MATCHERS)[number];
+type OmnidevVariable = keyof typeof VARIABLE_MAPPINGS;
+type ClaudeVariable = (typeof VARIABLE_MAPPINGS)[OmnidevVariable];
+/** Command-type hook that executes a shell command */
+interface HookCommand {
+	type: "command";
+	/** Shell command to execute */
+	command: string;
+	/** Timeout in seconds (default: 60) */
+	timeout?: number;
+}
+/** Prompt-type hook that uses LLM evaluation */
+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 */
+type Hook = HookCommand | HookPrompt;
+/** Hook matcher entry - groups hooks by matcher pattern */
+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[];
+}
+/** Full hooks configuration from hooks.toml */
+interface HooksConfig {
+	/** Optional description of the hooks */
+	description?: string;
+	PreToolUse?: HookMatcher[];
+	PostToolUse?: HookMatcher[];
+	PermissionRequest?: HookMatcher[];
+	Notification?: HookMatcher[];
+	SessionStart?: HookMatcher[];
+	PreCompact?: HookMatcher[];
+	UserPromptSubmit?: HookMatcher[];
+	Stop?: HookMatcher[];
+	SubagentStop?: HookMatcher[];
+	SessionEnd?: HookMatcher[];
+}
+type ValidationSeverity = "error" | "warning";
+/** Validation error codes for consistent reporting */
+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";
+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;
+}
+interface HookValidationResult {
+	valid: boolean;
+	errors: HookValidationIssue[];
+	warnings: HookValidationIssue[];
+}
+/** Hooks metadata attached to a capability */
+interface CapabilityHooks {
+	/** Source capability name */
+	capabilityName: string;
+	/** Source capability path */
+	capabilityPath: string;
+	/** The hooks configuration */
+	config: HooksConfig;
+	/** Validation result */
+	validation: HookValidationResult;
+}
+type DoctorCheckStatus = "pass" | "fail" | "warn";
+interface HooksDoctorCheck {
+	name: string;
+	status: DoctorCheckStatus;
+	message: string;
+	details?: string[];
+}
+interface HooksDoctorResult {
+	checks: HooksDoctorCheck[];
+	summary: {
+		total: number;
+		passed: number;
+		failed: number;
+		warnings: number;
+	};
+}
+/** Check if a hook is a command hook */
+declare function isHookCommand(hook: Hook): hook is HookCommand;
+/** Check if a hook is a prompt hook */
+declare function isHookPrompt(hook: Hook): hook is HookPrompt;
+/** Check if an event supports matchers */
+declare function isMatcherEvent(event: string): event is MatcherEvent;
+/** Check if an event supports prompt-type hooks */
+declare function isPromptHookEvent(event: string): event is PromptHookEvent;
+/** Check if a string is a valid hook event */
+declare function isHookEvent(event: string): event is HookEvent;
+/** Check if a string is a valid hook type */
+declare function isHookType(type: string): type is HookType;
 interface CapabilityMetadata {
 	id: string;
 	name: string;
@@ -324,6 +489,8 @@ interface CapabilitiesConfig {
 	disable?: string[];
 	/** Capability sources: id -> source string or full config (git or file) */
 	sources?: Record<string, CapabilitySourceConfig>;
+	/** Capability groups: group name -> array of capability IDs */
+	groups?: Record<string, string[]>;
 }
 interface ProfileConfig {
 	capabilities?: string[];
@@ -374,6 +541,8 @@ interface LoadedCapability {
 	exports: Record<string, unknown>;
 	/** Where this capability comes from */
 	source?: CapabilitySource;
+	/** Hooks configuration from hooks/hooks.toml */
+	hooks?: CapabilityHooks;
 }
 type ProviderId = Provider | (string & {});
 interface SyncBundle {
@@ -383,6 +552,8 @@ interface SyncBundle {
 	docs: Doc[];
 	commands: Command[];
 	subagents: Subagent[];
+	/** Merged hooks from all capabilities */
+	hooks?: HooksConfig;
 	instructionsPath: string;
 	instructionsContent: string;
 }
@@ -459,6 +630,10 @@ interface CapabilityRegistry {
 	getAllSkills(): Skill[];
 	getAllRules(): Rule[];
 	getAllDocs(): Doc[];
+	/** Get all capability hooks metadata */
+	getAllCapabilityHooks(): CapabilityHooks[];
+	/** Get merged hooks from all capabilities */
+	getMergedHooks(): HooksConfig;
 }
 /**
 * Builds a capability registry by discovering, loading, and filtering capabilities.
@@ -567,6 +742,149 @@ declare function checkForUpdates(config: OmniConfig): Promise<SourceUpdateInfo[]
 * Each subagent is a SUBAGENT.md file in its own subdirectory.
 */
 declare function loadSubagents(capabilityPath: string, capabilityId: string): Promise<Subagent[]>;
+interface ValidationOptions {
+	/** Base path for resolving script files */
+	basePath?: string;
+	/** Check if script files exist and are executable */
+	checkScripts?: boolean;
+}
+/**
+* Validate a hooks configuration object
+*/
+declare function validateHooksConfig(config: unknown, options?: ValidationOptions): HookValidationResult;
+/**
+* Validate a single hook entry
+*/
+declare function validateHook(hook: unknown, event: HookEvent, context: {
+	matcherIndex: number;
+	hookIndex: number;
+}, options?: ValidationOptions): HookValidationIssue[];
+/**
+* Check if a matcher regex pattern is valid
+*/
+declare function isValidMatcherPattern(pattern: string): boolean;
+/**
+* Check for duplicate commands across all hooks
+*/
+declare function findDuplicateCommands(config: HooksConfig): HookValidationIssue[];
+/**
+* Create an empty valid hooks config
+*/
+declare function createEmptyHooksConfig(): HooksConfig;
+/**
+* Create an empty validation result (valid with no issues)
+*/
+declare function createEmptyValidationResult(): HookValidationResult;
+/**
+* Transform Claude Code variables to OmniDev format
+* Used when: importing/wrapping external capabilities
+*
+* CLAUDE_PLUGIN_ROOT -> OMNIDEV_CAPABILITY_ROOT
+* CLAUDE_PROJECT_DIR -> OMNIDEV_PROJECT_DIR
+*/
+declare function transformToOmnidev(content: string): string;
+/**
+* Transform OmniDev variables to Claude Code format
+* Used when: writing to .claude/settings.json
+*
+* OMNIDEV_CAPABILITY_ROOT -> CLAUDE_PLUGIN_ROOT
+* OMNIDEV_PROJECT_DIR -> CLAUDE_PROJECT_DIR
+*/
+declare function transformToClaude(content: string): string;
+/**
+* Transform all variables in a HooksConfig
+*/
+declare function transformHooksConfig(config: HooksConfig, direction: "toOmnidev" | "toClaude"): HooksConfig;
+/**
+* Check if a string contains any Claude variables
+*/
+declare function containsClaudeVariables(content: string): boolean;
+/**
+* Check if a string contains any OmniDev variables
+*/
+declare function containsOmnidevVariables(content: string): boolean;
+interface LoadHooksOptions {
+	/** Transform Claude variables to OmniDev format (default: true) */
+	transformVariables?: boolean;
+	/** Validate the hooks configuration (default: true) */
+	validate?: boolean;
+	/** Check script files exist and are executable (default: false) */
+	checkScripts?: boolean;
+}
+interface LoadHooksResult {
+	/** The loaded hooks configuration (empty if not found or invalid) */
+	config: HooksConfig;
+	/** Validation result */
+	validation: HookValidationResult;
+	/** Whether hooks were found */
+	found: boolean;
+	/** Path to the hooks config file (if found) */
+	configPath?: string;
+	/** Any errors during loading (e.g., TOML parse error) */
+	loadError?: string;
+}
+/**
+* Load hooks configuration from a capability directory
+*
+* Looks for hooks/hooks.toml within the capability directory.
+* Transforms variables and validates the configuration.
+*/
+declare function loadHooksFromCapability(capabilityPath: string, options?: LoadHooksOptions): LoadHooksResult;
+/**
+* Load hooks and create CapabilityHooks metadata
+*/
+declare function loadCapabilityHooks(capabilityName: string, capabilityPath: string, options?: LoadHooksOptions): CapabilityHooks | null;
+/**
+* Check if a capability has hooks defined
+*/
+declare function hasHooks(capabilityPath: string): boolean;
+/**
+* Get the hooks directory path for a capability
+*/
+declare function getHooksDirectory(capabilityPath: string): string;
+/**
+* Get the hooks config file path for a capability
+*/
+declare function getHooksConfigPath(capabilityPath: string): string;
+/**
+* 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)
+*/
+declare function mergeHooksConfigs(capabilityHooks: CapabilityHooks[]): HooksConfig;
+/**
+* Options for deduplication
+*/
+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).
+*/
+declare function mergeAndDeduplicateHooks(capabilityHooks: CapabilityHooks[], options?: DeduplicateOptions): HooksConfig;
+/**
+* Check if a merged config has any hooks defined
+*/
+declare function hasAnyHooks(config: HooksConfig): boolean;
+/**
+* Count total number of hook definitions across all events
+*/
+declare function countHooks(config: HooksConfig): number;
+/**
+* Get all events that have hooks defined
+*/
+declare function getEventsWithHooks(config: HooksConfig): HookEvent[];
 /**
 * Get enabled capabilities for the active profile
 * Includes both profile-specific and always-enabled capabilities
@@ -677,6 +995,18 @@ declare function loadProviderConfig(): Promise<ProviderConfig>;
 declare function writeProviderConfig(config: ProviderConfig): Promise<void>;
 declare function parseProviderFlag(flag: string): Provider[];
 /**
+* Add a capability source to [capabilities.sources]
+*/
+declare function patchAddCapabilitySource(name: string, source: CapabilitySourceConfig): Promise<void>;
+/**
+* Add an MCP server configuration
+*/
+declare function patchAddMcp(name: string, config: McpConfig): Promise<void>;
+/**
+* Add a capability to a profile's capabilities array
+*/
+declare function patchAddToProfile(profileName: string, capabilityName: string): Promise<void>;
+/**
 * Resources provided by a single capability
 */
 interface CapabilityResources {
@@ -868,9 +1198,15 @@ declare function generateClaudeTemplate(): string;
 */
 declare function generateInstructionsTemplate(): string;
 /**
+* Template for OMNI.md - the user's project instructions file.
+* This is the single source of truth that gets transformed into
+* provider-specific files (CLAUDE.md, AGENTS.md, etc.) during sync.
+*/
+declare function generateOmniMdTemplate(): string;
+/**
 * Debug logger that writes to stdout when OMNIDEV_DEBUG=1
 */
 declare function debug(message: string, data?: unknown): void;
 declare const version = "0.1.0";
 declare function getVersion(): string;
-export { writeRules, writeProviderConfig, writeMcpJson, writeEnabledProviders, writeConfig, writeActiveProfileState, version, validateEnv, syncMcpJson, syncAgentConfiguration, sourceToGitUrl, setProfile, setActiveProfile, saveManifest, saveLockFile, resolveEnabledCapabilities, readMcpJson, readEnabledProviders, readActiveProfileState, parseSourceConfig, parseProviderFlag, parseOmniConfig, parseCapabilityConfig, loadSubagents, loadSkills, loadRules, loadProviderConfig, loadProfileConfig, loadManifest, loadLockFile, loadEnvironment, loadDocs, loadConfig, loadCommands, loadCapabilityConfig, loadCapability, loadBaseConfig, isSecretEnvVar, isProviderEnabled, installCapabilityDependencies, getVersion, getSourceCapabilityPath, getLockFilePath, getEnabledCapabilities, getActiveProviders, getActiveProfile, generateInstructionsTemplate, generateClaudeTemplate, generateAgentsTemplate, fetchCapabilitySource, fetchAllCapabilitySources, enableProvider, enableCapability, discoverCapabilities, disableProvider, disableCapability, debug, clearActiveProfileState, cleanupStaleResources, checkForUpdates, buildSyncBundle, buildRouteMap, buildManifestFromCapabilities, buildCommand, buildCapabilityRegistry, SyncResult, SyncOptions, SyncConfig, SyncBundle, SubagentPermissionMode, SubagentModel, SubagentHooks, SubagentHookConfig, SubagentExport, Subagent, SourceUpdateInfo, SkillExport, Skill, Rule, ResourceManifest, ProvidersState, ProviderSyncResult, ProviderManifest, ProviderInitResult, ProviderId, ProviderContext, ProviderConfig, ProviderAdapter, Provider, ProfileConfig, OmniConfig, McpTransport, McpToolSchema, McpServerStdioConfig, McpServerSseConfig, McpServerHttpConfig, McpServerConfig, McpJsonConfig, McpConfig, LoadedCapability, GitCapabilitySourceConfig, FileContent, FetchResult, EnvDeclaration, DocExport, Doc, DiscoveredContent, CommandExport, Command, CliConfig, CleanupResult, CapabilitySourceType, CapabilitySourceConfig, CapabilitySource, CapabilityResources, CapabilityRegistry, CapabilityMetadata, CapabilityLockEntry, CapabilityExports, CapabilityExport, CapabilityConfig, CapabilitiesLockFile, CapabilitiesConfig };
+export { writeRules, writeProviderConfig, writeMcpJson, writeEnabledProviders, writeConfig, writeActiveProfileState, version, validateHooksConfig, validateHook, validateEnv, transformToOmnidev, transformToClaude, transformHooksConfig, syncMcpJson, syncAgentConfiguration, sourceToGitUrl, setProfile, setActiveProfile, saveManifest, saveLockFile, resolveEnabledCapabilities, readMcpJson, readEnabledProviders, readActiveProfileState, patchAddToProfile, patchAddMcp, patchAddCapabilitySource, parseSourceConfig, parseProviderFlag, parseOmniConfig, parseCapabilityConfig, mergeHooksConfigs, mergeAndDeduplicateHooks, loadSubagents, loadSkills, loadRules, loadProviderConfig, loadProfileConfig, loadManifest, loadLockFile, loadHooksFromCapability, loadEnvironment, loadDocs, loadConfig, loadCommands, loadCapabilityHooks, loadCapabilityConfig, loadCapability, loadBaseConfig, isValidMatcherPattern, isSecretEnvVar, isProviderEnabled, isPromptHookEvent, isMatcherEvent, isHookType, isHookPrompt, isHookEvent, isHookCommand, installCapabilityDependencies, hasHooks, hasAnyHooks, getVersion, getSourceCapabilityPath, getLockFilePath, getHooksDirectory, getHooksConfigPath, getEventsWithHooks, getEnabledCapabilities, getActiveProviders, getActiveProfile, generateOmniMdTemplate, generateInstructionsTemplate, generateClaudeTemplate, generateAgentsTemplate, findDuplicateCommands, fetchCapabilitySource, fetchAllCapabilitySources, enableProvider, enableCapability, discoverCapabilities, disableProvider, disableCapability, debug, createEmptyValidationResult, createEmptyHooksConfig, countHooks, containsOmnidevVariables, containsClaudeVariables, clearActiveProfileState, cleanupStaleResources, checkForUpdates, buildSyncBundle, buildRouteMap, buildManifestFromCapabilities, buildCommand, buildCapabilityRegistry, ValidationSeverity, VARIABLE_MAPPINGS, SyncResult, SyncOptions, SyncConfig, SyncBundle, SubagentPermissionMode, SubagentModel, SubagentHooks, SubagentHookConfig, SubagentExport, Subagent, SourceUpdateInfo, SkillExport, Skill, SessionStartMatcher, SESSION_START_MATCHERS, Rule, ResourceManifest, ProvidersState, ProviderSyncResult, ProviderManifest, ProviderInitResult, ProviderId, ProviderContext, ProviderConfig, ProviderAdapter, Provider, PromptHookEvent, ProfileConfig, PreCompactMatcher, PROMPT_HOOK_EVENTS, PRE_COMPACT_MATCHERS, OmnidevVariable, OmniConfig, NotificationMatcher, NOTIFICATION_MATCHERS, McpTransport, McpToolSchema, McpServerStdioConfig, McpServerSseConfig, McpServerHttpConfig, McpServerConfig, McpJsonConfig, McpConfig, MatcherEvent, MATCHER_EVENTS, LoadedCapability, LoadHooksResult, LoadHooksOptions, HooksDoctorResult, HooksDoctorCheck, HooksConfig, HookValidationResult, HookValidationIssue, HookValidationCode, HookType, HookPrompt, HookMatcher, HookEvent, HookCommand, Hook, HOOK_TYPES, HOOK_EVENTS, HOOKS_DIRECTORY, HOOKS_CONFIG_FILENAME, GitCapabilitySourceConfig, FileContent, FetchResult, EnvDeclaration, DoctorCheckStatus, DocExport, Doc, DiscoveredContent, DeduplicateOptions, DEFAULT_PROMPT_TIMEOUT, DEFAULT_COMMAND_TIMEOUT, CommandExport, Command, CliConfig, CleanupResult, ClaudeVariable, CapabilitySourceType, CapabilitySourceConfig, CapabilitySource, CapabilityResources, CapabilityRegistry, CapabilityMetadata, CapabilityLockEntry, CapabilityHooks, CapabilityExports, CapabilityExport, CapabilityConfig, CapabilitiesLockFile, CapabilitiesConfig, COMMON_TOOL_MATCHERS };