sefy 0.18.0

//! Command-line surface: what `sefy` accepts and what each option means.

use clap::{Args, Parser, Subcommand, ValueEnum};
use std::ffi::OsString;
use std::path::PathBuf;

/// The variable naming the transport to use when there are several.
pub const TRANSPORT_ENV: &str = "SEFY_TRANSPORT";

/// The variable naming the remote copy.
pub const REMOTE_NAME_ENV: &str = "SEFY_REMOTE_NAME";

/// What the remote copy is called when nothing says otherwise.
pub const DEFAULT_REMOTE_NAME: &str = "vault";

/// An inconspicuous encrypted store for notes, credentials and files.
#[derive(Debug, Parser)]
#[command(name = "sefy", version, about, long_about = None)]
pub struct Cli {
    /// Vault file to work on; falls back to $SEFY_VAULT.
    ///
    /// There is deliberately no default path: a vault at a predictable
    /// location would be exactly the giveaway the format avoids.
    #[arg(
        long,
        short = 'f',
        global = true,
        env = "SEFY_VAULT",
        value_name = "FILE"
    )]
    pub vault: Option<PathBuf>,

    /// Read the master password from this environment variable.
    ///
    /// For scripts and CI. Passing a password as an argument is not supported:
    /// it would land in the shell history and in every process listing.
    #[arg(long, global = true, value_name = "VAR")]
    pub password_env: Option<String>,

    /// After a command that changes the vault, sync it: pull, then push.
    ///
    /// For a machine that is one of several: add a password on the laptop
    /// and it is already on the remote. The transport and the remote name are
    /// the ones `sefy sync` would use here. The change is on disk before the
    /// sync starts, so a sync that fails says why and leaves it there for the
    /// next one.
    #[arg(
        long,
        global = true,
        env = "SEFY_AUTO_SYNC",
        value_name = "WHEN",
        value_enum,
        ignore_case = true
    )]
    pub auto_sync: Option<Switch>,

    /// What to do. Omitted, sefy opens an interactive picker over the vault.
    #[command(subcommand)]
    pub command: Option<Command>,
}

/// What the user asked sefy to do.
#[derive(Debug, Subcommand)]
pub enum Command {
    /// Create a new vault.
    Init,

    /// Add an item to the vault.
    Add {
        #[command(subcommand)]
        kind: AddKind,
    },

    /// Copy a secret to the clipboard, or print it with --stdout.
    Get(GetArgs),

    /// Show an item without revealing its secret fields.
    Show {
        /// Item id, exact title, or text to search for.
        reference: String,
    },

    /// List items in the vault.
    Ls(ListArgs),

    /// Search items by text, kind and tags.
    Find(FindArgs),

    /// Change an item's title, contents or tags.
    Edit(EditArgs),

    /// List the earlier versions of an item's contents, or compare one with
    /// what is there now.
    ///
    /// Every change to a note's text or a record's fields keeps what it
    /// replaced, and so does a merge that had to choose. Secret values are
    /// never shown: a version says that its password differs, not what it
    /// was.
    History(HistoryArgs),

    /// Bring back an earlier version of an item's contents, or one field of
    /// it.
    ///
    /// What was there becomes a version of its own, so a restore can be
    /// undone the same way.
    Restore(RestoreArgs),

    /// Remove an item.
    Rm {
        /// Item id, exact title, or text to search for.
        reference: String,

        /// Do not ask for confirmation.
        #[arg(long, short = 'y')]
        yes: bool,
    },

    /// Write a stored file back to disk.
    Extract {
        /// Item id, exact title, or text to search for.
        reference: String,

        /// Where to write it; defaults to the stored filename in the current
        /// directory.
        #[arg(long, short = 'o', value_name = "PATH")]
        output: Option<PathBuf>,

        /// Overwrite the destination if it exists.
        #[arg(long)]
        force: bool,
    },

    /// List the tags in use.
    Tags,

    /// Generate a password or a passphrase and copy it to the clipboard.
    ///
    /// No vault is needed unless the result is kept with --save, which stores
    /// it as a new login in the same gesture.
    Gen(GenArgs),

    /// Open an item's site and copy its password to the clipboard.
    ///
    /// The two halves of signing in, in the order they are used: the browser
    /// loads while the password waits to be pasted.
    Open(OpenArgs),

    /// Copy a record's one-time password to the clipboard.
    ///
    /// With --set, store the key a site shows when two-factor sign-in is
    /// turned on first; with --qr, draw the key for a phone to scan.
    Otp(OtpArgs),

    /// Hand over a record's fields one at a time, in the order a form asks.
    ///
    /// A login gives its login, then its password, then a fresh one-time
    /// code: each goes to the clipboard, and Enter moves to the next.
    Fill(FillArgs),

    /// Run a command with secrets from the vault in its environment.
    ///
    /// For a script or a tool that reads a token from a variable: the secret
    /// reaches that one process and never a `.env` file, the shell history or
    /// a command line. The command's exit status becomes sefy's.
    Run(RunArgs),

    /// Look for what in the vault deserves a second look.
    ///
    /// Passwords that are easy to guess, shared between items or unchanged
    /// for over a year; a card, a token or a key kept in two items; records
    /// past or within 30 days of the last day they work. Worked out on this
    /// machine, from the vault alone: nothing is looked up and nothing is
    /// sent. Values are never shown. The exit status is non-zero when
    /// anything is found.
    Audit,

    /// Show what and where this vault is, without revealing any of it.
    ///
    /// Counts, versions and the last transfer - never a title or a value. It
    /// answers the question asked after a new machine, a restore or a week
    /// away: is this the right file, is everything in it, and has it reached
    /// the other side lately.
    Status,

    /// Write the vault's contents out, unencrypted, for another sefy or
    /// another password manager.
    ///
    /// sefy's own JSON carries everything. KeePass XML carries every kind
    /// too, and KeePass and KeePassXC import it; a CSV carries logins, and
    /// every browser imports it.
    Export {
        /// Where to write it; omit to print to stdout.
        #[arg(long, short = 'o', value_name = "PATH")]
        output: Option<PathBuf>,

        /// What to write.
        #[arg(long, value_enum, default_value_t = ExportFormat::Sefy)]
        format: ExportFormat,

        /// Include each item's earlier versions.
        ///
        /// Off by default: a file of every password an account has ever had,
        /// in the clear, is a larger exposure than moving the current ones
        /// calls for. sefy's JSON and KeePass XML have a place for them; a CSV
        /// does not.
        #[arg(long)]
        with_history: bool,

        /// Required: acknowledge that this writes every secret in the clear.
        ///
        /// Export exists so a vault is never a trap, but the file it produces
        /// is exactly as sensitive as the vault — and unlike the vault, it
        /// protects nothing. A warning printed after the fact would be too
        /// late, so the acknowledgement comes first.
        #[arg(long)]
        i_know_this_writes_plaintext: bool,

        /// Overwrite the destination if it exists.
        #[arg(long)]
        force: bool,
    },

    /// Add what another sefy, a password manager or a browser exported to
    /// this vault.
    ///
    /// The format is told from the file: a sefy export, a Bitwarden JSON
    /// export, a KeePass XML export, or a CSV of passwords. An entry the vault
    /// already holds under the same identity is skipped, so importing the same
    /// file twice does not duplicate it. Contents are never overwritten: the
    /// file may well be older than what is here, and bringing newer contents
    /// across is what `merge` is for.
    Import {
        /// File to read; omit to read from stdin.
        #[arg(value_name = "PATH")]
        input: Option<PathBuf>,
    },

    /// Fold another vault file into this one.
    ///
    /// For two copies that drifted apart: items missing here are copied across,
    /// newer contents from there replace older ones here, and an item changed
    /// on both sides keeps the newer contents with the other side's in its
    /// history. Nothing is ever deleted — "gone from there" and "added here"
    /// look identical from this side.
    Merge {
        /// The other vault file.
        #[arg(value_name = "FILE")]
        other: PathBuf,

        /// Read the other vault's password from this environment variable.
        ///
        /// Distinct from --password-env: a copy from another machine may well
        /// be under a different password, and reusing one variable for both
        /// would make that impossible to express.
        #[arg(long, value_name = "VAR")]
        other_password_env: Option<String>,

        /// Say what the merge would change, item by item, and change nothing.
        #[arg(long)]
        dry_run: bool,
    },

    /// Replace the master password.
    ChangePassword {
        /// Read the *new* password from this environment variable.
        ///
        /// Distinct from --password-env, which carries the current one: with a
        /// single variable the "new" password would be the old one.
        #[arg(long, value_name = "VAR")]
        new_password_env: Option<String>,
    },

    /// Destroy the vault: overwrite it, the copies beside it and any
    /// unfinished save with random bytes, and delete them.
    ///
    /// It asks for the master password, lists every file it will destroy,
    /// and goes ahead only once the vault's file name is typed back. There is
    /// no --yes, and without a terminal it refuses. The remote copy is not
    /// touched.
    ///
    /// The overwrite reaches the blocks the file system shows for each file,
    /// and no others. An SSD and a copy-on-write file system keep replaced
    /// blocks out of reach; a snapshot, a backup or a synced folder's history
    /// keeps a copy of its own. What survives there is the sealed vault,
    /// which still needs the password - but a wipe cannot promise it is gone.
    Wipe,

    /// Send this vault to the remote, replacing the copy there.
    ///
    /// The file that travels is the sealed one; the transport carrying it never
    /// sees the master password or a single item.
    Push(RemoteArgs),

    /// Fetch the remote copy and fold it into this vault.
    ///
    /// The two are merged rather than one replacing the other: items missing
    /// here are copied across, newer contents replace older ones, and an item
    /// changed on both sides keeps the other side's contents in its history.
    /// Nothing local is deleted.
    Pull(PullArgs),

    /// Pull, then push: take what is at the remote, then publish the result.
    ///
    /// The everyday gesture on a machine that is one of several. The order is
    /// not a preference — pushing first would replace the remote copy with one
    /// that never saw its contents.
    Sync(PullArgs),

    /// Check that what sefy needs on this machine works.
    ///
    /// The vault opens and so do the copies beside it, the plugins answer,
    /// the transport reaches the remote copy and that opens too, the
    /// clipboard is there. Nothing is changed and nothing is sent; the exit
    /// status is non-zero when a check fails.
    Doctor(RemoteArgs),

    /// Inspect the transports installed on this machine.
    Plugin {
        #[command(subcommand)]
        action: PluginAction,
    },

    /// Print a shell completion script.
    Completions {
        /// Shell to generate for.
        shell: clap_complete::Shell,
    },
}

/// Which transport to use, and what the remote copy is called.
#[derive(Debug, Args)]
pub struct RemoteArgs {
    /// Transport to use, by its short name; omit when only one is installed.
    ///
    /// There is no configuration file to record a default in — sefy keeps
    /// nothing on disk but the vault, its copies and its plugins — so the
    /// choice is either obvious or stated.
    #[arg(long, short = 'p', value_name = "NAME", env = TRANSPORT_ENV)]
    pub transport: Option<String>,

    /// What the remote copy is called.
    ///
    /// A transport needs some handle for the thing it stores, and the local
    /// file name is a poor one: a vault is deliberately named like anything
    /// else, and on a shared remote two machines' "notes.bak" would collide.
    #[arg(
        long,
        value_name = "NAME",
        env = REMOTE_NAME_ENV,
        default_value = DEFAULT_REMOTE_NAME
    )]
    pub name: String,
}

/// A pull or a sync: a transport, a remote name, and the remote's password.
#[derive(Debug, Args)]
pub struct PullArgs {
    #[command(flatten)]
    pub remote: RemoteArgs,

    /// Read the *remote* copy's master password from this environment variable.
    ///
    /// Only needed when the two differ. Unlike `merge`, which folds in a file
    /// from anywhere, a pull brings back a copy of *this* vault, and the same
    /// password is the ordinary case — so it is what sefy uses unless told
    /// otherwise here or with --ask-remote-password.
    #[arg(long, value_name = "VAR", conflicts_with = "ask_remote_password")]
    pub remote_password_env: Option<String>,

    /// Ask for the remote copy's password instead of reusing this vault's.
    #[arg(long)]
    pub ask_remote_password: bool,

    /// Say what would change, item by item, and change nothing.
    ///
    /// The remote copy is fetched and the merge is worked out in memory:
    /// nothing is written here, nothing is sent, and no transfer is recorded.
    /// A sync also says what the remote copy would gain.
    #[arg(long)]
    pub dry_run: bool,
}

/// On or off, as spelled on the command line or in a variable.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum Switch {
    /// On.
    #[value(alias = "true", alias = "yes", alias = "1")]
    On,
    /// Off.
    #[value(alias = "false", alias = "no", alias = "0")]
    Off,
}

/// What to do with plugins.
#[derive(Debug, Subcommand)]
pub enum PluginAction {
    /// List the plugins sefy can see, and say why any of them is unusable.
    List {
        /// Also print where sefy looked.
        #[arg(long)]
        paths: bool,
    },
}

/// The kind of item being added.
#[derive(Debug, Subcommand)]
pub enum AddKind {
    /// A free-form note.
    Note {
        /// What to call it.
        title: String,

        /// The text; omit to read it from stdin, or pass --editor.
        #[arg(long, short = 't', conflicts_with = "editor")]
        text: Option<String>,

        /// Write the note in $EDITOR.
        #[arg(long, short = 'e')]
        editor: bool,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// A login, its password and where it is used.
    #[command(alias = "credential")]
    Login {
        /// What to call it.
        title: String,

        /// Username, email, or whatever the service calls it.
        #[arg(long, short = 'l')]
        login: String,

        /// Where the account lives.
        #[arg(long, short = 'u')]
        url: Option<String>,

        /// Shared secret for time-based one-time passwords.
        #[arg(long)]
        totp: Option<String>,

        /// Anything else worth remembering.
        #[arg(long)]
        notes: Option<String>,

        /// Read the item's password from this environment variable instead of
        /// prompting.
        ///
        /// Deliberately separate from the global --password-env, which carries
        /// the master password.
        #[arg(long = "item-password-env", value_name = "VAR")]
        item_password_env: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// A payment card.
    ///
    /// The number, the CVV and the PIN are secret: they are asked for rather
    /// than passed as options, so they stay out of the shell history and out of
    /// every process listing on the machine.
    Card {
        /// What to call it.
        title: String,

        /// Name embossed on the card.
        #[arg(long)]
        holder: Option<String>,

        /// The month the card runs out, as printed on it: 03/29.
        ///
        /// Stored as the month it names, 2029-03, which is what `sefy audit`
        /// counts from; `sefy fill` hands it over as printed again.
        #[arg(long, value_name = "MM/YY")]
        expires: Option<String>,

        /// Anything else worth remembering.
        #[arg(long)]
        notes: Option<String>,

        /// Do not ask for the CVV.
        #[arg(long)]
        no_cvv: bool,

        /// Do not ask for the PIN.
        #[arg(long)]
        no_pin: bool,

        /// Read the card number from this environment variable instead of
        /// prompting.
        #[arg(long, value_name = "VAR")]
        number_env: Option<String>,

        /// Read the CVV from this environment variable instead of prompting.
        #[arg(long, value_name = "VAR", conflicts_with = "no_cvv")]
        cvv_env: Option<String>,

        /// Read the PIN from this environment variable instead of prompting.
        #[arg(long, value_name = "VAR", conflicts_with = "no_pin")]
        pin_env: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// An SSH key pair and its passphrase.
    ///
    /// The private key is read from a file rather than typed: it is multi-line
    /// and would not survive a prompt. It is stored as a field, not as an
    /// attachment, so `sefy get` can hand it to a command directly.
    SshKey {
        /// What to call it.
        title: String,

        /// Private key file to read.
        #[arg(long, value_name = "PATH")]
        private_key: PathBuf,

        /// Public key file to read; defaults to the private key's path with
        /// `.pub` appended, when such a file is there.
        #[arg(long, value_name = "PATH")]
        public_key: Option<PathBuf>,

        /// Where the key is used.
        #[arg(long)]
        host: Option<String>,

        /// Anything else worth remembering.
        #[arg(long)]
        notes: Option<String>,

        /// Do not ask for the passphrase; for a key that has none.
        #[arg(long)]
        no_passphrase: bool,

        /// Read the passphrase from this environment variable instead of
        /// prompting.
        #[arg(long, value_name = "VAR", conflicts_with = "no_passphrase")]
        passphrase_env: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// A Wi-Fi network: ssid, password, security, notes.
    ///
    /// The password is asked for; the other fields are passed with --set.
    Wifi(RecordArgs),

    /// A token for an API: token, url, scopes, expires, notes.
    ///
    /// The token is asked for; the other fields are passed with --set, the
    /// last day it works as --set expires=2027-01-31.
    ApiToken(RecordArgs),

    /// A bank account: account, holder, bank, routing, notes.
    ///
    /// The account number is asked for; the other fields are passed with
    /// --set.
    Bank(RecordArgs),

    /// A file, stored byte for byte.
    File {
        /// File to read.
        path: PathBuf,

        /// What to call it; defaults to the file name.
        #[arg(long, short = 'T')]
        title: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },
}

/// Arguments of the kinds that are nothing but their fields.
///
/// A kind like this is a row in the template table: which fields it has, which
/// are secret. The command line follows from the row rather than growing a
/// flag per field, so the next kind costs no new options.
#[derive(Debug, Args)]
pub struct RecordArgs {
    /// What to call it.
    pub title: String,

    /// Set a field: `--set ssid=Home`. Repeat for several.
    ///
    /// Secret fields are refused here and asked for instead, so they stay out
    /// of the shell history. A name the kind does not have is kept as an
    /// extra field.
    #[arg(long, value_name = "NAME=VALUE")]
    pub set: Vec<String>,

    /// Read a secret field from an environment variable instead of asking:
    /// `--secret-env password=WIFI_KEY`.
    #[arg(long, value_name = "NAME=VAR")]
    pub secret_env: Vec<String>,

    /// Do not ask for this secret field.
    #[arg(long, value_name = "NAME")]
    pub skip: Vec<String>,

    /// Tags to attach; repeat or separate with commas.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,
}

/// Arguments of `sefy get`.
#[derive(Debug, Args)]
pub struct GetArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Which field to take from a record.
    ///
    /// Any field the record carries, by name. Omitted, sefy takes the kind's
    /// own secret: a login's password, a card's number, an SSH key's private
    /// key.
    #[arg(long, value_name = "NAME")]
    pub field: Option<String>,

    /// Print the secret instead of copying it to the clipboard.
    ///
    /// Convenient for pipes, but the secret then lives in the terminal
    /// scrollback.
    #[arg(long)]
    pub stdout: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    ///
    /// sefy waits that long before exiting, and clears the clipboard only if
    /// the secret is still the value sitting on it.
    #[arg(long, value_name = "SECONDS", default_value_t = sefy_core::clipboard::HOLD_SECONDS)]
    pub clear_after: u64,
}

/// Arguments of `sefy gen`.
#[derive(Debug, Args)]
pub struct GenArgs {
    /// Length in characters.
    #[arg(
        long,
        short = 'n',
        value_name = "N",
        default_value_t = 20,
        conflicts_with = "words"
    )]
    pub length: usize,

    /// Leave out upper-case letters.
    #[arg(long, conflicts_with_all = ["words", "pronounceable"])]
    pub no_uppercase: bool,

    /// Leave out digits.
    #[arg(long, conflicts_with_all = ["words", "pronounceable"])]
    pub no_digits: bool,

    /// Leave out symbols, for the sites that refuse them.
    #[arg(long, conflicts_with_all = ["words", "pronounceable"])]
    pub no_symbols: bool,

    /// Alternate consonants and vowels, so it can be read out and typed.
    ///
    /// Weaker per character than the default: check the bits it reports and
    /// make it longer to match.
    #[arg(long, conflicts_with = "words")]
    pub pronounceable: bool,

    /// Make a passphrase of this many words instead of a password.
    ///
    /// For a secret typed by hand: a master password, a disk encryption key.
    #[arg(long, short = 'w', value_name = "N")]
    pub words: Option<usize>,

    /// Which word list a passphrase is drawn from.
    #[arg(long, value_enum, default_value = "en", requires = "words")]
    pub lang: WordList,

    /// What goes between the words of a passphrase.
    #[arg(long, value_name = "TEXT", default_value = "-", requires = "words")]
    pub separator: String,

    /// Store the result as a new login under this title.
    #[arg(long, value_name = "TITLE")]
    pub save: Option<String>,

    /// The login of the saved record.
    #[arg(long, short = 'l', requires = "save")]
    pub login: Option<String>,

    /// Where the saved account lives.
    #[arg(long, short = 'u', requires = "save")]
    pub url: Option<String>,

    /// Tags for the saved record; repeat or separate with commas.
    #[arg(long, value_delimiter = ',', requires = "save")]
    pub tag: Vec<String>,

    /// Print the result instead of copying it to the clipboard.
    ///
    /// The description goes to stderr, so a pipe receives the secret alone.
    #[arg(long)]
    pub stdout: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    #[arg(long, value_name = "SECONDS", default_value_t = sefy_core::clipboard::HOLD_SECONDS)]
    pub clear_after: u64,
}

/// What `sefy export` writes, as spelled on the command line.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum ExportFormat {
    /// sefy's own JSON: every kind, every field, nothing lost.
    Sefy,
    /// KeePass XML, which KeePass 2 and KeePassXC import.
    Keepass,
    /// Logins as CSV rows, which browsers and password managers import.
    Csv,
}

/// A passphrase word list, as spelled on the command line.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum WordList {
    /// The EFF large wordlist: 7776 words, 12.9 bits each.
    En,
    /// Russian Diceware 4d6: 1296 words, 10.3 bits each.
    Ru,
}

impl From<WordList> for sefy_core::Language {
    fn from(list: WordList) -> Self {
        match list {
            WordList::En => Self::English,
            WordList::Ru => Self::Russian,
        }
    }
}

/// Arguments of `sefy open`.
#[derive(Debug, Args)]
pub struct OpenArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Open the site without touching the clipboard.
    #[arg(long)]
    pub no_password: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    #[arg(long, value_name = "SECONDS", default_value_t = sefy_core::clipboard::HOLD_SECONDS)]
    pub clear_after: u64,
}

/// Arguments of `sefy otp`.
#[derive(Debug, Args)]
pub struct OtpArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Store a key on the record first; it is asked for and never echoed.
    ///
    /// Paste the otpauth:// link a setup QR code carries, or the text key the
    /// page shows beside it. The first code follows, for the site that asks
    /// for one to confirm.
    #[arg(long)]
    pub set: bool,

    /// Read the key to store from this environment variable instead of
    /// asking.
    #[arg(long, value_name = "VAR")]
    pub key_env: Option<String>,

    /// Draw the key as a QR code, for an authenticator app on a phone.
    ///
    /// The picture is the key itself: it is drawn only on a terminal and
    /// cleared from the screen once Enter is pressed.
    #[arg(long, conflicts_with = "stdout")]
    pub qr: bool,

    /// Print the code instead of copying it to the clipboard.
    #[arg(long)]
    pub stdout: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    #[arg(long, value_name = "SECONDS", default_value_t = sefy_core::clipboard::HOLD_SECONDS)]
    pub clear_after: u64,
}

/// Arguments of `sefy fill`.
#[derive(Debug, Args)]
pub struct FillArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Seconds before the last field is cleared from the clipboard; 0 leaves
    /// it there.
    #[arg(long, value_name = "SECONDS", default_value_t = sefy_core::clipboard::HOLD_SECONDS)]
    pub clear_after: u64,
}

/// Arguments of `sefy run`.
#[derive(Debug, Args)]
pub struct RunArgs {
    /// Set a variable from the vault: `--env GITHUB_TOKEN=github`.
    ///
    /// The value is the item's own secret, the one `sefy get` takes; add
    /// `#FIELD` for another field: `--env DB_USER=db#login`. Repeat for
    /// several.
    #[arg(
        long,
        short = 'e',
        value_name = "VAR=REFERENCE[#FIELD]",
        required = true
    )]
    pub env: Vec<String>,

    /// The command to run and its arguments, after `--`.
    #[arg(last = true, required = true, value_name = "COMMAND")]
    pub command: Vec<OsString>,
}

/// Arguments of `sefy ls`.
#[derive(Debug, Args)]
pub struct ListArgs {
    /// Keep only items of this kind.
    #[arg(long, value_enum)]
    pub kind: Option<Kind>,

    /// Keep only items carrying every one of these tags.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,
}

/// Arguments of `sefy find`.
#[derive(Debug, Args)]
pub struct FindArgs {
    /// Text to look for in titles, notes and credential fields.
    ///
    /// The contents of stored files are not searched.
    pub text: Option<String>,

    /// Keep only items of this kind.
    #[arg(long, value_enum)]
    pub kind: Option<Kind>,

    /// Keep only items carrying every one of these tags.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,
}

/// Arguments of `sefy edit`.
#[derive(Debug, Args)]
pub struct EditArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// New title.
    #[arg(long)]
    pub title: Option<String>,

    /// New text, for a note.
    #[arg(long, short = 't', conflicts_with = "editor")]
    pub text: Option<String>,

    /// Open the note in $EDITOR instead of passing its text on the command
    /// line.
    ///
    /// The draft is written to a temporary file, which is overwritten and
    /// removed as soon as the editor exits — but while the editor is open, that
    /// file holds the note in the clear, and an editor's own swap or backup
    /// files are outside sefy's reach.
    #[arg(long, short = 'e')]
    pub editor: bool,

    /// Set a field of a record: `--set url=https://example.com`.
    ///
    /// Repeat for several. A field the record does not have yet is added, so
    /// this is how a record grows beyond what its kind suggested.
    #[arg(long, value_name = "NAME=VALUE")]
    pub set: Vec<String>,

    /// Prompt for a field's value instead of passing it on the command line:
    /// `--set-secret password`.
    ///
    /// The value is read the way the master password is — never echoed, never
    /// in the shell history — and the field is marked secret.
    #[arg(long, value_name = "NAME")]
    pub set_secret: Vec<String>,

    /// Remove a field from a record.
    #[arg(long, value_name = "NAME")]
    pub unset: Vec<String>,

    /// Replace the item's tags; repeat or separate with commas.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,

    /// Remove every tag from the item.
    #[arg(long, conflicts_with = "tag")]
    pub clear_tags: bool,
}

/// Arguments of `sefy history`.
#[derive(Debug, Args)]
pub struct HistoryArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// A version, by the number the listing gives it, to compare with the
    /// current contents.
    #[arg(value_name = "VERSION")]
    pub version: Option<usize>,
}

/// Arguments of `sefy restore`.
#[derive(Debug, Args)]
pub struct RestoreArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// The version to bring back, by the number `sefy history` gives it.
    #[arg(value_name = "VERSION")]
    pub version: usize,

    /// Bring back only this field of a record; the others keep their current
    /// values.
    #[arg(long, value_name = "NAME")]
    pub field: Option<String>,
}

/// Kind of item, as spelled on the command line.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum Kind {
    /// A free-form note.
    Note,
    /// An account and its password.
    #[value(alias = "credential")]
    Login,
    /// A payment card.
    Card,
    /// An SSH key pair.
    SshKey,
    /// A Wi-Fi network.
    Wifi,
    /// A token for an API.
    ApiToken,
    /// A bank account.
    Bank,
    /// A stored file.
    File,
}

impl From<Kind> for sefy_core::ItemKind {
    fn from(kind: Kind) -> Self {
        match kind {
            Kind::Note => Self::Note,
            Kind::Login => Self::Login,
            Kind::Card => Self::Card,
            Kind::SshKey => Self::SshKey,
            Kind::Wifi => Self::Wifi,
            Kind::ApiToken => Self::ApiToken,
            Kind::Bank => Self::Bank,
            Kind::File => Self::File,
        }
    }
}