zexc 1.2.1

zex native lossless compressor — CLI zexc, library zexc, files *.zex
Documentation
//! Clap argument definitions for the `zexc` CLI.
//!
//! Primary UX (positional paths):
//! ```text
//! zexc compress   input.txt  output.zex
//! zexc decompress output.zex recovered.txt
//! zexc info       file.zex
//! ```

use clap::{Parser, Subcommand, ValueEnum};
use std::path::PathBuf;

/// zexc — ZEX native compressor (files use the `.zex` extension).
///
/// Binary name is **`zexc`** so it does not collide with other tools named `zex`.
#[derive(Debug, Parser)]
#[command(
    name = "zexc",
    version,
    about = "zexc — compress/decompress .zex files",
    long_about = "ZEX compression tool (command: zexc, files: *.zex)\n\n\
        Examples:\n  \
        zexc compress input.txt output.zex\n  \
        zexc decompress output.zex recovered.txt\n  \
        zexc info file.zex\n  \
        zexc test file.zex\n  \
        cat data | zexc compress - - > data.zex\n  \
        zexc archive create bundle.zexa a.txt b.bin\n  \
        zexc train-dict http.dict samples/*\n\n\
        License: GNU General Public License v3 only (GPL-3.0-only).\n\
        Copyright (C) 2026 Ali Zain <alizain@zainiumdynamics.tech>\n\
        Website: https://zainiumdynamics.tech\n\
        This is free software with ABSOLUTELY NO WARRANTY."
)]
pub struct Cli {
    /// Subcommand (`compress`, `decompress`, `info`, …)
    #[command(subcommand)]
    pub command: Commands,

    /// Worker threads (0 = all CPUs / rayon default)
    #[arg(short = 'T', long = "threads", global = true, default_value_t = 0)]
    pub threads: usize,

    /// Quiet (no stats on stderr)
    #[arg(short = 'q', long, global = true)]
    pub quiet: bool,
}

/// Top-level subcommands.
#[derive(Debug, Subcommand)]
pub enum Commands {
    /// Compress INPUT → OUTPUT (.zex)
    ///
    /// Example: `zexc compress input.txt output.zex`
    Compress {
        /// Input file (`-` = stdin)
        input: PathBuf,
        /// Output `.zex` file (`-` = stdout). Defaults to INPUT.zex (or stdout if INPUT is -)
        output: Option<PathBuf>,
        /// Level 1–22
        #[arg(short = 'l', long, default_value_t = 3)]
        level: u8,
        /// Profile: turbo | balanced | max
        #[arg(short = 'm', long, value_enum, default_value_t = ModeArg::Balanced)]
        mode: ModeArg,
        /// Disable CRC32
        #[arg(long)]
        no_checksum: bool,
        /// Strict security caps
        #[arg(long)]
        secure: bool,
        /// Password or 64-char hex key
        #[arg(short = 'e', long)]
        password: Option<String>,
        /// Dictionary file
        #[arg(short = 'D', long)]
        dict: Option<PathBuf>,
        /// Block size KiB
        #[arg(long, default_value_t = 256)]
        block_size_kib: u32,
        /// Delete INPUT after success (default: keep)
        #[arg(long)]
        rm: bool,
    },
    /// Decompress INPUT.zex → OUTPUT
    ///
    /// Example: `zexc decompress output.zex recovered.txt`
    Decompress {
        /// Input `.zex` file (`-` = stdin)
        input: PathBuf,
        /// Output file (`-` = stdout). Defaults to INPUT with .zex stripped
        output: Option<PathBuf>,
        /// Skip CRC check
        #[arg(long)]
        no_check: bool,
        /// Strict security caps
        #[arg(long)]
        secure: bool,
        /// Password / hex key
        #[arg(short = 'e', long)]
        password: Option<String>,
        /// Dictionary file
        #[arg(short = 'D', long)]
        dict: Option<PathBuf>,
        /// Delete INPUT after success
        #[arg(long)]
        rm: bool,
    },
    /// Show info about a `.zex` / `.zexa` file
    ///
    /// Example: `zexc info file.zex`
    Info {
        /// File to inspect
        input: PathBuf,
    },
    /// Verify a `.zex` file (decode + CRC)
    Test {
        /// Input `.zex` file
        input: PathBuf,
        /// Password / hex key
        #[arg(short = 'e', long)]
        password: Option<String>,
        /// Dictionary file
        #[arg(short = 'D', long)]
        dict: Option<PathBuf>,
    },
    /// Train a dictionary: `zexc train-dict out.dict sample1 sample2 …`
    TrainDict {
        /// Output dictionary path
        output: PathBuf,
        /// Sample files
        samples: Vec<PathBuf>,
        /// Maximum dictionary size in bytes
        #[arg(long, default_value_t = 112_640)]
        max_size: usize,
        /// Use simple trainer instead of COVER
        #[arg(long)]
        simple: bool,
        /// COVER segment length `d`
        #[arg(long, default_value_t = 8)]
        d: usize,
    },
    /// Seekable compress: `zexc seek-compress input.bin output.zexs`
    SeekCompress {
        /// Input file
        input: PathBuf,
        /// Output seekable `.zexs` file
        output: PathBuf,
        /// Independent frame size in KiB
        #[arg(long, default_value_t = 256)]
        frame_kib: u32,
        /// Level 1–22
        #[arg(short = 'l', long, default_value_t = 3)]
        level: u8,
        /// Profile: turbo | balanced | max
        #[arg(short = 'm', long, value_enum, default_value_t = ModeArg::Balanced)]
        mode: ModeArg,
    },
    /// Multi-file archive (`.zexa`)
    Archive {
        /// Archive action
        #[command(subcommand)]
        action: ArchiveCmd,
    },
    /// Microbench: `zexc bench file.bin`
    Bench {
        /// Input file to compress repeatedly
        input: PathBuf,
        /// Level 1–22
        #[arg(short = 'l', long, default_value_t = 3)]
        level: u8,
        /// Profile: turbo | balanced | max
        #[arg(short = 'm', long, value_enum, default_value_t = ModeArg::Balanced)]
        mode: ModeArg,
        /// Number of iterations
        #[arg(long, default_value_t = 5)]
        iters: u32,
    },
}

/// Archive subcommands.
#[derive(Debug, Subcommand)]
pub enum ArchiveCmd {
    /// `zexc archive create bundle.zexa a.txt b.bin`
    Create {
        /// Output archive path
        output: PathBuf,
        /// Input files
        files: Vec<PathBuf>,
        /// Level 1–22
        #[arg(short = 'l', long, default_value_t = 3)]
        level: u8,
        /// Profile: turbo | balanced | max
        #[arg(short = 'm', long, value_enum, default_value_t = ModeArg::Balanced)]
        mode: ModeArg,
    },
    /// `zexc archive list bundle.zexa`
    List {
        /// Archive path
        archive: PathBuf,
    },
    /// `zexc archive extract bundle.zexa out_dir`
    Extract {
        /// Archive path
        archive: PathBuf,
        /// Destination directory
        dir: PathBuf,
    },
}

/// Speed / ratio profile.
#[derive(Debug, Clone, Copy, ValueEnum, Default)]
pub enum ModeArg {
    /// Fastest path (levels ≤ 2 use turbo matcher)
    Turbo,
    /// Default balanced ratio/speed
    #[default]
    Balanced,
    /// Best ratio (slower)
    Max,
}

impl From<ModeArg> for crate::format::header::CompressionMode {
    fn from(m: ModeArg) -> Self {
        match m {
            ModeArg::Turbo => Self::Turbo,
            ModeArg::Balanced => Self::Balanced,
            ModeArg::Max => Self::Max,
        }
    }
}