rtb_app/

metadata.rs

//! Static, build-time tool metadata.

use std::time::Duration;

use serde::{Deserialize, Serialize};

/// Release-source descriptor. Drives the `version` and `update`
/// subcommands — `rtb-vcs` resolves this into a concrete
/// `ReleaseProvider`.
///
/// `host` fields default (to `github.com` / `gitlab.com`) so minimal
/// configs round-trip cleanly.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "lowercase", deny_unknown_fields)]
#[non_exhaustive]
pub enum ReleaseSource {
    /// A GitHub or GitHub-Enterprise-hosted release source.
    Github {
        /// Repository owner (user or organisation).
        owner: String,
        /// Repository name.
        repo: String,
        /// API host; `github.com` for public GitHub, otherwise the
        /// Enterprise host (`github.example.com`).
        #[serde(default = "default_github_host")]
        host: String,
    },
    /// A GitLab or self-hosted GitLab release source.
    Gitlab {
        /// Fully-qualified project path, e.g. `myorg/group/subgroup/project`.
        project: String,
        /// API host; `gitlab.com` for public GitLab.
        #[serde(default = "default_gitlab_host")]
        host: String,
    },
    /// A Bitbucket Cloud or Bitbucket Data Center release source.
    Bitbucket {
        /// Workspace (Cloud) or project key (Data Center).
        workspace: String,
        /// Repository slug.
        repo_slug: String,
        /// API host; defaults to `api.bitbucket.org/2.0` for Cloud.
        #[serde(default = "default_bitbucket_host")]
        host: String,
    },
    /// A self-hosted Gitea release source.
    Gitea {
        /// Repository owner.
        owner: String,
        /// Repository name.
        repo: String,
        /// API host — required (no public default).
        host: String,
    },
    /// Codeberg — a hosted Gitea instance at `codeberg.org`. Distinct
    /// variant rather than a Gitea alias for config-layer clarity.
    Codeberg {
        /// Repository owner.
        owner: String,
        /// Repository name.
        repo: String,
    },
    /// Direct HTTP release source (e.g. S3 bucket, CDN).
    Direct {
        /// URL template, e.g. `https://dist.example.com/{tool}/{version}/{asset}`.
        url_template: String,
    },
}

fn default_github_host() -> String {
    "github.com".into()
}

fn default_gitlab_host() -> String {
    "gitlab.com".into()
}

fn default_bitbucket_host() -> String {
    "api.bitbucket.org/2.0".into()
}

/// Author-set baseline for **synchronous, pre-run** self-update checks.
///
/// User-initiated `update` (the subcommand) is always available regardless
/// of this policy; this only governs automatic checking at the start of a
/// run. Default [`UpdatePolicy::Disabled`] — tools opt in to automation
/// explicitly, so there are no unsolicited network calls or pre-run
/// overhead by default.
///
/// See `docs/development/specs/2026-06-23-rtb-update-policy-v0.1.md`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum UpdatePolicy {
    /// Never check automatically (default). User-initiated only.
    #[default]
    Disabled,
    /// Check (throttled); on a newer version, prompt the user.
    Prompt,
    /// Check (throttled); on a newer version, update before running.
    Enabled,
}

/// Default interval between automatic update checks: 24 hours.
const DEFAULT_UPDATE_CHECK_INTERVAL: Duration = Duration::from_secs(24 * 60 * 60);

const fn default_update_check_interval() -> Duration {
    DEFAULT_UPDATE_CHECK_INTERVAL
}

/// Static tool metadata set at construction time.
///
/// Use the [`bon::Builder`] interface — `name` and `summary` are
/// required at compile time; missing either is a compile error.
#[derive(Debug, Clone, Serialize, Deserialize, bon::Builder)]
#[serde(deny_unknown_fields)]
#[builder(on(String, into))]
pub struct ToolMetadata {
    /// Human- and machine-facing tool name (`mytool`).
    pub name: String,

    /// One-line summary used in `--help` and the CLI banner.
    pub summary: String,

    /// Long-form description shown under `--help`.
    #[serde(default)]
    #[builder(default)]
    pub description: String,

    /// Optional release source — required iff `Feature::Update` is
    /// runtime-enabled.
    #[serde(default)]
    pub release_source: Option<ReleaseSource>,

    /// Author-set self-update policy baseline. Default
    /// [`UpdatePolicy::Disabled`]. In v0.1 the effective policy is this
    /// baseline (a runtime config override is deferred — see the spec).
    /// Inert unless `Feature::Update` is enabled and `release_source` is
    /// set.
    #[serde(default)]
    #[builder(default)]
    pub update_policy: UpdatePolicy,

    /// Minimum interval between automatic update checks (default 24h).
    /// Only consulted when `update_policy` is `Prompt`/`Enabled`; a check
    /// within this window of the last is throttled (skipped).
    #[serde(default = "default_update_check_interval")]
    #[builder(default = default_update_check_interval())]
    pub update_check_interval: Duration,

    /// Optional credential reference for the release source. Resolved
    /// at update time via `rtb_credentials::Resolver`. Public repos
    /// don't need it; private repos require this OR a fallback env
    /// var the resolver knows about.
    ///
    /// Deserialised from config files but never serialised back —
    /// `CredentialRef` contains a `SecretString` literal that should
    /// not round-trip through `Serialize` (the `secrecy` crate
    /// removed the `Serialize` impl on purpose, mirroring the
    /// "secrets don't cross untyped boundaries" rule).
    #[serde(default, skip_serializing)]
    pub release_credential: Option<rtb_credentials::CredentialRef>,

    /// Support channel advertised in error diagnostic footers.
    #[serde(default)]
    #[builder(default)]
    pub help: HelpChannel,

    /// minisign public keys trusted for verifying release-asset
    /// signatures, each the base64 string a `minisign.pub` file
    /// carries — `"RWR…"`, decoding to algorithm tag, key id and the
    /// 32-byte Ed25519 key.
    ///
    /// This is deliberately the *same* string pinned as `pubkey` in a
    /// crate's `[package.metadata.binstall.signing]` table and printed
    /// by `sigillum keys minisign`. One canonical representation means
    /// cargo-binstall and `rtb-update` cannot end up trusting
    /// different things, and an operator can compare the two by eye.
    ///
    /// The key id matters: `rtb-update` verifies via the same
    /// `minisign-verify` crate cargo-binstall uses, which matches a
    /// signature's key id against the public key's before checking any
    /// signature. A bare 32-byte key cannot satisfy that, which is why
    /// this carries the full encoded form rather than raw key bytes.
    ///
    /// Multiple keys enable rotation without breaking already-deployed
    /// binaries — any one verifying is accepted, so a binary shipped
    /// trusting `{old, new}` spans a rotation. Empty means
    /// `rtb-update` refuses to run (see `UpdateError::NoPublicKey`).
    /// Not serialised — keys are compile-time constants, not
    /// config-file values.
    #[serde(skip)]
    #[builder(default)]
    pub update_public_keys: Vec<String>,

    /// Optional asset name listing SHA-256 checksums for this
    /// release. `rtb-update` downloads it alongside the binary and
    /// cross-checks the binary's hash before swap. When `None`,
    /// signature verification is the only integrity gate.
    #[serde(skip)]
    pub update_checksums_asset: Option<&'static str>,

    /// Asset-name template `rtb-update` uses to select the right
    /// artefact for the running host. Default:
    /// `{name}-{version}-{target}{ext}`. Placeholders:
    /// `{name}` → [`ToolMetadata::name`], `{version}` → release tag
    /// (leading `v` stripped), `{target}` → Rust host triple,
    /// `{ext}` → `.tar.gz` on Unix / `.zip` on Windows. Tools with
    /// a different naming convention set this explicitly.
    #[serde(skip)]
    pub update_asset_pattern: Option<&'static str>,

    /// Privacy notice printed by `rtb-cli`'s v0.4 `telemetry enable`
    /// subcommand. `None` falls back to a generic message. Lives on
    /// `ToolMetadata` rather than `rtb-telemetry` so the subcommand
    /// can read it without depending on the telemetry crate.
    #[serde(skip)]
    pub telemetry_notice: Option<&'static str>,
}

/// User-support channel advertised in error output.
///
/// `rtb-cli::Application::run` reads this off `ToolMetadata`, formats
/// via [`HelpChannel::footer`], and installs the result into
/// `rtb_error::hook::install_with_footer` so every diagnostic ends
/// with a consistent support pointer.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "lowercase", deny_unknown_fields)]
#[non_exhaustive]
pub enum HelpChannel {
    /// No support footer.
    #[default]
    None,
    /// Slack channel reference.
    Slack {
        /// Slack workspace / team name.
        team: String,
        /// Channel name without the `#`.
        channel: String,
    },
    /// Microsoft Teams channel reference.
    Teams {
        /// Team name.
        team: String,
        /// Channel name.
        channel: String,
    },
    /// Arbitrary support URL (status page, docs, contact form).
    Url {
        /// The URL to advertise verbatim.
        url: String,
    },
}

impl HelpChannel {
    /// The one-line footer shown under error diagnostics.
    ///
    /// Returns `None` when the channel is [`HelpChannel::None`] —
    /// `install_with_footer` treats `None`/empty as "no footer".
    #[must_use]
    pub fn footer(&self) -> Option<String> {
        match self {
            Self::None => None,
            Self::Slack { team, channel } => Some(format!("support: slack #{channel} (in {team})")),
            Self::Teams { team, channel } => Some(format!("support: Teams → {team} / {channel}")),
            Self::Url { url } => Some(format!("support: {url}")),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{default_update_check_interval, ToolMetadata, UpdatePolicy};
    use std::time::Duration;

    #[test]
    fn update_policy_defaults_to_disabled() {
        assert_eq!(UpdatePolicy::default(), UpdatePolicy::Disabled);
    }

    #[test]
    fn metadata_update_baseline_defaults() {
        let m = ToolMetadata::builder().name("t").summary("s").build();
        assert_eq!(m.update_policy, UpdatePolicy::Disabled);
        assert_eq!(m.update_check_interval, Duration::from_secs(24 * 60 * 60));
    }

    #[test]
    fn builder_overrides_update_baseline() {
        let m = ToolMetadata::builder()
            .name("t")
            .summary("s")
            .update_policy(UpdatePolicy::Enabled)
            .update_check_interval(Duration::from_secs(3600))
            .build();
        assert_eq!(m.update_policy, UpdatePolicy::Enabled);
        assert_eq!(m.update_check_interval, Duration::from_secs(3600));
    }

    #[test]
    fn update_policy_serde_is_lowercase() {
        assert_eq!(serde_json::to_string(&UpdatePolicy::Enabled).unwrap(), "\"enabled\"");
        assert_eq!(
            serde_json::from_str::<UpdatePolicy>("\"prompt\"").unwrap(),
            UpdatePolicy::Prompt
        );
    }

    #[test]
    fn check_interval_default_fn_is_24h() {
        assert_eq!(default_update_check_interval(), Duration::from_secs(86_400));
    }
}