hooks

package
v0.3.18 Latest Latest
Warning

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

Go to latest
Published: Jul 17, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package hooks provides a system for executing scripts on task events.

Index

Constants

View Source
const (
	EventTaskBlocked  = "task.blocked"
	EventTaskDone     = "task.done"
	EventTaskFailed   = "task.failed"
	EventTaskStarted  = "task.started"
	EventAuthRequired = "task.auth_required" // Executor session needs re-authentication
)

Event types for hooks

View Source
const ActionTimeout = 60 * time.Second

ActionTimeout bounds how long a user-invoked action may run. Actions are synchronous (their output is shown to the user), so this is more generous than the fire-and-forget hook timeout.

View Source
const ManifestName = "plugin.yaml"

ManifestName is the file every plugin directory must contain to be loaded.

Variables

This section is empty.

Functions

func ActionEnv added in v0.3.18

func ActionEnv(p Plugin, task *db.Task) []string

ActionEnv builds the environment for a plugin action. task may be nil when an action is invoked without a task in context; the TASK_* vars are then omitted.

func DefaultHooksDir

func DefaultHooksDir() string

DefaultHooksDir returns the default hooks directory path.

func DefaultPluginsDir added in v0.3.18

func DefaultPluginsDir() string

DefaultPluginsDir returns the plugins directory path. The TY_PLUGINS_DIR environment variable overrides the default (~/.config/task/plugins), which is handy for relocating plugins and for test isolation.

func EnsureHooksDir

func EnsureHooksDir() (string, error)

EnsureHooksDir creates the hooks directory if it doesn't exist.

func FindAction added in v0.3.18

func FindAction(plugins []Plugin, pluginName, actionID string) (Plugin, Action, error)

FindAction locates a plugin and action by name/id across the given plugins.

func PluginWorkflowDirs added in v0.3.18

func PluginWorkflowDirs(pluginsDir string) []string

PluginWorkflowDirs returns the workflows/ subdir of every installed plugin that actually ships one. The pipeline registry feeds these into its workflow search path, so an installed plugin's workflows become resolvable by `ty pipeline -d`.

func RunAction added in v0.3.18

func RunAction(ctx context.Context, p Plugin, a Action, task *db.Task) ([]byte, error)

RunAction runs a plugin action to completion and returns its combined output. It is synchronous by design: actions are user-triggered and their result is surfaced back to the user (CLI stdout, a TUI banner, etc.).

Types

type Action added in v0.3.18

type Action struct {
	ID      string `yaml:"id"`      // stable identifier, unique within the plugin
	Label   string `yaml:"label"`   // human-facing label; defaults to ID if empty
	Command string `yaml:"command"` // script path, relative to the plugin dir
}

Action is a user-triggered plugin command.

func (Action) DisplayLabel added in v0.3.18

func (a Action) DisplayLabel() string

DisplayLabel returns the label, falling back to the ID.

type Plugin added in v0.3.18

type Plugin struct {
	Name        string `yaml:"name"`
	Version     string `yaml:"version"`
	Description string `yaml:"description"`
	// Hooks maps a task event name (e.g. "task.done") to a script path,
	// resolved relative to the plugin directory. Hooks fire automatically.
	Hooks map[string]string `yaml:"hooks"`
	// Actions are user-invoked commands (from `ty plugins run`, the detail-view
	// picker, or the command palette), each backed by a script in the plugin dir.
	Actions []Action `yaml:"actions"`

	// Dir is the absolute path to the plugin directory (not from the manifest).
	Dir string `yaml:"-"`
	// Workflows holds the names (filename stems) of the workflow definitions this
	// plugin ships in its workflows/ subdir. Discovered by convention at load time,
	// not declared in the manifest — a plugin is workflow cargo the moment it has a
	// workflows/*.yaml. Populated for display; the definitions themselves are loaded
	// by the pipeline registry via PluginWorkflowDirs.
	Workflows []string `yaml:"-"`
}

Plugin is a self-contained, droppable unit that reacts to task events.

A plugin is a directory under the plugins dir (default ~/.config/task/plugins/<name>/) containing a plugin.yaml manifest and the scripts it references. Unlike the legacy single-script hooks dir — where one file per event means two integrations collide — any number of plugins may each declare a handler for the same event, and all of them run.

func LoadPlugins added in v0.3.18

func LoadPlugins(pluginsDir string) (plugins []Plugin, warnings []string)

LoadPlugins discovers and validates every plugin under pluginsDir.

It is intentionally forgiving: a malformed or incomplete plugin is skipped (and reported via the returned warnings) rather than failing the whole load, so one bad community plugin can't break a user's task pipeline. A missing plugins dir is not an error — it just yields no plugins.

func (Plugin) Action added in v0.3.18

func (p Plugin) Action(id string) (Action, bool)

Action returns the action with the given ID.

func (Plugin) ScriptFor added in v0.3.18

func (p Plugin) ScriptFor(event string) (string, bool)

ScriptFor returns the absolute path to the script handling event, and whether the plugin handles that event at all.

func (Plugin) WorkflowsDir added in v0.3.18

func (p Plugin) WorkflowsDir() string

WorkflowsDir returns the plugin's workflows subdir, whether or not it exists.

type Runner

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

Runner executes hooks for task events.

func New

func New(hooksDir string) *Runner

New creates a new hook runner. hooksDir is typically ~/.config/task/hooks/

func NewSilent

func NewSilent(hooksDir string) *Runner

NewSilent creates a hook runner without logging.

func (*Runner) OnStatusChange

func (r *Runner) OnStatusChange(task *db.Task, newStatus, message string)

OnStatusChange triggers appropriate hooks based on status transition.

func (*Runner) Plugins added in v0.3.18

func (r *Runner) Plugins() []Plugin

Plugins returns the loaded plugins (read-only view for inspection/CLI).

func (*Runner) Run

func (r *Runner) Run(event string, task *db.Task, message string)

Run executes every hook registered for the given event: the legacy single-script hook in hooksDir (named after the event), plus the matching hook from each loaded plugin. All run concurrently in the background.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL