umbral_cli/

lib.rs

//! Library surface for user binaries to host umbral's management
//! subcommands.
//!
//! umbral-cli ships as two artefacts. The library (this crate) exposes
//! [`dispatch`] — the entry point user binaries call to gain the
//! `serve` / `migrate` / `makemigrations` / `inspectdb` /
//! `dumpdata` / `loaddata` subcommands. The binary (`umbral`) ships as
//! the global scaffolding tool installed via `cargo install
//! umbral-cli`, and handles `startproject` / `startapp` from outside
//! any project.
//!
//! ## Quickstart
//!
//! In your project's `src/main.rs`:
//!
//! ```ignore
//! use umbral::prelude::*;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
//!     tracing_subscriber::fmt::init();
//!
//!     let settings = Settings::from_env()?;
//!     let pool = umbral::db::connect(&settings.database_url).await?;
//!
//!     let app = App::builder()
//!         .settings(settings)
//!         .database("default", pool)
//!         .model::<Article>()
//!         .build_deferred()?;
//!
//!     umbral_cli::dispatch(app).await
//! }
//! ```
//!
//! Then:
//!
//! ```bash
//! cargo run -- migrate
//! cargo run -- serve
//! cargo run -- makemigrations
//! ```
//!
//! The subcommands run against the published ambient state (pool,
//! model registry) that the builder set up, so they see every model
//! and plugin the user wired into the builder.
//!
//! Note `build_deferred()`, not `build()`. It wires everything but leaves each
//! plugin's `on_ready` hook unfired, so [`dispatch`] can fire it once it knows
//! what argv asked for — never for `migrate`, which exists precisely because the
//! tables those hooks want to seed do not exist yet (gaps3 #41).

use std::net::SocketAddr;
use std::path::PathBuf;

use clap::{CommandFactory, Parser, Subcommand};
use umbral::App;
use umbral::inspect::{InspectError, InspectOptions};
use umbral::migrate::MigrateError;

pub mod scaffold;

/// Build the `cargo` argv for forwarding a `umbral <cmd> [args...]`
/// invocation to the current project's binary (`cargo run -- <cmd> [args...]`).
///
/// The global `umbral` scaffolding binary forwards every non-scaffolding
/// subcommand here so `umbral dev` behaves as `cargo run -- dev`. The
/// caller runs `cargo` with these args.
pub fn cargo_run_forward_args(forwarded: &[String]) -> Vec<String> {
    let mut argv = vec!["run".to_string(), "--".to_string()];
    argv.extend(forwarded.iter().cloned());
    argv
}

/// Whether `start` (or any ancestor) contains a `Cargo.toml` — i.e. we're
/// inside a Cargo project `cargo run` could build. Mirrors how `cargo`
/// itself finds the manifest by walking up from the working directory, so
/// `umbral <cmd>` works from a subdirectory just like `cargo run` does.
pub fn in_cargo_project(start: &std::path::Path) -> bool {
    start
        .ancestors()
        .any(|dir| dir.join("Cargo.toml").is_file())
}

#[derive(Debug, Parser)]
#[command(
    name = "umbral",
    about = "umbral management commands. Run from your project's binary.",
    disable_help_subcommand = true
)]
struct Cli {
    #[command(subcommand)]
    command: Option<Command>,
}

#[derive(Debug, Subcommand)]
enum Command {
    /// Boot the HTTP server on `settings.bind_addr`. Default
    /// subcommand when none is given. Override the bind address with
    /// `--addr` or `UMBRAL_BIND_ADDR`.
    Serve {
        /// Override `settings.bind_addr`. Format: `host:port`
        /// (e.g. `127.0.0.1:3000`).
        #[arg(long)]
        addr: Option<String>,
    },
    /// Diff registered models against the latest snapshot and write a
    /// new migration file per plugin with changes.
    Makemigrations {
        /// Write an EMPTY migration for `<plugin>` (current snapshot, no
        /// operations) instead of auto-detecting a schema diff. The stub
        /// for a hand-authored data migration: open the file and add a
        /// `RunSql { sql, reverse_sql }` op. Because it carries no schema
        /// change, it never disturbs the model-snapshot chain.
        #[arg(long, value_name = "PLUGIN")]
        empty: Option<String>,
    },
    /// Apply every pending migration against the ambient pool.
    Migrate {
        /// Mark a specific migration as applied in the tracking table
        /// WITHOUT running its SQL. Recovery path when the schema
        /// already exists (e.g. migrated outside umbral). Format:
        /// `<plugin>/<migration_name>` (e.g. `app/0001_create_post`).
        #[arg(long, value_name = "PLUGIN/NAME")]
        fake: Option<String>,
        /// For each plugin, if the first migration's tables already
        /// exist in the database, mark it applied without running SQL.
        /// Use when adopting a database bootstrapped outside umbral.
        #[arg(long, default_value_t = false)]
        fake_initial: bool,
        /// Proceed even if some applied migrations are missing from
        /// disk. Logs a warning for each missing file and applies the
        /// genuinely-pending ones. Without this flag, `migrate` errors
        /// on drift.
        #[arg(long, default_value_t = false)]
        allow_drift: bool,
        /// Allow destructive operations (DROP TABLE / DROP COLUMN / DROP M2M)
        /// to be applied. Without this flag, `migrate` REFUSES to run when any
        /// pending migration would drop a table or column and destroy its rows —
        /// the guard against one missing `.model::<T>()` registration silently
        /// dropping a production table (audit_2 core-migrate #6).
        #[arg(long, default_value_t = false)]
        allow_destructive: bool,
        /// Allow migrating an IN-MEMORY database (gaps3 #61).
        ///
        /// `migrate` normally refuses, because `sqlite::memory:` is the DEFAULT
        /// `database_url`: an app whose config never loaded migrates a database that
        /// evaporates on exit while the command reports "Applied N migration(s)". Success
        /// against nothing is worse than an error — the operator will trust it.
        ///
        /// Ephemeral migrates are legitimate in tests and CI. This flag is how you say so
        /// out loud.
        #[arg(long, default_value_t = false)]
        allow_in_memory: bool,
    },
    /// List applied vs pending migrations per plugin.
    ///
    /// Markers: [X] applied, [ ] pending, [!] applied-but-missing-on-disk,
    /// [?] on-disk-but-out-of-order.
    Showmigrations,
    /// Classify pending migrations for zero-downtime (blue-green) safety.
    ///
    /// Walks every operation in every pending migration and tags it
    /// SAFE / WARNING / UNSAFE, with an expand-contract note on each
    /// non-safe op. Exits non-zero when any UNSAFE op is found (or any
    /// WARNING under `--strict`), so it drops into a CI gate before deploy.
    /// Read-only — applies nothing.
    Checkmigrations {
        /// Also exit non-zero when a WARNING-tier op is present, not just
        /// UNSAFE. Use in CI when even a column rename must be reviewed.
        #[arg(long, default_value_t = false)]
        strict: bool,
    },
    /// Generate TypeScript types for every registered model.
    ///
    /// The frontend stops hand-maintaining a copy of your schema: an FK
    /// types as the target's primary key, `Option<T>` as `T | null`, and
    /// `#[umbral(choices)]` as a string-literal union, so a typo'd status
    /// fails at `tsc` instead of in production.
    ///
    /// Writes to stdout unless `--out` names a file.
    Typegen {
        /// File the generated TypeScript is written to. Omit for stdout.
        #[arg(long)]
        out: Option<PathBuf>,
        /// Don't write. Exit non-zero if `--out` differs from what the
        /// models would generate now. A CI gate against a checked-in
        /// types file drifting from the schema.
        #[arg(long, default_value_t = false, requires = "out")]
        check: bool,
    },
    /// Introspect the ambient database into a `models.rs` plus an
    /// initial migration. Used to onboard an existing schema.
    Inspectdb {
        /// Directory the generated files are written under.
        #[arg(long)]
        output: PathBuf,
        /// Record `0001_initial` in `umbral_migrations` after writing
        /// it, so the next `migrate` is a no-op against the
        /// already-populated database.
        #[arg(long, default_value_t = false)]
        mark_applied: bool,
    },
    /// Dump every registered model's rows to JSON. The upgrade-safety
    /// snapshot.
    Dumpdata {
        /// Where the JSON envelope is written.
        #[arg(long)]
        output: PathBuf,
    },
    /// Load a `dumpdata` JSON envelope into the schema. `migrate`
    /// first so the schema exists.
    Loaddata {
        /// Path to the JSON envelope.
        input: PathBuf,
    },
    /// Import a CSV file into one table's rows. The header row names the
    /// columns; each cell is coerced to its column type and inserted
    /// through the same validated write path as a REST POST (validators,
    /// `auto_now`, `slug_from`, FK-existence all apply). Best-effort: a
    /// bad row is reported by line number and skipped, not fatal. The
    /// inverse of the REST list endpoint's `?format=csv` export.
    Importcsv {
        /// Target table name (e.g. `blog_post`).
        table: String,
        /// Path to the CSV file. Must have a header row.
        input: PathBuf,
    },
    /// Dev-loop runner: watches `src/` and re-runs `cargo run` on
    /// change. Wraps `cargo-watch`; if not installed, prints the
    /// install hint and exits. Templates hot-reload in-process when
    /// `settings.environment == Dev`, so editing an `.html` file
    /// doesn't need a restart at all.
    Dev {
        /// Watch additional paths beyond the default (`src/`,
        /// `Cargo.toml`). Repeatable.
        #[arg(long, short = 'w')]
        watch: Vec<String>,
        /// Pass-through args to `cargo run`. After `--`, e.g.
        /// `umbral dev -- migrate` re-runs `cargo run -- migrate`
        /// on every change.
        #[arg(last = true)]
        run_args: Vec<String>,
    },
    /// Generate a fresh X25519 keypair for `Masked<T>` field encryption
    /// and print the two env-var lines (`UMBRAL_MASK_PUBLIC_KEY` /
    /// `UMBRAL_MASK_PRIVATE_KEY`) needed to configure it.
    Maskkeygen,
    /// Collapse a plugin's whole migration history into one optimized squash
    /// file, non-destructively (the originals stay on disk). Applying the
    /// squash on a fresh DB builds the schema in one shot; on a DB that already
    /// ran the originals it records without re-running. Once every deploy has
    /// migrated past the squash, delete the now-redundant original files.
    Squashmigrations {
        /// The plugin whose migrations to squash (e.g. `blog`, `auth`).
        plugin: String,
    },
}

/// Parse argv and run the requested management subcommand against the
/// passed-in App. The user binary's `main.rs` calls this after
/// wiring its App — see the module-level docs for the pattern.
///
/// # Build the app with [`AppBuilder::build_deferred`]
///
/// ```rust,ignore
/// let app = App::builder()
///     .settings(settings)
///     .database("default", pool)
///     .plugin(AuthPlugin::default())
///     .build_deferred()?;          // wire, but don't fire `on_ready` yet
///
/// umbral_cli::dispatch(app).await  // fires it iff argv warrants it
/// ```
///
/// `on_ready` is where plugins seed content, backfill rows, and create the
/// standard permissions — all of which need a migrated schema. `dispatch` is the
/// first place that knows what argv asked for, so it is the only place that can
/// decide whether the app is really "ready": it fires the hooks for `serve`
/// (after any auto-migrate) and for every command that runs against live data,
/// and skips them for the schema commands. See [`command_needs_ready`].
///
/// `App::build()` still fires `on_ready` itself, which is right for a test or an
/// embedder holding an `App` directly. Handing *that* app to `dispatch` leaves
/// the hooks already fired, which is the gaps3 #41 bug: `migrate` against a fresh
/// database ran every seed before the first table existed. `dispatch` warns when
/// it sees that combination.
pub async fn dispatch(app: App) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let argv: Vec<std::ffi::OsString> = std::env::args_os().collect();
    dispatch_with_argv(app, argv).await
}

/// The first non-flag token after the program name: the subcommand, or `None`
/// for a bare `umbral` (which defaults to `serve`) or a flag-only invocation
/// like `umbral --version`.
fn subcommand_name(argv: &[std::ffi::OsString]) -> Option<String> {
    argv.iter()
        .skip(1)
        .find(|a| !a.to_string_lossy().starts_with('-'))
        .map(|a| a.to_string_lossy().into_owned())
}

/// Whether this subcommand runs against a *live* application, and so should
/// fire every plugin's `on_ready` before it runs (gaps3 #41).
///
/// The `false` arm is the interesting one. Three groups:
///
/// - **Schema commands.** `migrate` and friends exist to bring the database up
///   to the models. Firing hooks that write rows first is backwards: on a fresh
///   database they run before a single table exists.
/// - **Offline utilities.** `typegen` reads the model registry, `maskkeygen`
///   generates a key, `dev` re-execs the binary under a file watcher (the child
///   process fires its own hooks). None of them touch application rows.
/// - **`serve`**, and the bare `umbral` that defaults to it. Handled separately
///   so the hooks fire *after* `auto_migrate_on_serve` has applied migrations,
///   not before. [`umbral_core::app::App::serve`] calls `ready()` itself.
///
/// Everything else — `dumpdata`, `loaddata`, `importcsv`, and every
/// plugin-contributed command (`createsuperuser`, `worker`, an app's own
/// `seed_orm_data`) — runs against a database that is expected to be migrated
/// already, so the hooks fire first, exactly as they did before the split.
fn builtin_needs_ready(subcommand: Option<&str>) -> bool {
    match subcommand {
        // Bare `umbral` / `umbral --addr …` defaults to serve.
        None => false,
        // INVARIANT: every name here must be one of THIS binary's own clap
        // subcommands (see `builtin_command_names`). A plugin's command must
        // never appear — it answers for itself via `PluginCommand::needs_ready`,
        // which is consulted first, so a name listed here that belongs to a
        // plugin is simply dead and misleading. `gen-client` (umbral-openapi)
        // used to be in this list; the moment `needs_ready` landed, the list
        // stopped being consulted for it and it silently started firing
        // `on_ready` again. It now declares `needs_ready() -> false` itself.
        Some(
            "serve" | "migrate" | "makemigrations" | "showmigrations" | "checkmigrations"
            | "squashmigrations" | "inspectdb" | "typegen" | "maskkeygen" | "dev" | "help",
        ) => false,
        Some(_) => true,
    }
}

/// Same as [`dispatch`] but argv is passed explicitly instead of read
/// from the process. Lets tests exercise the routing without spawning
/// a subprocess. User code should call [`dispatch`] (which reads
/// `std::env::args_os()` and delegates here).
///
/// The dispatch order is the same as [`dispatch`]: the app's own commands
/// (`AppBuilder::command`) and the plugin-contributed ones first, via
/// [`umbral_core::cli::dispatch_with_app_commands`], then the built-in
/// subcommand set (`serve` / `migrate` / etc.).
pub async fn dispatch_with_argv(
    app: App,
    argv: Vec<std::ffi::OsString>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Step 0: intercept the unified-help requests before any per-command
    // clap parser sees argv. `umbral help`, `umbral --help`, and `umbral -h`
    // all print the merged catalog of built-in + plugin commands and exit
    // clean. This is gaps2 #54: the user gets one list of everything they
    // can run, not a per-layer clap help that omits the other layer's
    // commands. (A bare `umbral` keeps its documented serve default.)
    if wants_top_level_help(&argv) {
        print!("{}", render_full_help(&app));
        return Ok(());
    }

    // Step 0.5: decide whether this command runs against a live application.
    // If it does, fire every plugin's `on_ready` before either dispatch layer
    // runs. If it doesn't — a schema command, an offline utility — the hooks
    // must not run at all: they seed content into tables `migrate` has not
    // created yet (gaps3 #41). `serve` is deferred rather than skipped; it fires
    // them from `App::serve`, after `auto_migrate_on_serve` has applied
    // migrations. `App::ready` is idempotent, so this is a no-op if the caller
    // used `App::build()`.
    let subcommand = subcommand_name(&argv);
    let builtins = builtin_command_names();
    let reserved: Vec<&str> = builtins.iter().map(String::as_str).collect();

    // Collect the registered commands ONCE. Collecting runs every plugin's
    // command constructors, builds each command's clap parser, and prints the
    // built-in-shadow warning — so asking the three questions below via three
    // separate collections printed that warning three times and rebuilt every
    // parser three times. One `CommandSet`, three questions.
    let commands = umbral_core::cli::CommandSet::collect(app.commands(), app.plugins(), &reserved);

    // A registered command gets to say whether it needs a live app
    // (`PluginCommand::needs_ready`). A code generator like `startpermission`
    // says no: firing `on_ready` would run every plugin's seeding/backfill
    // before writing a file, and on a fresh checkout that fails against tables
    // `migrate` has not created yet. Only if NO registered command claims the
    // name do we fall back to `builtin_needs_ready`, which speaks only for this
    // binary's own subcommands.
    let needs_ready = subcommand
        .as_deref()
        .and_then(|name| commands.needs_ready(name))
        .unwrap_or_else(|| builtin_needs_ready(subcommand.as_deref()));

    if needs_ready {
        app.ready()?;
    } else if app.ready_already_fired() && !matches!(subcommand.as_deref(), None | Some("serve")) {
        // The caller built with `App::build()`, so the hooks fired before argv
        // was ever read — the exact shape of gaps3 #41. Nothing we can do about
        // it here (they've already run), but say so at the moment it bites.
        eprintln!(
            "warning: plugin `on_ready` hooks already fired before `{}` ran. They seed \n\
             content and backfill rows, which is wrong for a schema command against a \n\
             fresh database. In main.rs, build with `.build_deferred()?` instead of \n\
             `.build()?` and let `dispatch` decide when the app is ready.",
            subcommand.as_deref().unwrap_or("<none>"),
        );
    }

    // Step 1: try the project's own commands and the plugin-contributed
    // ones first. The App's `AppBuilder::command` registrations come first
    // (what `umbral startcommand --in root` writes), then each registered
    // plugin's `commands()` — `createsuperuser` from `umbral-auth`,
    // `tasks-worker` from `umbral-tasks`. If argv matches one, that
    // command's `run` fires and we return; otherwise we fall through to
    // the built-in subcommand set below.
    if !commands.is_empty() {
        match commands.dispatch(argv.clone()).await {
            Ok(umbral_core::cli::DispatchOutcome::Matched(_)) => return Ok(()),
            Ok(umbral_core::cli::DispatchOutcome::Help(msg)) => {
                // A plugin command's --help was requested (e.g.
                // `umbral createsuperuser --help`). That's command-specific
                // help, not the top-level catalog, so print clap's
                // rendered body verbatim and exit clean.
                print!("{msg}");
                return Ok(());
            }
            Ok(umbral_core::cli::DispatchOutcome::Unmatched) => {
                // Fall through to the built-in subcommands.
            }
            Err(e) => return Err(e),
        }
    }

    // Step 2: built-in subcommands. clap parses argv against the fixed
    // `Command` enum. If argv has a token that's neither a built-in
    // subcommand nor a plugin command, clap surfaces a usage error here.
    let cli = match Cli::try_parse_from(&argv) {
        Ok(c) => c,
        Err(e) => {
            use clap::error::ErrorKind;
            match e.kind() {
                // Unknown subcommand / stray arg. The token is neither a
                // plugin command (Step 1 ruled that out) nor a built-in.
                // Print our unified `error: unknown command` + the full
                // catalog so the user sees what IS available, then exit
                // non-zero. Routing through `render_full_help` instead of
                // clap's default keeps plugin commands in the listing.
                ErrorKind::InvalidSubcommand
                | ErrorKind::UnknownArgument
                | ErrorKind::InvalidValue => {
                    let bad = unknown_token(&argv);
                    eprint!("{}", render_unknown(&app, bad.as_deref()));
                    std::process::exit(2);
                }
                _ => {
                    // Genuine clap output (a subcommand's own --help, a
                    // missing-required-arg usage error, --version, …).
                    // Let clap render it as before.
                    e.print()?;
                    std::process::exit(if e.use_stderr() { 2 } else { 0 });
                }
            }
        }
    };
    match cli.command.unwrap_or(Command::Serve { addr: None }) {
        Command::Serve { addr } => serve(app, addr).await,
        Command::Makemigrations { empty } => makemigrations(empty).await,
        Command::Migrate {
            fake,
            fake_initial,
            allow_drift,
            allow_destructive,
            allow_in_memory,
        } => {
            migrate(
                fake,
                fake_initial,
                allow_drift,
                allow_destructive,
                allow_in_memory,
            )
            .await
        }
        Command::Showmigrations => showmigrations().await,
        Command::Checkmigrations { strict } => checkmigrations(strict).await,
        Command::Typegen { out, check } => typegen(out, check),
        Command::Inspectdb {
            output,
            mark_applied,
        } => inspectdb(output, mark_applied).await,
        Command::Dumpdata { output } => dumpdata(output).await,
        Command::Loaddata { input } => loaddata(input).await,
        Command::Importcsv { table, input } => importcsv(table, input).await,
        Command::Dev { watch, run_args } => dev(watch, run_args).await,
        Command::Maskkeygen => maskkeygen(),
        Command::Squashmigrations { plugin } => squashmigrations(plugin).await,
    }
}

/// gaps2 #100 — collapse `<plugin>`'s migration history into a single optimized
/// squash file. Non-destructive: originals stay on disk so older deploys keep
/// working, and the runner treats the squash and its originals as mutually
/// exclusive. Prints what was written and the next step.
async fn squashmigrations(plugin: String) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let out = umbral::migrate::squash_in(
        std::path::Path::new(umbral::migrate::MIGRATIONS_DIR),
        &plugin,
    )?;
    println!(
        "Squashed {} migrations for `{plugin}` into {}",
        out.replaced.len(),
        out.id
    );
    println!("  wrote {}", out.path.display());
    println!("  replaces: {}", out.replaced.join(", "));
    println!(
        "\nThe originals are kept on disk (non-destructive). `migrate` now applies the squash on \n\
         a fresh database and record-only on databases that already ran the originals. Once EVERY \n\
         deploy has migrated past this squash, delete the {} original file(s) it replaces.",
        out.replaced.len()
    );
    Ok(())
}

/// The built-in commands that need NO project — no `App`, database, settings,
/// or compiled models — and can therefore run standalone. Every OTHER command
/// (`serve`, `migrate`, `makemigrations`, `seed_data`, …) needs the project's
/// compiled `App`, so the global `umbral` binary forwards it to
/// `cargo run -- <cmd>` instead.
///
/// Keep this in sync with [`try_run_standalone`]. It's a list, not a special
/// case: add a project-independent utility here and both the global binary and
/// `cargo run -- <cmd>` pick it up.
pub const STANDALONE_COMMANDS: &[&str] = &["maskkeygen"];

/// If `argv` names a [project-independent](STANDALONE_COMMANDS) built-in, run it
/// and return `Some(result)`. Return `None` otherwise, so the caller (the global
/// `umbral` binary) forwards the command to the project via `cargo run`.
///
/// This is what lets `umbral maskkeygen` work anywhere — including outside a
/// project — without a build, while `umbral migrate` / `umbral seed_data` still
/// forward to the compiled project that actually owns those commands.
pub fn try_run_standalone(
    argv: &[String],
) -> Option<Result<(), Box<dyn std::error::Error + Send + Sync>>> {
    match argv.first().map(String::as_str) {
        Some("maskkeygen") => Some(maskkeygen()),
        _ => None,
    }
}

/// Generate a fresh `Masked<T>` field-encryption keypair and print the
/// two env-var lines. The public key encrypts (every tier that writes
/// masked data needs it); the private key decrypts (`reveal()`) and
/// crypto-shreds on deletion.
fn maskkeygen() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let (public, secret) = umbral_core::orm::MaskKeyring::generate();
    println!("# Masked<T> field-encryption keypair — add to your environment / .env:");
    println!("#   UMBRAL_MASK_PUBLIC_KEY encrypts; UMBRAL_MASK_PRIVATE_KEY decrypts (reveal()).");
    println!(
        "#   Keep the PRIVATE key secret. Destroying it crypto-shreds every masked column\n\
         #   (a fast bulk \"right to be forgotten\")."
    );
    println!(
        "#   WARNING: the private key is printed below to STDOUT. Capture it straight into a\n\
         #   secret store (Vault, cloud secret manager, a sealed CI variable) and keep it out\n\
         #   of shell history, terminal scrollback, CI job logs, and any committed .env."
    );
    println!("UMBRAL_MASK_PUBLIC_KEY={public}");
    println!("UMBRAL_MASK_PRIVATE_KEY={secret}");
    Ok(())
}

/// True when argv is asking for the top-level command catalog: the
/// `help` pseudo-subcommand, or a top-level `--help` / `-h`. A `--help`
/// that follows a subcommand (e.g. `migrate --help`) is NOT top-level —
/// that's command-specific help and is left to clap, so we only treat
/// the FIRST post-argv0 token.
///
/// A bare `umbral` (no subcommand) is deliberately NOT intercepted: it
/// keeps its documented default of booting the server (`Serve`), which
/// the example apps rely on via a plain `cargo run`.
fn wants_top_level_help(argv: &[std::ffi::OsString]) -> bool {
    match argv.get(1) {
        None => false,
        Some(first) => first == "help" || first == "--help" || first == "-h",
    }
}

/// The first non-flag token after argv0 — the subcommand the user
/// tried to run. Used to name the offending command in the
/// `error: unknown command \`<x>\`` line.
fn unknown_token(argv: &[std::ffi::OsString]) -> Option<String> {
    argv.iter()
        .skip(1)
        .find(|a| !a.to_string_lossy().starts_with('-'))
        .map(|a| a.to_string_lossy().into_owned())
}

/// Build the merged `(name, about)` catalog: every built-in subcommand
/// (read off the derived clap `Command` via `CommandFactory`), then the
/// project's own `AppBuilder::command` registrations, then every
/// plugin-contributed command. Built-ins are placed first so they win a
/// name clash in [`umbral_core::cli::render_help`]'s dedup.
fn full_catalog(app: &App) -> Vec<(String, Option<String>)> {
    let mut catalog: Vec<(String, Option<String>)> = Vec::new();
    let root = <Cli as CommandFactory>::command();
    for sub in root.get_subcommands() {
        catalog.push((
            sub.get_name().to_string(),
            sub.get_about().map(|s| s.to_string()),
        ));
    }
    let builtins = builtin_command_names();
    let reserved: Vec<&str> = builtins.iter().map(String::as_str).collect();
    catalog.extend(umbral_core::cli::command_catalog_with_app_commands(
        app.commands(),
        app.plugins(),
        &reserved,
    ));
    catalog
}

/// The framework binary's own subcommands — `serve`, `migrate`, `makemigrations`,
/// … — read off the derived clap parser rather than hand-listed, so a new
/// subcommand reserves its own name with nothing to remember.
///
/// These names are **unavailable** to an app or plugin command. Dispatch tries
/// registered commands before the built-in parser, so a command named `migrate`
/// would not collide loudly — it would quietly take over, and the next deploy
/// would apply zero migrations and exit 0. `collect_commands` drops any command
/// that lands on one of these, and says so.
pub fn builtin_command_names() -> Vec<String> {
    let mut names: Vec<String> = <Cli as CommandFactory>::command()
        .get_subcommands()
        .map(|s| s.get_name().to_string())
        .collect();
    names.push("help".to_string());
    names
}

/// Render the full help screen (built-ins + plugin commands), for
/// `umbral help` / `umbral --help` / bare `umbral`. Prints to stdout.
fn render_full_help(app: &App) -> String {
    umbral_core::cli::render_help(&full_catalog(app))
}

/// Render the unknown-command screen: an `error: unknown command` line
/// (naming the bad token if known) followed by the full catalog so the
/// user sees what they CAN run. Printed to stderr; the caller exits
/// non-zero.
fn render_unknown(app: &App, bad: Option<&str>) -> String {
    let mut s = String::new();
    match bad {
        Some(b) => s.push_str(&format!("error: unknown command `{b}`\n\n")),
        None => s.push_str("error: unknown command\n\n"),
    }
    s.push_str(&render_full_help(app));
    s
}

/// `umbral dev` — wraps `cargo-watch` to re-run `cargo run` on source
/// changes. If `cargo-watch` isn't installed, prints the install hint
/// and exits non-zero so the user notices.
///
/// Template edits don't need this command — they hot-reload in-process
/// when `settings.environment == Dev` (see `umbral-core/src/templates.rs`).
/// `dev` exists for the Rust-source case where the binary needs a
/// rebuild + restart.
async fn dev(
    extra_watches: Vec<String>,
    run_args: Vec<String>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Probe for cargo-watch up front so the failure message is clear.
    let probe = std::process::Command::new("cargo")
        .args(["watch", "--version"])
        .stdout(std::process::Stdio::null())
        .stderr(std::process::Stdio::null())
        .status();
    if probe.is_err() || probe.as_ref().map(|s| !s.success()).unwrap_or(true) {
        eprintln!(
            "umbral dev: `cargo-watch` is not installed.\n\n\
             Install with:\n\n\
             \x20\x20\x20\x20cargo install cargo-watch\n\n\
             Then re-run `cargo run -- dev`.\n\n\
             Workaround without cargo-watch: leave one terminal running\n\
             `cargo run` and Ctrl-C + re-run after each edit. Templates\n\
             still hot-reload in dev mode without any restart.",
        );
        std::process::exit(1);
    }

    // Build the cargo-watch invocation. -x runs the given cargo command;
    // -w adds extra watch paths. Default watches are cargo-watch's own
    // (Cargo.toml + src/) so we don't pile -w on every invocation.
    let mut cmd = std::process::Command::new("cargo");
    cmd.arg("watch");
    for path in &extra_watches {
        cmd.arg("-w").arg(path);
    }
    let cargo_cmd = if run_args.is_empty() {
        "run".to_string()
    } else {
        format!("run -- {}", run_args.join(" "))
    };
    cmd.arg("-x").arg(&cargo_cmd);

    eprintln!("umbral dev: watching for changes, running `cargo {cargo_cmd}` on each save");
    eprintln!(
        "umbral dev: templates also hot-reload in-process; no restart needed for .html edits"
    );
    eprintln!("umbral dev: Ctrl-C to stop");
    eprintln!();

    let status = cmd.status()?;
    if !status.success() {
        return Err(format!(
            "cargo-watch exited with status {}",
            status
                .code()
                .map(|c| c.to_string())
                .unwrap_or_else(|| "<signal>".to_string())
        )
        .into());
    }
    Ok(())
}

async fn serve(
    app: App,
    addr_override: Option<String>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // gaps3 #23: `App::builder().auto_migrate_on_serve()` applies pending
    // migrations here — on the `serve` command ONLY, never during
    // `makemigrations` / `migrate` / any other subcommand (which don't route
    // through this fn). This owns the "migrate exactly when starting the server"
    // logic that consumers otherwise hand-roll with an argv-sniffing guard.
    if app.auto_migrate_on_serve_enabled() {
        let n = umbral::migrate::run().await?;
        if n > 0 {
            eprintln!("auto-migrate: applied {n} migration(s)");
        }
    }
    let addr_str = match addr_override {
        Some(s) => s,
        None => umbral_core::settings::get().bind_addr.clone(),
    };
    let addr: SocketAddr = addr_str
        .parse()
        .map_err(|e| format!("umbral: invalid bind_addr `{addr_str}`: {e}"))?;
    app.serve(addr).await?;
    Ok(())
}

async fn makemigrations(
    empty: Option<String>,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // --empty <plugin>: write a no-op migration (current snapshot, empty
    // ops) the developer edits to add a `RunSql` data migration.
    if let Some(plugin) = empty {
        let path = umbral::migrate::make_empty(&plugin).await?;
        println!("Wrote {} (empty)", path.display());
        println!(
            "  Edit it to add a data migration, e.g.:\n  \
             {{ \"kind\": \"RunSql\", \"sql\": \"UPDATE ... SET ...\", \
             \"reverse_sql\": null }}"
        );
        return Ok(());
    }

    match umbral::migrate::make().await {
        Ok(paths) => {
            for path in paths {
                println!("Wrote {}", path.display());
            }
            Ok(())
        }
        Err(MigrateError::NoChanges) => {
            println!("no changes detected");
            Ok(())
        }
        Err(err) => Err(Box::new(err)),
    }
}

async fn migrate(
    fake: Option<String>,
    fake_initial: bool,
    allow_drift: bool,
    allow_destructive: bool,
    allow_in_memory: bool,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // gaps3 #61 — refuse to "migrate" a database that is about to evaporate.
    //
    // The default `database_url` is `sqlite::memory:`, so an app whose config never
    // loaded (a stale `UMBRA_`-prefixed `.env` after the rename, a missing umbral.toml)
    // silently migrates an IN-MEMORY database and prints "Applied 19 migration(s)". The
    // command reports success, writes nothing, and the operator has no way to tell —
    // which is strictly worse than an error, because they will now trust it.
    //
    // Found in `examples/shop`, whose entire `.env` had been dead since the rename.
    if let Some(cfg) = umbral::settings::get_opt() {
        let url = &cfg.database_url;
        if !allow_in_memory && (url.contains(":memory:") || url.contains("mode=memory")) {
            eprintln!("error: umbral migrate: `database_url` is an IN-MEMORY database ({url}).");
            eprintln!();
            eprintln!("  Migrating it would apply every migration to a database that is");
            eprintln!("  discarded the moment this process exits — reporting success and");
            eprintln!("  persisting nothing.");
            eprintln!();
            eprintln!("  `sqlite::memory:` is the DEFAULT, so this almost always means your");
            eprintln!("  configuration never loaded. Common causes:");
            eprintln!("    - a `.env` still using the old `UMBRA_` prefix (it is now `UMBRAL_`)");
            eprintln!("    - no `umbral.toml` and no `UMBRAL_DATABASE_URL` in the environment");
            eprintln!();
            eprintln!("  Set UMBRAL_DATABASE_URL (e.g. sqlite://app.db?mode=rwc) and re-run.");
            eprintln!("  If an ephemeral migrate IS what you want (tests, CI), say so:");
            eprintln!("    umbral migrate --allow-in-memory");
            return Err("refusing to migrate an in-memory database".into());
        }
    }

    // --fake <plugin/name>: mark one migration applied without running SQL.
    if let Some(ref spec) = fake {
        let (plugin, name) = parse_migration_spec(spec)?;
        umbral::migrate::fake_apply(plugin, name).await?;
        println!("Marked {spec} as applied (no SQL executed)");
        return Ok(());
    }

    // audit_2 core-migrate #6: refuse to APPLY a migration that drops a table /
    // column (destroys rows) unless the operator explicitly opts in with
    // `--allow-destructive`. A single missing `.model::<T>()` registration
    // auto-generates a DropTable, and the plain `makemigrations && migrate` loop
    // would otherwise drop a production table with no confirmation. This gates
    // the APPLY (checkmigrations is only advisory / CI-side).
    if !allow_destructive {
        let unsafe_ops: Vec<_> = umbral::migrate::check_pending_safety()
            .await?
            .into_iter()
            .filter(|c| c.safety.is_unsafe())
            .collect();
        if !unsafe_ops.is_empty() {
            eprintln!(
                "error: umbral migrate: {} pending destructive operation(s) would DESTROY DATA:",
                unsafe_ops.len()
            );
            for c in &unsafe_ops {
                eprintln!(
                    "    [UNSAFE] {}/{}: {}",
                    c.plugin,
                    c.migration,
                    c.safety.reason()
                );
            }
            eprintln!();
            eprintln!(
                "  These usually come from an unregistered model/plugin (a removed \
                 `.model::<T>()`, a dropped plugin, or a feature flag off).\n  \
                 If the drop is intended, re-run: `umbral migrate --allow-destructive`.\n  \
                 If NOT, restore the model registration and re-run `makemigrations`."
            );
            return Err(format!(
                "refusing to apply {} destructive migration operation(s) without --allow-destructive",
                unsafe_ops.len()
            )
            .into());
        }
    }

    // --fake-initial: for every plugin, if the 0001 tables exist, fake-apply.
    if fake_initial {
        let n = umbral::migrate::fake_initial().await?;
        if n == 0 {
            println!("No plugins needed fake-initial (either already applied or tables absent)");
        } else {
            println!("Fake-applied initial migration for {n} plugin(s)");
        }
        return Ok(());
    }

    // Normal migrate with optional --allow-drift.
    match umbral::migrate::run_checked(allow_drift).await {
        Ok(n) => {
            if n == 0 {
                println!("No pending migrations");
            } else {
                println!("Applied {n} migration(s)");
            }
            Ok(())
        }
        Err(MigrateError::DriftDetected { ref missing }) => {
            let names: Vec<String> = missing.iter().map(|(p, n)| format!("{p}/{n}")).collect();
            eprintln!("error: umbral migrate: drift detected");
            eprintln!("  The following migrations are in the tracking table but missing on disk:");
            for name in &names {
                eprintln!("    [!] {name}");
            }
            eprintln!();
            eprintln!(
                "  Options:\n  \
                 1. Restore the file(s) from VCS.\n  \
                 2. Run `umbral migrate --allow-drift` to proceed and apply pending migrations.\n  \
                 3. Run `umbral migrate --fake <plugin/name>` to mark an individual migration \
                 as applied without running SQL."
            );
            Err(Box::new(MigrateError::DriftDetected {
                missing: missing.clone(),
            }))
        }
        Err(err) => Err(Box::new(err)),
    }
}

/// Parse `"plugin/name"` into `(&str, &str)`. Returns an error if the
/// format is wrong.
fn parse_migration_spec(
    spec: &str,
) -> Result<(&str, &str), Box<dyn std::error::Error + Send + Sync>> {
    let mut parts = spec.splitn(2, '/');
    let plugin = parts.next().ok_or("migration spec must be `plugin/name`")?;
    let name = parts
        .next()
        .ok_or("migration spec must be `plugin/name`; missing name after `/`")?;
    Ok((plugin, name))
}

async fn showmigrations() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let pending = umbral::migrate::show().await?;
    if pending > 0 {
        println!("\n{pending} migration(s) not yet applied.");
    }
    Ok(())
}

/// `umbral typegen` — emit TypeScript types for every registered model
/// (gaps3 #38).
///
/// Reads the model registry, which `App::build()` has already populated by the
/// time `dispatch` runs, so this touches no database.
///
/// `--check` is the CI gate: it compares the file `--out` names against what
/// the models would generate now and exits non-zero on any difference. Run it
/// beside `cargo test` and a schema change can never merge with a stale types
/// file next to it.
fn typegen(
    out: Option<PathBuf>,
    check: bool,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let generated = umbral::typegen::typescript();

    let Some(path) = out else {
        print!("{generated}");
        return Ok(());
    };

    if check {
        // A missing file is drift, not an IO error the operator has to decode.
        let existing = std::fs::read_to_string(&path).unwrap_or_default();
        if existing == generated {
            println!("{} is up to date.", path.display());
            return Ok(());
        }
        return Err(format!(
            "{} is out of date with the models. Regenerate it:\n    \
             cargo run -- typegen --out {}",
            path.display(),
            path.display(),
        )
        .into());
    }

    if let Some(parent) = path.parent().filter(|p| !p.as_os_str().is_empty()) {
        std::fs::create_dir_all(parent)?;
    }
    std::fs::write(&path, &generated)?;
    println!("Wrote {}.", path.display());
    Ok(())
}

/// `umbral checkmigrations` — classify every pending operation for
/// zero-downtime safety (feature #65). Prints the UNSAFE ops first, then
/// WARNING, then a SAFE count, and exits non-zero when any UNSAFE op is
/// present (or any WARNING under `--strict`). Applies nothing.
async fn checkmigrations(strict: bool) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let ops = umbral::migrate::check_pending_safety().await?;
    if ops.is_empty() {
        println!("No pending migrations — nothing to check.");
        return Ok(());
    }

    let unsafe_ops: Vec<_> = ops.iter().filter(|c| c.safety.is_unsafe()).collect();
    let warn_ops: Vec<_> = ops.iter().filter(|c| c.safety.is_warning()).collect();
    let safe_count = ops.len() - unsafe_ops.len() - warn_ops.len();

    let migrations: std::collections::BTreeSet<_> =
        ops.iter().map(|c| (&c.plugin, &c.migration)).collect();
    println!(
        "Checking {} operation(s) across {} pending migration(s)...\n",
        ops.len(),
        migrations.len()
    );

    if !unsafe_ops.is_empty() {
        println!("UNSAFE ({}):", unsafe_ops.len());
        for c in &unsafe_ops {
            println!(
                "  [{}] {}/{} — {}",
                op_kind(&c.op),
                c.plugin,
                c.migration,
                c.safety.reason()
            );
        }
        println!();
    }

    if !warn_ops.is_empty() {
        println!("WARNING ({}):", warn_ops.len());
        for c in &warn_ops {
            println!(
                "  [{}] {}/{} — {}",
                op_kind(&c.op),
                c.plugin,
                c.migration,
                c.safety.reason()
            );
        }
        println!();
    }

    println!(
        "Summary: {} safe, {} warning, {} unsafe.",
        safe_count,
        warn_ops.len(),
        unsafe_ops.len()
    );

    // Gate: UNSAFE always fails; WARNING fails only under --strict.
    let blocked = !unsafe_ops.is_empty() || (strict && !warn_ops.is_empty());
    if blocked {
        let why = if !unsafe_ops.is_empty() {
            format!("{} unsafe operation(s) found", unsafe_ops.len())
        } else {
            format!("{} warning(s) found (--strict)", warn_ops.len())
        };
        return Err(format!(
            "checkmigrations: {why}. Review the expand-contract notes above before deploying."
        )
        .into());
    }

    println!("\nAll pending operations are safe for a rolling deploy.");
    Ok(())
}

/// Short uppercase tag for an operation, used in the `checkmigrations`
/// report (e.g. `DROP TABLE`, `RENAME COL`, `ADD COL`).
fn op_kind(op: &umbral::migrate::Operation) -> &'static str {
    use umbral::migrate::Operation;
    match op {
        Operation::CreateTable { .. } => "CREATE TABLE",
        Operation::DropTable { .. } => "DROP TABLE",
        Operation::CreateView {
            materialized: true, ..
        } => "CREATE MATVIEW",
        Operation::CreateView { .. } => "CREATE VIEW",
        Operation::DropView {
            materialized: true, ..
        } => "DROP MATVIEW",
        Operation::DropView { .. } => "DROP VIEW",
        Operation::AddColumn { .. } => "ADD COL",
        Operation::DropColumn { .. } => "DROP COL",
        Operation::AlterColumn { .. } => "ALTER COL",
        Operation::RenameTable { .. } => "RENAME TABLE",
        Operation::RenameColumn { .. } => "RENAME COL",
        Operation::SetColumnComment { .. } => "COMMENT COL",
        Operation::CreateM2MTable { .. } => "CREATE M2M",
        Operation::DropM2MTable { .. } => "DROP M2M",
        Operation::RunSql { .. } => "RUN SQL",
        Operation::AddIndex { unique: true, .. } => "ADD UNIQUE",
        Operation::AddIndex { unique: false, .. } => "ADD INDEX",
        Operation::DropIndex { .. } => "DROP INDEX",
    }
}

async fn inspectdb(
    output: PathBuf,
    mark_applied: bool,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let opts = InspectOptions {
        output,
        mark_applied,
    };
    match umbral::inspect::inspectdb(opts).await {
        Ok(report) => {
            println!(
                "Inspected {} table(s), {} column(s)",
                report.tables, report.columns,
            );
            println!("Wrote {}", report.models_path.display());
            println!("Wrote {}", report.migration_path.display());
            Ok(())
        }
        Err(InspectError::NoTables) => {
            println!("no tables found in the database");
            Ok(())
        }
        Err(err) => Err(Box::new(err)),
    }
}

async fn dumpdata(output: PathBuf) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    umbral::backup::dump_to_path(&output).await?;
    println!("Wrote {}", output.display());
    Ok(())
}

async fn loaddata(input: PathBuf) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let report = umbral::backup::load_from_path(&input).await?;
    println!(
        "Loaded {} row(s) into {} table(s)",
        report.rows_loaded,
        report.tables_loaded.len()
    );
    for skipped in &report.skipped_tables {
        eprintln!("warning: skipped table `{skipped}` (not in current schema)");
    }
    Ok(())
}

/// `umbral importcsv <table> <file.csv>` — parse the CSV (the `csv` crate
/// handles quoting/escaping) and hand the header + string rows to
/// `import_table_rows`, which coerces each cell to its column type and
/// inserts through the validated dynamic write path.
async fn importcsv(
    table: String,
    input: PathBuf,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Resolve the table against the registered models so a typo fails
    // loudly (with the list of valid tables) before we read the file.
    let models = umbral::migrate::registered_models();
    let Some(meta) = models.into_iter().find(|m| m.table == table) else {
        let mut known: Vec<String> = umbral::migrate::registered_models()
            .iter()
            .map(|m| m.table.clone())
            .collect();
        known.sort();
        return Err(format!(
            "importcsv: unknown table `{table}`. Registered tables: {}",
            known.join(", ")
        )
        .into());
    };

    let mut reader = csv::ReaderBuilder::new()
        .has_headers(true)
        .flexible(true)
        .from_path(&input)?;
    let headers: Vec<String> = reader.headers()?.iter().map(|s| s.to_string()).collect();
    if headers.is_empty() {
        return Err("importcsv: the CSV has no header row".into());
    }
    let mut rows: Vec<Vec<String>> = Vec::new();
    for record in reader.records() {
        let record = record?;
        rows.push(record.iter().map(|s| s.to_string()).collect());
    }

    let report = umbral::orm::import_table_rows(&meta, &headers, &rows).await;
    println!(
        "Imported {} row(s) into `{}` ({} failed)",
        report.inserted,
        table,
        report.errors.len()
    );
    for (line, message) in &report.errors {
        eprintln!("  line {line}: {message}");
    }
    // Non-zero exit when any row failed, so a CI/script catches a partial
    // import without parsing stdout.
    if report.errors.is_empty() {
        Ok(())
    } else {
        Err(format!("importcsv: {} row(s) failed", report.errors.len()).into())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use async_trait::async_trait;
    use clap::ArgMatches;
    use umbral::Settings;
    use umbral_core::cli::{CliError, PluginCommand};
    use umbral_core::plugin::Plugin;

    #[test]
    fn forward_args_prefix_cargo_run_dashdash() {
        // `umbral dev` → `cargo run -- dev`
        assert_eq!(
            cargo_run_forward_args(&["dev".to_string()]),
            vec!["run", "--", "dev"]
        );
        // Flags and extra args ride along verbatim.
        assert_eq!(
            cargo_run_forward_args(&[
                "migrate".to_string(),
                "--fake".to_string(),
                "accounts/0001_auto".to_string(),
            ]),
            vec!["run", "--", "migrate", "--fake", "accounts/0001_auto"]
        );
    }

    #[test]
    fn in_cargo_project_detects_manifest_upward() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let root = tmp.path();
        // No Cargo.toml anywhere yet.
        assert!(!in_cargo_project(root));
        // A manifest at the root is found from a nested subdir (like cargo).
        std::fs::write(root.join("Cargo.toml"), b"[package]\nname='x'\n").unwrap();
        let nested = root.join("src").join("widgets");
        std::fs::create_dir_all(&nested).unwrap();
        assert!(in_cargo_project(&nested), "walks up to find the manifest");
        assert!(in_cargo_project(root));
    }

    struct WorkerCmd;

    #[async_trait]
    impl PluginCommand for WorkerCmd {
        fn command(&self) -> clap::Command {
            clap::Command::new("tasks-worker").about("Run the task worker")
        }
        async fn run(&self, _m: &ArgMatches) -> Result<(), CliError> {
            Ok(())
        }
    }

    struct WorkerPlugin;

    impl Plugin for WorkerPlugin {
        fn name(&self) -> &'static str {
            "tasks"
        }
        fn commands(&self) -> Vec<Box<dyn PluginCommand>> {
            vec![Box::new(WorkerCmd)]
        }
    }

    async fn app_with_worker() -> App {
        let settings = Settings::from_env().expect("figment defaults load");
        let pool = umbral::db::connect_sqlite("sqlite::memory:")
            .await
            .expect("in-memory sqlite connects");
        App::builder()
            .settings(settings)
            .database("default", pool)
            .plugin(WorkerPlugin)
            .build()
            .expect("App builds")
    }

    #[test]
    fn wants_top_level_help_recognizes_help_forms() {
        let os = |s: &str| std::ffi::OsString::from(s);
        assert!(wants_top_level_help(&[os("umbral"), os("help")]));
        assert!(wants_top_level_help(&[os("umbral"), os("--help")]));
        assert!(wants_top_level_help(&[os("umbral"), os("-h")]));
        // Bare invocation keeps the serve default — NOT intercepted.
        assert!(!wants_top_level_help(&[os("umbral")]));
        // `migrate --help` is command-specific, left to clap.
        assert!(!wants_top_level_help(&[
            os("umbral"),
            os("migrate"),
            os("--help")
        ]));
        // A real subcommand is not help.
        assert!(!wants_top_level_help(&[os("umbral"), os("migrate")]));
    }

    #[test]
    fn unknown_token_picks_first_non_flag() {
        let os = |s: &str| std::ffi::OsString::from(s);
        assert_eq!(
            unknown_token(&[os("umbral"), os("--verbose"), os("frobnicate")]).as_deref(),
            Some("frobnicate")
        );
        assert_eq!(unknown_token(&[os("umbral")]), None);
    }

    // NOTE: both the help and unknown-command paths are asserted in ONE
    // test because `App::build` calls the global `settings::init` (a
    // `OnceLock`) which panics if called twice in the same process.
    // Building one App and exercising both render paths against it sidesteps
    // that, and is also a faithful "one process, one App" shape.
    #[tokio::test]
    async fn help_and_unknown_list_builtins_and_plugin_commands() {
        let app = app_with_worker().await;

        // --- full help (umbral help / --help) ---
        let out = render_full_help(&app);
        // A built-in subcommand with its real `about`.
        assert!(
            out.contains("migrate"),
            "built-in `migrate` missing:\n{out}"
        );
        assert!(
            out.contains("Apply every pending migration"),
            "built-in `migrate` about missing:\n{out}"
        );
        // The plugin-contributed command with its about.
        assert!(
            out.contains("tasks-worker") && out.contains("Run the task worker"),
            "plugin command missing:\n{out}"
        );
        // Column alignment: built-in and plugin descriptions start at the
        // same offset on their respective lines.
        let mig_line = out
            .lines()
            .find(|l| l.trim_start().starts_with("migrate"))
            .unwrap();
        let worker_line = out.lines().find(|l| l.contains("tasks-worker")).unwrap();
        let mig_col = mig_line.find("Apply every pending migration").unwrap();
        let worker_col = worker_line.find("Run the task worker").unwrap();
        assert_eq!(mig_col, worker_col, "descriptions not aligned:\n{out}");

        // --- unknown command (umbral frobnicate) ---
        let out = render_unknown(&app, Some("frobnicate"));
        assert!(
            out.contains("unknown command") && out.contains("frobnicate"),
            "missing unknown-command error:\n{out}"
        );
        // Still shows what IS available — both a built-in and the plugin cmd.
        assert!(out.contains("migrate"), "listing missing built-in:\n{out}");
        assert!(
            out.contains("tasks-worker"),
            "listing missing plugin cmd:\n{out}"
        );
    }
}