Skip to main content

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}