cli

package
v0.11.5 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: EUPL-1.2 Imports: 69 Imported by: 0

Documentation

Overview

Package cli provides the Cobra-based command-line interface for AWF.

The CLI layer is the primary user-facing entry point, translating command-line invocations into application service calls. All commands follow the hexagonal architecture pattern: CLI → Application Services → Domain → Infrastructure. The package handles user input collection, output formatting, signal handling, and exit code mapping according to the AWF error taxonomy.

Architecture Role

In the hexagonal architecture:

  • CLI commands receive user input from cobra.Command flags and arguments
  • Commands delegate business logic to application services (WorkflowService, ExecutionService)
  • Commands handle cross-cutting concerns: signal handling, exit codes, output formatting
  • Commands inject infrastructure adapters (repositories, loggers, executors) into services

The CLI layer is an adapter in the "interfaces" layer, depending on both application services (orchestration) and infrastructure adapters (implementation details). No domain logic resides here—only input parsing, output rendering, and coordination.

Command Structure

## Root Command (root.go)

Application container and version command:

  • App: Dependency injection container with Config and Formatter
  • NewApp: Creates application with loaded configuration
  • NewRootCommand: Builds cobra command tree with global flags
  • --version: Displays AWF version, commit, and build date

Global flags:

  • --no-color: Disable colorized output
  • --json: JSON-formatted output
  • --no-hints: Suppress helpful tips

## Core Commands

### run (run.go)

Execute workflow with state machine traversal:

  • Flags: --input, --resume, --agent-input, --mock, --dry-run, --interactive, --no-save
  • Input resolution: CLI flags → project config → interactive prompts
  • Dry run mode: validates without execution, renders execution plan
  • Interactive mode: step-by-step execution with user confirmation
  • Resume support: continues from saved checkpoint state
  • Error categorization: maps domain/infra errors to exit codes (1-4)

### list (list.go)

Enumerate available workflows and prompts:

  • list: Display all workflows from configured paths
  • list prompts: Show available interactive prompts with descriptions
  • Output format: table (default) or JSON

### validate (validate.go)

Static workflow validation:

  • Parse workflow YAML
  • Validate structure, state references, transitions
  • Check for cycles, unreachable states
  • Exit 0 on success, 2 on validation errors

### status (status.go)

Check running workflow status:

  • Query execution state from StateStore
  • Display current step, progress, outputs
  • Show execution timeline and duration

### resume (resume.go)

Continue interrupted workflow:

  • Load checkpoint state from StateStore
  • Resume execution from last completed step
  • Preserve input values and outputs

### history (history.go)

Query workflow execution history:

  • List past executions with filtering (workflow name, status, date range)
  • Show execution statistics (duration, success rate)
  • Prune old history records

## Supporting Commands

### init (init.go)

Initialize AWF in current directory:

  • Create .awf/ directory structure
  • Generate default awf.yaml configuration
  • Create workflows/ directory with example

### config (config.go, config_cmd.go)

Configuration management:

  • config show: Display current configuration
  • config set <key> <value>: Update configuration value
  • config paths: Show search paths for workflows/templates/plugins

### plugin (plugin_cmd.go, plugins.go)

Plugin lifecycle management:

  • plugin list: Show available plugins
  • plugin enable <name>: Activate plugin
  • plugin disable <name>: Deactivate plugin
  • plugin status <name>: Check plugin state

### diagram (diagram.go)

Generate workflow visualization:

  • Render workflow state machine as Mermaid diagram
  • Output to stdout or file

### migration (migration.go)

Version migration utilities:

  • Migrate workflow syntax to latest version
  • Update deprecated fields

Signal Handling (signal_handler.go)

Graceful shutdown on SIGINT/SIGTERM:

  • setupSignalHandler: Starts goroutine listening for OS signals
  • Context cancellation: Propagates cancellation through execution stack
  • Process group cleanup: Terminates child processes on signal
  • Cleanup callback: Executes user-provided cleanup function before exit
  • Goroutine leak prevention: Returns cleanup function that MUST be deferred

Exit Codes (exitcodes.go)

AWF error taxonomy mapping:

  • ExitSuccess (0): Successful execution
  • ExitUser (1): User error (bad input, missing file, invalid flags)
  • ExitWorkflow (2): Workflow error (invalid state reference, cycle detection, schema violation)
  • ExitExecution (3): Execution error (command failed, timeout, agent error)
  • ExitSystem (4): System error (IO failure, permissions, resource exhaustion)

Error Handling (error.go)

Error categorization and formatting:

  • exitError: Wraps domain/infra errors with exit code
  • categorizeError: Maps error types to exit codes via taxonomy
  • writeErrorAndExit: Formats error, writes to stderr, exits with correct code
  • formatLog: Colorized log output with level-based styling

Design Principles

  • Thin adapter layer: All business logic in application/domain layers
  • Fail fast: Validate inputs before service calls
  • User-friendly errors: Context-rich messages with actionable guidance
  • Testability: Commands accept io.Writer for output, injectable services
  • Signal safety: Always defer signal handler cleanup to prevent leaks
  • Exit code discipline: Consistent taxonomy mapping for automation/scripting

Index

Constants

View Source
const (
	ExitSuccess   = 0 // Success
	ExitUser      = 1 // User error (bad input, missing file)
	ExitWorkflow  = 2 // Workflow error (invalid state reference, cycle)
	ExitExecution = 3 // Execution error (command failed, timeout)
	ExitSystem    = 4 // System error (IO, permissions)
)

Exit codes following the error taxonomy

Variables

View Source
var (
	Version   = "dev"
	Commit    = "unknown"
	BuildDate = "unknown"
)

Version information (set at build time via ldflags)

Functions

func AttachMirrorSubscriber added in v0.11.2

func AttachMirrorSubscriber(rec ports.Recorder, mirrorPath string) func()

AttachMirrorSubscriber attaches a debug mirror subscriber to the recorder. When mirrorPath is non-empty, recorder events are written to mirrorPath; when empty, returns a no-op cancel. The actual subscription lives in the transcript infrastructure (transcript.MirrorToFile) so the interface layer holds no direct recorder.Subscribe() call, preserving the SC-001 sole-subscriber invariant.

func BuildPluginPaths

func BuildPluginPaths() []repository.SourcedPath

BuildPluginPaths returns plugin paths in priority order: 1. AWF_PLUGINS_PATH env var 2. ./.awf/plugins/ (local project) 3. $XDG_DATA_HOME/awf/plugins/ (global)

func BuildPromptPaths

func BuildPromptPaths() []repository.SourcedPath

BuildPromptPaths returns the prompt paths in priority order: 1. ./.awf/prompts/ (local project) 2. $XDG_CONFIG_HOME/awf/prompts/ (global)

func BuildWorkflowPaths

func BuildWorkflowPaths() []repository.SourcedPath

BuildWorkflowPaths returns the workflow paths in priority order: 1. AWF_WORKFLOWS_PATH env var 2. ./.awf/workflows/ (local project) 3. $XDG_CONFIG_HOME/awf/workflows/ (global)

func CheckMigration

func CheckMigration(w io.Writer)

CheckMigration shows a one-time migration notice if ~/.awf exists

func NewRecorderFactory added in v0.11.2

func NewRecorderFactory() ports.RecorderFactory

NewRecorderFactory returns a ports.RecorderFactory backed by the transcript infrastructure Recorder. It is used by ExecutionService to create one child recorder per sub-run for F106 sub-workflow transcript linkage. The parent directory of the path passed to the factory must already exist.

func NewRootCommand

func NewRootCommand() *cobra.Command

func NewRootCommandAutoFacade added in v0.11.2

func NewRootCommandAutoFacade() (cmd *cobra.Command, cleanup func())

NewRootCommandAutoFacade builds the root command with a CLI-wide WorkflowFacade wired into cfg.Facade lazily (in PersistentPreRun, after flag parsing so --storage is honored). It returns the command and a cleanup that releases facade resources (closes the history store); main must call it after Execute returns.

func NewServeCommand added in v0.11.2

func NewServeCommand() *cobra.Command

NewServeCommand returns the cobra.Command for `awf serve`.

func NewWorkflowRepository

func NewWorkflowRepository() *repository.CompositeRepository

NewWorkflowRepository creates a CompositeRepository with standard paths

func ParseMockFlags

func ParseMockFlags(flags []string) (map[string]string, error)

ParseMockFlags parses --mock flags into a map. Format: states.step_name.Output=value

func RenderFacadeEventsToText added in v0.11.2

func RenderFacadeEventsToText(events []ports.Event) []byte

RenderFacadeEventsToText converts facade events to CLI text output in the default (non-quiet) mode. This is the renderer the facade conformance golden exercises; the live run driver uses RenderFacadeEventsToTextWithOptions to honor --quiet.

func RenderFacadeEventsToTextWithOptions added in v0.11.2

func RenderFacadeEventsToTextWithOptions(events []ports.Event, opts facadeRenderOptions) []byte

RenderFacadeEventsToTextWithOptions converts facade events to CLI text output, honoring the supplied options (e.g. --quiet). It restores the legacy phrasing so downstream tooling and users that grep "Workflow ID:" / "completed successfully" keep working:

  • EventRunStarted prints both a human "Workflow started:" line and the legacy "Workflow ID: <run-id>" line (suppressed in quiet mode via Info).
  • EventStepCompleted prints the legacy "<step>: completed successfully" feedback line for a silent step (no stdout/stderr), suppressed in quiet mode; a step that already printed output gets a plain completion marker instead (its output is the feedback).

func RenderWorkflowHelp

func RenderWorkflowHelp(cmd *cobra.Command, wf *workflow.Workflow, out io.Writer, noColor bool) error

RenderWorkflowHelp renders workflow-specific help output including workflow description and input parameters table. This is called when a user runs `awf run <workflow> --help` to display dynamic help for the specified workflow.

The output follows Cobra help conventions while adding workflow-specific content: - Workflow description (if present) - Input parameters table with NAME, TYPE, REQUIRED, DEFAULT, DESCRIPTION columns

func WireTranscript added in v0.11.2

func WireTranscript(runID, storageRoot string) (ports.Recorder, func() error, error)

WireTranscript builds a transcript Recorder at storage/transcripts/<runID>.jsonl and returns the recorder along with a cleanup closure that calls Close(). The storageRoot is the parent directory for transcripts (typically cfg.StoragePath). Returns the recorder, a cleanup function, and any error.

Types

type App

type App struct {
	Config    *Config
	Formatter *ui.Formatter
}

App holds CLI dependencies and configuration.

func NewApp

func NewApp(cfg *Config) *App

type Config

type Config struct {
	Verbose         bool
	Quiet           bool
	NoColor         bool
	NoHints         bool
	OutputMode      OutputMode
	OutputFormat    ui.OutputFormat
	LogLevel        string
	ConfigPath      string
	StoragePath     string
	PluginsDir      string // Override plugin discovery directory (empty = use BuildPluginPaths)
	OtelExporter    string
	OtelServiceName string
	Facade          ports.WorkflowFacade // nil until wired via NewRootCommandWithFacade or main.go
}

Config holds CLI configuration.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns default configuration.

type ConfigShowOutput

type ConfigShowOutput struct {
	Path   string         `json:"path"`
	Exists bool           `json:"exists"`
	Inputs map[string]any `json:"inputs,omitempty"`
}

ConfigShowOutput represents the structured output for 'config show' command. Used for JSON format output.

type Deps added in v0.11.2

type Deps struct {
	PluginManager      ports.PluginManager
	OperationProviders map[string]ports.OperationProvider
}

Deps holds injectable dependencies for the mcp-serve subcommand.

When Deps is populated (test or future in-process callers), runMCPServe uses OperationProviders directly for plugin_tools resolution. When Deps is empty (the subprocess case — ProxyService.StartForStdio spawns `awf mcp-serve` with no in-process state), runMCPServe self-bootstraps by calling initPluginSystem, which loads external plugins from the standard discovery paths. Either code path converges on the same registerTools call.

type HistoryInfo

type HistoryInfo struct {
	ID            string `json:"id"`
	WorkflowID    string `json:"workflow_id"`
	Attempt       int    `json:"attempt"`
	ResumedFromID string `json:"resumed_from_id,omitempty"`
	WorkflowName  string `json:"workflow_name"`
	Status        string `json:"status"`
	ExitCode      int    `json:"exit_code,omitempty"`
	StartedAt     string `json:"started_at"`
	CompletedAt   string `json:"completed_at"`
	DurationMs    int64  `json:"duration_ms"`
	ErrorMessage  string `json:"error_message,omitempty"`
}

type HistoryStatsInfo

type HistoryStatsInfo struct {
	TotalExecutions int   `json:"total_executions"`
	SuccessCount    int   `json:"success_count"`
	FailedCount     int   `json:"failed_count"`
	CancelledCount  int   `json:"cancelled_count"`
	AvgDurationMs   int64 `json:"avg_duration_ms"`
}

type OutputMode

type OutputMode int

OutputMode defines how command output is displayed.

const (
	OutputSilent    OutputMode = iota // default: no streaming
	OutputStreaming                   // real-time prefixed output
	OutputBuffered                    // show after completion
)

func ParseOutputMode

func ParseOutputMode(s string) (OutputMode, error)

ParseOutputMode parses a string to OutputMode.

func (OutputMode) String

func (m OutputMode) String() string

type PluginSystemResult

type PluginSystemResult struct {
	Service        *application.PluginService
	Manager        ports.OperationProvider
	RPCManager     *infrastructurePlugin.RPCPluginManager // for validator/step-type providers (C069)
	StateStore     *infrastructurePlugin.JSONPluginStateStore
	EventPublisher ports.EventPublisher
	Cleanup        func()
}

PluginSystemResult contains the initialized plugin system components.

Directories

Path Synopsis
Package ui provides user interface components for the AWF CLI.
Package ui provides user interface components for the AWF CLI.

Jump to

Keyboard shortcuts

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