Expand description
§fernctl — Type-Safe Design Tokens for Fern Shell
fernctl is the core library for Fern Shell’s design system, providing
compile-time guarantees for design token correctness through Rust’s type system.
§Overview
This crate implements a hexagonal architecture (ports and adapters) where:
-
Domain Layer (
domain): Pure business logic with zero external dependencies. Contains type-safe design tokens, theme definitions, and validation rules. -
Ports (
ports): Trait-based interfaces that define how the domain interacts with the outside world, without depending on specific implementations. -
Adapters (
adapters): Concrete implementations that connect ports to external systems (file I/O, D-Bus, notifications). -
Error Handling (
error): Rich, user-friendly error types with diagnostic information for debugging configuration issues.
§Design Philosophy
Traditional design systems define tokens as stringly-typed values:
button.background = "#1e1e2e" // Is this a valid background color?
button.radius = 9999 // Is this valid for buttons?These questions are answered at runtime (if at all), leading to subtle bugs.
fernctl encodes design system rules in the type system:
// ColorToken<Surface> can only be used where BackgroundRole is expected
button.background: ColorToken<Surface> // ✓ Compiles
button.background: ColorToken<Foreground> // ✗ Type error!
// ButtonRadius trait limits which radii are valid for buttons
button.radius: RadiusMd // ✓ Compiles (Md implements ButtonRadius)
button.radius: RadiusFull // ✗ Type error! (Full doesn't implement ButtonRadius)§Architecture Diagram
┌─────────────────────────────────┐
│ DRIVING ADAPTERS │
│ ┌──────┐ ┌─────┐ ┌──────┐ │
│ │ TOML │ │ CLI │ │ JSON │ │
│ └──┬───┘ └──┬──┘ └──┬───┘ │
│ │ │ │ │
│ ┌──▼─────────▼────────▼───┐ │
│ │ INBOUND PORTS │ │
│ │ ConfigPort, QueryPort │ │
│ └───────────┬─────────────┘ │
┌──────────────────────┼──────────────▼─────────────────┐│
│ │ DOMAIN ││
│ ┌───────────────────┴──────────────────────────────┐ ││
│ │ DESIGN LANGUAGE │ ││
│ │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ ││
│ │ │ Tokens │ │ Scales │ │ Components │ │ ││
│ │ │ Color │ │ Spacing │ │ ButtonSpec │ │ ││
│ │ │ Radius │ │ Radius │ │ ModuleSpec │ │ ││
│ │ └──────────┘ └──────────┘ └──────────────┘ │ ││
│ │ │ │ ││
│ │ ┌────▼────┐ │ ││
│ │ │ Theme │ │ ││
│ │ └─────────┘ │ ││
│ └──────────────────────────────────────────────────┘ ││
│ │ ││
│ ┌──────────────────────▼───────────────────────────┐ ││
│ │ OUTBOUND PORTS │ ││
│ │ PersistPort, NotifyPort, IpcPort │ ││
│ └──────────────────────┬───────────────────────────┘ ││
└─────────────────────────┼─────────────────────────────┘│
│ │ │
│ ┌──▼─────────────────────────┐ │
│ │ DRIVEN ADAPTERS │ │
│ │ ┌────────┐ ┌─────┐ ┌─────┐ │ │
│ │ │ File │ │D-Bus│ │Notif│ │ │
│ │ │ System │ │ IPC │ │ │ │ │
│ │ └────────┘ └─────┘ └─────┘ │ │
│ └────────────────────────────┘ │
└─────────────────────────────────┘§Quick Start
§Loading Configuration
use fernctl::prelude::*;
use fernctl::adapters::TomlConfigAdapter;
// Load and validate a TOML configuration
let toml_content = std::fs::read_to_string("config.toml")?;
let adapter = TomlConfigAdapter::new();
// Type-state ensures we can't use config before validation
let raw = adapter.parse(&toml_content)?; // Config<Parsed>
let validated = raw.validate()?; // Config<Validated>
let theme = validated.into_theme(); // Theme§Using Design Tokens
use fernctl::domain::tokens::*;
// Create type-safe colors
let surface: ColorToken<Surface> = ColorToken::from_hex("#313244")?;
let text: ColorToken<Foreground> = ColorToken::from_hex("#cdd6f4")?;
// The type system prevents misuse:
fn set_background(color: impl BackgroundRole) { /* ... */ }
set_background(surface); // ✓ Works - Surface is a BackgroundRole
// set_background(text); // ✗ Won't compile - Foreground is not BackgroundRole§Feature Flags
| Feature | Default | Description |
|---|---|---|
cli | ✓ | Enables the fernctl binary with clap |
fancy-errors | ✓ | Enables colorful miette error output |
watch | ✗ | Enables file watching for live reload |
dbus | ✗ | Enables D-Bus IPC with QuickShell |
§Modules
domain— Core design language types (tokens, scales, themes)error— Error types with rich diagnosticsports— Interface traits for hexagonal architectureadapters— Implementations connecting to external systems
§Design Decisions
This crate makes several opinionated choices:
- No unsafe code — The entire crate is
#![forbid(unsafe_code)] - No panics in library code — All fallible operations return
Result - Comprehensive documentation — Every public item is documented
- Type-level correctness — Invalid states are unrepresentable
For detailed rationale, see the module-level documentation in each submodule.
Modules§
- adapters
- Adapters — External System Integration
- commands
- CLI Command Implementations
- domain
- Domain Layer — The Core Design Language
- error
- Error Handling for Fern Shell
- ports
- Ports — Hexagonal Architecture Interfaces
- prelude
- Convenient re-exports for common usage patterns.
Constants§
- VERSION
- Crate version from Cargo.toml.