sefy 0.19.0

//! What each subcommand does once the vault is open.

use crate::autosync::AutoSync;
use crate::cli::{
    AddKind, EditArgs, ExportFormat, FillArgs, FindArgs, GenArgs, GetArgs, HistoryArgs, ListArgs,
    OpenArgs, OtpArgs, PullArgs, RecordArgs, RemoteArgs, RestoreArgs, RunArgs,
};
use crate::output;
use crate::session::{self, Master};
use anyhow::{Context, Result, bail};
use sefy_core::{
    Change, ChangeKind, Classes, Field, Item, ItemKind, ItemSummary, NewItem, Opener, Outcome,
    Payload, Query, Recipe, Strength, Target, Totp, Vault, Version,
};
use std::io::Read;
use std::path::{Path, PathBuf};
use zeroize::Zeroizing;

/// Creates a vault, refusing to touch a file that already exists.
pub fn init(path: &Path, password_env: Option<&str>) -> Result<()> {
    if path.exists() {
        bail!("{} already exists", path.display());
    }
    let password = session::new_password(password_env)?;
    Vault::create(path, password.as_bytes())?;
    println!("created {}", path.display());
    Ok(())
}

/// Adds an item and saves the vault.
pub fn add(vault: &mut Vault, kind: AddKind) -> Result<()> {
    let (item, description) = match kind {
        AddKind::Note {
            title,
            text,
            editor,
            tag,
        } => {
            let text = match text {
                Some(text) => text,
                None if editor => crate::editor::edit("")?,
                None => read_stdin().context("cannot read the note text from stdin")?,
            };
            (
                NewItem::new(title.clone(), Payload::Note { text }).with_tags(tag),
                title,
            )
        }
        AddKind::Login {
            title,
            login,
            url,
            totp,
            notes,
            item_password_env,
            tag,
        } => {
            // Only this item's own variable is consulted: falling back to
            // --password-env would silently store the master password as the
            // account's password.
            let password =
                session::secret("Password for this item: ", item_password_env.as_deref())?;
            let mut fields = vec![
                Field::public("login", login),
                Field::secret("password", password),
            ];
            push_optional(&mut fields, "url", url, false);
            let totp = totp
                .map(|key| checked(sefy_core::otp::FIELD, key))
                .transpose()?;
            push_optional(&mut fields, sefy_core::otp::FIELD, totp, true);
            push_optional(&mut fields, "notes", notes, false);
            (
                NewItem::new(title.clone(), Payload::fields(ItemKind::Login, fields))
                    .with_tags(tag),
                title,
            )
        }
        AddKind::Card {
            title,
            holder,
            expires,
            notes,
            no_cvv,
            no_pin,
            number_env,
            cvv_env,
            pin_env,
            tag,
        } => {
            let number = session::secret("Card number: ", number_env.as_deref())?;
            let mut fields = vec![Field::secret("number", number)];
            push_optional(&mut fields, "holder", holder, false);
            let expires = expires
                .map(|value| checked(sefy_core::expiry::FIELD, value))
                .transpose()?;
            push_optional(&mut fields, sefy_core::expiry::FIELD, expires, false);
            if !no_cvv {
                push_typed(
                    &mut fields,
                    "cvv",
                    session::secret("CVV (empty if there is none): ", cvv_env.as_deref())?,
                )?;
            }
            if !no_pin {
                push_typed(
                    &mut fields,
                    "pin",
                    session::secret("PIN (empty if unknown): ", pin_env.as_deref())?,
                )?;
            }
            push_optional(&mut fields, "notes", notes, false);
            (
                NewItem::new(title.clone(), Payload::fields(ItemKind::Card, fields)).with_tags(tag),
                title,
            )
        }
        AddKind::SshKey {
            title,
            private_key,
            public_key,
            host,
            notes,
            no_passphrase,
            passphrase_env,
            tag,
        } => {
            let private = std::fs::read_to_string(&private_key)
                .with_context(|| format!("cannot read {}", private_key.display()))?;
            let mut fields = vec![Field::secret("private-key", private)];
            if !no_passphrase {
                push_typed(
                    &mut fields,
                    "passphrase",
                    session::secret(
                        "Passphrase for the key (empty if it has none): ",
                        passphrase_env.as_deref(),
                    )?,
                )?;
            }
            // The conventional sibling is picked up when it is there, and its
            // absence is not an error: a key without its public half is still
            // worth storing, and the public half can be derived from it.
            let public_path = public_key.unwrap_or_else(|| sibling_public_key(&private_key));
            match std::fs::read_to_string(&public_path) {
                Ok(public) => fields.push(Field::public("public-key", public.trim())),
                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
                Err(error) => {
                    return Err(error)
                        .with_context(|| format!("cannot read {}", public_path.display()));
                }
            }
            push_optional(&mut fields, "host", host, false);
            push_optional(&mut fields, "notes", notes, false);
            (
                NewItem::new(title.clone(), Payload::fields(ItemKind::SshKey, fields))
                    .with_tags(tag),
                title,
            )
        }
        AddKind::Wifi(args) => record(ItemKind::Wifi, args)?,
        AddKind::ApiToken(args) => record(ItemKind::ApiToken, args)?,
        AddKind::Bank(args) => record(ItemKind::Bank, args)?,
        AddKind::File { path, title, tag } => {
            let bytes =
                std::fs::read(&path).with_context(|| format!("cannot read {}", path.display()))?;
            let filename = path
                .file_name()
                .map(|name| name.to_string_lossy().into_owned())
                .unwrap_or_else(|| "file".to_owned());
            let title = title.unwrap_or_else(|| filename.clone());
            (
                NewItem::new(title.clone(), Payload::File { filename, bytes }).with_tags(tag),
                title,
            )
        }
    };

    let id = vault.add(item)?;
    vault.save()?;
    println!("added {description:?} as {id}");
    Ok(())
}

/// Builds a record of a kind that is nothing but its template.
///
/// Every field comes from the template's row: public ones from `--set`, secret
/// ones asked for in the order the row lists them, or read from the variable
/// `--secret-env` names. A name the row does not have is kept as an extra
/// field, the way `edit --set` keeps one.
fn record(kind: ItemKind, args: RecordArgs) -> Result<(NewItem, String)> {
    let template = kind
        .template()
        .with_context(|| format!("a {kind} is not a record"))?;
    let given = assignments("--set", "NAME=VALUE", &args.set)?;
    let from_env = assignments("--secret-env", "NAME=VAR", &args.secret_env)?;
    let secret_names = || {
        template
            .fields
            .iter()
            .filter(|spec| spec.secret)
            .map(|spec| spec.name)
            .collect::<Vec<_>>()
            .join(", ")
    };

    for (name, _) in &given {
        if template.field(name).is_some_and(|spec| spec.secret) {
            bail!(
                "{name} is secret, so it is not taken on the command line\n\
                 leave it to the prompt, or pass --secret-env {name}=VAR"
            );
        }
    }
    for (name, _) in &from_env {
        if template.field(name).is_some_and(|spec| !spec.secret) {
            bail!("{name} is not secret; pass it with --set {name}=VALUE");
        }
    }
    for name in &args.skip {
        if !template.field(name).is_some_and(|spec| spec.secret) {
            bail!(
                "--skip names a secret field of a {kind}, and {name:?} is not one; \
                 those are: {}",
                secret_names()
            );
        }
    }

    let mut fields = Vec::new();
    for spec in template.fields {
        if spec.secret {
            if args.skip.iter().any(|name| name == spec.name) {
                continue;
            }
            let value = match from_env.iter().find(|(name, _)| name == spec.name) {
                Some((_, variable)) => session::secret("", Some(variable))?,
                None => session::secret(
                    &format!("{} ({}; empty to leave out): ", spec.name, spec.description),
                    None,
                )?,
            };
            push_typed(&mut fields, spec.name, value)?;
        } else if let Some((_, value)) = given.iter().find(|(name, _)| name == spec.name) {
            fields.push(Field::public(spec.name, checked(spec.name, value.clone())?));
        }
    }
    for (name, value) in &given {
        if template.field(name).is_none() {
            fields.push(Field::public(name.clone(), checked(name, value.clone())?));
        }
    }
    for (name, variable) in &from_env {
        if template.field(name).is_none() {
            push_typed(&mut fields, name, session::secret("", Some(variable))?)?;
        }
    }

    if fields.is_empty() {
        bail!("a {kind} needs at least one field; nothing was given or typed");
    }
    Ok((
        NewItem::new(args.title.clone(), Payload::fields(kind, fields)).with_tags(args.tag),
        args.title,
    ))
}

/// Adds a secret that was typed or read from a variable, unless it was empty.
///
/// Nothing typed is nothing stored: "no PIN" and "a PIN that is the empty
/// string" are different facts, and only the first is ever meant.
fn push_typed(fields: &mut Vec<Field>, name: &str, value: String) -> Result<()> {
    if !value.is_empty() {
        fields.push(Field::secret(name, checked(name, value)?));
    }
    Ok(())
}

/// Splits `NAME=VALUE` options, refusing a malformed one or a name given twice.
fn assignments(option: &str, shape: &str, raw: &[String]) -> Result<Vec<(String, String)>> {
    let mut pairs: Vec<(String, String)> = Vec::new();
    for assignment in raw {
        let (name, value) = assignment
            .split_once('=')
            .filter(|(name, _)| !name.is_empty())
            .with_context(|| format!("{option} takes {shape}, not {assignment:?}"))?;
        if pairs.iter().any(|(seen, _)| seen == name) {
            bail!("{option} names {name:?} twice");
        }
        pairs.push((name.to_owned(), value.to_owned()));
    }
    Ok(pairs)
}

/// Checks a value on its way into a field, for the fields that have a shape:
/// a one-time password key, and the date a record stops working. The core
/// says which and how, so every way a value arrives holds it to the same.
fn checked(name: &str, value: String) -> Result<String> {
    Ok(sefy_core::model::normalize_value(name, &value)?)
}

/// Says, on stderr, that a record is past or near the last day it works.
///
/// Said where a secret is taken, because that is when it matters: a token
/// that stopped working last week is why the command about to use it will
/// fail. On stderr, so a pipe still receives the secret alone.
fn warn_if_due(item: &Item) {
    if let Some(warning) = due(item, now()) {
        eprintln!("warning: {warning}");
    }
}

/// What [`warn_if_due`] says about `item` at `now`, if anything.
fn due(item: &Item, now: i64) -> Option<String> {
    let sefy_core::expiry::Stated::Date(date) = sefy_core::expiry::of(&item.payload)? else {
        return None;
    };
    let days = date.days_left(now);
    (days <= sefy_core::expiry::SOON_DAYS).then(|| {
        format!(
            "{:?} {} ({date})",
            item.summary.title,
            crate::when::due(days)
        )
    })
}

/// The value an item hands over, and the name of what was taken.
///
/// One answer for `get` and `run`: a note gives its text, a record the field
/// named or else the one its kind is mostly about. A file and a kind this
/// build does not know give nothing — each with the way to what was meant.
/// `naming` is how the caller's command line names a field, for the messages.
fn value_of(item: &Item, field: Option<&str>, naming: &str) -> Result<(String, String)> {
    let title = &item.summary.title;
    match &item.payload {
        // A field named on a note is refused rather than ignored: whoever
        // named one expected a record, and the text may not be what they
        // meant to hand over.
        Payload::Note { text } => match field {
            None => Ok((text.clone(), "text".to_owned())),
            Some(_) => bail!("{title:?} is a note, which has no fields; leave out {naming}"),
        },
        Payload::Fields { kind, fields } => {
            let name = match field {
                Some(name) => name,
                // Nothing was named, so sefy takes what the kind is mostly
                // about. A record whose fields are all public has no such
                // field, and guessing at one would hand over the wrong value.
                None => kind
                    .template()
                    .and_then(|template| template.default_field())
                    .map(|field| field.name)
                    .with_context(|| {
                        format!("{title:?} has no default field; name one with {naming}")
                    })?,
            };
            match fields.iter().find(|field| field.name == name) {
                Some(field) => Ok((field.value.clone(), field.name.clone())),
                None => bail!(
                    "{title:?} has no {name:?}; it holds: {}",
                    field_names(fields)
                ),
            }
        }
        Payload::File { .. } => bail!(
            "{title:?} is a file; write it to disk with: sefy extract {}",
            item.summary.id
        ),
        Payload::Unknown { kind } => bail!(
            "{title:?} is a {kind}, which this version of sefy does not know\n\
             it was written by a newer sefy — upgrade to read it\n\
             (the item is safe: it is listed, exported and synced as it is)"
        ),
    }
}

/// Copies a secret to the clipboard, or prints it when asked to.
pub fn get(vault: &Vault, args: GetArgs) -> Result<()> {
    let summary = vault.resolve(&args.reference).map_err(output::explain)?;
    let item = vault.get(summary.id)?;
    let (value, description) = value_of(&item, args.field.as_deref(), "--field")?;
    warn_if_due(&item);

    if args.stdout {
        println!("{value}");
        return Ok(());
    }

    if args.clear_after > 0 {
        // Said before the wait, not after: the user needs to know why the
        // command is sitting there.
        println!(
            "copied {description} of {:?} to the clipboard; clearing in {}s",
            item.summary.title, args.clear_after
        );
    } else {
        println!(
            "copied {description} of {:?} to the clipboard",
            item.summary.title
        );
    }
    flush_stdout();

    let hold = output::to_clipboard(&value, args.clear_after)?;
    if hold.cleared {
        println!("clipboard cleared");
    }
    Ok(())
}

/// Generates a password or a passphrase, keeps it if asked, and hands it over.
///
/// `vault` is there exactly when `--save` is. The record is written before the
/// value goes to the clipboard: a clipboard that cannot be reached must not
/// cost a password the site has already accepted. It is synced before then
/// too, when syncing after a write is on: the clipboard wait can be long and
/// is often cut short, and the record should not wait on it.
pub fn generate(vault: Option<&mut Vault>, args: GenArgs, auto: &mut AutoSync) -> Result<()> {
    let recipe = if let Some(count) = args.words {
        Recipe::Words {
            count,
            language: args.lang.into(),
            separator: args.separator.clone(),
        }
    } else if args.pronounceable {
        Recipe::Pronounceable {
            length: args.length,
        }
    } else {
        Recipe::Characters {
            length: args.length,
            classes: Classes {
                uppercase: !args.no_uppercase,
                digits: !args.no_digits,
                symbols: !args.no_symbols,
            },
        }
    };
    let generated = sefy_core::generate(&recipe)?;

    // What the password must not lean on: the words of the record it is for.
    let context: Vec<&str> = [
        args.save.as_deref(),
        args.login.as_deref(),
        args.url.as_deref(),
    ]
    .into_iter()
    .flatten()
    .collect();
    let strength = sefy_core::estimate_generated(&generated.value, generated.bits, &context);

    let unit = match recipe {
        Recipe::Words { count, .. } => format!("{count} words"),
        _ => format!("{} characters", generated.value.chars().count()),
    };
    let mut description = format!(
        "generated {unit}: {:.0} bits of entropy, strength {}/{}",
        generated.bits,
        strength.score,
        Strength::MAX_SCORE
    );
    if let Some(warning) = &strength.warning {
        description.push_str(&format!(" - {warning}"));
    }

    // Under --stdout everything but the secret goes to stderr, so a pipe
    // receives the secret and nothing else.
    let say = |line: &str| {
        if args.stdout {
            eprintln!("{line}");
        } else {
            println!("{line}");
        }
    };

    if let (Some(vault), Some(title)) = (vault, &args.save) {
        let mut fields = Vec::new();
        push_optional(&mut fields, "login", args.login.clone(), false);
        fields.push(Field::secret("password", generated.value.as_str()));
        push_optional(&mut fields, "url", args.url.clone(), false);
        let id = vault.add(
            NewItem::new(title.clone(), Payload::fields(ItemKind::Login, fields))
                .with_tags(args.tag.clone()),
        )?;
        vault.save()?;
        say(&format!("added {title:?} as {id}"));
        auto.catch_up(vault);
    }
    say(&description);
    if generated.bits < sefy_core::generate::OFFLINE_BITS {
        say(&format!(
            "under {:.0} bits: fine behind a site that limits sign-in attempts, \
             too few for a master password; add length or words",
            sefy_core::generate::OFFLINE_BITS
        ));
    }

    if args.stdout {
        println!("{}", generated.value.as_str());
        return Ok(());
    }

    if args.clear_after > 0 {
        println!(
            "copied it to the clipboard; clearing in {}s",
            args.clear_after
        );
    } else {
        println!("copied it to the clipboard");
    }
    flush_stdout();

    let hold = output::to_clipboard(&generated.value, args.clear_after)?;
    if hold.cleared {
        println!("clipboard cleared");
    }
    Ok(())
}

/// Makes sure a message is on screen before a wait, not buffered behind it.
fn flush_stdout() {
    use std::io::Write;
    let _ = std::io::stdout().flush();
}

/// Shows an item's fields, keeping its secrets hidden.
pub fn show(vault: &Vault, reference: &str) -> Result<()> {
    let summary = vault.resolve(reference).map_err(output::explain)?;
    let item = vault.get(summary.id)?;

    field("id", &item.summary.id.to_string());
    field("title", &item.summary.title);
    field("kind", item.summary.kind.as_str());
    if !item.summary.tags.is_empty() {
        field("tags", &item.summary.tags.join(", "));
    }
    // Said only when there is something to go back to: a line announcing an
    // empty history on every item would be noise on the common case.
    let earlier = vault.earlier_versions(item.summary.id)?;
    if earlier > 0 {
        field(
            "history",
            &format!(
                "{} (sefy history {})",
                output::count(earlier, "earlier version"),
                item.summary.id
            ),
        );
    }

    match &item.payload {
        Payload::Note { text } => {
            println!("---");
            println!("{text}");
        }
        Payload::Fields { fields, .. } => {
            for stored in fields {
                if stored.name == sefy_core::otp::FIELD {
                    // The key is rarely what is wanted; the code it makes is.
                    field(&stored.name, "<hidden — sefy otp gives the code>");
                } else if stored.secret {
                    // Never printed here; `sefy get` is the one way a secret
                    // leaves, and it says which field to ask for by name.
                    field(
                        &stored.name,
                        &format!("<hidden — use sefy get --field {}>", stored.name),
                    );
                } else if stored.name == sefy_core::expiry::FIELD
                    && let Some(date) = sefy_core::Expiry::parse(&stored.value)
                {
                    // The distance is the part that is read; the date is
                    // what was written.
                    let days = date.days_left(now());
                    let distance = if days < 0 {
                        crate::when::due(days)
                    } else {
                        crate::when::days_away(days)
                    };
                    field(&stored.name, &format!("{} ({distance})", stored.value));
                } else {
                    field(&stored.name, &stored.value);
                }
            }
        }
        Payload::File { filename, bytes } => {
            field("file", filename);
            field("size", &format!("{} bytes", bytes.len()));
        }
        Payload::Unknown { kind } => {
            println!("---");
            println!("This item is a {kind}, a kind this version of sefy does not know.");
            println!("A newer sefy wrote it. Upgrade to read its contents.");
            println!("Nothing is lost: the item keeps its place in this vault.");
        }
    }
    Ok(())
}

/// Prints one labelled line of `sefy show`, aligned to a fixed column.
///
/// A single place to pad from: hand-spaced labels drift the moment one of them
/// is longer than the rest, and `password` already had. The width leaves a
/// space after the longest label rather than butting against it.
fn field(label: &str, value: &str) {
    // Wide enough for the longest label any built-in template uses; a longer
    // one from a field the user named themselves simply pushes its own value
    // along rather than shifting every other line.
    const LABEL_WIDTH: usize = "private-key:".len() + 1;
    println!("{:<LABEL_WIDTH$}{value}", format!("{label}:"));
}

/// Adds a field when the user gave a value for it, and leaves it out when not.
///
/// An absent option stays absent rather than being stored empty: "this login
/// has no URL" and "its URL is the empty string" are different facts, and only
/// the first one is true.
fn push_optional(fields: &mut Vec<Field>, name: &str, value: Option<String>, secret: bool) {
    if let Some(value) = value {
        fields.push(if secret {
            Field::secret(name, value)
        } else {
            Field::public(name, value)
        });
    }
}

/// The path a public key conventionally sits at, beside its private half.
fn sibling_public_key(private_key: &Path) -> PathBuf {
    let mut name = private_key.as_os_str().to_os_string();
    name.push(".pub");
    PathBuf::from(name)
}

/// Names of a record's fields, for a message that says what is on offer.
fn field_names(fields: &[Field]) -> String {
    fields
        .iter()
        .map(|field| field.name.as_str())
        .collect::<Vec<_>>()
        .join(", ")
}

/// Lists items, optionally narrowed by kind and tags.
pub fn ls(vault: &Vault, args: ListArgs) -> Result<()> {
    let mut query = Query::all().tags(args.tag);
    if let Some(kind) = args.kind {
        query = query.kind(kind.into());
    }
    output::table(&vault.search(&query)?);
    Ok(())
}

/// Searches items by text, kind and tags.
pub fn find(vault: &Vault, args: FindArgs) -> Result<()> {
    let mut query = Query::all().tags(args.tag);
    if let Some(text) = args.text {
        query = query.text(text);
    }
    if let Some(kind) = args.kind {
        query = query.kind(kind.into());
    }
    // Always a listing. `find` is what a script calls, and a command that
    // printed a table into a pipe but opened a menu on a terminal would be two
    // commands wearing one name. Browsing is `sefy` with no arguments.
    output::table(&vault.search(&query)?);
    Ok(())
}

/// Browses the vault: pick an item, then show it.
///
/// What `sefy` with no subcommand does. The command line is exact and
/// remembering is not - this is the way in for "it is in there somewhere",
/// and it is a separate command rather than a mode of `find` so that neither
/// has to ask where it is running.
pub fn browse(vault: &Vault) -> Result<()> {
    if !crate::picker::available() {
        bail!(
            "sefy with no command opens an interactive picker, and this is not a terminal\n\
             list items with: sefy ls"
        );
    }
    pick_from(vault, &vault.list()?)
}

/// Shows the picker over `items` and acts on what comes back.
///
/// Acting means `show`: the item without its secrets. Copying the password
/// straight to the clipboard would be the quicker path and the wrong default -
/// the picker is also how someone browses their own vault, and browsing should
/// not leave a secret on the clipboard of a machine they were only looking at.
pub fn pick_from(vault: &Vault, items: &[ItemSummary]) -> Result<()> {
    if items.is_empty() {
        println!("no items");
        return Ok(());
    }

    let Some(picked) = crate::picker::choose(items, "Item")? else {
        // Escape. Nothing to say - the user closed a menu.
        return Ok(());
    };

    show(vault, &picked.id.to_string())
}

/// Changes an item's title, contents or tags.
pub fn edit(vault: &mut Vault, args: EditArgs) -> Result<()> {
    let summary = vault.resolve(&args.reference).map_err(output::explain)?;
    let existing = vault.get(summary.id)?;

    let payload = build_edited_payload(&existing.payload, &args)?;
    let tags = if args.clear_tags {
        Some(Vec::new())
    } else if args.tag.is_empty() {
        None
    } else {
        Some(args.tag.clone())
    };

    if args.title.is_none() && payload.is_none() && tags.is_none() {
        bail!("nothing to change; pass --title, --tag, or a field to edit");
    }

    vault.update(summary.id, args.title, payload, tags)?;
    vault.save()?;
    println!("updated {}", summary.id);
    Ok(())
}

/// Applies the edit flags to an item's current payload.
///
/// Returns `None` when no flag touches the payload, so the item keeps what it
/// has. Flags meant for another kind of item are an error rather than a silent
/// no-op.
fn build_edited_payload(existing: &Payload, args: &EditArgs) -> Result<Option<Payload>> {
    let touches_fields =
        !args.set.is_empty() || !args.set_secret.is_empty() || !args.unset.is_empty();

    match existing {
        Payload::Note { text: current } => {
            if touches_fields {
                bail!("this item is a note; --set, --set-secret and --unset apply to records");
            }
            if args.editor {
                return Ok(Some(Payload::Note {
                    text: crate::editor::edit(current)?,
                }));
            }
            Ok(args.text.clone().map(|text| Payload::Note { text }))
        }
        Payload::Fields { kind, fields } => {
            if args.text.is_some() || args.editor {
                bail!("this item is a {kind}; --text and --editor apply to notes");
            }
            if !touches_fields {
                return Ok(None);
            }
            Ok(Some(Payload::Fields {
                kind: kind.clone(),
                fields: edit_fields(kind, fields, args)?,
            }))
        }
        Payload::File { .. } => {
            if args.text.is_some() || args.editor || touches_fields {
                bail!("this item is a file; only --title and tags can be edited");
            }
            Ok(None)
        }
        // Title and tags live beside the contents, not inside them, so they can
        // still be changed — returning `None` here leaves the payload alone and
        // lets the caller apply them. Anything that would rewrite the contents
        // is refused: this build cannot read them and must not replace them.
        Payload::Unknown { kind } => {
            if args.text.is_some() || args.editor || touches_fields {
                bail!(
                    "this item is a {kind}, a kind this version of sefy does not know;\n\
                     only --title and tags can be edited"
                );
            }
            Ok(None)
        }
    }
}

/// Applies `--set`, `--set-secret` and `--unset` to a record's fields.
///
/// A field keeps its place: an edit changes what a record says, not the order
/// it reads in. A field that is new lands at the end, unless the kind's
/// template has an opinion about where it belongs.
fn edit_fields(kind: &ItemKind, existing: &[Field], args: &EditArgs) -> Result<Vec<Field>> {
    let mut fields = existing.to_vec();

    for assignment in &args.set {
        let (name, value) = assignment
            .split_once('=')
            .with_context(|| format!("--set takes NAME=VALUE, not {assignment:?}"))?;
        // A value passed on the command line is public by default: it has
        // already been through the shell history, so calling it secret would
        // be a promise sefy cannot keep. An existing field keeps whatever
        // secrecy it was stored with — the user is changing the value, not
        // declaring the field harmless.
        set_field(
            kind,
            &mut fields,
            name,
            checked(name, value.to_owned())?,
            None,
        );
    }

    for name in &args.set_secret {
        let value = session::secret(&format!("New value for {name}: "), None)?;
        set_field(kind, &mut fields, name, checked(name, value)?, Some(true));
    }

    for name in &args.unset {
        let before = fields.len();
        fields.retain(|field| &field.name != name);
        if fields.len() == before {
            bail!(
                "no field named {name:?}; it holds: {}",
                field_names(existing)
            );
        }
    }

    if fields.is_empty() {
        bail!("a {kind} cannot be left without any field");
    }
    Ok(fields)
}

/// Writes one field, in place if it is already there and at the end if not.
fn set_field(
    kind: &ItemKind,
    fields: &mut Vec<Field>,
    name: &str,
    value: String,
    secret: Option<bool>,
) {
    if let Some(field) = fields.iter_mut().find(|field| field.name == name) {
        field.value = value;
        if let Some(secret) = secret {
            field.secret = secret;
        }
        return;
    }

    // A name the template knows brings the template's idea of secrecy with it,
    // so `--set totp=…` on a login is hidden without having to be told.
    let secret = secret.unwrap_or_else(|| {
        kind.template()
            .and_then(|template| template.field(name))
            .is_some_and(|field| field.secret)
    });
    fields.push(Field {
        name: name.to_owned(),
        value,
        secret,
    });
}

/// Lists the versions of an item's contents, or compares one with now.
pub fn history(vault: &Vault, args: HistoryArgs) -> Result<()> {
    let summary = vault.resolve(&args.reference).map_err(output::explain)?;
    refuse_unknown(&summary)?;
    let versions = vault.history(summary.id)?;

    match args.version {
        None => list_versions(&summary, &versions),
        Some(number) => {
            let index = version_index(&summary, &versions, number)?;
            compare_with_now(&summary, &versions, index);
        }
    }
    Ok(())
}

/// Brings back an earlier version of an item's contents, or one field of it.
pub fn restore(vault: &mut Vault, args: RestoreArgs) -> Result<()> {
    let summary = vault.resolve(&args.reference).map_err(output::explain)?;
    refuse_unknown(&summary)?;
    let versions = vault.history(summary.id)?;
    let index = version_index(&summary, &versions, args.version)?;
    let wanted = &versions[index];
    let title = &summary.title;

    if wanted.current {
        println!(
            "version {} is what {title:?} holds now; nothing to restore",
            args.version
        );
        return Ok(());
    }
    if let Some(name) = &args.field
        && !matches!(wanted.payload, Payload::Fields { .. })
    {
        bail!(
            "{title:?} is a {}, which is restored whole; leave out --field {name}",
            summary.kind
        );
    }

    let changed = match vault.restore(summary.id, &wanted.uuid, args.field.as_deref()) {
        Ok(changed) => changed,
        Err(sefy_core::Error::FieldNotInVersion { name, available }) => bail!(
            "version {} of {title:?} has no {name:?}; it held: {}",
            args.version,
            available.join(", ")
        ),
        Err(other) => return Err(other.into()),
    };
    if !changed {
        println!(
            "nothing to restore: {title:?} already holds what version {} did{}",
            args.version,
            args.field
                .as_deref()
                .map(|name| format!(" in {name}"))
                .unwrap_or_default()
        );
        return Ok(());
    }
    vault.save()?;

    let what = match &args.field {
        Some(name) => format!("the {name} of {title:?}"),
        None => format!("{title:?}"),
    };
    println!(
        "restored {what} from version {} ({})",
        args.version,
        written(wanted)
    );
    println!(
        "what it replaced is kept as version {}; sefy history {} lists them",
        versions.len(),
        summary.id
    );
    Ok(())
}

/// Stops at an item whose contents this build cannot read.
fn refuse_unknown(summary: &ItemSummary) -> Result<()> {
    if !summary.kind.is_known() {
        bail!(
            "{:?} is a {}, which this version of sefy does not know\n\
             it was written by a newer sefy — upgrade to read its history",
            summary.title,
            summary.kind
        );
    }
    Ok(())
}

/// Turns the number a listing showed into a place in the history.
fn version_index(summary: &ItemSummary, versions: &[Version], number: usize) -> Result<usize> {
    if number == 0 || number > versions.len() {
        bail!(
            "{:?} has {}, numbered from 1; there is no version {number}",
            summary.title,
            output::count(versions.len(), "version")
        );
    }
    Ok(number - 1)
}

/// When and where a version was written, for a line about it.
fn written(version: &Version) -> String {
    match &version.device {
        Some(device) => format!(
            "written {} on {device}",
            crate::when::date_time(version.made_at)
        ),
        None => format!("written {}", crate::when::date_time(version.made_at)),
    }
}

/// Prints one line per version, oldest first: when, where, and what changed.
fn list_versions(summary: &ItemSummary, versions: &[Version]) {
    println!(
        "{:?} ({}), {}",
        summary.title,
        summary.kind,
        output::count(versions.len(), "version")
    );
    println!();

    let number_width = versions.len().to_string().len();
    let device_width = versions
        .iter()
        .map(|version| {
            version
                .device
                .as_deref()
                .map_or(1, |name| name.chars().count())
        })
        .max()
        .unwrap_or(1);

    for (index, version) in versions.iter().enumerate() {
        let mut what = if index == 0 {
            // The first kept version is the item's creation only if it is
            // dated then; one migrated from before history is simply the
            // earliest there is.
            if version.made_at == summary.created_at {
                "created".to_owned()
            } else {
                "earliest kept".to_owned()
            }
        } else {
            let names = sefy_core::history::changed(&versions[index - 1].payload, &version.payload);
            if names.is_empty() {
                "no change".to_owned()
            } else {
                names.join(", ")
            }
        };
        if version.conflict {
            what.push_str("  (lost a merge conflict)");
        }
        if version.current {
            what.push_str("  (current)");
        }
        println!(
            "  {:>number_width$}  {}  {:<device_width$}  {what}",
            index + 1,
            crate::when::date_time(version.made_at),
            version.device.as_deref().unwrap_or("-"),
        );
    }

    if versions.len() > 1 {
        println!();
        println!(
            "compare one with now: sefy history {id} VERSION\n\
             bring one back:       sefy restore {id} VERSION{by_field}",
            id = summary.id,
            by_field = if summary.kind.is_record() {
                " [--field NAME]"
            } else {
                ""
            }
        );
    } else {
        println!();
        println!("no earlier versions yet; the next change to its contents keeps this one");
    }
}

/// Shows how one version differs from the current contents, part by part.
///
/// A secret is only ever said to differ. Text — a note, a public field, a file
/// name — is shown line by line, with long unchanged stretches folded.
fn compare_with_now(summary: &ItemSummary, versions: &[Version], index: usize) {
    let then = &versions[index];
    let now = versions
        .last()
        .expect("history ends with the current version");
    let number = index + 1;

    if then.current {
        println!(
            "version {number} is what {:?} holds now; there is nothing to compare it with",
            summary.title
        );
        return;
    }
    println!(
        "version {number} of {:?}, {}, against what it holds now (version {}):",
        summary.title,
        written(then),
        versions.len()
    );
    println!();

    let changes: Vec<Change> = sefy_core::history::compare(&then.payload, &now.payload);
    let width = changes
        .iter()
        .map(|change| change.name.chars().count())
        .max()
        .unwrap_or(0);

    for change in &changes {
        let label = format!("{:<width$}", change.name);
        match (change.kind, change.secret) {
            (ChangeKind::Same, _) => println!("{label}  same"),
            (ChangeKind::Changed, true) => {
                println!(
                    "{label}  {}",
                    secret_difference(change, &then.payload, &now.payload)
                );
            }
            (ChangeKind::Removed, true) => println!("{label}  only in version {number} (secret)"),
            (ChangeKind::Added, true) => println!("{label}  only now (secret)"),
            (ChangeKind::Changed, false) => {
                println!("{label}  changed");
                let old = sefy_core::history::text_of(&then.payload, &change.name).unwrap_or("");
                let new = sefy_core::history::text_of(&now.payload, &change.name).unwrap_or("");
                crate::diff::print(&sefy_core::history::lines(old, new));
            }
            (ChangeKind::Removed, false) => {
                println!("{label}  only in version {number}");
                let old = sefy_core::history::text_of(&then.payload, &change.name).unwrap_or("");
                crate::diff::print(&sefy_core::history::lines(old, ""));
            }
            (ChangeKind::Added, false) => {
                println!("{label}  only now");
                let new = sefy_core::history::text_of(&now.payload, &change.name).unwrap_or("");
                crate::diff::print(&sefy_core::history::lines("", new));
            }
        }
    }

    if changes.iter().any(|change| change.kind != ChangeKind::Same) {
        println!();
        println!(
            "bring it back: sefy restore {} {number}{}",
            summary.id,
            if matches!(then.payload, Payload::Fields { .. }) {
                " [--field NAME]"
            } else {
                ""
            }
        );
    }
}

/// How a secret part differs, without a word of what it holds.
///
/// A file's bytes are the one secret part whose size is worth saying: it tells
/// two versions of a key file apart without showing either.
fn secret_difference(change: &Change, then: &Payload, now: &Payload) -> String {
    match (then, now) {
        (Payload::File { bytes: old, .. }, Payload::File { bytes: new, .. })
            if change.name == "contents" =>
        {
            format!(
                "changed ({} then, {} now)",
                output::count(old.len(), "byte"),
                output::count(new.len(), "byte")
            )
        }
        _ => "changed (secret, not shown)".to_owned(),
    }
}

/// Removes an item, asking first unless told not to.
pub fn rm(vault: &mut Vault, reference: &str, yes: bool) -> Result<()> {
    let summary = vault.resolve(reference).map_err(output::explain)?;

    // The history goes with the item, and a question that did not say so
    // would be asking about less than it removes.
    let earlier = vault.earlier_versions(summary.id)?;
    let and_history = if earlier > 0 {
        format!(" and {}", output::count(earlier, "earlier version"))
    } else {
        String::new()
    };
    if !yes
        && !confirm(&format!(
            "remove {:?} ({}){and_history}? [y/N] ",
            summary.title, summary.id
        ))?
    {
        println!("kept");
        return Ok(());
    }

    vault.remove(summary.id)?;
    vault.save()?;
    println!("removed {}", summary.id);
    Ok(())
}

/// Writes a stored file back to disk.
pub fn extract(
    vault: &Vault,
    reference: &str,
    output_path: Option<PathBuf>,
    force: bool,
) -> Result<()> {
    let summary = vault.resolve(reference).map_err(output::explain)?;
    let item = vault.get(summary.id)?;

    let Payload::File { filename, bytes } = &item.payload else {
        bail!(
            "{:?} is a {}, not a file",
            item.summary.title,
            item.summary.kind
        );
    };

    let destination = output_path.unwrap_or_else(|| PathBuf::from(filename));
    if destination.exists() && !force {
        bail!(
            "{} already exists; pass --force to overwrite",
            destination.display()
        );
    }

    std::fs::write(&destination, bytes)
        .with_context(|| format!("cannot write {}", destination.display()))?;
    println!("wrote {} ({} bytes)", destination.display(), bytes.len());
    Ok(())
}

/// Lists the tags in use with their item counts.
pub fn tags(vault: &Vault) -> Result<()> {
    let tags = vault.tags()?;
    if tags.is_empty() {
        println!("no tags");
        return Ok(());
    }
    let width = tags
        .iter()
        .map(|(name, _)| name.chars().count())
        .max()
        .unwrap_or(4);
    for (name, count) in tags {
        println!("{name:<width$}  {count}");
    }
    Ok(())
}

/// Writes the vault's contents out in the clear, in the chosen format.
pub fn export(
    vault: &Vault,
    output_path: Option<PathBuf>,
    format: ExportFormat,
    with_history: bool,
    acknowledged: bool,
    force: bool,
) -> Result<()> {
    if !acknowledged {
        bail!(
            "export writes every secret in this vault in the clear\n\
             the resulting file protects nothing - encrypt it, or delete it when done\n\
             pass --i-know-this-writes-plaintext to go ahead"
        );
    }
    let target = match (format, with_history) {
        (ExportFormat::Sefy, history) => Target::Sefy { history },
        (ExportFormat::Keepass, history) => Target::KeePass { history },
        (ExportFormat::Csv, false) => Target::Csv,
        (ExportFormat::Csv, true) => bail!(
            "a CSV has no place for earlier versions\n\
             use --format keepass or --format sefy to carry them"
        ),
    };
    if let Some(path) = &output_path
        && path.exists()
        && !force
    {
        bail!(
            "{} already exists; pass --force to overwrite",
            path.display()
        );
    }

    let exported = sefy_core::exchange::export(vault, target)?;
    let report = &exported.report;

    match &output_path {
        Some(path) => {
            std::fs::write(path, exported.text.as_bytes())
                .with_context(|| format!("cannot write {}", path.display()))?;
            let mut written = output::count(report.written, "item");
            if report.versions > 0 {
                written.push_str(&format!(
                    " and {}",
                    output::count(report.versions, "earlier version")
                ));
            }
            eprintln!("wrote {} in the clear: {written}", path.display());
        }
        None => println!("{}", exported.text.as_str()),
    }

    // On stderr either way, so a pipe receives the file and nothing else.
    if !report.left_out.is_empty() {
        let kinds: Vec<String> = report
            .left_out
            .iter()
            .map(|(kind, count)| output::count(*count, kind.as_str()))
            .collect();
        eprintln!(
            "left out: {} - {} holds logins only; --format keepass carries every kind",
            kinds.join(", "),
            target.name()
        );
    }
    if report.trimmed > 0 {
        eprintln!(
            "{} {} fields a CSV has no column for; those fields are left out",
            output::count(report.trimmed, "login"),
            if report.trimmed == 1 { "has" } else { "have" }
        );
    }
    if report.unreadable > 0 {
        let what = match target {
            Target::Sefy { .. } => "written without its contents",
            _ => "left out",
        };
        eprintln!(
            "{} of a kind this version of sefy does not know: {what}",
            output::count(report.unreadable, "item")
        );
    }
    Ok(())
}

/// Adds what another sefy, a password manager or a browser exported.
pub fn import(vault: &mut Vault, input: Option<PathBuf>) -> Result<()> {
    let bytes = Zeroizing::new(match &input {
        Some(path) => {
            std::fs::read(path).with_context(|| format!("cannot read {}", path.display()))?
        }
        None => {
            let mut bytes = Vec::new();
            std::io::stdin()
                .read_to_end(&mut bytes)
                .context("cannot read the file to import from stdin")?;
            bytes
        }
    });
    let text = std::str::from_utf8(&bytes).map_err(|_| {
        anyhow::anyhow!(
            "the file is not UTF-8 text\n\
             save it again as UTF-8 - spreadsheet programs offer it as \"CSV UTF-8\""
        )
    })?;

    let report = sefy_core::exchange::import(vault, text)?;

    let added = report.added_total();
    let mut line = format!(
        "imported {} from {}",
        output::count(added, "item"),
        report.format.describe()
    );
    if added > 0 {
        let kinds: Vec<String> = report
            .added
            .iter()
            .map(|(kind, count)| output::count(*count, kind.as_str()))
            .collect();
        line.push_str(&format!(": {}", kinds.join(", ")));
    }
    println!("{line}");
    if report.versions > 0 {
        println!(
            "with {} kept in their history",
            output::count(report.versions, "earlier version")
        );
    }
    if report.skipped > 0 {
        // Silence here would read as "imported nothing" on a re-import, when
        // what actually happened is that the vault already had it all.
        println!(
            "{} already here, left alone",
            output::count(report.skipped, "item")
        );
    }

    for (outcome, heading) in [
        (Outcome::NotImported, "not imported:"),
        (Outcome::InPart, "imported in part:"),
        (Outcome::Reshaped, "imported in another shape:"),
    ] {
        let notices: Vec<_> = report
            .notices
            .iter()
            .filter(|notice| notice.outcome == outcome)
            .collect();
        if notices.is_empty() {
            continue;
        }
        println!("{heading}");
        for notice in notices {
            println!("  {:?} - {}", notice.title, notice.reason);
        }
    }
    if !report.columns_left_out.is_empty() {
        println!(
            "columns left out as the exporting program's own bookkeeping: {}",
            report.columns_left_out.join(", ")
        );
    }

    if let Some(kept) = &report.kept_copy {
        println!("{}", kept_line(kept));
    }
    if let Some(path) = input {
        println!(
            "{} still holds all of it in the clear; delete it once the import looks right",
            path.display()
        );
    }
    Ok(())
}

/// Folds another vault file into this one, or says what doing so would change.
pub fn merge(
    vault: &mut Vault,
    other: &Path,
    other_password_env: Option<&str>,
    dry_run: bool,
) -> Result<()> {
    if other == vault.path() {
        bail!("that is this vault; merging a file into itself would do nothing");
    }

    // Asked for separately: a copy from another machine may be under a
    // different password, and assuming otherwise would just fail confusingly.
    let password = session::secret(
        &format!("Password for {}: ", other.display()),
        other_password_env,
    )?;
    let source = session::open(other, &password)?;

    if dry_run {
        let report = sefy_core::merge::preview(vault, &source)?;
        println!("here, from {}:", other.display());
        print_lines(&preview_lines(&report, true));
        println!("{NOTHING_DONE}");
        return Ok(());
    }

    let report = sefy_core::merge(vault, &source)?;

    print_lines(&merge_lines(
        &report,
        "nothing to merge; the two vaults already agree",
    ));
    Ok(())
}

/// Replaces the master password and rewrites the file under it.
pub fn change_password(vault: &mut Vault, password_env: Option<&str>) -> Result<()> {
    let password = session::new_password(password_env)?;
    let change = vault.change_password(password.as_bytes())?;
    println!("password changed");
    if change.resealed > 0 {
        println!(
            "{} beside the vault sealed under it too",
            output::count(change.resealed, "copy")
        );
    }
    for left in &change.left {
        // Named rather than deleted: it is not known what it is, only that the
        // old password does not open it.
        println!(
            "{} does not open under the old password and was left as it was",
            left.display()
        );
    }
    // Whoever holds the old password is holding a password that opens nothing
    // here any more, and whose retiring was presumably the point.
    let locked = session::lock_everywhere();
    if !locked.is_empty() {
        println!(
            "locked the {}: it held the old password",
            locked.join(" and the ")
        );
    }
    Ok(())
}

/// Opens an item's site and puts its password on the clipboard.
///
/// The two halves of signing in, in the order they are used: the browser is
/// already loading while the password is waiting to be pasted. Doing it as one
/// command also removes the step where a user goes looking for the URL, finds
/// it with `show`, and copies it by hand from a terminal.
///
/// The clipboard is the same path `get` uses, timeout and all: a password left
/// on the clipboard after the browser is open is exactly the exposure the
/// timeout exists for, and the browser being open does not change it.
pub fn open(vault: &Vault, args: OpenArgs) -> Result<()> {
    let summary = vault.resolve(&args.reference).map_err(output::explain)?;
    let item = vault.get(summary.id)?;

    let Payload::Fields { kind, fields } = &item.payload else {
        bail!(
            "{:?} is a {}, which has no site to open",
            item.summary.title,
            item.summary.kind.as_str()
        );
    };

    let url = fields
        .iter()
        .find(|field| field.name == URL_FIELD)
        .with_context(|| {
            format!(
                "{:?} has no {URL_FIELD:?} field; it holds: {}\n\
                 add one with: sefy edit {} --set url=https://…",
                item.summary.title,
                field_names(fields),
                item.summary.id
            )
        })?;

    crate::browser::open(&url.value)?;
    println!("opened {}", url.value);
    warn_if_due(&item);

    if args.no_password {
        return Ok(());
    }

    // The password is a convenience on top of opening the site, so a record
    // without one is not an error: the site is open, which is what was asked.
    let Some(secret) = kind
        .template()
        .and_then(|template| template.default_field())
        .and_then(|spec| fields.iter().find(|field| field.name == spec.name))
    else {
        return Ok(());
    };

    println!(
        "copied {} of {:?} to the clipboard; clearing in {}s",
        secret.name, item.summary.title, args.clear_after
    );
    flush_stdout();

    let hold = output::to_clipboard(&secret.value, args.clear_after)?;
    if hold.cleared {
        println!("clipboard cleared");
    }
    Ok(())
}

/// Copies a record's current one-time code, storing or drawing its key first
/// when asked.
///
/// `--set` is the moment of enrolment: the site shows a key and asks for the
/// first code to prove it was taken. Storing and answering are one command so
/// the key is in the vault before the site considers two-factor sign-in on.
pub fn otp(vault: &mut Vault, args: OtpArgs, auto: &mut AutoSync) -> Result<()> {
    let summary = vault.resolve(&args.reference).map_err(output::explain)?;
    let item = vault.get(summary.id)?;
    let title = &item.summary.title;
    let Payload::Fields { kind, fields } = &item.payload else {
        bail!(
            "{title:?} is a {}; one-time passwords belong to a record such as a login",
            item.summary.kind
        );
    };
    let mut fields = fields.clone();
    warn_if_due(&item);

    // Under --stdout everything but the code goes to stderr, so a pipe
    // receives the code and nothing else.
    let say = |line: &str| {
        if args.stdout {
            eprintln!("{line}");
        } else {
            println!("{line}");
        }
    };

    if args.set || args.key_env.is_some() {
        let key = session::secret("Setup key or otpauth:// link: ", args.key_env.as_deref())?;
        let key = checked(sefy_core::otp::FIELD, key)?;
        set_field(kind, &mut fields, sefy_core::otp::FIELD, key, Some(true));
        vault.update(
            summary.id,
            None,
            Some(Payload::Fields {
                kind: kind.clone(),
                fields: fields.clone(),
            }),
            None,
        )?;
        vault.save()?;
        say(&format!("stored the one-time password key of {title:?}"));
        // Before the code or the picture: both can wait on the person for a
        // while, and the key should reach the other machines regardless.
        auto.catch_up(vault);
    }

    let stored = fields
        .iter()
        .find(|field| field.name == sefy_core::otp::FIELD)
        .with_context(|| {
            format!(
                "{title:?} has no one-time password key\n\
                 store the one the site shows with: sefy otp {} --set",
                summary.id
            )
        })?;
    let totp = Totp::parse(&stored.value).with_context(|| {
        format!(
            "the {} field of {title:?} cannot make a code\n\
             replace it with: sefy otp {} --set",
            sefy_core::otp::FIELD,
            summary.id
        )
    })?;

    if args.qr {
        let login = fields
            .iter()
            .find(|field| field.name == "login")
            .map(|field| field.value.as_str());
        return crate::qr::show(&totp.link(title, login));
    }

    let now = unix_now()?;
    let code = totp.code_at(now);
    if args.stdout {
        println!("{code}");
        return Ok(());
    }

    let valid = totp.remaining(now);
    if args.clear_after > 0 {
        println!(
            "copied the one-time code of {title:?} to the clipboard; \
             valid for {valid}s, clearing in {}s",
            args.clear_after
        );
    } else {
        println!("copied the one-time code of {title:?} to the clipboard; valid for {valid}s");
    }
    flush_stdout();

    let hold = output::to_clipboard(&code, args.clear_after)?;
    if hold.cleared {
        println!("clipboard cleared");
    }
    Ok(())
}

/// Hands over a record's fields one at a time, Enter between them.
///
/// Which fields, and in what order, is the template's word: a login gives its
/// login, its password and a one-time code, a card its number, holder, the
/// month it runs out and CVV. A one-time code is made when its turn comes rather than up front,
/// so time spent on the fields before it does not eat into its life.
pub fn fill(vault: &Vault, args: FillArgs) -> Result<()> {
    use std::io::IsTerminal;

    let summary = vault.resolve(&args.reference).map_err(output::explain)?;
    let item = vault.get(summary.id)?;
    let title = &item.summary.title;
    let Payload::Fields { kind, fields } = &item.payload else {
        bail!(
            "{title:?} is a {}; fill hands over the fields of a record such as a login",
            item.summary.kind
        );
    };

    let steps: Vec<&Field> = kind
        .template()
        .into_iter()
        .flat_map(|template| template.fill_order())
        .filter_map(|spec| fields.iter().find(|field| field.name == spec.name))
        .collect();
    if steps.is_empty() {
        bail!(
            "{title:?} holds nothing a {kind} fills in; it holds: {}\n\
             take a field with: sefy get {} --field NAME",
            field_names(fields),
            summary.id
        );
    }
    if !std::io::stdin().is_terminal() {
        bail!(
            "fill waits for Enter between fields, and input is not a terminal\n\
             take one field at a time with: sefy get {} --field NAME --stdout",
            summary.id
        );
    }
    warn_if_due(&item);

    let mut clipboard = output::open_clipboard()?;
    let total = steps.len();
    for (index, field) in steps.iter().enumerate() {
        let (value, label) = if field.name == sefy_core::otp::FIELD {
            let totp = Totp::parse(&field.value).with_context(|| {
                format!(
                    "the {} field of {title:?} cannot make a code\n\
                     replace it with: sefy otp {} --set",
                    sefy_core::otp::FIELD,
                    summary.id
                )
            })?;
            let now = unix_now()?;
            (
                totp.code_at(now),
                format!("one-time code (valid for {}s)", totp.remaining(now)),
            )
        } else if field.name == sefy_core::expiry::FIELD
            && let Some(date) = sefy_core::Expiry::parse(&field.value)
        {
            // As printed on a card, which is what a payment form asks for.
            (
                date.printed(),
                format!("{} ({})", field.name, date.printed()),
            )
        } else {
            (field.value.clone(), field.name.clone())
        };
        let position = format!("{}/{total}", index + 1);

        if index + 1 < total {
            clipboard.put(&value)?;
            print!("{position} {label} is on the clipboard; paste it, then press Enter ");
            flush_stdout();
            let mut line = String::new();
            if std::io::stdin().read_line(&mut line)? == 0 {
                // Input closed mid-way: nothing more will be pasted, so what
                // is on the clipboard now has no reason to stay there.
                clipboard.take_back(&value);
                println!();
                bail!("input closed before the last field; the clipboard is cleared");
            }
        } else {
            if args.clear_after > 0 {
                println!(
                    "{position} {label} is on the clipboard; clearing in {}s",
                    args.clear_after
                );
            } else {
                println!("{position} {label} is on the clipboard");
            }
            flush_stdout();
            let hold = clipboard.hold(&value, args.clear_after)?;
            if hold.cleared {
                println!("clipboard cleared");
            }
            break;
        }
    }
    Ok(())
}

/// Starts a command with secrets from the vault in its environment.
///
/// Every variable is settled before anything starts: a reference that matches
/// nothing, or two things, stops the run rather than starting the command with
/// part of what it needs. The vault is closed first, and the variable that
/// carried the master password is left out of the command's environment — the
/// command was given a token, not the key to every other secret.
pub fn run(
    vault: Vault,
    args: RunArgs,
    password_env: Option<&str>,
) -> Result<std::convert::Infallible> {
    let mappings = args
        .env
        .iter()
        .map(|assignment| Mapping::parse(assignment))
        .collect::<Result<Vec<_>>>()?;

    // Compared without case on every system: Windows holds one variable under
    // both spellings, and a script refused here is one that would have lost a
    // value there.
    for (index, mapping) in mappings.iter().enumerate() {
        if let Some(earlier) = mappings[..index]
            .iter()
            .find(|earlier| earlier.variable.eq_ignore_ascii_case(mapping.variable))
        {
            if earlier.variable == mapping.variable {
                bail!("--env sets {} twice", mapping.variable);
            }
            bail!(
                "--env sets {} and {}, which Windows holds as one variable",
                earlier.variable,
                mapping.variable
            );
        }
    }

    let mut set = Vec::with_capacity(mappings.len());
    for mapping in &mappings {
        let value = mapping
            .value(&vault)
            .with_context(|| format!("cannot set {}", mapping.variable))?;
        set.push((mapping.variable.to_owned(), value));
    }
    drop(vault);

    let (program, arguments) = args
        .command
        .split_first()
        .context("no command to run; name one after --")?;
    Ok(crate::launch::replace_with(
        program,
        arguments,
        password_env,
        set,
    )?)
}

/// One `--env VAR=REFERENCE[#FIELD]` of `sefy run`.
struct Mapping<'a> {
    variable: &'a str,
    reference: &'a str,
    field: Option<&'a str>,
}

impl<'a> Mapping<'a> {
    fn parse(assignment: &'a str) -> Result<Self> {
        let malformed = || format!("--env takes VAR=REFERENCE[#FIELD], not {assignment:?}");
        let (variable, target) = assignment
            .split_once('=')
            .filter(|(variable, target)| !variable.is_empty() && !target.is_empty())
            .with_context(malformed)?;
        // The last `#` is the one that splits: no field of a template has one
        // in its name, and a title that does is still reachable by its id.
        let (reference, field) = match target.rsplit_once('#') {
            Some((reference, field)) if !reference.is_empty() && !field.is_empty() => {
                (reference, Some(field))
            }
            Some(_) => bail!(
                "{}\n\
                 a # starts a field name; an item whose title has one is taken by its id",
                malformed()
            ),
            None => (target, None),
        };
        Ok(Self {
            variable,
            reference,
            field,
        })
    }

    fn value(&self, vault: &Vault) -> Result<String> {
        let summary = vault.resolve(self.reference).map_err(output::explain)?;
        let item = vault.get(summary.id)?;
        let (value, name) = value_of(&item, self.field, "#FIELD")?;
        warn_if_due(&item);
        // Refused here rather than left to the system: it would surface as the
        // command failing to start, which points at the command.
        if value.contains('\0') {
            bail!(
                "the {name} of {:?} holds a NUL character, which a variable cannot carry",
                item.summary.title
            );
        }
        Ok(value)
    }
}

/// Seconds since the epoch, for making a one-time code.
///
/// An error rather than a zero when the clock is set before 1970: a code made
/// for the wrong time is not a code, and failing to sign in with it would say
/// nothing about why.
fn unix_now() -> Result<u64> {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|elapsed| elapsed.as_secs())
        .context("the system clock is set before 1970; a one-time code needs the real time")
}

/// The field `sefy open` looks for.
///
/// Named here rather than inline so the templates and this command cannot
/// drift apart silently — a gate checks that every kind which could be opened
/// declares it.
const URL_FIELD: &str = "url";

/// Reports what and where this vault is, without revealing any of it.
///
/// The question it answers is the one 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. Every line is about shape — counts, versions, the
/// last transfer — and never about contents: a status that named an item would
/// put a secret's title on a screen that was asked only whether the vault is
/// there.
///
/// It never asks for the password. With the vault locked and no password given
/// it says what can be said without one: that is the answer to "is it locked",
/// and a command that held that answer back behind a prompt would be asking for
/// the master password of someone who might have asked because they were about
/// to walk away.
pub fn status(path: &Path, password_env: Option<&str>) -> Result<()> {
    let opened = match password_env {
        Some(_) => Some(session::typed(path, password_env)?),
        None => session::looking_through_agent(path)?,
    };
    let Some((vault, master)) = opened else {
        let file =
            std::fs::metadata(path).with_context(|| format!("cannot read {}", path.display()))?;
        println!("vault    {}", path.display());
        println!("size     {}", size(file.len()));
        println!("lock     {}", session::lock_line(path, None)?);
        println!("the rest takes the password: `sefy agent` unlocks the vault for a while");
        return Ok(());
    };

    let status = vault.status()?;
    let stats = &status.stats;

    println!("vault    {}", status.path.display());
    if let Some(bytes) = status.size {
        println!("size     {}", size(bytes));
    }
    println!("lock     {}", session::lock_line(path, Some(&master))?);
    println!(
        "items    {}{}",
        output::count(stats.items, "item"),
        if stats.by_kind.is_empty() {
            String::new()
        } else {
            let breakdown: Vec<String> = stats
                .by_kind
                .iter()
                .map(|(kind, count)| format!("{count} {kind}"))
                .collect();
            format!("  ({})", breakdown.join(", "))
        }
    );
    println!("tags     {}", output::count(stats.tags, "tag"));

    // The schema the file carries, with a word about what it means, because
    // "schema 4" alone tells a user nothing they can act on.
    let schema = if stats.written_by_newer() {
        format!("{} (written by a newer sefy)", stats.schema)
    } else {
        format!("{}", stats.schema)
    };
    println!("schema   {schema}");
    println!("sealed   {}", sealing(&status.sealing));

    match &stats.last_sync {
        Some(stamp) => println!(
            "synced   {} through {} ({})",
            crate::when::moment(stamp.at, now()),
            stamp.transport,
            stamp.operation
        ),
        None => println!("synced   never"),
    }

    println!("copies   {}", copies_line(&status.copies));

    let plugins = sefy_core::plugin::discover_in(&sefy_core::plugin::search_paths());
    if plugins.is_empty() {
        println!("plugins  none installed");
    } else {
        let names: Vec<String> = plugins
            .iter()
            .map(|plugin| {
                if plugin.usable {
                    plugin.name().to_owned()
                } else {
                    format!("{} (unusable)", plugin.name())
                }
            })
            .collect();
        println!("plugins  {}", names.join(", "));
    }

    Ok(())
}

/// How the vault is sealed, in one line: the key derivation and its cost, the
/// cipher, the format.
fn sealing(sealing: &sefy_core::Sealing) -> String {
    format!(
        "{} ({} MiB, {} passes, {} lanes), {}, format v{}",
        sealing.kdf,
        sealing.memory_kib / 1024,
        sealing.passes,
        sealing.lanes,
        sealing.cipher,
        sealing.format
    )
}

/// The copies kept beside a vault, in one phrase: how many, and how old the
/// most recent is.
pub(crate) fn copies_line(copies: &[sefy_core::copies::Copy]) -> String {
    let Some(newest) = copies.first() else {
        return "none yet; one is kept before a merge or an import changes the vault".to_owned();
    };
    let taken = newest
        .taken
        .and_then(|taken| taken.duration_since(std::time::UNIX_EPOCH).ok())
        .map(|elapsed| {
            format!(
                ", newest {}",
                crate::when::moment(elapsed.as_secs() as i64, now())
            )
        })
        .unwrap_or_default();
    format!(
        "{} beside the vault{taken}",
        output::count(copies.len(), "copy")
    )
}

/// A number of bytes, in units a person reads.
pub(crate) fn size(bytes: u64) -> String {
    const KB: u64 = 1024;
    const MB: u64 = 1024 * KB;
    if bytes < KB {
        format!("{bytes} B")
    } else if bytes < MB {
        format!("{:.1} KB", bytes as f64 / KB as f64)
    } else {
        format!("{:.1} MB", bytes as f64 / MB as f64)
    }
}

/// Unix seconds, for rendering how long ago something happened.
pub(crate) fn now() -> i64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|elapsed| elapsed.as_secs() as i64)
        .unwrap_or(0)
}

/// Sends the vault file to the remote.
pub fn push(vault: &mut Vault, args: RemoteArgs) -> Result<()> {
    let plugin = transport(args.transport.as_deref())?;
    let report = sefy_core::push(vault, &plugin, &args.name)?;

    println!("pushed {:?} through {}", args.name, plugin.name());
    if let Some(message) = report.message {
        println!("{message}");
    }
    Ok(())
}

/// Fetches the remote copy and folds it in, or says what that would change.
pub fn pull(vault: &mut Vault, args: PullArgs, master: &Master) -> Result<()> {
    let plugin = transport(args.remote.transport.as_deref())?;
    let remote_password = remote_password(&args)?;
    let opener = opener_of_remote(remote_password.as_ref(), master);
    let name = &args.remote.name;

    if args.dry_run {
        let report = sefy_core::sync::preview_pull(vault, &plugin, name, opener)?;
        println!("here, from {name:?} through {}:", plugin.name());
        print_lines(&preview_lines(&report.merged, true));
        println!("{NOTHING_DONE}");
        return Ok(());
    }

    let report = sefy_core::pull(vault, &plugin, name, opener)?;

    println!("pulled {name:?} through {}", plugin.name());
    if let Some(message) = &report.transport.message {
        println!("{message}");
    }
    print_lines(&merge_lines(&report.merged, NOTHING_CAME_BACK));
    Ok(())
}

/// Pulls, then pushes the result back; or says what each leg would change.
pub fn sync(vault: &mut Vault, args: PullArgs, master: &Master) -> Result<()> {
    let plugin = transport(args.remote.transport.as_deref())?;
    let remote_password = remote_password(&args)?;
    let opener = opener_of_remote(remote_password.as_ref(), master);
    let name = &args.remote.name;

    if args.dry_run {
        let preview = sefy_core::sync::preview_sync(vault, &plugin, name, opener)?;
        println!("here, from {name:?} through {}:", plugin.name());
        print_lines(&preview_lines(&preview.coming, true));
        println!("there, once the result is pushed:");
        print_lines(&preview_lines(&preview.going, false));
        println!("{NOTHING_DONE}");
        return Ok(());
    }

    let report = sefy_core::sync(vault, &plugin, name, opener)?;

    println!("synced {name:?} through {}", plugin.name());
    for message in [
        report.pulled.transport.message.as_deref(),
        report.pushed.message.as_deref(),
    ]
    .into_iter()
    .flatten()
    {
        println!("{message}");
    }
    print_lines(&merge_lines(&report.pulled.merged, NOTHING_CAME_BACK));
    Ok(())
}

/// What a pull or a sync says when the remote held nothing new.
pub(crate) const NOTHING_CAME_BACK: &str = "nothing came back that this vault did not already have";

/// The last line of every dry run.
const NOTHING_DONE: &str = "dry run: nothing was written here or sent anywhere";

/// The master password of the copy on the other side, if it was given.
///
/// A pull brings back a copy of *this* vault, so the same password is the
/// ordinary case and the default. Both ways of saying otherwise are honoured.
fn remote_password(args: &PullArgs) -> Result<Option<Zeroizing<String>>> {
    if let Some(variable) = args.remote_password_env.as_deref() {
        return session::secret("", Some(variable))
            .map(Zeroizing::new)
            .map(Some);
    }
    if args.ask_remote_password {
        return session::secret("Password of the remote copy: ", None)
            .map(Zeroizing::new)
            .map(Some);
    }
    Ok(None)
}

/// What opens the copy on the other side: the password given for it, or what
/// opened this vault.
fn opener_of_remote<'a>(given: Option<&'a Zeroizing<String>>, master: &'a Master) -> Opener<'a> {
    match given {
        Some(password) => Opener::Password(password.as_bytes()),
        None => master.opener(),
    }
}

/// Picks the transport to use.
///
/// Named, or the only one installed. Guessing between several would mean
/// choosing where somebody's vault goes, and a wrong guess there is not a
/// mistake that announces itself.
pub(crate) fn transport(name: Option<&str>) -> Result<sefy_core::Plugin> {
    let installed = sefy_core::plugin::discover();

    if let Some(name) = name {
        let found = sefy_core::plugin::find(installed, name).ok_or_else(|| {
            anyhow::anyhow!(
                "no transport called {name:?}\n\
                     run `sefy plugin list` to see what is installed."
            )
        })?;
        return Ok(found);
    }

    let usable: Vec<sefy_core::Plugin> = installed
        .into_iter()
        .filter(|plugin| plugin.usable)
        .collect();

    match usable.len() {
        0 => bail!(
            "no usable transport installed\n\
             a transport is an executable named {}<name>; `sefy plugin list` \
             says where sefy looks and why anything found is unusable.",
            sefy_core::plugin::PREFIX
        ),
        1 => Ok(usable.into_iter().next().expect("just counted")),
        _ => {
            let names: Vec<&str> = usable.iter().map(sefy_core::Plugin::name).collect();
            bail!(
                "several transports are installed: {}\n\
                 say which one with --transport <NAME>.",
                names.join(", ")
            )
        }
    }
}

/// What a merge did, as lines to print.
///
/// Shared by `merge`, `pull`, `sync` and syncing after a write: the outcome is
/// the same thing in all of them, and a conflict has to read the same way
/// whichever brought it in. Only the line for "the two already agree" differs,
/// since what the user did differs.
///
/// Counts rather than names: a merge after every write would otherwise fill
/// the screen with titles nobody asked about. Naming each item is what
/// `--dry-run` is for. Conflicts are the exception and are always named —
/// they are the one outcome somebody has to look at.
pub(crate) fn merge_lines(report: &sefy_core::MergeReport, nothing_to_do: &str) -> Vec<String> {
    if report.is_empty() {
        return vec![nothing_to_do.to_owned()];
    }

    let mut lines = Vec::new();
    let brought = if report.versions > 0 {
        format!(
            "; {} brought across",
            output::count(report.versions, "earlier version")
        )
    } else {
        String::new()
    };
    lines.push(format!(
        "merged: {} added, {} updated, {} unchanged{brought}",
        report.added.len(),
        report.updated.len(),
        report.unchanged
    ));

    if report.unsupported > 0 {
        lines.push(format!(
            "{} left where it was: a kind this version of sefy does not know.\n\
             Nothing was lost — merge again from a build that knows it.",
            output::count(report.unsupported, "item")
        ));
    }

    if !report.conflicts.is_empty() {
        // Loud on purpose: a conflict means two versions of one secret, and
        // only the person who made them can say which is right. The one that
        // was not chosen is not gone, and this is where they learn where it is.
        lines.push(format!(
            "\n{} changed on both sides.",
            output::count(report.conflicts.len(), "item")
        ));
        lines.push(
            "The copy changed more recently is current; the other is kept in the item's history:"
                .to_owned(),
        );
        for conflict in &report.conflicts {
            let whose = match conflict.current {
                sefy_core::Side::Here => "this vault's is current",
                sefy_core::Side::There => "the other copy's is current",
            };
            lines.push(format!(
                "  {:?} ({whose}): sefy history {}",
                conflict.title, conflict.id
            ));
        }
        lines.push(
            "Compare with sefy history ID VERSION; bring one back with sefy restore ID VERSION."
                .to_owned(),
        );
    }

    if let Some(kept) = &report.kept_copy {
        lines.push(kept_line(kept));
    }
    lines
}

/// What a merge would do, item by item, as indented lines.
///
/// A preview names everything: deciding whether to go ahead is exactly when
/// "3 added" is not enough, and "which three" is the question.
///
/// `here` says whether the report is about this vault. Ids are shown only
/// then: an id in the remote copy names nothing on this machine.
pub(crate) fn preview_lines(report: &sefy_core::MergeReport, here: bool) -> Vec<String> {
    let id = |id: i64| {
        if here {
            format!(" ({id})")
        } else {
            String::new()
        }
    };
    if report.is_empty() {
        return vec!["  nothing would change".to_owned()];
    }

    let mut lines = Vec::new();
    for item in &report.added {
        lines.push(format!("  add       {:?}", item.title));
    }
    for item in &report.updated {
        lines.push(format!("  update    {:?}{}", item.title, id(item.id)));
    }
    for conflict in &report.conflicts {
        let outcome = match conflict.current {
            sefy_core::Side::Here => "keeps its contents; the other side's go to its history",
            sefy_core::Side::There => "takes the other side's contents; its own go to its history",
        };
        lines.push(format!(
            "  conflict  {:?}{} {outcome}",
            conflict.title,
            id(conflict.id)
        ));
    }

    let mut also = Vec::new();
    if report.versions > 0 {
        also.push(format!(
            "{} brought across",
            output::count(report.versions, "earlier version")
        ));
    }
    if report.unsupported > 0 {
        also.push(format!(
            "{} of a kind this sefy does not know left where it is",
            output::count(report.unsupported, "item")
        ));
    }
    also.push(format!("{} unchanged", report.unchanged));
    lines.push(format!("  {}", also.join("; ")));
    lines
}

/// The line naming where a vault was kept before a change.
fn kept_line(kept: &Path) -> String {
    format!("the vault as it was is kept as {}", kept.display())
}

fn print_lines(lines: &[String]) {
    for line in lines {
        println!("{line}");
    }
}

/// Lists the transports installed on this machine.
///
/// Everything found is shown, usable or not. A plugin that is present but
/// broken looks exactly like one that was never installed if it is left out —
/// and the two call for opposite fixes.
pub fn plugin_list(show_paths: bool) -> Result<()> {
    let paths = sefy_core::plugin::search_paths();
    let plugins = sefy_core::plugin::discover_in(&paths);

    if show_paths {
        println!("looked in:");
        for path in &paths {
            println!("  {}", path.display());
        }
        println!();
    }

    if plugins.is_empty() {
        println!("no plugins installed");
        println!(
            "a plugin is an executable named {}<name>, on PATH or in {}",
            sefy_core::plugin::PREFIX,
            match sefy_core::plugin::plugin_directory() {
                Some(directory) => directory.display().to_string(),
                None => "sefy's data directory".to_owned(),
            }
        );
        return Ok(());
    }

    let name_width = plugins
        .iter()
        .map(|plugin| plugin.name().chars().count())
        .max()
        .unwrap_or(4);

    for plugin in &plugins {
        let version = plugin
            .manifest
            .as_ref()
            .map_or("?", |manifest| manifest.version.as_str());

        let state = if plugin.usable {
            let mut operations: Vec<&str> = plugin
                .manifest
                .iter()
                .flat_map(|manifest| &manifest.operations)
                .map(|operation| operation.as_str())
                .collect();
            operations.sort_unstable();
            operations.join(", ")
        } else {
            format!(
                "unusable: {}",
                plugin.reason.as_deref().unwrap_or("no reason given")
            )
        };

        println!(
            "{:<name_width$}  {:<8}  {}",
            plugin.name(),
            version,
            state,
            name_width = name_width
        );
    }

    Ok(())
}

/// Reads everything from stdin as text.
fn read_stdin() -> Result<String> {
    let mut text = String::new();
    std::io::stdin().read_to_string(&mut text)?;
    Ok(text.trim_end_matches(['\n', '\r']).to_owned())
}

/// Asks a yes/no question on the terminal.
fn confirm(question: &str) -> Result<bool> {
    use std::io::{IsTerminal, Write};

    if !std::io::stdin().is_terminal() {
        bail!("cannot ask for confirmation: input is not a terminal; pass --yes");
    }

    print!("{question}");
    std::io::stdout().flush()?;

    let mut answer = String::new();
    std::io::stdin().read_line(&mut answer)?;
    Ok(matches!(
        answer.trim().to_ascii_lowercase().as_str(),
        "y" | "yes"
    ))
}