Skip to main content

taskfast_cli/
lib.rs

1// SPDX-License-Identifier: MIT
2//! `taskfast-cli` library surface.
3//!
4//! The crate ships primarily as the `taskfast` binary (see `src/main.rs`),
5//! but every subcommand's `run` function and the shared envelope/exit/error
6//! types are re-exported here so integration tests (and, later, embedded
7//! callers) can drive the pipeline without spawning a process.
8
9// TODO: tighten doc coverage on public items + remove this allow.
10// Tracked under the rust-best-practices follow-up.
11#![allow(missing_docs)]
12
13pub mod cmd;
14pub mod config;
15pub mod envelope;
16pub mod exit;
17pub mod state_store;
18pub mod tempo_session;
19pub mod trace;
20pub mod wallet_lock;
21
22pub use config::Config;
23pub use envelope::{Envelope, ErrorPayload};
24pub use exit::ExitCode;
25pub use state_store::{StateAsset, StateStore};
26
27/// Re-exported from `main.rs` so tests can construct a [`cmd::Ctx`] with a
28/// named [`Environment`] without depending on the binary entry point.
29#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, clap::ValueEnum)]
30pub enum Environment {
31    Prod,
32    Staging,
33    Local,
34}
35
36/// Tempo network selector. Derived from [`Environment`] — never persisted,
37/// never accepted as a CLI flag. The compile-time mapping in
38/// [`Environment::network`] is the single source of truth; the runtime
39/// invariant in `cmd::enforce_server_network_invariant` cross-checks it
40/// against `/config/network`.
41#[derive(Debug, Clone, Copy, PartialEq, Eq)]
42pub enum Network {
43    Mainnet,
44    Testnet,
45}
46
47impl Network {
48    pub fn as_str(self) -> &'static str {
49        match self {
50            Self::Mainnet => "mainnet",
51            Self::Testnet => "testnet",
52        }
53    }
54}
55
56impl Environment {
57    /// Every variant. Drives table-driven tests and the well-known-base
58    /// iterator; touching [`Environment`] without updating this array
59    /// fails the `all_covers_every_variant` test.
60    pub const ALL: &'static [Environment] = &[Self::Prod, Self::Staging, Self::Local];
61
62    pub fn as_str(self) -> &'static str {
63        match self {
64            Self::Prod => "production",
65            Self::Staging => "staging",
66            Self::Local => "local",
67        }
68    }
69
70    /// Sole TaskFast API base URL for this environment. Total function;
71    /// the F2 endpoint-override guard treats anything else as adversarial.
72    ///
73    /// `Local` uses the IPv4 literal `127.0.0.1` rather than `localhost`:
74    /// the well-known-base allowlist matches the bound string verbatim, and
75    /// some dev hosts resolve `localhost` to `::1` first, which then misses
76    /// an IPv4-only `mix phx.server` and confuses the endpoint guard.
77    pub fn api_base(self) -> &'static str {
78        match self {
79            Self::Prod => "https://api.taskfast.app",
80            Self::Staging => "https://staging.api.taskfast.app",
81            Self::Local => "http://127.0.0.1:4000",
82        }
83    }
84
85    /// Sole Tempo network for this environment. Prod runs mainnet; staging
86    /// and local both run testnet. The runtime invariant verifies the
87    /// deployment at [`api_base`](Self::api_base) advertises exactly this
88    /// network and no other.
89    pub fn network(self) -> Network {
90        match self {
91            Self::Prod => Network::Mainnet,
92            Self::Staging => Network::Testnet,
93            Self::Local => Network::Testnet,
94        }
95    }
96}
97
98/// Iterator over the well-known TaskFast API base URLs — one per
99/// [`Environment`] variant, derived from [`Environment::api_base`].
100///
101/// Used by the F2 endpoint-override guard: an `api_base` supplied via the
102/// `--api-base` flag is rejected unless it matches one of these or the
103/// caller passed `--allow-custom-endpoints`.
104pub fn well_known_api_bases() -> impl Iterator<Item = &'static str> {
105    Environment::ALL.iter().map(|e| e.api_base())
106}
107
108/// True when `url` exactly matches a known-good default from
109/// [`well_known_api_bases`]. Trailing `/` is tolerated so a value
110/// `https://api.taskfast.app/` isn't flagged as custom.
111pub fn is_well_known_api_base(url: &str) -> bool {
112    let trimmed = url.trim_end_matches('/');
113    well_known_api_bases().any(|w| w.trim_end_matches('/') == trimmed)
114}
115
116/// Derive the human-facing Personal API Key URL from an API base URL.
117///
118/// Strips the `api` label from the host (so `api.taskfast.app` →
119/// `taskfast.app`) and links to `/accounts#personal-api-key`. Hosts without
120/// an `api` label (localhost, bare domains, IPs) are passed through.
121/// Scheme and port are preserved; existing path, query, and fragment are replaced.
122pub fn accounts_url(api_base: &str) -> String {
123    match url::Url::parse(api_base) {
124        Ok(mut u) => {
125            let rewritten = u.host_str().and_then(strip_api_label);
126            if let Some(h) = rewritten {
127                let _ = u.set_host(Some(&h));
128            }
129            u.set_path("/accounts");
130            u.set_query(None);
131            u.set_fragment(Some("personal-api-key"));
132            u.to_string()
133        }
134        // Fallback for a malformed base: best-effort string concat.
135        Err(_) => format!(
136            "{}/accounts#personal-api-key",
137            api_base.trim_end_matches('/')
138        ),
139    }
140}
141
142/// Drop the `api` label from a host so the URL points at the human-facing
143/// dashboard. `api.taskfast.app` → `taskfast.app`;
144/// `staging.api.taskfast.app` → `staging.taskfast.app`. Returns `None`
145/// when the host has no `api` label to strip.
146fn strip_api_label(host: &str) -> Option<String> {
147    if let Some(rest) = host.strip_prefix("api.") {
148        return Some(rest.to_owned());
149    }
150    // Middle label: collapse `.api.` into a single `.`.
151    if host.contains(".api.") {
152        return Some(host.replacen(".api.", ".", 1));
153    }
154    None
155}
156
157#[cfg(test)]
158mod tests {
159    use super::{accounts_url, is_well_known_api_base, well_known_api_bases, Environment, Network};
160    use std::collections::HashSet;
161
162    #[test]
163    fn all_covers_every_variant() {
164        // Drift trap: if someone adds an Environment variant without
165        // appending it to ::ALL, this test catches the gap that compile-
166        // time exhaustiveness can't (a new variant compiles fine if it's
167        // never read; ::ALL is a const array, not a match).
168        let n = Environment::ALL.len();
169        let unique: HashSet<_> = Environment::ALL.iter().copied().collect();
170        assert_eq!(unique.len(), n, "Environment::ALL has duplicates");
171        for env in Environment::ALL {
172            // Touch every method so adding a variant without updating one
173            // of these breaks the build via match exhaustiveness.
174            let _ = env.as_str();
175            let _ = env.api_base();
176            let _ = env.network();
177        }
178    }
179
180    #[test]
181    fn each_env_has_unique_api_base() {
182        let bases: HashSet<_> = Environment::ALL.iter().map(|e| e.api_base()).collect();
183        assert_eq!(
184            bases.len(),
185            Environment::ALL.len(),
186            "two envs share an api_base"
187        );
188    }
189
190    #[test]
191    fn env_api_base_table_is_frozen() {
192        // Pin the exact mapping. Touching this test = a deliberate decision.
193        assert_eq!(Environment::Prod.api_base(), "https://api.taskfast.app");
194        assert_eq!(
195            Environment::Staging.api_base(),
196            "https://staging.api.taskfast.app"
197        );
198        assert_eq!(Environment::Local.api_base(), "http://127.0.0.1:4000");
199    }
200
201    #[test]
202    fn env_network_table_is_frozen() {
203        assert_eq!(Environment::Prod.network(), Network::Mainnet);
204        assert_eq!(Environment::Staging.network(), Network::Testnet);
205        assert_eq!(Environment::Local.network(), Network::Testnet);
206    }
207
208    #[test]
209    fn well_known_api_bases_cover_every_environment_default() {
210        for env in Environment::ALL {
211            let url = env.api_base();
212            assert!(
213                is_well_known_api_base(url),
214                "api_base for {env:?} ({url}) must be in well_known_api_bases"
215            );
216        }
217    }
218
219    #[test]
220    fn is_well_known_api_base_accepts_exact_defaults() {
221        for url in well_known_api_bases() {
222            assert!(is_well_known_api_base(url), "expected well-known: {url}");
223        }
224    }
225
226    #[test]
227    fn is_well_known_api_base_tolerates_trailing_slash() {
228        assert!(is_well_known_api_base("https://api.taskfast.app/"));
229        assert!(is_well_known_api_base("http://127.0.0.1:4000/"));
230    }
231
232    #[test]
233    fn is_well_known_api_base_rejects_attacker_hosts() {
234        assert!(!is_well_known_api_base("https://evil.example"));
235        assert!(!is_well_known_api_base(
236            "https://api.taskfast.app.evil.example"
237        ));
238        assert!(!is_well_known_api_base("http://api.taskfast.app"));
239        assert!(!is_well_known_api_base("https://staging.taskfast.app"));
240    }
241
242    #[test]
243    fn accounts_url_strips_api_prefix_prod() {
244        assert_eq!(
245            accounts_url("https://api.taskfast.app"),
246            "https://taskfast.app/accounts#personal-api-key"
247        );
248    }
249
250    #[test]
251    fn accounts_url_strips_api_prefix_staging() {
252        assert_eq!(
253            accounts_url("https://staging.api.taskfast.app"),
254            "https://staging.taskfast.app/accounts#personal-api-key"
255        );
256    }
257
258    #[test]
259    fn accounts_url_passthrough_localhost_with_port() {
260        assert_eq!(
261            accounts_url("http://127.0.0.1:4000"),
262            "http://127.0.0.1:4000/accounts#personal-api-key"
263        );
264    }
265
266    #[test]
267    fn accounts_url_passthrough_bare_domain() {
268        assert_eq!(
269            accounts_url("https://taskfast.app"),
270            "https://taskfast.app/accounts#personal-api-key"
271        );
272    }
273
274    #[test]
275    fn accounts_url_replaces_existing_path_query_and_fragment() {
276        assert_eq!(
277            accounts_url("https://api.taskfast.app/v1?x=1#old-section"),
278            "https://taskfast.app/accounts#personal-api-key"
279        );
280    }
281
282    #[test]
283    fn accounts_url_malformed_falls_back_to_concat() {
284        assert_eq!(
285            accounts_url("not a url"),
286            "not a url/accounts#personal-api-key"
287        );
288    }
289}