hooks

Documentation

Overview

Package hooks manages Claude Code settings.json files and the PromptVM hook tracker sidecar (.promptvm-hooks.json). It provides read/write helpers used by the hooks CLI commands.

The core types and functions are split across:

• settings.go: Settings, Scope, ReadSettings, MergeHook, RemoveHook, Write, Checksum
• tracker.go: Tracker, TrackedHook, LoadTracker, TrackerFilePath

Index

• func Checksum(events map[string]interface{}) string
• func SettingsFilePath(scope Scope) (string, error)
• func TrackerFilePath(scope Scope) (string, error)
• type Scope
• type Settings
  • func ReadSettings(path string) (*Settings, error)
  • func (s *Settings) Hooks() map[string]interface{}
  • func (s *Settings) MergeHook(fragment map[string]interface{}, slug string, force bool)
  • func (s *Settings) RemoveHook(tracker *Tracker, slug string) bool
  • func (s *Settings) Write(path string) error
• type TrackedHook
• type Tracker
  • func LoadTracker(scope Scope) (*Tracker, error)
  • func LoadTrackerFromPath(path string) (*Tracker, error)
  • func (t *Tracker) Add(hook TrackedHook)
  • func (t *Tracker) EventsForSlug(slug string) []string
  • func (t *Tracker) Get(slug string) *TrackedHook
  • func (t *Tracker) Remove(slug string) bool
  • func (t *Tracker) Save() error

Functions

func Checksum

func Checksum(events map[string]interface{}) string

Checksum computes sha256 of the JSON-encoded event entries for a hook. Keys are sorted for deterministic output.

func SettingsFilePath

func SettingsFilePath(scope Scope) (string, error)

SettingsFilePath returns the path to the Claude Code settings.json for the given scope.

func TrackerFilePath

func TrackerFilePath(scope Scope) (string, error)

TrackerFilePath returns path to the sidecar file for the given scope.

Types

type Scope

type Scope string

Scope determines which settings file to target.

const (
	ScopeProject Scope = "project"
	ScopeUser    Scope = "user"
)

type Settings

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

Settings represents a Claude Code settings.json file. We use map[string]interface{} to preserve unknown keys.

func ReadSettings

func ReadSettings(path string) (*Settings, error)

ReadSettings reads and parses the settings file. Returns empty settings if file doesn't exist.

func (*Settings) Hooks

func (s *Settings) Hooks() map[string]interface{}

Hooks returns the hooks map from settings, or empty map if none.

func (*Settings) MergeHook

func (s *Settings) MergeHook(fragment map[string]interface{}, slug string, force bool)

MergeHook adds a hook's event entries to the settings. For each event:

• If event doesn't exist, create it with the matchers.
• If event exists, append matchers (dedup by checksum).
• If force, replace any existing entries from the same slug first.

The fragment is a map of event names to arrays of matcher objects. Each matcher object may contain a "_slug" field used for identification.

func (*Settings) RemoveHook

func (s *Settings) RemoveHook(tracker *Tracker, slug string) bool

RemoveHook removes all entries associated with a slug (using the tracker to identify them). It removes matcher entries whose "_slug" field matches the given slug and cleans up empty arrays. Returns true if any entries were removed.

func (*Settings) Write

func (s *Settings) Write(path string) error

Write atomically writes the settings file (tmp + rename pattern).

type TrackedHook

type TrackedHook struct {
	Slug        string   `json:"slug"`
	Version     int      `json:"version"`
	SourceURL   string   `json:"source_url,omitempty"`
	InstalledAt string   `json:"installed_at"`
	Events      []string `json:"events"`
	Checksum    string   `json:"checksum"`
}

TrackedHook represents a managed hook entry.

type Tracker

type Tracker struct {
	Hooks []TrackedHook `json:"hooks"`
	// contains filtered or unexported fields
}

Tracker manages the sidecar file.

func LoadTracker

func LoadTracker(scope Scope) (*Tracker, error)

LoadTracker reads the sidecar file. Returns empty tracker if not found.

func LoadTrackerFromPath

func LoadTrackerFromPath(path string) (*Tracker, error)

LoadTrackerFromPath reads a tracker from a specific file path.

func (*Tracker) Add

func (t *Tracker) Add(hook TrackedHook)

Add adds or updates a tracked hook entry. If a hook with the same slug already exists, it is replaced.

func (*Tracker) EventsForSlug

func (t *Tracker) EventsForSlug(slug string) []string

EventsForSlug returns the event keys associated with a slug.

func (*Tracker) Get

func (t *Tracker) Get(slug string) *TrackedHook

Get returns a tracked hook by slug, or nil.

func (*Tracker) Remove

func (t *Tracker) Remove(slug string) bool

Remove removes a tracked hook by slug. Returns true if found.

func (*Tracker) Save

func (t *Tracker) Save() error

Save atomically writes the tracker file.