feat: Implement --skip flag for pipeline steps and --list-steps for detailed help, along with adding Help() methods to all pipeline steps.

Author: tercel

CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.2.0] - 2026-03-24
+
+### Added
+- `--skip` CLI flag to skip pipeline steps from the command line (comma-separated, e.g. `--skip publish,test`), merged with config `skip` list with deduplication
+- `--list-steps` CLI flag to show detailed descriptions of all pipeline steps
+- `Help()` method on `Step` interface providing per-step documentation (what it does, per-language commands, prerequisites, hooks, destructive warnings)
+- Available steps summary in `--help` output, auto-generated from step definitions
+- `StepInfo` / `StepInfoList` for programmatic step metadata access
+
+### Changed
+- Skip message in pipeline output changed from "skipped by config" to "skipped" (source-agnostic)
+- `Config.Merge()` now accepts `cliSkip` parameter for CLI skip merge
+- Consolidated step list into single `buildAllSteps()` function (was duplicated 3x)
+- Help text and step validation now derived from step definitions (single source of truth)
+
+### Fixed
+- `StepNames` in `pipeline/step.go` was missing `"verify"` step
+
 ## [0.1.1] - 2026-03-22
 
 ### Changed

README.md

@@ -62,12 +62,14 @@ Steps marked as **destructive** (git_tag, github_release, publish) prompt for co
 unirelease [path] [flags]
 
 Flags:
-  --dry-run          Preview pipeline without executing
-  --step <name>      Run only a specific step
-  --type <type>      Override auto-detection (rust|go|node|bun|python)
-  -v, --version           Print version
+  --dry-run              Preview pipeline without executing
+  --step <name>          Run only a specific step
+  --skip <steps>         Steps to skip (comma-separated, e.g. --skip publish,test)
+  --list-steps           Show detailed descriptions of all pipeline steps
+  --type <type>          Override auto-detection (rust|go|node|bun|python)
+  -v, --version          Print version
   -V, --set-version <X.Y.Z>  Override detected version
-  -y, --yes          Non-interactive mode (skip confirmations)
+  -y, --yes              Non-interactive mode (skip confirmations)
 ```
 
 ### Examples
@@ -85,6 +87,12 @@ unirelease --set-version 2.0.0
 # Run only the build step
 unirelease --step build
 
+# Skip specific steps from CLI
+unirelease --skip publish,test
+
+# Show detailed help for all steps
+unirelease --list-steps
+
 # Force project type (useful for monorepos)
 unirelease --type rust
 
@@ -242,38 +250,10 @@ After the pipeline completes, unirelease displays a summary with:
   Release complete!
 ```
 
-## Project Structure
-
-```
-unirelease/
-├── cmd/root.go                    # CLI entry point (Cobra)
-├── internal/
-│   ├── changelog/                 # CHANGELOG.md parser
-│   ├── config/                    # .unirelease.toml loader
-│   ├── detector/                  # Project type & version detection
-│   ├── git/                       # Git operations (tag, push, status)
-│   ├── github/                    # GitHub API client (go-github)
-│   ├── pipeline/
-│   │   ├── engine.go              # Pipeline orchestrator
-│   │   ├── context.go             # Provider interface & shared context
-│   │   └── steps/                 # 11 pipeline step implementations
-│   ├── providers/                 # Language-specific providers
-│   │   ├── rust.go
-│   │   ├── go.go
-│   │   ├── node.go
-│   │   ├── bun.go
-│   │   └── python.go
-│   ├── runner/                    # Command executor (dry-run aware)
-│   └── ui/                        # Colored output & interactive prompts
-├── e2e_test.go                    # End-to-end pipeline tests
-├── go.mod
-└── main.go
-```
-
 ## Development
 
 ```bash
-# Run all tests (183 tests across 10 packages)
+# Run all tests
 go test ./...
 
 # Run with verbose output

cmd/root.go

@@ -18,27 +18,65 @@ import (
 )
 
 var (
-	flagStep    string
-	flagYes     bool
-	flagDryRun  bool
-	flagVersion string
-	flagType    string
+	flagStep      string
+	flagSkip      []string
+	flagYes       bool
+	flagDryRun    bool
+	flagVersion   string
+	flagType      string
+	flagListSteps bool
 )
 
-// Valid pipeline step names.
-var validSteps = []string{
-	"detect", "read_version", "verify_env", "check_git_status",
-	"clean", "build", "test", "verify", "git_tag", "github_release", "publish",
+var semverRegex = regexp.MustCompile(`^\d+\.\d+\.\d+$`)
+
+// buildAllSteps returns the canonical pipeline step list.
+func buildAllSteps() []pipeline.Step {
+	return []pipeline.Step{
+		&steps.DetectStep{},
+		&steps.ReadVersionStep{},
+		&steps.VerifyEnvStep{},
+		&steps.CheckGitStatusStep{},
+		&steps.CleanStep{},
+		&steps.BuildStep{},
+		&steps.TestStep{},
+		&steps.VerifyStep{},
+		&steps.GitTagStep{},
+		&steps.GitHubReleaseStep{},
+		&steps.PublishStep{},
+	}
 }
 
-var semverRegex = regexp.MustCompile(`^\d+\.\d+\.\d+$`)
+// validStepNames returns the list of valid step names derived from buildAllSteps.
+func validStepNames() []string {
+	allSteps := buildAllSteps()
+	names := make([]string, len(allSteps))
+	for i, s := range allSteps {
+		names[i] = s.Name()
+	}
+	return names
+}
+
+// buildLongHelp generates the Long help text from the step list.
+func buildLongHelp() string {
+	var b strings.Builder
+	b.WriteString("Auto-detects project type (Rust, Node, Bun, Python, Go) and runs a unified release pipeline.\n")
+	b.WriteString("\nAvailable steps (in execution order):\n")
+	for i, step := range buildAllSteps() {
+		tag := ""
+		if step.Destructive() {
+			tag = " [destructive]"
+		}
+		fmt.Fprintf(&b, "  %2d. %-17s %s%s\n", i+1, step.Name(), step.Description(), tag)
+	}
+	b.WriteString("\nUse --list-steps for detailed descriptions of each step.")
+	return b.String()
+}
 
 var rootCmd = &cobra.Command{
-	Use:   "unirelease [path]",
-	Short: "Unified release pipeline for any project",
-	Long:  "Auto-detects project type (Rust, Node, Bun, Python, Go) and runs a unified release pipeline.",
-	Args:  cobra.MaximumNArgs(1),
-	RunE:  runRelease,
+	Use:           "unirelease [path]",
+	Short:         "Unified release pipeline for any project",
+	Args:          cobra.MaximumNArgs(1),
+	RunE:          runRelease,
 	SilenceUsage:  true,
 	SilenceErrors: true,
 }
@@ -49,11 +87,14 @@ func SetVersion(v string) {
 }
 
 func init() {
+	rootCmd.Long = buildLongHelp()
 	rootCmd.Flags().StringVar(&flagStep, "step", "", "Run only a specific pipeline step")
+	rootCmd.Flags().StringSliceVar(&flagSkip, "skip", nil, "Steps to skip (comma-separated, e.g. --skip publish,test)")
 	rootCmd.Flags().BoolVarP(&flagYes, "yes", "y", false, "Non-interactive mode (skip confirmations)")
 	rootCmd.Flags().BoolVar(&flagDryRun, "dry-run", false, "Preview pipeline without executing")
 	rootCmd.Flags().StringVarP(&flagVersion, "set-version", "V", "", "Override detected version (e.g. 1.2.3)")
 	rootCmd.Flags().StringVar(&flagType, "type", "", "Override auto-detection (rust|node|bun|python|go)")
+	rootCmd.Flags().BoolVar(&flagListSteps, "list-steps", false, "Show detailed descriptions of all pipeline steps")
 }
 
 func Execute() error {
@@ -93,17 +134,14 @@ func resolveProjectDir(args []string) (string, error) {
 
 // validateFlags validates all flag values before running the pipeline.
 func validateFlags() error {
-	if flagStep != "" {
-		valid := false
-		for _, s := range validSteps {
-			if flagStep == s {
-				valid = true
-				break
-			}
-		}
-		if !valid {
-			return fmt.Errorf("invalid step %q (valid: %s)", flagStep, strings.Join(validSteps, ", "))
-		}
+	names := validStepNames()
+	nameSet := make(map[string]bool, len(names))
+	for _, s := range names {
+		nameSet[s] = true
+	}
+
+	if flagStep != "" && !nameSet[flagStep] {
+		return fmt.Errorf("invalid step %q (valid: %s)", flagStep, strings.Join(names, ", "))
 	}
 
 	if flagType != "" {
@@ -124,6 +162,12 @@ func validateFlags() error {
 		}
 	}
 
+	for _, s := range flagSkip {
+		if !nameSet[s] {
+			return fmt.Errorf("invalid skip step %q (valid: %s)", s, strings.Join(names, ", "))
+		}
+	}
+
 	if flagVersion != "" && !semverRegex.MatchString(flagVersion) {
 		return fmt.Errorf("invalid version %q (expected format: X.Y.Z, e.g. 1.2.3)", flagVersion)
 	}
@@ -132,6 +176,12 @@ func validateFlags() error {
 }
 
 func runRelease(cmd *cobra.Command, args []string) error {
+	// List steps mode
+	if flagListSteps {
+		printStepDetails()
+		return nil
+	}
+
 	// Validate flags
 	if err := validateFlags(); err != nil {
 		return err
@@ -150,7 +200,7 @@ func runRelease(cmd *cobra.Command, args []string) error {
 	}
 
 	// Merge CLI flags into config
-	cfg.Merge(flagType)
+	cfg.Merge(flagType, flagSkip)
 
 	// Create UI
 	u := ui.New()
@@ -172,19 +222,7 @@ func runRelease(cmd *cobra.Command, args []string) error {
 	}
 
 	// Build step list
-	allSteps := []pipeline.Step{
-		&steps.DetectStep{},
-		&steps.ReadVersionStep{},
-		&steps.VerifyEnvStep{},
-		&steps.CheckGitStatusStep{},
-		&steps.CleanStep{},
-		&steps.BuildStep{},
-		&steps.TestStep{},
-		&steps.VerifyStep{},
-		&steps.GitTagStep{},
-		&steps.GitHubReleaseStep{},
-		&steps.PublishStep{},
-	}
+	allSteps := buildAllSteps()
 
 	// Wrap detect step to also resolve the provider after detection
 	wrappedSteps := make([]pipeline.Step, len(allSteps))
@@ -204,6 +242,7 @@ type detectAndResolveStep struct {
 
 func (s *detectAndResolveStep) Name() string        { return s.inner.Name() }
 func (s *detectAndResolveStep) Description() string  { return s.inner.Description() }
+func (s *detectAndResolveStep) Help() string         { return s.inner.Help() }
 func (s *detectAndResolveStep) Destructive() bool    { return s.inner.Destructive() }
 
 func (s *detectAndResolveStep) Execute(ctx *pipeline.Context) error {
@@ -228,3 +267,19 @@ func resolveProvider(ctx *pipeline.Context) error {
 	ctx.Provider = provider
 	return nil
 }
+
+func printStepDetails() {
+	infoList := pipeline.StepInfoList(buildAllSteps())
+
+	fmt.Println("Pipeline Steps:")
+	fmt.Println()
+	for i, info := range infoList {
+		marker := " "
+		if info.Destructive {
+			marker = "!"
+		}
+		fmt.Printf("  %2d. [%s] %-17s %s\n", i+1, marker, info.Name, info.Description)
+		fmt.Printf("      %s\n\n", info.Help)
+	}
+	fmt.Println("Legend: [!] = destructive (prompts for confirmation, use --yes to skip)")
+}

cmd/root_test.go

@@ -3,7 +3,10 @@ package cmd
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
+
+	"github.com/aiperceivable/unirelease/internal/pipeline"
 )
 
 func TestValidateFlags_ValidStep(t *testing.T) {
@@ -75,6 +78,62 @@ func TestValidateFlags_InvalidVersion(t *testing.T) {
 	}
 }
 
+func TestValidateFlags_ValidSkip(t *testing.T) {
+	flagStep = ""
+	flagType = ""
+	flagVersion = ""
+	flagSkip = []string{"publish", "test"}
+	defer func() { flagSkip = nil }()
+
+	if err := validateFlags(); err != nil {
+		t.Errorf("unexpected error: %v", err)
+	}
+}
+
+func TestValidateFlags_InvalidSkip(t *testing.T) {
+	flagStep = ""
+	flagType = ""
+	flagVersion = ""
+	flagSkip = []string{"publish", "bogus"}
+	defer func() { flagSkip = nil }()
+
+	err := validateFlags()
+	if err == nil {
+		t.Fatal("expected error for invalid skip step")
+	}
+}
+
+func TestBuildAllSteps_MatchesStepNames(t *testing.T) {
+	allSteps := buildAllSteps()
+	stepNames := pipeline.StepNames
+
+	if len(allSteps) != len(stepNames) {
+		t.Fatalf("buildAllSteps() has %d steps, StepNames has %d", len(allSteps), len(stepNames))
+	}
+	for i, step := range allSteps {
+		if step.Name() != stepNames[i] {
+			t.Errorf("step %d: buildAllSteps() has %q, StepNames has %q", i, step.Name(), stepNames[i])
+		}
+	}
+}
+
+func TestBuildAllSteps_HelpNotEmpty(t *testing.T) {
+	for _, step := range buildAllSteps() {
+		if step.Help() == "" {
+			t.Errorf("step %q has empty Help()", step.Name())
+		}
+	}
+}
+
+func TestBuildLongHelp_ContainsAllSteps(t *testing.T) {
+	helpText := buildLongHelp()
+	for _, step := range buildAllSteps() {
+		if !strings.Contains(helpText, step.Name()) {
+			t.Errorf("Long help missing step %q", step.Name())
+		}
+	}
+}
+
 func TestResolveProjectDir_Explicit(t *testing.T) {
 	dir := t.TempDir()
 	result, err := resolveProjectDir([]string{dir})

e2e_test.go

@@ -58,6 +58,7 @@ type detectAndResolveStep struct {
 
 func (s *detectAndResolveStep) Name() string        { return s.inner.Name() }
 func (s *detectAndResolveStep) Description() string { return s.inner.Description() }
+func (s *detectAndResolveStep) Help() string        { return s.inner.Help() }
 func (s *detectAndResolveStep) Destructive() bool   { return s.inner.Destructive() }
 
 func (s *detectAndResolveStep) Execute(ctx *pipeline.Context) error {