core

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 18, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package core provides the canonical types for hook configuration that can be converted to/from various AI assistant formats.

Index

Constants

View Source 
const DefaultFileMode fs.FileMode = 0600

DefaultFileMode is the default permission mode for configuration files. This can be used by adapters or overridden with WriteFileWithMode.

Variables

View Source 
var (
	// ErrNoCommandOrPrompt is returned when a hook has neither command nor prompt.
	ErrNoCommandOrPrompt = errors.New("hook must have either command or prompt")

	// ErrBothCommandAndPrompt is returned when a hook has both command and prompt.
	ErrBothCommandAndPrompt = errors.New("hook cannot have both command and prompt")

	// ErrUnsupportedEvent is returned when an event is not supported by a tool.
	ErrUnsupportedEvent = errors.New("event not supported by this tool")

	// ErrInvalidMatcher is returned when a matcher pattern is invalid.
	ErrInvalidMatcher = errors.New("invalid matcher pattern")

	// ErrEmptyConfig is returned when configuration is empty.
	ErrEmptyConfig = errors.New("configuration is empty")
)

Common errors for hooks configuration.

View Source 
var DefaultRegistry = NewAdapterRegistry()

DefaultRegistry is the global adapter registry.

Functions

func Convert 

func Convert(data []byte, from, to string) ([]byte, error)

Convert converts between formats using the default registry.

func Register 

func Register(adapter Adapter)

Register adds an adapter to the default registry.

Types

type Adapter 

type Adapter interface {
	// Name returns the name of the tool/format (e.g., "claude", "cursor").
	Name() string

	// DefaultPaths returns the default configuration file paths for this tool.
	DefaultPaths() []string

	// Parse parses tool-specific data into the canonical Config format.
	Parse(data []byte) (*Config, error)

	// Marshal converts the canonical Config to tool-specific format.
	Marshal(cfg *Config) ([]byte, error)

	// ReadFile reads a tool-specific config file and returns canonical Config.
	ReadFile(path string) (*Config, error)

	// WriteFile writes the canonical Config to a tool-specific file.
	WriteFile(cfg *Config, path string) error

	// SupportedEvents returns the events supported by this tool.
	SupportedEvents() []Event
}

Adapter defines the interface for converting between the canonical Config format and tool-specific formats.

func GetAdapter 

func GetAdapter(name string) (Adapter, bool)

GetAdapter returns an adapter from the default registry.

type AdapterRegistry 

type AdapterRegistry struct {
	// contains filtered or unexported fields
}

AdapterRegistry holds registered adapters for different tools.

func NewAdapterRegistry 

func NewAdapterRegistry() *AdapterRegistry

NewAdapterRegistry creates a new adapter registry.

func (*AdapterRegistry) Convert 

func (r *AdapterRegistry) Convert(data []byte, from, to string) ([]byte, error)

Convert converts a config from one format to another.

func (*AdapterRegistry) Get 

func (r *AdapterRegistry) Get(name string) (Adapter, bool)

Get returns an adapter by name.

func (*AdapterRegistry) Names 

func (r *AdapterRegistry) Names() []string

Names returns the names of all registered adapters.

func (*AdapterRegistry) Register 

func (r *AdapterRegistry) Register(adapter Adapter)

Register adds an adapter to the registry.

type Config 

type Config struct {
	// Version is the configuration version (used by Cursor).
	Version int `json:"version,omitempty"`

	// Hooks maps events to their hook entries.
	Hooks map[Event][]HookEntry `json:"hooks"`

	// DisableAllHooks disables all hooks when true (Claude-specific).
	DisableAllHooks bool `json:"disableAllHooks,omitempty"`

	// AllowManagedHooksOnly restricts to enterprise-managed hooks only (Claude-specific).
	AllowManagedHooksOnly bool `json:"allowManagedHooksOnly,omitempty"`
}

Config represents the canonical hooks configuration that can be converted to/from various AI assistant formats.

func NewConfig 

func NewConfig() *Config

NewConfig creates a new empty hooks Config.

func ReadFile 

func ReadFile(path string) (*Config, error)

ReadFile reads a config from a JSON file.

func (*Config) AddHook 

func (c *Config) AddHook(event Event, hook Hook)

AddHook adds a hook for the specified event.

func (*Config) AddHookWithMatcher 

func (c *Config) AddHookWithMatcher(event Event, matcher string, hook Hook)

AddHookWithMatcher adds a hook with a matcher pattern for the specified event.

func (*Config) Events 

func (c *Config) Events() []Event

Events returns all events that have hooks configured.

func (*Config) FilterByTool 

func (c *Config) FilterByTool(tool string) *Config

FilterByTool returns a new config with only hooks supported by the specified tool.

func (*Config) GetAllHooksForEvent 

func (c *Config) GetAllHooksForEvent(event Event) []Hook

GetAllHooksForEvent returns a flat list of all hooks for an event.

func (*Config) GetHooks 

func (c *Config) GetHooks(event Event) []HookEntry

GetHooks returns all hook entries for an event.

func (*Config) HasHooks 

func (c *Config) HasHooks() bool

HasHooks returns true if any hooks are configured.

func (*Config) HookCount 

func (c *Config) HookCount() int

HookCount returns the total number of hooks across all events.

func (*Config) MarshalJSON 

func (c *Config) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Config) Merge 

func (c *Config) Merge(other *Config)

Merge combines another config into this one. Hooks from the other config are appended to existing hooks.

func (*Config) RemoveHooks 

func (c *Config) RemoveHooks(event Event)

RemoveHooks removes all hooks for an event.

func (*Config) UnmarshalJSON 

func (c *Config) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks if the configuration is valid.

func (*Config) WriteFile 

func (c *Config) WriteFile(path string) error

WriteFile writes the config to a file in JSON format using DefaultFileMode.

func (*Config) WriteFileWithMode 

func (c *Config) WriteFileWithMode(path string, mode fs.FileMode) error

WriteFileWithMode writes the config to a file in JSON format with the specified permission mode.

type ConversionError 

type ConversionError struct {
	From  string
	To    string
	Event Event
	Err   error
}

ConversionError represents an error converting between formats.

func (*ConversionError) Error 

func (e *ConversionError) Error() string

func (*ConversionError) Unwrap 

func (e *ConversionError) Unwrap() error

type Event 

type Event string

Event represents the canonical hook event types. Different tools use different naming conventions, but these map to common concepts. 

const (
	// File operations
	BeforeFileRead  Event = "before_file_read"
	AfterFileRead   Event = "after_file_read"
	BeforeFileWrite Event = "before_file_write"
	AfterFileWrite  Event = "after_file_write"

	// Shell/Command operations
	BeforeCommand Event = "before_command"
	AfterCommand  Event = "after_command"

	// MCP operations
	BeforeMCP Event = "before_mcp"
	AfterMCP  Event = "after_mcp"

	// Prompt/Input operations
	BeforePrompt Event = "before_prompt"

	// Agent lifecycle
	OnStop         Event = "on_stop"
	OnSessionStart Event = "on_session_start"
	OnSessionEnd   Event = "on_session_end"

	// Response events (Cursor-specific)
	AfterResponse Event = "after_response"
	AfterThought  Event = "after_thought"

	// Permission events (Claude-specific)
	OnPermission Event = "on_permission"

	// Other events
	OnNotification Event = "on_notification"
	BeforeCompact  Event = "before_compact"
	OnSubagentStop Event = "on_subagent_stop"

	// Tab/Completion events (Cursor-specific)
	BeforeTabRead Event = "before_tab_read"
	AfterTabEdit  Event = "after_tab_edit"
)

func AllEvents 

func AllEvents() []Event

AllEvents returns all defined canonical events.

func (Event) CanBlock 

func (e Event) CanBlock() bool

CanBlock returns true if hooks for this event can block the action.

func (Event) GetToolSupport 

func (e Event) GetToolSupport() ToolSupport

GetToolSupport returns which tools support the given event.

func (Event) IsAfterEvent 

func (e Event) IsAfterEvent() bool

IsAfterEvent returns true if this is an "after" event for observation.

func (Event) IsBeforeEvent 

func (e Event) IsBeforeEvent() bool

IsBeforeEvent returns true if this is a "before" event that can block actions.

func (Event) String 

func (e Event) String() string

String returns the string representation of the event.

type Hook 

type Hook struct {
	// Type specifies how the hook is executed (command or prompt).
	Type HookType `json:"type"`

	// Command is the shell command to execute (for command type).
	Command string `json:"command,omitempty"`

	// Prompt is the LLM prompt for context-aware decisions (Claude-specific).
	Prompt string `json:"prompt,omitempty"`

	// Timeout in seconds for hook execution.
	Timeout int `json:"timeout,omitempty"`

	// ShowOutput displays hook output in the UI (Windsurf-specific).
	ShowOutput bool `json:"showOutput,omitempty"`

	// WorkingDir is the working directory for command execution.
	WorkingDir string `json:"workingDir,omitempty"`
}

Hook represents a single hook definition that can be triggered by an event.

func NewCommandHook 

func NewCommandHook(command string) Hook

NewCommandHook creates a new command-type hook.

func NewPromptHook 

func NewPromptHook(prompt string) Hook

NewPromptHook creates a new prompt-type hook (Claude-specific).

func (*Hook) IsCommand 

func (h *Hook) IsCommand() bool

IsCommand returns true if this is a command-type hook.

func (*Hook) IsPrompt 

func (h *Hook) IsPrompt() bool

IsPrompt returns true if this is a prompt-type hook (Claude-specific).

func (*Hook) Validate 

func (h *Hook) Validate() error

Validate checks if the hook is valid.

func (Hook) WithShowOutput 

func (h Hook) WithShowOutput(show bool) Hook

WithShowOutput sets whether to show output (Windsurf-specific).

func (Hook) WithTimeout 

func (h Hook) WithTimeout(seconds int) Hook

WithTimeout sets the timeout for a hook.

func (Hook) WithWorkingDir 

func (h Hook) WithWorkingDir(dir string) Hook

WithWorkingDir sets the working directory for command execution.

type HookEntry 

type HookEntry struct {
	// Matcher filters which tools trigger this hook (Claude-specific).
	// Examples: "Bash", "Write", "Edit", "Read", "Bash|Write"
	Matcher string `json:"matcher,omitempty"`

	// Hooks is the list of hooks to execute for this entry.
	Hooks []Hook `json:"hooks"`
}

HookEntry represents a collection of hooks for a specific event, with optional filtering by tool/matcher.

type HookType 

type HookType string

HookType represents the type of hook execution. 

const (
	// HookTypeCommand executes a shell command.
	HookTypeCommand HookType = "command"

	// HookTypePrompt uses an LLM for context-aware decisions (Claude-specific).
	HookTypePrompt HookType = "prompt"
)

type HookValidationError 

type HookValidationError struct {
	Event      Event
	EntryIndex int
	HookIndex  int
	Err        error
}

HookValidationError wraps a validation error with context.

func (*HookValidationError) Error 

func (e *HookValidationError) Error() string

func (*HookValidationError) Unwrap 

func (e *HookValidationError) Unwrap() error

type ParseError 

type ParseError struct {
	Format string
	Path   string
	Err    error
}

ParseError represents an error parsing a configuration file.

func (*ParseError) Error 

func (e *ParseError) Error() string

func (*ParseError) Unwrap 

func (e *ParseError) Unwrap() error

type ToolSupport 

type ToolSupport struct {
	Claude   bool
	Cursor   bool
	Windsurf bool
}

ToolSupport indicates which tools support which events.

type WriteError 

type WriteError struct {
	Format string
	Path   string
	Err    error
}

WriteError represents an error writing a configuration file.

func (*WriteError) Error 

func (e *WriteError) Error() string

func (*WriteError) Unwrap 

func (e *WriteError) Unwrap() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.