rtb-app¶

#[derive(Clone)]
pub struct App {
    pub metadata: Arc<ToolMetadata>,
    pub version:  Arc<VersionInfo>,
    // Type-erased since 0.4.1: reach the typed handle through
    // `typed_config::<C>()` or `config_as::<C>()`. Stored as
    // `Arc<dyn Any + Send + Sync>` so `Arc::downcast` recovers the
    // typed `Arc<Config<C>>` sharing the same backing allocation.
    pub(crate) config: ErasedConfig,
    pub assets:   Arc<Assets>,
    pub shutdown: CancellationToken,
    pub credentials_provider: Option<Arc<dyn CredentialProvider>>, // since 0.4.0
    pub(crate) typed_config_ops: Option<Arc<TypedConfigOps>>,      // since 0.4.1
}

impl App {
    /// Typed access to the wired configuration. `Some` when
    /// `Application::builder().config(...)` was called with a
    /// `Config<C>`; `None` otherwise.
    pub fn typed_config<C>(&self) -> Option<Arc<Config<C>>>
    where C: serde::de::DeserializeOwned + Send + Sync + 'static; // since 0.4.1

    /// Same as `typed_config`, but panics with a diagnostic naming
    /// the requested type when no matching typed config is wired.
    /// Surfaces the call-site location via `#[track_caller]`.
    pub fn config_as<C>(&self) -> Arc<Config<C>>
    where C: serde::de::DeserializeOwned + Send + Sync + 'static; // since 0.4.1

    /// JSON Schema for the wired typed config. `None` when no
    /// typed-config ops were attached. Drives `config schema /
    /// validate` in `rtb-cli`.
    pub fn config_schema(&self) -> Option<&serde_json::Value>;     // since 0.4.1

    /// Merged typed-config value rendered as a `serde_json::Value`.
    /// Drives `config show / get` in `rtb-cli`.
    pub fn config_value(&self) -> Option<serde_json::Value>;       // since 0.4.1

    /// Yield the configured credentials. Returns `Vec::new()` when
    /// no provider has been wired — `credentials list` reports the
    /// empty set, which is the right thing for a tool that hasn't
    /// declared any credentials yet.
    pub fn credentials(&self) -> Vec<(String, CredentialRef)>;     // since 0.4.0
}

#[derive(Debug, Clone, Serialize, Deserialize, bon::Builder)]
#[serde(deny_unknown_fields)]
pub struct ToolMetadata {
    pub name: String,                               // required
    pub summary: String,                            // required
    pub description: String,                        // optional
    pub release_source: Option<ReleaseSource>,      // optional
    pub release_credential: Option<CredentialRef>,  // optional
    pub help: HelpChannel,                          // optional
    pub update_public_keys: Vec<[u8; 32]>,          // optional
    pub update_checksums_asset: Option<&'static str>, // optional
    pub update_asset_pattern: Option<&'static str>, // optional
    pub telemetry_notice: Option<&'static str>,     // optional, since 0.4.0
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "lowercase", deny_unknown_fields)]
#[non_exhaustive]
pub enum ReleaseSource {
    Github { owner: String, repo: String, host: String },
    Gitlab { project: String, host: String },
    Direct { url_template: String },
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "lowercase", deny_unknown_fields)]
#[non_exhaustive]
pub enum HelpChannel {
    #[default]
    None,
    Slack { team: String, channel: String },
    Teams { team: String, channel: String },
    Url   { url: String },
}

impl HelpChannel {
    pub fn footer(&self) -> Option<String>;
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VersionInfo {
    pub version: semver::Version,
    pub commit: Option<String>,
    pub date:   Option<String>,
}

impl VersionInfo {
    pub const fn new(version: Version) -> Self;
    pub fn with_commit(self, commit: impl Into<String>) -> Self;
    pub fn with_date(self, date: impl Into<String>) -> Self;
    pub fn from_env() -> Self;              // reads CARGO_PKG_VERSION
    pub fn is_development(&self) -> bool;   // pre-release or major == 0
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Feature {
    Init, Version, Update, Docs, Mcp, Doctor,
    Ai, Telemetry, Config, Changelog,
    Credentials,    // since 0.4.0
}

impl Feature {
    pub fn defaults() -> Features;
    pub const fn all() -> &'static [Self];
}

pub struct Features { /* ... */ }

impl Features {
    pub fn builder() -> FeaturesBuilder;
    pub fn is_enabled(&self, feature: Feature) -> bool;
    pub fn iter(&self) -> impl Iterator<Item = Feature> + '_;
}

pub struct FeaturesBuilder { /* ... */ }

impl FeaturesBuilder {
    pub fn new() -> Self;         // defaults pre-populated
    pub fn none() -> Self;        // empty set
    pub fn enable(self, Feature) -> Self;
    pub fn disable(self, Feature) -> Self;
    pub fn build(self) -> Features;
}

#[async_trait::async_trait]
pub trait Command: Send + Sync + 'static {
    fn spec(&self) -> &CommandSpec;
    async fn run(&self, app: App) -> miette::Result<()>;

    /// `true` → the outer clap parser passes every arg after `<name>`
    /// straight to `run`. Commands that own their own clap subtree
    /// (e.g. `docs`, `update`, `mcp`) opt in. Default `false`.
    fn subcommand_passthrough(&self) -> bool { false }

    /// `true` → registered as an MCP tool by `rtb_mcp::McpServer`.
    /// Default `false`. See [MCP exposure](../concepts/mcp-exposure.md).
    fn mcp_exposed(&self) -> bool { false }

    /// JSON Schema for the command's arguments — surfaced to MCP
    /// clients via `tools/list`. Default `None`. Authors with a
    /// `clap::Args` struct typically derive this from
    /// `serde_json::to_value(schemars::schema_for!(MyArgs))`.
    fn mcp_input_schema(&self) -> Option<serde_json::Value> { None }
}

#[derive(Debug, Clone)]
pub struct CommandSpec {
    pub name:    &'static str,
    pub about:   &'static str,
    pub aliases: &'static [&'static str],
    pub feature: Option<Feature>,  // runtime-gated when Some
}

use linkme::distributed_slice;

#[distributed_slice]
pub static BUILTIN_COMMANDS: [fn() -> Box<dyn Command>];

use rtb_app::command::{BUILTIN_COMMANDS, Command, CommandSpec};
use linkme::distributed_slice;

pub struct MyCommand;

#[async_trait::async_trait]
impl Command for MyCommand {
    fn spec(&self) -> &CommandSpec {
        static SPEC: CommandSpec = CommandSpec {
            name: "my-cmd",
            about: "do the thing",
            aliases: &[],
            feature: None,
        };
        &SPEC
    }
    async fn run(&self, app: App) -> miette::Result<()> { /* ... */ }
}

#[distributed_slice(BUILTIN_COMMANDS)]
fn __register_my_cmd() -> Box<dyn Command> { Box::new(MyCommand) }