obz_core/
descriptor.rs

1//! Extension command and flag descriptors.
2//!
3//! These pure data structs allow providers to declare their extension
4//! commands and provider-specific flags without depending on clap.
5//! The obz shell reads these descriptors at startup and registers them
6//! as real clap subcommands and arguments, giving full tab-completion
7//! and `--help` support.
8//!
9//! # Design contract
10//!
11//! Every field in [`FlagDescriptor`] maps directly to a clap argument
12//! attribute. obz must be able to losslessly convert a `FlagDescriptor`
13//! into a `clap::Arg` without losing any information.
14
15/// The value type of a provider-specific flag.
16///
17/// Maps to clap's `value_parser` and determines the Rust type used when
18/// obz reads the parsed value back out of `ArgMatches`.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub enum FlagType {
21    /// UTF-8 string value (most flags).
22    String,
23    /// Signed 64-bit integer.
24    Int,
25    /// Boolean switch (presence = true, `--no-*` = false).
26    Bool,
27    /// Duration string parsed by the obz time module (e.g. `30s`, `5m`).
28    Duration,
29}
30
31/// Descriptor for a single provider-specific flag.
32///
33/// Designed so that obz can convert it to a `clap::Arg` without any
34/// additional information. All fields that clap needs are present here.
35#[derive(Debug, Clone)]
36pub struct FlagDescriptor {
37    /// Long flag name without the `--` prefix (e.g. `"round-digits"`).
38    /// Must be unique within a command across all providers sharing that command.
39    pub name: &'static str,
40    /// Value type — determines the clap `value_parser` and `ArgAction`.
41    pub flag_type: FlagType,
42    /// Whether the flag is required for this provider.
43    ///
44    /// Always declare `false` at the clap level — enforcement happens at
45    /// runtime after the provider is resolved, so other providers that
46    /// don't use this flag don't get a clap error.
47    pub required: bool,
48    /// Default value as a string. `None` means no default.
49    pub default: Option<&'static str>,
50    /// Short one-line help text shown in `--help`.
51    pub description: &'static str,
52    /// Whether the flag may be specified multiple times.
53    pub repeatable: bool,
54    /// Optional single-character short flag (e.g. `Some('q')` for `-q`).
55    pub short: Option<char>,
56}
57
58/// Descriptor for a provider extension command.
59///
60/// Extension commands are provider-specific subcommands (e.g.,
61/// `metric top-queries`) that are registered into the core command
62/// tree alongside the standard commands.
63#[derive(Debug, Clone)]
64pub struct CommandDescriptor {
65    /// Command path relative to the signal group, e.g. `"top-queries"`.
66    /// This becomes `obz metric top-queries` when registered under `metric`.
67    pub name: &'static str,
68    /// Short description shown in `--help`.
69    pub description: &'static str,
70    /// Flags specific to this extension command.
71    pub flags: &'static [FlagDescriptor],
72}
obz_core/descriptor.rs

obz_core/
descriptor.rs
