fernctl/lib.rs
1//! # fernctl — Type-Safe Design Tokens for Fern Shell
2//!
3//! `fernctl` is the core library for Fern Shell's design system, providing
4//! compile-time guarantees for design token correctness through Rust's type system.
5//!
6//! ## Overview
7//!
8//! This crate implements a **hexagonal architecture** (ports and adapters) where:
9//!
10//! - **Domain Layer** ([`domain`]): Pure business logic with zero external dependencies.
11//! Contains type-safe design tokens, theme definitions, and validation rules.
12//!
13//! - **Ports** ([`ports`]): Trait-based interfaces that define how the domain
14//! interacts with the outside world, without depending on specific implementations.
15//!
16//! - **Adapters** ([`adapters`]): Concrete implementations that connect ports to
17//! external systems (file I/O, D-Bus, notifications).
18//!
19//! - **Error Handling** ([`error`]): Rich, user-friendly error types with
20//! diagnostic information for debugging configuration issues.
21//!
22//! ## Design Philosophy
23//!
24//! Traditional design systems define tokens as stringly-typed values:
25//!
26//! ```text
27//! button.background = "#1e1e2e" // Is this a valid background color?
28//! button.radius = 9999 // Is this valid for buttons?
29//! ```
30//!
31//! These questions are answered at runtime (if at all), leading to subtle bugs.
32//!
33//! `fernctl` encodes design system rules in the type system:
34//!
35//! ```rust,ignore
36//! // ColorToken<Surface> can only be used where BackgroundRole is expected
37//! button.background: ColorToken<Surface> // ✓ Compiles
38//! button.background: ColorToken<Foreground> // ✗ Type error!
39//!
40//! // ButtonRadius trait limits which radii are valid for buttons
41//! button.radius: RadiusMd // ✓ Compiles (Md implements ButtonRadius)
42//! button.radius: RadiusFull // ✗ Type error! (Full doesn't implement ButtonRadius)
43//! ```
44//!
45//! ## Architecture Diagram
46//!
47//! ```text
48//! ┌─────────────────────────────────┐
49//! │ DRIVING ADAPTERS │
50//! │ ┌──────┐ ┌─────┐ ┌──────┐ │
51//! │ │ TOML │ │ CLI │ │ JSON │ │
52//! │ └──┬───┘ └──┬──┘ └──┬───┘ │
53//! │ │ │ │ │
54//! │ ┌──▼─────────▼────────▼───┐ │
55//! │ │ INBOUND PORTS │ │
56//! │ │ ConfigPort, QueryPort │ │
57//! │ └───────────┬─────────────┘ │
58//! ┌──────────────────────┼──────────────▼─────────────────┐│
59//! │ │ DOMAIN ││
60//! │ ┌───────────────────┴──────────────────────────────┐ ││
61//! │ │ DESIGN LANGUAGE │ ││
62//! │ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ ││
63//! │ │ │ Tokens │ │ Scales │ │ Components │ │ ││
64//! │ │ │ Color │ │ Spacing │ │ ButtonSpec │ │ ││
65//! │ │ │ Radius │ │ Radius │ │ ModuleSpec │ │ ││
66//! │ │ └──────────┘ └──────────┘ └──────────────┘ │ ││
67//! │ │ │ │ ││
68//! │ │ ┌────▼────┐ │ ││
69//! │ │ │ Theme │ │ ││
70//! │ │ └─────────┘ │ ││
71//! │ └──────────────────────────────────────────────────┘ ││
72//! │ │ ││
73//! │ ┌──────────────────────▼───────────────────────────┐ ││
74//! │ │ OUTBOUND PORTS │ ││
75//! │ │ PersistPort, NotifyPort, IpcPort │ ││
76//! │ └──────────────────────┬───────────────────────────┘ ││
77//! └─────────────────────────┼─────────────────────────────┘│
78//! │ │ │
79//! │ ┌──▼─────────────────────────┐ │
80//! │ │ DRIVEN ADAPTERS │ │
81//! │ │ ┌────────┐ ┌─────┐ ┌─────┐ │ │
82//! │ │ │ File │ │D-Bus│ │Notif│ │ │
83//! │ │ │ System │ │ IPC │ │ │ │ │
84//! │ │ └────────┘ └─────┘ └─────┘ │ │
85//! │ └────────────────────────────┘ │
86//! └─────────────────────────────────┘
87//! ```
88//!
89//! ## Quick Start
90//!
91//! ### Loading Configuration
92//!
93//! ```rust,ignore
94//! use fernctl::prelude::*;
95//! use fernctl::adapters::TomlConfigAdapter;
96//!
97//! // Load and validate a TOML configuration
98//! let toml_content = std::fs::read_to_string("config.toml")?;
99//! let adapter = TomlConfigAdapter::new();
100//!
101//! // Type-state ensures we can't use config before validation
102//! let raw = adapter.parse(&toml_content)?; // Config<Parsed>
103//! let validated = raw.validate()?; // Config<Validated>
104//! let theme = validated.into_theme(); // Theme
105//! ```
106//!
107//! ### Using Design Tokens
108//!
109//! ```rust,ignore
110//! use fernctl::domain::tokens::*;
111//!
112//! // Create type-safe colors
113//! let surface: ColorToken<Surface> = ColorToken::from_hex("#313244")?;
114//! let text: ColorToken<Foreground> = ColorToken::from_hex("#cdd6f4")?;
115//!
116//! // The type system prevents misuse:
117//! fn set_background(color: impl BackgroundRole) { /* ... */ }
118//! set_background(surface); // ✓ Works - Surface is a BackgroundRole
119//! // set_background(text); // ✗ Won't compile - Foreground is not BackgroundRole
120//! ```
121//!
122//! ## Feature Flags
123//!
124//! | Feature | Default | Description |
125//! |---------|---------|-------------|
126//! | `cli` | ✓ | Enables the `fernctl` binary with clap |
127//! | `fancy-errors` | ✓ | Enables colorful miette error output |
128//! | `watch` | ✗ | Enables file watching for live reload |
129//! | `dbus` | ✗ | Enables D-Bus IPC with QuickShell |
130//!
131//! ## Modules
132//!
133//! - [`domain`] — Core design language types (tokens, scales, themes)
134//! - [`error`] — Error types with rich diagnostics
135//! - [`ports`] — Interface traits for hexagonal architecture
136//! - [`adapters`] — Implementations connecting to external systems
137//!
138//! ## Design Decisions
139//!
140//! This crate makes several opinionated choices:
141//!
142//! 1. **No unsafe code** — The entire crate is `#![forbid(unsafe_code)]`
143//! 2. **No panics in library code** — All fallible operations return `Result`
144//! 3. **Comprehensive documentation** — Every public item is documented
145//! 4. **Type-level correctness** — Invalid states are unrepresentable
146//!
147//! For detailed rationale, see the module-level documentation in each submodule.
148
149#![doc(html_root_url = "https://docs.rs/fernctl/0.1.0")]
150#![cfg_attr(docsrs, feature(doc_cfg))]
151#![forbid(unsafe_code)]
152#![warn(
153 missing_docs,
154 missing_debug_implementations,
155 rust_2018_idioms,
156 unreachable_pub
157)]
158
159pub mod domain;
160pub mod error;
161pub mod ports;
162
163#[cfg(feature = "cli")]
164#[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
165pub mod adapters;
166
167#[cfg(feature = "cli")]
168#[cfg_attr(docsrs, doc(cfg(feature = "cli")))]
169pub mod commands;
170
171/// Convenient re-exports for common usage patterns.
172///
173/// Import this module to get started quickly:
174///
175/// ```rust,ignore
176/// use fernctl::prelude::*;
177/// ```
178pub mod prelude {
179 // Domain types
180 pub use crate::domain::theme::Theme;
181 pub use crate::domain::tokens::{
182 ColorToken,
183 BackgroundRole,
184 ForegroundRole,
185 AccentRole,
186 };
187
188 // Error types
189 pub use crate::error::{
190 FernError,
191 Result,
192 Severity,
193 };
194
195 // Port traits
196 pub use crate::ports::inbound::ConfigPort;
197 pub use crate::ports::outbound::NotifyPort;
198}
199
200/// Crate version from Cargo.toml.
201pub const VERSION: &str = env!("CARGO_PKG_VERSION");