actions

Documentation

Index

• Variables
• func CheckArgs(manager, pkg string) []string
• type Action
• type BinaryAction
  • func (a *BinaryAction) Describe() string
  • func (a *BinaryAction) Run(ctx context.Context, dryRun bool) error
• type DirectoryAction
  • func (a *DirectoryAction) Describe() string
  • func (a *DirectoryAction) IsApplied(ctx context.Context) (bool, error)
  • func (a *DirectoryAction) ResolvedDir() string
  • func (a *DirectoryAction) ResolvedTarget() string
  • func (a *DirectoryAction) Run(ctx context.Context, dryRun bool) error
• type FileAction
  • func (a *FileAction) Describe() string
  • func (a *FileAction) IsApplied(ctx context.Context) (bool, error)
  • func (a *FileAction) PermissionsStatus() string
  • func (a *FileAction) ResolvedDir() string
  • func (a *FileAction) ResolvedTarget() string
  • func (a *FileAction) Run(ctx context.Context, dryRun bool) error
• type Idempotent
• type PackageAction
  • func (a *PackageAction) Describe() string
  • func (a *PackageAction) IsApplied(ctx context.Context) (bool, error)
  • func (a *PackageAction) Run(ctx context.Context, dryRun bool) error
• type RunAction
  • func (a *RunAction) Describe() string
  • func (a *RunAction) Run(ctx context.Context, dryRun bool) error
• type ScriptAction
  • func (a *ScriptAction) Describe() string
  • func (a *ScriptAction) Run(ctx context.Context, dryRun bool) error
• type SettingAction
  • func (a *SettingAction) Describe() string
  • func (a *SettingAction) Run(ctx context.Context, dryRun bool) error

Variables

var ErrSkipped = errors.New("skipped")

ErrSkipped is returned by an action's Run method when the action cannot proceed but the failure is not an error (e.g. pulling a file that does not exist on the system). The runner treats this as a skip rather than a failure.

Functions

func CheckArgs

func CheckArgs(manager, pkg string) []string

CheckArgs returns the command to test whether a package is installed. Returns nil when no check is defined for the manager.

Types

type Action

type Action interface {
	// Describe returns a human-readable summary of the action.
	Describe() string
	// Run executes the action. When dryRun is true it only prints what would happen.
	Run(ctx context.Context, dryRun bool) error
}

Action is a single executable step produced from a config item.

type BinaryAction

type BinaryAction struct {
	Name      string // binary name (used to locate within archive)
	Version   string // version string for display only
	SourceURL string // resolved for current OS
	InstallTo string // destination directory (may contain ~ / $VARS)
}

BinaryAction downloads a pre-built binary from a URL, optionally extracts it from a tar.gz or zip archive, and installs it to a target directory.

Idempotency: BinaryAction does not implement Idempotent. Use skip_if to guard against redundant downloads (e.g. skip_if: test -f ~/.local/bin/nvim). The verify field is recommended for version-aware checks.

func (*BinaryAction) Describe

func (a *BinaryAction) Describe() string

func (*BinaryAction) Run

func (a *BinaryAction) Run(ctx context.Context, dryRun bool) error

type DirectoryAction

type DirectoryAction struct {
	Source      string // repo-side directory path
	Destination string // system-side parent directory (may contain ~ / $VARS)
	Direction   string // "push" | "pull" | "sync"
	Link        bool
	Permissions string // applied to every file written (optional)
}

DirectoryAction manages a whole directory tree between the repo and the system.

Supported directions:

• push (default): copy repo directory → system directory.
• pull: copy system directory → repo directory.
• sync: push if system dir missing; pull if repo dir missing; push if both present (full per-file directory sync is not yet implemented — use file items for fine-grained sync control).

Link=true creates a symlink at the system destination pointing to the repo directory (equivalent to permanent push, always in sync).

Idempotency: DirectoryAction implements Idempotent for link items. It verifies that the symlink exists and resolves to the correct source path.

func (*DirectoryAction) Describe

func (a *DirectoryAction) Describe() string

func (*DirectoryAction) IsApplied

func (a *DirectoryAction) IsApplied(ctx context.Context) (bool, error)

IsApplied implements Idempotent for link items.

func (*DirectoryAction) ResolvedDir

func (a *DirectoryAction) ResolvedDir() string

ResolvedDir returns the parent directory of the resolved target.

func (*DirectoryAction) ResolvedTarget

func (a *DirectoryAction) ResolvedTarget() string

ResolvedTarget returns the fully expanded destination directory path. If the destination's basename matches the source basename or has a file extension, it is treated as the complete path. Otherwise the source basename is appended. A trailing "/" always forces directory treatment (append basename).

func (*DirectoryAction) Run

func (a *DirectoryAction) Run(ctx context.Context, dryRun bool) error

type FileAction

type FileAction struct {
	Source      string // repo-side path
	Destination string // system-side directory (may contain ~ and $VARS)
	Direction   string // "push" | "pull" | "sync"
	Link        bool
	Permissions string // Unix octal string, e.g. "0600"
	Encrypted   bool
	AgeKey      *ageutil.Key // required when Encrypted is true
}

FileAction copies, symlinks, or syncs a config file between the repo and the system.

Idempotency:

• Link=true: implements Idempotent. IsApplied checks that the symlink at the destination already exists and resolves to the correct absolute source.
• Push/pull/sync (copy): does not implement Idempotent. Direction logic (e.g. filesEqual in sync) provides implicit idempotency; use skip_if for custom guards.

Permissions: when Permissions is non-empty (Unix octal, e.g. "0600"), the mode is enforced on the destination file after every write. On apply, if the existing file's mode does not match, it is corrected.

Encryption: when Encrypted is true and AgeKey is set, files are stored in the repo with an ".age" extension. On push the repo file is decrypted to the destination; on pull the system file is re-encrypted before writing to the repo.

func (*FileAction) Describe

func (a *FileAction) Describe() string

func (*FileAction) IsApplied

func (a *FileAction) IsApplied(ctx context.Context) (bool, error)

IsApplied implements Idempotent for link items.

func (*FileAction) PermissionsStatus

func (a *FileAction) PermissionsStatus() string

PermissionsStatus returns a human-readable permissions annotation for use in status output, or "" when not applicable or already correct.

func (*FileAction) ResolvedDir

func (a *FileAction) ResolvedDir() string

resolvedDir returns the parent directory of the resolved target.

func (*FileAction) ResolvedTarget

func (a *FileAction) ResolvedTarget() string

resolvedTarget returns the fully expanded destination file path. If the destination has a file extension (e.g. ~/.wezterm.lua), it is treated as a complete file path. Otherwise it is treated as a directory and the source basename is appended. A trailing "/" always forces directory treatment.

func (*FileAction) Run

func (a *FileAction) Run(ctx context.Context, dryRun bool) error

type Idempotent

type Idempotent interface {
	// IsApplied returns true when the action's desired state is already in
	// place and the action can safely be skipped.
	IsApplied(ctx context.Context) (bool, error)
}

Idempotent is optionally implemented by actions that can self-check whether they have already been applied. The runner uses this for automatic skip logic.

Idempotency contracts per action type:

• PackageAction: queries the package manager to determine whether the package is already installed. Guaranteed to be side-effect free.
• FileAction (link): checks that the symlink at the destination already exists and resolves to the correct absolute source path.
• FileAction (push/pull/sync), ScriptAction, SettingAction: do not implement Idempotent; use skip_if for custom idempotency guards.

type PackageAction

type PackageAction struct {
	Package string
	Manager string // e.g. "brew", "winget", "apt"
}

PackageAction installs a package via the specified package manager.

Idempotency: PackageAction implements Idempotent. IsApplied queries the package manager (e.g. `brew list`, `winget list`) to check whether the package is already installed. If the check command is unavailable the query is skipped and the install proceeds normally.

func (*PackageAction) Describe

func (a *PackageAction) Describe() string

func (*PackageAction) IsApplied

func (a *PackageAction) IsApplied(ctx context.Context) (bool, error)

IsApplied returns true when the package is already installed according to the package manager. Returns (false, nil) when the check is unsupported.

func (*PackageAction) Run

func (a *PackageAction) Run(ctx context.Context, dryRun bool) error

type RunAction

type RunAction struct {
	Command string
	After   string // informational dependency annotation
}

RunAction executes an inline shell command declared directly in the module. It is semantically equivalent to ScriptAction with via=local, but the command is written inline rather than as a script file path.

The After field records which item type this step logically follows. It is informational only in v1 — ordering is determined by the item's position in the items list. Module authors should place run items after their dependencies in the declaration order.

Idempotency: RunAction does not implement Idempotent. Use skip_if for custom guards.

func (*RunAction) Describe

func (a *RunAction) Describe() string

func (*RunAction) Run

func (a *RunAction) Run(ctx context.Context, dryRun bool) error

type ScriptAction

type ScriptAction struct {
	Script string
	Via    string // "remote" or "local"
}

ScriptAction runs a shell script, either from a local path or a remote URL.

func (*ScriptAction) Describe

func (a *ScriptAction) Describe() string

func (*ScriptAction) Run

func (a *ScriptAction) Run(ctx context.Context, dryRun bool) error

type SettingAction

type SettingAction struct {
	Domain string // macOS bundle ID or Windows registry path
	Key    string
	Value  any
}

SettingAction writes a system preference. On macOS it calls `defaults write`; on Windows it calls `reg add`.

func (*SettingAction) Describe

func (a *SettingAction) Describe() string

func (*SettingAction) Run

func (a *SettingAction) Run(ctx context.Context, dryRun bool) error