argot_cmd/
lib.rs

1//! # argot
2//!
3//! An agent-first command interface framework for Rust.
4//!
5//! argot makes it easy to define structured CLI commands that are equally
6//! useful for human operators and AI agents. Every command carries rich
7//! metadata — summaries, descriptions, typed arguments, flags, examples, and
8//! best-practice guidance — that can be serialized to JSON or rendered as
9//! Markdown for consumption by an LLM tool-call layer.
10//!
11//! ## Architecture
12//!
13//! The library is built around five cooperating layers:
14//!
15//! 1. **[`model`]** — the data model: [`Command`], [`Argument`], [`Flag`],
16//!    [`Example`], and their builders.
17//! 2. **[`resolver`]** — maps a raw string token to a [`Command`] via exact →
18//!    prefix → ambiguous resolution.
19//! 3. **[`parser`]** — tokenizes a raw `argv` slice, walks the subcommand tree
20//!    using the resolver, then binds flags and positional arguments.
21//! 4. **[`query`]** — [`Registry`] is the central command store; it supports
22//!    lookup by canonical name, subcommand path, substring search, and fuzzy
23//!    search.
24//! 5. **[`render`]** — three plain-text / Markdown renderers: [`render_help`],
25//!    [`render_subcommand_list`], and [`render_markdown`].
26//!
27//! A convenience [`cli`] module provides the [`Cli`] struct, which wires all
28//! five layers together so you can go from `Vec<Command>` to a fully
29//! functional CLI dispatch loop in a few lines.
30//!
31//! ## Quick Start
32//!
33//! ```no_run
34//! use std::sync::Arc;
35//! use argot_cmd::{Command, Flag, Registry, Parser, render_help};
36//!
37//! // 1. Build commands.
38//! let cmd = Command::builder("deploy")
39//!     .summary("Deploy the application to an environment")
40//!     .flag(
41//!         Flag::builder("env")
42//!             .description("Target environment")
43//!             .takes_value()
44//!             .required()
45//!             .build()
46//!             .unwrap(),
47//!     )
48//!     .handler(Arc::new(|parsed| {
49//!         println!("deploying to {}", parsed.flags["env"]);
50//!         Ok(())
51//!     }))
52//!     .build()
53//!     .unwrap();
54//!
55//! // 2. Store in a registry.
56//! let registry = Registry::new(vec![cmd]);
57//!
58//! // 3. Parse raw arguments.
59//! let parser = Parser::new(registry.commands());
60//! let parsed = parser.parse(&["deploy", "--env", "production"]).unwrap();
61//!
62//! // 4. Render help.
63//! let help = render_help(parsed.command);
64//! println!("{}", help);
65//! ```
66//!
67//! ## Feature Flags
68//!
69//! | Feature   | Description |
70//! |-----------|-------------|
71//! | `derive`  | Enables the `#[derive(ArgotCommand)]` proc-macro from `argot-cmd-derive`. |
72//! | `fuzzy`   | Enables [`Registry::fuzzy_search`] via the `fuzzy-matcher` crate.    |
73//! | `mcp`     | Enables the MCP stdio transport server ([`transport`]).               |
74//!
75//! ## Modules
76//!
77//! - [`cli`] — high-level [`Cli`] entry point
78//! - [`model`] — data model and builders
79//! - [`resolver`] — string-to-command resolution
80//! - [`parser`] — `argv` parsing
81//! - [`query`] — command registry and search
82//! - [`render`] — human-readable and Markdown output
83
84#![forbid(unsafe_code)]
85#![warn(missing_docs)]
86
87pub mod cli;
88pub mod middleware;
89pub mod model;
90pub mod parser;
91pub mod query;
92pub mod render;
93pub mod resolver;
94
95pub use cli::{Cli, CliError};
96pub use middleware::Middleware;
97
98pub use model::{
99    Argument, ArgumentBuilder, BuildError, Command, CommandBuilder, Example, Flag, FlagBuilder,
100    HandlerFn, ParsedCommand,
101};
102
103#[cfg(feature = "async")]
104pub use model::AsyncHandlerFn;
105pub use parser::{ParseError, Parser};
106pub use query::{CommandEntry, QueryError, Registry};
107pub use render::{
108    render_ambiguity, render_completion, render_docs, render_help, render_json_schema,
109    render_markdown, render_resolve_error, render_subcommand_list, DefaultRenderer, Renderer,
110    Shell,
111};
112pub use resolver::{ResolveError, Resolver};
113
114/// Trait implemented by types annotated with `#[derive(ArgotCommand)]`.
115///
116/// Call `T::command()` to obtain a fully-built [`Command`] from the struct's
117/// `#[argot(...)]` attributes.
118///
119/// # Examples
120///
121/// ```
122/// # #[cfg(feature = "derive")] {
123/// use argot_cmd::ArgotCommand;
124///
125/// #[derive(argot_cmd::ArgotCommand)]
126/// #[argot(summary = "Greet the world")]
127/// struct Greet;
128///
129/// let cmd = Greet::command();
130/// assert_eq!(cmd.canonical, "greet");
131/// # }
132/// ```
133pub trait ArgotCommand {
134    /// Return the [`Command`] described by this type's `#[argot(...)]`
135    /// attributes.
136    fn command() -> Command;
137}
138
139#[cfg(feature = "derive")]
140pub use argot_cmd_derive::ArgotCommand;
141
142/// MCP (Model Context Protocol) stdio transport server.
143///
144/// Enable with the `mcp` feature flag. Exposes the command registry as MCP
145/// tools over a newline-delimited JSON-RPC 2.0 stream.
146#[cfg(feature = "mcp")]
147pub mod transport;
148#[cfg(feature = "mcp")]
149pub use transport::McpServer;
argot_cmd/lib.rs

argot_cmd/
lib.rs
