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 ¶
- Constants
- func BuildCaptureFragment(events []string) map[string]interface{}
- func Checksum(events map[string]interface{}) string
- func SettingsFilePath(scope Scope) (string, error)
- func SettingsFilePathAt(scope Scope, root string) (string, error)
- func TrackerFilePath(scope Scope) (string, error)
- type Scope
- type Settings
- type TrackedHook
- type Tracker
Constants ¶
const CaptureHookCommand = "promptvm sync run"
CaptureHookCommand is the command every capture hook event invokes. The command is identical across events and platforms; `sync run` reads the event name from stdin and self-detaches, so non-blocking behavior does not depend on Claude Code's `async` field or a `setsid` binary (HOOK-3 / DX-6).
const CaptureHookSlug = "promptvm-context-sync"
CaptureHookSlug is the tracker/_slug identifier for the context-sync capture hook. It scopes MergeHook/RemoveHook so re-running `sync init` is idempotent and never collides with marketplace-installed hooks.
Variables ¶
This section is empty.
Functions ¶
func BuildCaptureFragment ¶ added in v0.6.0
BuildCaptureFragment builds a Claude Code settings.json "hooks" fragment for the given events. Each event gets a single command-hook matcher group tagged with CaptureHookSlug so it is trackable and removable. The fragment is shaped for the settings "hooks" key (HOOK-7), not PromptVM's internal "events" key.
SessionStart is reconcile-only and stdout-silent (HOOK-4); it carries no matcher so it fires on all sources (startup|resume|clear|compact).
func Checksum ¶
Checksum computes sha256 of the JSON-encoded event entries for a hook. Keys are sorted for deterministic output.
func SettingsFilePath ¶
SettingsFilePath returns the path to the Claude Code settings.json for the given scope, anchoring project/local scopes at the current working directory.
func SettingsFilePathAt ¶ added in v0.7.0
SettingsFilePathAt returns the settings.json path for the given scope, anchoring project/local scopes at root. When root is "" it falls back to the current working directory. Callers that know the git repo root (e.g. `sync init`) MUST pass it so the settings file lands next to the manifest at the repo root rather than wherever the command happened to be invoked from.
func TrackerFilePath ¶
TrackerFilePath returns path to the sidecar file for the given scope.
Types ¶
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 ¶
ReadSettings reads and parses the settings file. Returns empty settings if file doesn't exist.
func (*Settings) CaptureEventsInstalled ¶ added in v0.6.0
CaptureEventsInstalled returns the capture-hook event names currently present in the settings, identified by the CaptureHookSlug tag.
func (*Settings) MergeHook ¶
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 ¶
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.
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 ¶
LoadTracker reads the sidecar file. Returns empty tracker if not found.
func LoadTrackerFromPath ¶
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 ¶
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.
Source Files