flodl_cli/
lib.rs

1//! flodl-cli — library side of the `fdl` binary.
2//!
3//! This crate is both a library and a binary. The binary (`fdl`) is the
4//! user-facing driver; the library exposes the pieces that other crates
5//! (e.g. a flodl-based training binary) need to integrate with the
6//! `fdl` ecosystem:
7//!
8//! - [`FdlArgs`] — derive macro + trait for argv parsing and schema emission
9//! - [`parse_or_schema`] — intercepts `--fdl-schema` / `--help` and dispatches
10//! - [`Schema`], [`OptionSpec`], [`ArgSpec`] — the canonical schema shape
11//!
12//! # Example
13//!
14//! ```no_run
15//! use flodl_cli::{FdlArgs, parse_or_schema};
16//!
17//! /// My training binary.
18//! #[derive(FdlArgs, Debug)]
19//! struct Cli {
20//!     /// Model to run.
21//!     #[option(short = 'm', default = "all")]
22//!     model: String,
23//!
24//!     /// Write a report instead of training.
25//!     #[option(default = "runs/report.md")]
26//!     report: Option<String>,
27//! }
28//!
29//! fn main() {
30//!     let cli: Cli = parse_or_schema();
31//!     // ... use cli.model, cli.report, etc.
32//! }
33//! ```
34
35// Self-alias: the `#[derive(FdlArgs)]` macro emits `::flodl_cli::...`
36// paths. That resolves automatically when the derive is used from a
37// downstream crate (or from `main.rs`, which sees the lib as an external
38// dep), but inside the library itself the compiler only knows the
39// crate by its `crate`-root name. The alias makes `::flodl_cli::...`
40// resolve to ourselves so `builtins.rs` can derive the same trait.
41extern crate self as flodl_cli;
42
43// Internal modules — shared by lib consumers and the fdl binary.
44
45/// Structured API reference for flodl itself (`fdl api-ref`), used by
46/// AI porting tools and as a machine-readable surface index.
47pub mod api_ref;
48
49/// Argv parsing primitives and the [`FdlArgsTrait`](args::FdlArgsTrait)
50/// contract that `#[derive(FdlArgs)]` implements.
51pub mod args;
52
53/// Built-in `fdl` sub-commands (setup, install, completions, schema,
54/// config, libtorch, diagnose, init, skill, ...).
55pub mod builtins;
56
57/// Shell completion script generation and per-project completion
58/// enrichment driven by cached schemas.
59pub mod completions;
60
61/// `fdl.yml` manifest loading, validation, and resolved-command types.
62pub mod config;
63
64/// Cross-cutting context passed to sub-command handlers (resolved config,
65/// verbosity, overlay selection, working directory, ...).
66pub mod context;
67
68/// Top-level command dispatch: routing argv to built-ins vs. manifest
69/// entries, resolving the three command kinds (run / path / preset).
70pub mod dispatch;
71
72/// Hardware and compatibility diagnostics (`fdl diagnose`).
73pub mod diagnose;
74
75/// Project scaffolding (`fdl init`): generates Dockerfile, `fdl.yml`,
76/// training template, `.gitignore`.
77pub mod init;
78
79/// libtorch variant management (download, build, list, activate, remove,
80/// info) used by both `fdl libtorch` and the standalone-manager flow.
81pub mod libtorch;
82
83/// Environment overlay loader (`--env`, `FDL_ENV`, first-arg convention)
84/// with per-field origin annotations for `fdl config show`.
85pub mod overlay;
86
87/// Runtime: invoking resolved commands, streaming their output, and
88/// mapping exit codes through `fdl`.
89pub mod run;
90
91/// `fdl schema` sub-command: discover every cache under the project,
92/// report fresh / stale / orphan states, and clear or refresh on
93/// demand. The [`Schema`] type itself lives in [`config`].
94pub mod schema;
95
96/// `--fdl-schema` binary contract and per-command cache mechanics.
97/// Caches live at `<cmd_dir>/.fdl/schema-cache/<cmd>.json` with
98/// mtime + binary hash metadata for staleness detection.
99pub mod schema_cache;
100
101/// First-run and reconfiguration wizard (`fdl setup`).
102pub mod setup;
103
104/// AI-skill bundles: packaging and installing the `/port` skill and
105/// similar assistant integrations.
106pub mod skill;
107
108/// ANSI styling primitives and the `--ansi` / `--no-ansi` / `NO_COLOR`
109/// resolution chain used by the help renderer and CLI output.
110pub mod style;
111
112/// Miscellaneous helpers shared by the other modules.
113pub mod util;
114
115/// Print a red-prefixed `error: <formatted>` line to stderr.
116///
117/// Takes standard `format!` arguments. Coloring follows the `--ansi` /
118/// `--no-ansi` / `NO_COLOR` / `FORCE_COLOR` chain via
119/// [`style::color_enabled`], so pipes stay plain automatically.
120#[macro_export]
121macro_rules! cli_error {
122    ($($arg:tt)*) => {
123        $crate::style::print_cli_error(format_args!($($arg)*))
124    };
125}
126
127// ── Public API for binary authors ──────────────────────────────────────
128
129/// Parse argv into `T`, intercepting `--fdl-schema` and `--help`.
130pub use args::parse_or_schema;
131
132/// Slice-based variant of [`parse_or_schema`] — parses from an explicit
133/// `&[String]` rather than `std::env::args()`. Used by the `fdl` driver to
134/// dispatch per-sub-command arg tails.
135pub use args::parse_or_schema_from;
136
137/// Trait implemented by `#[derive(FdlArgs)]` structs. Binary authors do
138/// not typically implement this manually — the derive emits it.
139pub use args::FdlArgsTrait;
140
141/// Derive macro for `FdlArgs`. Generates argv parsing, `--fdl-schema`
142/// emission, and `--help` rendering from a single struct definition.
143pub use flodl_cli_macros::FdlArgs;
144
145/// Schema types — mirror the JSON shape emitted by `--fdl-schema` and
146/// consumed by the fdl driver.
147pub use config::{ArgSpec, OptionSpec, Schema};
148
149/// Re-exported dependencies the derive macro needs to reference by path.
150/// Users should not depend on these directly — they are only stable as
151/// an implementation detail of the derive.
152#[doc(hidden)]
153pub use serde_json;
flodl_cli/lib.rs

flodl_cli/
lib.rs
