fraiseql_cli/
introspection.rs

1//! CLI introspection for AI agents
2//!
3//! Extracts command metadata from clap to enable machine-readable help output.
4
5use clap::Command;
6
7use crate::output::{ArgumentHelp, CliHelp, CommandHelp, CommandSummary, get_exit_codes};
8
9/// Extract complete CLI help from a clap Command
10pub fn extract_cli_help(cmd: &Command, version: &str) -> CliHelp {
11    CliHelp {
12        name:           cmd.get_name().to_string(),
13        version:        version.to_string(),
14        about:          cmd.get_about().map_or_else(String::new, ToString::to_string),
15        global_options: extract_global_options(cmd),
16        subcommands:    cmd
17            .get_subcommands()
18            .filter(|sub| !sub.is_hide_set())
19            .map(extract_command_help)
20            .collect(),
21        exit_codes:     get_exit_codes(),
22    }
23}
24
25/// Extract help for a single command
26pub fn extract_command_help(cmd: &Command) -> CommandHelp {
27    let (arguments, options) = extract_arguments(cmd);
28
29    CommandHelp {
30        name: cmd.get_name().to_string(),
31        about: cmd.get_about().map_or_else(String::new, ToString::to_string),
32        arguments,
33        options,
34        subcommands: cmd
35            .get_subcommands()
36            .filter(|sub| !sub.is_hide_set())
37            .map(extract_command_help)
38            .collect(),
39        examples: extract_examples(cmd),
40    }
41}
42
43/// List all available commands with summaries
44pub fn list_commands(cmd: &Command) -> Vec<CommandSummary> {
45    cmd.get_subcommands()
46        .filter(|sub| !sub.is_hide_set())
47        .map(|sub| CommandSummary {
48            name:            sub.get_name().to_string(),
49            description:     sub.get_about().map_or_else(String::new, ToString::to_string),
50            has_subcommands: sub.get_subcommands().count() > 0,
51        })
52        .collect()
53}
54
55/// Extract global options from the root command
56fn extract_global_options(cmd: &Command) -> Vec<ArgumentHelp> {
57    cmd.get_arguments()
58        .filter(|arg| arg.is_global_set())
59        .map(|arg| ArgumentHelp {
60            name:            arg.get_id().to_string(),
61            short:           arg.get_short().map(|c| format!("-{c}")),
62            long:            arg.get_long().map(|s| format!("--{s}")),
63            help:            arg.get_help().map_or_else(String::new, ToString::to_string),
64            required:        arg.is_required_set(),
65            default_value:   arg
66                .get_default_values()
67                .first()
68                .and_then(|v| v.to_str())
69                .map(String::from),
70            takes_value:     arg.get_num_args().is_some_and(|n| n.min_values() > 0),
71            possible_values: arg
72                .get_possible_values()
73                .iter()
74                .map(|v| v.get_name().to_string())
75                .collect(),
76        })
77        .collect()
78}
79
80/// Extract arguments and options from a command
81fn extract_arguments(cmd: &Command) -> (Vec<ArgumentHelp>, Vec<ArgumentHelp>) {
82    let mut arguments = Vec::new();
83    let mut options = Vec::new();
84
85    for arg in cmd.get_arguments() {
86        // Skip global arguments (they're listed separately)
87        if arg.is_global_set() {
88            continue;
89        }
90
91        // Skip the built-in help and version flags
92        let id = arg.get_id().as_str();
93        if id == "help" || id == "version" {
94            continue;
95        }
96
97        let arg_help = ArgumentHelp {
98            name:            arg.get_id().to_string(),
99            short:           arg.get_short().map(|c| format!("-{c}")),
100            long:            arg.get_long().map(|s| format!("--{s}")),
101            help:            arg.get_help().map_or_else(String::new, ToString::to_string),
102            required:        arg.is_required_set(),
103            default_value:   arg
104                .get_default_values()
105                .first()
106                .and_then(|v| v.to_str())
107                .map(String::from),
108            takes_value:     arg.get_num_args().is_some_and(|n| n.min_values() > 0),
109            possible_values: arg
110                .get_possible_values()
111                .iter()
112                .map(|v| v.get_name().to_string())
113                .collect(),
114        };
115
116        // Positional arguments have no short or long flag
117        if arg.get_short().is_none() && arg.get_long().is_none() {
118            arguments.push(arg_help);
119        } else {
120            options.push(arg_help);
121        }
122    }
123
124    (arguments, options)
125}
126
127/// Extract examples from command's after_help text
128fn extract_examples(cmd: &Command) -> Vec<String> {
129    // Look for EXAMPLES section in after_help
130    if let Some(after_help) = cmd.get_after_help() {
131        let text = after_help.to_string();
132        if let Some(examples_start) = text.find("EXAMPLES:") {
133            let examples_section = &text[examples_start + 9..];
134            return examples_section
135                .lines()
136                .map(str::trim)
137                .filter(|line| !line.is_empty() && line.starts_with("fraiseql"))
138                .map(String::from)
139                .collect();
140        }
141    }
142    Vec::new()
143}
fraiseql_cli/introspection.rs

fraiseql_cli/
introspection.rs
