hanna/fabrica

feat(cli): user account management commands

3bc5ed9 · hanna committed on 2026-07-25

Add the `fabrica user` group — add, passwd, list, disable, enable, del —
operating directly on the store with no running server. Highlights:

- `user passwd` sets a password from `--pass`, an interactive no-echo prompt
  (confirmed twice on a terminal), or a single piped stdin line for scripting.
  This is the SMTP-disabled path for activating an account.
- `user add` hashes `--pass` when given; without it the account is created
  inactive with guidance to run `user passwd` (email invites arrive in phase 9).
- `user del` refuses a repo owner unless `--purge`, and confirms on a TTY or
  requires `--yes` when piped.
- `--json user list` exposes only whether a password is set, never the hash.

Store-backed commands self-migrate on connect so a fresh install's first
`user add` bootstraps the database. End-to-end tests cover each command against
a temp SQLite database; decisions.md records the pull-forward and interim
`user add` behaviour.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

Cargo.lock +110 −9

crates/cli/Cargo.toml +9 −0

crates/cli/src/context.rs +61 −0

crates/cli/src/lib.rs +10 −0

crates/cli/src/prompt.rs +78 −0

crates/cli/src/user_cmd.rs +521 −0

docs/decisions.md +36 −0

 [dependencies]
 config = { workspace = true }
+store = { workspace = true }
+auth = { workspace = true }
+model = { workspace = true }
 anyhow = { workspace = true }
 clap = { workspace = true }
+serde = { workspace = true }
 serde_json = { workspace = true }
+tokio = { workspace = true }
+rpassword = { workspace = true }
+[dev-dependencies]
+tempfile = { workspace = true }
 [lints]
 workspace = true

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! Shared plumbing for store-backed subcommands.
+//!
+//! Every CLI mutation operates directly on the database — there is no IPC with a
+//! running `serve`. These helpers turn the loaded configuration into an open
+//! [`Store`] and give the (otherwise synchronous) command handlers a place to
+//! block on async work.
+use std::future::Future;
+use std::path::Path;
+use config::Config;
+use store::Store;
+/// Load configuration, open the store, and apply any pending migrations.
+///
+/// Migrations run on every store-backed command so a fresh install is usable
+/// immediately: the first `fabrica user add` creates the database file, brings
+/// the schema up to date, and inserts the row in one step. Migrations are
+/// idempotent, so this is a cheap no-op once the schema is current.
+///
+/// Configuration warnings are printed to stderr, matching `config check`/`show`.
+///
+/// # Errors
+///
+/// Returns an error if the configuration is invalid, the database cannot be
+/// opened, or migrations fail.
+pub(crate) async fn open_store(config_path: Option<&Path>) -> anyhow::Result<(Config, Store)> {
+    let loaded = config::load(config_path)?;
+    for warning in &loaded.warnings {
+        eprintln!("warning: {warning}");
+    }
+    let store = Store::connect(
+        &loaded.config.database.url,
+        loaded.config.database.max_connections,
+    )
+    .await?;
+    store.migrate().await?;
+    Ok((loaded.config, store))
+}
+/// Run an async command body to completion on a fresh current-thread runtime.
+///
+/// The CLI is a short-lived, single-shot process, so a current-thread runtime is
+/// the right size — no worker pool to spin up and tear down per invocation.
+///
+/// # Errors
+///
+/// Propagates any error from building the runtime or from `fut` itself.
+pub(crate) fn block_on<F, T>(fut: F) -> anyhow::Result<T>
+where
+    F: Future<Output = anyhow::Result<T>>,
+{
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()?;
+    runtime.block_on(fut)
+}

 //! phases; today it covers only `config check` and `config show`.
 mod config_cmd;
+mod context;
+mod prompt;
+mod user_cmd;
 use std::path::PathBuf;
 use std::process::ExitCode;
         #[command(subcommand)]
         command: config_cmd::ConfigCommand,
     },
+    /// Manage user accounts.
+    User {
+        /// The user action to perform.
+        #[command(subcommand)]
+        command: user_cmd::UserCommand,
+    },
+}
 /// Parse arguments and dispatch to the requested subcommand.
 fn dispatch(cli: &Cli) -> anyhow::Result<ExitCode> {
     match &cli.command {
         Command::Config { command } => config_cmd::run(command, cli.config.as_deref(), cli.json),
+        Command::User { command } => user_cmd::run(command, cli.config.as_deref(), cli.json),
+    }
+}

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! Interactive terminal prompts: non-echoing password entry and destructive-
+//! action confirmation.
+//!
+//! Both degrade deliberately when stdin is not a terminal (a pipe, a systemd
+//! unit, CI). A password can still be supplied on a single stdin line for
+//! scripting; a confirmation, by contrast, refuses rather than guess, so a
+//! non-interactive destructive command must pass `--yes` explicitly.
+use std::io::{IsTerminal, Write};
+/// Resolve a password to use, in three ways depending on how the command was
+/// invoked:
+///
+/// * `explicit` (from `--pass`) is used verbatim when present;
+/// * otherwise, on a terminal, the user is prompted twice with no echo and the
+///   two entries must match;
+/// * otherwise (piped stdin) a single line is read, so
+///   `printf '%s' pw | fabrica user passwd alice` works.
+///
+/// An empty password is rejected in every case.
+///
+/// # Errors
+///
+/// Returns an error if the prompts cannot be read, the two interactive entries
+/// differ, or the resolved password is empty.
+pub(crate) fn resolve_password(explicit: Option<String>) -> anyhow::Result<String> {
+    let password = match explicit {
+        Some(pass) => pass,
+        None if std::io::stdin().is_terminal() => {
+            let first = rpassword::prompt_password("New password: ")?;
+            let second = rpassword::prompt_password("Confirm password: ")?;
+            if first != second {
+                anyhow::bail!("passwords did not match");
+            }
+            first
+        }
+        None => {
+            let mut line = String::new();
+            std::io::stdin().read_line(&mut line)?;
+            line.trim_end_matches(['\r', '\n']).to_string()
+        }
+    };
+    if password.is_empty() {
+        anyhow::bail!("password must not be empty");
+    }
+    Ok(password)
+}
+/// Ask the user to confirm a destructive action.
+///
+/// `assume_yes` (from `--yes`) short-circuits to `true`. Otherwise a terminal is
+/// prompted `[y/N]` and only `y`/`yes` (any case) confirms. When stdin is not a
+/// terminal and `--yes` was not given, the action is refused rather than assumed.
+///
+/// # Errors
+///
+/// Returns an error if stdin is not a terminal and `--yes` was not passed, or if
+/// the prompt cannot be read.
+pub(crate) fn confirm(question: &str, assume_yes: bool) -> anyhow::Result<bool> {
+    if assume_yes {
+        return Ok(true);
+    }
+    if !std::io::stdin().is_terminal() {
+        anyhow::bail!(
+            "refusing to proceed without confirmation; re-run with --yes for non-interactive use"
+        );
+    }
+    eprint!("{question} [y/N] ");
+    std::io::stderr().flush()?;
+    let mut line = String::new();
+    std::io::stdin().read_line(&mut line)?;
+    let answer = line.trim().to_ascii_lowercase();
+    Ok(answer == "y" || answer == "yes")
+}

 makes the exhaustive matrix test possible — and keeps the collaborator lookup at
 the call site (the store), where it belongs. The five ordered rules are unchanged
 from the spec.
+## 2026-07-24 — `user` CLI pulled forward; store-backed commands self-migrate
+**Decision:** The `fabrica user` command group (`add`, `passwd`, `list`,
+`disable`, `enable`, `del`) is implemented now, alongside phase 4, rather than
+waiting for the phase-8 CLI milestone. Every store-backed command applies pending
+migrations on connect (idempotent), so a fresh install's first `user add`
+bootstraps the database in one step.
+**Alternatives:** Keep strictly to phase order and ship the `user` commands only
+in phase 8; require a separate `fabrica migrate` before any `user` command works.
+**Rationale:** The requested capability — set a user's password from the CLI when
+SMTP is unavailable — is realized by `user passwd`, which needs both `auth`
+(hashing) and `store` (persistence) but nothing from the intervening phases
+(git/highlight). Building it now delivers that capability immediately and keeps
+the auth crate exercised by a real caller. Self-migrating on connect is what makes
+`user add` usable before `serve` has ever run; `serve --no-migrate` remains the
+opt-out for the server path.
+## 2026-07-24 — Interim `user add` without `--pass` creates an inactive account
+**Decision:** Until the mail/invite flow ships (phase 9), `fabrica user add`
+without `--pass` creates the user with a `NULL` password (unable to log in) and
+prints guidance to run `fabrica user passwd`. CLI-set passwords clear
+`must_change_password` (the operator chose a known credential).
+**Alternatives:** Block `user add` until invites exist; always require `--pass`.
+**Rationale:** The spec's `user add` mints an emailed activation link, which
+depends on `crates/mail` (a later phase). The inactive-account-plus-guidance
+behaviour is a faithful interim: no account is silently left in a login-capable
+state without a credential, and the operator has an obvious next step. When mail
+lands, this path grows the invite-and-email behaviour; the `passwd` fallback stays
+for SMTP-disabled instances (`mail.backend = "none"`), which is exactly the case
+that motivated it.

 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
 dependencies = [
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
 dependencies = [
  "anstyle",
  "once_cell_polyfill",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
 version = "0.1.0"
 dependencies = [
  "anyhow",
+ "auth",
  "clap",
  "config",
+ "model",
+ "rpassword",
+ "serde",
  "serde_json",
+ "store",
+ "tempfile",
+ "tokio",
+]
 [[package]]
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
 checksum = "de48cc4d1c1d97a20fd819def54b890cadde72ed3ad0c614822a0a433361be96"
 dependencies = [
  "cfg-if",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
 dependencies = [
  "libc",
  "wasi",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
+]
 [[package]]
+name = "rpassword"
+version = "7.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2da316a15f47e3d053de9cb2c439650bd8fa4aaeb9365f2e5f27f492ff73c196"
+dependencies = [
+ "libc",
+ "rtoolbox",
+ "windows-sys 0.61.2",
+]
+[[package]]
+name = "rtoolbox"
+version = "0.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50a0e551c1e27e1731aba276dbeaeac73f53c7cd34d1bda485d02bd1e0f36844"
+dependencies = [
+ "libc",
+ "windows-sys 0.59.0",
+]
+[[package]]
 name = "rustix"
 version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
 checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"
 dependencies = [
  "libc",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
  "getrandom 0.4.3",
  "once_cell",
  "rustix",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
  "pin-project-lite",
  "socket2",
  "tokio-macros",
- "windows-sys",
+ "windows-sys 0.61.2",
+]
 [[package]]
 [[package]]
 name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets",
+]
+[[package]]
+name = "windows-sys"
 version = "0.61.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+]
 [[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+[[package]]
 name = "winnow"
 version = "0.7.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"

+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+//! `fabrica user` — account administration, operating directly on the store.
+use std::path::Path;
+use std::process::ExitCode;
+use clap::Subcommand;
+use config::Config;
+use model::User;
+use store::{NewUser, Store};
+use crate::context::{block_on, open_store};
+use crate::prompt::{confirm, resolve_password};
+/// Actions under `fabrica user`.
+#[derive(Debug, Subcommand)]
+pub(crate) enum UserCommand {
+    /// Create a user. Without `--pass` the account is created with no password
+    /// and cannot log in until one is set with `fabrica user passwd`.
+    Add {
+        /// Login name (validated: see the name rules).
+        name: String,
+        /// Primary email address.
+        email: String,
+        /// Set this password now instead of leaving the account inactive. Omit
+        /// the value to be prompted; omit the flag entirely to create an
+        /// inactive account.
+        #[arg(long)]
+        pass: Option<String>,
+        /// Grant site-administrator privileges.
+        #[arg(long)]
+        admin: bool,
+        /// Human-friendly display name.
+        #[arg(long = "display-name")]
+        display_name: Option<String>,
+    },
+    /// Set a user's password. With no `--pass`, prompts twice on a terminal, or
+    /// reads a single line from stdin when piped. Rotating a password logs the
+    /// user out of every existing session.
+    Passwd {
+        /// The user whose password to set.
+        name: String,
+        /// The new password. Omit to be prompted (or to read it from stdin).
+        #[arg(long)]
+        pass: Option<String>,
+    },
+    /// List all users.
+    List,
+    /// Disable a user: they can no longer log in, and existing sessions are
+    /// dropped.
+    Disable {
+        /// The user to disable.
+        name: String,
+    },
+    /// Re-enable a previously disabled user.
+    Enable {
+        /// The user to enable.
+        name: String,
+    },
+    /// Delete a user. Refuses if the user still owns repositories unless
+    /// `--purge` is given.
+    Del {
+        /// The user to delete.
+        name: String,
+        /// Also delete every repository the user owns.
+        #[arg(long)]
+        purge: bool,
+        /// Skip the confirmation prompt (required when stdin is not a terminal).
+        #[arg(long)]
+        yes: bool,
+    },
+}
+/// Dispatch a `user` subcommand, blocking on the async store work.
+pub(crate) fn run(
+    command: &UserCommand,
+    config_path: Option<&Path>,
+    json: bool,
+) -> anyhow::Result<ExitCode> {
+    match command {
+        UserCommand::Add {
+            name,
+            email,
+            pass,
+            admin,
+            display_name,
+        } => block_on(add(
+            config_path,
+            name,
+            email,
+            pass.clone(),
+            *admin,
+            display_name.clone(),
+        )),
+        UserCommand::Passwd { name, pass } => block_on(passwd(config_path, name, pass.clone())),
+        UserCommand::List => block_on(list(config_path, json)),
+        UserCommand::Disable { name } => block_on(set_disabled(config_path, name, true)),
+        UserCommand::Enable { name } => block_on(set_disabled(config_path, name, false)),
+        UserCommand::Del { name, purge, yes } => block_on(del(config_path, name, *purge, *yes)),
+    }
+}
+/// Hash a plaintext password with the instance's configured Argon2id cost.
+fn hash_password(config: &Config, password: &str) -> anyhow::Result<String> {
+    let params = auth::HashParams {
+        m_cost: config.auth.argon2_m_cost,
+        t_cost: config.auth.argon2_t_cost,
+        p_cost: config.auth.argon2_p_cost,
+    };
+    Ok(auth::hash_password(password, params)?)
+}
+/// Look a user up by name, turning "not found" into a clean error.
+async fn require_user(store: &Store, name: &str) -> anyhow::Result<User> {
+    store
+        .user_by_username(name)
+        .await?
+        .ok_or_else(|| anyhow::anyhow!("no such user {name:?}"))
+}
+async fn add(
+    config_path: Option<&Path>,
+    name: &str,
+    email: &str,
+    pass: Option<String>,
+    admin: bool,
+    display_name: Option<String>,
+) -> anyhow::Result<ExitCode> {
+    let (config, store) = open_store(config_path).await?;
+    // A password is set eagerly only when `--pass` is present. `--pass` with no
+    // value prompts; the flag being absent leaves the account inactive.
+    let password_hash = match pass {
+        Some(explicit) => {
+            let password = resolve_password(Some(explicit))?;
+            Some(hash_password(&config, &password)?)
+        }
+        None => None,
+    };
+    let has_password = password_hash.is_some();
+    let user = store
+        .create_user(NewUser {
+            username: name.to_string(),
+            email: email.to_string(),
+            display_name,
+            password_hash,
+            is_admin: admin,
+            must_change_password: false,
+        })
+        .await?;
+    println!(
+        "created user {} <{}>{}",
+        user.username,
+        user.email,
+        if user.is_admin { " (admin)" } else { "" }
+    );
+    if !has_password {
+        // Email invitations are not implemented yet (phase 9), so there is no
+        // out-of-band way to activate the account — point the operator at the
+        // direct path. This is the SMTP-disabled fallback made explicit.
+        eprintln!(
+            "note: no password set; this account cannot log in yet. \
+             Set one with: fabrica user passwd {}",
+            user.username
+        );
+    }
+    Ok(ExitCode::SUCCESS)
+}
+async fn passwd(
+    config_path: Option<&Path>,
+    name: &str,
+    pass: Option<String>,
+) -> anyhow::Result<ExitCode> {
+    let (config, store) = open_store(config_path).await?;
+    let user = require_user(&store, name).await?;
+    let password = resolve_password(pass)?;
+    let hash = hash_password(&config, &password)?;
+    store.set_password(&user.id, Some(&hash)).await?;
+    println!("password updated for {}", user.username);
+    Ok(ExitCode::SUCCESS)
+}
+async fn list(config_path: Option<&Path>, json: bool) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let users = store.list_users().await?;
+    if json {
+        let view: Vec<_> = users.iter().map(user_json).collect();
+        println!("{}", serde_json::to_string_pretty(&view)?);
+        return Ok(ExitCode::SUCCESS);
+    }
+    if users.is_empty() {
+        println!("no users");
+        return Ok(ExitCode::SUCCESS);
+    }
+    let width = users
+        .iter()
+        .map(|u| u.username.len())
+        .max()
+        .unwrap_or(0)
+        .max("USERNAME".len());
+    println!("{:<width$}  {:<28}  FLAGS", "USERNAME", "EMAIL");
+    for user in &users {
+        println!(
+            "{:<width$}  {:<28}  {}",
+            user.username,
+            user.email,
+            flags(user).join(",")
+        );
+    }
+    Ok(ExitCode::SUCCESS)
+}
+async fn set_disabled(
+    config_path: Option<&Path>,
+    name: &str,
+    disabled: bool,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user = require_user(&store, name).await?;
+    store.set_disabled(&user.id, disabled).await?;
+    println!(
+        "{} user {}",
+        if disabled { "disabled" } else { "enabled" },
+        user.username
+    );
+    Ok(ExitCode::SUCCESS)
+}
+async fn del(
+    config_path: Option<&Path>,
+    name: &str,
+    purge: bool,
+    yes: bool,
+) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user = require_user(&store, name).await?;
+    let repos = store.repos_by_owner(&user.id).await?;
+    if !repos.is_empty() && !purge {
+        eprintln!(
+            "{} still owns {} repositor{}:",
+            user.username,
+            repos.len(),
+            plural(repos.len())
+        );
+        for repo in &repos {
+            eprintln!("  {}", repo.path);
+        }
+        anyhow::bail!(
+            "refusing to delete a user who owns repositories; pass --purge to remove them"
+        );
+    }
+    let question = if repos.is_empty() {
+        format!("Delete user {}?", user.username)
+    } else {
+        format!(
+            "Delete user {} and {} owned repositor{}?",
+            user.username,
+            repos.len(),
+            plural(repos.len())
+        )
+    };
+    if !confirm(&question, yes)? {
+        println!("aborted");
+        return Ok(ExitCode::SUCCESS);
+    }
+    // Cascades to the user's repos, keys, tokens, and sessions in the database.
+    // On-disk bare repositories are not yet created by `repo add`, so there is
+    // nothing to remove from the filesystem here; that cleanup lands with the
+    // git-storage phases.
+    store.delete_user(&user.id).await?;
+    println!("deleted user {}", user.username);
+    Ok(ExitCode::SUCCESS)
+}
+/// The single-character-free flag labels shown by `user list`.
+fn flags(user: &User) -> Vec<&'static str> {
+    let mut flags = Vec::new();
+    if user.is_admin {
+        flags.push("admin");
+    }
+    if user.disabled_at.is_some() {
+        flags.push("disabled");
+    }
+    if user.password_hash.is_none() {
+        flags.push("no-password");
+    }
+    if flags.is_empty() {
+        flags.push("-");
+    }
+    flags
+}
+/// Render a user for `--json`, deliberately exposing only whether a password is
+/// set (never the hash).
+fn user_json(user: &User) -> serde_json::Value {
+    serde_json::json!({
+        "id": user.id,
+        "username": user.username,
+        "email": user.email,
+        "display_name": user.display_name,
+        "is_admin": user.is_admin,
+        "has_password": user.password_hash.is_some(),
+        "must_change_password": user.must_change_password,
+        "disabled": user.disabled_at.is_some(),
+        "created_at": user.created_at,
+        "updated_at": user.updated_at,
+    })
+}
+/// The plural suffix `y`/`ies` helper for "repositor{y,ies}".
+fn plural(n: usize) -> &'static str {
+    if n == 1 { "y" } else { "ies" }
+}
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used, clippy::expect_used)]
+    use std::path::PathBuf;
+    use store::NewRepo;
+    use tempfile::TempDir;
+    use super::*;
+    /// A temp directory holding a SQLite database and a config file that points
+    /// at it, so the handlers can run end-to-end with no external services.
+    struct Env {
+        _dir: TempDir,
+        config_path: PathBuf,
+        db_url: String,
+    }
+    fn env() -> Env {
+        let dir = tempfile::tempdir().unwrap();
+        let repos = dir.path().join("repos");
+        let db = dir.path().join("fabrica.db");
+        let db_url = format!("sqlite://{}", db.display());
+        let config_path = dir.path().join("fabrica.toml");
+        let toml = format!(
+            "[storage]\ndata_dir = {:?}\nrepo_dir = {:?}\n\n[database]\nurl = {:?}\n",
+            dir.path().display(),
+            repos.display(),
+            db_url,
+        );
+        std::fs::write(&config_path, toml).unwrap();
+        Env {
+            _dir: dir,
+            config_path,
+            db_url,
+        }
+    }
+    impl Env {
+        /// The `--config` argument the handlers expect: `Some(path)`. The
+        /// `Option` is intrinsic to the handler signature, not incidental.
+        #[allow(clippy::unnecessary_wraps)]
+        fn path(&self) -> Option<&Path> {
+            Some(self.config_path.as_path())
+        }
+        async fn store(&self) -> Store {
+            Store::connect(&self.db_url, 1).await.unwrap()
+        }
+    }
+    #[test]
+    fn clap_command_tree_is_valid() {
+        use clap::CommandFactory;
+        crate::Cli::command().debug_assert();
+    }
+    #[test]
+    fn add_with_password_creates_a_usable_admin() {
+        let env = env();
+        let code = block_on(add(
+            env.path(),
+            "alice",
+            "alice@example.com",
+            Some("s3cr3t".to_string()),
+            true,
+            Some("Alice".to_string()),
+        ))
+        .unwrap();
+        assert_eq!(code, ExitCode::SUCCESS);
+        let created = block_on(async {
+            let user = require_user(&env.store().await, "alice").await?;
+            anyhow::Ok(user)
+        })
+        .unwrap();
+        assert!(created.is_admin);
+        assert_eq!(created.display_name.as_deref(), Some("Alice"));
+        let hash = created.password_hash.expect("password should be set");
+        assert!(auth::verify_password("s3cr3t", Some(&hash)));
+    }
+    #[test]
+    fn add_without_password_is_inactive_then_passwd_activates() {
+        let env = env();
+        block_on(add(env.path(), "bob", "bob@example.com", None, false, None)).unwrap();
+        let before =
+            block_on(async { anyhow::Ok(require_user(&env.store().await, "bob").await?) }).unwrap();
+        assert!(before.password_hash.is_none(), "no password until set");
+        // The SMTP-disabled fallback: set the password directly.
+        block_on(passwd(env.path(), "bob", Some("hunter2".to_string()))).unwrap();
+        let after =
+            block_on(async { anyhow::Ok(require_user(&env.store().await, "bob").await?) }).unwrap();
+        let hash = after.password_hash.expect("password now set");
+        assert!(auth::verify_password("hunter2", Some(&hash)));
+    }
+    #[test]
+    fn disable_then_enable_toggles_the_flag() {
+        let env = env();
+        block_on(add(
+            env.path(),
+            "carol",
+            "carol@example.com",
+            Some("pw".to_string()),
+            false,
+            None,
+        ))
+        .unwrap();
+        block_on(set_disabled(env.path(), "carol", true)).unwrap();
+        let disabled =
+            block_on(async { anyhow::Ok(require_user(&env.store().await, "carol").await?) })
+                .unwrap();
+        assert!(disabled.disabled_at.is_some());
+        block_on(set_disabled(env.path(), "carol", false)).unwrap();
+        let enabled =
+            block_on(async { anyhow::Ok(require_user(&env.store().await, "carol").await?) })
+                .unwrap();
+        assert!(enabled.disabled_at.is_none());
+    }
+    #[test]
+    fn del_refuses_repo_owner_without_purge_then_purges() {
+        let env = env();
+        block_on(add(
+            env.path(),
+            "dave",
+            "dave@example.com",
+            Some("pw".to_string()),
+            false,
+            None,
+        ))
+        .unwrap();
+        // Give Dave a repo directly through the store.
+        let dave_id = block_on(async {
+            let store = env.store().await;
+            let dave = require_user(&store, "dave").await?;
+            store
+                .create_repo(NewRepo {
+                    owner_id: dave.id.clone(),
+                    group_id: None,
+                    name: "proj".to_string(),
+                    path: "proj".to_string(),
+                    description: None,
+                    is_private: true,
+                    default_branch: "main".to_string(),
+                })
+                .await?;
+            anyhow::Ok(dave.id)
+        })
+        .unwrap();
+        // Without --purge the delete is refused and the user survives.
+        let refused = block_on(del(env.path(), "dave", false, true));
+        assert!(refused.is_err(), "owning a repo should block deletion");
+        assert!(
+            block_on(async { anyhow::Ok(env.store().await.user_by_id(&dave_id).await?) })
+                .unwrap()
+                .is_some()
+        );
+        // With --purge (and --yes to skip the prompt) the user and repo go.
+        block_on(del(env.path(), "dave", true, true)).unwrap();
+        block_on(async {
+            let store = env.store().await;
+            assert!(store.user_by_id(&dave_id).await?.is_none());
+            assert!(store.repos_by_owner(&dave_id).await?.is_empty());
+            anyhow::Ok(())
+        })
+        .unwrap();
+    }
+    #[test]
+    fn passwd_on_missing_user_errors() {
+        let env = env();
+        // Create the database (via one successful command) first.
+        block_on(add(
+            env.path(),
+            "eve",
+            "eve@example.com",
+            Some("pw".to_string()),
+            false,
+            None,
+        ))
+        .unwrap();
+        let err = block_on(passwd(env.path(), "nobody", Some("x".to_string()))).unwrap_err();
+        assert!(err.to_string().contains("no such user"), "got {err}");
+    }
+}