rustango 0.38.0

//! Django-style `manage.py` analog for rustango projects.
//!
//! [`run`] takes `argv` and dispatches to the right migration
//! function. Users drop a tiny `src/bin/manage.rs` binary into their
//! own project that imports their `#[derive(Model)]` structs (so
//! `inventory` registers them) and forwards argv to this runner:
//!
//! ```ignore
//! use rustango::sql::sqlx::PgPool;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Bring user models into this binary so inventory sees them.
//!     use my_app::models::*;
//!
//!     let pool = PgPool::connect(&std::env::var("DATABASE_URL")?).await?;
//!     let dir: &std::path::Path = "./migrations".as_ref();
//!     rustango::manage::run(&pool, dir, std::env::args().skip(1)).await?;
//!     Ok(())
//! }
//! ```
//!
//! UX: `cargo run -- migrate`,
//! `cargo run -- makemigrations [name]`, etc. The
//! framework owns the dispatcher; the user owns the entrypoint
//! (which must compile in their models). Same factoring as Django's
//! `manage.py` adapted for Rust's link-by-binary model.
//!
//! ## Subcommands
//!
//! | command | what it does |
//! |---------|--------------|
//! | `makemigrations [name]` | Diff registry vs latest snapshot; write next file. |
//! | `makemigrations --empty <name>` | Write an empty scaffold for hand-authored data migrations. |
//! | `migrate` | Apply every pending migration. |
//! | `migrate <target>` | Forward-or-back to `<target>`. `zero` wipes everything. |
//! | `downgrade [N]` | Step back N applied migrations (default 1). |
//! | `showmigrations` / `status` | List migrations with `[X]`/`[ ]` applied marker. |
//! | `--help` / `-h` / `help` | Print usage. |

use std::io::Write;
use std::path::Path;

use crate::core::inventory;
use crate::sql::Pool;

use super::error::MigrateError;
use super::file::{self, DataOp, Migration, Operation};
use super::make::{make_migrations, make_migrations_for_app};
use super::runner;
use super::snapshot::SchemaSnapshot;

/// Parse argv (no binary name) and dispatch to the right subcommand.
/// All output is written to stdout. Use [`run_with_writer`] when you
/// need to capture the output (tests, structured logging, custom UIs).
///
/// `dir` is the migrations directory (e.g. `./migrations`).
///
/// # Errors
/// Returns whatever the underlying migration function returns, plus
/// [`MigrateError::Validation`] for unknown subcommands or bad argv,
/// or [`MigrateError::Io`] if writing to stdout fails (broken pipe).
pub async fn run(
    pool: &Pool,
    dir: &Path,
    args: impl IntoIterator<Item = String>,
) -> Result<(), MigrateError> {
    let mut stdout = std::io::stdout();
    run_with_writer(pool, dir, args, &mut stdout).await
}

/// Same as [`run`] but writes user-facing output to `writer`. Useful
/// for tests (`Vec<u8>`), captured logs, or piping the dispatcher's
/// output through a custom formatter.
///
/// # Errors
/// As [`run`] — including [`MigrateError::Io`] from any failed
/// `writer.write` (the writer's surface).
pub async fn run_with_writer<W: Write + Send>(
    pool: &Pool,
    dir: &Path,
    args: impl IntoIterator<Item = String>,
    writer: &mut W,
) -> Result<(), MigrateError> {
    let args: Vec<String> = args.into_iter().collect();
    let cmd = args.first().map_or("", String::as_str);

    match cmd {
        "" | "--help" | "-h" | "help" => {
            print_help(writer)?;
            Ok(())
        }
        "makemigrations" => makemigrations(dir, &args[1..], writer),
        "migrate" => migrate(pool, dir, &args[1..], writer).await,
        "downgrade" => downgrade(pool, dir, &args[1..], writer).await,
        "showmigrations" | "status" => showmigrations(pool, dir, writer).await,
        "forget-pending" => forget_pending_cmd(pool, dir, &args[1..], writer).await,
        "startapp" => startapp(&args[1..], writer),
        "add-data-op" => add_data_op_cmd(dir, &args[1..], writer),
        "make:viewset" => make_viewset_cmd(&args[1..], writer),
        "make:api_routes" => make_api_routes_cmd(&args[1..], writer),
        "make:serializer" => make_serializer_cmd(&args[1..], writer),
        "make:form" => make_form_cmd(&args[1..], writer),
        "make:job" => make_job_cmd(&args[1..], writer),
        "make:notification" => make_notification_cmd(&args[1..], writer),
        "make:middleware" => make_middleware_cmd(&args[1..], writer),
        "make:test" => make_test_cmd(&args[1..], writer),
        "about" => about_cmd(pool, writer).await,
        "check" => check_cmd(pool, dir, &args[1..], writer).await,
        "docs" => docs_cmd(writer),
        "version" | "--version" => version_cmd(writer),
        "db:dump" => db_dump_cmd(&args[1..], writer),
        "db:restore" => db_restore_cmd(&args[1..], writer),
        "db:info" => db_info_cmd(writer),
        // v0.38 — `inspectdb` is tri-dialect: PG + MySQL via
        // `information_schema`, SQLite via `PRAGMA table_info` +
        // `sqlite_master`. Dispatch happens inside `inspectdb_cmd`.
        "inspectdb" => super::inspectdb::inspectdb_cmd(pool, &args[1..], writer).await,
        other => Err(MigrateError::Validation(format!(
            "unknown subcommand: `{other}` (run with --help for usage)"
        ))),
    }
}

fn print_help<W: Write>(w: &mut W) -> std::io::Result<()> {
    writeln!(w, "rustango::manage — Django-style migration runner\n")?;
    writeln!(w, "USAGE:")?;
    writeln!(w, "  manage <COMMAND> [args]\n")?;
    writeln!(w, "COMMANDS:")?;
    writeln!(w, "  makemigrations [name]")?;
    writeln!(
        w,
        "      Diff the inventory registry against the latest snapshot"
    )?;
    writeln!(
        w,
        "      and write the next migration file. `name` overrides the"
    )?;
    writeln!(w, "      auto-derived suffix.\n")?;
    writeln!(w, "  makemigrations --empty <name>")?;
    writeln!(
        w,
        "      Write an empty migration scaffold (`forward: []`) for"
    )?;
    writeln!(
        w,
        "      hand-authored data migrations. Edit the JSON to add"
    )?;
    writeln!(w, "      `data` ops with sql + reverse_sql.\n")?;
    writeln!(w, "  migrate")?;
    writeln!(w, "      Apply every pending migration in lex order.\n")?;
    writeln!(w, "  migrate <target>")?;
    writeln!(
        w,
        "      Forward or back to <target>. `zero` unapplies every"
    )?;
    writeln!(w, "      applied migration.\n")?;
    writeln!(w, "  migrate --dry-run")?;
    writeln!(
        w,
        "      Print the SQL each pending migration would run; never"
    )?;
    writeln!(
        w,
        "      writes. Reads the ledger so the preview is accurate.\n"
    )?;
    writeln!(w, "  migrate --squash")?;
    writeln!(
        w,
        "      Delete every pending (un-applied) migration JSON and"
    )?;
    writeln!(
        w,
        "      regenerate a single fresh diff via makemigrations. Dev-"
    )?;
    writeln!(
        w,
        "      iteration escape hatch when an evolving model produces a"
    )?;
    writeln!(
        w,
        "      pending migration the validator rejects (e.g. AddColumn"
    )?;
    writeln!(
        w,
        "      NOT NULL with no default). Refuses to touch applied rows.\n"
    )?;
    writeln!(w, "  downgrade [N]")?;
    writeln!(w, "      Step back N applied migrations (default 1).\n")?;
    writeln!(w, "  showmigrations | status")?;
    writeln!(w, "      List migrations with [X]/[ ] applied marker.\n")?;
    writeln!(w, "  forget-pending <name>")?;
    writeln!(
        w,
        "      Delete a migration JSON that has NOT been applied yet,"
    )?;
    writeln!(
        w,
        "      so the next `makemigrations` regenerates the diff."
    )?;
    writeln!(
        w,
        "      Refuses if the migration is recorded in the ledger.\n"
    )?;
    writeln!(
        w,
        "  add-data-op --sql <SQL> [--reverse-sql <SQL>] [--name <name>] [--to <migration>]"
    )?;
    writeln!(
        w,
        "      Add a data transformation op (up + optional down)."
    )?;
    writeln!(w, "      --sql        Forward SQL to run (required).")?;
    writeln!(
        w,
        "      --reverse-sql  Rollback SQL. Omit for irreversible ops."
    )?;
    writeln!(
        w,
        "      --name       Name suffix for the new migration file."
    )?;
    writeln!(
        w,
        "      --to         Append to an existing migration instead of creating one.\n"
    )?;
    writeln!(w, "  about")?;
    writeln!(w, "      Print framework version, registered models/apps,")?;
    writeln!(w, "      and detected backend configuration.\n")?;
    writeln!(w, "  check [--deploy]")?;
    writeln!(
        w,
        "      Run system audits — pending migrations, missing models, common"
    )?;
    writeln!(
        w,
        "      misconfigurations. With --deploy: production hardening checks."
    )?;
    writeln!(w, "      Exits non-zero on any error-level finding.\n")?;
    writeln!(w, "  docs")?;
    writeln!(w, "      Open docs.rs/rustango in the default browser.\n")?;
    writeln!(w, "  version | --version")?;
    writeln!(w, "      Print the rustango framework version.\n")?;
    writeln!(
        w,
        "  (To bootstrap a new project from scratch, install + run"
    )?;
    writeln!(
        w,
        "  `cargo install cargo-rustango` then `cargo rustango new <name>`.)\n"
    )?;
    writeln!(
        w,
        "  make:viewset <Name> [--model <Model>] [--tenant | --no-tenant]"
    )?;
    writeln!(
        w,
        "    --tenant emits a `ViewSet::for_model(...).tenant_router(...)`"
    )?;
    writeln!(
        w,
        "    shape that resolves a per-request connection via `Tenant`"
    )?;
    writeln!(
        w,
        "    instead of baking a pool at mount time (required for tenancy)."
    )?;
    writeln!(
        w,
        "    Auto-detected from Cargo.toml when the rustango dep enables"
    )?;
    writeln!(
        w,
        "    `tenancy` — pass `--no-tenant` to override the auto-detection."
    )?;
    writeln!(w, "  make:api_routes <app> [--tenant]")?;
    writeln!(
        w,
        "    Scaffold src/<app>/api_routes.rs — the per-app composer that"
    )?;
    writeln!(
        w,
        "    merges every viewset's router into a single Router<()>."
    )?;
    writeln!(w, "  make:serializer <Name> [--model <Model>]")?;
    writeln!(w, "  make:form <Name>")?;
    writeln!(w, "  make:job <Name>")?;
    writeln!(w, "  make:notification <Name>")?;
    writeln!(w, "  make:middleware <Name>")?;
    writeln!(w, "  make:test <Name>")?;
    writeln!(
        w,
        "      Scaffold a single source file with the chosen shape."
    )?;
    writeln!(
        w,
        "      Writes to src/<snake_name>.rs (skips if exists).\n"
    )?;
    writeln!(
        w,
        "  db:dump [--out <file>] [--data-only|--schema-only] [--no-owner]"
    )?;
    writeln!(
        w,
        "      Run pg_dump against $DATABASE_URL. Default: prints SQL to"
    )?;
    writeln!(
        w,
        "      stdout (omit --out to pipe). --data-only / --schema-only"
    )?;
    writeln!(
        w,
        "      mirror pg_dump's flags. --no-owner skips OWNER lines.\n"
    )?;
    writeln!(w, "  db:restore <file> [--clean]")?;
    writeln!(
        w,
        "      Run psql against $DATABASE_URL with `\\i <file>`. With"
    )?;
    writeln!(
        w,
        "      --clean, prepend a `DROP SCHEMA public CASCADE; CREATE SCHEMA public;`"
    )?;
    writeln!(w, "      so the restore lands on a clean database.\n")?;
    writeln!(w, "  db:info")?;
    writeln!(
        w,
        "      Print the resolved DB URL (password redacted), detected"
    )?;
    writeln!(
        w,
        "      backend, and which `postgres`/`mysql` Cargo features are"
    )?;
    writeln!(w, "      compiled in. Read-only — does not connect.\n")?;
    writeln!(w, "  inspectdb [--schema <name>] [--table <name>]")?;
    writeln!(
        w,
        "      Connect to DATABASE_URL and emit `#[derive(Model)]`"
    )?;
    writeln!(
        w,
        "      source for every base table in `--schema` (default `public`)."
    )?;
    writeln!(
        w,
        "      Pipe to a file the user reviews + edits. Mirrors Django's"
    )?;
    writeln!(
        w,
        "      `inspectdb` shape — adopts rustango against an existing DB"
    )?;
    writeln!(w, "      without rewriting it.\n")?;
    writeln!(w, "  startapp <name> [--with-manage-bin]")?;
    writeln!(
        w,
        "      Scaffold a Django-shape app module under src/<name>/"
    )?;
    writeln!(
        w,
        "      (models.rs + views.rs + urls.rs + mod.rs). Idempotent;"
    )?;
    writeln!(
        w,
        "      existing files are left untouched. With --with-manage-bin,"
    )?;
    writeln!(w, "      also writes src/bin/manage.rs.")?;
    Ok(())
}

fn makemigrations<W: Write>(dir: &Path, args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let mut empty = false;
    let mut name: Option<String> = None;
    let mut app: Option<String> = None;
    let mut scope_override: Option<crate::core::ModelScope> = None;
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--empty" => empty = true,
            "--app" => {
                app = Some(iter.next().cloned().ok_or_else(|| {
                    MigrateError::Validation("--app requires an app name".into())
                })?);
            }
            "--scope" => {
                let raw = iter.next().cloned().ok_or_else(|| {
                    MigrateError::Validation("--scope requires \"registry\" or \"tenant\"".into())
                })?;
                scope_override =
                    Some(crate::core::ModelScope::from_str(&raw).ok_or_else(|| {
                        MigrateError::Validation(format!(
                            "--scope must be \"registry\" or \"tenant\", got {raw:?}"
                        ))
                    })?);
            }
            "--help" | "-h" => {
                writeln!(
                    w,
                    "makemigrations [name]                  diff registry, write next file in <dir>\n\
                     makemigrations --app <app> [name]      diff one app, write to <project_root>/<app>/migrations/\n\
                     makemigrations --scope <s> [name]      <s> = registry|tenant; one file with that MigrationScope\n\
                     makemigrations --empty <name>          empty scaffold for data ops\n\
                     \n\
                     In tenancy projects (any registered model with scope = \"registry\"),\n\
                     a flagless makemigrations splits the diff into TWO files — one for\n\
                     registry-scoped models, one for tenant-scoped — so framework tables\n\
                     don't bleed across scopes when migrate-tenants fans out."
                )?;
                return Ok(());
            }
            other if other.starts_with('-') => {
                return Err(MigrateError::Validation(format!("unknown flag: {other}")));
            }
            other => {
                if name.is_some() {
                    return Err(MigrateError::Validation(format!(
                        "unexpected positional argument: {other}"
                    )));
                }
                name = Some(other.to_owned());
            }
        }
    }

    if empty {
        let Some(n) = name else {
            return Err(MigrateError::Validation(
                "makemigrations --empty requires a name".into(),
            ));
        };
        let mig = make_empty(dir, &n)?;
        writeln!(
            w,
            "wrote {} (empty scaffold — fill in `forward` with data ops)",
            file_path(dir, &mig.name).display()
        )?;
        return Ok(());
    }

    // Per-app makemigrations (slice 9.0g): filter inventory to models
    // whose `resolved_app_label()` matches `<app>` and write the
    // result under `<project_root>/<app>/migrations/`. The `dir`
    // argument's parent is the project root so existing manage CLI
    // wiring (which passes the flat `migrations/` dir) keeps working.
    if let Some(app_name) = app {
        let project_root = dir.parent().unwrap_or(dir);
        match make_migrations_for_app(project_root, &app_name, name.as_deref())? {
            Some(mig) => {
                let app_dir = project_root.join(&app_name).join("migrations");
                writeln!(w, "wrote {}", file_path(&app_dir, &mig.name).display())?;
                for op in &mig.forward {
                    writeln!(w, "    + {}", describe_op(op))?;
                }
            }
            None => writeln!(
                w,
                "app `{app_name}`: no changes — models match latest snapshot (or no models with this app_label)"
            )?,
        }
        return Ok(());
    }

    // Explicit scope flag — emit exactly one file in that scope.
    if let Some(scope) = scope_override {
        return write_scoped_migration(dir, scope, name.as_deref(), w);
    }

    // Auto-detect: if any registered model is `scope = "registry"`,
    // we're in a tenancy project. Run BOTH scopes so framework
    // registry tables get their own file and user's tenant models
    // get theirs. Each scope is a no-op when nothing in that scope
    // changed; the user sees one or two "wrote ..." lines.
    let has_registry_scoped = inventory::iter::<crate::core::ModelEntry>
        .into_iter()
        .any(|e| e.schema.scope == crate::core::ModelScope::Registry);
    if has_registry_scoped {
        let mut wrote_any = false;
        for scope in [
            crate::core::ModelScope::Registry,
            crate::core::ModelScope::Tenant,
        ] {
            let mig = crate::migrate::make::make_migrations_for_scope(dir, scope, name.as_deref())?;
            match mig {
                Some(m) => {
                    writeln!(
                        w,
                        "wrote {} ({} scope)",
                        file_path(dir, &m.name).display(),
                        scope.as_str(),
                    )?;
                    for op in &m.forward {
                        writeln!(w, "    + {}", describe_op(op))?;
                    }
                    wrote_any = true;
                }
                None => writeln!(w, "no changes for {} scope", scope.as_str(),)?,
            }
        }
        if !wrote_any {
            // Fall through silently — both scope-clean messages already printed.
        }
        return Ok(());
    }

    // Single-tenant (no registry-scoped models): one migration covering
    // every registered model — the v0.24.x behavior.
    match make_migrations(dir, name.as_deref())? {
        Some(mig) => {
            writeln!(w, "wrote {}", file_path(dir, &mig.name).display())?;
            for op in &mig.forward {
                writeln!(w, "    + {}", describe_op(op))?;
            }
        }
        None => writeln!(w, "no changes — registry matches latest snapshot")?,
    }
    Ok(())
}

fn write_scoped_migration<W: Write>(
    dir: &Path,
    scope: crate::core::ModelScope,
    name: Option<&str>,
    w: &mut W,
) -> Result<(), MigrateError> {
    match crate::migrate::make::make_migrations_for_scope(dir, scope, name)? {
        Some(mig) => {
            writeln!(
                w,
                "wrote {} ({} scope)",
                file_path(dir, &mig.name).display(),
                scope.as_str(),
            )?;
            for op in &mig.forward {
                writeln!(w, "    + {}", describe_op(op))?;
            }
        }
        None => writeln!(
            w,
            "no changes — {} models match latest snapshot",
            scope.as_str(),
        )?,
    }
    Ok(())
}

async fn migrate<W: Write>(
    pool: &Pool,
    dir: &Path,
    args: &[String],
    w: &mut W,
) -> Result<(), MigrateError> {
    let mut dry_run = false;
    let mut squash = false;
    let mut positional: Option<&str> = None;
    for arg in args {
        match arg.as_str() {
            "--dry-run" => dry_run = true,
            "--squash" => squash = true,
            "--help" | "-h" => {
                writeln!(
                    w,
                    "migrate                    apply pending migrations\n\
                     migrate <target>           forward or back to <target> (`zero` wipes)\n\
                     migrate --dry-run          preview the SQL without writing\n\
                     migrate --squash           delete every pending (un-applied) migration JSON\n\
                                                and regenerate a single fresh diff. Dev-iteration\n\
                                                escape hatch — refuses to touch applied rows."
                )?;
                return Ok(());
            }
            other if other.starts_with('-') => {
                return Err(MigrateError::Validation(format!("unknown flag: {other}")));
            }
            other => {
                if positional.is_some() {
                    return Err(MigrateError::Validation(format!(
                        "unexpected positional argument: {other}"
                    )));
                }
                positional = Some(other);
            }
        }
    }

    if squash {
        if dry_run || positional.is_some() {
            return Err(MigrateError::Validation(
                "`migrate --squash` does not combine with `--dry-run` or a positional target"
                    .into(),
            ));
        }
        return migrate_squash(pool, dir, w).await;
    }

    if dry_run {
        if positional.is_some() {
            return Err(MigrateError::Validation(
                "`migrate <target> --dry-run` is not supported in v0.4 — use plain `--dry-run` to preview pending forward migrations".into(),
            ));
        }
        let preview = runner::migrate_dry_run_pool(pool, dir).await?;
        if preview.is_empty() {
            writeln!(w, "nothing to migrate (already up to date)")?;
        } else {
            writeln!(
                w,
                "-- DRY RUN: {} pending migration(s); no SQL will be executed",
                preview.len()
            )?;
            for p in &preview {
                writeln!(w)?;
                writeln!(
                    w,
                    "-- {} ({})",
                    p.name,
                    if p.atomic { "atomic" } else { "non-atomic" }
                )?;
                for stmt in &p.statements {
                    writeln!(w, "{stmt};")?;
                }
            }
        }
        return Ok(());
    }

    if let Some(target) = positional {
        let touched = runner::migrate_to_pool(pool, dir, target).await?;
        if touched.is_empty() {
            writeln!(w, "already at {target}")?;
        } else {
            for m in &touched {
                writeln!(w, "  touched {}", m.name)?;
            }
        }
        return Ok(());
    }

    let applied = runner::migrate_pool(pool, dir).await?;
    if applied.is_empty() {
        writeln!(w, "nothing to migrate (already up to date)")?;
    } else {
        for m in &applied {
            writeln!(w, "  applied {}", m.name)?;
        }
    }
    Ok(())
}

/// `migrate --squash` (#84a) — dev-iteration escape hatch.
///
/// Deletes every pending (un-applied) migration JSON in `dir`, then
/// re-runs `makemigrations` so the diff regenerates as a single
/// fresh file against the current model registry. Recovers the
/// "scaffolder shape → real shape" iteration cycle that hits the
/// `AddColumn NOT NULL no default` validator rejection without
/// touching the database.
///
/// Refuses if any pending migration is somehow already applied
/// (impossible by definition — "pending" means absent from the
/// ledger — but the check is cheap and guards against a future
/// caller passing a stale `applied_set`). Refuses if there are zero
/// pending migrations (nothing to do) or only one (`forget-pending`
/// is the right verb for the single-file case).
async fn migrate_squash<W: Write>(pool: &Pool, dir: &Path, w: &mut W) -> Result<(), MigrateError> {
    runner::ensure_ledger_pool(pool).await?;
    let all = file::list_dir(dir)?;
    let applied = runner::applied_set_pool(pool).await?;

    let pending: Vec<&Migration> = all.iter().filter(|m| !applied.contains(&m.name)).collect();
    if pending.is_empty() {
        writeln!(
            w,
            "no pending migrations to squash (every JSON is in the ledger)"
        )?;
        return Ok(());
    }
    if pending.len() == 1 {
        return Err(MigrateError::Validation(format!(
            "only one pending migration (`{}`) — use `forget-pending {}` instead of `--squash`",
            pending[0].name, pending[0].name,
        )));
    }

    // Defensive double-check: the filter above already guarantees
    // none of these are applied. If a future refactor breaks that
    // invariant we still fail loudly instead of clobbering the
    // ledger.
    for m in &pending {
        if applied.contains(&m.name) {
            return Err(MigrateError::Validation(format!(
                "migrate --squash: refused — migration `{}` appears applied. \
                 Use `migrate <prev>` or `downgrade` to unapply it first.",
                m.name,
            )));
        }
    }

    writeln!(
        w,
        "squashing {} pending migration(s) into a fresh diff:",
        pending.len()
    )?;
    for m in &pending {
        let path = file_path(dir, &m.name);
        std::fs::remove_file(&path).map_err(|e| {
            MigrateError::Validation(format!("migrate --squash: rm {}: {e}", path.display()))
        })?;
        writeln!(w, "  removed {}", path.display())?;
    }

    writeln!(w, "regenerating diff against current model registry...")?;
    // Empty args means "default makemigrations behavior" — splits
    // registry vs tenant in tenancy projects, single file otherwise.
    // Pass through to the existing entry point so any future flags
    // gain consistent behavior automatically.
    makemigrations(dir, &[], w)
}

async fn downgrade<W: Write>(
    pool: &Pool,
    dir: &Path,
    args: &[String],
    w: &mut W,
) -> Result<(), MigrateError> {
    let steps: usize = if let Some(arg) = args.first() {
        arg.parse().map_err(|_| {
            MigrateError::Validation(format!(
                "invalid step count: {arg} (expected a non-negative integer)"
            ))
        })?
    } else {
        1
    };
    let touched = runner::downgrade_pool(pool, dir, steps).await?;
    if touched.is_empty() {
        writeln!(w, "nothing to downgrade")?;
    } else {
        for m in &touched {
            writeln!(w, "  rolled back {}", m.name)?;
        }
    }
    Ok(())
}

async fn showmigrations<W: Write>(pool: &Pool, dir: &Path, w: &mut W) -> Result<(), MigrateError> {
    runner::ensure_ledger_pool(pool).await?;
    let all = file::list_dir(dir)?;
    let applied = runner::applied_set_pool(pool).await?;

    if all.is_empty() {
        writeln!(w, "(no migrations in {})", dir.display())?;
        return Ok(());
    }
    writeln!(w, "Migrations in {}:", dir.display())?;
    for m in &all {
        let mark = if applied.contains(&m.name) {
            "[X]"
        } else {
            "[ ]"
        };
        writeln!(w, "  {mark} {}", m.name)?;
    }
    Ok(())
}

/// `manage forget-pending <name>` — delete a migration JSON that
/// hasn't been applied yet, so the next `makemigrations` regenerates
/// the diff from the current model registry. The actionable
/// companion to the dev-iteration recovery path documented in the
/// `AddColumn NOT NULL no default` validator error (#84).
///
/// Refuses if:
///   - the migration name doesn't match any file in `dir`
///   - the migration is recorded in `__rustango_migrations__` (i.e.
///     it's been applied — removing the JSON without unapplying
///     would orphan the ledger row and break further migrate runs)
///   - more than one migration matches a partial-name query (use
///     the full name to disambiguate)
///
/// On success: deletes the file, prints a one-line confirmation,
/// and suggests `makemigrations` as the follow-up.
async fn forget_pending_cmd<W: Write>(
    pool: &Pool,
    dir: &Path,
    args: &[String],
    w: &mut W,
) -> Result<(), MigrateError> {
    // --help / no args
    let target = match args.first().map(String::as_str) {
        Some("--help") | Some("-h") | None => {
            writeln!(w, "forget-pending <name>")?;
            writeln!(
                w,
                "  Delete a migration JSON that has NOT been applied yet, so the"
            )?;
            writeln!(
                w,
                "  next `makemigrations` regenerates the diff against current"
            )?;
            writeln!(
                w,
                "  models. Refuses to delete an already-applied migration (would"
            )?;
            writeln!(
                w,
                "  orphan the `{}` ledger row and break later runs).",
                runner::LEDGER_TABLE
            )?;
            writeln!(w)?;
            writeln!(
                w,
                "  <name> can be the full migration name (e.g. `0003_auto`)"
            )?;
            writeln!(w, "  or a unique substring; ambiguous matches error.")?;
            return Ok(());
        }
        Some(s) if s.starts_with('-') => {
            return Err(MigrateError::Validation(format!(
                "forget-pending: expected positional <name> first, got flag `{s}`"
            )));
        }
        Some(s) => s,
    };

    runner::ensure_ledger_pool(pool).await?;
    let all = file::list_dir(dir)?;
    let applied = runner::applied_set_pool(pool).await?;

    // Resolve <name> against the file list — accept exact match OR
    // unique substring (matches the "0003" use case).
    let exact: Vec<&Migration> = all.iter().filter(|m| m.name == target).collect();
    let candidates: Vec<&Migration> = if exact.len() == 1 {
        exact
    } else {
        all.iter().filter(|m| m.name.contains(target)).collect()
    };
    let migration = match candidates.len() {
        0 => {
            return Err(MigrateError::Validation(format!(
                "forget-pending: no migration matches `{target}` in {}",
                dir.display()
            )));
        }
        1 => candidates[0],
        n => {
            let names: Vec<&str> = candidates.iter().map(|m| m.name.as_str()).collect();
            return Err(MigrateError::Validation(format!(
                "forget-pending: `{target}` is ambiguous ({n} matches: {}); pass the full migration name",
                names.join(", ")
            )));
        }
    };

    // Refuse if the migration has been applied — removing it would
    // orphan the ledger row.
    if applied.contains(&migration.name) {
        return Err(MigrateError::Validation(format!(
            "forget-pending: migration `{}` is already applied (recorded in `{}`). \
             Use `migrate <prev>` or `downgrade` to unapply it first, then \
             `forget-pending` to drop the JSON.",
            migration.name,
            runner::LEDGER_TABLE,
        )));
    }

    let path = file_path(dir, &migration.name);
    std::fs::remove_file(&path).map_err(|e| {
        MigrateError::Validation(format!("forget-pending: rm {}: {e}", path.display()))
    })?;
    writeln!(w, "deleted {}", path.display())?;
    writeln!(w, "  next: `cargo run -- makemigrations` will regenerate")?;
    writeln!(w, "  the diff against the current model registry.")?;
    Ok(())
}

/// Write an empty migration scaffold (`forward: []`) carrying the
/// predecessor's snapshot so a subsequent `make_migrations` doesn't
/// re-emit the same diff. The user fills in `forward` by hand for
/// data migrations.
///
/// Public so binaries that want a programmatic equivalent of
/// `makemigrations --empty` can call it directly.
///
/// # Errors
/// As [`super::file::list_dir`] / [`super::file::write`].
pub fn make_empty(dir: &Path, name: &str) -> Result<Migration, MigrateError> {
    let prior = file::list_dir(dir)?;
    let prev_snapshot = prior.last().map_or_else(
        || SchemaSnapshot {
            tables: vec![],
            m2m_tables: vec![],
            indexes: vec![],
            checks: vec![],
        },
        |m| m.snapshot.clone(),
    );
    let prev_name = prior.last().map(|m| m.name.clone());
    let next_index = prior
        .last()
        .and_then(|m| file::extract_index(&m.name))
        .map_or(1, |n| n + 1);

    let full_name = format!("{next_index:04}_{name}");
    let mig = Migration {
        name: full_name.clone(),
        created_at: chrono::Utc::now().to_rfc3339(),
        prev: prev_name,
        atomic: true,
        scope: super::MigrationScope::default(),
        snapshot: prev_snapshot,
        forward: vec![],
    };
    if !dir.exists() {
        std::fs::create_dir_all(dir)?;
    }
    file::write(&file_path(dir, &mig.name), &mig)?;
    Ok(mig)
}

fn file_path(dir: &Path, name: &str) -> std::path::PathBuf {
    dir.join(format!("{name}.json"))
}

// ------------------------------------------------------------------ add-data-op

/// Create a new migration containing a single data operation.
///
/// `name` is the migration name suffix (e.g. `"backfill_slugs"`); the index
/// prefix is derived automatically from the migration chain in `dir`.
///
/// If `reverse_sql` is `Some`, the op is marked `reversible = true` and
/// `unapply` / `downgrade` will run the reverse SQL. If `None`, the op is
/// irreversible and rollback will fail fast.
///
/// # Errors
/// [`MigrateError::Io`] / [`MigrateError::Json`] if the file can't be written.
pub fn make_data_migration(
    dir: &Path,
    name: &str,
    sql: &str,
    reverse_sql: Option<&str>,
) -> Result<Migration, MigrateError> {
    let prior = file::list_dir(dir)?;
    let prev_snapshot = prior
        .last()
        .map_or_else(|| SchemaSnapshot::default(), |m| m.snapshot.clone());
    let prev_name = prior.last().map(|m| m.name.clone());
    let next_index = prior
        .last()
        .and_then(|m| file::extract_index(&m.name))
        .map_or(1, |n| n + 1);

    let full_name = format!("{next_index:04}_{name}");
    let op = Operation::Data(DataOp {
        sql: sql.to_owned(),
        reverse_sql: reverse_sql.map(str::to_owned),
        reversible: reverse_sql.is_some(),
    });
    let mig = Migration {
        name: full_name.clone(),
        created_at: chrono::Utc::now().to_rfc3339(),
        prev: prev_name,
        atomic: true,
        scope: super::MigrationScope::default(),
        snapshot: prev_snapshot,
        forward: vec![op],
    };
    if !dir.exists() {
        std::fs::create_dir_all(dir)?;
    }
    file::write(&file_path(dir, &mig.name), &mig)?;
    Ok(mig)
}

/// Append a data operation to an existing migration file.
///
/// `migration_name` is the full migration name (e.g. `"0002_add_slug"`).
/// The op is appended to the end of `forward`. If `reverse_sql` is `Some`
/// the op is reversible.
///
/// # Errors
/// [`MigrateError::Validation`] if `migration_name` not found in `dir`.
/// [`MigrateError::Io`] / [`MigrateError::Json`] for file I/O failures.
pub fn append_data_op(
    dir: &Path,
    migration_name: &str,
    sql: &str,
    reverse_sql: Option<&str>,
) -> Result<(), MigrateError> {
    let path = file_path(dir, migration_name);
    let mut mig = file::load(&path).map_err(|_| {
        MigrateError::Validation(format!(
            "migration `{migration_name}` not found at {}",
            path.display()
        ))
    })?;
    mig.forward.push(Operation::Data(DataOp {
        sql: sql.to_owned(),
        reverse_sql: reverse_sql.map(str::to_owned),
        reversible: reverse_sql.is_some(),
    }));
    file::write(&path, &mig)?;
    Ok(())
}

/// `add-data-op` subcommand handler.
fn add_data_op_cmd<W: Write>(dir: &Path, args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let mut sql: Option<String> = None;
    let mut reverse_sql: Option<String> = None;
    let mut name: Option<String> = None;
    let mut to: Option<String> = None;
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--sql" => {
                sql =
                    Some(iter.next().cloned().ok_or_else(|| {
                        MigrateError::Validation("--sql requires a value".into())
                    })?);
            }
            "--reverse-sql" => {
                reverse_sql = Some(iter.next().cloned().ok_or_else(|| {
                    MigrateError::Validation("--reverse-sql requires a value".into())
                })?);
            }
            "--name" => {
                name =
                    Some(iter.next().cloned().ok_or_else(|| {
                        MigrateError::Validation("--name requires a value".into())
                    })?);
            }
            "--to" => {
                to = Some(iter.next().cloned().ok_or_else(|| {
                    MigrateError::Validation("--to requires a migration name".into())
                })?);
            }
            "--help" | "-h" => {
                writeln!(
                    w,
                    "add-data-op --sql <SQL> [--reverse-sql <SQL>] [--name <name>] [--to <migration>]"
                )?;
                return Ok(());
            }
            other if other.starts_with('-') => {
                return Err(MigrateError::Validation(format!("unknown flag: {other}")));
            }
            other => {
                return Err(MigrateError::Validation(format!(
                    "unexpected argument: `{other}` — use --sql, --reverse-sql, --name, --to"
                )));
            }
        }
    }

    let sql = sql.ok_or_else(|| MigrateError::Validation("--sql is required".into()))?;

    if let Some(migration_name) = to {
        append_data_op(dir, &migration_name, &sql, reverse_sql.as_deref())?;
        writeln!(w, "appended data op to {migration_name}.json")?;
    } else {
        let name = name.unwrap_or_else(|| "data_op".to_owned());
        let mig = make_data_migration(dir, &name, &sql, reverse_sql.as_deref())?;
        let rev_note = if reverse_sql.is_some() {
            " (reversible)"
        } else {
            " (irreversible)"
        };
        writeln!(w, "wrote {}{rev_note}", file_path(dir, &mig.name).display())?;
    }
    Ok(())
}

fn describe_op(op: &Operation) -> String {
    match op {
        Operation::Schema(c) => format!("{c:?}"),
        Operation::Data(d) => {
            let head: String = d.sql.chars().take(60).collect();
            let ellipsis = if d.sql.chars().count() > 60 {
                "…"
            } else {
                ""
            };
            format!("data: {head}{ellipsis}")
        }
    }
}

/// `startapp <name> [--with-manage-bin]` — scaffold a Django-shape app
/// module under `src/<name>/` (`models.rs` + `views.rs` + `urls.rs` +
/// `mod.rs`). Idempotent — files that already exist are reported as
/// skipped. With `--with-manage-bin`, also writes `src/bin/manage.rs`
/// with the standard single-tenant dispatcher boilerplate.
fn startapp<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let mut iter = args.iter();
    let app_name = iter
        .next()
        .cloned()
        .ok_or_else(|| MigrateError::Validation(usage()))?;
    let mut with_manage_bin = false;
    let mut into: Option<String> = None;
    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--with-manage-bin" => with_manage_bin = true,
            "--into" => {
                into = Some(iter.next().cloned().ok_or_else(|| {
                    MigrateError::Validation("--into requires a directory argument".into())
                })?);
            }
            "--help" | "-h" => {
                writeln!(w, "{}", usage())?;
                return Ok(());
            }
            other => {
                return Err(MigrateError::Validation(format!(
                    "startapp: unknown argument `{other}` (run --help for usage)"
                )));
            }
        }
    }
    let base_label = into.clone().unwrap_or_else(|| "src".into());
    let opts = super::scaffold::StartAppOptions {
        app_name: app_name.clone(),
        manage_bin: with_manage_bin.then_some(super::scaffold::SINGLE_TENANT_MANAGE_BIN),
        base_dir: into.map(std::path::PathBuf::from),
    };
    // Project root = current working directory. Most users run
    // `cargo run -- startapp …` from the project root,
    // which is exactly where Cargo.toml lives. Document this in the
    // help string so non-default invocations are an explicit `cd`.
    let cwd = std::env::current_dir()?;
    let report = super::scaffold::startapp(&cwd, &opts)?;
    write_startapp_report(w, &app_name, &base_label, &report)
}

fn write_startapp_report<W: Write>(
    w: &mut W,
    app_name: &str,
    base_label: &str,
    report: &super::scaffold::StartAppReport,
) -> Result<(), MigrateError> {
    if report.written.is_empty() && report.skipped.is_empty() {
        writeln!(w, "startapp: nothing to do")?;
        return Ok(());
    }
    writeln!(w, "startapp `{app_name}`")?;
    for path in &report.written {
        writeln!(w, "  + wrote {path}")?;
    }
    for path in &report.skipped {
        writeln!(w, "  · {path} already exists — left untouched")?;
    }
    for path in &report.patched {
        writeln!(w, "  ~ patched {path} (auto-mounted new app)")?;
    }
    for hint in &report.manual_steps {
        writeln!(w, "  ! manual: {hint}")?;
    }
    if !report.written.is_empty() {
        writeln!(w, "next:")?;
        writeln!(
            w,
            "  add `mod {app_name};` to {base_label}/main.rs (or {base_label}/lib.rs)"
        )?;
        writeln!(
            w,
            "  so the derive macros' `inventory` registrations are pulled in."
        )?;
    }
    Ok(())
}

fn usage() -> String {
    "startapp <name> [--with-manage-bin]\n  \
     Scaffold a Django-shape app module under src/<name>/ (mod.rs +\n  \
     models.rs + views.rs + urls.rs). Idempotent: existing files\n  \
     are left untouched. <name> must be a valid Rust identifier.\n\n  \
     --with-manage-bin\n  \
     Also write src/bin/manage.rs with the single-tenant dispatcher\n  \
     boilerplate. Skipped if the file already exists."
        .to_owned()
}

// ============================================================ about / check / docs / version

/// `manage about` — env summary for support tickets / debugging.
async fn about_cmd<W: Write>(pool: &Pool, w: &mut W) -> Result<(), MigrateError> {
    let registered_models = crate::core::inventory::iter::<crate::core::ModelEntry>
        .into_iter()
        .count();
    let mut apps: std::collections::BTreeSet<&'static str> = std::collections::BTreeSet::new();
    for entry in crate::core::inventory::iter::<crate::core::ModelEntry> {
        if let Some(app) = entry.resolved_app_label() {
            apps.insert(app);
        }
    }

    writeln!(w, "rustango")?;
    writeln!(w, "  version:        {}", env!("CARGO_PKG_VERSION"))?;
    writeln!(w, "  models:         {registered_models} registered")?;
    writeln!(
        w,
        "  apps:           {} ({})",
        apps.len(),
        if apps.is_empty() {
            "none".to_owned()
        } else {
            apps.iter().copied().collect::<Vec<_>>().join(", ")
        }
    )?;
    let env_label = std::env::var("RUSTANGO_ENV").unwrap_or_else(|_| "(unset)".into());
    writeln!(w, "  RUSTANGO_ENV:   {env_label}")?;
    let db_url = std::env::var("DATABASE_URL").map_or("(unset)".into(), |s| {
        // Redact password component
        if let Some(at) = s.rfind('@') {
            if let Some(scheme_end) = s.find("://") {
                let prefix = &s[..scheme_end + 3];
                let rest = &s[at..];
                return format!("{prefix}***{rest}");
            }
        }
        s
    });
    writeln!(w, "  DATABASE_URL:   {db_url}")?;

    // DB connectivity — tri-dialect: SELECT 1 is universal across PG/MySQL/SQLite.
    write!(w, "  db_connect:     ")?;
    let ok = crate::sql::raw_execute_pool(pool, "SELECT 1", Vec::new())
        .await
        .is_ok();
    writeln!(w, "{}", if ok { "ok" } else { "FAILED" })?;

    Ok(())
}

/// `manage check [--deploy]` — run system audits.
async fn check_cmd<W: Write>(
    pool: &Pool,
    dir: &Path,
    args: &[String],
    w: &mut W,
) -> Result<(), MigrateError> {
    let deploy = args.iter().any(|a| a == "--deploy");
    let mut errors: Vec<String> = Vec::new();
    let mut warnings: Vec<String> = Vec::new();
    let mut info: Vec<String> = Vec::new();

    writeln!(
        w,
        "running rustango system check{}...",
        if deploy { " (deploy mode)" } else { "" }
    )?;

    // Always-on checks
    let model_count = crate::core::inventory::iter::<crate::core::ModelEntry>
        .into_iter()
        .count();
    if model_count == 0 {
        errors.push("no models registered — every #[derive(Model)] struct must be `pub use`d through the binary's crate root".into());
    } else {
        info.push(format!("{model_count} models registered via inventory"));
    }

    // DB connectivity — tri-dialect via raw_execute_pool.
    if crate::sql::raw_execute_pool(pool, "SELECT 1", Vec::new())
        .await
        .is_err()
    {
        errors.push("cannot connect to database — verify DATABASE_URL is reachable".into());
    } else {
        info.push("database reachable".into());
    }

    // Pending migrations
    if dir.exists() {
        let prior = file::list_dir(dir)?;
        if prior.is_empty() && model_count > 0 {
            warnings.push(
                "models registered but no migrations on disk — run `manage makemigrations`".into(),
            );
        } else {
            info.push(format!("{} migration(s) on disk", prior.len()));
        }
    }

    // Deploy checks
    if deploy {
        let mut audit = DeployAuditFindings::default();
        run_deploy_audit(&deploy_audit_env(), &mut audit);
        // Settings audit (#87 slice 4) — flags dev-defaults left in
        // prod (e.g. `headers_preset = "dev"` in `prod_settings.toml`).
        // Gated by the `config` feature; no-op without it.
        #[cfg(feature = "config")]
        run_settings_audit(&mut audit);
        info.extend(audit.info);
        warnings.extend(audit.warnings);
        errors.extend(audit.errors);
    }

    // Render
    for msg in &info {
        writeln!(w, "  [info]    {msg}")?;
    }
    for msg in &warnings {
        writeln!(w, "  [warning] {msg}")?;
    }
    for msg in &errors {
        writeln!(w, "  [error]   {msg}")?;
    }

    if !errors.is_empty() {
        return Err(MigrateError::Validation(format!(
            "{} system check(s) failed",
            errors.len()
        )));
    }
    if warnings.is_empty() && errors.is_empty() {
        writeln!(w, "all checks passed")?;
    }
    Ok(())
}

/// `manage docs` — try to open https://docs.rs/rustango in the user's browser.
fn docs_cmd<W: Write>(w: &mut W) -> Result<(), MigrateError> {
    let url = "https://docs.rs/rustango";
    writeln!(w, "{url}")?;
    // Best-effort — don't fail if the OS has no `open` / `xdg-open` / `start`
    let opener = if cfg!(target_os = "macos") {
        Some(("open", url))
    } else if cfg!(target_os = "linux") {
        Some(("xdg-open", url))
    } else if cfg!(target_os = "windows") {
        Some(("cmd", "/C start"))
    } else {
        None
    };
    if let Some((cmd, _)) = opener {
        let _ = std::process::Command::new(cmd).arg(url).spawn();
    }
    Ok(())
}

/// `manage version` — print the rustango framework version.
fn version_cmd<W: Write>(w: &mut W) -> Result<(), MigrateError> {
    writeln!(w, "rustango {}", env!("CARGO_PKG_VERSION"))?;
    Ok(())
}

// ============================================================ make:* generators

fn parse_name_and_model(args: &[String]) -> Result<(String, Option<String>), MigrateError> {
    let mut name: Option<String> = None;
    let mut model: Option<String> = None;
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--model" => {
                model =
                    Some(iter.next().cloned().ok_or_else(|| {
                        MigrateError::Validation("--model requires a value".into())
                    })?);
            }
            other if other.starts_with('-') => {
                return Err(MigrateError::Validation(format!("unknown flag `{other}`")));
            }
            other => {
                if name.is_some() {
                    return Err(MigrateError::Validation(format!(
                        "unexpected positional `{other}`"
                    )));
                }
                name = Some(other.to_owned());
            }
        }
    }
    let name = name.ok_or_else(|| {
        MigrateError::Validation("name is required (e.g. `manage make:viewset PostViewSet`)".into())
    })?;
    if !is_valid_type_name(&name) {
        return Err(MigrateError::Validation(format!(
            "`{name}` is not a valid Rust type name (PascalCase, alphanumeric + underscore)"
        )));
    }
    Ok((name, model))
}

fn is_valid_type_name(name: &str) -> bool {
    let bytes = name.as_bytes();
    !bytes.is_empty()
        && bytes[0].is_ascii_uppercase()
        && bytes
            .iter()
            .all(|b| b.is_ascii_alphanumeric() || *b == b'_')
}

fn pascal_to_snake(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 4);
    for (i, c) in s.chars().enumerate() {
        if c.is_ascii_uppercase() && i > 0 {
            out.push('_');
        }
        out.push(c.to_ascii_lowercase());
    }
    out
}

fn write_generated<W: Write>(
    w: &mut W,
    file_name: &str,
    contents: String,
) -> Result<(), MigrateError> {
    let path = std::path::PathBuf::from("src").join(file_name);
    if path.exists() {
        return Err(MigrateError::Validation(format!(
            "{} already exists — refusing to overwrite",
            path.display()
        )));
    }
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)?;
    }
    std::fs::write(&path, contents)?;
    writeln!(w, "wrote {}", path.display())?;
    writeln!(
        w,
        "  add `mod {};` to src/main.rs (or `pub mod ...;` to src/lib.rs)",
        file_name.trim_end_matches(".rs")
    )?;
    Ok(())
}

fn make_viewset_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    // Tenancy projects need a different scaffold shape — the
    // single-pool `#[derive(ViewSet)]` is fatal for them (#80) — so
    // this command toggles between two templates. Resolution order:
    //
    //   1. `--no-tenant` flag → pool template (escape hatch when
    //      auto-detection guesses wrong, or when a tenancy project
    //      hand-rolls a single-pool viewset for some reason)
    //   2. `--tenant` flag → tenant template (explicit)
    //   3. Cargo.toml has `features = [..., "tenancy", ...]` on the
    //      `rustango` dep → tenant template (auto-detected)
    //   4. Otherwise → pool template
    //
    // The auto-detect path keeps Django-shape "you don't need a flag
    // for the obvious thing" ergonomics: tenancy projects get
    // `tenant_router` without the user having to remember `--tenant`.
    let mut explicit_tenant = false;
    let mut explicit_no_tenant = false;
    let mut filtered: Vec<String> = Vec::with_capacity(args.len());
    for a in args {
        if a == "--tenant" || a == "--tenant-aware" {
            explicit_tenant = true;
        } else if a == "--no-tenant" {
            explicit_no_tenant = true;
        } else {
            filtered.push(a.clone());
        }
    }
    let (tenant_aware, echoed_auto_detect) =
        resolve_viewset_tenant_mode(explicit_tenant, explicit_no_tenant, project_uses_tenancy());
    // Echo when auto-detection picked tenant mode — silent
    // auto-config surprises users; one informational line points
    // them at the override flag without being noisy.
    if echoed_auto_detect {
        writeln!(
            w,
            "make:viewset: auto-detected tenancy mode from Cargo.toml (pass `--no-tenant` to override)"
        )?;
    }
    let (name, model) = parse_name_and_model(&filtered)?;
    let snake = pascal_to_snake(&name);
    let model = model.unwrap_or_else(|| "Post".into());
    let body = if tenant_aware {
        viewset_template_tenant(&name, &model, &snake)
    } else {
        viewset_template_pool(&name, &model, &snake)
    };
    write_generated(w, &format!("{snake}.rs"), body)
}

/// Template emitted by `make:viewset <Name>` (default). Uses the
/// `#[derive(ViewSet)]` shape with a mount-time `PgPool` —
/// appropriate for single-tenant projects (api / fullstack
/// templates).
fn viewset_template_pool(name: &str, model: &str, snake: &str) -> String {
    format!(
        r#"//! Auto-scaffolded by `manage make:viewset {name}`.

use rustango::ViewSet;

#[derive(ViewSet)]
#[viewset(
    model        = {model},
    fields       = "id, ",
    filter_fields = "",
    search_fields = "",
    page_size    = 20,
)]
pub struct {name};

// Mount in your urls.rs:
//
//   .merge({name}::router("/api/{snake}", pool.clone()))
"#
    )
}

/// Template emitted by `make:viewset <Name> --tenant`. Uses the
/// runtime-built `ViewSet::for_model(...).tenant_router(...)` shape
/// (#80) so each request resolves the per-tenant connection via the
/// `Tenant` extractor instead of capturing a single pool at mount
/// time. Required for tenancy projects.
///
/// Since v0.30, `tenant_router` carries the full static-router builder
/// chain (filter / search / ordering / pagination / permissions) so
/// the scaffold demonstrates each knob — same shape Django's class-
/// based admin generators emit, just with `// uncomment to enable`
/// markers next to each one.
fn viewset_template_tenant(name: &str, model: &str, snake: &str) -> String {
    format!(
        r#"//! Auto-scaffolded by `manage make:viewset {name} --tenant`.
//!
//! Tenant-aware viewset: each request resolves the connection via
//! `rustango::extractors::Tenant`, so the same `router()` serves
//! every tenant under their own subdomain / schema / database.
//!
//! Since v0.30 (#80), `tenant_router` carries the full static-router
//! builder chain — filter_fields / search_fields / ordering /
//! page_size / permissions_for_model all work in tenant mode too.

use axum::Router;
use rustango::core::Model as _;
use rustango::viewset::ViewSet;

use crate::models::{model};

pub fn router() -> Router<()> {{
    ViewSet::for_model({model}::SCHEMA)
        // .fields(&["id", "name", "created_at"])    // restrict response shape
        // .filter_fields(&["status", "owner_id"])    // ?status=draft&owner_id=42
        // .search_fields(&["name", "description"])   // ?search=foo (ILIKE)
        // .ordering(&[("created_at", true)])         // default ORDER BY
        // .ordering_fields(&["name", "created_at"])  // ?ordering=-name allowlist
        // .page_size(20)
        // .permissions_for_model::<{model}>()        // CRUD codenames
        // .read_only()                               // GET only
        .tenant_router("/api/{snake}")
}}

// Mount in your urls.rs:
//
//   .merge(crate::viewsets::{snake}::router())
"#
    )
}

/// Detect whether the project the scaffolder is running inside enables
/// the `tenancy` feature on its `rustango` dep — used to default
/// `make:viewset` to `--tenant` when no explicit flag is given.
/// Reads `./Cargo.toml` from the current working directory; returns
/// `false` (single-tenant default) on any read/parse failure so the
/// scaffolder doesn't break in odd environments.
///
/// Heuristic: look for a `[dependencies.rustango]` table with
/// `features = [..., "tenancy", ...]` OR an inline-table dep
/// (`rustango = {{ version = "...", features = [..., "tenancy"] }}`).
/// Cargo.toml syntax is well-defined; this is a substring check
/// rather than a full TOML parse to keep the binary light, but it's
/// strict enough — a `# tenancy` comment elsewhere wouldn't trigger.
/// Decide whether `make:viewset` should emit the tenant template
/// and whether to echo a one-line auto-detect notice. Pure
/// function — no I/O, no `cargo` introspection — so tests can
/// exercise every branch without chdir tricks. The actual Cargo.toml
/// inspection happens once in [`project_uses_tenancy`] and gets
/// passed in here.
///
/// Returns `(tenant_aware, echo_auto_detect)`.
fn resolve_viewset_tenant_mode(
    explicit_tenant: bool,
    explicit_no_tenant: bool,
    project_tenancy: bool,
) -> (bool, bool) {
    if explicit_no_tenant {
        return (false, false);
    }
    if explicit_tenant {
        return (true, false);
    }
    // Auto-detect path. Echo only when we actually picked tenant.
    (project_tenancy, project_tenancy)
}

fn project_uses_tenancy() -> bool {
    let Ok(s) = std::fs::read_to_string("Cargo.toml") else {
        return false;
    };
    // Find the rustango dep block. Either a bare key
    // `rustango = "..."` (no features at all → not tenancy) or a
    // structured form (`rustango = { features = [...] }`) or a
    // dedicated table `[dependencies.rustango]`. We scan the whole
    // file for both shapes since the line carrying the features may
    // be on its own.
    let lower = s.to_ascii_lowercase();
    let has_inline = lower.contains("rustango")
        && lower
            .lines()
            .any(|line| line.contains("rustango") && line.contains("\"tenancy\""));
    let has_table_block =
        lower.contains("[dependencies.rustango]") && lower.contains("\"tenancy\"");
    has_inline || has_table_block
}

/// `manage make:api_routes <app> [--tenant]` — emit
/// `src/<app>/api_routes.rs`, the per-app composer that merges
/// every viewset's router into a single `Router<()>` (#82).
///
/// Mirrors the working pattern in tango/src/regions/api_routes.rs:
/// each per-model file under `viewsets/` exposes a router fn, and
/// `api_routes::api()` composes them with `.merge(...)`. The
/// scaffold is intentionally minimal — placeholder comments mark
/// where to add `.merge(...)` lines as new viewsets are written.
///
/// Refuses to overwrite an existing file. Errors clearly when the
/// `src/<app>/` directory is missing — tells the user to run
/// `manage startapp <app>` first.
fn make_api_routes_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let mut tenant_aware = false;
    let mut filtered: Vec<String> = Vec::with_capacity(args.len());
    for a in args {
        if a == "--tenant" || a == "--tenant-aware" {
            tenant_aware = true;
        } else if a == "--help" || a == "-h" {
            writeln!(w, "make:api_routes <app> [--tenant]")?;
            writeln!(
                w,
                "  Scaffold src/<app>/api_routes.rs — the per-app router composer."
            )?;
            writeln!(
                w,
                "  Use --tenant for tenancy projects (no PgPool argument; each"
            )?;
            writeln!(
                w,
                "  viewset resolves its own per-request connection via the Tenant"
            )?;
            writeln!(w, "  extractor).")?;
            return Ok(());
        } else if a.starts_with('-') {
            return Err(MigrateError::Validation(format!(
                "make:api_routes: unrecognized flag `{a}`"
            )));
        } else {
            filtered.push(a.clone());
        }
    }
    let app = filtered.first().ok_or_else(|| {
        MigrateError::Validation(
            "app name is required (e.g. `manage make:api_routes regions`)".into(),
        )
    })?;
    if filtered.len() > 1 {
        return Err(MigrateError::Validation(format!(
            "make:api_routes: expected one app name, got {} ({:?})",
            filtered.len(),
            filtered
        )));
    }
    if !is_valid_app_name(app) {
        return Err(MigrateError::Validation(format!(
            "make:api_routes: app name `{app}` must match `[a-z_][a-z0-9_]*`"
        )));
    }

    let app_dir = std::path::PathBuf::from("src").join(app);
    if !app_dir.exists() {
        return Err(MigrateError::Validation(format!(
            "make:api_routes: src/{app}/ does not exist. Run `manage startapp {app}` first."
        )));
    }

    let path = app_dir.join("api_routes.rs");
    if path.exists() {
        return Err(MigrateError::Validation(format!(
            "{} already exists — refusing to overwrite",
            path.display()
        )));
    }

    let body = if tenant_aware {
        api_routes_template_tenant(app)
    } else {
        api_routes_template_pool(app)
    };
    std::fs::write(&path, body)?;
    writeln!(w, "wrote {}", path.display())?;
    writeln!(
        w,
        "  add `pub mod api_routes;` to src/{app}/mod.rs (or `mod ...;`),"
    )?;
    writeln!(
        w,
        "  then `.merge({app}::api_routes::api())` from your top-level urls.rs."
    )?;
    Ok(())
}

fn is_valid_app_name(s: &str) -> bool {
    let mut chars = s.chars();
    match chars.next() {
        Some(c) if c.is_ascii_lowercase() || c == '_' => {}
        _ => return false,
    }
    chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
}

/// `--tenant` template — uses each viewset's `tenant_router(...)`,
/// no `PgPool` threaded through `api()` since the per-tenant
/// connection is resolved per-request via the `Tenant` extractor.
fn api_routes_template_tenant(app: &str) -> String {
    format!(
        r#"//! Auto-scaffolded by `manage make:api_routes {app} --tenant`.
//!
//! API routing for the `{app}` app. Per-model viewsets live under
//! `viewsets/` and each exposes a `pub fn viewset() -> ViewSet`;
//! this file composes them into a single `Router<()>`.
//!
//! Adding a resource:
//!   1. Drop a new file under `viewsets/` exposing
//!      `pub fn viewset() -> ViewSet`.
//!   2. Declare it in `viewsets/mod.rs`.
//!   3. Add one `.merge(...)` line below.

use axum::Router;

pub fn api() -> Router<()> {{
    Router::new()
        // .merge(super::viewsets::<model>::viewset().tenant_router("/api/<model>"))
}}
"#
    )
}

/// Default template (no `--tenant`) — single-pool projects. The
/// `pool` argument is threaded into per-model `router(prefix, pool)`
/// calls; the macro-derived ViewSet captures it at mount time.
fn api_routes_template_pool(app: &str) -> String {
    format!(
        r#"//! Auto-scaffolded by `manage make:api_routes {app}`.
//!
//! API routing for the `{app}` app. Composes per-model viewsets
//! into a single `Router<()>`. Each viewset captures the supplied
//! `PgPool` at mount time.
//!
//! Adding a resource:
//!   1. Run `manage make:viewset <Name> --model <Model>`.
//!   2. Add one `.merge(...)` line below.

use axum::Router;
use rustango::sql::sqlx::PgPool;

pub fn api(pool: PgPool) -> Router<()> {{
    let _pool = pool;
    Router::new()
        // .merge(super::viewsets::<snake>::router("/api/<snake>", _pool.clone()))
}}
"#
    )
}

fn make_serializer_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let (name, model) = parse_name_and_model(args)?;
    let snake = pascal_to_snake(&name);
    let model = model.unwrap_or_else(|| "Post".into());
    let body = format!(
        r#"//! Auto-scaffolded by `manage make:serializer {name}`.

use rustango::Serializer;

#[derive(Serializer, serde::Deserialize, Default)]
#[serializer(model = {model})]
pub struct {name} {{
    pub id: i64,
    // pub title: String,
    // #[serializer(read_only)]
    // pub created_at: chrono::DateTime<chrono::Utc>,
}}
"#
    );
    write_generated(w, &format!("{snake}.rs"), body)
}

fn make_form_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let (name, _) = parse_name_and_model(args)?;
    let snake = pascal_to_snake(&name);
    let body = format!(
        r#"//! Auto-scaffolded by `manage make:form {name}`.

use rustango::forms::Form;
use rustango::Form as DeriveForm;

#[derive(DeriveForm)]
pub struct {name} {{
    #[form(min_length = 1, max_length = 200)]
    pub title: String,
    pub body: Option<String>,
}}
"#
    );
    write_generated(w, &format!("{snake}.rs"), body)
}

fn make_job_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let (name, _) = parse_name_and_model(args)?;
    let snake = pascal_to_snake(&name);
    let body = format!(
        r#"//! Auto-scaffolded by `manage make:job {name}`.
//!
//! Background job — run async work outside the request lifecycle.
//! Pair with `rustango::scheduler::Scheduler` (cron-shape) or your queue layer.

use std::sync::Arc;
use rustango::sql::sqlx::PgPool;

pub struct {name} {{
    pub pool: PgPool,
}}

impl {name} {{
    pub async fn run(self: Arc<Self>) {{
        // TODO: implement
        let _ = self.pool.acquire().await;
    }}
}}

// Wire up in main.rs:
//
//   let job = Arc::new({name} {{ pool: pool.clone() }});
//   scheduler.every("{snake}", Duration::from_secs(60), move || {{
//       let job = job.clone();
//       async move {{ job.run().await }}
//   }});
"#
    );
    write_generated(w, &format!("{snake}.rs"), body)
}

fn make_notification_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let (name, _) = parse_name_and_model(args)?;
    let snake = pascal_to_snake(&name);
    let body = format!(
        r#"//! Auto-scaffolded by `manage make:notification {name}`.
//!
//! User-facing notification. For now this just builds an Email; once the
//! `rustango::notifications` layer ships you'll add `via()` for multi-channel.

use rustango::email::Email;

pub struct {name} {{
    pub user_email: String,
    pub subject: String,
}}

impl {name} {{
    pub fn build_email(&self) -> Email {{
        Email::new()
            .to(&self.user_email)
            .from("noreply@example.com")
            .subject(&self.subject)
            .body("Hello — this notification was generated by {name}.")
    }}
}}
"#
    );
    write_generated(w, &format!("{snake}.rs"), body)
}

fn make_middleware_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let (name, _) = parse_name_and_model(args)?;
    let snake = pascal_to_snake(&name);
    let body = format!(
        r#"//! Auto-scaffolded by `manage make:middleware {name}`.

use axum::body::Body;
use axum::http::{{Request, Response}};
use axum::middleware::Next;

pub async fn {snake}(req: Request<Body>, next: Next) -> Response<Body> {{
    // TODO: pre-handler logic
    let response = next.run(req).await;
    // TODO: post-handler logic
    response
}}

// Apply with:
//   router.layer(axum::middleware::from_fn({snake}))
"#
    );
    write_generated(w, &format!("{snake}.rs"), body)
}

fn make_test_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let (name, _) = parse_name_and_model(args)?;
    let snake = pascal_to_snake(&name);
    let body = format!(
        r#"//! Auto-scaffolded by `manage make:test {name}`.
//!
//! Integration test. Run with `cargo test --test {snake}`.

use rustango::test_client::TestClient;
use axum::Router;
use axum::routing::get;

fn app() -> Router {{
    Router::new().route("/hello", get(|| async {{ "hi" }}))
}}

#[tokio::test]
async fn {snake}_smoke() {{
    let client = TestClient::new(app());
    let r = client.get("/hello").send().await;
    assert_eq!(r.status, 200);
    assert_eq!(r.text(), "hi");
}}
"#
    );
    // Tests live in tests/ not src/
    let path = std::path::PathBuf::from("tests").join(format!("{snake}.rs"));
    if path.exists() {
        return Err(MigrateError::Validation(format!(
            "{} already exists — refusing to overwrite",
            path.display()
        )));
    }
    if let Some(parent) = path.parent() {
        std::fs::create_dir_all(parent)?;
    }
    std::fs::write(&path, body)?;
    writeln!(w, "wrote {}", path.display())?;
    Ok(())
}

// =====================================================================
// db:dump / db:restore — shell out to pg_dump / psql
// =====================================================================

#[derive(Debug, PartialEq)]
struct DbDumpArgs {
    out: Option<String>,
    data_only: bool,
    schema_only: bool,
    no_owner: bool,
}

fn parse_db_dump_args(args: &[String]) -> Result<DbDumpArgs, MigrateError> {
    let mut out: Option<String> = None;
    let mut data_only = false;
    let mut schema_only = false;
    let mut no_owner = false;
    let mut iter = args.iter();
    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--out" | "-o" => {
                out = Some(
                    iter.next()
                        .cloned()
                        .ok_or_else(|| MigrateError::Validation("--out requires a path".into()))?,
                );
            }
            "--data-only" => data_only = true,
            "--schema-only" => schema_only = true,
            "--no-owner" => no_owner = true,
            other => {
                return Err(MigrateError::Validation(format!("unknown flag: {other}")));
            }
        }
    }
    if data_only && schema_only {
        return Err(MigrateError::Validation(
            "--data-only and --schema-only are mutually exclusive".into(),
        ));
    }
    Ok(DbDumpArgs {
        out,
        data_only,
        schema_only,
        no_owner,
    })
}

/// Build the argument vector for pg_dump given parsed args + database
/// URL. Pure function — easy to test.
fn build_pg_dump_argv(parsed: &DbDumpArgs, database_url: &str) -> Vec<String> {
    let mut argv = vec![database_url.to_owned()];
    if parsed.data_only {
        argv.push("--data-only".into());
    }
    if parsed.schema_only {
        argv.push("--schema-only".into());
    }
    if parsed.no_owner {
        argv.push("--no-owner".into());
    }
    if let Some(out) = &parsed.out {
        argv.push("--file".into());
        argv.push(out.clone());
    }
    argv
}

fn db_dump_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let parsed = parse_db_dump_args(args)?;
    let url = std::env::var("DATABASE_URL").map_err(|_| {
        MigrateError::Validation(
            "DATABASE_URL must be set for db:dump (e.g. \
             postgres://user:pass@host:5432/db)"
                .into(),
        )
    })?;
    let argv = build_pg_dump_argv(&parsed, &url);
    writeln!(w, "running: pg_dump {}", redact(&argv).join(" "))?;
    let status = std::process::Command::new("pg_dump")
        .args(&argv)
        .status()
        .map_err(|e| {
            MigrateError::Validation(format!("could not run pg_dump (is it on PATH?): {e}"))
        })?;
    if !status.success() {
        return Err(MigrateError::Validation(format!(
            "pg_dump exited with status {status}"
        )));
    }
    Ok(())
}

#[derive(Debug, PartialEq)]
struct DbRestoreArgs {
    file: String,
    clean: bool,
}

fn parse_db_restore_args(args: &[String]) -> Result<DbRestoreArgs, MigrateError> {
    let mut file: Option<String> = None;
    let mut clean = false;
    for arg in args {
        match arg.as_str() {
            "--clean" => clean = true,
            other if other.starts_with('-') => {
                return Err(MigrateError::Validation(format!("unknown flag: {other}")));
            }
            other => {
                if file.is_some() {
                    return Err(MigrateError::Validation(format!(
                        "unexpected argument: {other}"
                    )));
                }
                file = Some(other.to_owned());
            }
        }
    }
    let file = file.ok_or_else(|| {
        MigrateError::Validation("db:restore <file> requires a dump file path".into())
    })?;
    Ok(DbRestoreArgs { file, clean })
}

/// Build the psql argv given parsed args + URL. Pure function — easy
/// to test.
fn build_psql_argv(parsed: &DbRestoreArgs, database_url: &str) -> Vec<String> {
    let mut argv = vec![database_url.to_owned()];
    // -v ON_ERROR_STOP=1 makes psql exit non-zero on the first SQL
    // error, instead of plowing through and "succeeding" with garbage.
    argv.push("-v".into());
    argv.push("ON_ERROR_STOP=1".into());
    if parsed.clean {
        argv.push("-c".into());
        argv.push("DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public;".into());
    }
    argv.push("-f".into());
    argv.push(parsed.file.clone());
    argv
}

fn db_restore_cmd<W: Write>(args: &[String], w: &mut W) -> Result<(), MigrateError> {
    let parsed = parse_db_restore_args(args)?;
    let url = std::env::var("DATABASE_URL").map_err(|_| {
        MigrateError::Validation(
            "DATABASE_URL must be set for db:restore (e.g. \
             postgres://user:pass@host:5432/db)"
                .into(),
        )
    })?;
    let argv = build_psql_argv(&parsed, &url);
    writeln!(w, "running: psql {}", redact(&argv).join(" "))?;
    let status = std::process::Command::new("psql")
        .args(&argv)
        .status()
        .map_err(|e| {
            MigrateError::Validation(format!("could not run psql (is it on PATH?): {e}"))
        })?;
    if !status.success() {
        return Err(MigrateError::Validation(format!(
            "psql exited with status {status}"
        )));
    }
    Ok(())
}

/// `db:info` — read-only summary of the DB configuration this build
/// would use. Shows the resolved URL (password redacted), the detected
/// backend, and which `postgres`/`mysql` Cargo features are compiled
/// in. Does not connect — handy in CI / containers where DB might not
/// be reachable yet but you still want to confirm the runtime sees
/// the expected backend.
fn db_info_cmd<W: Write>(w: &mut W) -> Result<(), MigrateError> {
    writeln!(w, "rustango db:info")?;
    writeln!(w, "  framework version:  {}", env!("CARGO_PKG_VERSION"))?;

    let pg_enabled = cfg!(feature = "postgres");
    let mysql_enabled = cfg!(feature = "mysql");
    writeln!(
        w,
        "  postgres feature:   {}",
        if pg_enabled { "enabled" } else { "disabled" }
    )?;
    writeln!(
        w,
        "  mysql feature:      {} (impl lands in v0.23.0-batch2)",
        if mysql_enabled { "enabled" } else { "disabled" }
    )?;

    match crate::env::database_url_from_env() {
        Ok(url) => {
            let scheme = url.split("://").next().unwrap_or("(unknown)");
            writeln!(w, "  resolved URL:       {}", redact_url(&url))?;
            writeln!(w, "  detected backend:   {scheme}")?;
            // Soft warning when scheme + feature don't line up — caught
            // at runtime by Pool::connect, but this surfaces it before
            // the operator tries to start the server.
            match scheme {
                "postgres" | "postgresql" if !pg_enabled => {
                    writeln!(
                        w,
                        "  ! warning: URL is postgres but the `postgres` feature is disabled — \
                         add `features = [\"postgres\"]` to rustango"
                    )?;
                }
                "mysql" if !mysql_enabled => {
                    writeln!(
                        w,
                        "  ! warning: URL is mysql but the `mysql` feature is disabled — \
                         add `features = [\"mysql\"]` to rustango"
                    )?;
                }
                "mysql" if mysql_enabled => {
                    writeln!(
                        w,
                        "  ! note: MySql connections will fail in v0.23.0-batch1 \
                         (MySqlDialect lands in batch2)"
                    )?;
                }
                _ => {}
            }
        }
        Err(e) => {
            writeln!(w, "  resolved URL:       (none — {e})")?;
            writeln!(
                w,
                "  hint:               set DATABASE_URL or DB_USER+DB_NAME (+optional \
                 DB_HOST/DB_PORT/DB_PASSWORD/DB_DRIVER/DB_PARAMS)"
            )?;
        }
    }
    Ok(())
}

/// Mask the password in a `postgres://user:pass@host/db` connection
/// URL so it doesn't leak into log output.
fn redact(argv: &[String]) -> Vec<String> {
    argv.iter().map(|a| redact_url(a)).collect()
}

fn redact_url(s: &str) -> String {
    // Match `<scheme>://<user>:<password>@<rest>` and replace `<password>`
    // with `***`. Anything that doesn't look like a URL passes through.
    let Some(scheme_end) = s.find("://") else {
        return s.to_owned();
    };
    let rest = &s[scheme_end + 3..];
    let Some(at) = rest.find('@') else {
        return s.to_owned();
    };
    let creds = &rest[..at];
    let Some(colon) = creds.find(':') else {
        return s.to_owned();
    };
    let user = &creds[..colon];
    let after_at = &rest[at..];
    format!("{}://{user}:***{after_at}", &s[..scheme_end])
}

/// Snapshot of the env vars `manage check --deploy` cares about.
/// Lifted out so the audit logic is pure (testable without
/// `unsafe { env::set_var }` race conditions across `cargo test`'s
/// parallel runners).
#[derive(Debug, Default, Clone)]
pub(crate) struct DeployAuditEnv {
    pub rustango_env: Option<String>,
    pub session_secret: Option<String>,
    pub database_url: Option<String>,
    pub apex_domain: Option<String>,
    pub bind: Option<String>,
}

fn deploy_audit_env() -> DeployAuditEnv {
    DeployAuditEnv {
        rustango_env: std::env::var("RUSTANGO_ENV").ok(),
        session_secret: std::env::var("RUSTANGO_SESSION_SECRET").ok(),
        database_url: std::env::var("DATABASE_URL").ok(),
        apex_domain: std::env::var("RUSTANGO_APEX_DOMAIN").ok(),
        bind: std::env::var("RUSTANGO_BIND").ok(),
    }
}

#[derive(Debug, Default)]
pub(crate) struct DeployAuditFindings {
    pub info: Vec<String>,
    pub warnings: Vec<String>,
    pub errors: Vec<String>,
}

/// Run the `manage check --deploy` audit checks against `env`.
/// Pure function so callers can test it with arbitrary env
/// snapshots without poking actual process env vars.
///
/// Modernized from the v0.27 shape that checked the wrong env
/// var (`SECRET_KEY` — never read by the framework). The
/// framework reads `RUSTANGO_SESSION_SECRET` for HMAC-signing
/// the operator-console + tenant-admin cookies AND the JWT
/// payloads issued by `auth_routes::jwt_router` (#81). Same key
/// covers both surfaces.
pub(crate) fn run_deploy_audit(env: &DeployAuditEnv, out: &mut DeployAuditFindings) {
    // RUSTANGO_ENV — production should be explicitly tagged.
    match env.rustango_env.as_deref() {
        Some("prod" | "production") => {
            out.info
                .push("RUSTANGO_ENV is set to a production value".into());
        }
        Some(other) => {
            out.warnings.push(format!(
                "RUSTANGO_ENV is `{other}` — set to `prod` (or `production`) in deployed env"
            ));
        }
        None => {
            out.warnings.push(
                "RUSTANGO_ENV is unset — set to `prod` so config loaders pick the right tier"
                    .into(),
            );
        }
    }

    // RUSTANGO_SESSION_SECRET — required for cookie + JWT signing.
    // Recommended: 32+ bytes of base64-encoded entropy
    // (`openssl rand -base64 32`). The framework treats the raw
    // value as the HMAC key, so length matters.
    match env.session_secret.as_deref() {
        None => {
            out.errors.push(
                "RUSTANGO_SESSION_SECRET is unset — operator + tenant cookies + JWTs would use \
                 an ephemeral random secret that's regenerated on every restart, signing every \
                 user out. Set via `openssl rand -base64 32`."
                    .into(),
            );
        }
        Some(s) if s.len() < 32 => {
            out.errors.push(format!(
                "RUSTANGO_SESSION_SECRET is only {} bytes — need ≥ 32 for HMAC key strength. \
                 Regenerate with `openssl rand -base64 32`.",
                s.len()
            ));
        }
        Some(s) if s.contains("change-me") || s.contains("placeholder") => {
            out.errors.push(
                "RUSTANGO_SESSION_SECRET still contains the scaffolder placeholder \
                 (`change-me-...`) — replace with a real secret via `openssl rand -base64 32`."
                    .into(),
            );
        }
        Some(_) => {
            out.info.push("RUSTANGO_SESSION_SECRET length OK".into());
        }
    }

    // DATABASE_URL — required.
    match env.database_url.as_deref() {
        None => out
            .errors
            .push("DATABASE_URL is unset — required in production".into()),
        Some(url) if url.contains("localhost") || url.contains("127.0.0.1") => {
            out.warnings.push(
                "DATABASE_URL points at localhost / 127.0.0.1 — verify this is intended in \
                 production (typically a managed service hostname)"
                    .into(),
            );
        }
        Some(_) => out.info.push("DATABASE_URL set".into()),
    }

    // RUSTANGO_APEX_DOMAIN — required for tenancy projects, but
    // single-tenant projects don't need it. Surface as info, not
    // warning, when unset (`localhost` is the framework default
    // and works for non-tenancy deployments).
    match env.apex_domain.as_deref() {
        None | Some("localhost") => {
            out.warnings.push(
                "RUSTANGO_APEX_DOMAIN is unset / `localhost` — tenancy projects need this set to \
                 the public-facing apex (e.g. `app.example.com`) so subdomain resolution + \
                 cookie scoping work in production. Single-tenant projects can ignore."
                    .into(),
            );
        }
        Some(_) => out
            .info
            .push("RUSTANGO_APEX_DOMAIN set to a non-localhost value".into()),
    }

    // RUSTANGO_BIND — warn if loopback-only. Common typo in dev
    // configs that get promoted to prod without rebinding.
    match env.bind.as_deref() {
        Some(b) if b.starts_with("127.0.0.1") => {
            out.warnings.push(format!(
                "RUSTANGO_BIND={b} only listens on loopback — production usually wants \
                 `0.0.0.0:<port>` to accept external traffic"
            ));
        }
        Some(_) | None => {} // either explicit non-loopback or framework default (0.0.0.0)
    }
}

/// `manage check --deploy` settings-side audit (#87 slice 4) —
/// loads `Settings::load_from_env()` and flags dev-defaults left in
/// the prod tier. Pure function over the loaded settings + resolved
/// tier, no env-var poking.
///
/// Graceful: missing `config/default.toml` is silently skipped (the
/// project might not use the layered loader at all). Bad TOML
/// shape surfaces as a warning so the operator notices but the
/// rest of the audit still runs.
#[cfg(feature = "config")]
fn run_settings_audit(out: &mut DeployAuditFindings) {
    use crate::config::Settings;

    let env_tier = Settings::current_env_tier();
    out.info
        .push(format!("config tier resolved to `{env_tier}`"));

    let settings = match Settings::load_from_env() {
        Ok(s) => s,
        Err(crate::config::ConfigError::Io { .. }) => {
            // `config/default.toml` not present — project doesn't use
            // the layered loader. Skip silently.
            return;
        }
        Err(e) => {
            out.warnings.push(format!(
                "config: failed to load settings for audit: {e} — fix the file shape \
                 to enable the rest of the deploy audit"
            ));
            return;
        }
    };

    settings_audit_check(&env_tier, &settings, out);
}

/// Pure-function half of [`run_settings_audit`] — caller supplies
/// the resolved tier + settings. Lifted out so unit tests can run
/// against any combination without touching the on-disk config
/// pipeline (which would race against parallel test runners).
#[cfg(feature = "config")]
pub(crate) fn settings_audit_check(
    env_tier: &str,
    settings: &crate::config::Settings,
    out: &mut DeployAuditFindings,
) {
    let in_prod = matches!(env_tier, "prod" | "production");
    if !in_prod {
        // Non-prod tiers don't need the dev-default-leak audit.
        return;
    }

    // [security] headers_preset — must be `strict` (or unset →
    // strict by default at the layer). `"dev"` / `"none"` in prod
    // strips HSTS / XFO / nosniff / Referrer-Policy.
    if let Some(preset) = settings.security.headers_preset.as_deref() {
        if preset == "dev" || preset == "none" {
            out.warnings.push(format!(
                "[security] headers_preset = `{preset}` in prod tier — promote to `strict` \
                 so HSTS / X-Frame-Options / X-Content-Type-Options / Referrer-Policy are emitted"
            ));
        }
    }

    // [security] hsts_max_age_secs = 0 in prod disables HSTS.
    if matches!(settings.security.hsts_max_age_secs, Some(0)) {
        out.warnings.push(
            "[security] hsts_max_age_secs = 0 in prod tier — disables HSTS, leaving TLS-strip \
             attacks viable on first request"
                .into(),
        );
    }

    // [auth] argon2 memory cost — OWASP 2024 floor is 19456 KiB.
    if let Some(kib) = settings.auth.argon2_memory_kib {
        if kib < 19_456 {
            out.warnings.push(format!(
                "[auth] argon2_memory_kib = {kib} in prod tier — OWASP 2024 recommends ≥ 19456 \
                 for password hashing brute-force resistance"
            ));
        }
    }

    // [auth.jwt] access TTL too long. Anything over 1 hour is
    // suspicious — refresh tokens should rotate access tokens.
    if let Some(ttl) = settings.auth.jwt.access_ttl_secs {
        if ttl > 3600 {
            out.warnings.push(format!(
                "[auth.jwt] access_ttl_secs = {ttl} in prod tier — access tokens > 1h widen \
                 the leaked-token blast radius. The refresh flow rotates them; keep this short."
            ));
        }
    }

    // [audit] retention_days unset → log grows forever. Not an
    // error (some compliance regimes mandate forever) but worth
    // info-flagging so the operator decides intentionally.
    if settings.audit.retention_days.is_none() {
        out.info.push(
            "[audit] retention_days unset — log grows forever; consider setting + scheduling \
             `manage audit-cleanup --days <N>`"
                .into(),
        );
    }

    // [routes] legacy_preset = true is a deliberate choice (#85) but
    // worth surfacing in audit output so operators rationalize the
    // `/__admin` shape against the current Django-ish default.
    if matches!(settings.routes.legacy_preset, Some(true)) {
        out.info.push(
            "[routes] legacy_preset = true — using the pre-v0.29 `__`-prefixed URLs \
             (`/__login`, `/__admin`, …). Switch to the friendly defaults when bookmarks allow."
                .into(),
        );
    }

    // [server] bind on loopback in prod. The env-var path catches
    // RUSTANGO_BIND; this catches the TOML case that bypasses it.
    if let Some(bind) = settings.server.bind.as_deref() {
        if bind.starts_with("127.0.0.1") || bind.starts_with("localhost") {
            out.warnings.push(format!(
                "[server] bind = `{bind}` in prod tier — only listens on loopback. \
                 Production usually wants `0.0.0.0:<port>` to accept external traffic."
            ));
        }
    }

    // v0.36 slice 9 — backend × tenancy alignment check. Schema-mode
    // tenancy uses `SET search_path` which only Postgres supports.
    // Flag config files that pair a non-PG backend with tenancy.
    if let Some(backend) = settings.database.resolved_backend() {
        let tenancy_on = crate::config::Settings::detected_features()
            .iter()
            .any(|f| *f == "tenancy");
        if tenancy_on && backend != "postgres" {
            out.warnings.push(format!(
                "[database] backend = `{backend}` with `tenancy` feature on — \
                 schema-mode multi-tenancy is Postgres-only by language semantics \
                 (it relies on `SET search_path`). Either switch to a Postgres URL \
                 in prod, or use `crate::tenancy::DatabasePools<DB>` for the \
                 one-database-per-tenant model that works on sqlite/mysql."
            ));
        }
    }

    // v0.36 slice 7+10 — [admin] section deploy audit. The new
    // settings-driven admin Builder reads these in
    // `admin::Builder::from_settings`; flag dev-defaults left in prod.
    let admin = &settings.admin;

    // CSRF cookie must be Secure in prod (HTTPS only).
    if matches!(admin.csrf_cookie_secure, Some(false)) {
        out.warnings.push(
            "[admin] csrf_cookie_secure = false in prod tier — admin CSRF cookie will be \
             sent over plain HTTP, which strips its tamper resistance. Set true (or remove \
             the override) so the framework default Secure flag applies."
                .into(),
        );
    }

    // Hex color sanity — common typo is missing `#` or RGB shorthand.
    if let Some(hex) = admin.primary_color.as_deref() {
        let stripped = hex.trim_start_matches('#');
        let valid_len = matches!(stripped.len(), 3 | 6 | 8);
        let all_hex = stripped.chars().all(|c| c.is_ascii_hexdigit());
        if !hex.starts_with('#') || !valid_len || !all_hex {
            out.warnings.push(format!(
                "[admin] primary_color = `{hex}` does not parse as a hex color (expected \
                 `#RRGGBB`, `#RGB`, or `#RRGGBBAA`) — the theme will fall back to the default \
                 accent. Check for a missing leading `#` or non-hex characters."
            ));
        }
    }

    // theme_mode allowlist — typo-detection.
    if let Some(mode) = admin.theme_mode.as_deref() {
        if !matches!(mode, "auto" | "light" | "dark") {
            out.warnings.push(format!(
                "[admin] theme_mode = `{mode}` is not one of `auto` / `light` / `dark` — \
                 the chrome will ignore it and fall back to `auto`."
            ));
        }
    }

    // session_timeout_minutes = 0 in prod means no idle expiry — info-flag
    // (some deploys want this deliberately for kiosks etc.).
    if matches!(admin.session_timeout_minutes, Some(0)) {
        out.info.push(
            "[admin] session_timeout_minutes = 0 in prod tier — admin sessions never idle-expire. \
             Confirm this is deliberate (kiosk / single-user setup); otherwise pick a non-zero \
             value so abandoned sessions can't be hijacked."
                .into(),
        );
    }

    // url_prefix smell tests — trailing slash trips up some
    // template hrefs; root-mount empty string is legal but worth
    // info-flagging since it conflicts with most reverse proxies.
    if let Some(prefix) = admin.url_prefix.as_deref() {
        if prefix.ends_with('/') && prefix.len() > 1 {
            out.warnings.push(format!(
                "[admin] url_prefix = `{prefix}` ends with a trailing slash — Builder will \
                 strip it, but config files should write the canonical form (no trailing slash) \
                 so reviewers can grep across deployments."
            ));
        }
    }
}

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

    #[test]
    fn pascal_to_snake_cases() {
        assert_eq!(pascal_to_snake("Post"), "post");
        assert_eq!(pascal_to_snake("PostViewSet"), "post_view_set");
        assert_eq!(pascal_to_snake("API"), "a_p_i"); // simple impl — acceptable
        assert_eq!(pascal_to_snake("UserNotification"), "user_notification");
    }

    #[test]
    fn is_valid_type_name_accepts_pascal() {
        assert!(is_valid_type_name("Post"));
        assert!(is_valid_type_name("PostViewSet"));
        assert!(is_valid_type_name("Foo_Bar"));
    }

    #[test]
    fn is_valid_type_name_rejects_invalid() {
        assert!(!is_valid_type_name(""));
        assert!(!is_valid_type_name("post")); // lowercase
        assert!(!is_valid_type_name("123Foo")); // starts with digit
        assert!(!is_valid_type_name("Post!")); // bad char
    }

    #[test]
    fn parse_name_and_model_basic() {
        let (n, m) = parse_name_and_model(&["PostViewSet".into()]).unwrap();
        assert_eq!(n, "PostViewSet");
        assert_eq!(m, None);
    }

    #[test]
    fn parse_name_and_model_with_model_flag() {
        let args: Vec<String> = vec!["PostViewSet".into(), "--model".into(), "Post".into()];
        let (n, m) = parse_name_and_model(&args).unwrap();
        assert_eq!(n, "PostViewSet");
        assert_eq!(m, Some("Post".into()));
    }

    #[test]
    fn parse_name_and_model_rejects_missing_name() {
        let r = parse_name_and_model(&[]);
        assert!(r.is_err());
    }

    #[test]
    fn parse_name_and_model_rejects_lowercase_name() {
        let r = parse_name_and_model(&["postviewset".into()]);
        assert!(r.is_err());
    }

    /// Default template (no `--tenant`) keeps the v0.28
    /// `#[derive(ViewSet)]` shape — single-tenant projects rely on
    /// the mount-time `pool` argument.
    #[test]
    fn viewset_template_pool_emits_derive_macro() {
        let body = viewset_template_pool("PostViewSet", "Post", "post_view_set");
        assert!(
            body.contains("#[derive(ViewSet)]"),
            "expected derive macro, got: {body}"
        );
        assert!(
            body.contains("PostViewSet::router"),
            "expected `Name::router(...)` mount hint, got: {body}"
        );
        assert!(
            !body.contains("tenant_router"),
            "pool template must NOT reference tenant_router, got: {body}"
        );
    }

    /// `--tenant` template uses `ViewSet::for_model(...).tenant_router(...)`
    /// and pulls `crate::extractors::Tenant`-shape connections instead
    /// of baking a pool at mount time. Required for tenancy projects
    /// (#80).
    #[test]
    fn viewset_template_tenant_uses_tenant_router() {
        let body = viewset_template_tenant("PostViewSet", "Post", "post_view_set");
        assert!(
            body.contains("ViewSet::for_model"),
            "expected runtime ViewSet::for_model builder, got: {body}"
        );
        assert!(
            body.contains(".tenant_router("),
            "expected `.tenant_router(...)` call, got: {body}"
        );
        assert!(
            !body.contains("#[derive(ViewSet)]"),
            "tenant template must NOT use the derive macro (pool-coupled), got: {body}"
        );
        assert!(
            body.contains("/api/post_view_set"),
            "expected snake-cased path, got: {body}"
        );
        // The hint comment in the template should match the actual
        // function call site Devs will copy from it.
        assert!(
            body.contains("pub fn router()"),
            "expected `pub fn router()` so api_routes.rs can `.merge(...)`, got: {body}"
        );
        // v0.30.5 — the scaffolded body must demonstrate the v0.30
        // unified builder chain (filter / search / ordering / page /
        // perms) so users discover the surface without reading the
        // docs. Stale "v1 scope" caveat must NOT appear.
        assert!(
            !body.contains("v1 scope"),
            "v0.30 unification removed the v1 scope caveat — \
             template must reflect full feature parity, got: {body}"
        );
        for knob in [
            ".filter_fields(",
            ".search_fields(",
            ".ordering(",
            ".page_size(",
            ".permissions_for_model::",
        ] {
            assert!(
                body.contains(knob),
                "expected `{knob}` in tenant template (commented hint), got: {body}"
            );
        }
    }

    /// CWD is process-global; tests that chdir must be serialized
    /// or `cargo test`'s default thread-pool will race them and
    /// trip "No such file or directory" when one test's tempdir
    /// drop runs while another is restoring CWD. This static
    /// mutex serializes every chdir-based test in this module.
    fn cwd_lock() -> &'static std::sync::Mutex<()> {
        static LOCK: std::sync::OnceLock<std::sync::Mutex<()>> = std::sync::OnceLock::new();
        LOCK.get_or_init(|| std::sync::Mutex::new(()))
    }

    /// `project_uses_tenancy` reads Cargo.toml from CWD and looks for
    /// the `tenancy` feature on the `rustango` dep. Tested by
    /// pushing a fixture file into a tempdir, chdir-ing in, and
    /// asserting the result.
    #[test]
    fn project_uses_tenancy_detects_inline_features_array() {
        let _guard = cwd_lock().lock().unwrap_or_else(|p| p.into_inner());
        let dir = tempfile::tempdir().unwrap();
        let cargo = dir.path().join("Cargo.toml");
        std::fs::write(
            &cargo,
            r#"[package]
name = "demo"
version = "0.1.0"
edition = "2021"

[dependencies]
rustango = { version = "0.30", features = ["tenancy", "manage"] }
"#,
        )
        .unwrap();
        let prev = std::env::current_dir().unwrap();
        std::env::set_current_dir(dir.path()).unwrap();
        let detected = project_uses_tenancy();
        let _ = std::env::set_current_dir(&prev);
        assert!(
            detected,
            "inline-table dep with `tenancy` in features should auto-detect"
        );
    }

    /// `project_uses_tenancy` returns false on the dedicated dep
    /// table form when `tenancy` isn't listed.
    #[test]
    fn project_uses_tenancy_false_when_feature_absent() {
        let _guard = cwd_lock().lock().unwrap_or_else(|p| p.into_inner());
        let dir = tempfile::tempdir().unwrap();
        let cargo = dir.path().join("Cargo.toml");
        std::fs::write(
            &cargo,
            r#"[package]
name = "demo"
version = "0.1.0"
edition = "2021"

[dependencies]
rustango = { version = "0.30", features = ["postgres", "manage"] }
"#,
        )
        .unwrap();
        let prev = std::env::current_dir().unwrap();
        std::env::set_current_dir(dir.path()).unwrap();
        let detected = project_uses_tenancy();
        let _ = std::env::set_current_dir(&prev);
        assert!(
            !detected,
            "no tenancy feature → must default to single-tenant scaffold"
        );
    }

    /// Missing Cargo.toml (running outside a project) → false.
    /// Scaffolder must not crash; auto-detect just falls back to
    /// the safer single-tenant default.
    #[test]
    fn project_uses_tenancy_false_when_cargo_toml_missing() {
        let _guard = cwd_lock().lock().unwrap_or_else(|p| p.into_inner());
        let dir = tempfile::tempdir().unwrap();
        let prev = std::env::current_dir().unwrap();
        std::env::set_current_dir(dir.path()).unwrap();
        let detected = project_uses_tenancy();
        let _ = std::env::set_current_dir(&prev);
        assert!(!detected);
    }

    /// `resolve_viewset_tenant_mode` is the pure decision the
    /// `make:viewset` command runs after parsing flags. Tested as
    /// a pure function so we don't need chdir + tempdir + writing
    /// to a project tree (which earlier leaked test artifacts when
    /// parallel tests raced on CWD).
    ///
    /// Echo fires only on the implicit-auto-detect path; explicit
    /// `--tenant` / `--no-tenant` users already know what they
    /// asked for.
    #[test]
    fn resolve_viewset_tenant_mode_decision_table() {
        // (explicit_tenant, explicit_no_tenant, project_tenancy)
        // → (tenant_aware, echo)
        let cases: &[(bool, bool, bool, bool, bool)] = &[
            // No flags, no tenancy detected → pool, no echo.
            (false, false, false, false, false),
            // No flags, tenancy detected → tenant + echo.
            (false, false, true, true, true),
            // Explicit --tenant, no tenancy detected → tenant, no echo.
            (true, false, false, true, false),
            // Explicit --tenant, tenancy detected → tenant, no echo
            // (the user asked for it, no need to inform).
            (true, false, true, true, false),
            // Explicit --no-tenant always wins → pool, no echo.
            (false, true, false, false, false),
            (false, true, true, false, false),
            // Both flags set: --no-tenant is the safer default and
            // takes precedence (the function checks it first).
            (true, true, true, false, false),
        ];
        for &(et, ent, pt, want_tenant, want_echo) in cases {
            let (tenant, echo) = resolve_viewset_tenant_mode(et, ent, pt);
            assert_eq!(
                (tenant, echo),
                (want_tenant, want_echo),
                "case (explicit_tenant={et}, explicit_no_tenant={ent}, project_tenancy={pt})"
            );
        }
    }

    // -------- make:api_routes (#82-partial) --------

    /// Tenancy template emits the no-arg `pub fn api()` shape and
    /// references `tenant_router` in the placeholder hint.
    #[test]
    fn api_routes_template_tenant_emits_no_arg_fn() {
        let body = api_routes_template_tenant("regions");
        assert!(
            body.contains("pub fn api() -> Router<()>"),
            "expected no-arg `pub fn api()`, got: {body}"
        );
        assert!(
            body.contains("tenant_router("),
            "expected tenant_router hint comment, got: {body}"
        );
        assert!(
            !body.contains("PgPool"),
            "tenant template must NOT thread PgPool through api(), got: {body}"
        );
    }

    /// Default template threads `PgPool` so per-model derived
    /// viewsets have something to capture at mount time.
    #[test]
    fn api_routes_template_pool_threads_pgpool() {
        let body = api_routes_template_pool("blog");
        assert!(
            body.contains("pub fn api(pool: PgPool) -> Router<()>"),
            "expected pool-arg api fn, got: {body}"
        );
        assert!(
            body.contains("use rustango::sql::sqlx::PgPool;"),
            "expected PgPool import, got: {body}"
        );
    }

    /// App-name validator accepts snake_case and rejects hyphens /
    /// uppercase / leading digits — same rule we apply to table
    /// names in the macro. Keeps `src/<app>/` shape Rust-friendly.
    #[test]
    fn is_valid_app_name_snake_case_only() {
        assert!(is_valid_app_name("regions"));
        assert!(is_valid_app_name("blog_posts"));
        assert!(is_valid_app_name("_internal"));
        assert!(!is_valid_app_name(""));
        assert!(!is_valid_app_name("Regions"));
        assert!(!is_valid_app_name("region-app"));
        assert!(!is_valid_app_name("9_apps"));
    }

    // -------- run_deploy_audit (`manage check --deploy`) --------

    fn good_prod_env() -> DeployAuditEnv {
        DeployAuditEnv {
            rustango_env: Some("prod".into()),
            session_secret: Some("a".repeat(48)),
            database_url: Some("postgres://app:s3cr3t@db.example.com/app_prod".into()),
            apex_domain: Some("app.example.com".into()),
            bind: Some("0.0.0.0:8080".into()),
        }
    }

    fn run(env: &DeployAuditEnv) -> DeployAuditFindings {
        let mut out = DeployAuditFindings::default();
        run_deploy_audit(env, &mut out);
        out
    }

    #[test]
    fn deploy_audit_clean_prod_env_has_no_warnings_or_errors() {
        let r = run(&good_prod_env());
        assert!(
            r.errors.is_empty(),
            "expected no errors in clean prod env, got: {:?}",
            r.errors
        );
        assert!(
            r.warnings.is_empty(),
            "expected no warnings in clean prod env, got: {:?}",
            r.warnings
        );
    }

    #[test]
    fn deploy_audit_unset_session_secret_errors() {
        let env = DeployAuditEnv {
            session_secret: None,
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.errors
                .iter()
                .any(|e| e.contains("RUSTANGO_SESSION_SECRET")),
            "expected error for unset RUSTANGO_SESSION_SECRET, got: {:?}",
            r.errors
        );
    }

    #[test]
    fn deploy_audit_short_session_secret_errors() {
        let env = DeployAuditEnv {
            session_secret: Some("too-short".into()),
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.errors
                .iter()
                .any(|e| e.contains("only") && e.contains("bytes")),
            "expected length error for short secret, got: {:?}",
            r.errors
        );
    }

    /// The scaffolder writes
    /// `RUSTANGO_SESSION_SECRET=change-me-base64-encoded-32-bytes-or-more`
    /// to `.env.example`. A user who copied that to `.env` and never
    /// ran `openssl rand -base64 32` should get a loud error in
    /// `--deploy` mode rather than silently shipping a known-public
    /// "secret".
    #[test]
    fn deploy_audit_placeholder_session_secret_errors() {
        let env = DeployAuditEnv {
            session_secret: Some("change-me-base64-encoded-32-bytes-or-more".into()),
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.errors
                .iter()
                .any(|e| e.contains("placeholder") || e.contains("change-me")),
            "expected error for unchanged placeholder secret, got: {:?}",
            r.errors
        );
    }

    #[test]
    fn deploy_audit_unset_rustango_env_warns() {
        let env = DeployAuditEnv {
            rustango_env: None,
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.warnings.iter().any(|w| w.contains("RUSTANGO_ENV")),
            "expected warning for unset RUSTANGO_ENV, got: {:?}",
            r.warnings
        );
    }

    #[test]
    fn deploy_audit_dev_rustango_env_warns() {
        let env = DeployAuditEnv {
            rustango_env: Some("dev".into()),
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.warnings.iter().any(|w| w.contains("`dev`")),
            "expected warning for non-prod RUSTANGO_ENV, got: {:?}",
            r.warnings
        );
    }

    #[test]
    fn deploy_audit_unset_database_url_errors() {
        let env = DeployAuditEnv {
            database_url: None,
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.errors.iter().any(|e| e.contains("DATABASE_URL")),
            "expected error for unset DATABASE_URL, got: {:?}",
            r.errors
        );
    }

    #[test]
    fn deploy_audit_localhost_database_url_warns() {
        let env = DeployAuditEnv {
            database_url: Some("postgres://app:p@localhost/db".into()),
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("DATABASE_URL") && w.contains("localhost")),
            "expected warning for localhost DATABASE_URL, got: {:?}",
            r.warnings
        );
    }

    #[test]
    fn deploy_audit_localhost_apex_warns_for_tenancy() {
        let env = DeployAuditEnv {
            apex_domain: Some("localhost".into()),
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("RUSTANGO_APEX_DOMAIN")),
            "expected warning for localhost apex, got: {:?}",
            r.warnings
        );
    }

    #[test]
    fn deploy_audit_loopback_bind_warns() {
        let env = DeployAuditEnv {
            bind: Some("127.0.0.1:8080".into()),
            ..good_prod_env()
        };
        let r = run(&env);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("RUSTANGO_BIND") && w.contains("loopback")),
            "expected warning for loopback bind, got: {:?}",
            r.warnings
        );
    }

    // -------- settings_audit_check (#87 slice 4) --------

    #[cfg(feature = "config")]
    fn settings_run(env_tier: &str, s: &crate::config::Settings) -> DeployAuditFindings {
        let mut out = DeployAuditFindings::default();
        settings_audit_check(env_tier, s, &mut out);
        out
    }

    /// In dev/staging tiers, the audit is a no-op — operators
    /// expect dev defaults to be loud only when promoted to prod.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_dev_tier_is_quiet() {
        let mut s = crate::config::Settings::default();
        s.security.headers_preset = Some("dev".into());
        s.security.hsts_max_age_secs = Some(0);
        s.auth.argon2_memory_kib = Some(1024); // dev-fast
        let r = settings_run("dev", &s);
        assert!(
            r.warnings.is_empty(),
            "dev tier should be quiet, got: {:?}",
            r.warnings
        );
        assert!(
            r.info.is_empty(),
            "dev tier should be quiet, got: {:?}",
            r.info
        );
    }

    /// In prod, `headers_preset = "dev"` is a clear footgun —
    /// emit a warning pointing at the fix.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_prod_with_dev_headers_preset_warns() {
        let mut s = crate::config::Settings::default();
        s.security.headers_preset = Some("dev".into());
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("headers_preset") && w.contains("dev")),
            "expected warning for dev headers in prod, got: {:?}",
            r.warnings
        );
    }

    /// `hsts_max_age_secs = 0` in prod disables HSTS.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_prod_with_zero_hsts_warns() {
        let mut s = crate::config::Settings::default();
        s.security.hsts_max_age_secs = Some(0);
        let r = settings_run("prod", &s);
        assert!(
            r.warnings.iter().any(|w| w.contains("hsts_max_age_secs")),
            "expected HSTS warning, got: {:?}",
            r.warnings
        );
    }

    /// argon2 below the OWASP 2024 floor warns. Default values
    /// (None) don't warn — they fall through to the framework's
    /// hardcoded sensible default.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_prod_low_argon2_warns_but_unset_is_quiet() {
        let mut s = crate::config::Settings::default();
        s.auth.argon2_memory_kib = Some(4096); // way below 19456
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("argon2_memory_kib") && w.contains("19456")),
            "expected argon2 floor warning, got: {:?}",
            r.warnings
        );

        // Unset = framework default. Quiet.
        let s_default = crate::config::Settings::default();
        let r = settings_run("prod", &s_default);
        assert!(
            !r.warnings.iter().any(|w| w.contains("argon2")),
            "default argon2 should be quiet, got: {:?}",
            r.warnings
        );
    }

    /// JWT access TTL > 1h in prod warns.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_prod_long_jwt_access_ttl_warns() {
        let mut s = crate::config::Settings::default();
        s.auth.jwt.access_ttl_secs = Some(86400); // 24h
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("access_ttl_secs") && w.contains("86400")),
            "expected access TTL warning, got: {:?}",
            r.warnings
        );
    }

    /// Loopback bind in TOML triggers the warning even when
    /// RUSTANGO_BIND env var isn't set.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_prod_loopback_bind_warns() {
        let mut s = crate::config::Settings::default();
        s.server.bind = Some("127.0.0.1:8080".into());
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("[server] bind") && w.contains("loopback")),
            "expected loopback warning, got: {:?}",
            r.warnings
        );
    }

    /// `legacy_preset = true` is a deliberate choice — info, not
    /// warning. `retention_days = None` is also info-level.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_legacy_preset_and_unset_retention_are_info() {
        let mut s = crate::config::Settings::default();
        s.routes.legacy_preset = Some(true);
        let r = settings_run("prod", &s);
        assert!(
            r.info.iter().any(|i| i.contains("legacy_preset")),
            "expected legacy_preset info, got: {:?}",
            r.info
        );
        assert!(
            r.info.iter().any(|i| i.contains("retention_days")),
            "expected retention_days info, got: {:?}",
            r.info
        );
        assert!(
            r.warnings.is_empty(),
            "neither should be warnings, got: {:?}",
            r.warnings
        );
    }

    // -------- v0.36 slice 7+10 — [admin] section audit --------

    /// `csrf_cookie_secure = false` in prod is a footgun — admin
    /// CSRF cookie sent over plain HTTP loses tamper resistance.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_admin_csrf_insecure_warns_in_prod() {
        let mut s = crate::config::Settings::default();
        s.admin.csrf_cookie_secure = Some(false);
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("[admin]") && w.contains("csrf_cookie_secure")),
            "expected CSRF secure warning, got: {:?}",
            r.warnings
        );
    }

    /// Malformed hex color trips the format check.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_admin_bad_primary_color_warns() {
        let mut s = crate::config::Settings::default();
        s.admin.primary_color = Some("not-a-color".into());
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("[admin]") && w.contains("primary_color")),
            "expected primary_color warning, got: {:?}",
            r.warnings
        );
    }

    /// Valid hex colors (3 / 6 / 8 hex digits, leading #) stay quiet.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_admin_valid_hex_color_is_quiet() {
        for hex in ["#abc", "#2c6fb0", "#2c6fb0ff"] {
            let mut s = crate::config::Settings::default();
            s.admin.primary_color = Some(hex.into());
            let r = settings_run("prod", &s);
            assert!(
                !r.warnings
                    .iter()
                    .any(|w| w.contains("[admin]") && w.contains("primary_color")),
                "expected `{hex}` to be quiet, got: {:?}",
                r.warnings
            );
        }
    }

    /// Bogus theme_mode trips the allowlist.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_admin_unknown_theme_mode_warns() {
        let mut s = crate::config::Settings::default();
        s.admin.theme_mode = Some("midnight".into());
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("[admin]") && w.contains("theme_mode")),
            "expected theme_mode warning, got: {:?}",
            r.warnings
        );
    }

    /// `session_timeout_minutes = 0` is info-level (some deploys
    /// want never-expire kiosk sessions deliberately).
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_admin_zero_session_timeout_is_info() {
        let mut s = crate::config::Settings::default();
        s.admin.session_timeout_minutes = Some(0);
        let r = settings_run("prod", &s);
        assert!(
            r.info
                .iter()
                .any(|i| i.contains("[admin]") && i.contains("session_timeout_minutes")),
            "expected session_timeout_minutes info, got: {:?}",
            r.info
        );
    }

    /// url_prefix with a trailing slash trips the canonical-form
    /// nudge (Builder strips it, but the config should be clean).
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_admin_trailing_slash_url_prefix_warns() {
        let mut s = crate::config::Settings::default();
        s.admin.url_prefix = Some("/admin/".into());
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("[admin]") && w.contains("url_prefix")),
            "expected url_prefix warning, got: {:?}",
            r.warnings
        );
    }

    /// Empty (root-mount) url_prefix stays quiet — legal, just unusual.
    #[cfg(feature = "config")]
    #[test]
    fn settings_audit_admin_empty_url_prefix_is_quiet() {
        let mut s = crate::config::Settings::default();
        s.admin.url_prefix = Some("".into());
        let r = settings_run("prod", &s);
        assert!(
            !r.warnings
                .iter()
                .any(|w| w.contains("[admin]") && w.contains("url_prefix")),
            "empty url_prefix should be quiet, got: {:?}",
            r.warnings
        );
    }

    /// v0.36 slice 9 — pairing `tenancy` feature with a non-PG backend
    /// is a misconfiguration: schema-mode tenancy needs Postgres.
    /// This test only runs when the test profile has tenancy on AND
    /// postgres is the active backend — every other feature combo
    /// makes the assertion logically unreachable.
    #[cfg(all(
        feature = "config",
        feature = "tenancy",
        feature = "postgres",
        any(feature = "sqlite", feature = "mysql"),
    ))]
    #[test]
    fn settings_audit_sqlite_backend_with_tenancy_warns_in_prod() {
        let mut s = crate::config::Settings::default();
        s.database.backend = Some("sqlite".into());
        let r = settings_run("prod", &s);
        assert!(
            r.warnings
                .iter()
                .any(|w| w.contains("[database]") && w.contains("tenancy")),
            "expected backend × tenancy warning, got: {:?}",
            r.warnings
        );
    }
}

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

    fn args(s: &[&str]) -> Vec<String> {
        s.iter().map(|x| (*x).to_owned()).collect()
    }

    // -------- parse_db_dump_args

    #[test]
    fn dump_no_flags_defaults() {
        let p = parse_db_dump_args(&[]).unwrap();
        assert!(p.out.is_none());
        assert!(!p.data_only);
        assert!(!p.schema_only);
        assert!(!p.no_owner);
    }

    #[test]
    fn dump_out_flag_with_value() {
        let p = parse_db_dump_args(&args(&["--out", "/tmp/db.sql"])).unwrap();
        assert_eq!(p.out.as_deref(), Some("/tmp/db.sql"));
    }

    #[test]
    fn dump_short_o_flag() {
        let p = parse_db_dump_args(&args(&["-o", "/tmp/db.sql"])).unwrap();
        assert_eq!(p.out.as_deref(), Some("/tmp/db.sql"));
    }

    #[test]
    fn dump_data_only_flag() {
        let p = parse_db_dump_args(&args(&["--data-only"])).unwrap();
        assert!(p.data_only);
        assert!(!p.schema_only);
    }

    #[test]
    fn dump_schema_only_flag() {
        let p = parse_db_dump_args(&args(&["--schema-only"])).unwrap();
        assert!(p.schema_only);
        assert!(!p.data_only);
    }

    #[test]
    fn dump_no_owner_flag() {
        let p = parse_db_dump_args(&args(&["--no-owner"])).unwrap();
        assert!(p.no_owner);
    }

    #[test]
    fn dump_out_without_value_errors() {
        let r = parse_db_dump_args(&args(&["--out"]));
        assert!(r.is_err());
    }

    #[test]
    fn dump_data_and_schema_only_conflict() {
        let r = parse_db_dump_args(&args(&["--data-only", "--schema-only"]));
        assert!(r.is_err());
    }

    #[test]
    fn dump_unknown_flag_errors() {
        let r = parse_db_dump_args(&args(&["--bogus"]));
        assert!(r.is_err());
    }

    // -------- build_pg_dump_argv

    #[test]
    fn dump_argv_contains_url_first() {
        let parsed = DbDumpArgs {
            out: None,
            data_only: false,
            schema_only: false,
            no_owner: false,
        };
        let argv = build_pg_dump_argv(&parsed, "postgres://u:p@h/db");
        assert_eq!(argv[0], "postgres://u:p@h/db");
    }

    #[test]
    fn dump_argv_includes_chosen_flags() {
        let parsed = DbDumpArgs {
            out: Some("/tmp/x.sql".into()),
            data_only: true,
            schema_only: false,
            no_owner: true,
        };
        let argv = build_pg_dump_argv(&parsed, "postgres://u:p@h/db");
        assert!(argv.contains(&"--data-only".to_owned()));
        assert!(argv.contains(&"--no-owner".to_owned()));
        assert!(argv.contains(&"--file".to_owned()));
        assert!(argv.contains(&"/tmp/x.sql".to_owned()));
        assert!(!argv.contains(&"--schema-only".to_owned()));
    }

    // -------- parse_db_restore_args

    #[test]
    fn restore_requires_file() {
        let r = parse_db_restore_args(&[]);
        assert!(r.is_err());
    }

    #[test]
    fn restore_positional_file() {
        let p = parse_db_restore_args(&args(&["/tmp/db.sql"])).unwrap();
        assert_eq!(p.file, "/tmp/db.sql");
        assert!(!p.clean);
    }

    #[test]
    fn restore_with_clean_flag() {
        let p = parse_db_restore_args(&args(&["--clean", "/tmp/db.sql"])).unwrap();
        assert!(p.clean);
        assert_eq!(p.file, "/tmp/db.sql");
    }

    #[test]
    fn restore_clean_after_file() {
        let p = parse_db_restore_args(&args(&["/tmp/db.sql", "--clean"])).unwrap();
        assert!(p.clean);
    }

    #[test]
    fn restore_two_files_errors() {
        let r = parse_db_restore_args(&args(&["a.sql", "b.sql"]));
        assert!(r.is_err());
    }

    // -------- build_psql_argv

    #[test]
    fn restore_argv_includes_on_error_stop() {
        let parsed = DbRestoreArgs {
            file: "/tmp/x.sql".into(),
            clean: false,
        };
        let argv = build_psql_argv(&parsed, "postgres://u:p@h/db");
        // ON_ERROR_STOP=1 prevents psql from continuing past errors
        // and silently "succeeding" with a half-restored DB.
        assert!(argv.contains(&"ON_ERROR_STOP=1".to_owned()));
        assert!(argv.contains(&"-f".to_owned()));
        assert!(argv.contains(&"/tmp/x.sql".to_owned()));
        assert!(!argv.iter().any(|a| a.contains("DROP SCHEMA")));
    }

    #[test]
    fn restore_argv_with_clean_drops_schema() {
        let parsed = DbRestoreArgs {
            file: "/tmp/x.sql".into(),
            clean: true,
        };
        let argv = build_psql_argv(&parsed, "postgres://u:p@h/db");
        assert!(argv.iter().any(|a| a.contains("DROP SCHEMA")));
        assert!(argv.iter().any(|a| a.contains("CREATE SCHEMA")));
    }

    // -------- redact_url

    #[test]
    fn redact_masks_password_in_postgres_url() {
        assert_eq!(
            redact_url("postgres://alice:supersecret@localhost:5432/mydb"),
            "postgres://alice:***@localhost:5432/mydb"
        );
    }

    #[test]
    fn redact_passes_through_url_without_credentials() {
        assert_eq!(
            redact_url("postgres://localhost:5432/mydb"),
            "postgres://localhost:5432/mydb"
        );
    }

    #[test]
    fn redact_passes_through_non_urls() {
        assert_eq!(redact_url("--data-only"), "--data-only");
        assert_eq!(redact_url("/tmp/db.sql"), "/tmp/db.sql");
    }

    #[test]
    fn redact_handles_url_with_only_user() {
        // No colon → no password to redact → pass through.
        assert_eq!(
            redact_url("postgres://alice@localhost/db"),
            "postgres://alice@localhost/db"
        );
    }
}