toko_feed_cli/

lib.rs

//! Installed operator CLI for a Toko Feed canister.
//!
//! The process boundary delegates identity and network handling to `icp`, but
//! encodes and decodes the canister protocol with shared Rust types. Users do
//! not need to write Candid arguments or interpret Candid values.

mod backup;
mod cache;

use std::{
    collections::HashSet,
    fs::{self, OpenOptions},
    io::{self, Write},
    path::PathBuf,
    process::Command,
    str::FromStr,
    sync::atomic::{AtomicU64, Ordering},
};

use candid::{CandidType, decode_one, encode_args};
use clap::{Args, Parser, Subcommand, error::ErrorKind};
use serde::{Serialize, de::DeserializeOwned};
use serde_json::{Value, json};
use thiserror::Error;
use toko_feed::{
    Collection, CollectionDetails, CollectionPage, CollectionSourcePage, CollectionSourceView,
    CuratePokemonCardMetadataArgs, FeedError, FeedStatus, IngestionRunPage, LockPokemonCardArgs,
    LockPokemonSetArgs, OperationalLogPage, PokemonCardDetails, PokemonCardMetadataDetails,
    PokemonCardPage, PokemonCardPrintingPage, PokemonCardPrintingView,
    PokemonCardReconciliationCandidate, PokemonCardReconciliationPage, PokemonCardSearchPage,
    PokemonCardSourcePage, PokemonCardSourceView, PokemonCardView, PokemonSealedDetails,
    PokemonSealedPage, PokemonSealedSourcePage, PokemonSealedSourceView, PokemonSetDetails,
    PokemonSetEvidenceView, PokemonSetPage, PokemonSetReconciliationCandidate,
    PokemonSetReconciliationPage, PokemonSetSourcePage, PokemonSetView, PokemonType,
    PriceObservationPage, Provider, ReconcilePokemonCardArgs, ReconcilePokemonCardPrintingArgs,
    ReconcilePokemonCardsArgs, ReconcilePokemonCardsReceipt, ReconcilePokemonSetArgs,
    SchedulerStatus, SealedPriceObservationPage, SetLifecycleStatus, TimeCursor,
};

use backup::DEFAULT_CANONICAL_BACKUP_PATH;
use cache::{
    DEFAULT_PROVIDER_SOURCE_PATH, DEFAULT_SCRYDEX_MAGIC_SOURCE_PATH, DEFAULT_SCRYDEX_SOURCE_PATH,
    DEFAULT_TCGDEX_SOURCE_PATH,
};

const DEFAULT_LIMIT: u16 = 20;
const DEFAULT_MAX_PAGES: usize = 1_000;
const MAX_QUERY_LIMIT: u16 = 100;
const DEFAULT_PROVIDER_COMPARISON_CARDS: u16 = 10;
const MAX_PROVIDER_SET_CARDS: u16 = 1_000;
const MAX_RECONCILIATION_SOURCES: usize = 8;
const MAX_SAFE_RECONCILIATION_CARDS: u16 = 10;
const MAX_RAW_REPLY_BYTES: usize = 16 * 1024 * 1024;
static CALL_ARGUMENT_SEQUENCE: AtomicU64 = AtomicU64::new(0);

/// Failure reported by CLI parsing, the ICP process boundary, or the typed
/// canister protocol.
#[derive(Debug, Error)]
pub enum CliError {
    /// Clap rejected the command line before any canister call was attempted.
    #[error(transparent)]
    Clap(#[from] clap::Error),
    /// Command-line arguments did not describe a valid operation.
    #[error("{0}\n\nRun with --help for usage.")]
    Usage(String),
    /// The ICP CLI process could not be started.
    #[error("could not start icp: {0}")]
    StartIcp(#[source] io::Error),
    /// The ICP CLI process reported a failed call.
    #[error("icp call failed{status}: {message}")]
    Icp {
        /// Numeric process exit status, when the platform supplied one.
        status: String,
        /// Bounded diagnostic written by the ICP CLI.
        message: String,
    },
    /// Typed Candid argument encoding failed before the process was started.
    #[error("could not encode arguments for `{method}`: {source}")]
    Encode {
        /// Canister method being prepared.
        method: &'static str,
        /// Candid codec failure.
        #[source]
        source: candid::Error,
    },
    /// The canister reply was not valid for the shared interface type.
    #[error("could not decode the typed reply from `{method}`: {source}")]
    Decode {
        /// Canister method whose reply was being decoded.
        method: &'static str,
        /// Candid codec failure.
        #[source]
        source: candid::Error,
    },
    /// The ICP CLI returned something other than one bounded hexadecimal reply.
    #[error("icp returned an invalid raw reply: {0}")]
    RawReply(&'static str),
    /// A temporary binary Candid argument file could not be prepared.
    #[error("could not prepare temporary Candid arguments: {0}")]
    ArgumentFile(#[source] io::Error),
    /// A typed application error was returned by the canister.
    #[error("canister method `{method}` returned {error}")]
    Canister {
        /// Called canister method.
        method: &'static str,
        /// Credential-free bounded application error.
        error: String,
    },
    /// A provider-set card acquisition failed after earlier cards were
    /// checkpointed successfully.
    #[error("provider `{provider}` set `{set_id}` failed at card offset {offset}: {source}")]
    ProviderCard {
        /// Provider adapter being acquired.
        provider: &'static str,
        /// Provider-owned set identifier.
        set_id: String,
        /// Zero-based card position in the provider set index.
        offset: u64,
        /// Bounded canister or transport failure.
        #[source]
        source: Box<Self>,
    },
    /// Replaying a bounded group of retained provider records failed.
    #[error(
        "provider cache replay for `{provider}` {kind} records {first_record}-{last_record}{set} failed: {source}"
    )]
    ProviderReplay {
        /// Provider adapter represented by the retained records.
        provider: String,
        /// Human-readable cache partition kind.
        kind: &'static str,
        /// Optional provider-owned set context.
        set: String,
        /// One-based first record position in this cache partition.
        first_record: usize,
        /// One-based last record position in this cache partition.
        last_record: usize,
        /// Bounded canister or transport failure.
        #[source]
        source: Box<Self>,
    },
    /// JSON input or output could not be decoded or encoded.
    #[error("could not process JSON: {0}")]
    Json(#[from] serde_json::Error),
    /// Writing the final report failed.
    #[error("could not write output: {0}")]
    Io(#[source] io::Error),
    /// Reading or atomically replacing a provider cache failed.
    #[error("could not {action} provider cache `{}`: {source}", path.display())]
    CacheIo {
        /// Filesystem operation being attempted.
        action: &'static str,
        /// Cache artifact path.
        path: PathBuf,
        /// Underlying filesystem failure.
        #[source]
        source: io::Error,
    },
    /// Writing a canonical JSON backup failed.
    #[error("could not {action} canonical backup `{}`: {source}", path.display())]
    BackupIo {
        /// Filesystem operation being attempted.
        action: &'static str,
        /// Backup path involved in the failed operation.
        path: PathBuf,
        /// Underlying filesystem failure.
        #[source]
        source: io::Error,
    },
    /// A provider cache did not satisfy its bounded format contract.
    #[error("invalid provider cache: {0}")]
    InvalidCache(String),
    /// A canister returned a continuation that had already been observed.
    #[error("pagination cursor did not advance: {0}")]
    PaginationStalled(String),
    /// Automatic pagination reached its operator-provided safety bound.
    #[error("listing still had another page after the --max-pages limit of {0}")]
    PaginationLimit(usize),
}

impl CliError {
    /// Shell exit status for this failure category.
    #[must_use]
    pub fn exit_code(&self) -> i32 {
        match self {
            Self::Clap(error) => error.exit_code(),
            Self::Usage(_) => 2,
            _ => 1,
        }
    }

    /// Whether a downstream pipeline closed standard output intentionally.
    #[must_use]
    pub fn is_broken_pipe(&self) -> bool {
        matches!(self, Self::Io(error) if error.kind() == io::ErrorKind::BrokenPipe)
    }
}

#[derive(Clone, Debug, Eq, PartialEq, Args)]
struct Target {
    /// ICP environment to use.
    #[arg(
        long,
        default_value = "local",
        value_name = "NAME",
        help_heading = "Connection"
    )]
    environment: String,
    /// Canister name or principal.
    #[arg(
        long,
        default_value = "toko-feed",
        value_name = "NAME|ID",
        help_heading = "Connection"
    )]
    canister: String,
    /// ICP identity used for calls.
    #[arg(
        long,
        default_value = "anonymous",
        value_name = "NAME",
        help_heading = "Connection"
    )]
    identity: String,
    /// Read an encrypted identity password from this file.
    #[arg(long, value_name = "PATH", help_heading = "Connection")]
    identity_password_file: Option<PathBuf>,
    /// Override ICP project discovery.
    #[arg(long, value_name = "PATH", help_heading = "Connection")]
    project_root: Option<PathBuf>,
    /// ICP CLI executable.
    #[arg(
        long,
        default_value = "icp",
        value_name = "PATH",
        help_heading = "Connection"
    )]
    icp: PathBuf,
    /// Print compact JSON.
    #[arg(long)]
    compact: bool,
}

#[derive(Debug, Parser)]
#[command(
    name = "toko-feed",
    version,
    about = "Operate and query a Toko Feed canister",
    long_about = None,
    arg_required_else_help = true
)]
struct Cli {
    #[command(flatten)]
    target: Target,
    #[command(subcommand)]
    command: RootCommand,
}

#[derive(Debug, Subcommand)]
enum RootCommand {
    /// Replay every retained provider-source cache without network access.
    Bootstrap,
    /// Back up canonical truth as tracked JSON.
    Backup(BackupArgs),
    /// Show feed configuration and cursor state.
    Status,
    /// Show durable scheduler state.
    Scheduler,
    /// Inspect ingestion run history.
    Runs(HistoryArgs),
    /// Inspect sanitized operational logs.
    Logs(HistoryArgs),
    /// Query canonical collectible collections.
    Collections(CollectionsGroup),
    /// Query or lock canonical Pokémon sets.
    Sets(SetsGroup),
    /// Query or lock canonical Pokémon cards.
    Cards(CardsGroup),
    /// Query current sealed-product projections.
    Sealed(SealedGroup),
    /// Inspect provider evidence independently of canonical truth.
    Sources(SourceKindsGroup),
    /// Acquire or replay bounded provider evidence.
    Provider(ProviderGroup),
    /// Compare provider evidence and explicitly accept canonical truth.
    Reconcile(ReconcileGroup),
}

#[derive(Debug, Args)]
struct ReconcileGroup {
    #[command(subcommand)]
    command: ReconcileCommand,
}

#[derive(Debug, Subcommand)]
enum ReconcileCommand {
    /// Reconcile set evidence without naming a provider adapter.
    Sets(ReconcileSetsGroup),
    /// Reconcile card evidence without naming a provider adapter.
    Cards(ReconcileCardsGroup),
}

#[derive(Debug, Args)]
struct ReconcileSetsGroup {
    #[command(subcommand)]
    command: ReconcileSetsCommand,
}

#[derive(Debug, Subcommand)]
enum ReconcileSetsCommand {
    /// Preview dynamically grouped provider evidence.
    Plan(ReconciliationPlanArgs),
    /// Accept one corroborated plan using its comparison key.
    AcceptSafe(MatchKeyArg),
    /// Accept selected sources with curator-supplied canonical fields.
    Accept(SetReconcileArgs),
}

#[derive(Debug, Args)]
struct ReconcileCardsGroup {
    #[command(subcommand)]
    command: ReconcileCardsCommand,
}

#[derive(Debug, Subcommand)]
enum ReconcileCardsCommand {
    /// Preview dynamically grouped evidence for one canonical set.
    Plan(CardReconciliationPlanArgs),
    /// Accept one or all bounded pages of safely corroborated cards.
    AcceptSafe(CardSafeReconcileArgs),
    /// Accept selected sources with curator-supplied canonical fields.
    Accept(CardReconcileArgs),
    /// Attach provider-specific collector variants beneath one card.
    AcceptPrinting(CardPrintingReconcileArgs),
    /// Promote one mapped provider payload into provisional structured metadata.
    AcceptMetadata(CardMetadataReconcileArgs),
}

#[derive(Debug, Args)]
struct BackupArgs {
    /// Destination for the canonical JSON snapshot.
    #[arg(long, value_name = "PATH", default_value = DEFAULT_CANONICAL_BACKUP_PATH)]
    output: PathBuf,
}

#[derive(Debug, Args)]
struct ProviderGroup {
    #[command(subcommand)]
    command: ProviderCommand,
}

#[derive(Debug, Subcommand)]
enum ProviderCommand {
    /// Replay or refresh evidence for one provider set ID.
    Set(ProviderSetArgs),
}

#[derive(Debug, Args)]
struct ProviderSetArgs {
    /// Provider name or alias, such as `just-tcg`, `tcgdex`, or `scry`.
    #[arg(value_name = "PROVIDER")]
    provider: Provider,
    /// Canonical collection name or alias, such as `pokemon`, `magic`, or `mtg`.
    #[arg(long, default_value = "pokemon", value_name = "COLLECTION")]
    collection: Collection,
    /// Provider-owned set identifier or an unambiguous display name.
    #[arg(value_name = "SET")]
    set_id: ProviderSetId,
    /// Local ignored source directory; defaults according to PROVIDER.
    #[arg(long = "source", visible_alias = "data", value_name = "PATH")]
    source: Option<PathBuf>,
    /// Refresh set metadata and acquire only card records missing from --source.
    #[arg(long)]
    refresh: bool,
    /// Number of card records to acquire for a bounded comparison sample.
    #[arg(
        long,
        conflicts_with = "all",
        value_parser = clap::value_parser!(u16).range(1..=i64::from(MAX_PROVIDER_SET_CARDS))
    )]
    cards: Option<u16>,
    /// Follow provider continuations until the complete set has been acquired.
    #[arg(long, conflicts_with = "cards")]
    all: bool,
}

fn default_provider_source(provider: Provider, collection: &str) -> PathBuf {
    match (provider, collection) {
        (Provider::JustTcg, "pokemon") => PathBuf::from(DEFAULT_PROVIDER_SOURCE_PATH),
        (Provider::JustTcg, collection) => {
            PathBuf::from(DEFAULT_PROVIDER_SOURCE_PATH).join(collection)
        }
        (Provider::TcgDex, _) => PathBuf::from(DEFAULT_TCGDEX_SOURCE_PATH),
        (Provider::Scrydex, "pokemon") => PathBuf::from(DEFAULT_SCRYDEX_SOURCE_PATH),
        (Provider::Scrydex, _) => PathBuf::from(DEFAULT_SCRYDEX_MAGIC_SOURCE_PATH),
    }
}

#[derive(Debug, Args)]
struct CollectionsGroup {
    #[command(subcommand)]
    command: CollectionsCommand,
}

#[derive(Debug, Subcommand)]
enum CollectionsCommand {
    /// List canonical collections.
    List(ListArgs),
    /// Get one canonical collection.
    Get(IdArg),
}

#[derive(Debug, Args)]
struct SetsGroup {
    #[command(subcommand)]
    command: SetsCommand,
}

#[derive(Debug, Subcommand)]
enum SetsCommand {
    /// List canonical Pokémon sets.
    List(ListArgs),
    /// Get one canonical set and its current evidence.
    Get(IdArg),
    /// Permanently lock a verified set.
    Lock(SetLockArgs),
}

#[derive(Debug, Args)]
struct CardsGroup {
    #[command(subcommand)]
    command: CardsCommand,
}

#[derive(Debug, Subcommand)]
enum CardsCommand {
    /// List canonical card identities.
    List(ListArgs),
    /// Get one card and its current provider variants.
    Get(IdArg),
    /// Permanently lock a verified card.
    Lock(CardLockArgs),
    /// Read one card's price history.
    Prices(PriceArgs),
    /// List canonical cards through the indexed Pokémon-type relation.
    ByType(CardTypeListArgs),
}

#[derive(Debug, Args)]
struct CardTypeListArgs {
    /// Canonical Pokémon type, such as Fire or Lightning.
    #[arg(value_name = "TYPE")]
    pokemon_type: PokemonType,
    #[command(flatten)]
    list: ListArgs,
}

#[derive(Debug, Args)]
struct SourceKindsGroup {
    #[command(subcommand)]
    command: SourceKindCommand,
}

#[derive(Debug, Subcommand)]
enum SourceKindCommand {
    /// Inspect provider collection mappings.
    Collections(ReadOnlySourcesGroup),
    /// Inspect or reject provider set evidence.
    Sets(ReviewableSourcesGroup),
    /// Inspect or reject provider card evidence.
    Cards(ReviewableSourcesGroup),
    /// Inspect provider sealed-product evidence.
    Sealed(ReadOnlySourcesGroup),
}

#[derive(Debug, Args)]
struct ReadOnlySourcesGroup {
    #[command(subcommand)]
    command: ReadOnlySourcesCommand,
}

#[derive(Debug, Subcommand)]
enum ReadOnlySourcesCommand {
    /// List provider source records.
    List(ListArgs),
    /// Get one provider source record.
    Get(IdArg),
}

#[derive(Debug, Args)]
struct ReviewableSourcesGroup {
    #[command(subcommand)]
    command: ReviewableSourcesCommand,
}

#[derive(Debug, Subcommand)]
enum ReviewableSourcesCommand {
    /// List provider source records.
    List(ListArgs),
    /// Get one provider source record.
    Get(IdArg),
    /// Reject one unresolved provider source record.
    Reject(IdArg),
}

#[derive(Debug, Args)]
struct SealedGroup {
    #[command(subcommand)]
    command: SealedCommand,
}

#[derive(Debug, Subcommand)]
enum SealedCommand {
    /// List sealed products.
    List(ListArgs),
    /// Get one sealed product and its current provider variants.
    Get(IdArg),
    /// Read one sealed product's price history.
    Prices(PriceArgs),
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct LocalId(String);

#[derive(Debug, Args)]
struct IdArg {
    /// Toko-owned local identifier.
    #[arg(value_name = "ULID")]
    id: LocalId,
}

#[derive(Debug, Args)]
struct ListArgs {
    /// Records requested per canister call.
    #[arg(
        long,
        default_value_t = DEFAULT_LIMIT,
        value_parser = clap::value_parser!(u16).range(1..=i64::from(MAX_QUERY_LIMIT))
    )]
    limit: u16,
    /// Start strictly after this local identifier.
    #[arg(long, value_name = "ULID")]
    after: Option<LocalId>,
    /// Follow cursors until the listing is complete.
    #[arg(long)]
    all: bool,
    /// Safety bound for --all.
    #[arg(
        long,
        default_value_t = DEFAULT_MAX_PAGES,
        value_name = "COUNT",
        requires = "all",
        value_parser = clap::builder::RangedU64ValueParser::<usize>::new().range(1..)
    )]
    max_pages: usize,
}

#[derive(Debug, Args)]
struct HistoryArgs {
    /// Records requested per canister call.
    #[arg(
        long,
        default_value_t = DEFAULT_LIMIT,
        value_parser = clap::value_parser!(u16).range(1..=i64::from(MAX_QUERY_LIMIT))
    )]
    limit: u16,
    /// Timestamp from a returned descending history cursor.
    #[arg(long, value_name = "INTEGER", requires = "before_id")]
    before_time: Option<u64>,
    /// ULID from the same descending history cursor.
    #[arg(long, value_name = "ULID", requires = "before_time")]
    before_id: Option<LocalId>,
    /// Follow cursors until the history is complete.
    #[arg(long)]
    all: bool,
    /// Safety bound for --all.
    #[arg(
        long,
        default_value_t = DEFAULT_MAX_PAGES,
        value_name = "COUNT",
        requires = "all",
        value_parser = clap::builder::RangedU64ValueParser::<usize>::new().range(1..)
    )]
    max_pages: usize,
}

#[derive(Debug, Args)]
struct ReconciliationPlanArgs {
    /// Comparison key after which the page starts.
    #[arg(long, value_name = "MATCH_KEY")]
    after: Option<String>,
    /// Candidate groups requested per canister call.
    #[arg(
        long,
        default_value_t = DEFAULT_LIMIT,
        value_parser = clap::value_parser!(u16).range(1..=i64::from(MAX_QUERY_LIMIT))
    )]
    limit: u16,
    /// Follow comparison-key cursors until the plan is complete.
    #[arg(long)]
    all: bool,
    /// Safety bound for --all.
    #[arg(
        long,
        default_value_t = DEFAULT_MAX_PAGES,
        requires = "all",
        value_parser = clap::builder::RangedU64ValueParser::<usize>::new().range(1..)
    )]
    max_pages: usize,
}

#[derive(Debug, Args)]
struct CardReconciliationPlanArgs {
    /// Toko-owned canonical set ULID.
    #[arg(long, value_name = "ULID")]
    set: LocalId,
    #[command(flatten)]
    plan: ReconciliationPlanArgs,
}

#[derive(Debug, Args)]
struct MatchKeyArg {
    /// Exact comparison key shown by `reconcile sets plan`.
    #[arg(value_name = "MATCH_KEY")]
    match_key: String,
}

#[derive(Debug, Args)]
struct SetReconcileArgs {
    /// Provider set-source ULIDs to accept as one identity.
    #[arg(long, value_name = "ULID", required = true, num_args = 1..=MAX_RECONCILIATION_SOURCES)]
    source: Vec<LocalId>,
    /// Existing canonical set to revise.
    #[arg(long, value_name = "ULID", requires = "revision")]
    set: Option<LocalId>,
    /// Expected current revision of --set.
    #[arg(long, value_name = "N", requires = "set")]
    revision: Option<u64>,
    /// Canonical set name.
    #[arg(long)]
    name: String,
    #[command(flatten)]
    release_date: ReleaseDateArgs,
    #[command(flatten)]
    lifecycle: LifecycleArgs,
}

#[derive(Debug, Args)]
struct CardReconcileArgs {
    /// Provider card-source ULIDs to accept as one identity.
    #[arg(long, value_name = "ULID", required = true, num_args = 1..=MAX_RECONCILIATION_SOURCES)]
    source: Vec<LocalId>,
    /// Existing canonical card to revise.
    #[arg(long, value_name = "ULID", requires = "revision")]
    card: Option<LocalId>,
    /// Expected current revision of --card.
    #[arg(long, value_name = "N", requires = "card")]
    revision: Option<u64>,
    /// Required canonical set relation.
    #[arg(long, value_name = "ULID")]
    set: LocalId,
    /// Canonical card name.
    #[arg(long)]
    name: String,
    /// Canonical collector number.
    #[arg(long)]
    collector_number: String,
    #[command(flatten)]
    rarity: RarityArgs,
}

#[derive(Debug, Args)]
struct CardSafeReconcileArgs {
    /// Toko-owned canonical set ULID.
    #[arg(long, value_name = "ULID")]
    set: LocalId,
    /// Comparison key after which reconciliation starts.
    #[arg(long, value_name = "MATCH_KEY")]
    after: Option<String>,
    /// Candidate groups processed per update call.
    #[arg(
        long,
        default_value_t = MAX_SAFE_RECONCILIATION_CARDS,
        value_parser = clap::value_parser!(u16).range(1..=i64::from(MAX_SAFE_RECONCILIATION_CARDS))
    )]
    limit: u16,
    /// Follow every returned continuation.
    #[arg(long)]
    all: bool,
    /// Safety bound for --all.
    #[arg(
        long,
        default_value_t = DEFAULT_MAX_PAGES,
        requires = "all",
        value_parser = clap::builder::RangedU64ValueParser::<usize>::new().range(1..)
    )]
    max_pages: usize,
}

#[derive(Debug, Args)]
struct CardPrintingReconcileArgs {
    /// Provider card-source ULIDs for this physical printing.
    #[arg(long, value_name = "ULID", required = true, num_args = 1..=MAX_RECONCILIATION_SOURCES)]
    source: Vec<LocalId>,
    /// Parent canonical card ULID.
    #[arg(long, value_name = "ULID")]
    card: LocalId,
    /// Provider collector number including the printing suffix, such as 50a.
    #[arg(long)]
    collector_number: String,
    /// Printing suffix, such as a or b.
    #[arg(long)]
    variant: String,
}

#[derive(Debug, Args)]
struct CardMetadataReconcileArgs {
    /// Parent canonical card ULID.
    #[arg(long, value_name = "ULID")]
    card: LocalId,
    /// Mapped `TCGdex` or `Scrydex` card-source ULID selected as provisional evidence.
    #[arg(long, value_name = "ULID")]
    source: LocalId,
}

#[derive(Debug, Args)]
#[group(required = true, multiple = false)]
struct RarityArgs {
    /// Curator-approved rarity.
    #[arg(long)]
    rarity: Option<String>,
    /// Explicitly record no rarity.
    #[arg(long)]
    no_rarity: bool,
}

#[derive(Debug, Args)]
#[group(required = true, multiple = false)]
struct ReleaseDateArgs {
    /// Curated release date.
    #[arg(long, value_name = "DATE")]
    release_date: Option<String>,
    /// Explicitly record no release date.
    #[arg(long)]
    no_release_date: bool,
}

#[derive(Debug, Args)]
#[group(multiple = false)]
struct LifecycleArgs {
    /// Keep the set active.
    #[arg(long)]
    active: bool,
    /// Mark the set retired.
    #[arg(long)]
    retired: bool,
}

#[derive(Debug, Args)]
struct SetLockArgs {
    /// Toko-owned canonical set identifier.
    #[arg(value_name = "ULID")]
    id: LocalId,
    /// Expected current canonical revision.
    #[arg(long, value_name = "N")]
    revision: u64,
}

#[derive(Debug, Args)]
struct CardLockArgs {
    /// Toko-owned canonical card identifier.
    #[arg(value_name = "ULID")]
    id: LocalId,
    /// Expected current canonical revision.
    #[arg(long, value_name = "N")]
    revision: u64,
}

#[derive(Debug, Args)]
struct PriceArgs {
    /// Toko-owned card or sealed-product identifier.
    #[arg(value_name = "ULID")]
    id: LocalId,
    #[command(flatten)]
    history: HistoryArgs,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum Resource {
    Collections,
    CollectionSources,
    Sets,
    SetSources,
    Cards,
    CardSources,
    Sealed,
    SealedSources,
}

impl Resource {
    const fn collection_field(self) -> &'static str {
        match self {
            Self::Collections => "collections",
            Self::Sets => "sets",
            Self::CollectionSources
            | Self::SetSources
            | Self::CardSources
            | Self::SealedSources => "sources",
            Self::Cards => "cards",
            Self::Sealed => "sealed",
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct ListOptions {
    limit: u16,
    after: Option<String>,
    all: bool,
    max_pages: usize,
}

impl Default for ListOptions {
    fn default() -> Self {
        Self {
            limit: DEFAULT_LIMIT,
            after: None,
            all: false,
            max_pages: DEFAULT_MAX_PAGES,
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct HistoryOptions {
    limit: u16,
    before: Option<TimeCursor>,
    all: bool,
    max_pages: usize,
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct ReconciliationPlanOptions {
    after: Option<String>,
    limit: u16,
    all: bool,
    max_pages: usize,
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct CardReconciliationPlanOptions {
    pokemon_set_id: String,
    plan: ReconciliationPlanOptions,
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct SafeCardReconciliationOptions {
    args: ReconcilePokemonCardsArgs,
    all: bool,
    max_pages: usize,
}

impl Default for HistoryOptions {
    fn default() -> Self {
        Self {
            limit: DEFAULT_LIMIT,
            before: None,
            all: false,
            max_pages: DEFAULT_MAX_PAGES,
        }
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
enum Action {
    Bootstrap,
    Backup(PathBuf),
    ProviderSet(ProviderSetOptions),
    Status,
    Scheduler,
    Runs(HistoryOptions),
    Logs(HistoryOptions),
    List(Resource, ListOptions),
    ListCardsByType(PokemonType, ListOptions),
    Get(Resource, String),
    LockSet(LockPokemonSetArgs),
    LockCard(LockPokemonCardArgs),
    RejectSource(Resource, String),
    Prices(Resource, String, HistoryOptions),
    PlanSets(ReconciliationPlanOptions),
    ReconcileSafeSet(String),
    ReconcileSet(ReconcilePokemonSetArgs),
    PlanCards(CardReconciliationPlanOptions),
    ReconcileSafeCards(SafeCardReconciliationOptions),
    ReconcileCard(ReconcilePokemonCardArgs),
    ReconcileCardPrinting(ReconcilePokemonCardPrintingArgs),
    ReconcileCardMetadata(CuratePokemonCardMetadataArgs),
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct ProviderSetOptions {
    provider: Provider,
    collection: String,
    set_id: String,
    source: PathBuf,
    refresh: bool,
    cards: Option<u16>,
}

struct CallArgumentFile {
    path: PathBuf,
}

impl CallArgumentFile {
    fn create(arguments: &[u8]) -> Result<Self, CliError> {
        for _ in 0..32 {
            let sequence = CALL_ARGUMENT_SEQUENCE.fetch_add(1, Ordering::Relaxed);
            let path = std::env::temp_dir().join(format!(
                "toko-feed-candid-{}-{sequence}.bin",
                std::process::id()
            ));
            let mut options = OpenOptions::new();
            options.write(true).create_new(true);
            #[cfg(unix)]
            {
                use std::os::unix::fs::OpenOptionsExt as _;
                options.mode(0o600);
            }
            let mut file = match options.open(&path) {
                Ok(file) => file,
                Err(error) if error.kind() == io::ErrorKind::AlreadyExists => continue,
                Err(error) => return Err(CliError::ArgumentFile(error)),
            };
            if let Err(source) = file.write_all(arguments) {
                let _ = fs::remove_file(&path);
                return Err(CliError::ArgumentFile(source));
            }
            return Ok(Self { path });
        }
        Err(CliError::ArgumentFile(io::Error::new(
            io::ErrorKind::AlreadyExists,
            "could not allocate a unique temporary path",
        )))
    }
}

impl Drop for CallArgumentFile {
    fn drop(&mut self) {
        let _ = fs::remove_file(&self.path);
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct Invocation {
    target: Target,
    action: Action,
}

/// Run the CLI from the current process arguments.
///
/// # Errors
///
/// Returns a bounded [`CliError`] when arguments are invalid, the `icp`
/// process fails, the canister rejects the request, or output cannot be
/// rendered.
pub fn run_from_env() -> Result<(), CliError> {
    let cli = match Cli::try_parse() {
        Ok(cli) => cli,
        Err(error) if is_clap_display(&error) => {
            return error.print().map_err(CliError::Io);
        }
        Err(error) => return Err(CliError::Clap(error)),
    };
    run(&cli.into_invocation())
}

fn run(invocation: &Invocation) -> Result<(), CliError> {
    let output = execute(invocation)?;
    let rendered = if invocation.target.compact {
        serde_json::to_string(&output)?
    } else {
        serde_json::to_string_pretty(&output)?
    };
    write_text(&format!("{rendered}\n"))
}

fn write_text(text: &str) -> Result<(), CliError> {
    io::stdout()
        .lock()
        .write_all(text.as_bytes())
        .map_err(CliError::Io)
}

fn is_clap_display(error: &clap::Error) -> bool {
    matches!(
        error.kind(),
        ErrorKind::DisplayHelp
            | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
            | ErrorKind::DisplayVersion
    )
}

#[cfg(test)]
fn parse_test_invocation(arguments: &[&str]) -> Result<Invocation, CliError> {
    let cli = Cli::try_parse_from(std::iter::once("toko-feed").chain(arguments.iter().copied()))?;
    Ok(cli.into_invocation())
}

impl Cli {
    fn into_invocation(self) -> Invocation {
        let action = self.command.into_action();
        Invocation {
            target: self.target,
            action,
        }
    }
}

impl RootCommand {
    fn into_action(self) -> Action {
        match self {
            Self::Bootstrap => Action::Bootstrap,
            Self::Backup(args) => Action::Backup(args.output),
            Self::Provider(group) => match group.command {
                ProviderCommand::Set(args) => Action::ProviderSet(args.into_options()),
            },
            Self::Reconcile(group) => match group.command {
                ReconcileCommand::Sets(group) => match group.command {
                    ReconcileSetsCommand::Plan(args) => Action::PlanSets(args.into_options()),
                    ReconcileSetsCommand::AcceptSafe(args) => {
                        Action::ReconcileSafeSet(args.match_key)
                    }
                    ReconcileSetsCommand::Accept(args) => {
                        Action::ReconcileSet(args.into_canister_args())
                    }
                },
                ReconcileCommand::Cards(group) => match group.command {
                    ReconcileCardsCommand::Plan(args) => Action::PlanCards(args.into_options()),
                    ReconcileCardsCommand::AcceptSafe(args) => {
                        Action::ReconcileSafeCards(args.into_options())
                    }
                    ReconcileCardsCommand::Accept(args) => {
                        Action::ReconcileCard(args.into_canister_args())
                    }
                    ReconcileCardsCommand::AcceptPrinting(args) => {
                        Action::ReconcileCardPrinting(args.into_canister_args())
                    }
                    ReconcileCardsCommand::AcceptMetadata(args) => {
                        Action::ReconcileCardMetadata(args.into_canister_args())
                    }
                },
            },
            Self::Status => Action::Status,
            Self::Scheduler => Action::Scheduler,
            Self::Runs(args) => Action::Runs(args.into_options()),
            Self::Logs(args) => Action::Logs(args.into_options()),
            Self::Collections(group) => match group.command {
                CollectionsCommand::List(args) => {
                    Action::List(Resource::Collections, args.into_options())
                }
                CollectionsCommand::Get(args) => Action::Get(Resource::Collections, args.id.into()),
            },
            Self::Sets(group) => match group.command {
                SetsCommand::List(args) => Action::List(Resource::Sets, args.into_options()),
                SetsCommand::Get(args) => Action::Get(Resource::Sets, args.id.into()),
                SetsCommand::Lock(args) => Action::LockSet(args.into_canister_args()),
            },
            Self::Cards(group) => match group.command {
                CardsCommand::List(args) => Action::List(Resource::Cards, args.into_options()),
                CardsCommand::Get(args) => Action::Get(Resource::Cards, args.id.into()),
                CardsCommand::Lock(args) => Action::LockCard(args.into_canister_args()),
                CardsCommand::Prices(args) => args.into_action(Resource::Cards),
                CardsCommand::ByType(args) => {
                    Action::ListCardsByType(args.pokemon_type, args.list.into_options())
                }
            },
            Self::Sealed(group) => match group.command {
                SealedCommand::List(args) => Action::List(Resource::Sealed, args.into_options()),
                SealedCommand::Get(args) => Action::Get(Resource::Sealed, args.id.into()),
                SealedCommand::Prices(args) => args.into_action(Resource::Sealed),
            },
            Self::Sources(group) => group.into_action(),
        }
    }
}

impl ProviderSetArgs {
    fn into_options(self) -> ProviderSetOptions {
        let collection = self.collection.slug().to_owned();
        let source = self
            .source
            .unwrap_or_else(|| default_provider_source(self.provider, &collection));
        ProviderSetOptions {
            provider: self.provider,
            collection,
            set_id: self.set_id.into(),
            source,
            refresh: self.refresh,
            cards: (!self.all).then_some(self.cards.unwrap_or(DEFAULT_PROVIDER_COMPARISON_CARDS)),
        }
    }
}

impl SourceKindsGroup {
    fn into_action(self) -> Action {
        match self.command {
            SourceKindCommand::Collections(group) => group.into_action(Resource::CollectionSources),
            SourceKindCommand::Sets(group) => group.into_action(Resource::SetSources),
            SourceKindCommand::Cards(group) => group.into_action(Resource::CardSources),
            SourceKindCommand::Sealed(group) => group.into_action(Resource::SealedSources),
        }
    }
}

impl ReadOnlySourcesGroup {
    fn into_action(self, resource: Resource) -> Action {
        match self.command {
            ReadOnlySourcesCommand::List(args) => Action::List(resource, args.into_options()),
            ReadOnlySourcesCommand::Get(args) => Action::Get(resource, args.id.into()),
        }
    }
}

impl ReviewableSourcesGroup {
    fn into_action(self, resource: Resource) -> Action {
        match self.command {
            ReviewableSourcesCommand::List(args) => Action::List(resource, args.into_options()),
            ReviewableSourcesCommand::Get(args) => Action::Get(resource, args.id.into()),
            ReviewableSourcesCommand::Reject(args) => {
                Action::RejectSource(resource, args.id.into())
            }
        }
    }
}

impl ListArgs {
    fn into_options(self) -> ListOptions {
        ListOptions {
            limit: self.limit,
            after: self.after.map(Into::into),
            all: self.all,
            max_pages: self.max_pages,
        }
    }
}

impl HistoryArgs {
    fn into_options(self) -> HistoryOptions {
        HistoryOptions {
            limit: self.limit,
            before: self
                .before_time
                .zip(self.before_id)
                .map(|(timestamp, id)| TimeCursor {
                    timestamp,
                    id: id.into(),
                }),
            all: self.all,
            max_pages: self.max_pages,
        }
    }
}

impl ReconciliationPlanArgs {
    fn into_options(self) -> ReconciliationPlanOptions {
        ReconciliationPlanOptions {
            after: self.after,
            limit: self.limit,
            all: self.all,
            max_pages: self.max_pages,
        }
    }
}

impl CardReconciliationPlanArgs {
    fn into_options(self) -> CardReconciliationPlanOptions {
        CardReconciliationPlanOptions {
            pokemon_set_id: self.set.into(),
            plan: self.plan.into_options(),
        }
    }
}

impl SetReconcileArgs {
    fn into_canister_args(self) -> ReconcilePokemonSetArgs {
        ReconcilePokemonSetArgs {
            source_ids: self.source.into_iter().map(Into::into).collect(),
            pokemon_set_id: self.set.map(Into::into),
            expected_revision: self.revision,
            name: self.name,
            release_date: self.release_date.release_date,
            lifecycle_status: if self.lifecycle.retired {
                SetLifecycleStatus::Retired
            } else {
                SetLifecycleStatus::Active
            },
        }
    }
}

impl CardReconcileArgs {
    fn into_canister_args(self) -> ReconcilePokemonCardArgs {
        ReconcilePokemonCardArgs {
            source_ids: self.source.into_iter().map(Into::into).collect(),
            pokemon_card_id: self.card.map(Into::into),
            expected_revision: self.revision,
            pokemon_set_id: self.set.into(),
            name: self.name,
            collector_number: self.collector_number,
            rarity: self.rarity.rarity,
        }
    }
}

impl CardSafeReconcileArgs {
    fn into_options(self) -> SafeCardReconciliationOptions {
        SafeCardReconciliationOptions {
            args: ReconcilePokemonCardsArgs {
                pokemon_set_id: self.set.into(),
                after_match_key: self.after,
                limit: self.limit,
            },
            all: self.all,
            max_pages: self.max_pages,
        }
    }
}

impl CardPrintingReconcileArgs {
    fn into_canister_args(self) -> ReconcilePokemonCardPrintingArgs {
        ReconcilePokemonCardPrintingArgs {
            source_ids: self.source.into_iter().map(Into::into).collect(),
            pokemon_card_id: self.card.into(),
            collector_number: self.collector_number,
            variant_code: self.variant,
        }
    }
}

impl CardMetadataReconcileArgs {
    fn into_canister_args(self) -> CuratePokemonCardMetadataArgs {
        CuratePokemonCardMetadataArgs {
            pokemon_card_id: self.card.into(),
            pokemon_card_source_id: self.source.into(),
        }
    }
}

impl SetLockArgs {
    fn into_canister_args(self) -> LockPokemonSetArgs {
        LockPokemonSetArgs {
            id: self.id.into(),
            expected_revision: self.revision,
        }
    }
}

impl CardLockArgs {
    fn into_canister_args(self) -> LockPokemonCardArgs {
        LockPokemonCardArgs {
            id: self.id.into(),
            expected_revision: self.revision,
        }
    }
}

impl PriceArgs {
    fn into_action(self, resource: Resource) -> Action {
        Action::Prices(resource, self.id.into(), self.history.into_options())
    }
}

impl FromStr for LocalId {
    type Err = &'static str;

    fn from_str(id: &str) -> Result<Self, Self::Err> {
        if is_valid_local_id(id) {
            Ok(Self(id.to_owned()))
        } else {
            Err("must be a 26-character uppercase ULID")
        }
    }
}

impl From<LocalId> for String {
    fn from(id: LocalId) -> Self {
        id.0
    }
}

#[derive(Clone, Debug, Eq, PartialEq)]
struct ProviderSetId(String);

impl FromStr for ProviderSetId {
    type Err = &'static str;

    fn from_str(id: &str) -> Result<Self, Self::Err> {
        let id = id.trim();
        let valid = !id.is_empty()
            && id.len() <= 256
            && !id.chars().any(char::is_control)
            && !id.contains(['/', '\\']);
        if valid {
            Ok(Self(id.to_owned()))
        } else {
            Err("must be 1-256 characters without control characters")
        }
    }
}

impl From<ProviderSetId> for String {
    fn from(id: ProviderSetId) -> Self {
        id.0
    }
}

fn is_valid_local_id(id: &str) -> bool {
    id.len() == 26
        && id.bytes().all(|byte| {
            matches!(
                byte,
                b'0'..=b'9' | b'A'..=b'H' | b'J'..=b'K' | b'M'..=b'N' | b'P'..=b'T' | b'V'..=b'Z'
            )
        })
}

fn execute(invocation: &Invocation) -> Result<Value, CliError> {
    match &invocation.action {
        Action::Bootstrap => cache::execute_bootstrap(&invocation.target),
        Action::Backup(path) => backup::execute(&invocation.target, path),
        Action::ProviderSet(options) => cache::execute_provider_set(
            &invocation.target,
            options.provider,
            &options.collection,
            &options.set_id,
            &options.source,
            options.refresh,
            options.cards,
        ),
        Action::Status => output(call_empty::<FeedStatus>(
            &invocation.target,
            "toko_feed_status",
            true,
        )?),
        Action::Scheduler => output(call_empty::<SchedulerStatus>(
            &invocation.target,
            "toko_feed_scheduler",
            true,
        )?),
        Action::Runs(options) if options.all => list_all_runs(&invocation.target, options),
        Action::Logs(options) if options.all => list_all_logs(&invocation.target, options),
        Action::Prices(resource, item_id, options) => {
            execute_prices(&invocation.target, *resource, item_id, options)
        }
        Action::Runs(options) => output(fetch_run_page(
            &invocation.target,
            options.before.clone(),
            options.limit,
        )?),
        Action::Logs(options) => output(fetch_log_page(
            &invocation.target,
            options.before.clone(),
            options.limit,
        )?),
        Action::Get(resource, id) => execute_get(&invocation.target, *resource, id),
        Action::LockSet(args) => set_mutation(&invocation.target, "toko_feed_lock_set", args),
        Action::LockCard(args) => card_mutation(&invocation.target, "toko_feed_lock_card", args),
        Action::RejectSource(resource, id) => {
            execute_reject_source(&invocation.target, *resource, id)
        }
        Action::List(resource, options) => execute_list(&invocation.target, *resource, options),
        Action::ListCardsByType(pokemon_type, options) => {
            execute_cards_by_type(&invocation.target, *pokemon_type, options)
        }
        Action::PlanSets(options) => execute_set_reconciliation_plan(&invocation.target, options),
        Action::ReconcileSafeSet(match_key) => set_mutation(
            &invocation.target,
            "toko_feed_reconcile_safe_set",
            match_key,
        ),
        Action::ReconcileSet(args) => {
            set_mutation(&invocation.target, "toko_feed_reconcile_set", args)
        }
        Action::PlanCards(options) => execute_card_reconciliation_plan(&invocation.target, options),
        Action::ReconcileSafeCards(options) => {
            execute_safe_card_reconciliation(&invocation.target, options)
        }
        Action::ReconcileCard(args) => {
            card_mutation(&invocation.target, "toko_feed_reconcile_card", args)
        }
        Action::ReconcileCardPrinting(args) => output(call_one::<_, PokemonCardPrintingView>(
            &invocation.target,
            "toko_feed_reconcile_card_printing",
            args.clone(),
            false,
        )?),
        Action::ReconcileCardMetadata(args) => output(call_one::<_, PokemonCardMetadataDetails>(
            &invocation.target,
            "toko_feed_curate_card_metadata",
            args.clone(),
            false,
        )?),
    }
}

fn execute_set_reconciliation_plan(
    target: &Target,
    options: &ReconciliationPlanOptions,
) -> Result<Value, CliError> {
    if !options.all {
        return output(fetch_set_reconciliation_page(
            target,
            options.after.clone(),
            options.limit,
        )?);
    }
    let mut cursor = options.after.clone();
    let mut candidates = Vec::<PokemonSetReconciliationCandidate>::new();
    for _ in 0..options.max_pages {
        let page = fetch_set_reconciliation_page(target, cursor.clone(), options.limit)?;
        candidates.extend(page.candidates);
        let Some(next) = page.next_after else {
            return output(PokemonSetReconciliationPage {
                candidates,
                next_after: None,
            });
        };
        ensure_cursor_advanced(cursor.as_deref(), &next)?;
        cursor = Some(next);
    }
    Err(CliError::PaginationLimit(options.max_pages))
}

fn execute_card_reconciliation_plan(
    target: &Target,
    options: &CardReconciliationPlanOptions,
) -> Result<Value, CliError> {
    if !options.plan.all {
        return output(fetch_card_reconciliation_page(
            target,
            options.pokemon_set_id.clone(),
            options.plan.after.clone(),
            options.plan.limit,
        )?);
    }
    let mut cursor = options.plan.after.clone();
    let mut candidates = Vec::<PokemonCardReconciliationCandidate>::new();
    for _ in 0..options.plan.max_pages {
        let page = fetch_card_reconciliation_page(
            target,
            options.pokemon_set_id.clone(),
            cursor.clone(),
            options.plan.limit,
        )?;
        candidates.extend(page.candidates);
        let Some(next) = page.next_after else {
            return output(PokemonCardReconciliationPage {
                candidates,
                next_after: None,
            });
        };
        ensure_cursor_advanced(cursor.as_deref(), &next)?;
        cursor = Some(next);
    }
    Err(CliError::PaginationLimit(options.plan.max_pages))
}

fn execute_safe_card_reconciliation(
    target: &Target,
    options: &SafeCardReconciliationOptions,
) -> Result<Value, CliError> {
    if !options.all {
        return output(call_one::<_, ReconcilePokemonCardsReceipt>(
            target,
            "toko_feed_reconcile_cards",
            options.args.clone(),
            false,
        )?);
    }
    let mut args = options.args.clone();
    let mut receipts = Vec::new();
    let mut cards_reconciled = 0_u64;
    let mut sources_mapped = 0_u64;
    let mut candidates_skipped = 0_u64;
    for _ in 0..options.max_pages {
        let receipt = call_one::<_, ReconcilePokemonCardsReceipt>(
            target,
            "toko_feed_reconcile_cards",
            args.clone(),
            false,
        )?;
        cards_reconciled = cards_reconciled.saturating_add(u64::from(receipt.cards_reconciled));
        sources_mapped = sources_mapped.saturating_add(u64::from(receipt.sources_mapped));
        candidates_skipped =
            candidates_skipped.saturating_add(u64::from(receipt.candidates_skipped));
        let next = receipt.next_after.clone();
        receipts.push(receipt);
        let Some(next) = next else {
            return Ok(json!({
                "cards_reconciled": cards_reconciled,
                "sources_mapped": sources_mapped,
                "candidates_skipped": candidates_skipped,
                "receipts": receipts,
            }));
        };
        ensure_cursor_advanced(args.after_match_key.as_deref(), &next)?;
        args.after_match_key = Some(next);
    }
    Err(CliError::PaginationLimit(options.max_pages))
}

fn ensure_cursor_advanced(previous: Option<&str>, next: &str) -> Result<(), CliError> {
    if previous.is_some_and(|previous| previous >= next) {
        Err(CliError::PaginationStalled(next.to_owned()))
    } else {
        Ok(())
    }
}

fn execute_reject_source(target: &Target, resource: Resource, id: &str) -> Result<Value, CliError> {
    match resource {
        Resource::SetSources => output(call_one::<_, PokemonSetEvidenceView>(
            target,
            "toko_feed_reject_set_source",
            id.to_owned(),
            false,
        )?),
        Resource::CardSources => output(call_one::<_, PokemonCardSourceView>(
            target,
            "toko_feed_reject_card_source",
            id.to_owned(),
            false,
        )?),
        _ => Err(CliError::Usage(
            "only provider source records can be rejected".to_owned(),
        )),
    }
}

fn execute_list(
    target: &Target,
    resource: Resource,
    options: &ListOptions,
) -> Result<Value, CliError> {
    if options.all {
        return match resource {
            Resource::Collections => list_all_collections(target, options),
            Resource::CollectionSources => list_all_collection_sources(target, options),
            Resource::Sets => list_all_sets(target, options),
            Resource::SetSources => list_all_set_sources(target, options),
            Resource::Cards => list_all_cards(target, options),
            Resource::CardSources => list_all_card_sources(target, options),
            Resource::Sealed => list_all_sealed(target, options),
            Resource::SealedSources => list_all_sealed_sources(target, options),
        };
    }
    match resource {
        Resource::Collections => output(fetch_collection_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
        Resource::CollectionSources => output(fetch_collection_source_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
        Resource::Sets => output(fetch_set_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
        Resource::SetSources => output(fetch_set_source_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
        Resource::Cards => output(fetch_card_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
        Resource::CardSources => output(fetch_card_source_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
        Resource::Sealed => output(fetch_sealed_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
        Resource::SealedSources => output(fetch_sealed_source_page(
            target,
            options.after.clone(),
            options.limit,
        )?),
    }
}

fn execute_cards_by_type(
    target: &Target,
    pokemon_type: PokemonType,
    options: &ListOptions,
) -> Result<Value, CliError> {
    if !options.all {
        return output(fetch_card_type_page(
            target,
            pokemon_type,
            options.after.clone(),
            options.limit,
        )?);
    }
    let (cards, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_card_type_page(target, pokemon_type, after, limit)?;
        Ok((page.cards, page.next_after))
    })?;
    Ok(json!({
        "cards": cards,
        "count": cards.len(),
        "pages": pages,
        "next_after": null,
        "pokemon_type": pokemon_type,
    }))
}

fn execute_get(target: &Target, resource: Resource, id: &str) -> Result<Value, CliError> {
    match resource {
        Resource::Collections => output(call_one::<_, Option<CollectionDetails>>(
            target,
            "toko_feed_collection",
            id.to_owned(),
            true,
        )?),
        Resource::CollectionSources => output(call_one::<_, Option<CollectionSourceView>>(
            target,
            "toko_feed_collection_source",
            id.to_owned(),
            true,
        )?),
        Resource::Sets => output(call_one::<_, Option<PokemonSetDetails>>(
            target,
            "toko_feed_set",
            id.to_owned(),
            true,
        )?),
        Resource::Cards => output(call_one::<_, Option<PokemonCardDetails>>(
            target,
            "toko_feed_card",
            id.to_owned(),
            true,
        )?),
        Resource::SetSources => output(call_one::<_, Option<PokemonSetEvidenceView>>(
            target,
            "toko_feed_set_source",
            id.to_owned(),
            true,
        )?),
        Resource::CardSources => output(call_one::<_, Option<PokemonCardSourceView>>(
            target,
            "toko_feed_card_source",
            id.to_owned(),
            true,
        )?),
        Resource::Sealed => output(call_one::<_, Option<PokemonSealedDetails>>(
            target,
            "toko_feed_sealed_product",
            id.to_owned(),
            true,
        )?),
        Resource::SealedSources => output(call_one::<_, Option<PokemonSealedSourceView>>(
            target,
            "toko_feed_sealed_source",
            id.to_owned(),
            true,
        )?),
    }
}

fn execute_prices(
    target: &Target,
    resource: Resource,
    item_id: &str,
    options: &HistoryOptions,
) -> Result<Value, CliError> {
    if options.all {
        return list_all_prices(target, resource, item_id, options);
    }
    match resource {
        Resource::Cards => output(fetch_card_price_page(
            target,
            item_id.to_owned(),
            options.before.clone(),
            options.limit,
        )?),
        Resource::Sealed => output(fetch_sealed_price_page(
            target,
            item_id.to_owned(),
            options.before.clone(),
            options.limit,
        )?),
        Resource::Collections
        | Resource::CollectionSources
        | Resource::Sets
        | Resource::SetSources
        | Resource::CardSources
        | Resource::SealedSources => Err(CliError::Usage(format!(
            "{} does not expose price history",
            resource.collection_field()
        ))),
    }
}

fn output(value: impl Serialize) -> Result<Value, CliError> {
    serde_json::to_value(value).map_err(CliError::Json)
}

fn set_mutation<A>(target: &Target, method: &'static str, args: &A) -> Result<Value, CliError>
where
    A: CandidType + Clone,
{
    output(call_one::<_, PokemonSetView>(
        target,
        method,
        args.clone(),
        false,
    )?)
}

fn card_mutation<A>(target: &Target, method: &'static str, args: &A) -> Result<Value, CliError>
where
    A: CandidType + Clone,
{
    output(call_one::<_, PokemonCardView>(
        target,
        method,
        args.clone(),
        false,
    )?)
}

fn call_empty<T>(target: &Target, method: &'static str, query: bool) -> Result<T, CliError>
where
    T: CandidType + DeserializeOwned,
{
    let arguments = encode_args(()).map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, query)
}

fn call_one<A, T>(
    target: &Target,
    method: &'static str,
    argument: A,
    query: bool,
) -> Result<T, CliError>
where
    A: CandidType,
    T: CandidType + DeserializeOwned,
{
    let arguments =
        encode_args((argument,)).map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, query)
}

fn fetch_set_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonSetPage, CliError> {
    call_page(target, "toko_feed_sets", after, limit)
}

fn fetch_collection_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<CollectionPage, CliError> {
    call_page(target, "toko_feed_collections", after, limit)
}

fn fetch_collection_source_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<CollectionSourcePage, CliError> {
    call_page(target, "toko_feed_collection_sources", after, limit)
}

fn fetch_card_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonCardPage, CliError> {
    call_page(target, "toko_feed_cards", after, limit)
}

fn fetch_card_type_page(
    target: &Target,
    pokemon_type: PokemonType,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonCardSearchPage, CliError> {
    const METHOD: &str = "toko_feed_cards_by_type";
    let arguments =
        encode_args((pokemon_type, after, limit)).map_err(|source| CliError::Encode {
            method: METHOD,
            source,
        })?;
    call_and_decode(target, METHOD, &arguments, true)
}

fn fetch_card_printing_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonCardPrintingPage, CliError> {
    call_page(target, "toko_feed_card_printings", after, limit)
}

fn fetch_set_source_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonSetSourcePage, CliError> {
    call_page(target, "toko_feed_set_sources", after, limit)
}

fn fetch_card_source_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonCardSourcePage, CliError> {
    call_page(target, "toko_feed_card_sources", after, limit)
}

fn fetch_sealed_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonSealedPage, CliError> {
    call_page(target, "toko_feed_sealed", after, limit)
}

fn fetch_sealed_source_page(
    target: &Target,
    after: Option<String>,
    limit: u16,
) -> Result<PokemonSealedSourcePage, CliError> {
    call_page(target, "toko_feed_sealed_sources", after, limit)
}

fn fetch_set_reconciliation_page(
    target: &Target,
    after_match_key: Option<String>,
    limit: u16,
) -> Result<PokemonSetReconciliationPage, CliError> {
    let method = "toko_feed_set_reconciliation";
    let arguments = encode_args((after_match_key, limit))
        .map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, true)
}

fn fetch_card_reconciliation_page(
    target: &Target,
    pokemon_set_id: String,
    after_match_key: Option<String>,
    limit: u16,
) -> Result<PokemonCardReconciliationPage, CliError> {
    let method = "toko_feed_card_reconciliation";
    let arguments = encode_args((pokemon_set_id, after_match_key, limit))
        .map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, true)
}

fn fetch_run_page(
    target: &Target,
    before: Option<TimeCursor>,
    limit: u16,
) -> Result<IngestionRunPage, CliError> {
    call_history_page(target, "toko_feed_runs", before, limit)
}

fn fetch_log_page(
    target: &Target,
    before: Option<TimeCursor>,
    limit: u16,
) -> Result<OperationalLogPage, CliError> {
    call_history_page(target, "toko_feed_logs", before, limit)
}

fn fetch_card_price_page(
    target: &Target,
    card_id: String,
    before: Option<TimeCursor>,
    limit: u16,
) -> Result<PriceObservationPage, CliError> {
    let method = "toko_feed_card_prices";
    let arguments = encode_args((card_id, before, limit))
        .map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, true)
}

fn fetch_sealed_price_page(
    target: &Target,
    sealed_id: String,
    before: Option<TimeCursor>,
    limit: u16,
) -> Result<SealedPriceObservationPage, CliError> {
    let method = "toko_feed_sealed_prices";
    let arguments = encode_args((sealed_id, before, limit))
        .map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, true)
}

fn call_history_page<T>(
    target: &Target,
    method: &'static str,
    before: Option<TimeCursor>,
    limit: u16,
) -> Result<T, CliError>
where
    T: CandidType + DeserializeOwned,
{
    let arguments =
        encode_args((before, limit)).map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, true)
}

fn call_page<T>(
    target: &Target,
    method: &'static str,
    after: Option<String>,
    limit: u16,
) -> Result<T, CliError>
where
    T: CandidType + DeserializeOwned,
{
    let arguments =
        encode_args((after, limit)).map_err(|source| CliError::Encode { method, source })?;
    call_and_decode(target, method, &arguments, true)
}

fn call_and_decode<T>(
    target: &Target,
    method: &'static str,
    arguments: &[u8],
    query: bool,
) -> Result<T, CliError>
where
    T: CandidType + DeserializeOwned,
{
    let reply = call_raw(target, method, arguments, query)?;
    decode_result(method, &reply)
}

fn decode_result<T>(method: &'static str, reply: &[u8]) -> Result<T, CliError>
where
    T: CandidType + DeserializeOwned,
{
    let result = decode_one::<Result<T, FeedError>>(reply)
        .map_err(|source| CliError::Decode { method, source })?;
    result.map_err(|error| CliError::Canister {
        method,
        error: format!("{error:?}"),
    })
}

fn call_raw(
    target: &Target,
    method: &'static str,
    arguments: &[u8],
    query: bool,
) -> Result<Vec<u8>, CliError> {
    let argument_file = CallArgumentFile::create(arguments)?;
    let mut command = Command::new(&target.icp);
    if let Some(project_root) = &target.project_root {
        command.arg("--project-root-override").arg(project_root);
    }
    if let Some(password_file) = &target.identity_password_file {
        command.arg("--identity-password-file").arg(password_file);
    }
    command
        .args(["canister", "call", "--environment"])
        .arg(&target.environment)
        .args(["--args-format", "bin", "--args-file"])
        .arg(&argument_file.path)
        .args(["--output", "hex"]);
    command.args(["--identity", &target.identity]);
    if query {
        command.arg("--query");
    }
    command.args([&target.canister, method]);

    let output = command.output().map_err(CliError::StartIcp)?;
    if !output.status.success() {
        let status = output
            .status
            .code()
            .map_or_else(String::new, |code| format!(" (exit {code})"));
        let message = bounded_diagnostic(&output.stderr);
        return Err(CliError::Icp { status, message });
    }
    if output.stdout.len() > MAX_RAW_REPLY_BYTES * 2 + 2 {
        return Err(CliError::RawReply("hexadecimal response exceeded 16 MiB"));
    }
    decode_hex(&output.stdout)
}

fn bounded_diagnostic(bytes: &[u8]) -> String {
    const MAX_DIAGNOSTIC_BYTES: usize = 8 * 1024;
    let visible = &bytes[..bytes.len().min(MAX_DIAGNOSTIC_BYTES)];
    let mut message = String::from_utf8_lossy(visible).trim().to_owned();
    if bytes.len() > MAX_DIAGNOSTIC_BYTES {
        message.push_str("…[truncated]");
    }
    if message.is_empty() {
        "no diagnostic was written to stderr".to_owned()
    } else {
        message
    }
}

#[cfg(test)]
fn encode_hex(bytes: &[u8]) -> String {
    const DIGITS: &[u8; 16] = b"0123456789abcdef";
    let mut output = String::with_capacity(bytes.len() * 2);
    for byte in bytes {
        output.push(char::from(DIGITS[usize::from(byte >> 4)]));
        output.push(char::from(DIGITS[usize::from(byte & 0x0f)]));
    }
    output
}

fn decode_hex(input: &[u8]) -> Result<Vec<u8>, CliError> {
    let input = std::str::from_utf8(input)
        .map_err(|_| CliError::RawReply("response was not UTF-8 hexadecimal text"))?
        .trim();
    let input = input.strip_prefix("0x").unwrap_or(input);
    if input.len() % 2 != 0 {
        return Err(CliError::RawReply(
            "hexadecimal response had an odd number of digits",
        ));
    }

    input
        .as_bytes()
        .chunks_exact(2)
        .map(|pair| {
            let high = hex_digit(pair[0])?;
            let low = hex_digit(pair[1])?;
            Ok((high << 4) | low)
        })
        .collect()
}

const fn hex_digit(byte: u8) -> Result<u8, CliError> {
    match byte {
        b'0'..=b'9' => Ok(byte - b'0'),
        b'a'..=b'f' => Ok(byte - b'a' + 10),
        b'A'..=b'F' => Ok(byte - b'A' + 10),
        _ => Err(CliError::RawReply(
            "response contained a non-hexadecimal character",
        )),
    }
}

fn list_all_runs(target: &Target, options: &HistoryOptions) -> Result<Value, CliError> {
    let (runs, pages) = collect_history_pages(options, |before, limit| {
        let page = fetch_run_page(target, before, limit)?;
        Ok((page.runs, page.next_before))
    })?;
    Ok(json!({
        "runs": runs,
        "count": runs.len(),
        "pages": pages,
        "next_before": null,
    }))
}

fn list_all_logs(target: &Target, options: &HistoryOptions) -> Result<Value, CliError> {
    let (logs, pages) = collect_history_pages(options, |before, limit| {
        let page = fetch_log_page(target, before, limit)?;
        Ok((page.logs, page.next_before))
    })?;
    Ok(json!({
        "logs": logs,
        "count": logs.len(),
        "pages": pages,
        "next_before": null,
    }))
}

fn list_all_prices(
    target: &Target,
    resource: Resource,
    item_id: &str,
    options: &HistoryOptions,
) -> Result<Value, CliError> {
    let (observations, pages) = match resource {
        Resource::Cards => collect_history_pages(options, |before, limit| {
            let page = fetch_card_price_page(target, item_id.to_owned(), before, limit)?;
            Ok((page.observations, page.next_before))
        })?,
        Resource::Sealed => {
            let (observations, pages) = collect_history_pages(options, |before, limit| {
                let page = fetch_sealed_price_page(target, item_id.to_owned(), before, limit)?;
                Ok((page.observations, page.next_before))
            })?;
            return Ok(json!({
                "observations": observations,
                "count": observations.len(),
                "pages": pages,
                "next_before": null,
            }));
        }
        Resource::Collections
        | Resource::CollectionSources
        | Resource::Sets
        | Resource::SetSources
        | Resource::CardSources
        | Resource::SealedSources => {
            return Err(CliError::Usage(format!(
                "{} does not expose price history",
                resource.collection_field()
            )));
        }
    };
    Ok(json!({
        "observations": observations,
        "count": observations.len(),
        "pages": pages,
        "next_before": null,
    }))
}

fn collect_history_pages<T>(
    options: &HistoryOptions,
    mut fetch: impl FnMut(Option<TimeCursor>, u16) -> Result<(Vec<T>, Option<TimeCursor>), CliError>,
) -> Result<(Vec<T>, usize), CliError> {
    let mut before = options.before.clone();
    let mut seen = before
        .as_ref()
        .map(time_cursor_token)
        .into_iter()
        .collect::<HashSet<_>>();
    let mut items = Vec::new();
    let mut pages = 0usize;
    loop {
        enforce_page_budget(pages, options.max_pages)?;
        let (page_items, next_before) = fetch(before, options.limit)?;
        pages += 1;
        items.extend(page_items);
        let Some(next_before) = next_before else {
            return Ok((items, pages));
        };
        validate_time_cursor(&next_before, &mut seen)?;
        before = Some(next_before);
    }
}

const fn enforce_page_budget(pages: usize, maximum: usize) -> Result<(), CliError> {
    if pages == maximum {
        Err(CliError::PaginationLimit(maximum))
    } else {
        Ok(())
    }
}

fn validate_time_cursor(cursor: &TimeCursor, seen: &mut HashSet<String>) -> Result<(), CliError> {
    if !is_valid_local_id(&cursor.id) {
        return Err(CliError::RawReply(
            "next_before contained an invalid local ULID",
        ));
    }
    let token = time_cursor_token(cursor);
    if !seen.insert(token.clone()) {
        return Err(CliError::PaginationStalled(token));
    }
    Ok(())
}

fn time_cursor_token(cursor: &TimeCursor) -> String {
    format!("{}:{}", cursor.timestamp, cursor.id)
}

fn list_all_sets(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (sets, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_set_page(target, after, limit)?;
        Ok((page.sets, page.next_after))
    })?;
    Ok(json!({
        "sets": sets,
        "count": sets.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn list_all_collections(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (collections, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_collection_page(target, after, limit)?;
        Ok((page.collections, page.next_after))
    })?;
    Ok(json!({
        "collections": collections,
        "count": collections.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn list_all_collection_sources(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (sources, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_collection_source_page(target, after, limit)?;
        Ok((page.sources, page.next_after))
    })?;
    Ok(json!({
        "sources": sources,
        "count": sources.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn list_all_cards(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (cards, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_card_page(target, after, limit)?;
        Ok((page.cards, page.next_after))
    })?;
    Ok(json!({
        "cards": cards,
        "count": cards.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn list_all_set_sources(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (sources, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_set_source_page(target, after, limit)?;
        Ok((page.sources, page.next_after))
    })?;
    Ok(json!({
        "sources": sources,
        "count": sources.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn list_all_card_sources(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (sources, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_card_source_page(target, after, limit)?;
        Ok((page.sources, page.next_after))
    })?;
    Ok(json!({
        "sources": sources,
        "count": sources.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn list_all_sealed(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (sealed, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_sealed_page(target, after, limit)?;
        Ok((page.sealed, page.next_after))
    })?;
    Ok(json!({
        "sealed": sealed,
        "count": sealed.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn list_all_sealed_sources(target: &Target, options: &ListOptions) -> Result<Value, CliError> {
    let (sources, pages) = collect_keyset_pages(options, |after, limit| {
        let page = fetch_sealed_source_page(target, after, limit)?;
        Ok((page.sources, page.next_after))
    })?;
    Ok(json!({
        "sources": sources,
        "count": sources.len(),
        "pages": pages,
        "next_after": null,
    }))
}

fn collect_keyset_pages<T>(
    options: &ListOptions,
    mut fetch: impl FnMut(Option<String>, u16) -> Result<(Vec<T>, Option<String>), CliError>,
) -> Result<(Vec<T>, usize), CliError> {
    let mut after = options.after.clone();
    let mut seen = after.iter().cloned().collect::<HashSet<_>>();
    let mut items = Vec::new();
    let mut pages = 0usize;
    loop {
        enforce_page_budget(pages, options.max_pages)?;
        let (page_items, next_after) = fetch(after, options.limit)?;
        pages += 1;
        items.extend(page_items);
        let Some(next_after) = next_after else {
            return Ok((items, pages));
        };
        validate_reply_cursor(&next_after, &mut seen)?;
        after = Some(next_after);
    }
}

fn validate_reply_cursor(cursor: &str, seen: &mut HashSet<String>) -> Result<(), CliError> {
    if !is_valid_local_id(cursor) {
        return Err(CliError::RawReply("next_after was not a valid local ULID"));
    }
    if !seen.insert(cursor.to_owned()) {
        return Err(CliError::PaginationStalled(cursor.to_owned()));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use candid::{decode_args, encode_one};
    use clap::CommandFactory;

    use super::*;

    fn invocation(values: &[&str]) -> Invocation {
        parse_test_invocation(values).expect("arguments should parse")
    }

    fn clap_error(values: &[&str]) -> ErrorKind {
        match parse_test_invocation(values) {
            Err(CliError::Clap(error)) => error.kind(),
            Err(error) => panic!("expected a Clap error, got {error}"),
            Ok(_) => panic!("expected Clap to reject the arguments"),
        }
    }

    #[test]
    fn parses_global_and_automatic_pagination_options() {
        let parsed = invocation(&[
            "--environment",
            "ic",
            "--canister",
            "aaaaa-aa",
            "--identity",
            "operator",
            "--project-root",
            "/srv/toko-feed",
            "--compact",
            "sets",
            "list",
            "--limit",
            "100",
            "--after",
            "01KZ9GFKW3SY1G000000000001",
            "--all",
            "--max-pages",
            "12",
        ]);

        assert_eq!(parsed.target.environment, "ic");
        assert_eq!(parsed.target.canister, "aaaaa-aa");
        assert_eq!(parsed.target.identity, "operator");
        assert_eq!(
            parsed.target.project_root.as_deref(),
            Some(std::path::Path::new("/srv/toko-feed"))
        );
        assert!(parsed.target.compact);
        assert_eq!(
            parsed.action,
            Action::List(
                Resource::Sets,
                ListOptions {
                    limit: 100,
                    after: Some("01KZ9GFKW3SY1G000000000001".to_owned()),
                    all: true,
                    max_pages: 12,
                }
            )
        );
    }

    #[test]
    fn parses_bootstrap_and_keeps_root_help_focused() {
        assert_eq!(
            invocation(&["backup"]).action,
            Action::Backup(PathBuf::from(DEFAULT_CANONICAL_BACKUP_PATH))
        );
        assert_eq!(invocation(&["bootstrap"]).action, Action::Bootstrap);
        assert!(parse_test_invocation(&["bootstrap", "--source", "/tmp/cache"]).is_err());
        assert!(parse_test_invocation(&["bootstrap", "--refresh"]).is_err());

        let help = Cli::command().render_help().to_string();
        assert!(help.contains("backup"));
        assert!(help.contains("bootstrap"));
        assert!(help.contains("Connection:"));
        assert!(!help.contains("tcgdex"));
        assert!(!help.contains("scrydex"));
        assert!(!help.contains("--before-time"));
        assert!(!help.contains("--release-date"));
        assert!(help.lines().count() < 45);
    }

    #[test]
    fn parses_bounded_provider_set_refresh() {
        assert_eq!(
            invocation(&[
                "provider",
                "set",
                "tcgdex",
                "ecard2",
                "--source",
                "/tmp/tcgdex",
                "--refresh",
                "--cards",
                "12",
            ])
            .action,
            Action::ProviderSet(ProviderSetOptions {
                provider: Provider::TcgDex,
                collection: "pokemon".to_owned(),
                set_id: "ecard2".to_owned(),
                source: PathBuf::from("/tmp/tcgdex"),
                refresh: true,
                cards: Some(12),
            })
        );
        assert_eq!(
            clap_error(&["provider", "set", "tcgdex", "ecard2", "--cards", "1001"]),
            ErrorKind::ValueValidation
        );
        assert_eq!(
            clap_error(&["provider", "set", "tcgdex", "../ecard2"]),
            ErrorKind::ValueValidation
        );
    }

    #[test]
    fn parses_provider_set_aliases_defaults_and_full_acquisition() {
        assert_eq!(
            invocation(&[
                "provider",
                "set",
                "scrydex",
                "ecard2",
                "--source",
                "/tmp/scrydex",
                "--refresh",
                "--cards",
                "10",
            ])
            .action,
            Action::ProviderSet(ProviderSetOptions {
                provider: Provider::Scrydex,
                collection: "pokemon".to_owned(),
                set_id: "ecard2".to_owned(),
                source: PathBuf::from("/tmp/scrydex"),
                refresh: true,
                cards: Some(10),
            })
        );
        assert_eq!(
            invocation(&["provider", "set", "scrydex", "ecard2"]).action,
            Action::ProviderSet(ProviderSetOptions {
                provider: Provider::Scrydex,
                collection: "pokemon".to_owned(),
                set_id: "ecard2".to_owned(),
                source: PathBuf::from(DEFAULT_SCRYDEX_SOURCE_PATH),
                refresh: false,
                cards: Some(DEFAULT_PROVIDER_COMPARISON_CARDS),
            })
        );
        assert_eq!(
            invocation(&["provider", "set", "scry", "ecard2"]).action,
            Action::ProviderSet(ProviderSetOptions {
                provider: Provider::Scrydex,
                collection: "pokemon".to_owned(),
                set_id: "ecard2".to_owned(),
                source: PathBuf::from(DEFAULT_SCRYDEX_SOURCE_PATH),
                refresh: false,
                cards: Some(DEFAULT_PROVIDER_COMPARISON_CARDS),
            })
        );
        assert_eq!(
            invocation(&[
                "provider",
                "set",
                "scry",
                "DRK",
                "--collection",
                "magic",
                "--all",
            ])
            .action,
            Action::ProviderSet(ProviderSetOptions {
                provider: Provider::Scrydex,
                collection: "magic-the-gathering".to_owned(),
                set_id: "DRK".to_owned(),
                source: PathBuf::from(DEFAULT_SCRYDEX_MAGIC_SOURCE_PATH),
                refresh: false,
                cards: None,
            })
        );
        assert_eq!(
            invocation(&["provider", "set", "just-tcg", "aquapolis-pokemon", "--all",]).action,
            Action::ProviderSet(ProviderSetOptions {
                provider: Provider::JustTcg,
                collection: "pokemon".to_owned(),
                set_id: "aquapolis-pokemon".to_owned(),
                source: PathBuf::from(DEFAULT_PROVIDER_SOURCE_PATH),
                refresh: false,
                cards: None,
            })
        );
        assert_eq!(
            clap_error(&["provider", "set", "unknown", "ecard2"]),
            ErrorKind::ValueValidation
        );
        assert_eq!(
            clap_error(&["provider", "set", "scry", "DRK", "--collection", "unknown",]),
            ErrorKind::ValueValidation
        );

        assert_eq!(
            invocation(&["provider", "set", "scrydex", "ecard2", "--all"]).action,
            Action::ProviderSet(ProviderSetOptions {
                provider: Provider::Scrydex,
                collection: "pokemon".to_owned(),
                set_id: "ecard2".to_owned(),
                source: PathBuf::from(DEFAULT_SCRYDEX_SOURCE_PATH),
                refresh: false,
                cards: None,
            })
        );
        assert_eq!(
            clap_error(&[
                "provider", "set", "scrydex", "ecard2", "--all", "--cards", "10",
            ]),
            ErrorKind::ArgumentConflict
        );
    }

    #[test]
    fn clap_owns_argument_relationships_and_validation() {
        Cli::command().debug_assert();

        assert!(parse_test_invocation(&["cards", "ingest"]).is_err());
        assert!(parse_test_invocation(&["sets", "curate"]).is_err());
        assert_eq!(
            clap_error(&["sets", "list", "--max-pages", "2"]),
            ErrorKind::MissingRequiredArgument
        );
        assert_eq!(
            clap_error(&["cards", "get", "not-an-id",]),
            ErrorKind::ValueValidation
        );
    }

    #[test]
    fn parses_canonical_card_queries_and_rejects_legacy_ingestion() {
        assert_eq!(
            invocation(&["cards", "get", "01KZ9GFKW3SY1G000000000001"]).action,
            Action::Get(Resource::Cards, "01KZ9GFKW3SY1G000000000001".to_owned())
        );
        assert!(parse_test_invocation(&["cards", "ingest"]).is_err());
        assert!(parse_test_invocation(&["cards", "curate"]).is_err());
        assert_eq!(
            invocation(&["cards", "by-type", "fire", "--limit", "25", "--all",]).action,
            Action::ListCardsByType(
                PokemonType::Fire,
                ListOptions {
                    limit: 25,
                    all: true,
                    ..ListOptions::default()
                }
            )
        );
        assert!(parse_test_invocation(&["cards", "by-type", "steam"]).is_err());
    }

    #[test]
    fn parses_canonical_collection_queries() {
        assert_eq!(
            invocation(&["collections", "list", "--all"]).action,
            Action::List(
                Resource::Collections,
                ListOptions {
                    all: true,
                    ..ListOptions::default()
                }
            )
        );
        assert!(parse_test_invocation(&["collections", "ingest"]).is_err());
    }

    #[test]
    fn parses_revisioned_set_lock_and_rejects_legacy_curation() {
        let set_id = "01KZ9GFKW3SY1G000000000002";
        assert_eq!(
            invocation(&["sets", "lock", set_id, "--revision", "8"]).action,
            Action::LockSet(LockPokemonSetArgs {
                id: set_id.to_owned(),
                expected_revision: 8,
            })
        );
        assert!(parse_test_invocation(&["sets", "curate"]).is_err());
    }

    #[test]
    fn parses_source_first_evidence_commands() {
        let source_id = "01KZ9GFKW3SY1G000000000001";
        let card_id = "01KZ9GFKW3SY1G000000000003";

        assert_eq!(
            invocation(&["sources", "collections", "get", source_id]).action,
            Action::Get(Resource::CollectionSources, source_id.to_owned())
        );
        assert_eq!(
            invocation(&["sources", "sets", "reject", source_id]).action,
            Action::RejectSource(Resource::SetSources, source_id.to_owned())
        );
        assert_eq!(
            invocation(&["sources", "cards", "list", "--all"]).action,
            Action::List(
                Resource::CardSources,
                ListOptions {
                    all: true,
                    ..ListOptions::default()
                }
            )
        );
        assert_eq!(
            invocation(&["sources", "sealed", "get", source_id]).action,
            Action::Get(Resource::SealedSources, source_id.to_owned())
        );
        assert_eq!(
            invocation(&["cards", "lock", card_id, "--revision", "1"]).action,
            Action::LockCard(LockPokemonCardArgs {
                id: card_id.to_owned(),
                expected_revision: 1,
            })
        );
        assert!(parse_test_invocation(&["sets", "sources", "list"]).is_err());
        assert!(parse_test_invocation(&["cards", "sources", "list"]).is_err());
        assert!(parse_test_invocation(&["sources", "sealed", "reject", source_id]).is_err());
    }

    #[test]
    fn parses_scheduler_history_and_price_commands() {
        assert_eq!(invocation(&["scheduler"]).action, Action::Scheduler);
        assert_eq!(
            invocation(&[
                "runs",
                "--before-time",
                "123",
                "--before-id",
                "01KZ9GFKW3SY1G000000000001",
                "--all",
            ])
            .action,
            Action::Runs(HistoryOptions {
                before: Some(TimeCursor {
                    timestamp: 123,
                    id: "01KZ9GFKW3SY1G000000000001".to_owned(),
                }),
                all: true,
                ..HistoryOptions::default()
            })
        );
        assert!(matches!(
            invocation(&[
                "cards",
                "prices",
                "01KZ9GFKW3SY1G000000000001",
                "--limit",
                "100",
            ])
            .action,
            Action::Prices(Resource::Cards, _, HistoryOptions { limit: 100, .. })
        ));
        assert!(matches!(
            invocation(&["sealed", "prices", "01KZ9GFKW3SY1G000000000001", "--all",]).action,
            Action::Prices(Resource::Sealed, _, HistoryOptions { all: true, .. })
        ));
        assert!(parse_test_invocation(&["runs", "list"]).is_err());
        assert!(parse_test_invocation(&["logs", "list"]).is_err());
        assert!(parse_test_invocation(&["logs", "--before-time", "123",]).is_err());
    }

    #[test]
    fn parses_sealed_queries_and_rejects_separate_ingestion() {
        assert_eq!(
            invocation(&["sealed", "list", "--all"]).action,
            Action::List(
                Resource::Sealed,
                ListOptions {
                    all: true,
                    ..ListOptions::default()
                }
            )
        );
        assert_eq!(
            invocation(&["sealed", "get", "01KZ9GFKW3SY1G000000000001"]).action,
            Action::Get(Resource::Sealed, "01KZ9GFKW3SY1G000000000001".to_owned())
        );
        assert!(parse_test_invocation(&["sealed", "ingest"]).is_err());
    }

    #[test]
    fn rejects_invalid_bounds_and_identifiers() {
        assert!(parse_test_invocation(&["sets", "list", "--limit", "0"]).is_err());
        assert!(parse_test_invocation(&["sets", "list", "--max-pages", "2"]).is_err());
        assert!(parse_test_invocation(&["sets", "get", "not-an-id"]).is_err());
    }

    #[test]
    fn accepts_help_at_any_command_depth_and_version_at_the_top_level() {
        assert!(matches!(
            parse_test_invocation(&["sets", "list", "--help"]),
            Err(CliError::Clap(error)) if error.kind() == ErrorKind::DisplayHelp
        ));
        assert!(matches!(
            parse_test_invocation(&["--version"]),
            Err(CliError::Clap(error)) if error.kind() == ErrorKind::DisplayVersion
        ));
    }

    #[test]
    fn encodes_typed_page_arguments_without_candid_text() {
        let bytes = encode_args((Some("01KZ9GFKW3SY1G000000000001".to_owned()), 100_u16))
            .expect("encode page arguments");
        let decoded = decode_args::<(Option<String>, u16)>(&bytes).expect("decode page arguments");

        assert_eq!(
            decoded,
            (Some("01KZ9GFKW3SY1G000000000001".to_owned()), 100)
        );
    }

    #[test]
    fn parses_provider_neutral_reconciliation_commands() {
        const SET: &str = "01KZ9GFKW3SY1G000000000001";
        const SOURCE_ONE: &str = "01KZ9GFKW3SY1G000000000002";
        const SOURCE_TWO: &str = "01KZ9GFKW3SY1G000000000003";
        const CARD: &str = "01KZ9GFKW3SY1G000000000004";

        assert_eq!(
            invocation(&[
                "reconcile",
                "cards",
                "plan",
                "--set",
                SET,
                "--limit",
                "50",
                "--all",
            ])
            .action,
            Action::PlanCards(CardReconciliationPlanOptions {
                pokemon_set_id: SET.to_owned(),
                plan: ReconciliationPlanOptions {
                    after: None,
                    limit: 50,
                    all: true,
                    max_pages: DEFAULT_MAX_PAGES,
                },
            })
        );
        assert_eq!(
            invocation(&[
                "reconcile",
                "cards",
                "accept-metadata",
                "--card",
                CARD,
                "--source",
                SOURCE_ONE,
            ])
            .action,
            Action::ReconcileCardMetadata(CuratePokemonCardMetadataArgs {
                pokemon_card_id: CARD.to_owned(),
                pokemon_card_source_id: SOURCE_ONE.to_owned(),
            })
        );
        assert_eq!(
            invocation(&["reconcile", "cards", "accept-safe", "--set", SET, "--all",]).action,
            Action::ReconcileSafeCards(SafeCardReconciliationOptions {
                args: ReconcilePokemonCardsArgs {
                    pokemon_set_id: SET.to_owned(),
                    after_match_key: None,
                    limit: MAX_SAFE_RECONCILIATION_CARDS,
                },
                all: true,
                max_pages: DEFAULT_MAX_PAGES,
            })
        );
        assert_eq!(
            invocation(&[
                "reconcile",
                "cards",
                "accept-printing",
                "--source",
                SOURCE_ONE,
                SOURCE_TWO,
                "--card",
                CARD,
                "--collector-number",
                "50a",
                "--variant",
                "a",
            ])
            .action,
            Action::ReconcileCardPrinting(ReconcilePokemonCardPrintingArgs {
                source_ids: vec![SOURCE_ONE.to_owned(), SOURCE_TWO.to_owned()],
                pokemon_card_id: CARD.to_owned(),
                collector_number: "50a".to_owned(),
                variant_code: "a".to_owned(),
            })
        );
        assert_eq!(
            invocation(&[
                "reconcile",
                "sets",
                "accept-safe",
                "pokemon-set:v1:pokemon:aquapolis:2003-01-15",
            ])
            .action,
            Action::ReconcileSafeSet("pokemon-set:v1:pokemon:aquapolis:2003-01-15".to_owned())
        );
        assert_eq!(
            clap_error(&[
                "reconcile",
                "cards",
                "accept-safe",
                "--set",
                SET,
                "--limit",
                "11",
            ]),
            ErrorKind::ValueValidation
        );
    }

    #[test]
    fn hexadecimal_transport_round_trips_raw_candid() {
        let bytes = encode_args((None::<String>, 20_u16)).expect("encode arguments");
        assert_eq!(
            decode_hex(format!("0x{}\n", encode_hex(&bytes)).as_bytes()).expect("decode hex"),
            bytes
        );
    }

    #[test]
    fn binary_call_arguments_are_removed_after_use() {
        let arguments = b"bounded candid payload";
        let argument_file =
            CallArgumentFile::create(arguments).expect("argument file should be created");
        let path = argument_file.path.clone();
        assert_eq!(
            fs::read(&path).expect("argument file should be readable"),
            arguments
        );
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt as _;
            let mode = fs::metadata(&path)
                .expect("argument metadata should be readable")
                .permissions()
                .mode();
            assert_eq!(mode & 0o777, 0o600);
        }
        drop(argument_file);
        assert!(!path.exists());
    }

    #[test]
    fn decodes_a_typed_canister_result() {
        let status = FeedStatus {
            configured: true,
            scrydex_configured: true,
            next_offset: 50,
            sets_next_offset: 20,
            ingesting: false,
            last_error_code: None,
            updated_at_ns: 123,
        };
        let reply = encode_one(Ok::<_, FeedError>(status.clone())).expect("encode reply");

        assert_eq!(
            decode_result::<FeedStatus>("toko_feed_status", &reply).expect("decode result"),
            status
        );
    }

    #[test]
    fn rejects_non_hexadecimal_transport_output() {
        assert!(decode_hex(b"not-hex").is_err());
        assert!(decode_hex(b"abc").is_err());
    }

    #[test]
    fn keyset_page_collection_preserves_order_and_rejects_stalled_cursors() {
        const CURSOR: &str = "01KZ9GFKW3SY1G000000000001";
        let options = ListOptions {
            after: None,
            limit: 2,
            all: true,
            max_pages: 3,
        };
        let (items, pages) = collect_keyset_pages(&options, |after, limit| {
            assert_eq!(limit, 2);
            match after.as_deref() {
                None => Ok((vec![1, 2], Some(CURSOR.to_owned()))),
                Some(CURSOR) => Ok((vec![3], None)),
                Some(_) => Err(CliError::RawReply("unexpected test cursor")),
            }
        })
        .expect("bounded pages should collect");
        assert_eq!(items, vec![1, 2, 3]);
        assert_eq!(pages, 2);

        let stalled = ListOptions {
            after: Some(CURSOR.to_owned()),
            ..options
        };
        assert!(matches!(
            collect_keyset_pages::<u8>(&stalled, |_, _| Ok((vec![1], Some(CURSOR.to_owned())))),
            Err(CliError::PaginationStalled(cursor)) if cursor == CURSOR
        ));
    }
}