Documentation
¶
Overview ¶
Package workflow provides a structured engine for executing sequential, multi-step CLI operations. It separates the "what" (Steps) from the "how" (Runner), allowing for reusable logic, consistent error handling, and standardized user interaction.
Core Concepts ¶
- Step: An interface defining a single unit of work. It has a Description, a PreCheck (validation), and an Execute (action) phase.
- Runner: The engine that orchestrates the execution of Steps. It handles UI presentation, confirmation prompts, and error propagation.
- PresenterInterface: An abstraction for UI output, allowing the workflow to be tested without writing to actual stdout/stderr.
Usage Pattern ¶
runner := workflow.NewRunner(presenter, assumeYes)
err := runner.Run(ctx, "My Workflow Title",
&MyStep1{},
&MyStep2{},
)
PreChecks vs Execution ¶
The Runner executes all PreChecks first. If any PreCheck fails, the workflow aborts immediately. This ensures the environment is safe before any state changes occur. If all PreChecks pass, the Runner (optionally) prompts the user for confirmation before proceeding to the Execute phase of each step.
Index ¶
- func GetValidatedBranchName(ctx context.Context, branchNameFlag string, cfg *config.Config, ...) (string, error)
- type AnalyzeBranchStep
- type CheckAndPromptStashStep
- type CheckGoEnvStep
- type CheckOnMainBranchStep
- type CommitSquashStep
- type ConfigurePathStep
- type CreateAndPushBranchStep
- type EnsureCleanOrSaveStep
- type EnsureNotMainBranchStep
- type EnsureStagedStep
- type FetchStep
- type ForcePushStep
- type GenerateCommitPromptStep
- type GenerateSquashPromptStep
- type InstallGoToolsStep
- type InstallSelfStep
- type PresenterInterface
- type Runner
- type ScaffoldFirebaseStep
- type ScaffoldIDXStep
- type SoftResetStep
- type SquashState
- type Step
- type UpdateMainBranchStep
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetValidatedBranchName ¶
func GetValidatedBranchName( ctx context.Context, branchNameFlag string, cfg *config.Config, presenter PresenterInterface, gitClient *git.GitClient, assumeYes bool, ) (string, error)
GetValidatedBranchName is a helper function that can be used by the command before initializing the workflow. It's not a step itself.
Types ¶
type AnalyzeBranchStep ¶
type AnalyzeBranchStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
State *SquashState
}
AnalyzeBranchStep calculates commit counts and merge base.
func (*AnalyzeBranchStep) Description ¶
func (s *AnalyzeBranchStep) Description() string
type CheckAndPromptStashStep ¶
type CheckAndPromptStashStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
AssumeYes bool
DidStash bool // ADDED: This field will track if a stash was performed.
}
CheckAndPromptStashStep checks for a clean workspace and offers to stash changes.
func (*CheckAndPromptStashStep) Description ¶
func (s *CheckAndPromptStashStep) Description() string
Description returns a description of the step.
type CheckGoEnvStep ¶ added in v0.6.0
type CheckGoEnvStep struct {
ExecClient *exec.ExecutorClient
Presenter PresenterInterface
}
CheckGoEnvStep verifies Go is installed and logs the version.
func (*CheckGoEnvStep) Description ¶ added in v0.6.0
func (s *CheckGoEnvStep) Description() string
Description returns the step description.
type CheckOnMainBranchStep ¶
type CheckOnMainBranchStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
}
CheckOnMainBranchStep verifies that the current branch is the main branch.
func (*CheckOnMainBranchStep) Description ¶
func (s *CheckOnMainBranchStep) Description() string
Description returns a description of the step.
type CommitSquashStep ¶
type CommitSquashStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
State *SquashState
AssumeYes bool
}
CommitSquashStep prompts for the message and commits.
func (*CommitSquashStep) Description ¶
func (s *CommitSquashStep) Description() string
type ConfigurePathStep ¶ added in v0.6.0
type ConfigurePathStep struct {
Presenter PresenterInterface
AssumeYes bool
}
ConfigurePathStep ensures $HOME/go/bin is in .bashrc.
func (*ConfigurePathStep) Description ¶ added in v0.6.0
func (s *ConfigurePathStep) Description() string
Description returns the step description.
type CreateAndPushBranchStep ¶
CreateAndPushBranchStep creates and pushes a new branch.
func (*CreateAndPushBranchStep) Description ¶
func (s *CreateAndPushBranchStep) Description() string
Description returns a description of the step.
type EnsureCleanOrSaveStep ¶
type EnsureCleanOrSaveStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
AssumeYes bool
}
EnsureCleanOrSaveStep checks for dirty state and offers to commit.
func (*EnsureCleanOrSaveStep) Description ¶
func (s *EnsureCleanOrSaveStep) Description() string
type EnsureNotMainBranchStep ¶ added in v0.4.1
type EnsureNotMainBranchStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
}
EnsureNotMainBranchStep ensures the user is NOT on the main branch.
func (*EnsureNotMainBranchStep) Description ¶ added in v0.4.1
func (s *EnsureNotMainBranchStep) Description() string
Description returns a description of the step.
type EnsureStagedStep ¶ added in v0.4.1
type EnsureStagedStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
AssumeYes bool
}
EnsureStagedStep ensures there are staged changes, prompting to add if necessary.
func (*EnsureStagedStep) Description ¶ added in v0.4.1
func (s *EnsureStagedStep) Description() string
Description returns a description of the step.
type FetchStep ¶
type FetchStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
}
FetchStep ensures we have the latest remote refs.
func (*FetchStep) Description ¶
type ForcePushStep ¶
type ForcePushStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
State *SquashState
AssumeYes bool
}
ForcePushStep performs the push.
func (*ForcePushStep) Description ¶
func (s *ForcePushStep) Description() string
type GenerateCommitPromptStep ¶ added in v0.4.1
type GenerateCommitPromptStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
}
GenerateCommitPromptStep reads the state and outputs the AI prompt.
func (*GenerateCommitPromptStep) Description ¶ added in v0.4.1
func (s *GenerateCommitPromptStep) Description() string
Description returns a description of the step.
type GenerateSquashPromptStep ¶
type GenerateSquashPromptStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
State *SquashState
}
GenerateSquashPromptStep creates the _contextvibes.md file for the AI.
func (*GenerateSquashPromptStep) Description ¶
func (s *GenerateSquashPromptStep) Description() string
type InstallGoToolsStep ¶ added in v0.6.0
type InstallGoToolsStep struct {
ExecClient *exec.ExecutorClient
Presenter PresenterInterface
}
InstallGoToolsStep force-installs the required tools.
func (*InstallGoToolsStep) Description ¶ added in v0.6.0
func (s *InstallGoToolsStep) Description() string
Description returns the step description.
type InstallSelfStep ¶
type InstallSelfStep struct {
ExecClient *exec.ExecutorClient
Ref string // The git reference to install (e.g., "main", a hash, or a branch)
}
InstallSelfStep installs the contextvibes CLI binary using go install.
func (*InstallSelfStep) Description ¶
func (s *InstallSelfStep) Description() string
Description returns the step description.
type PresenterInterface ¶
type PresenterInterface interface {
Error(format string, a ...any)
Warning(format string, a ...any)
Info(format string, a ...any)
Success(format string, a ...any)
Detail(format string, a ...any)
Step(format string, a ...any)
Header(format string, a ...any)
Summary(format string, a ...any)
Newline()
PromptForConfirmation(prompt string) (bool, error)
PromptForInput(prompt string) (string, error)
Advice(format string, a ...any)
}
PresenterInterface defines the UI methods the workflow engine needs. This decouples the engine from the concrete ui.Presenter.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner manages the execution of a series of workflow steps.
func NewRunner ¶
func NewRunner(presenter PresenterInterface, assumeYes bool) *Runner
NewRunner creates a new workflow runner.
type ScaffoldFirebaseStep ¶
type ScaffoldFirebaseStep struct {
ExecClient *exec.ExecutorClient
Presenter PresenterInterface
}
ScaffoldFirebaseStep initializes Firebase.
func (*ScaffoldFirebaseStep) Description ¶
func (s *ScaffoldFirebaseStep) Description() string
Description returns the step description.
type ScaffoldIDXStep ¶
type ScaffoldIDXStep struct {
Presenter PresenterInterface
AssumeYes bool
}
ScaffoldIDXStep generates the .idx configuration files.
func (*ScaffoldIDXStep) Description ¶
func (s *ScaffoldIDXStep) Description() string
Description returns the step description.
type SoftResetStep ¶
type SoftResetStep struct {
GitClient *git.GitClient
Presenter PresenterInterface
State *SquashState
AssumeYes bool
}
SoftResetStep performs the git reset --soft.
func (*SoftResetStep) Description ¶
func (s *SoftResetStep) Description() string
type SquashState ¶
type SquashState struct {
CurrentBranch string
TargetBase string // The ref we are squashing against (e.g. origin/main)
MergeBase string
CommitCount int
}
SquashState holds data shared between squash workflow steps.
type Step ¶
type Step interface {
// Description returns a user-friendly string explaining what this step will do.
// This is used to build the "plan" shown to the user before confirmation.
Description() string
// PreCheck runs any prerequisite validations before the main execution.
// If it returns an error, the entire workflow is aborted.
PreCheck(ctx context.Context) error
// Execute performs the primary action of the step.
Execute(ctx context.Context) error
}
Step represents a single, discrete, and reusable action within a larger workflow.
type UpdateMainBranchStep ¶
UpdateMainBranchStep updates the main branch from the remote.
func (*UpdateMainBranchStep) Description ¶
func (s *UpdateMainBranchStep) Description() string
Description returns a description of the step.
Source Files