api: handlers hold no logic, and one generated contract (plan 2.3, 2.4)

.github/workflows/ci.yml

@@ -149,6 +149,37 @@
       - run: pnpm -C tauri typecheck
       - run: pnpm -C tauri build
 
+  # ── API surface check (plan 2.3) ──────────────────────────────────
+  #
+  # One generated contract: the OpenAPI document springtaled derives
+  # from its own handlers must stay in step with the checked-in copy the
+  # frontend generates types from, and every route it declares must be
+  # reachable from the command line and from the web DataProvider.
+  surface:
+    name: API surface check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2
+        with:
+          egress-policy: audit
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@6bed0761d98439e5a578e2877258200ad565ba87 # stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+      - name: Regenerate the contract and prove it matches the committed one
+        run: |
+          cargo run -q -p springtaled -- --dump-openapi > /tmp/openapi.json
+          diff -u tauri/packages/types/openapi.json /tmp/openapi.json \
+            || { echo "openapi.json is stale — run: cargo run -p springtaled -- --dump-openapi > tauri/packages/types/openapi.json"; exit 1; }
+      - name: Every route has a CLI verb and a provider method
+        run: sh scripts/check-surface.sh
+
   # ── TypeScript Lint (Biome) ───────────────────────────────────────
   #
   # Biome is the workspace's TS/JSX linter + formatter (2026 idiom for

Cargo.toml

@@ -203,6 +203,10 @@ pyo3             = { version = "0.29", features = ["extension-module", "abi3-py3
 
 # ── CLI ────────────────────────────────────────────────────────────────────────
 clap             = { version = "4",    features = ["derive", "env"] }
+clap_complete    = "4"
+clap_mangen      = "0.2"
+utoipa           = { version = "5",    features = ["axum_extras", "uuid", "chrono"] }
+utoipa-axum      = "0.2"
 indicatif        = "0.17"
 tabled           = "0.17"
 rpassword        = "5"

apps/springtale-cli/Cargo.toml

@@ -44,6 +44,13 @@ springtale-ai = { workspace = true }
 springtale-sentinel = { workspace = true }
 connector-telegram = { workspace = true }
 
+# Shell completions + man page are generated at build time from the same
+# `src/cli.rs` the binary compiles (see `build.rs` for the include! mechanism).
+[build-dependencies]
+clap = { workspace = true }
+clap_complete = { workspace = true }
+clap_mangen = { workspace = true }
+
 [dev-dependencies]
 tempfile = { workspace = true }
 # `tests/daemon_client.rs` runs the real CLI binary against a real

apps/springtale-cli/build.rs

@@ -0,0 +1,94 @@
+//! Build-time generation of shell completions and the `springtale(1)` man page.
+//!
+//! # Mechanism
+//!
+//! A build script cannot `use` items from the binary crate it builds, so the
+//! clap definition has to reach this file some other way. `src/cli.rs` is
+//! deliberately standalone — it imports nothing but `std::path::PathBuf` and
+//! `clap` — so it is `include!`d here into a private `cli` module. The binary
+//! keeps `mod cli;` unchanged; both compile the same source, and the
+//! `#[cfg(test)]` block inside it is compiled out for the build script.
+//!
+//! If `src/cli.rs` ever grows a `crate::`/`super::` reference the include stops
+//! compiling, and the fix is to move that reference out of `cli.rs` rather than
+//! to weaken this script — the CLI surface is meant to be declarable on its own.
+//!
+//! # Output
+//!
+//! Everything lands under `$OUT_DIR/assets/`:
+//!
+//! ```text
+//! assets/completions/springtale.bash
+//! assets/completions/_springtale          (zsh)
+//! assets/completions/springtale.fish
+//! assets/completions/_springtale.ps1      (powershell)
+//! assets/completions/springtale.elv       (elvish)
+//! assets/man/springtale.1
+//! ```
+//!
+//! `$OUT_DIR` is buried under `target/`, so the absolute path is also exported
+//! as the `SPRINGTALE_ASSETS_DIR` compile-time env var for packaging scripts to
+//! read back with `cargo build --message-format=json`. Setting the
+//! `SPRINGTALE_ASSET_DIR` environment variable at build time mirrors every file
+//! into that directory as well (used by the release packaging job).
+
+use std::io::Result;
+use std::path::{Path, PathBuf};
+
+use clap::CommandFactory;
+use clap_complete::Shell;
+
+mod cli {
+    include!("src/cli.rs");
+}
+
+fn main() -> Result<()> {
+    println!("cargo::rerun-if-changed=src/cli.rs");
+    println!("cargo::rerun-if-changed=build.rs");
+    println!("cargo::rerun-if-env-changed=SPRINGTALE_ASSET_DIR");
+
+    let Some(out_dir) = std::env::var_os("OUT_DIR") else {
+        // Not running under cargo (rust-analyzer probes, doc tooling).
+        return Ok(());
+    };
+    let assets = PathBuf::from(out_dir).join("assets");
+    generate_into(&assets)?;
+
+    if let Some(extra) = std::env::var_os("SPRINGTALE_ASSET_DIR") {
+        generate_into(Path::new(&extra))?;
+    }
+
+    println!(
+        "cargo::rustc-env=SPRINGTALE_ASSETS_DIR={}",
+        assets.display()
+    );
+    Ok(())
+}
+
+/// Write every completion script and the man page under `root`.
+fn generate_into(root: &Path) -> Result<()> {
+    let completions = root.join("completions");
+    let man = root.join("man");
+    std::fs::create_dir_all(&completions)?;
+    std::fs::create_dir_all(&man)?;
+
+    let mut command = cli::Cli::command();
+    command.build();
+
+    for shell in [
+        Shell::Bash,
+        Shell::Zsh,
+        Shell::Fish,
+        Shell::PowerShell,
+        Shell::Elvish,
+    ] {
+        clap_complete::generate_to(shell, &mut command, "springtale", &completions)?;
+    }
+
+    let rendered = {
+        let mut buf = Vec::new();
+        clap_mangen::Man::new(command).render(&mut buf)?;
+        buf
+    };
+    std::fs::write(man.join("springtale.1"), rendered)
+}

apps/springtale-cli/src/cli.rs

@@ -353,6 +353,12 @@ pub enum SafetyAction {
     /// Turn the disguise overlay on or off.
     Disguise {
         /// `true` to activate the disguise, `false` to clear it.
+        ///
+        /// A positional `bool` derives `ArgAction::SetTrue` by default,
+        /// which clap rejects for a positional (it would take no value).
+        /// `Set` makes it the value-taking positional the help text
+        /// describes.
+        #[arg(action = clap::ArgAction::Set)]
         active: bool,
     },
     /// Set how many rapid title-bar taps trigger the panic wipe.
@@ -636,6 +642,16 @@ mod tests {
     use super::*;
     use clap::CommandFactory;
 
+    /// clap's own consistency check over the whole tree. `build.rs`
+    /// generates completions and the man page from this same definition,
+    /// so a malformed arg (e.g. a positional `bool`, which derives
+    /// `SetTrue` and takes no value) breaks the build rather than
+    /// panicking the first user who runs the subcommand.
+    #[test]
+    fn test_cli_definition_passes_clap_debug_assert() {
+        Cli::command().debug_assert();
+    }
+
     /// Walk the whole clap tree, collecting `parent/child` verb paths.
     fn verb_paths(cmd: &clap::Command, prefix: &str, out: &mut Vec<String>) {
         for sub in cmd.get_subcommands() {

apps/springtale-cli/src/commands/author.rs

@@ -60,12 +60,14 @@ pub async fn run(action: AuthorAction, store: &SqliteBackend, json: bool) -> Res
                 .await
                 .map_err(|e| anyhow::anyhow!("{e}"))?;
 
-            if json {
-                output::print_json(&serde_json::json!({ "name": name, "pubkey": pubkey_hex }))?;
-            } else {
-                println!("Trusted author added: {name}");
-                println!("  pubkey: {pubkey_hex}");
-            }
+            let added = serde_json::json!({ "name": name, "pubkey": pubkey_hex });
+            output::emit(json, &added, |v| {
+                format!(
+                    "Trusted author added: {}\n  pubkey: {}",
+                    output::cell(v, "name"),
+                    output::cell(v, "pubkey")
+                )
+            })?;
         }
         AuthorAction::List => {
             let configs = store
@@ -88,25 +90,28 @@ pub async fn run(action: AuthorAction, store: &SqliteBackend, json: bool) -> Res
                 })
                 .collect();
 
-            if json {
-                let authors: Vec<serde_json::Value> = rows
-                    .iter()
-                    .map(|r| serde_json::json!({ "name": r.name, "pubkey": r.pubkey }))
-                    .collect();
-                output::print_json(&authors)?;
-            } else if rows.is_empty() {
-                println!("No trusted authors.");
-            } else {
-                println!("{}", Table::new(rows));
-            }
+            let authors: Vec<serde_json::Value> = rows
+                .iter()
+                .map(|r| serde_json::json!({ "name": r.name, "pubkey": r.pubkey }))
+                .collect();
+            output::emit(json, &authors, |_| {
+                if rows.is_empty() {
+                    "No trusted authors.".to_owned()
+                } else {
+                    Table::new(rows).to_string()
+                }
+            })?;
         }
         AuthorAction::Remove { name } => {
             let key = format!("{TRUSTED_AUTHOR_PREFIX}{name}");
             store
                 .delete_config(&key)
                 .await
                 .map_err(|e| anyhow::anyhow!("{e}"))?;
-            println!("Removed trusted author: {name}");
+            let removed = serde_json::json!({ "name": name, "removed": true });
+            output::emit(json, &removed, |v| {
+                format!("Removed trusted author: {}", output::cell(v, "name"))
+            })?;
         }
     }
     Ok(())