fernctl/commands/mod.rs
1//! # CLI Command Implementations
2//!
3//! This module contains the implementation logic for each `fernctl` subcommand.
4//! By separating command implementations from the CLI definition in [`main`],
5//! we achieve:
6//!
7//! - **Testability** — Commands can be unit tested without parsing CLI arguments
8//! - **Reusability** — Command logic can be called programmatically
9//! - **Separation of concerns** — CLI parsing vs. business logic
10//!
11//! ## Module Structure
12//!
13//! Each command has its own submodule with:
14//!
15//! | Module | Command | Description |
16//! |--------|---------|-------------|
17//! | [`validate`] | `fernctl validate` | Validate configuration syntax and semantics |
18//! | [`convert`] | `fernctl convert` | Convert TOML to JSON |
19//! | [`query`] | `fernctl query` | Query specific theme values |
20//! | [`watch`] | `fernctl watch` | Watch config and auto-convert on changes |
21//!
22//! ## Architecture
23//!
24//! Commands follow the hexagonal architecture pattern:
25//!
26//! ```text
27//! ┌─────────────────────────────────────────────────────────────┐
28//! │ CLI (main.rs) │
29//! │ Parses arguments, constructs dependencies, calls commands │
30//! └─────────────────────────────┬───────────────────────────────┘
31//! │
32//! ▼
33//! ┌─────────────────────────────────────────────────────────────┐
34//! │ Commands (this module) │
35//! │ Pure logic that accepts ports as dependencies │
36//! │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
37//! │ │ validate │ │ convert │ │ query │ │ watch │ │
38//! │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
39//! └───────┼────────────┼────────────┼────────────┼──────────────┘
40//! │ │ │ │
41//! ▼ ▼ ▼ ▼
42//! ┌─────────────────────────────────────────────────────────────┐
43//! │ Ports (traits) │
44//! │ ConfigPort, PersistPort, NotifyPort, WatchPort │
45//! └─────────────────────────────────────────────────────────────┘
46//! ```
47//!
48//! ## Usage Example
49//!
50//! Commands are called with their dependencies injected:
51//!
52//! ```rust,ignore
53//! use fernctl::commands::watch;
54//! use fernctl::adapters::{TomlConfigAdapter, FileSystemAdapter};
55//!
56//! let config_adapter = TomlConfigAdapter::new();
57//! let persist_adapter = FileSystemAdapter::new();
58//!
59//! // Options configure command behavior
60//! let options = watch::WatchOptions {
61//! debounce_ms: 100,
62//! notify_on_success: true,
63//! ..Default::default()
64//! };
65//!
66//! watch::run(&config_path, &json_path, options, &config_adapter, &persist_adapter)?;
67//! ```
68//!
69//! ## Error Handling
70//!
71//! All commands return [`Result<T, FernError>`](crate::error::FernError).
72//! Errors are enriched with context about what operation failed:
73//!
74//! ```text
75//! Error: fern::config::parse_error
76//!
77//! × TOML syntax error
78//! ╭─[config.toml:12:5]
79//! 11 │ [bar]
80//! 12 │ height = "forty"
81//! · ──────── expected integer
82//! ╰────
83//! help: Bar height must be a number in pixels
84//! ```
85
86pub mod convert;
87pub mod query;
88pub mod validate;
89
90#[cfg(feature = "watch")]
91#[cfg_attr(docsrs, doc(cfg(feature = "watch")))]
92pub mod watch;