rustango 0.61.13

//! Tenant provisioning + management subcommands.
//!
//! Composes with `crate::migrate::manage::run` — recognizes the
//! tenancy-specific verbs (`create-tenant`, `drop-tenant`,
//! `purge-tenant`, `list-tenants`, `migrate-tenants`,
//! `migrate-registry`, `init-tenancy`, `create-operator`,
//! `create-user`, `run-server`, scope-aware `migrate`) and delegates
//! everything else to the standard single-tenant runner using the
//! registry pool.
//!
//! ## User wiring
//!
//! ```ignore
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     let registry_url = std::env::var("DATABASE_URL")?;
//!     let pool = rustango::sql::sqlx::PgPool::connect(&registry_url).await?;
//!     let pools = crate::tenancy::TenantPools::new(pool);
//!     let dir = std::path::Path::new("./migrations");
//!     crate::tenancy::manage::run(
//!         &pools,
//!         &registry_url,
//!         dir,
//!         std::env::args().skip(1),
//!     ).await?;
//!     Ok(())
//! }
//! ```
//!
//! ## Crate-internal layout
//!
//! - [`tenants`] — `create-tenant`, `drop-tenant`, `purge-tenant`,
//!   `list-tenants` plus the database-mode admin-DROP helper.
//! - [`users`] — `create-operator`, `create-user`, plus the
//!   schema-scoped pool builder used to land tenant inserts.
//! - [`migrations`] — `init-tenancy`, `migrate`, `migrate-registry`,
//!   `migrate-tenants` and the tenant migration report formatter.
//! - [`server`] — `run-server` (thin wrapper around
//!   [`super::server::run`]).
//! - [`args`] — shared positional / flag parsing helpers.

// Agent / skill verbs are MCP-only (see `super::agents`, gated the same way).
#[cfg(feature = "mcp")]
mod agents;
mod args;
mod audit;
mod data;
mod db_servers;
mod edit;
mod flush;
mod hosts;
mod inspect;
mod menu;
#[cfg(feature = "postgres")]
mod migrate_storage;
mod migrations;
mod operators;
mod reseal;
mod roles;
mod scaffold;
mod server;
#[cfg(feature = "sso")]
mod sso_check;
mod tenants;
mod users;
mod wizard;

/// Typed Rust API for tenancy provisioning — `create_tenant_if_missing`,
/// `create_operator_if_missing`, `create_user_if_missing`, `find_org`.
/// Use these from `Builder::seed_with` closures and other in-process
/// callers; the verb dispatcher
/// [`run_with_writer`](crate::tenancy::manage::run_with_writer) is the
/// CLI surface.
pub mod api;

use std::io::{self, Write};
use std::path::Path;

use super::error::TenancyError;
use super::pools::TenantPools;

/// `Cli` runs it before any pool exists.
#[cfg(feature = "manage")]
pub(crate) use scaffold::startapp_cmd as startapp;

/// Function pointer for the bootstrap initializer used by the
/// `init-tenancy` verb. Defaults to
/// [`crate::tenancy::bootstrap::init_tenancy`]; override via
/// [`run_with_init`] / [`run_with_writer_and_init`] to swap in a
/// custom [`crate::tenancy::TenantUserModel`] (typically threaded
/// from [`crate::manage::Cli::user_model`]).
pub type InitTenancyFn = fn(&Path) -> Result<super::bootstrap::InitTenancyReport, TenancyError>;

/// Dispatch entrypoint. Recognizes tenancy verbs and delegates the
/// rest to `crate::migrate::manage::run`.
///
/// `dir` is the migrations directory (same as the underlying
/// rustango-migrate runner). `registry_url` is needed for schema-
/// mode tenant migrations + tenant pool building; supply the same
/// value the registry pool was built from.
///
/// # Errors
/// Either a [`TenancyError`] from a tenancy verb, or a wrapped
/// `crate::migrate::MigrateError` from the delegated call.
pub async fn run<DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    registry_url: &str,
    dir: &Path,
    args: impl IntoIterator<Item = String>,
) -> Result<(), TenancyError>
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    let mut stdout = io::stdout();
    run_with_writer(pools, registry_url, dir, args, &mut stdout).await
}

/// Like [`run`] but with a custom bootstrap initializer — wires a
/// [`crate::tenancy::TenantUserModel`] override through to the
/// `init-tenancy` verb. Other verbs ignore `init_fn`.
///
/// # Errors
/// As [`run`].
pub async fn run_with_init<DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    registry_url: &str,
    dir: &Path,
    args: impl IntoIterator<Item = String>,
    init_fn: InitTenancyFn,
) -> Result<(), TenancyError>
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    let mut stdout = io::stdout();
    run_with_writer_and_init(pools, registry_url, dir, args, &mut stdout, init_fn).await
}

/// Same as [`run`] but writes user-facing output to `writer` —
/// useful for tests.
///
/// # Errors
/// As [`run`].
pub async fn run_with_writer<W: Write + Send, DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    registry_url: &str,
    dir: &Path,
    args: impl IntoIterator<Item = String>,
    writer: &mut W,
) -> Result<(), TenancyError>
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    run_with_writer_and_init(
        pools,
        registry_url,
        dir,
        args,
        writer,
        super::bootstrap::init_tenancy,
    )
    .await
}

/// Full-bore variant: custom writer **and** custom bootstrap
/// initializer. The other variants are ergonomic wrappers around
/// this one.
///
/// # Errors
/// As [`run`].
pub async fn run_with_writer_and_init<W: Write + Send, DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    registry_url: &str,
    dir: &Path,
    args: impl IntoIterator<Item = String>,
    writer: &mut W,
    init_fn: InitTenancyFn,
) -> Result<(), TenancyError>
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    // Boxed: inline, dispatch's state overflows a 2 MiB test thread in debug builds.
    Box::pin(dispatch(
        pools,
        registry_url,
        dir,
        args.into_iter().collect(),
        writer,
        init_fn,
    ))
    .await
}

/// What `Cli` knows about the deployment that a verb cannot see.
#[derive(Clone, Default)]
pub(crate) struct CliFacts {
    /// `with_tenant_provisioning` was called.
    pub(crate) provisioning: bool,
    /// `Cli::brand_storage`, for the verbs that delete brand files.
    pub(crate) brand_storage: Option<crate::storage::BoxedStorage>,
}

/// [`run_with_writer_and_init`] with the `Cli`'s [`CliFacts`].
#[cfg(feature = "manage")]
pub(crate) async fn run_from_cli<W: Write + Send, DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    registry_url: &str,
    dir: &Path,
    args: Vec<String>,
    writer: &mut W,
    init_fn: InitTenancyFn,
    facts: CliFacts,
) -> Result<(), TenancyError>
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    Box::pin(dispatch_with(
        pools,
        registry_url,
        dir,
        args,
        writer,
        init_fn,
        facts,
    ))
    .await
}

/// One verb, dispatched. Split out so `menu` can run a chosen verb through
/// the same match rather than shelling out or duplicating the table.
pub(super) async fn dispatch<W: Write + Send, DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    registry_url: &str,
    dir: &Path,
    args: Vec<String>,
    writer: &mut W,
    init_fn: InitTenancyFn,
) -> Result<(), TenancyError>
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    dispatch_with(
        pools,
        registry_url,
        dir,
        args,
        writer,
        init_fn,
        CliFacts::default(),
    )
    .await
}

async fn dispatch_with<W: Write + Send, DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    registry_url: &str,
    dir: &Path,
    args: Vec<String>,
    writer: &mut W,
    init_fn: InitTenancyFn,
    facts: CliFacts,
) -> Result<(), TenancyError>
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    let cmd = args.first().map_or("", String::as_str);

    match cmd {
        "" | "help" | "--help" | "-h" => {
            write_help(writer)?;
            Ok(())
        }
        "create-tenant" => {
            tenants::create_tenant(pools, registry_url, dir, &args[1..], writer).await
        }
        "test-tenant-connection" => tenants::test_tenant_connection(&args[1..], writer).await,
        "drop-tenant" => tenants::drop_tenant(pools, &args[1..], writer).await,
        "purge-tenant" => {
            tenants::purge_tenant(pools, &args[1..], writer, facts.brand_storage.clone()).await
        }
        "rotate-tenant-password" => {
            tenants::rotate_tenant_password(pools, &args[1..], writer).await
        }
        "list-tenants" => {
            args::no_args(&args[1..], "list-tenants")?;
            tenants::list_tenants(pools, writer).await
        }
        // #1344 — routing and display config were console-only to change.
        "edit-tenant" => edit::edit_tenant(pools, &args[1..], writer).await,
        "reseal-tenant-secrets" => reseal::reseal_tenant_secrets(pools, &args[1..], writer).await,
        // #1344 — the console has bound extra hostnames since #1318; these
        // give a deploy hook and a browser-less box the same reach.
        "list-hosts" => hosts::list_hosts(pools, &args[1..], writer).await,
        "add-host" => hosts::add_host(pools, &args[1..], writer).await,
        "remove-host" => hosts::remove_host(pools, &args[1..], writer).await,
        "set-host-enabled" => hosts::set_host_enabled(pools, &args[1..], writer).await,
        "add-db-server" => db_servers::add_db_server(pools, &args[1..], writer).await,
        "edit-db-server" => db_servers::edit_db_server(pools, &args[1..], writer).await,
        "list-db-servers" => db_servers::list_db_servers(pools, &args[1..], writer).await,
        "test-db-server" => db_servers::test_db_server(pools, &args[1..], writer).await,
        "remove-db-server" => db_servers::remove_db_server(pools, &args[1..], writer).await,
        "prewarm-pools" => {
            // v0.27.7 (#60) — eagerly build pools for every active
            // database-mode tenant. Useful as a post-deploy hook
            // after credential rotation, or to validate that all
            // tenants are reachable before flipping a load balancer.
            args::no_args(&args[1..], "prewarm-pools")?;
            let report = pools.prewarm_database_tenants().await?;
            writeln!(
                writer,
                "prewarm: {} active tenants — warmed {}, failed {}, skipped (cap) {}",
                report.total_active, report.warmed, report.failed, report.skipped_cap
            )?;
            migrations::tenant_failures(report.failed, report.total_active)
        }
        "migrate-tenants" => {
            migrations::migrate_tenants_cmd(pools, registry_url, dir, &args[1..], writer).await
        }
        "migrate-registry" => {
            migrations::migrate_registry_cmd(pools, dir, &args[1..], writer).await
        }
        #[cfg(feature = "postgres")]
        "migrate-tenant-storage" => {
            // PG-only: uses pg_dump | psql + schema-mode dispatch.
            // Downcast through `Any` so the generic dispatcher path
            // can still compile on multi-backend builds.
            let pg_pools = (pools as &dyn std::any::Any)
                .downcast_ref::<TenantPools<sqlx::Postgres>>()
                .ok_or_else(|| {
                    TenancyError::Validation(
                        "migrate-tenant-storage is Postgres-only (uses pg_dump | psql + \
                         schema-mode dispatch). Re-run with a postgres:// DATABASE_URL."
                            .into(),
                    )
                })?;
            migrate_storage::migrate_tenant_storage_cmd(pg_pools, registry_url, &args[1..], writer)
                .await
        }
        #[cfg(not(feature = "postgres"))]
        "migrate-tenant-storage" => Err(TenancyError::Validation(
            "migrate-tenant-storage requires the `postgres` feature (uses pg_dump | psql + \
             schema-mode is PG-only)"
                .into(),
        )),
        "create-operator" => users::create_operator_cmd(pools, &args[1..], writer).await,
        // #1344 — seeing who exists, and turning one off, were console-only.
        "list-operators" => operators::list_operators(pools, &args[1..], writer).await,
        "set-operator-active" => operators::set_operator_active(pools, &args[1..], writer).await,
        #[cfg(feature = "totp")]
        "reset-operator-totp" => operators::reset_operator_totp(pools, &args[1..], writer).await,
        // #1344 — the console renders all three; nothing printed them, so an
        // incident question needed a browser or a SQL client.
        "list-runs" => inspect::list_runs(pools, &args[1..], writer).await,
        "show-run" => inspect::show_run(pools, &args[1..], writer).await,
        "audit-log" => inspect::audit_log(pools, &args[1..], writer).await,
        "create-user" => users::create_user_cmd(pools, registry_url, &args[1..], writer).await,
        "create-superuser" => {
            users::create_superuser_cmd(pools, registry_url, &args[1..], writer).await
        }
        "set-superuser" => users::set_superuser_cmd(pools, registry_url, &args[1..], writer).await,
        #[cfg(feature = "passkey")]
        "revoke-passkey" => {
            users::revoke_passkey_cmd(pools, registry_url, &args[1..], writer).await
        }
        "reset-password" => {
            users::reset_password_cmd(pools, registry_url, &args[1..], writer).await
        }
        "set-password-link" => tenants::set_password_link(pools, &args[1..], writer).await,
        "reset-operator-password" => {
            users::reset_operator_password_cmd(pools, &args[1..], writer).await
        }
        "change-password" => {
            users::change_password_cmd(pools, registry_url, &args[1..], writer).await
        }
        "change-operator-password" => {
            users::change_operator_password_cmd(pools, &args[1..], writer).await
        }
        "run-server" | "runserver" => {
            server::run_server_cmd(pools, registry_url, &args[1..], writer).await
        }
        "init-tenancy" => migrations::init_tenancy_cmd_with(dir, writer, init_fn),
        "wizard" | "init" => {
            // Interactive setup wizard (roadmap #2, v0.30.14).
            // Reads from stdin, writes to the same writer the
            // dispatcher uses. `init` is an alias the muscle
            // memory of `cargo init` users will reach for.
            //
            // `SharedStdin`, not `stdin.lock()`: this calls verbs that
            // prompt for themselves, and holding the lock across that
            // deadlocks (#1360).
            let mut reader = crate::manage_interactive::SharedStdin;
            wizard::wizard_cmd(pools, registry_url, dir, init_fn, &mut reader, writer).await
        }
        // The wizard above is a linear first-run setup; this is the standing
        // list of everything you can do afterwards (#1345).
        "menu" | "actions" => {
            // Off a terminal there is nobody to answer, and rendering the
            // menu to a log while exiting 0 looks like success (#1357).
            if !std::io::IsTerminal::is_terminal(&std::io::stdin()) {
                return Err(TenancyError::Validation(
                    "`menu` needs a terminal — run a verb directly, or `--help` for the list"
                        .into(),
                ));
            }
            let mut reader = crate::manage_interactive::SharedStdin;
            menu::menu_cmd(pools, registry_url, dir, init_fn, &mut reader, writer).await
        }
        // Intercepted before fall-through: tenancy ships its own
        // manage.rs template in `--with-manage-bin`, wiring
        // `crate::tenancy::manage::run` instead of the single-tenant
        // dispatcher. Plain models/views/urls files are identical
        // across both crates, so the heavy lifting still runs through
        // `rustango::migrate::scaffold::startapp`.
        "audit-cleanup" => audit::audit_cleanup_cmd(pools, &args[1..], writer).await,
        // The fall-through flush is scope-blind and ran on the registry pool (#2284).
        "flush" => flush::flush_cmd(pools, &args[1..], writer).await,
        // The fall-through read and wrote every model on the registry pool.
        "dumpdata" => data::data_cmd(pools, data::Verb::Dump, &args[1..], writer).await,
        "loaddata" => data::data_cmd(pools, data::Verb::Load, &args[1..], writer).await,
        // `public` holds the registry here; --clean would drop every org with it.
        "db:restore" if args[1..].iter().any(|a| a == "--clean") => Err(TenancyError::Validation(
            "db:restore --clean is refused in a tenancy project: schema `public` is the registry"
                .into(),
        )),
        "create-role" => roles::create_role_cmd(pools, &args[1..], writer).await,
        "list-roles" => roles::list_roles_cmd(pools, &args[1..], writer).await,
        "assign-role" => roles::assign_role_cmd(pools, &args[1..], writer).await,
        "revoke-role" => roles::revoke_role_cmd(pools, &args[1..], writer).await,
        "grant-perm" => roles::grant_perm_cmd(pools, &args[1..], writer).await,
        "revoke-perm" => roles::revoke_perm_cmd(pools, &args[1..], writer).await,
        "create-api-key" => roles::create_api_key_cmd(pools, &args[1..], writer).await,
        #[cfg(feature = "mcp")]
        "create-agent" => agents::create_agent_cmd(pools, registry_url, &args[1..], writer).await,
        #[cfg(feature = "mcp")]
        "rotate-agent-secret" => {
            agents::rotate_agent_secret_cmd(pools, registry_url, &args[1..], writer).await
        }
        #[cfg(feature = "mcp")]
        "list-agents" => agents::list_agents_cmd(pools, registry_url, &args[1..], writer).await,
        #[cfg(feature = "mcp")]
        "create-skill" => agents::create_skill_cmd(pools, registry_url, &args[1..], writer).await,
        #[cfg(feature = "mcp")]
        "grant-skill" => agents::grant_skill_cmd(pools, registry_url, &args[1..], writer).await,
        #[cfg(feature = "mcp")]
        "revoke-skill" => agents::revoke_skill_cmd(pools, registry_url, &args[1..], writer).await,
        #[cfg(feature = "mcp")]
        "list-skills" => agents::list_skills_cmd(pools, registry_url, &args[1..], writer).await,
        #[cfg(feature = "mcp")]
        "create-user-key" => {
            agents::create_user_key_cmd(pools, registry_url, &args[1..], writer).await
        }
        #[cfg(feature = "mcp")]
        "list-user-keys" => {
            agents::list_user_keys_cmd(pools, registry_url, &args[1..], writer).await
        }
        #[cfg(feature = "mcp")]
        "revoke-user-key" => {
            agents::revoke_user_key_cmd(pools, registry_url, &args[1..], writer).await
        }
        #[cfg(feature = "mcp")]
        "map-skill-permission" => {
            agents::map_skill_permission_cmd(pools, registry_url, &args[1..], writer).await
        }
        #[cfg(feature = "mcp")]
        "unmap-skill-permission" => {
            agents::unmap_skill_permission_cmd(pools, registry_url, &args[1..], writer).await
        }
        // The SSO providers live per tenant, which the registry pool can't see (#2359).
        // Tenant-scoped files are compared with each tenant's ledger.
        "check" => rustango::migrate::manage::check_cmd_with(
            &pools.registry_pool(),
            dir,
            &args[1..],
            writer,
            Some(rustango::migrate::manage::TenancyCheck {
                deploy: tenancy_deploy_findings(pools, facts),
                ledgers: migrations::active_tenant_ledgers(pools),
            }),
        )
        .await
        .map_err(TenancyError::Migrate),
        // Tenant-scoped migrations are recorded in the tenant ledgers (#2393).
        "forget-pending" => rustango::migrate::manage::forget_pending_cmd_with(
            &pools.registry_pool(),
            dir,
            &args[1..],
            writer,
            async {
                let [project] =
                    migrations::tenant_ledgers(pools, [rustango::migrate::LEDGER_TABLE]).await?;
                Ok(project)
            },
        )
        .await
        .map_err(TenancyError::Migrate),
        "showmigrations" | "status" => migrations::showmigrations_cmd(pools, dir, writer).await,
        // Tenant-scoped migrations live in the tenant ledgers, not the registry's.
        "downgrade" => migrations::downgrade_cmd(pools, dir, &args[1..], writer).await,
        "seed-permissions" => roles::seed_permissions_cmd(pools, &args[1..], writer).await,
        "startapp" => scaffold::startapp_cmd(&args[1..], writer),
        // Plain `migrate` is scope-aware here — registry-scoped
        // migrations apply to the registry pool first, then tenant-
        // scoped ones fan out across active orgs. Direct fall-through
        // to `rustango::migrate::manage` (which is scope-blind) would
        // apply tenant migrations to the registry pool, a real
        // footgun. `migrate-registry` / `migrate-tenants` stay
        // available for fine-grained control.
        "migrate" => {
            migrations::migrate_all_cmd(pools, registry_url, dir, &args[1..], writer).await
        }
        // Everything else (makemigrations, sqlmigrate,
        // …) is registry-scoped and delegates to the standard
        // single-tenant runner.
        // v0.38 — `manage::run_with_writer` now accepts `&crate::sql::Pool`
        // (instead of `&PgPool`), so we route through the tri-dialect
        // `registry_pool()` accessor that returns the backend-agnostic
        // enum form.
        _ => rustango::migrate::manage::run_with_writer(&pools.registry_pool(), dir, args, writer)
            .await
            .map_err(TenancyError::Migrate),
    }
}

/// Render the curated help text for `cargo run` (or
/// equivalent). Covers every tenancy verb with a brief description +
/// the most common flags, then the registry-scoped verbs that fall
/// through to `rustango::migrate::manage`.
///
/// Public so generated `manage.rs` binaries can short-circuit the
/// `help` / `--help` / `-h` / no-args case **before** connecting to
/// Postgres — otherwise `cargo run -- help` would error
/// with "missing DATABASE_URL" and the user couldn't see the help.
///
/// # Errors
/// Returns [`TenancyError::Io`] for a failed write — should not happen
/// against `std::io::stdout()`.
pub fn write_help<W: Write>(w: &mut W) -> Result<(), TenancyError> {
    writeln!(w, "rustango manage CLI — tenancy-aware dispatcher")?;
    writeln!(w)?;
    writeln!(w, "USAGE:")?;
    writeln!(w, "  cargo run -- <verb> [args]")?;
    writeln!(w)?;
    writeln!(w, "TENANT MANAGEMENT:")?;
    writeln!(
        w,
        "  create-tenant <slug> [--display-name <s>] [--mode schema|database]"
    )?;
    writeln!(
        w,
        "                       [--host-pattern <s>] [--database-url <s> | --server <name>] [--no-migrate]"
    )?;
    writeln!(
        w,
        "                       [--admin-email <e> [--admin-username <u>]]  first admin; prints a set-password link"
    )?;
    writeln!(
        w,
        "                       [--resume]  finish a tenant whose migrations failed (left inactive)"
    )?;
    writeln!(
        w,
        "  test-tenant-connection <url> [--no-write-probe] [--timeout <secs>]"
    )?;
    writeln!(
        w,
        "                       Provision a new tenant. Schema mode (default) gives the"
    )?;
    writeln!(
        w,
        "                       tenant its own Postgres schema; database mode points at"
    )?;
    writeln!(
        w,
        "                       a separate DB: an existing one via --database-url, or a new"
    )?;
    writeln!(
        w,
        "                       one with its own login on a saved server via --server."
    )?;
    writeln!(w, "  drop-tenant   <slug> [--confirm <slug>]")?;
    writeln!(
        w,
        "                       Soft-delete (active=false). Data preserved."
    )?;
    writeln!(
        w,
        "  purge-tenant  <slug> [--confirm <slug>] [--purge-database]"
    )?;
    writeln!(
        w,
        "                       HARD-delete: drops schema (or DB with --purge-database)."
    )?;
    writeln!(w, "  rotate-tenant-password <slug>")?;
    writeln!(
        w,
        "                       New password for a login made on a saved server."
    )?;
    writeln!(
        w,
        "  list-tenants         Print every Org row in the registry."
    )?;
    writeln!(
        w,
        "  edit-tenant <slug> [--display-name <s>] [--host-pattern <h>]"
    )?;
    writeln!(
        w,
        "                     [--path-prefix <p>] [--port <n>] [--database-url <u>]"
    )?;
    writeln!(
        w,
        "                     [--activate | --deactivate] [--clear <field>]"
    )?;
    writeln!(
        w,
        "  reseal-tenant-secrets [--apply]  Re-seal stored tenant URLs with the current key (dry run without --apply)."
    )?;
    writeln!(
        w,
        "                       Change routing and display config. Only the fields you"
    )?;
    writeln!(
        w,
        "                       name are touched; --clear empties one. Rotating the URL"
    )?;
    writeln!(w, "                       evicts the tenant's pool.")?;
    writeln!(w)?;
    writeln!(w, "INSPECTION (read-only):")?;
    writeln!(
        w,
        "  list-runs [--limit N] [--kind provision|migrate|purge|rotate_password] [--state <s>]"
    )?;
    writeln!(
        w,
        "                       Recent provisioning and migration runs, newest first."
    )?;
    writeln!(
        w,
        "  show-run <id>        One run's header and every step it recorded."
    )?;
    writeln!(
        w,
        "  audit-log [--limit N] [--table <t>] [--pk <v>] [--operation <o>] [--source <s>]"
    )?;
    writeln!(
        w,
        "                       The registry's audit trail — who changed what, and when."
    )?;
    writeln!(w)?;
    writeln!(w, "HOSTNAMES:")?;
    writeln!(
        w,
        "  list-hosts <slug>    Every hostname the tenant answers on, base first."
    )?;
    writeln!(w, "  add-host <slug> <hostname>")?;
    writeln!(
        w,
        "                       Bind an extra hostname. Rejected if another tenant"
    )?;
    writeln!(w, "                       already claims it.")?;
    writeln!(w, "  remove-host <slug> <hostname>")?;
    writeln!(
        w,
        "                       Unbind one. The base host cannot be removed here —"
    )?;
    writeln!(w, "                       change --host-pattern instead.")?;
    writeln!(w, "  set-host-enabled <slug> <hostname> --on|--off")?;
    writeln!(
        w,
        "                       Park a host without losing the record (DNS in flight,"
    )?;
    writeln!(w, "                       domain being retired).")?;
    writeln!(w)?;
    writeln!(w, "DATABASE SERVERS:")?;
    writeln!(
        w,
        "  add-db-server <name> --host <h> [--port <n>] --user <u> [--tls <mode>, default require]"
    )?;
    writeln!(
        w,
        "                [--maintenance-db <db>] [--sqlite-dir <dir>] [--password-env <VAR> | --no-password]"
    )?;
    writeln!(
        w,
        "                       Save a server's admin login; the password is asked hidden"
    )?;
    writeln!(
        w,
        "                       and stored sealed (needs RUSTANGO_SECRET_KEY)."
    )?;
    writeln!(w, "  list-db-servers      Saved servers, without secrets.")?;
    writeln!(
        w,
        "  test-db-server <name>  Log in and report the admin login's rights."
    )?;
    writeln!(
        w,
        "  edit-db-server <name> [same flags] [--prompt-password | --clear-password] [--on|--off]"
    )?;
    writeln!(
        w,
        "  remove-db-server <name>  Refused while a tenant's database is on it."
    )?;
    writeln!(w)?;
    writeln!(w, "USER / OPERATOR MANAGEMENT:")?;
    writeln!(
        w,
        "  create-operator <username> [--password <p> | --generate]"
    )?;
    writeln!(
        w,
        "                       Operator-level account; signs into the apex /login."
    )?;
    writeln!(
        w,
        "  list-operators       Every operator, with active state and creation date."
    )?;
    writeln!(w, "  set-operator-active <username> --on|--off")?;
    writeln!(
        w,
        "                       Turn an operator's access off or back on. Refuses to"
    )?;
    writeln!(
        w,
        "                       deactivate the last active one — that would lock"
    )?;
    writeln!(w, "                       everyone out of the console.")?;
    writeln!(w, "  reset-operator-totp <username>")?;
    writeln!(
        w,
        "                       Remove an operator's two-factor device (lost phone)."
    )?;
    writeln!(
        w,
        "  create-user <slug> <username> [--password <p> | --generate] [--superuser]"
    )?;
    writeln!(
        w,
        "                       Tenant-scoped user; signs into <slug>.<apex>{}.",
        crate::tenancy::RouteConfig::default().login_url
    )?;
    writeln!(w, "  create-superuser <slug> <username> [--password <p>]")?;
    writeln!(
        w,
        "                       Tenant-scoped superuser (alias for create-user --superuser)."
    )?;
    writeln!(w, "  set-superuser <slug> <username> [--on|--off]")?;
    writeln!(
        w,
        "                       Promote / demote an existing tenant user."
    )?;
    #[cfg(feature = "passkey")]
    writeln!(
        w,
        "  revoke-passkey <slug> <username> [--credential <id>]\n                       \
         Delete one passkey of a tenant user, or all of them."
    )?;
    writeln!(
        w,
        "  reset-password <slug> <username> [--password <p> | --generate]"
    )?;
    writeln!(
        w,
        "                       Reset a tenant user's password without their old one."
    )?;
    writeln!(w, "  set-password-link <slug> <username>")?;
    writeln!(
        w,
        "                       A single-use link for the user to set their own password."
    )?;
    writeln!(
        w,
        "  reset-operator-password <username> [--password <p> | --generate]"
    )?;
    writeln!(
        w,
        "                       Reset an operator's password without their old one."
    )?;
    writeln!(
        w,
        "  change-password <slug> <username> [--current <p> | --current-stdin] [--password <p> | --generate]"
    )?;
    writeln!(
        w,
        "                       Rotate a tenant user's password; verifies current first."
    )?;
    writeln!(
        w,
        "  change-operator-password <username> [--current <p> | --current-stdin] [--password <p> | --generate]"
    )?;
    writeln!(
        w,
        "                       Rotate an operator's password; verifies current first."
    )?;
    writeln!(w)?;
    writeln!(w, "QUICK START:")?;
    writeln!(
        w,
        "  wizard | init        Interactive setup — walks you from a fresh project to"
    )?;
    writeln!(
        w,
        "                       a working tenant + operator + tenant superuser through"
    )?;
    writeln!(
        w,
        "                       prompts. Each step is opt-in (press n to skip)."
    )?;
    writeln!(
        w,
        "  menu | actions       Numbered list of the common verbs. Asks only for what"
    )?;
    writeln!(
        w,
        "                       the verb won't ask itself, echoes the equivalent"
    )?;
    writeln!(
        w,
        "                       command line, then runs it and comes back."
    )?;
    writeln!(w)?;
    writeln!(w, "MIGRATIONS:")?;
    writeln!(
        w,
        "  init-tenancy         No-op, kept so old scripts don't break. Framework tables\n\
         \x20                      are generated from the models and applied by `migrate`."
    )?;
    writeln!(
        w,
        "  makemigrations       Diff models against latest snapshot, emit a new JSON file."
    )?;
    writeln!(
        w,
        "  migrate              Apply registry-scoped, then tenant-scoped, migrations."
    )?;
    writeln!(
        w,
        "  migrate --fake <name>  Insert <name> into registry ledger WITHOUT running its SQL"
    )?;
    writeln!(
        w,
        "                         (recovery: \"relation X already exists\" 42P07 errors)."
    )?;
    writeln!(
        w,
        "  migrate-registry     Apply registry-scoped migrations only."
    )?;
    writeln!(
        w,
        "  migrate-tenants      Apply tenant-scoped migrations to every active org."
    )?;
    writeln!(
        w,
        "  prewarm-pools        Eagerly build pools for every active database-mode tenant"
    )?;
    writeln!(
        w,
        "                       (drops first-request latency on the hot path)."
    )?;
    writeln!(
        w,
        "  migrate-tenant-storage <slug> --to schema|database [--database-url <s>] [--schema-name <s>] [--allow-extension <name>]... [--drain-secs <n>] [--dry-run]"
    )?;
    writeln!(
        w,
        "                       Move a tenant between storage modes via pg_dump → psql."
    )?;
    writeln!(
        w,
        "  showmigrations       List which migrations are applied / pending."
    )?;
    writeln!(
        w,
        "  downgrade [N | <target>] [--tenant <slug> | --all-tenants [--yes]]"
    )?;
    writeln!(
        w,
        "                       Roll back the last N migrations (default 1), or those after"
    )?;
    writeln!(
        w,
        "                       <target>: registry-scoped, or tenant-scoped in one tenant /"
    )?;
    writeln!(
        w,
        "                       every active tenant. --all-tenants prints the plan; --yes runs it."
    )?;
    writeln!(w)?;
    writeln!(w, "ROLES & PERMISSIONS:")?;
    writeln!(w, "  create-role <slug> <name> [--description <s>]")?;
    writeln!(w, "                       Create a named role on a tenant.")?;
    writeln!(
        w,
        "  list-roles  <slug>   List roles and permission counts."
    )?;
    writeln!(w, "  assign-role <slug> <username> <role>")?;
    writeln!(w, "                       Add a user to a role.")?;
    writeln!(w, "  revoke-role <slug> <username> <role>")?;
    writeln!(w, "                       Remove a user from a role.")?;
    writeln!(w, "  grant-perm  <slug> <name> <codename> [--role]")?;
    writeln!(
        w,
        "                       Grant a codename to a user (default) or role (--role)."
    )?;
    writeln!(w, "  revoke-perm <slug> <name> <codename> [--role]")?;
    writeln!(
        w,
        "                       Revoke a codename from a user or role."
    )?;
    writeln!(
        w,
        "  create-api-key <slug> <username> [--label <s>] [--expires-days <N>]"
    )?;
    writeln!(
        w,
        "                       Issue a Bearer API key for a tenant user."
    )?;
    // MCP agent/skill verbs only exist when the `mcp` feature is compiled in.
    #[cfg(feature = "mcp")]
    {
        writeln!(w, "  create-agent <slug> <name>")?;
        writeln!(
            w,
            "                       Provision an MCP agent (prints its secret once)."
        )?;
        writeln!(w, "  rotate-agent-secret <slug> <name>")?;
        writeln!(
            w,
            "                       Issue a fresh secret for an MCP agent."
        )?;
        writeln!(w, "  list-agents <slug>   List a tenant's MCP agents.")?;
        writeln!(
            w,
            "  create-skill <slug> <codename> [--name ..] [--tools a,b] [--instructions ..]"
        )?;
        writeln!(
            w,
            "                       Define an MCP skill (a bundle of tools)."
        )?;
        writeln!(w, "  grant-skill <slug> <agent> <skill>")?;
        writeln!(w, "                       Grant a skill to an agent.")?;
        writeln!(w, "  revoke-skill <slug> <agent> <skill>")?;
        writeln!(w, "                       Revoke a skill from an agent.")?;
        writeln!(w, "  list-skills <slug>   List a tenant's MCP skills.")?;
        // Flags, not a positional `[label]` — the parser rejects a third
        // positional with "unexpected argument" (#1407).
        writeln!(
            w,
            "  create-user-key <slug> <username> [--label <l>] [--skill <codename>]…"
        )?;
        writeln!(
            w,
            "                       Issue a personal, user-owned MCP key (prints its token once)."
        )?;
        writeln!(w, "  list-user-keys <slug> <username>")?;
        writeln!(w, "                       List a user's personal MCP keys.")?;
        writeln!(w, "  revoke-user-key <slug> <username> <key_id>")?;
        writeln!(
            w,
            "                       Revoke one of a user's personal keys by id."
        )?;
        writeln!(w, "  map-skill-permission <slug> <skill> <permission>")?;
        writeln!(
            w,
            "                       Grant a skill to any user holding <permission> (user keys)."
        )?;
        writeln!(w, "  unmap-skill-permission <slug> <skill> <permission>")?;
        writeln!(
            w,
            "                       Remove a skill↔permission mapping."
        )?;
    }
    writeln!(w, "  seed-permissions [--slug <s>]")?;
    writeln!(
        w,
        "                       Re-seed `rustango_permissions` for one (--slug)"
    )?;
    writeln!(
        w,
        "                       or every active tenant. Idempotent — safe to"
    )?;
    writeln!(
        w,
        "                       run after adding `#[rustango(permissions)]` to"
    )?;
    writeln!(
        w,
        "                       a model without a fresh migrate cycle."
    )?;
    writeln!(w)?;
    writeln!(w, "AUDIT:")?;
    writeln!(
        w,
        "  audit-cleanup --days <N>     Delete entries older than N days (registry + all active tenants)."
    )?;
    writeln!(
        w,
        "  audit-cleanup --keep-last <N> Keep N most recent entries per row."
    )?;
    writeln!(
        w,
        "                [--tenant <s>]  Scope to one tenant instead of all."
    )?;
    writeln!(w)?;
    writeln!(w, "DATA:")?;
    writeln!(
        w,
        "  flush --tenant <s> [--yes]   Wipe one tenant's tables; the registry is never flushed."
    )?;
    writeln!(
        w,
        "  dumpdata | loaddata [--tenant <s>]  One tenant's models, or the registry's without it."
    )?;
    writeln!(w)?;
    writeln!(w, "SERVER:")?;
    writeln!(w, "  run-server [--bind <addr>]")?;
    writeln!(
        w,
        "                       Boot the HTTP server with admin + operator console."
    )?;
    writeln!(w)?;
    writeln!(w, "SCAFFOLDING:")?;
    writeln!(
        w,
        "  startapp <name> [--into <dir>] [--with-manage-bin] [--with-bootstrap-migration]"
    )?;
    writeln!(w, "                       Scaffold an app module.")?;
    writeln!(w)?;
    writeln!(w, "EXAMPLES:")?;
    writeln!(w, "  cargo run -- migrate")?;
    writeln!(
        w,
        "  cargo run -- create-operator admin   # prompts twice; RUSTANGO_PASSWORD off a TTY"
    )?;
    writeln!(
        w,
        "  cargo run -- create-tenant acme --display-name 'ACME Corp'"
    )?;
    writeln!(
        w,
        "  cargo run -- create-user acme alice --password-stdin --superuser"
    )?;
    writeln!(w, "  cargo run -- list-tenants")?;
    writeln!(w, "  cargo run -- audit-cleanup --days 90")?;
    writeln!(
        w,
        "  cargo run -- audit-cleanup --keep-last 50 --tenant acme"
    )?;
    writeln!(w)?;
    writeln!(
        w,
        "Run any verb with --help for verb-specific flags + details."
    )?;
    Ok(())
}

/// `check --deploy` findings only a tenancy deploy has.
async fn tenancy_deploy_findings<DB: sqlx::Database>(
    pools: &TenantPools<DB>,
    facts: CliFacts,
) -> rustango::migrate::manage::DeployAuditFindings
where
    crate::sql::Pool: From<sqlx::Pool<DB>>,
{
    #[cfg(feature = "sso")]
    let mut out = sso_check::findings(pools).await;
    #[cfg(not(feature = "sso"))]
    let mut out = {
        let _ = pools;
        rustango::migrate::manage::DeployAuditFindings::default()
    };
    tenant_scheme_audit(
        crate::tenancy::server::tenant_scheme_setting().as_deref(),
        &mut out,
    );
    if facts.provisioning {
        secret_key_audit(crate::aead::key_status(), &mut out);
    }
    role_schema_audit(&pools.registry_pool(), &mut out).await;
    out
}

/// A tenant schema named like a role leads that role's default
/// `search_path`; new ones are refused, existing ones are only named.
async fn role_schema_audit(
    registry: &crate::sql::Pool,
    out: &mut rustango::migrate::manage::DeployAuditFindings,
) {
    #[cfg(feature = "postgres")]
    #[allow(irrefutable_let_patterns)]
    if let crate::sql::Pool::Postgres(pg) = registry {
        use crate::core::Column as _;
        use crate::sql::FetcherPool as _;
        let orgs: Vec<crate::tenancy::Org> = match crate::tenancy::Org::objects()
            .where_(
                crate::tenancy::Org::storage_mode
                    .eq(crate::tenancy::StorageMode::Schema.as_str().to_owned()),
            )
            .fetch(registry)
            .await
        {
            Ok(orgs) => orgs,
            Err(e) => {
                out.warnings
                    .push(format!("could not list schema-mode tenants: {e}"));
                return;
            }
        };
        for org in orgs {
            let schema = org.effective_schema();
            if crate::tenancy::provision::is_role_name(pg, schema)
                .await
                .unwrap_or(false)
            {
                out.warnings.push(format!(
                    "tenant `{}` lives in schema `{schema}`, the name of a database role: that \
                     role's sessions see this tenant's tables before `public`; move it to another \
                     schema (a database move and back) or rename the role",
                    org.slug
                ));
            }
        }
    }
    #[cfg(not(feature = "postgres"))]
    let _ = (registry, out);
}

/// Provisioning seals server passwords and tenant URLs with this key.
fn secret_key_audit(
    status: crate::aead::KeyStatus,
    out: &mut rustango::migrate::manage::DeployAuditFindings,
) {
    use crate::aead::KeyStatus;
    match status {
        KeyStatus::Missing => out.warnings.push(
            "RUSTANGO_SECRET_KEY is unset — tenant provisioning is mounted but cannot save \
             server passwords, and new tenant URLs are stored unsealed; set 32+ random bytes \
             (`openssl rand -base64 48`) and back it up"
                .into(),
        ),
        KeyStatus::Short => out.warnings.push(
            "RUSTANGO_SECRET_KEY is shorter than 32 bytes — sealed secrets use a weak key".into(),
        ),
        KeyStatus::DevFile => out.warnings.push(
            "RUSTANGO_SECRET_KEY is unset — sealed secrets use the dev key file \
             `var/.rustango_secret.key`, which a redeploy loses; set the env var \
             (`openssl rand -base64 48`) and back it up"
                .into(),
        ),
        KeyStatus::Ok => out
            .info
            .push("RUSTANGO_SECRET_KEY is set for sealed secrets".into()),
    }
}

/// The impersonation handoff carries a one-time superuser login (#2425).
fn tenant_scheme_audit(
    setting: Option<&str>,
    out: &mut rustango::migrate::manage::DeployAuditFindings,
) {
    match setting {
        Some("https") => {}
        Some(other) => out.warnings.push(format!(
            "RUSTANGO_TENANT_SCHEME is `{other}` — impersonation handoff tokens go out in \
             clear; set it to `https`"
        )),
        None => out.warnings.push(
            "RUSTANGO_TENANT_SCHEME is unset — impersonation links use https only while \
             cookies are Secure; set it to `https`"
                .into(),
        ),
    }
}

#[cfg(test)]
mod deploy_tests {
    use super::*;

    /// A missing or short secret key is flagged when provisioning is mounted.
    #[test]
    fn a_missing_or_short_secret_key_is_flagged() {
        use crate::aead::KeyStatus;
        for (status, flagged) in [
            (KeyStatus::Missing, true),
            (KeyStatus::Short, true),
            (KeyStatus::DevFile, true),
            (KeyStatus::Ok, false),
        ] {
            let mut out = rustango::migrate::manage::DeployAuditFindings::default();
            secret_key_audit(status, &mut out);
            assert_eq!(
                out.warnings
                    .iter()
                    .any(|w| w.contains("RUSTANGO_SECRET_KEY")),
                flagged,
                "{status:?}"
            );
        }
    }

    /// #2425 — an unset or non-https tenant scheme is flagged; https is not.
    #[test]
    fn a_tenant_scheme_that_is_not_https_is_flagged() {
        for (setting, flagged) in [(None, true), (Some("http"), true), (Some("https"), false)] {
            let mut out = rustango::migrate::manage::DeployAuditFindings::default();
            tenant_scheme_audit(setting, &mut out);
            assert_eq!(
                out.warnings
                    .iter()
                    .any(|w| w.contains("RUSTANGO_TENANT_SCHEME")),
                flagged,
                "{setting:?}"
            );
        }
    }
}