omni_dev/cli/

drive.rs

//! Drive CLI commands.

pub(crate) mod account;
pub(crate) mod auth;
pub(crate) mod create;
pub(crate) mod dedupe;
pub(crate) mod docs;
pub(crate) mod edit;
pub(crate) mod format;
pub(crate) mod helpers;
pub(crate) mod lease;
/// `drive move` — named `move_file` (not `move`, a Rust keyword) mirroring
/// `crate::cli::atlassian::confluence::move_page`'s identical workaround.
pub(crate) mod move_file;
pub(crate) mod permissions;
pub(crate) mod read;
pub(crate) mod rename;
pub(crate) mod search;
pub(crate) mod sheets;
pub(crate) mod upload;

use anyhow::Result;
use clap::{Parser, Subcommand};

use crate::drive::account::DRIVE_ACCOUNT_ENV;
use crate::drive::client::DriveClient;

/// Drive: search, read, rename, and move Google Drive files via OAuth2.
#[derive(Parser)]
pub struct DriveCommand {
    /// Selects a named Drive account configured in
    /// `~/.omni-dev/settings.json` (AWS-CLI style, mirrors the top-level
    /// `--profile`) for this invocation.
    ///
    /// Orthogonal to `--profile`: switching the Drive account never changes
    /// which profile is active, and vice versa (see
    /// [ADR-0066](../../../docs/adrs/adr-0066.md),
    /// [ADR-0069](../../../docs/adrs/adr-0069.md)). Overrides
    /// `OMNI_DEV_DRIVE_ACCOUNT`. Scoped to the `drive` subtree — not usable
    /// before the `drive` subcommand name, only after it, so it can't
    /// collide with an unrelated subcommand's own `--account` flag.
    #[arg(long, global = true, value_name = "NAME")]
    pub account: Option<String>,
    /// The Drive subcommand to execute.
    #[command(subcommand)]
    pub command: DriveSubcommands,
}

/// Drive subcommands.
#[derive(Subcommand)]
pub enum DriveSubcommands {
    /// Manages Drive OAuth2 credentials.
    Auth(auth::AuthCommand),
    /// Manages named Drive accounts.
    Account(account::AccountCommand),
    /// Searches Drive files.
    Search(search::SearchCommand),
    /// Reads a single Drive file's metadata or content.
    Read(read::ReadCommand),
    /// Finds Drive files sharing the same content hash.
    Dedupe(dedupe::DedupeCommand),
    /// Creates a new file or folder, gated by the folder write-permission
    /// rules (issue #1574). Requires the `drive.file` or `drive` scope
    /// (`drive auth login --write-file`/`--write-full`).
    Create(create::CreateCommand),
    /// Uploads local content as a new file, gated by the folder
    /// write-permission rules (issue #1574). Requires the `drive.file` or
    /// `drive` scope (`drive auth login --write-file`/`--write-full`).
    Upload(upload::UploadCommand),
    /// Replaces an existing file's content, gated by the
    /// write-permission rules (issues #1574, #1612). Requires the `drive.file`
    /// scope if `omni-dev` created the file, or the unrestricted `drive`
    /// scope for any pre-existing file (`drive auth login --write-file`
    /// or `--write-full`).
    Edit(edit::EditCommand),
    /// Backs up a file and mints a Touch ID-authorised lease token,
    /// required by `drive edit` and (in later phases) every other
    /// content-mutating verb ([ADR-0080](../../docs/adrs/adr-0080.md)).
    Lease(lease::LeaseCommand),
    /// Renames a single Drive file. Requires the `drive.metadata` scope
    /// (`drive auth login --write`).
    Rename(rename::RenameCommand),
    /// Moves one or more Drive files into a destination folder. Requires
    /// the `drive.metadata` scope (`drive auth login --write`).
    Move(move_file::MoveCommand),
    /// Inspects the write-permission rules gating `drive
    /// create`/`upload`/`edit`, `drive sheets
    /// write`/`append`/`clear`/`create` and `drive docs
    /// replace`/`append`/`create` (issues #1574, #1589, #1612, #1615).
    Permissions(permissions::PermissionsCommand),
    /// Reads the structure and text of a Google Doc via the Docs v1 API
    /// (issue #1615).
    Docs(docs::DocsCommand),
    /// Reads and writes the cells of a Google Sheet via the Sheets v4 API
    /// (issue #1589).
    Sheets(sheets::SheetsCommand),
}

impl DriveCommand {
    /// Executes the Drive command. `auth`/`account` must run without a
    /// resolved client (they manage credentials/account selection);
    /// `Permissions` and `Lease` resolve their own client lazily, per leaf
    /// (see the comments below); every other subcommand resolves one
    /// shared client **once** here and threads it down via
    /// [`DriveSubcommands::dispatch`].
    pub async fn execute(self) -> Result<()> {
        // Propagates --account to DRIVE_ACCOUNT_ENV for the duration of this
        // call only (crate::drive::account::resolve_account reads it),
        // mirroring GmailCommand::execute. Set *before* matching Auth/
        // Account: those subcommands need the resolved account too (e.g.
        // `drive auth login --account work`). The guard restores the
        // ambient value (or removes the var) on drop at the end of this
        // function, so execute() is safe to call more than once per process
        // (#1538).
        let _account_guard = self
            .account
            .as_ref()
            .map(|account| crate::utils::env::ScopedEnvVar::set(DRIVE_ACCOUNT_ENV, account));

        match self.command {
            DriveSubcommands::Auth(cmd) => cmd.execute().await,
            DriveSubcommands::Account(cmd) => cmd.execute(),
            // Permissions' three leaves have mixed client needs (`show` is
            // config-only, `lookup-folder`/`check` both call the Drive
            // API) — like Auth, it resolves its own client lazily per leaf
            // rather than sharing the single eager resolution below.
            DriveSubcommands::Permissions(cmd) => cmd.execute().await,
            // `Lease`'s four leaves have mixed client needs: `acquire`/
            // `restore` always call the Drive API, `release` never does
            // (issue #1685 — it must work with no credentials at all, since
            // it's how a lease gets stood down after `drive auth logout`),
            // and `prune --dry-run` is a pure ledger read that doesn't
            // either (issue #1743). Like `Permissions`, it resolves its own
            // client lazily per leaf rather than sharing the eager
            // resolution below — `helpers::create_client` is passed as a
            // thunk so a leaf that never needs one never pays for
            // credential resolution.
            DriveSubcommands::Lease(cmd) => cmd.execute(helpers::create_client).await,
            command => {
                let client = helpers::create_client()?;
                command.dispatch(&client).await
            }
        }
    }
}

impl DriveSubcommands {
    /// Routes a non-`Auth`/`Account`/`Permissions`/`Lease` subcommand
    /// against the shared client. Those four arms are unreachable: all are
    /// handled before client resolution in [`DriveCommand::execute`].
    async fn dispatch(self, client: &DriveClient) -> Result<()> {
        match self {
            Self::Auth(_) => unreachable!("Auth is dispatched before client resolution"),
            Self::Account(_) => unreachable!("Account is dispatched before client resolution"),
            Self::Permissions(_) => {
                unreachable!("Permissions is dispatched before client resolution")
            }
            Self::Lease(_) => unreachable!("Lease is dispatched before client resolution"),
            Self::Search(cmd) => cmd.execute(client).await,
            Self::Read(cmd) => cmd.execute(client).await,
            Self::Dedupe(cmd) => cmd.execute(client).await,
            Self::Create(cmd) => cmd.execute(client).await,
            Self::Upload(cmd) => cmd.execute(client).await,
            Self::Edit(cmd) => cmd.execute(client).await,
            Self::Rename(cmd) => cmd.execute(client).await,
            Self::Move(cmd) => cmd.execute(client).await,
            Self::Docs(cmd) => cmd.execute(client).await,
            Self::Sheets(cmd) => cmd.execute(client).await,
        }
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
    use super::*;
    use crate::cli::drive::format::OutputFormat;
    use crate::drive::auth::{DriveCredentials, DriveGrantedScopes};
    use crate::utils::secret::Secret;

    fn dead_credentials() -> DriveCredentials {
        DriveCredentials {
            client_id: "client".to_string(),
            client_secret: Secret::new("secret"),
            refresh_token: Secret::new("refresh"),
            scope: DriveGrantedScopes::READONLY,
        }
    }

    fn dead_client() -> DriveClient {
        DriveClient::new("http://127.0.0.1:1", &dead_credentials()).unwrap()
    }

    /// The `StructureWriteArgs` every dispatch-routing test below wants:
    /// live (non-dry-run), no lease, table output.
    fn no_write_args() -> helpers::StructureWriteArgs {
        helpers::StructureWriteArgs {
            dry_run: false,
            lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
            output: OutputFormat::Table,
        }
    }

    #[tokio::test]
    async fn execute_routes_auth_subcommand_and_surfaces_missing_credentials() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Auth(auth::AuthCommand {
                command: auth::AuthSubcommands::Status(auth::StatusCommand { all: false }),
            }),
        };
        let err = cmd.execute().await.unwrap_err();
        assert!(err.to_string().contains("not configured"));
    }

    #[tokio::test]
    async fn execute_non_auth_subcommand_errors_when_credentials_missing() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Search(search::SearchCommand {
                query: "name contains 'report'".to_string(),
                limit: 10,
                output: OutputFormat::Table,
            }),
        };
        let err = cmd.execute().await.unwrap_err();
        assert!(err.to_string().contains("not configured"));
    }

    /// `lease release` must reach the ledger with no credentials configured
    /// (issue #1685) — it never calls the lazily-resolved client at all.
    ///
    /// Drives `LeaseCommand::run` directly rather than through
    /// `DriveCommand::execute` — this token resolves `NoSuchToken`, whose
    /// exit code is non-zero (issue #1775), and `execute` would
    /// `std::process::exit` on that, aborting the test binary. Calling
    /// `run` with a panicking client thunk is also a strictly stronger
    /// check of "never calls the lazily-resolved client" than the old
    /// indirect proxy of "would fail if it tried, since credentials are
    /// missing".
    #[tokio::test]
    async fn execute_lease_release_needs_no_credentials() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let dir = guard.clear_credentials();
        let audit = crate::test_support::AuditLogGuard::redirect(dir.path());

        let cmd = lease::LeaseCommand::release_for_test("no-such-token".to_string());
        let code = cmd
            .run(|| panic!("release must never resolve a client"))
            .await
            .unwrap();
        assert_eq!(code, 1, "NoSuchToken must be a non-zero exit");

        assert_eq!(audit.verdicts(), vec!["release-no-such-token".to_string()]);
    }

    /// `lease prune --dry-run` is a pure ledger read and must work with no
    /// credentials configured (issue #1743), the same way `release` does —
    /// it never calls the lazily-resolved client either.
    #[tokio::test]
    async fn execute_lease_prune_dry_run_needs_no_credentials() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Lease(lease::LeaseCommand::prune_for_test("1h", true)),
        };
        cmd.execute().await.unwrap();
    }

    /// `acquire` always needs the Drive API, so it still resolves a client
    /// lazily on first use and a missing credential is reported then.
    #[tokio::test]
    async fn execute_lease_acquire_still_errors_when_credentials_missing() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Lease(lease::LeaseCommand::acquire_for_test(
                "file-1".to_string(),
            )),
        };
        let err = cmd.execute().await.unwrap_err();
        assert!(err.to_string().contains("not configured"), "{err}");
    }

    #[tokio::test]
    async fn execute_restores_account_env_var_after_return() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: Some("work".to_string()),
            command: DriveSubcommands::Account(account::AccountCommand {
                command: account::AccountSubcommands::List(account::list::ListCommand {
                    output: OutputFormat::Table,
                }),
            }),
        };
        cmd.execute().await.unwrap();
        assert_eq!(std::env::var(DRIVE_ACCOUNT_ENV).ok(), None);
    }

    #[tokio::test]
    async fn execute_restores_previous_account_env_var_after_return() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();
        std::env::set_var(DRIVE_ACCOUNT_ENV, "personal");

        let cmd = DriveCommand {
            account: Some("work".to_string()),
            command: DriveSubcommands::Account(account::AccountCommand {
                command: account::AccountSubcommands::List(account::list::ListCommand {
                    output: OutputFormat::Table,
                }),
            }),
        };
        cmd.execute().await.unwrap();
        assert_eq!(
            std::env::var(DRIVE_ACCOUNT_ENV).ok().as_deref(),
            Some("personal")
        );
    }

    #[tokio::test]
    async fn execute_does_not_leak_account_across_sequential_calls() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let account_list_cmd = || DriveCommand {
            account: None,
            command: DriveSubcommands::Account(account::AccountCommand {
                command: account::AccountSubcommands::List(account::list::ListCommand {
                    output: OutputFormat::Table,
                }),
            }),
        };

        let first = DriveCommand {
            account: Some("alpha".to_string()),
            ..account_list_cmd()
        };
        first.execute().await.unwrap();
        assert_eq!(std::env::var(DRIVE_ACCOUNT_ENV).ok(), None);

        // If the first call's value had leaked, this second call — which
        // omits --account entirely — would still see it via the env var.
        account_list_cmd().execute().await.unwrap();
        assert_eq!(std::env::var(DRIVE_ACCOUNT_ENV).ok(), None);
    }

    #[tokio::test]
    async fn execute_absent_account_leaves_ambient_env_var_untouched() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();
        std::env::set_var(DRIVE_ACCOUNT_ENV, "personal");

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Account(account::AccountCommand {
                command: account::AccountSubcommands::List(account::list::ListCommand {
                    output: OutputFormat::Table,
                }),
            }),
        };
        cmd.execute().await.unwrap();
        assert_eq!(
            std::env::var(DRIVE_ACCOUNT_ENV).ok().as_deref(),
            Some("personal")
        );
    }

    #[tokio::test]
    async fn execute_routes_account_list_without_client_resolution() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Account(account::AccountCommand {
                command: account::AccountSubcommands::List(account::list::ListCommand {
                    output: OutputFormat::Table,
                }),
            }),
        };
        cmd.execute().await.unwrap();
    }

    #[tokio::test]
    async fn execute_routes_permissions_show_without_client_resolution() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Permissions(permissions::PermissionsCommand {
                command: permissions::PermissionsSubcommands::Show(
                    permissions::show::ShowCommand {
                        output: OutputFormat::Table,
                    },
                ),
            }),
        };
        cmd.execute().await.unwrap();
    }

    #[tokio::test]
    async fn execute_routes_permissions_check_and_surfaces_missing_credentials() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveCommand {
            account: None,
            command: DriveSubcommands::Permissions(permissions::PermissionsCommand {
                command: permissions::PermissionsSubcommands::Check(
                    permissions::check::CheckCommand {
                        id: "f1".to_string(),
                        operation: permissions::check::OperationArg::Read,
                        output: OutputFormat::Table,
                    },
                ),
            }),
        };
        let err = cmd.execute().await.unwrap_err();
        assert!(err.to_string().contains("not configured"));
    }

    #[tokio::test]
    async fn dispatch_routes_docs_info() {
        // Like the Sheets routing tests, this needs an env guard: a
        // `DocsClient` with no `DOCS_API_URL` set resolves the *real*
        // `docs.googleapis.com`, so without the redirect this test would
        // send a request to Google.
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Docs(docs::DocsCommand {
            command: docs::DocsSubcommands::Info(docs::info::InfoCommand {
                document_id: "d1".to_string(),
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_docs_read() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Docs(docs::DocsCommand {
            command: docs::DocsSubcommands::Read(docs::read::ReadCommand {
                document_id: "d1".to_string(),
                tab: None,
                suggestions_view: docs::read::SuggestionsViewArg::Default,
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    /// The Docs *write* verbs return `Ok(())` even when the API is
    /// unreachable, which is the exit-code convention rather than an
    /// oversight: a `Blocked`/`Failed`/`StaleRevision` outcome rides the
    /// **output**, and `$?` stays 0 (ADR-0076 §13, and ADR-0070 §10 before
    /// it). So these assert `is_ok()` — which still proves routing, since
    /// every other arm of `dispatch` would surface the dead port as an
    /// `Err` — and in doing so pin the convention itself.
    ///
    /// `clear_credentials` is what makes that deterministic: without it
    /// `active_account_rules` reads the developer's real
    /// `~/.omni-dev/settings.json`, so the result depends on the machine.
    #[tokio::test]
    async fn dispatch_routes_docs_replace() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Docs(docs::DocsCommand {
            command: docs::DocsSubcommands::Replace(docs::write::ReplaceCommand {
                document_id: "d1".to_string(),
                search: "a".to_string(),
                replace: "b".to_string(),
                ignore_case: false,
                dry_run: false,
                lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_docs_append() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Docs(docs::DocsCommand {
            command: docs::DocsSubcommands::Append(docs::write::AppendCommand {
                document_id: "d1".to_string(),
                text: Some("x".to_string()),
                text_file: None,
                dry_run: false,
                lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                output: OutputFormat::Table,
            }),
        });
        // See `dispatch_routes_docs_replace` for why this is `is_ok()`.
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_docs_create() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Docs(docs::DocsCommand {
            command: docs::DocsSubcommands::Create(docs::create::CreateCommand {
                name: "n".to_string(),
                parent: "folder-1".to_string(),
                text: None,
                text_file: None,
                dry_run: false,
                output: OutputFormat::Table,
            }),
        });
        // See `dispatch_routes_docs_replace` for why this is `is_ok()`.
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_info() {
        // Unlike every other routing test, this one needs an env guard: a
        // `SheetsClient` with no `SHEETS_API_URL` set resolves the *real*
        // `sheets.googleapis.com`, so without the redirect this test would
        // send a request to Google.
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::Info(sheets::info::InfoCommand {
                spreadsheet_id: "s1".to_string(),
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_read() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::Read(sheets::read::ReadCommand {
                spreadsheet_id: "s1".to_string(),
                range: None,
                sheet: None,
                render: sheets::read::RenderArg::Formatted,
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_write() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::Write(sheets::write::WriteCommand {
                spreadsheet_id: "s1".to_string(),
                range: Some("A1".to_string()),
                sheet: None,
                values: "/definitely/not/here.csv".to_string(),
                values_format: sheets::values::ValuesFormat::Auto,
                input: sheets::write::InputArg::UserEntered,
                dry_run: false,
                lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_append() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::Append(sheets::write::AppendCommand {
                spreadsheet_id: "s1".to_string(),
                range: Some("A1".to_string()),
                sheet: None,
                values: "/definitely/not/here.csv".to_string(),
                values_format: sheets::values::ValuesFormat::Auto,
                input: sheets::write::InputArg::UserEntered,
                dry_run: false,
                lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_clear() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::Clear(sheets::write::ClearCommand {
                spreadsheet_id: "s1".to_string(),
                range: Some("A1".to_string()),
                sheet: None,
                dry_run: false,
                lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                output: OutputFormat::Table,
            }),
        });
        // Unlike its siblings this returns `Ok`, and that is the contract,
        // not an accident: `write`/`append` fail here only because reading
        // `--values` fails *before* the engine. `clear` reaches the engine,
        // which never returns `Err` — every failure is a `WriteResult`
        // variant and the process still exits 0 (ADR-0070 §10, ADR-0071
        // §12). Scripts must inspect the output, not `$?`.
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_create() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::Create(sheets::create::CreateCommand {
                name: "Budget".to_string(),
                parent: "parent-1".to_string(),
                values: None,
                values_format: sheets::values::ValuesFormat::Auto,
                input: sheets::write::InputArg::UserEntered,
                dry_run: false,
                output: OutputFormat::Table,
            }),
        });
        // Like `clear`, this reaches the engine (no `--values` to fail
        // reading first), and `create` never returns `Err` either — every
        // failure is a `CreateResult` variant (ADR-0070 §10, ADR-0071 §12).
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_add_sheet() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::AddSheet(sheets::structure::AddSheetCommand {
                target: sheets::structure::SpreadsheetIdArg {
                    spreadsheet_id: "sheet-1".to_string(),
                },
                title: "Q3".to_string(),
                index: None,
                rows: None,
                columns: None,
                write: no_write_args(),
            }),
        });
        // Reaches the engine, which never returns `Err` — every failure is a
        // `StructureResult` variant (ADR-0073 §13).
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_rename_sheet() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::RenameSheet(
                sheets::structure::RenameSheetCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    title: "Q3".to_string(),
                    write: no_write_args(),
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_insert_rows() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::InsertRows(sheets::structure::InsertRowsCommand {
                target: sheets::structure::SpreadsheetIdArg {
                    spreadsheet_id: "sheet-1".to_string(),
                },
                sheet: "Q2".to_string(),
                at: 5,
                count: 3,
                write: no_write_args(),
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_insert_columns() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::InsertColumns(
                sheets::structure::InsertColumnsCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    at: 2,
                    count: 1,
                    write: no_write_args(),
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_move_rows() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::MoveRows(sheets::structure::MoveRowsCommand {
                target: sheets::structure::SpreadsheetIdArg {
                    spreadsheet_id: "sheet-1".to_string(),
                },
                sheet: "Q2".to_string(),
                at: 5,
                count: 3,
                before: 10,
                write: no_write_args(),
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_move_columns() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::MoveColumns(
                sheets::structure::MoveColumnsCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    at: 5,
                    count: 3,
                    before: 10,
                    write: no_write_args(),
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_move_chart() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::MoveChart(
                sheets::embedded_object::MoveChartCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    chart_id: 1,
                    sheet: None,
                    anchor: Some("F2".to_string()),
                    offset_x: None,
                    offset_y: None,
                    width: None,
                    height: None,
                    new_sheet: false,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_move_slicer() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::MoveSlicer(
                sheets::embedded_object::MoveSlicerCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    slicer_id: 1,
                    sheet: None,
                    anchor: Some("F2".to_string()),
                    offset_x: None,
                    offset_y: None,
                    width: None,
                    height: None,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_update_chart_border() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UpdateChartBorder(
                sheets::embedded_object::UpdateChartBorderCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    chart_id: 1,
                    color: Some("#4A86E8".to_string()),
                    clear: false,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_delete_sheet() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DeleteSheet(
                sheets::structure::DeleteSheetCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    write: no_write_args(),
                },
            ),
        });
        // Reaches the engine, which never returns `Err` — every failure is a
        // `StructureResult` variant (ADR-0073 §13, ADR-0077).
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_delete_rows() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DeleteRows(sheets::structure::DeleteRowsCommand {
                target: sheets::structure::SpreadsheetIdArg {
                    spreadsheet_id: "sheet-1".to_string(),
                },
                sheet: "Q2".to_string(),
                at: 5,
                count: 3,
                write: no_write_args(),
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_delete_columns() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DeleteColumns(
                sheets::structure::DeleteColumnsCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    at: 2,
                    count: 1,
                    write: no_write_args(),
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_delete_range() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DeleteRange(
                sheets::structure::DeleteRangeCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    range: sheets::structure::GridRangeArgs {
                        start_row: 2,
                        end_row: 4,
                        start_column: 2,
                        end_column: 3,
                        shift: sheets::structure::ShiftArg::Rows,
                    },
                    write: no_write_args(),
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_duplicate_sheet() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DuplicateSheet(
                sheets::structure::DuplicateSheetCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    title: Some("Q2 copy".to_string()),
                    index: None,
                    write: no_write_args(),
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_reorder_sheet() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ReorderSheet(
                sheets::structure::ReorderSheetCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    sheet: "Q2".to_string(),
                    index: 0,
                    write: no_write_args(),
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_hide_sheet() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::HideSheet(sheets::structure::HideSheetCommand {
                target: sheets::structure::SpreadsheetIdArg {
                    spreadsheet_id: "sheet-1".to_string(),
                },
                sheet: "Q2".to_string(),
                write: no_write_args(),
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_show_sheet() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ShowSheet(sheets::structure::ShowSheetCommand {
                target: sheets::structure::SpreadsheetIdArg {
                    spreadsheet_id: "sheet-1".to_string(),
                },
                sheet: "Q2".to_string(),
                write: no_write_args(),
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_update_workbook_properties() {
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UpdateWorkbookProperties(
                sheets::structure::UpdateWorkbookPropertiesCommand {
                    target: sheets::structure::SpreadsheetIdArg {
                        spreadsheet_id: "sheet-1".to_string(),
                    },
                    locale: Some("en_US".to_string()),
                    time_zone: None,
                    auto_recalc: None,
                    iterative_calculation: None,
                    iterative_calculation_max_iterations: None,
                    iterative_calculation_convergence_threshold: None,
                    write: no_write_args(),
                },
            ),
        });
        // Reaches the engine, which never returns `Err` — every failure is a
        // `StructureResult` variant (ADR-0073 §13).
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_format_cells() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::FormatCells(sheets::format::FormatCellsCommand {
                spreadsheet_id: "sheet-1".to_string(),
                range: Some("A1:B2".to_string()),
                sheet: None,
                bold: Some(true),
                italic: None,
                strikethrough: None,
                underline: None,
                font_size: None,
                text_color: None,
                background: None,
                horizontal_align: Some(sheets::format::HorizontalAlign::Center),
                vertical_align: Some(sheets::format::VerticalAlign::Middle),
                number_format: Some("#,##0.00".to_string()),
                number_format_type: Some(sheets::format::NumberFormatType::Currency),
                wrap: Some(sheets::format::WrapStrategy::Wrap),
                font_family: None,
                text_rotation_angle: None,
                text_rotation_vertical: false,
                hyperlink_display_type: None,
                padding_top: None,
                padding_right: None,
                padding_bottom: None,
                padding_left: None,
                text_direction: None,
                write: helpers::StructureWriteArgs {
                    dry_run: false,
                    lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                    output: OutputFormat::Table,
                },
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    fn base_format_cells_command() -> sheets::format::FormatCellsCommand {
        sheets::format::FormatCellsCommand {
            spreadsheet_id: "sheet-1".to_string(),
            range: Some("A1:B2".to_string()),
            sheet: None,
            bold: None,
            italic: None,
            strikethrough: None,
            underline: None,
            font_size: None,
            text_color: None,
            background: None,
            horizontal_align: None,
            vertical_align: None,
            number_format: None,
            number_format_type: None,
            wrap: None,
            font_family: None,
            text_rotation_angle: None,
            text_rotation_vertical: false,
            hyperlink_display_type: None,
            padding_top: None,
            padding_right: None,
            padding_bottom: None,
            padding_left: None,
            text_direction: None,
            write: helpers::StructureWriteArgs {
                dry_run: false,
                lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                output: OutputFormat::Table,
            },
        }
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_format_cells_text_rotation_angle() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::FormatCells(sheets::format::FormatCellsCommand {
                text_rotation_angle: Some(45),
                ..base_format_cells_command()
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_format_cells_text_rotation_vertical() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::FormatCells(sheets::format::FormatCellsCommand {
                text_rotation_vertical: true,
                ..base_format_cells_command()
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_update_borders() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UpdateBorders(
                sheets::format::UpdateBordersCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    range: Some("A1:B2".to_string()),
                    sheet: None,
                    top: true,
                    bottom: false,
                    left: false,
                    right: false,
                    all: false,
                    inner_horizontal: false,
                    inner_vertical: false,
                    style: sheets::format::BorderStyle::Dashed,
                    color: Some("#FF0000".to_string()),
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_merge_cells() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::MergeCells(sheets::format::MergeCellsCommand {
                spreadsheet_id: "sheet-1".to_string(),
                range: Some("A1:B2".to_string()),
                sheet: None,
                r#type: sheets::format::MergeType::Rows,
                dry_run: false,
                lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                output: OutputFormat::Table,
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_unmerge_cells() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UnmergeCells(sheets::format::UnmergeCellsCommand {
                spreadsheet_id: "sheet-1".to_string(),
                range: Some("A1:B2".to_string()),
                sheet: None,
                write: helpers::StructureWriteArgs {
                    dry_run: false,
                    lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                    output: OutputFormat::Table,
                },
            }),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_auto_resize_dimension() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::AutoResizeDimension(
                sheets::format::AutoResizeDimensionCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q2".to_string(),
                    dimension: sheets::format::DimensionArg::Columns,
                    start: 1,
                    end: 3,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_update_dimension_properties() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UpdateDimensionProperties(
                sheets::format::UpdateDimensionPropertiesCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q2".to_string(),
                    dimension: sheets::format::DimensionArg::Rows,
                    start: 1,
                    end: 3,
                    pixel_size: 42,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_set_data_validation() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::SetDataValidation(Box::new(
                sheets::validation::SetDataValidationCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    range: Some("A1:A10".to_string()),
                    sheet: None,
                    one_of_list: Some(vec!["yes".to_string(), "no".to_string()]),
                    one_of_range: None,
                    number_between: None,
                    number_not_between: None,
                    number_greater: None,
                    number_greater_eq: None,
                    number_less: None,
                    number_less_eq: None,
                    number_eq: None,
                    number_not_eq: None,
                    text_contains: None,
                    text_not_contains: None,
                    text_starts_with: None,
                    text_ends_with: None,
                    text_eq: None,
                    date_after: None,
                    date_before: None,
                    date_on: None,
                    date_between: None,
                    blank: false,
                    not_blank: false,
                    checkbox: false,
                    custom_formula: None,
                    input_message: Some("Pick one".to_string()),
                    show_warning: false,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            )),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_clear_data_validation() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ClearDataValidation(
                sheets::validation::ClearDataValidationCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    range: Some("A1:A10".to_string()),
                    sheet: None,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_set_developer_metadata() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::SetDeveloperMetadata(
                sheets::developer_metadata::SetDeveloperMetadataCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    key: "owner".to_string(),
                    value: "team-a".to_string(),
                    sheet: None,
                    dimension: None,
                    start: None,
                    end: None,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        // See `dispatch_routes_docs_replace` for why this is `is_ok()`: with
        // no configured account, `developer_metadata()` never returns
        // `Err` — it reports `Blocked`/`Failed` as a printed outcome.
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_delete_developer_metadata() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DeleteDeveloperMetadata(
                sheets::developer_metadata::DeleteDeveloperMetadataCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    key: "owner".to_string(),
                    sheet: None,
                    dimension: None,
                    start: None,
                    end: None,
                    dry_run: false,
                    lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                    output: OutputFormat::Table,
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_search_developer_metadata() {
        // Read-only and ungated, like `sheets info`/`list-protections` —
        // needs the host redirect so it fails fast against a dead port
        // instead of trying the real Sheets API.
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::SearchDeveloperMetadata(
                sheets::developer_metadata::SearchDeveloperMetadataCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    key: None,
                    sheet: None,
                    dimension: None,
                    start: None,
                    end: None,
                    output: OutputFormat::Table,
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_protect_range() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ProtectRange(
                sheets::protection::ProtectRangeCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    range: Some("A1:B2".to_string()),
                    sheet: None,
                    whole_sheet: false,
                    description: Some("locked".to_string()),
                    warning_only: false,
                    editors: vec!["alice@example.com".to_string()],
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_update_protection() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UpdateProtection(
                sheets::protection::UpdateProtectionCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    range: Some("A1:B2".to_string()),
                    sheet: None,
                    whole_sheet: false,
                    description: Some("still locked".to_string()),
                    warning_only: Some(true),
                    add_editors: vec!["bob@example.com".to_string()],
                    remove_editors: vec!["alice@example.com".to_string()],
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_unprotect_range() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UnprotectRange(
                sheets::protection::UnprotectRangeCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    range: Some("A1:B2".to_string()),
                    sheet: None,
                    whole_sheet: false,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_list_protections() {
        // Read-only and ungated, like `sheets info` — needs the host
        // redirect so it fails fast against a dead port instead of trying
        // the real Sheets API.
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ListProtections(
                sheets::protection::ListProtectionsCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    output: OutputFormat::Table,
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    /// A minimal `--cell-empty`-only rule (no `--background`/`--text-color`/
    /// `--bold`) so this stays a plain routing test: `conditional_format`'s
    /// own validation refuses it before any network call, and — like
    /// `ProtectRange` above — the mutating verb still reports that refusal
    /// as an `Ok` outcome rather than propagating an error, since it never
    /// reaches a dead-port network call at all.
    fn cell_empty_only_rule_args() -> sheets::conditional_format::ConditionalFormatRuleArgs {
        sheets::conditional_format::ConditionalFormatRuleArgs {
            number_between: None,
            number_not_between: None,
            number_greater: None,
            number_greater_eq: None,
            number_less: None,
            number_less_eq: None,
            number_eq: None,
            number_not_eq: None,
            text_contains: None,
            text_not_contains: None,
            text_starts_with: None,
            text_ends_with: None,
            text_eq: None,
            date_after: None,
            date_before: None,
            date_on: None,
            date_between: None,
            cell_empty: true,
            cell_not_empty: false,
            custom_formula: None,
            background: None,
            text_color: None,
            bold: None,
            gradient_min_color: None,
            gradient_max_color: None,
            gradient_mid_color: None,
            gradient_mid_type: None,
            gradient_mid_value: None,
        }
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_add_conditional_format() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::AddConditionalFormat(Box::new(
                sheets::conditional_format::AddConditionalFormatCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q1".to_string(),
                    ranges: vec!["A1:A10".to_string()],
                    index: None,
                    rule: cell_empty_only_rule_args(),
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            )),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_update_conditional_format() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UpdateConditionalFormat(Box::new(
                sheets::conditional_format::UpdateConditionalFormatCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q1".to_string(),
                    index: 0,
                    ranges: vec!["A1:A10".to_string()],
                    rule: cell_empty_only_rule_args(),
                    dry_run: false,
                    lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                    output: OutputFormat::Table,
                },
            )),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_delete_conditional_format() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DeleteConditionalFormat(
                sheets::conditional_format::DeleteConditionalFormatCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q1".to_string(),
                    index: 0,
                    dry_run: false,
                    lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                    output: OutputFormat::Table,
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_list_conditional_formats() {
        // Read-only and ungated, like `list-protections` — needs the host
        // redirect so it fails fast against a dead port instead of trying
        // the real Sheets API.
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ListConditionalFormats(
                sheets::conditional_format::ListConditionalFormatsCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    output: OutputFormat::Table,
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_set_basic_filter() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::SetBasicFilter(
                sheets::filter::SetBasicFilterCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q1".to_string(),
                    range: "A1:D10".to_string(),
                    sort_by: vec!["0:asc".to_string()],
                    hide_values: vec!["1:Closed".to_string()],
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_clear_basic_filter() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ClearBasicFilter(
                sheets::filter::ClearBasicFilterCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q1".to_string(),
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_add_filter_view() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::AddFilterView(
                sheets::filter::AddFilterViewCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    sheet: "Q1".to_string(),
                    range: "A1:D10".to_string(),
                    title: Some("Open only".to_string()),
                    sort_by: Vec::new(),
                    hide_values: Vec::new(),
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_update_filter_view() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::UpdateFilterView(
                sheets::filter::UpdateFilterViewCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    filter_view_id: 7,
                    sheet: None,
                    range: None,
                    title: Some("Renamed".to_string()),
                    sort_by: Vec::new(),
                    hide_values: Vec::new(),
                    clear_sort: false,
                    clear_criteria: false,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_delete_filter_view() {
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::DeleteFilterView(
                sheets::filter::DeleteFilterViewCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    filter_view_id: 7,
                    write: helpers::StructureWriteArgs {
                        dry_run: false,
                        lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
                        output: OutputFormat::Table,
                    },
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_sheets_list_filter_views() {
        // Read-only and ungated, like `list-protections` — needs the host
        // redirect so it fails fast against a dead port instead of trying
        // the real Sheets API.
        let guard = crate::drive::test_support::EnvGuard::take();
        guard.redirect_api_hosts_to_a_dead_port();

        let cmd = DriveSubcommands::Sheets(sheets::SheetsCommand {
            command: sheets::SheetsSubcommands::ListFilterViews(
                sheets::filter::ListFilterViewsCommand {
                    spreadsheet_id: "sheet-1".to_string(),
                    output: OutputFormat::Table,
                },
            ),
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_search() {
        let cmd = DriveSubcommands::Search(search::SearchCommand {
            query: "name contains 'x'".to_string(),
            limit: 10,
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_read() {
        let cmd = DriveSubcommands::Read(read::ReadCommand {
            file_id: "f1".to_string(),
            content: false,
            export_mime_type: None,
            out_file: None,
            verify: false,
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_dedupe() {
        let cmd = DriveSubcommands::Dedupe(dedupe::DedupeCommand {
            query: "name contains 'x'".to_string(),
            limit: 10,
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_create() {
        // Unlike rename/move (whose engine fns return `Result` and
        // propagate a network error via `?`), `create`'s engine fn always
        // returns an `Ok`-shaped `CreateOutcome` — a fetch failure against
        // the dead client becomes an embedded `Failed{detail}`, matching
        // the exit-0-regardless-of-outcome convention (ADR-0071 §12), not
        // a dispatch-level error. Needs env isolation (unlike the other
        // dispatch_routes_* tests): `create`'s CLI layer resolves the
        // active account's write_permissions.rules via `Settings::load()`,
        // so without a clean $HOME it reads whatever real
        // ~/.omni-dev/settings.json this process has.
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();

        let cmd = DriveSubcommands::Create(create::CreateCommand {
            name: "New File".to_string(),
            parent: "parent-1".to_string(),
            folder: false,
            mime_type: None,
            dry_run: false,
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_upload() {
        // Same env-isolation and exit-0-regardless-of-outcome reasoning as
        // dispatch_routes_create.
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();
        let content_dir = tempfile::tempdir().unwrap();
        let local_path = content_dir.path().join("upload-me.txt");
        std::fs::write(&local_path, b"content").unwrap();

        let cmd = DriveSubcommands::Upload(upload::UploadCommand {
            local_path,
            parent: "parent-1".to_string(),
            name: None,
            mime_type: None,
            dry_run: false,
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_edit() {
        // Same env-isolation and exit-0-regardless-of-outcome reasoning as
        // dispatch_routes_create/dispatch_routes_upload.
        let guard = crate::drive::test_support::EnvGuard::take();
        let _dir = guard.clear_credentials();
        let content_dir = tempfile::tempdir().unwrap();
        let content_path = content_dir.path().join("new-content.txt");
        std::fs::write(&content_path, b"content").unwrap();

        let cmd = DriveSubcommands::Edit(edit::EditCommand {
            file_id: "f1".to_string(),
            content: content_path.to_str().unwrap().to_string(),
            mime_type: None,
            dry_run: false,
            lease: crate::cli::drive::helpers::LeaseTokenArg { lease: None },
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_ok());
    }

    #[tokio::test]
    async fn dispatch_routes_rename() {
        let cmd = DriveSubcommands::Rename(rename::RenameCommand {
            file_id: "f1".to_string(),
            new_name: "New Name".to_string(),
            dry_run: false,
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }

    #[tokio::test]
    async fn dispatch_routes_move() {
        let cmd = DriveSubcommands::Move(move_file::MoveCommand {
            file_ids: vec!["f1".to_string()],
            to: "dest1".to_string(),
            allow_visibility_increase: false,
            allow_visibility_decrease: false,
            allow_drive_boundary_crossing: false,
            dry_run: false,
            output: OutputFormat::Table,
        });
        assert!(cmd.dispatch(&dead_client()).await.is_err());
    }
}