feat: implement zerv flow cli core structure

Author: wislertt

.claude/plan/34-zerv-flow-implementation-steps.md

@@ -1,9 +1,39 @@
 # Zerv Flow Implementation Plan
 
-**Status**: Planned
+**Status**: In Progress
 **Priority**: High
 **Context**: Step-by-step implementation plan for the `zerv flow` command based on CLI design in document #33.
 
+## Current Progress Summary (as of Oct 29, 2025)
+
+### ✅ **Completed Work:**
+
+- **Phase 1**: Core CLI Structure - 100% Complete
+    - CLI module structure implemented (`src/cli/flow/`)
+    - Flow command registered in parser and dispatcher
+    - Help system working (`zerv flow --help`)
+    - Shared args integration completed
+    - Validation system implemented
+    - All tests passing (6/6 flow tests)
+
+- **Shared Args Refactoring**: Completed
+    - Created `src/cli/common/args/` with InputConfig, OutputConfig, Validation
+    - Both version and flow commands now use shared args
+    - Eliminated code duplication between commands
+    - Comprehensive test coverage (35 tests) for shared components
+
+- **Code Quality Improvements**: Completed
+    - Added BoolResolution utility for opposing boolean flags
+    - Cleaned up verbose documentation comments
+    - Fixed inconsistent module structures
+    - Added comprehensive test coverage to common args
+
+### 🔄 **Next Steps:**
+
+- **Phase 2**: Implement branch pattern system and flow-to-version translation logic
+- **Phase 3**: Complete pipeline assembly with actual version command integration
+- **Phase 4**: Comprehensive testing and documentation
+
 ## Goals
 
 1. Implement `zerv flow` command that mirrors `zerv version` structure
@@ -14,41 +44,55 @@
 
 ## Implementation Plan
 
-### Phase 1: Core CLI Structure
+### ✅ **Phase 1: Core CLI Structure - COMPLETED**
+
+**All Phase 1 tasks have been successfully completed:**
+
+- ✅ CLI structure implemented and working
+- ✅ Flow command registered and dispatching correctly
+- ✅ Help system functioning (`zerv flow --help` works)
+- ✅ Basic validation and error handling in place
+- ✅ Shared input/output args integration complete
+- ✅ Module structure properly organized (args/mod.rs pattern)
 
-#### Step 1: Create Flow Command Module Structure
+### Phase 2: Flow Logic as Translation Layer
+
+#### Step 1: Create Flow Command Module Structure ✅
 
 - **Files**:
     - `src/cli/flow/mod.rs` (new file - module exports)
-    - `src/cli/flow/args.rs` (new file - argument structs)
+    - `src/cli/flow/args/mod.rs` (new file - argument structs)
     - `src/cli/flow/pipeline.rs` (new file - main handler)
 - **Tasks**:
-    - Create module structure following existing version command pattern
-    - Define `FlowArgs` struct with `clap::Parser` derive macro
-    - Organize arguments into logical groups (main, overrides, flow-specific)
-    - Set up proper module exports and dependencies
-- **Validation**: Module compiles and imports work correctly
+    - ✅ Create module structure following existing version command pattern
+    - ✅ Define `FlowArgs` struct with `clap::Parser` derive macro
+    - ✅ Organize arguments into logical groups (input, output, flow-specific, overrides)
+    - ✅ Set up proper module exports and dependencies
+    - ✅ Use shared input/output args from `src/cli/common/args/`
+    - ✅ Implement consistent module structure with version command
+- **Validation**: ✅ Module compiles and imports work correctly
 
-#### Step 2: Implement Flow Command Handler
+#### Step 2: Implement Flow Command Handler ✅
 
 - **File**: `src/cli/flow/pipeline.rs`
 - **Tasks**:
-    - Create `run_flow_pipeline(args: FlowArgs) -> Result<String, ZervError>` function
-    - Follow existing pattern: validation → processing → formatting → return
-    - Set up basic argument validation using `args.validate()` method
-    - Add error handling with `ZervError` and detailed context
-    - Use constants from `crate::utils::constants::*` instead of bare strings
-- **Validation**: Function compiles and returns proper Result type
+    - ✅ Create `run_flow_pipeline(args: FlowArgs) -> Result<String, ZervError>` function
+    - ✅ Follow existing pattern: validation → processing → formatting → return
+    - ✅ Set up basic argument validation using `args.validate()` method
+    - ✅ Add error handling with `ZervError` and detailed context
+    - ✅ Use constants from `crate::utils::constants::*` instead of bare strings
+    - ✅ Add placeholder implementation that returns `NotImplemented` error
+- **Validation**: ✅ Function compiles and returns proper Result type
 
-#### Step 3: Register Flow Command in CLI Parser
+#### Step 3: Register Flow Command in CLI Parser ✅
 
 - **Files**: `src/cli/parser.rs`, `src/cli/app.rs`
 - **Tasks**:
-    - Add `Flow(FlowArgs)` to `Commands` enum in `parser.rs`
-    - Add command dispatch handling in `app.rs` following existing pattern
-    - Ensure output is written to provided `writer`
-    - Add proper error propagation in dispatch
-- **Validation**: `zerv flow --help` shows all arguments correctly
+    - ✅ Add `Flow(FlowArgs)` to `Commands` enum in `parser.rs`
+    - ✅ Add command dispatch handling in `app.rs` following existing pattern
+    - ✅ Ensure output is written to provided `writer`
+    - ✅ Add proper error propagation in dispatch
+- **Validation**: ✅ `zerv flow --help` shows all arguments correctly
 
 ### Phase 2: Flow Logic as Translation Layer
 
@@ -103,17 +147,18 @@
     - Add verbose output showing translation results for debugging
 - **Validation**: Complete flow works end-to-end using version command
 
-#### Step 8: Add Argument Validation
+#### Step 8: Add Argument Validation ✅
 
-- **File**: `src/cli/flow/args.rs` (continued)
+- **File**: `src/cli/flow/args/validation.rs`
 - **Tasks**:
-    - Implement `validate()` method for `FlowArgs` struct
-    - Add validation for conflicting argument combinations
-    - Validate RON string format for branch rules
-    - Validate post mode values and hash length ranges
-    - Use `ZervError` with detailed messages for validation failures
-    - Follow existing validation patterns from version command
-- **Validation**: All validation scenarios work correctly
+    - ✅ Implement `validate()` method for `FlowArgs` struct
+    - ✅ Add validation for conflicting argument combinations
+    - ✅ Validate RON string format for branch rules
+    - ✅ Validate post mode values and hash length ranges
+    - ✅ Use `ZervError` with detailed messages for validation failures
+    - ✅ Follow existing validation patterns from version command
+    - ✅ Use shared validation for input/output conflicts
+- **Validation**: ✅ All validation scenarios work correctly
 
 ### Phase 4: Testing and Documentation
 

src/cli/app.rs

@@ -3,6 +3,7 @@ use std::io::Write;
 use clap::Parser;
 
 use crate::cli::check::run_check_command;
+use crate::cli::flow::run_flow_pipeline;
 use crate::cli::llm_help::display_llm_help;
 use crate::cli::parser::{
     Cli,
@@ -31,6 +32,10 @@ pub fn run_with_args<W: Write>(
             let output = run_version_pipeline(*version_args)?;
             writeln!(writer, "{output}")?;
         }
+        Some(Commands::Flow(flow_args)) => {
+            let output = run_flow_pipeline(*flow_args)?;
+            writeln!(writer, "{output}")?;
+        }
         Some(Commands::Check(check_args)) => {
             run_check_command(check_args)?;
         }

src/cli/check.rs

@@ -6,7 +6,6 @@ use clap::Parser;
 use crate::error::ZervError;
 use crate::utils::constants::{
     SUPPORTED_FORMAT_NAMES,
-    SUPPORTED_FORMATS,
     format_names,
     formats,
 };
@@ -79,7 +78,10 @@ pub fn run_check_command(args: CheckArgs) -> Result<(), ZervError> {
         }
         Some(format) => {
             eprintln!("✗ Unknown format: {format}");
-            eprintln!("Supported formats: {}", SUPPORTED_FORMATS.join(", "));
+            eprintln!(
+                "Supported formats: {}",
+                formats::SUPPORTED_FORMATS.join(", ")
+            );
             return Err(ZervError::UnknownFormat(format.to_string()));
         }
     }

src/cli/common/args/input.rs

@@ -0,0 +1,144 @@
+use clap::Parser;
+
+use crate::utils::constants::{
+    formats,
+    sources,
+};
+
+/// Reusable input configuration for version data
+#[derive(Parser, Debug, Clone)]
+pub struct InputConfig {
+    // ============================================================================
+    // INPUT OPTIONS
+    // ============================================================================
+    /// Input source for version data
+    #[arg(short = 's', long = "source", default_value = sources::GIT, value_parser = [sources::GIT, sources::STDIN],
+          help = "Input source: 'git' (extract from repository) or 'stdin' (read Zerv RON format)")]
+    pub source: String,
+
+    /// Input format for version string parsing
+    #[arg(short = 'f', long = "input-format", default_value = formats::AUTO, value_parser = [formats::AUTO, formats::SEMVER, formats::PEP440],
+          help = "Input format: 'auto' (detect), 'semver', or 'pep440'")]
+    pub input_format: String,
+
+    /// Working directory (default: current directory)
+    #[arg(short = 'C', long = "directory", value_name = "DIR")]
+    pub directory: Option<String>,
+}
+
+impl Default for InputConfig {
+    fn default() -> Self {
+        Self {
+            source: sources::GIT.to_string(),
+            input_format: formats::AUTO.to_string(),
+            directory: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_input_config_defaults() {
+        let config = InputConfig::default();
+        assert_eq!(config.source, sources::GIT);
+        assert_eq!(config.input_format, formats::AUTO);
+        assert!(config.directory.is_none());
+    }
+
+    #[test]
+    fn test_input_config_construction() {
+        let config = InputConfig {
+            source: sources::STDIN.to_string(),
+            input_format: formats::SEMVER.to_string(),
+            directory: Some("/path/to/repo".to_string()),
+        };
+        assert_eq!(config.source, sources::STDIN);
+        assert_eq!(config.input_format, formats::SEMVER);
+        assert_eq!(config.directory, Some("/path/to/repo".to_string()));
+    }
+
+    #[test]
+    fn test_input_config_various_sources() {
+        let sources_to_test = [
+            (sources::GIT, sources::GIT),
+            (sources::STDIN, sources::STDIN),
+        ];
+
+        for (source_value, expected_source) in sources_to_test {
+            let config = InputConfig {
+                source: source_value.to_string(),
+                input_format: formats::AUTO.to_string(),
+                directory: None,
+            };
+            assert_eq!(config.source, expected_source);
+        }
+    }
+
+    #[test]
+    fn test_input_config_various_formats() {
+        let formats_to_test = [
+            (formats::AUTO, formats::AUTO),
+            (formats::SEMVER, formats::SEMVER),
+            (formats::PEP440, formats::PEP440),
+        ];
+
+        for (format_value, expected_format) in formats_to_test {
+            let config = InputConfig {
+                source: sources::GIT.to_string(),
+                input_format: format_value.to_string(),
+                directory: None,
+            };
+            assert_eq!(config.input_format, expected_format);
+        }
+    }
+
+    #[test]
+    fn test_input_config_debug_format() {
+        let config = InputConfig {
+            source: "stdin".to_string(),
+            input_format: "semver".to_string(),
+            directory: Some("/test".to_string()),
+        };
+        let debug_str = format!("{:?}", config);
+        assert!(debug_str.contains("stdin"));
+        assert!(debug_str.contains("semver"));
+        assert!(debug_str.contains("/test"));
+    }
+
+    #[test]
+    fn test_input_config_clone() {
+        let config = InputConfig {
+            source: "stdin".to_string(),
+            input_format: "semver".to_string(),
+            directory: Some("/test".to_string()),
+        };
+        let cloned = config.clone();
+        assert_eq!(config.source, cloned.source);
+        assert_eq!(config.input_format, cloned.input_format);
+        assert_eq!(config.directory, cloned.directory);
+    }
+
+    #[test]
+    fn test_input_config_empty_directory() {
+        let config = InputConfig {
+            source: sources::GIT.to_string(),
+            input_format: formats::AUTO.to_string(),
+            directory: Some("".to_string()),
+        };
+        assert_eq!(config.directory, Some("".to_string()));
+    }
+
+    #[test]
+    fn test_input_config_complex_directory() {
+        let complex_path = "/workspace/user/project/subdir";
+        let config = InputConfig {
+            source: sources::GIT.to_string(),
+            input_format: formats::SEMVER.to_string(),
+            directory: Some(complex_path.to_string()),
+        };
+        assert_eq!(config.directory, Some(complex_path.to_string()));
+    }
+}

src/cli/common/args/mod.rs

@@ -0,0 +1,7 @@
+pub mod input;
+pub mod output;
+pub mod validation;
+
+pub use input::InputConfig;
+pub use output::OutputConfig;
+pub use validation::Validation;