Skip to main content

clap_noun_verb/
lib.rs

1//! clap-noun-verb - A framework for building composable CLI patterns
2//!
3//! This crate provides a high-level, ergonomic API for building noun-verb CLI patterns
4//! on top of clap, similar to how Python's Typer provides a simpler interface over Click.
5//!
6//! ## Minimal Dependencies
7//!
8//! By default, clap-noun-verb compiles with **only 10 core dependencies** for basic CLI:
9//! - `clap` - CLI framework
10//! - `clap-noun-verb-macros` - Our proc macros
11//! - `linkme` - Auto-discovery
12//! - `serde`, `serde_json` - JSON output
13//! - `thiserror`, `anyhow` - Error handling
14//! - `once_cell`, `lazy_static`, `atty` - Utilities
15//!
16//! All advanced features are opt-in via cargo features:
17//! - `full` - Enable all features
18//! - `autonomic` - Agent introspection & telemetry spans
19//! - `async` - Async handlers (tokio, futures)
20//! - `io` - Advanced I/O (clio)
21//! - `crypto` - Cryptographic hashing (sha2, sha3, blake3)
22//! - `agent2028` - Trillion-agent ecosystems
23//! - `rdf` - RDF/Ontology with MCP
24//! - `kernel` - Deterministic execution
25//!
26//! ## Version 5.3.0 Architecture
27//!
28//! - **Attribute Macros** (`clap-noun-verb-macros`) - `#[verb]` for declarative command registration
29//! - **Auto-Discovery** - Commands automatically discovered using `linkme` distributed slices
30//! - **Type Inference** - Arguments automatically inferred from function signatures
31//! - **JSON Output** - All output automatically serialized to JSON
32//!
33//! ### Key Principles
34//!
35//! 1. **Zero Boilerplate** - Just add `#[verb]` attributes to functions
36//! 2. **Auto-Discovery** - Commands automatically discovered at compile time
37//! 3. **Type Inference** - Arguments inferred from function signatures
38//! 4. **JSON by Default** - Perfect for agents, MCP, and modern tooling
39//! 5. **Minimal Dependencies** - Core CLI needs only 9 crates
40//!
41//! ## API Stability
42//!
43//! This crate follows [Semantic Versioning](https://semver.org/). Version 5.3.0 provides:
44//!
45//! - **Public APIs** are stable within the same major version
46//! - **Breaking changes** only in major version bumps
47//! - **Feature flags** are stable - won't be removed without deprecation
48
49// =============================================================================
50// CORE MODULES - Always available (no feature flags)
51// =============================================================================
52
53pub mod builder;
54pub mod cli;
55pub mod error;
56pub mod logic;
57pub mod macros;
58pub mod noun;
59pub mod registry;
60pub mod router;
61pub mod runtime;
62pub mod tree;
63pub mod verb;
64
65// Capability Discovery Engine (requires agent2028 feature for swarm optimization)
66#[cfg(feature = "agent2028")]
67pub mod macros_discovery_engine;
68
69// =============================================================================
70// OPTIONAL MODULES - Feature-gated for minimal compile burden
71// =============================================================================
72
73// Async verb support (requires "async" feature)
74#[cfg(feature = "async")]
75pub mod async_verb;
76
77// Shell completion generation (requires "completions" feature)
78#[cfg(feature = "completions")]
79pub mod completion;
80
81// Configuration formats (requires "config-formats" feature)
82#[cfg(feature = "config-formats")]
83pub mod config;
84
85// Execution context
86pub mod context;
87
88// Deprecation warnings
89pub mod deprecation;
90
91// Output formatting
92pub mod format;
93
94// Man page generation (requires "mangen" feature)
95#[cfg(feature = "mangen")]
96pub mod mangen;
97
98// Shell utilities
99pub mod shell;
100
101// URL/Regex validators (requires "validators" feature)
102#[cfg(feature = "validators")]
103pub mod validators;
104
105// Autonomic CLI Layer (requires "autonomic" feature)
106#[cfg(feature = "autonomic")]
107pub mod autonomic;
108
109// CNV Kernel Capabilities (requires "kernel" feature)
110#[cfg(feature = "kernel")]
111pub mod kernel;
112
113// I/O Integration (requires "io" feature)
114#[cfg(feature = "io")]
115pub mod io;
116
117// Advanced clap Integration
118pub mod clap_ext;
119
120// Plugin System (requires "full" feature)
121#[cfg(feature = "full")]
122pub mod plugin;
123
124// Middleware System (requires "full" feature)
125#[cfg(feature = "full")]
126pub mod middleware;
127
128// Telemetry & Observability (requires "observability" feature)
129#[cfg(feature = "observability")]
130pub mod telemetry;
131
132// Integration Layer (requires "full" feature)
133#[cfg(feature = "full")]
134pub mod integration;
135
136// Production Plugins (requires "full" feature)
137#[cfg(feature = "full")]
138pub mod plugins;
139
140// Agent2028 - Trillion-Agent Ecosystems (requires "agent2028" feature)
141#[cfg(feature = "agent2028")]
142pub mod agent2028;
143
144// RDF/Ontology Control Layer (requires "rdf" feature)
145#[cfg(feature = "rdf")]
146pub mod rdf;
147
148// Semantic Agent Coordinator (requires "agent2028" feature + optional "rdf", "autonomic")
149#[cfg(feature = "agent2028")]
150pub mod agents;
151
152// Semantic CLI Composition (requires "rdf" feature for SPARQL and RDF metadata)
153#[cfg(feature = "rdf")]
154pub mod semantic;
155
156// Frontier Packages - 10 Advanced Agent-Grade Packages (v5.4+)
157// Requires any frontier feature (meta-framework, rdf-composition, etc.)
158#[cfg(any(
159    feature = "meta-framework",
160    feature = "rdf-composition",
161    feature = "executable-specs",
162    feature = "fractal-patterns",
163    feature = "discovery-engine",
164    feature = "federated-network",
165    feature = "learning-trajectories",
166    feature = "reflexive-testing",
167    feature = "economic-sim",
168    feature = "quantum-ready"
169))]
170pub mod frontier;
171
172// Wizard - Interactive multi-step CLI workflows with AI assistance (requires "wizard" feature)
173#[cfg(feature = "wizard")]
174pub mod wizard;
175
176// Procedural macros are available as attributes: #[clap_noun_verb::noun] and #[clap_noun_verb::verb]
177// They don't need to be re-exported - they're used directly as attributes
178
179// =============================================================================
180// PUBLIC RE-EXPORTS - Core types always available
181// =============================================================================
182
183// Re-export CLI run function for convenience
184pub use cli::run;
185
186// Core framework types
187pub use builder::{build_cli, run_cli, run_cli_with_args, CliBuilder};
188pub use error::{NounVerbError, Result};
189pub use noun::{CompoundNounCommand, NounCommand, NounContext};
190pub use registry::CommandRegistry;
191pub use router::CommandRouter;
192pub use tree::{CommandTree, CommandTreeBuilder};
193pub use verb::{VerbArgs, VerbCommand, VerbContext};
194
195// Context and formatting (always available)
196pub use context::AppContext;
197pub use deprecation::{Deprecation, DeprecationType};
198pub use format::{format_output, OutputFormat};
199
200// Re-export clap types so users don't need clap as a direct dependency
201// This follows the facade pattern used by serde, tokio, and tracing
202// Note: These are from clap's builder module (the main clap crate re-exports these)
203pub use clap::{Arg, ArgAction, ArgMatches, Command};
204
205// =============================================================================
206// FEATURE-GATED RE-EXPORTS
207// =============================================================================
208
209// Async support (requires "async" feature)
210#[cfg(feature = "async")]
211pub use async_verb::{create_runtime, run_async};
212
213// Shell completion (requires "completions" feature)
214#[cfg(feature = "completions")]
215pub use completion::{generate_completion, print_completion, Shell};
216
217// Macros are exported at crate root via #[macro_export]
218
219// Framework-level re-exports for easy composition
220pub use builder::CliBuilder as Cli;
221pub use registry::CommandRegistry as Registry;
222pub use tree::CommandTree as Tree;
223pub mod agent_cli;