refactor: modularize CLI crate into focused modules

Split lib.rs (917→19 lines) and main.rs (689→568 lines) into:
- args/ - PipelineArgs, DebugArgs structs
- types/ - WhiteBalance, ProcessingParams
- parsers/ - parse_* functions (base, pipeline, CB options)
- builders/ - build_convert_options, build_cb_options
- processing/ - process_single_image, input utilities

All new files are under 300 lines with single responsibilities.
Updated CLAUDE.md docs to reflect current directory structure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: narrowstacks

CLAUDE.md

@@ -34,10 +34,10 @@ All processing uses f32 linear RGB (0.0-1.0 range).
 
 **Pipeline changes MUST be implemented in both CPU and GPU codepaths.**
 
-| Component | CPU               | GPU                  |
-| --------- | ----------------- | -------------------- |
-| Pipeline  | `pipeline/mod.rs` | `gpu/pipeline.rs`    |
-| Shaders   | N/A               | `gpu/shaders/*.wgsl` |
+| Component | CPU               | GPU                    |
+| --------- | ----------------- | ---------------------- |
+| Pipeline  | `pipeline/mod.rs` | `gpu/pipeline/mod.rs`  |
+| Shaders   | N/A               | `gpu/shaders/*.wgsl`   |
 
 When modifying pipeline logic:
 
@@ -47,9 +47,11 @@ When modifying pipeline logic:
 
 ## Key Files
 
-- `crates/invers-core/src/pipeline/` - CPU processing pipeline
-- `crates/invers-core/src/gpu/` - GPU acceleration (wgpu)
-- `crates/invers-core/src/models/` - Data structures (FilmPreset, ConvertOptions, etc.)
-- `crates/invers-core/src/auto_adjust/` - Auto-levels, color, exposure, white balance
+- `crates/invers-core/src/pipeline/` - CPU processing pipeline (base_estimation/, inversion/, tone_mapping/)
+- `crates/invers-core/src/gpu/` - GPU acceleration (context/, pipeline/, shaders/)
+- `crates/invers-core/src/models/` - Data structures (cb/, convert_options/, scan_profile/)
+- `crates/invers-core/src/auto_adjust/` - Auto-adjustments (levels/, white_balance/, color.rs, exposure.rs)
+- `crates/invers-core/src/decoders/` - Image decoders (tiff.rs, png.rs, raw.rs)
+- `crates/invers-core/src/color/` - Color space conversions (hsl.rs, lab.rs)
 - `crates/invers-cli/src/commands/` - CLI command implementations
 - `config/pipeline_defaults.yml` - Default pipeline configuration

crates/invers-cli/src/args/debug.rs

@@ -0,0 +1,74 @@
+//! Debug-only argument structs for CLI commands.
+
+#[cfg(debug_assertions)]
+use clap::Args;
+
+/// Debug-only arguments (only available in debug builds).
+/// These flags are hidden from default help output.
+#[cfg(debug_assertions)]
+#[derive(Args, Clone, Debug, Default)]
+pub struct DebugArgs {
+    /// [DEBUG] Skip tone curve application
+    #[arg(long, hide = true)]
+    pub no_tonecurve: bool,
+
+    /// [DEBUG] Skip color matrix correction
+    #[arg(long, hide = true)]
+    pub no_colormatrix: bool,
+
+    /// [DEBUG] Inversion mode override: "mask-aware", "linear", "log", "divide-blend", or "bw"
+    #[arg(long, value_name = "MODE", hide = true)]
+    pub inversion: Option<String>,
+
+    /// [DEBUG] Enable automatic white balance correction
+    #[arg(long, hide = true)]
+    pub auto_wb: bool,
+
+    /// [DEBUG] Strength of auto white balance correction (0.0-1.0)
+    #[arg(long, value_name = "FLOAT", default_value = "1.0", hide = true)]
+    pub auto_wb_strength: f32,
+
+    /// [DEBUG] Auto white balance mode: "gray", "avg", or "pct" (percentile-based)
+    /// "pct" uses 98th percentile (robust white patch) - robust for varied scenes
+    #[arg(long, value_name = "MODE", default_value = "gray", hide = true)]
+    pub auto_wb_mode: String,
+
+    /// [DEBUG] Tone curve type: "neutral", "log", "cinematic", "linear", "asymmetric"
+    /// "log"/"cinematic" provides cinematic log-style tone profile
+    #[arg(long, value_name = "TYPE", hide = true)]
+    pub tone_curve: Option<String>,
+
+    /// [DEBUG] Enable debug output (detailed pipeline parameters)
+    #[arg(long, hide = true)]
+    pub debug: bool,
+}
+
+/// Placeholder for release builds - provides default values.
+#[cfg(not(debug_assertions))]
+#[derive(Clone, Debug, Default)]
+pub struct DebugArgs {
+    pub no_tonecurve: bool,
+    pub no_colormatrix: bool,
+    pub inversion: Option<String>,
+    pub auto_wb: bool,
+    pub auto_wb_strength: f32,
+    pub auto_wb_mode: String,
+    pub tone_curve: Option<String>,
+    pub debug: bool,
+}
+
+#[cfg(not(debug_assertions))]
+impl DebugArgs {
+    pub fn release_defaults() -> Self {
+        Self {
+            no_tonecurve: false,
+            no_colormatrix: false,
+            inversion: None,
+            auto_wb: true,
+            auto_wb_strength: 1.0,
+            auto_wb_mode: "avg".to_string(),
+            tone_curve: None,
+            debug: false,
+        }
+    }
+}

crates/invers-cli/src/args/mod.rs

@@ -0,0 +1,7 @@
+//! CLI argument structs.
+
+mod debug;
+mod pipeline;
+
+pub use debug::DebugArgs;
+pub use pipeline::PipelineArgs;

crates/invers-cli/src/args/pipeline.rs

@@ -0,0 +1,51 @@
+//! Pipeline argument structs for CLI commands.
+
+use clap::Args;
+
+/// Common pipeline arguments shared between Convert and Batch commands.
+/// These are advanced/research options hidden from default help output.
+#[derive(Args, Clone, Debug)]
+pub struct PipelineArgs {
+    /// Pipeline mode: "legacy" (default), "research", or "cb"
+    /// Research pipeline uses density balance BEFORE inversion for better color accuracy
+    /// CB pipeline uses curve-based processing for film-like rendering
+    #[arg(long, value_name = "MODE", default_value = "legacy", hide = true)]
+    pub pipeline: String,
+
+    /// [RESEARCH] Density balance red exponent (R^db_r)
+    /// Typical range: 0.8-1.3, default 1.05
+    #[arg(long, value_name = "FLOAT", hide = true)]
+    pub db_red: Option<f32>,
+
+    /// [RESEARCH] Density balance blue exponent (B^db_b)
+    /// Typical range: 0.7-1.1, default 0.90
+    #[arg(long, value_name = "FLOAT", hide = true)]
+    pub db_blue: Option<f32>,
+
+    /// [RESEARCH] Neutral point ROI for auto-calculating density balance (x,y,width,height)
+    /// Sample a known gray area to auto-compute density balance
+    #[arg(long, value_name = "X,Y,W,H", hide = true)]
+    pub neutral_roi: Option<String>,
+
+    /// [CB] Tone profile preset (standard, logarithmic, log-rich, log-flat, linear,
+    /// linear-gamma, linear-flat, linear-deep, all-soft, all-hard, highlight-hard,
+    /// highlight-soft, shadow-hard, shadow-soft, auto)
+    #[arg(long, value_name = "PROFILE", hide = true)]
+    pub cb_tone: Option<String>,
+
+    /// [CB] Enhanced profile/LUT (none, natural, frontier, crystal, pakon)
+    #[arg(long, value_name = "PROFILE", hide = true)]
+    pub cb_lut: Option<String>,
+
+    /// [CB] Color model (none, basic, frontier, noritsu, bw)
+    #[arg(long, value_name = "MODEL", hide = true)]
+    pub cb_color: Option<String>,
+
+    /// [CB] Film character (none, generic, kodak, fuji, cinestill-50d, cinestill-800t)
+    #[arg(long, value_name = "CHARACTER", hide = true)]
+    pub cb_film: Option<String>,
+
+    /// [CB] White balance preset (none, auto, neutral, warm, cool, mix, standard, kodak, fuji, cine-t, cine-d)
+    #[arg(long, value_name = "PRESET", hide = true)]
+    pub cb_wb: Option<String>,
+}

crates/invers-cli/src/builders/cb.rs

@@ -0,0 +1,31 @@
+//! CB (curve-based) pipeline options builder.
+
+use crate::parsers::{
+    parse_cb_color_model, parse_cb_enhanced_profile, parse_cb_film_character,
+    parse_cb_tone_profile, parse_cb_wb_preset,
+};
+
+/// Build CbOptions from parsed command line arguments
+pub fn build_cb_options(
+    tone_profile: Option<&str>,
+    enhanced_profile: Option<&str>,
+    color_model: Option<&str>,
+    film_character: Option<&str>,
+    wb_preset: Option<&str>,
+) -> Result<invers_core::models::CbOptions, String> {
+    let tone = parse_cb_tone_profile(tone_profile)?;
+    let lut = parse_cb_enhanced_profile(enhanced_profile)?;
+    let color = parse_cb_color_model(color_model)?;
+    let film = parse_cb_film_character(film_character)?;
+    let wb = parse_cb_wb_preset(wb_preset)?;
+
+    let mut opts = invers_core::models::CbOptions::from_presets(
+        tone,
+        lut,
+        color,
+        film,
+        invers_core::models::CbEnginePreset::V3_1,
+    );
+    opts.wb_preset = wb;
+    Ok(opts)
+}

crates/invers-cli/src/builders/mod.rs

@@ -0,0 +1,7 @@
+//! Builder functions for CLI options.
+
+mod cb;
+mod options;
+
+pub use cb::build_cb_options;
+pub use options::build_convert_options_full_with_gpu;

crates/invers-cli/src/builders/options.rs

@@ -0,0 +1,102 @@
+//! ConvertOptions builder functions.
+
+use std::path::PathBuf;
+
+/// Build a ConvertOptions struct with all options including GPU control
+///
+/// This is the canonical function for building ConvertOptions with all
+/// pipeline defaults, making it reusable across CLI and GUI applications.
+#[allow(clippy::too_many_arguments)]
+pub fn build_convert_options_full_with_gpu(
+    input: PathBuf,
+    output_dir: PathBuf,
+    export: &str,
+    colorspace: String,
+    base_estimation: Option<invers_core::models::BaseEstimation>,
+    film_preset: Option<invers_core::models::FilmPreset>,
+    scan_profile: Option<invers_core::models::ScanProfile>,
+    no_tonecurve: bool,
+    no_colormatrix: bool,
+    exposure: f32,
+    inversion_mode: Option<invers_core::models::InversionMode>,
+    no_auto_levels: bool,
+    preserve_headroom: bool,
+    no_clip: bool,
+    auto_wb: bool,
+    auto_wb_strength: f32,
+    debug: bool,
+    use_gpu: bool,
+) -> Result<invers_core::models::ConvertOptions, String> {
+    let config_handle = invers_core::config::pipeline_config_handle();
+    let defaults = config_handle.config.defaults.clone();
+
+    // Parse output format
+    let output_format = match export {
+        "tiff16" | "tiff" => invers_core::models::OutputFormat::Tiff16,
+        "dng" => invers_core::models::OutputFormat::LinearDng,
+        _ => return Err(format!("Unknown export format: {}", export)),
+    };
+
+    // Use provided inversion mode, or scan profile preference, or fall back to config default
+    let inversion_mode = inversion_mode
+        .or_else(|| {
+            scan_profile
+                .as_ref()
+                .and_then(|sp| sp.preferred_inversion_mode)
+        })
+        .unwrap_or(defaults.inversion_mode);
+
+    // Auto-levels: disabled if --no-auto-levels is set
+    let enable_auto_levels = !no_auto_levels && defaults.enable_auto_levels;
+
+    Ok(invers_core::models::ConvertOptions {
+        input_paths: vec![input],
+        output_dir,
+        output_format,
+        working_colorspace: colorspace,
+        bit_depth_policy: invers_core::models::BitDepthPolicy::Force16Bit,
+        film_preset,
+        scan_profile,
+        base_estimation,
+        num_threads: None,
+        skip_tone_curve: no_tonecurve || defaults.skip_tone_curve,
+        skip_color_matrix: no_colormatrix || defaults.skip_color_matrix,
+        exposure_compensation: defaults.exposure_compensation * exposure,
+        debug,
+        enable_auto_levels,
+        auto_levels_clip_percent: defaults.auto_levels_clip_percent,
+        preserve_headroom: preserve_headroom || defaults.preserve_headroom,
+        enable_auto_color: defaults.enable_auto_color,
+        auto_color_strength: defaults.auto_color_strength,
+        auto_color_min_gain: defaults.auto_color_min_gain,
+        auto_color_max_gain: defaults.auto_color_max_gain,
+        auto_color_max_divergence: defaults.auto_color_max_divergence,
+        base_brightest_percent: defaults.base_brightest_percent,
+        base_sampling_mode: defaults.base_sampling_mode,
+        base_estimation_method: invers_core::models::BaseEstimationMethod::default(),
+        auto_levels_mode: invers_core::models::AutoLevelsMode::default(),
+        inversion_mode,
+        shadow_lift_mode: defaults.shadow_lift_mode,
+        shadow_lift_value: defaults.shadow_lift_value,
+        highlight_compression: defaults.highlight_compression,
+        enable_auto_exposure: defaults.enable_auto_exposure,
+        auto_exposure_target_median: defaults.auto_exposure_target_median,
+        auto_exposure_strength: defaults.auto_exposure_strength,
+        auto_exposure_min_gain: defaults.auto_exposure_min_gain,
+        auto_exposure_max_gain: defaults.auto_exposure_max_gain,
+        no_clip,
+        enable_auto_wb: auto_wb,
+        auto_wb_strength,
+        auto_wb_mode: invers_core::models::AutoWbMode::default(),
+        use_gpu,
+        // Research pipeline options (defaults for now, CLI args coming soon)
+        pipeline_mode: invers_core::models::PipelineMode::Legacy,
+        density_balance: None,
+        neutral_point: None,
+        density_balance_red: None,
+        density_balance_blue: None,
+        tone_curve_override: None,
+        // CB-style pipeline options
+        cb_options: None,
+    })
+}