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");