talon/
cli.rs

1//! Command-line interface (`clap` derive).
2
3use std::path::PathBuf;
4
5use clap::{Args, Parser, Subcommand};
6
7/// `talon` — automated AI SOC analyst for CoPilot.
8#[derive(Debug, Parser)]
9#[command(name = "talon", version, about, long_about = None)]
10pub struct Cli {
11    /// Talon project directory (holds `.env`, `groups/`, `store/`, `data/`).
12    /// Defaults to the current directory.
13    #[arg(long, global = true, env = "TALON_PROJECT_ROOT", value_name = "DIR")]
14    pub project_root: Option<PathBuf>,
15
16    /// Subcommand; `run` when omitted.
17    #[command(subcommand)]
18    pub command: Option<Command>,
19}
20
21/// Top-level subcommands.
22#[derive(Debug, Subcommand, PartialEq)]
23pub enum Command {
24    /// Run the orchestrator (default).
25    Run,
26    /// Run a setup step (`timezone`, `environment`, `vllm`, `container`,
27    /// `groups`, `register`, `mounts`, `service`, `verify`).
28    Setup(SetupArgs),
29    /// Diagnose the environment: container runtime, image, vLLM, LLM
30    /// gateway, directories, audit chain.
31    Doctor,
32    /// Inspect the hash-chained audit log.
33    Audit {
34        /// Audit subcommand.
35        #[command(subcommand)]
36        command: AuditCommand,
37    },
38    /// Score investigation quality against the golden set
39    /// (`evals/golden/`): offline from saved reports, or online through a
40    /// running Talon.
41    Eval {
42        /// Eval subcommand.
43        #[command(subcommand)]
44        command: EvalCommand,
45    },
46    /// Print the version.
47    Version,
48}
49
50/// `talon eval` subcommands.
51#[derive(Debug, Subcommand, PartialEq)]
52pub enum EvalCommand {
53    /// Offline: score already-produced reports (`<case id>.json`) against
54    /// the golden cases. Exit code 1 when the pass rate is below
55    /// `--min-pass-rate`, 2 on unusable input.
56    Score(EvalScoreArgs),
57    /// Online: submit every golden case to a running Talon
58    /// (`POST /investigate`), wait for each verdict, then score. The
59    /// case's alert must already exist in the CoPilot stack Talon is
60    /// connected to.
61    Run(EvalRunArgs),
62}
63
64/// Options shared by the `talon eval` modes.
65#[derive(Debug, Args, PartialEq)]
66pub struct EvalCommonArgs {
67    /// Directory of golden case files (default: `<project root>/evals/golden`).
68    #[arg(long, value_name = "DIR")]
69    pub cases: Option<PathBuf>,
70    /// Print the summary as JSON instead of a table.
71    #[arg(long)]
72    pub json: bool,
73    /// Lowest acceptable fraction of passing cases, `0.0`–`1.0`.
74    #[arg(long, value_name = "FRACTION", default_value_t = 1.0, value_parser = parse_pass_rate)]
75    pub min_pass_rate: f64,
76}
77
78/// Arguments of `talon eval score`.
79#[derive(Debug, Args, PartialEq)]
80pub struct EvalScoreArgs {
81    /// Directory holding one `<case id>.json` per case: a triage report, or
82    /// an investigation record as returned by `GET /investigations/{id}`.
83    #[arg(long, value_name = "DIR")]
84    pub reports: PathBuf,
85    /// Shared options.
86    #[command(flatten)]
87    pub common: EvalCommonArgs,
88}
89
90/// Arguments of `talon eval run`.
91#[derive(Debug, Args, PartialEq)]
92pub struct EvalRunArgs {
93    /// Base URL of the Talon HTTP API (default:
94    /// `http://<COPILOT_HTTP_BIND>:<COPILOT_HTTP_PORT>` from the project's
95    /// `.env`). The API key is always `HTTP_API_KEY` from `.env`.
96    #[arg(long, value_name = "URL")]
97    pub url: Option<String>,
98    /// Seconds to wait for each investigation's verdict.
99    #[arg(long, value_name = "SECONDS", default_value_t = 900, value_parser = clap::value_parser!(u64).range(1..))]
100    pub timeout_secs: u64,
101    /// Seconds between status polls.
102    #[arg(long, value_name = "SECONDS", default_value_t = 5, value_parser = clap::value_parser!(u64).range(1..))]
103    pub poll_secs: u64,
104    /// JSON file mapping case ids to the alert ids they are seeded under
105    /// in the target stack (`{"<case id>": 4711, ...}`); overrides the
106    /// case's `request.alert_id`.
107    #[arg(long, value_name = "FILE")]
108    pub alert_map: Option<PathBuf>,
109    /// Customer code to submit instead of each case's
110    /// `request.customer_code`.
111    #[arg(long, value_name = "CODE")]
112    pub customer_code: Option<String>,
113    /// Write each investigation record to `<DIR>/<case id>.json`, in the
114    /// form `talon eval score --reports <DIR>` reads.
115    #[arg(long, value_name = "DIR")]
116    pub save_dir: Option<PathBuf>,
117    /// Score the existing job when Talon de-duplicates a trigger instead of
118    /// failing the case (the verdict may predate the change under test).
119    #[arg(long)]
120    pub allow_deduplicated: bool,
121    /// Shared options.
122    #[command(flatten)]
123    pub common: EvalCommonArgs,
124}
125
126fn parse_pass_rate(raw: &str) -> Result<f64, String> {
127    match raw.trim().parse::<f64>() {
128        Ok(v) if (0.0..=1.0).contains(&v) => Ok(v),
129        _ => Err("expected a fraction between 0.0 and 1.0".to_string()),
130    }
131}
132
133/// Arguments of `talon setup`.
134#[derive(Debug, Args, PartialEq, Eq)]
135pub struct SetupArgs {
136    /// Step name.
137    pub step: String,
138    /// Step arguments, passed through verbatim (e.g. `--tz Europe/Berlin`).
139    #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
140    pub args: Vec<String>,
141}
142
143/// `talon audit` subcommands.
144#[derive(Debug, Subcommand, PartialEq, Eq)]
145pub enum AuditCommand {
146    /// Verify the chain (and, with `TALON_AUDIT_KEY`, its MACs and the
147    /// truncation checkpoint); exit code 1 if anything does not verify.
148    Verify,
149    /// Print the newest row's id, hash and sequence number, for anchoring
150    /// the chain on a system this host cannot write.
151    Head,
152    /// Print recent audit events (oldest first) as JSON lines.
153    Tail {
154        /// Number of events.
155        #[arg(short = 'n', long = "lines", default_value_t = 50)]
156        lines: usize,
157        /// Only events whose kind starts with this prefix (e.g. `ipc.`).
158        #[arg(long)]
159        kind: Option<String>,
160    },
161}
162
163impl Cli {
164    /// The subcommand to run (`run` when none was given).
165    pub fn command(&self) -> &Command {
166        self.command.as_ref().unwrap_or(&Command::Run)
167    }
168
169    /// Project root: `--project-root`, `TALON_PROJECT_ROOT`, else the
170    /// current directory.
171    pub fn resolve_project_root(&self) -> std::io::Result<PathBuf> {
172        match &self.project_root {
173            Some(p) if p.is_absolute() => Ok(p.clone()),
174            Some(p) => Ok(std::env::current_dir()?.join(p)),
175            None => std::env::current_dir(),
176        }
177    }
178}
179
180#[cfg(test)]
181mod tests {
182    use super::*;
183
184    fn parse(args: &[&str]) -> Cli {
185        Cli::try_parse_from(args).unwrap()
186    }
187
188    #[test]
189    fn defaults_to_run() {
190        let cli = parse(&["talon"]);
191        assert_eq!(cli.command(), &Command::Run);
192        assert_eq!(parse(&["talon", "run"]).command(), &Command::Run);
193    }
194
195    #[test]
196    fn setup_passes_hyphenated_args_through() {
197        let cli = parse(&[
198            "talon",
199            "setup",
200            "timezone",
201            "--tz",
202            "Europe/Berlin",
203            "--force",
204        ]);
205        assert_eq!(
206            cli.command(),
207            &Command::Setup(SetupArgs {
208                step: "timezone".into(),
209                args: vec!["--tz".into(), "Europe/Berlin".into(), "--force".into()],
210            })
211        );
212    }
213
214    #[test]
215    fn audit_subcommands() {
216        assert_eq!(
217            parse(&["talon", "audit", "verify"]).command(),
218            &Command::Audit {
219                command: AuditCommand::Verify
220            }
221        );
222        assert_eq!(
223            parse(&["talon", "audit", "head"]).command(),
224            &Command::Audit {
225                command: AuditCommand::Head
226            }
227        );
228        assert_eq!(
229            parse(&["talon", "audit", "tail", "-n", "5", "--kind", "ipc."]).command(),
230            &Command::Audit {
231                command: AuditCommand::Tail {
232                    lines: 5,
233                    kind: Some("ipc.".into())
234                }
235            }
236        );
237        assert_eq!(
238            parse(&["talon", "audit", "tail"]).command(),
239            &Command::Audit {
240                command: AuditCommand::Tail {
241                    lines: 50,
242                    kind: None
243                }
244            }
245        );
246    }
247
248    #[test]
249    fn eval_subcommands() {
250        let Some(Command::Eval {
251            command: EvalCommand::Score(score),
252        }) = parse(&["talon", "eval", "score", "--reports", "out"]).command
253        else {
254            panic!("expected eval score");
255        };
256        assert_eq!(score.reports, PathBuf::from("out"));
257        assert_eq!(score.common.cases, None);
258        assert!(!score.common.json);
259        assert!((score.common.min_pass_rate - 1.0).abs() < f64::EPSILON);
260
261        let Some(Command::Eval {
262            command: EvalCommand::Run(run),
263        }) = parse(&[
264            "talon",
265            "eval",
266            "run",
267            "--cases",
268            "c",
269            "--json",
270            "--min-pass-rate",
271            "0.8",
272            "--timeout-secs",
273            "60",
274            "--alert-map",
275            "map.json",
276            "--allow-deduplicated",
277        ])
278        .command
279        else {
280            panic!("expected eval run");
281        };
282        assert_eq!(run.common.cases, Some(PathBuf::from("c")));
283        assert!(run.common.json && run.allow_deduplicated);
284        assert!((run.common.min_pass_rate - 0.8).abs() < f64::EPSILON);
285        assert_eq!((run.timeout_secs, run.poll_secs), (60, 5));
286        assert_eq!(run.alert_map, Some(PathBuf::from("map.json")));
287        assert_eq!(
288            (run.url, run.save_dir, run.customer_code),
289            (None, None, None)
290        );
291
292        let bad: [&[&str]; 5] = [
293            &["talon", "eval"],
294            &["talon", "eval", "score"],
295            &[
296                "talon",
297                "eval",
298                "score",
299                "--reports",
300                "o",
301                "--min-pass-rate",
302                "1.5",
303            ],
304            &[
305                "talon",
306                "eval",
307                "score",
308                "--reports",
309                "o",
310                "--min-pass-rate",
311                "NaN",
312            ],
313            &["talon", "eval", "run", "--timeout-secs", "0"],
314        ];
315        for args in bad {
316            assert!(Cli::try_parse_from(args).is_err(), "{args:?}");
317        }
318    }
319
320    #[test]
321    fn project_root_flag_is_global() {
322        let cli = parse(&["talon", "doctor", "--project-root", "/srv/talon"]);
323        assert_eq!(cli.command(), &Command::Doctor);
324        assert_eq!(
325            cli.resolve_project_root().unwrap(),
326            PathBuf::from("/srv/talon")
327        );
328    }
329
330    #[test]
331    fn unknown_command_is_rejected() {
332        assert!(Cli::try_parse_from(["talon", "frobnicate"]).is_err());
333    }
334}
talon/cli.rs

talon/
cli.rs
