Documentation
¶
Overview ¶
Package profile defines how to execute commands against sets of files.
It provides support for hooks (pre/post execution commands), plugins (ad-hoc commands), and source filtering to determine which files should be observed by file watchers.
It can also be used to define UI overrides for when the profile is matched.
Index ¶
- Constants
- Variables
- func RenderLib() cel.EnvOption
- type Executor
- type HookCommand
- type HookCommandOpt
- type HookOpts
- type Hooks
- type Plugin
- type PluginOpt
- type Profile
- func (p *Profile) Build() error
- func (p *Profile) CompileReload() error
- func (p *Profile) CompileSource() error
- func (p *Profile) Exec(ctx context.Context, dir string) (*execs.Result, error)
- func (p *Profile) GetPlugin(name string) *Plugin
- func (p *Profile) GetPluginKeyBinds() []keys.KeyBind
- func (p *Profile) GetPluginNameByKey(keyCode string) string
- func (p *Profile) MatchFileEvent(filePath string, fsOp fsnotify.Op) (bool, error)
- func (p *Profile) MatchFiles(dirPath string, files []string) (bool, []string)
- func (p *Profile) String() string
- type ProfileOpt
- func WithArgs(args ...string) ProfileOpt
- func WithEnvFrom(envFrom []execs.EnvFromSource) ProfileOpt
- func WithEnvVar(envVar execs.EnvVar) ProfileOpt
- func WithExecutor(executor Executor) ProfileOpt
- func WithExtraArgs(args ...string) ProfileOpt
- func WithHooks(hooks *Hooks) ProfileOpt
- func WithPlugins(plugins map[string]*Plugin) ProfileOpt
- func WithReload(reload string) ProfileOpt
- func WithSource(source string) ProfileOpt
- func WithStatusManager(status StatusManager) ProfileOpt
- type RenderResult
- type RenderStage
- type Status
- type StatusManager
- type UIConfig
Constants ¶
const ( // StageNone indicates no rendering is active. StageNone RenderStage = iota // StageInit is the initial stage of rendering. Not currently implemented. StageInit // StagePreRender is the stage before the main rendering command. StagePreRender // StageRender is the main rendering stage where the command is executed. StageRender // StagePostRender is the stage after the main rendering command. StagePostRender // ResultOK indicates the rendering was successful. ResultOK RenderResult = "OK" // ResultError indicates there was an error during rendering. ResultError RenderResult = "ERROR" // ResultCancel indicates the rendering was canceled. ResultCancel RenderResult = "CANCEL" // ResultNone indicates no rendering result is available. ResultNone RenderResult = "" )
Variables ¶
var ( // ErrHookExecution is returned when hook execution fails. ErrHookExecution = errors.New("hook") // ErrPluginExecution is returned when plugin execution fails. ErrPluginExecution = errors.New("plugin") )
Functions ¶
Types ¶
type Executor ¶ added in v0.24.1
type Executor interface {
Exec(ctx context.Context, dir string) (*execs.Result, error)
ExecWithStdin(ctx context.Context, dir string, stdin []byte) (*execs.Result, error)
String() string
}
Executor executes a profile's commands.
type HookCommand ¶
type HookCommand struct {
// Command contains the command execution configuration.
Command execs.Command `json:",inline"`
// contains filtered or unexported fields
}
HookCommand represents a single hook command to execute.
func MustNewHookCommand ¶ added in v0.14.0
func MustNewHookCommand(command string, opts ...HookCommandOpt) *HookCommand
MustNewHookCommand creates a new hook command and panics if there's an error.
func NewHookCommand ¶
func NewHookCommand(command string, opts ...HookCommandOpt) (*HookCommand, error)
NewHookCommand creates a new hook command with the given command and options.
func (*HookCommand) Build ¶ added in v0.14.0
func (hc *HookCommand) Build() error
func (*HookCommand) ExecWithStdin ¶ added in v0.15.0
type HookCommandOpt ¶ added in v0.14.0
type HookCommandOpt func(*HookCommand)
HookCommandOpt is a functional option for configuring a HookCommand.
func WithHookArgs ¶ added in v0.14.0
func WithHookArgs(args ...string) HookCommandOpt
WithHookArgs sets the command arguments for the hook command.
func WithHookCommandExecutor ¶ added in v0.24.1
func WithHookCommandExecutor(executor Executor) HookCommandOpt
WithHookCommandExecutor sets the Executor for the hook command.
func WithHookEnvFrom ¶ added in v0.14.0
func WithHookEnvFrom(envFrom []execs.EnvFromSource) HookCommandOpt
WithHookEnvFrom sets the envFrom sources for the hook command.
func WithHookEnvVar ¶ added in v0.14.0
func WithHookEnvVar(envVar execs.EnvVar) HookCommandOpt
WithHookEnvVar sets a single environment variable for the hook command.
func WithHookExecutor ¶ added in v0.24.1
func WithHookExecutor(executor Executor) HookCommandOpt
WithHookExecutor sets the Executor for the hook command.
type HookOpts ¶
type HookOpts func(*Hooks)
HookOpts is a functional option for configuring Hooks.
func WithPostRender ¶
func WithPostRender(hooks ...*HookCommand) HookOpts
WithPostRender adds post-render hooks.
func WithPreRender ¶
func WithPreRender(hooks ...*HookCommand) HookOpts
WithPreRender adds pre-render hooks.
type Hooks ¶
type Hooks struct {
// Init contains commands to run during initialization.
Init []*HookCommand `json:"init,omitempty" jsonschema:"title=Init Hooks"`
// PreRender contains commands to run before rendering.
PreRender []*HookCommand `json:"preRender,omitempty" jsonschema:"title=Pre Render Hooks"`
// PostRender contains commands to run after rendering.
PostRender []*HookCommand `json:"postRender,omitempty" jsonschema:"title=Post Render Hooks"`
// contains filtered or unexported fields
}
Hooks represents the different types of hooks that can be executed.
func MustNewHooks ¶ added in v0.14.0
MustNewHooks creates a new Hooks instance and panics if there's an error.
type Plugin ¶
type Plugin struct {
// Command contains the command execution configuration.
Command execs.Command `json:",inline"`
// Description provides a description of what the plugin does.
Description string `json:"description" jsonschema:"title=Description"`
// Keys defines the key bindings that trigger this plugin.
Keys []keys.Key `json:"keys,omitempty" jsonschema:"title=Keys"`
// contains filtered or unexported fields
}
Plugin represents a command plugin that can be executed on demand with keybinds.
func MustNewPlugin ¶ added in v0.14.0
MustNewPlugin creates a new plugin and panics if there's an error.
type PluginOpt ¶
type PluginOpt func(*Plugin)
PluginOpt is a functional option for configuring a Plugin.
func WithPluginArgs ¶
WithPluginArgs sets the command arguments for the plugin.
func WithPluginEnvFrom ¶ added in v0.14.0
func WithPluginEnvFrom(envFrom []execs.EnvFromSource) PluginOpt
WithPluginEnvFrom sets the envFrom sources for the plugin.
func WithPluginEnvVar ¶ added in v0.14.0
WithPluginEnvVar sets a single environment variable for the plugin.
func WithPluginExecutor ¶ added in v0.24.1
WithPluginExecutor sets the Executor for the plugin.
func WithPluginKeys ¶
WithPluginKeys sets the keybinds for the plugin.
type Profile ¶
type Profile struct {
// Hooks contains lifecycle hooks for the profile.
Hooks *Hooks `json:"hooks,omitempty" jsonschema:"title=Hooks"`
// UI contains UI configuration overrides for this profile.
UI *UIConfig `json:"ui,omitempty" jsonschema:"title=UI Overrides"`
// Plugins contains a map of plugin names to Plugin configurations.
Plugins map[string]*Plugin `json:"plugins,omitempty" jsonschema:"title=Plugins"`
// Source is a CEL expression that determines which files should be watched by
// this profile, when file watching is enabled. The expression has access to:
// - `files` (list<string>): All file paths in directory
// - `dir` (string): The directory path being processed
//
// Source CEL expressions must return a list of files:
// - `files.filter(f, pathExt(f) in [".yaml", ".yml"])` - returns all YAML files
// - `files.filter(f, pathBase(f) in ["Chart.yaml", "values.yaml"])` - returns Chart and values files
// - `files.filter(f, pathBase(f) == "Chart.yaml")` - returns files named Chart.yaml
// - `files.filter(f, !pathBase(f).matches(".*test.*"))` - returns non-test files
// - `files.filter(f, pathBase(f) == "Chart.yaml" && yamlPath(f, "$.apiVersion") == "v2")` - returns charts with apiVersion v2
// - `files` - unfiltered list means all files should be processed
// - `[]` - empty list means no files should be processed
//
// If no Source expression is provided, the profile will match all files by default.
Source string `json:"source,omitempty" jsonschema:"title=Source"`
// Reload contains a CEL expression that is evaluated on automated reload
// events (e.g. from watch). If the expression returns true, the reload will proceed.
// If it returns false, the reload will be skipped. The expression has access to:
// - `file` (string): The file path that triggered the event
// - `fs.event` (int): The file event type, at least one of `fs.CREATE`, `fs.WRITE`, `fs.REMOVE`, `fs.RENAME`, `fs.CHMOD`
// - `render.stage` (int): The current render stage, one of `render.STAGE_NONE`, `render.STAGE_PRE_RENDER`, `render.STAGE_RENDER`, `render.STAGE_POST_RENDER`
// - `render.result` (string): The result of the last render operation, one of `render.RESULT_OK`, `render.RESULT_ERROR`, `render.RESULT_CANCEL`
//
// Reload CEL expressions must return a boolean value:
// - `pathBase(file) != "kustomization.yaml"` - skip reload for kustomization.yaml files
// - `fs.event.has(fs.WRITE, fs.RENAME)` - reload for write or rename events
// - `render.result != render.RESULT_CANCEL` - skip reload if the last render was canceled
// - `render.stage < render.STAGE_RENDER` - only reload if the main render stage has not started
//
// If no Reload expression is provided, the profile will always reload on any events.
Reload string `json:"reload,omitempty" jsonschema:"title=Reload"`
// Command contains the command execution configuration.
Command execs.Command `json:",inline"`
// ExtraArgs contains extra arguments that can be overridden from the CLI.
// They are appended to the Args of the Command.
ExtraArgs []string `json:"extraArgs,omitempty" jsonschema:"title=Optional Arguments" yaml:"extraArgs,flow,omitempty"`
// contains filtered or unexported fields
}
Profile represents a command profile.
func MustNew ¶
func MustNew(command string, opts ...ProfileOpt) *Profile
MustNew creates a new profile and panics if there's an error.
func New ¶
func New(command string, opts ...ProfileOpt) (*Profile, error)
New creates a new profile with the given command and options.
func (*Profile) CompileReload ¶ added in v0.24.0
CompileReload compiles the profile's reload expression into a CEL program.
func (*Profile) CompileSource ¶
CompileSource compiles the profile's source expression into a CEL program.
func (*Profile) Exec ¶
Exec runs the profile in the specified directory. Returns ExecResult with the command output and any post-render hooks.
func (*Profile) GetPluginKeyBinds ¶
func (*Profile) GetPluginNameByKey ¶
GetPluginNameByKey returns the name of the first plugin that matches the given key code.
func (*Profile) MatchFileEvent ¶ added in v0.24.0
MatchFileEvent evaluates the profile's reload expression against a file system event. Returns true if the reload should proceed, false if it should be skipped. If no reload expression is configured, it always returns true.
func (*Profile) MatchFiles ¶
MatchFiles checks if the profile's source expression matches files in a directory. The CEL expression must return a list of strings representing files. An empty list means no files should be processed with this profile.
Returns (matches, files) where: - matches: true if the profile should be used (non-empty file list) - files: specific files that were matched.
type ProfileOpt ¶
type ProfileOpt func(*Profile)
ProfileOpt is a functional option for configuring a Profile.
func WithArgs ¶
func WithArgs(args ...string) ProfileOpt
WithArgs sets the command arguments for the profile.
func WithEnvFrom ¶ added in v0.14.0
func WithEnvFrom(envFrom []execs.EnvFromSource) ProfileOpt
WithEnvFrom sets the envFrom sources for the profile.
func WithEnvVar ¶ added in v0.14.0
func WithEnvVar(envVar execs.EnvVar) ProfileOpt
WithEnvVar sets a single environment variable for the profile. Call multiple times to set multiple environment variables.
func WithExecutor ¶ added in v0.24.1
func WithExecutor(executor Executor) ProfileOpt
WithExecutor sets the Executor for the profile.
func WithExtraArgs ¶ added in v0.21.0
func WithExtraArgs(args ...string) ProfileOpt
WithExtraArgs sets extra command arguments for the profile. These arguments can be overridden from the CLI.
func WithPlugins ¶
func WithPlugins(plugins map[string]*Plugin) ProfileOpt
WithPlugins sets the plugins for the profile.
func WithReload ¶ added in v0.24.0
func WithReload(reload string) ProfileOpt
WithReload sets the reload expression for the profile.
func WithSource ¶
func WithSource(source string) ProfileOpt
WithSource sets the source filtering expression for the profile.
func WithStatusManager ¶ added in v0.24.1
func WithStatusManager(status StatusManager) ProfileOpt
WithStatusManager sets the StatusManager for the profile.
type RenderResult ¶ added in v0.24.0
type RenderResult string
RenderResult represents the result of a rendering operation.
type RenderStage ¶ added in v0.24.0
type RenderStage int
RenderStage represents the different stages of rendering. It is used to track the progress of rendering operations.
type Status ¶ added in v0.24.0
type Status struct {
// contains filtered or unexported fields
}
func (*Status) RenderMap ¶ added in v0.24.0
RenderMap returns a map of render values exposed to CEL.
func (*Status) SetResult ¶ added in v0.24.0
func (s *Status) SetResult(result RenderResult)
func (*Status) SetStage ¶ added in v0.24.0
func (s *Status) SetStage(stage RenderStage)
type StatusManager ¶ added in v0.24.1
type StatusManager interface {
SetError(ctx context.Context)
SetResult(result RenderResult)
SetStage(stage RenderStage)
RenderMap() map[string]any
}
StatusManager manages the status of a profile.
type UIConfig ¶
type UIConfig struct {
// Compact enables compact display mode with reduced spacing.
Compact *bool `json:"compact,omitempty" jsonschema:"title=Enable Compact Display"`
// WordWrap enables automatic word wrapping for long text.
WordWrap *bool `json:"wordWrap,omitempty" jsonschema:"title=Enable Word Wrap"`
// LineNumbers enables line numbers in the display.
LineNumbers *bool `json:"lineNumbers,omitempty" jsonschema:"title=Enable Line Numbers"`
// Theme specifies the theme name to use. This can be a custom theme added under `themes`,
// or a theme from the Chroma Style Gallery: https://xyproto.github.io/splash/docs/
Theme string `json:"theme,omitempty" jsonschema:"title=Theme Name"`
}
UIConfig defines UI config overrides for a profile.