raid

Documentation

Overview

The primary interface for the raid CLI tool functionality.

Lifecycle:

1. Initialize: set up the raid environment, including loading configurations and initializing data storage.
2. Compile: compile the raid configurations and prepare them for execution.
3. Execute: run the raid commands based on the compiled configurations.
4. Shutdown: gracefully shut down the raid environment, ensuring all resources are released and saved.

Related packages:

• `raid/profile`: provides the core functionality for loading and managing profiles
• `raid/repo`: provides the core functionality for loading and managing repositories
• `raid/env`: provides the core functionality for loading and managing environments

Index

• Constants
• Variables
• func ExecuteCommand(name string, args []string, named map[string]string) error
• func ExecuteRepoCommand(repoName, cmdName string, args []string, named map[string]string) error
• func ForceLoad() error
• func GetCommands() []lib.Command
• func GetProperty(name Property) (string, error)
• func GetRepos() []lib.Repo
• func Initialize()
• func Install(maxThreads int) error
• func InstallRepo(name string) error
• func Load() error
• func QuietGetCommands() []lib.Command
• func SetCommandOutput(stdout, stderr io.Writer) func()
• func WatchRaidVars(ctx context.Context, onChange func()) error
• func WithMutationLock(fn func() error) error
• type Environment
• type Finding
  • func Doctor() []Finding
• type Property
• type Severity
• type Verify
• type VerifyOutcome
  • func RunVerify(v Verify) (VerifyOutcome, error)

Constants

const (
	RaidConfigFileName  = lib.RaidConfigFileName
	ConfigPathFlag      = lib.ConfigPathFlag
	ConfigPathFlagDesc  = lib.ConfigPathFlagDesc
	ConfigPathFlagShort = lib.ConfigPathFlagShort
	ConfigPathDefault   = lib.ConfigPathDefault
	ConfigDirName       = lib.ConfigDirName
	ConfigFileName      = lib.ConfigFileName
)

const (
	VerifyOutcomeOK         = lib.VerifyOutcomeOK
	VerifyOutcomeRemediated = lib.VerifyOutcomeRemediated
	VerifyOutcomeFailed     = lib.VerifyOutcomeFailed
)

const (
	SeverityOK    = lib.SeverityOK
	SeverityWarn  = lib.SeverityWarn
	SeverityError = lib.SeverityError
)

const (
	PropertyVersion     = resources.PropertyVersion
	PropertyEnvironment = resources.PropertyEnvironment
)

const (
	EnvironmentDevelopment = resources.EnvironmentDevelopment
	EnvironmentPreview     = resources.EnvironmentPreview
	EnvironmentProduction  = resources.EnvironmentProduction
)

Variables

var ConfigPath = &lib.CfgPath

Pointer to the configuration path

Functions

func ExecuteCommand

func ExecuteCommand(name string, args []string, named map[string]string) error

ExecuteCommand runs the named command from the active profile. `named` carries values for declared args/flags; pass nil for the legacy positional-only path.

func ExecuteRepoCommand

func ExecuteRepoCommand(repoName, cmdName string, args []string, named map[string]string) error

ExecuteRepoCommand runs a command defined in a specific repository's raid.yaml. See ExecuteCommand for `named`.

func ForceLoad

func ForceLoad() error

Force load the raid configurations for execution. Ignores cache.

func GetCommands

func GetCommands() []lib.Command

GetCommands returns all commands available in the active profile.

func GetProperty

func GetProperty(name Property) (string, error)

GetProperty returns the value of the named property from app.properties.

func GetRepos

func GetRepos() []lib.Repo

GetRepos returns the repositories in the active profile.

func Initialize

func Initialize()

Initialize the raid environment, including loading configurations and initializing data storage.

func Install

func Install(maxThreads int) error

Install the active profile

func InstallRepo

func InstallRepo(name string) error

InstallRepo clones a single named repository and runs its install tasks.

func Load

func Load() error

Load the raid configurations for execution. Uses cached results if available.

func QuietGetCommands

func QuietGetCommands() []lib.Command

QuietGetCommands performs a best-effort, read-only profile load and returns the available commands. It does not create config files or emit warnings, and returns nil if the config is absent or loading fails.

func SetCommandOutput

func SetCommandOutput(stdout, stderr io.Writer) func()

SetCommandOutput swaps the writers used by task execution, repository cloning, and environment setup. Returns a restore function — call via defer to revert. Used by `raid context serve` to keep these writes off os.Stdout, which the MCP server reserves for JSON-RPC framing.

func WatchRaidVars

func WatchRaidVars(ctx context.Context, onChange func()) error

WatchRaidVars watches the persisted raid vars file (~/.raid/vars) for the lifetime of ctx and invokes onChange whenever the file is created, modified, or replaced. Events are debounced internally. The watcher returns when ctx is cancelled. See lib.WatchRaidVars for atomic-rename / inode-swap semantics.

func WithMutationLock

func WithMutationLock(fn func() error) error

WithMutationLock blocks on a cross-process exclusive lock at ~/.raid/.lock, runs fn, and releases the lock. Wrap every user-visible mutating operation (install, env switch, run task, profile add/remove/ switch) so concurrent raid invocations — including any combination of CLI usage and the MCP server's mutating tools — serialize cleanly.

Read paths don't need to acquire the lock; stale reads during a mutation are recoverable.

Types

type Environment

type Environment = resources.Environment

Environment identifies the runtime environment the binary was built for.

type Finding

type Finding = lib.Finding

Finding represents the result of a single Doctor check.

func Doctor

func Doctor() []Finding

Doctor performs all configuration checks and returns the findings.

type Property

type Property = resources.Property

Property identifies a key in app.properties.

type Severity

type Severity = lib.Severity

Severity indicates the importance of a Doctor finding.

type Verify

type Verify = lib.Verify

Verify is a re-export of the declarative precondition entry used in profiles and per-repo configs. See lib.Verify for the field semantics.

type VerifyOutcome

type VerifyOutcome = lib.VerifyOutcome

VerifyOutcome distinguishes a first-try pass from a successful self-heal. See lib.VerifyOutcome.

func RunVerify

func RunVerify(v Verify) (VerifyOutcome, error)

RunVerify executes a single verify entry: run Tasks; on failure, run the optional OnFail remediation and re-run Tasks once. Returns the outcome (passed / remediated / failed) and a non-nil structured errs.VerifyFailed iff the outcome is VerifyOutcomeFailed.