docsrs_cli/cli/agent_args.rs
1//! Agent-native payload reduction flags, shared by every subcommand.
2//!
3//! # Why these live in their own struct
4//!
5//! Declaring *how much of the payload reaches the caller* is a different concern from
6//! declaring *how the request is made*. The transport knobs ([`crate::cli::Cli`]:
7//! timeouts, retries, cache) describe the fetch; these describe the emission. Keeping
8//! them apart means a reduction knob can be added without touching the transport
9//! surface, and [`crate::agent_ops`] takes one value instead of a growing argument list.
10//!
11//! # Query limits versus emission limits
12//!
13//! `search-in-crate --limit` and `search-crates --per-page` bound the **query**: they
14//! decide how much upstream work happens. [`AgentArgs::max_items`] bounds the
15//! **emission**: it decides how much of the already-computed result is written to
16//! stdout. The names differ because the things differ — and because a second `--limit`
17//! would collide, which clap rejects outright with "Long option names must be unique
18//! for each argument".
19
20use clap::Args;
21
22/// Payload reduction knobs applied to the JSON envelope before it is written.
23///
24/// Every field is `global = true`, so the flags are accepted before or after the
25/// subcommand. See [`crate::agent_ops`] for the fixed application order.
26#[derive(Debug, Clone, Default, Args)]
27pub struct AgentArgs {
28 /// Project only these dotted keys (CSV or repeated). Missing keys are skipped, never null
29 #[arg(long, visible_alias = "fields", global = true, value_delimiter = ',')]
30 pub select: Vec<String>,
31
32 /// Keep only matching elements: `key=value`, `key!=value`, `key~substring` (repeat = AND)
33 ///
34 /// A malformed expression fails with exit 65 instead of returning an empty set.
35 #[arg(long, global = true)]
36 pub filter: Vec<String>,
37
38 /// Sort elements ascending by this dotted key (stable; elements without it go last)
39 #[arg(long, global = true)]
40 pub sort_by: Option<String>,
41
42 /// Drop later elements repeating this key's value (elements without the key are kept)
43 #[arg(long, global = true)]
44 pub dedupe_by: Option<String>,
45
46 /// Emit at most N elements, counted after --filter and --dedupe-by (0 emits none)
47 ///
48 /// Bounds the emission, not the query: `search-in-crate --limit` is the query bound.
49 #[arg(long, global = true)]
50 pub max_items: Option<usize>,
51
52 /// Replace the payload with `{"count": N}`, counted after --filter, --dedupe-by and --max-items
53 #[arg(long, global = true)]
54 pub count_only: bool,
55
56 /// Shorten every string above N characters (never bytes; UTF-8 is never split)
57 #[arg(long, global = true)]
58 pub truncate_content: Option<usize>,
59
60 /// Cap emitted payload size in bytes (hard max 2097152 = 2 MiB; cannot raise above)
61 #[arg(long, global = true)]
62 pub max_output_bytes: Option<u64>,
63}