hanna/fabrica

feat(config): load, validate, and show TOML+env configuration

d1a7fc7 · hanna committed on 2026-07-25

Implement phase 2. The config crate loads a TOML file layered over
built-in defaults and FABRICA__* env overrides via figment (defaults ->
/etc -> XDG -> --config -> env, later wins), then validates strictly and
fails fast: unknown keys are an error, instance.url must parse without a
trailing slash, storage dirs must be creatable, smtp needs host/from;
cookie-secure-over-http is a warning.

Secrets (auth.secret, mail.password) are a redact-by-default Secret
newtype — Debug and Serialize always emit <redacted>, the real value is
reachable only via expose() — and their *_file siblings are read from
disk and take precedence. This keeps secrets out of logs, errors, and
`config show`.

Wire `fabrica config check` and `fabrica config show [--json]` into a
minimal clap tree with global --config/--log-level/--json. Ship a
fully-commented fabrica.example.toml and docs/configuration.md, and log
the Secret and strict-loading decisions.

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

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

Cargo.lock +875 −0

Cargo.toml +11 −0

crates/cli/Cargo.toml +4 −0

crates/cli/src/config_cmd.rs +62 −0

crates/cli/src/lib.rs +57 −4

crates/config/Cargo.toml +8 −0

crates/config/src/lib.rs +420 −0

crates/config/src/secret.rs +101 −0

crates/config/src/types.rs +384 −0

docs/configuration.md +92 −0

docs/decisions.md +33 −0

fabrica.example.toml +89 −0

@@ @@ -48,6 +48,17 @@ web = { path = "crates/web" } @@
 api = { path = "crates/api" }
 cli = { path = "crates/cli" }
 # External dependencies. Versions are centralised here; crates opt in with
 # `<dep> = { workspace = true }` so the whole workspace stays on one version.
 figment = { version = "0.10", features = ["toml", "env"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 toml = "0.8"
 thiserror = "2"
 url = "2"
 clap = { version = "4", features = ["derive"] }
 anyhow = "1"
 [workspace.lints.rust]
 unsafe_code = "forbid"
 missing_docs = "warn"

@@ @@ -10,6 +10,10 @@ repository.workspace = true @@
 publish.workspace = true
 [dependencies]
 config = { workspace = true }
 anyhow = { workspace = true }
 clap = { workspace = true }
 serde_json = { workspace = true }
 [lints]
 workspace = true

@@ @@ -0,0 +1,62 @@ @@
 // 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 config check` and `fabrica config show`.
 use std::path::Path;
 use std::process::ExitCode;
 use clap::Subcommand;
 /// Actions under `fabrica config`.
 #[derive(Debug, Subcommand)]
 pub(crate) enum ConfigCommand {
     /// Validate the effective configuration and exit non-zero on any error.
     Check,
     /// Print the effective, merged configuration with secrets redacted.
     Show,
+}
 /// Dispatch a `config` subcommand.
 ///
 /// Warnings are always written to stderr; on `check` they do not affect the exit
 /// status. A validation failure is reported to stderr and yields
 /// [`ExitCode::FAILURE`] without returning an `Err`, so no backtrace-style
 /// wrapper is printed for the expected "your config is wrong" case.
 pub(crate) fn run(
     command: &ConfigCommand,
     config_path: Option<&Path>,
     json: bool,
 ) -> anyhow::Result<ExitCode> {
     match command {
         ConfigCommand::Check => match config::load(config_path) {
             Ok(loaded) => {
                 warn(&loaded.warnings);
                 println!("configuration ok");
                 Ok(ExitCode::SUCCESS)
+            }
             Err(err) => {
                 eprintln!("error: {err}");
                 Ok(ExitCode::FAILURE)
+            }
         },
         ConfigCommand::Show => {
             let loaded = config::load(config_path)?;
             warn(&loaded.warnings);
             if json {
                 println!("{}", serde_json::to_string_pretty(&loaded.config)?);
             } else {
                 print!("{}", loaded.config.to_toml_string()?);
+            }
             Ok(ExitCode::SUCCESS)
+        }
+    }
+}
 /// Write each warning to stderr, prefixed, leaving stdout for real output.
 fn warn(warnings: &[String]) {
     for warning in warnings {
         eprintln!("warning: {warning}");
+    }
+}

@@ @@ -6,15 +6,68 @@ @@
 //!
 //! Every subcommand operates directly on the store and filesystem; there is no
 //! IPC with a running `serve`. [`run`] is the single entry point invoked by the
 //! `fabrica` binary.
 //! `fabrica` binary. The command tree is built out over the implementation
 //! phases; today it covers only `config check` and `config show`.
 mod config_cmd;
 use std::path::PathBuf;
 use std::process::ExitCode;
 use clap::{Parser, Subcommand};
 /// Top-level argument parser for the `fabrica` binary.
 #[derive(Debug, Parser)]
 #[command(name = "fabrica", version, about = "A self-hosted git server.")]
 struct Cli {
     /// Path to a configuration file, merged last after the standard locations.
     #[arg(long, global = true, value_name = "PATH")]
     config: Option<PathBuf>,
     /// Override the configured log level (`trace|debug|info|warn|error`).
     #[arg(long, global = true, value_name = "LEVEL")]
     log_level: Option<String>,
     /// Emit machine-readable JSON instead of human-formatted output.
     #[arg(long, global = true)]
     json: bool,
     /// The subcommand to run.
     #[command(subcommand)]
     command: Command,
+}
 /// The fabrica subcommand tree.
 #[derive(Debug, Subcommand)]
 enum Command {
     /// Inspect and validate configuration.
     Config {
         /// The configuration action to perform.
         #[command(subcommand)]
         command: config_cmd::ConfigCommand,
     },
+}
 /// Parse arguments and dispatch to the requested subcommand.
 ///
 /// Returns the process exit code. The command tree is built out over the
 /// implementation phases; today this is a placeholder that exits successfully.
 /// Returns the process exit code. Argument-parse failures are handled by clap
 /// (which prints usage and exits); any other error is printed to stderr and
 /// mapped to [`ExitCode::FAILURE`].
 #[must_use]
 pub fn run() -> ExitCode {
     ExitCode::SUCCESS
     let cli = Cli::parse();
     match dispatch(&cli) {
         Ok(code) => code,
         Err(err) => {
             eprintln!("error: {err:#}");
             ExitCode::FAILURE
+        }
+    }
+}
 /// Route a parsed [`Cli`] to its handler.
 fn dispatch(cli: &Cli) -> anyhow::Result<ExitCode> {
     match &cli.command {
         Command::Config { command } => config_cmd::run(command, cli.config.as_deref(), cli.json),
+    }
+}

@@ @@ -10,6 +10,14 @@ repository.workspace = true @@
 publish.workspace = true
 [dependencies]
 figment = { workspace = true }
 serde = { workspace = true }
 thiserror = { workspace = true }
 toml = { workspace = true }
 url = { workspace = true }
 [dev-dependencies]
 figment = { workspace = true, features = ["test"] }
 [lints]
 workspace = true

@@ @@ -3,20 +3,189 @@ @@
 version = 4
 [[package]]
 name = "anstream"
 version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
 dependencies = [
  "anstyle",
  "anstyle-parse",
  "anstyle-query",
  "anstyle-wincon",
  "colorchoice",
  "is_terminal_polyfill",
  "utf8parse",
+]
 [[package]]
 name = "anstyle"
 version = "1.0.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
 [[package]]
 name = "anstyle-parse"
 version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
 dependencies = [
  "utf8parse",
+]
 [[package]]
 name = "anstyle-query"
 version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
 dependencies = [
  "windows-sys",
+]
 [[package]]
 name = "anstyle-wincon"
 version = "3.0.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
 dependencies = [
  "anstyle",
  "once_cell_polyfill",
  "windows-sys",
+]
 [[package]]
 name = "anyhow"
 version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 [[package]]
 name = "api"
 version = "0.1.0"
 [[package]]
 name = "atomic"
 version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89cbf775b137e9b968e67227ef7f775587cde3fd31b0d8599dbd0f598a48340"
 dependencies = [
  "bytemuck",
+]
 [[package]]
 name = "auth"
 version = "0.1.0"
 [[package]]
 name = "bitflags"
 version = "2.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
 [[package]]
 name = "bytemuck"
 version = "1.25.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 [[package]]
 name = "clap"
 version = "4.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d91e0c145792ef73a6ad36d27c75ac09f1832222a3c209689d90f534685ee5b7"
 dependencies = [
  "clap_builder",
  "clap_derive",
+]
 [[package]]
 name = "clap_builder"
 version = "4.6.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
 dependencies = [
  "anstream",
  "anstyle",
  "clap_lex",
  "strsim",
+]
 [[package]]
 name = "clap_derive"
 version = "4.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
 dependencies = [
  "heck",
  "proc-macro2",
  "quote",
  "syn 3.0.3",
+]
 [[package]]
 name = "clap_lex"
 version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
 [[package]]
 name = "cli"
 version = "0.1.0"
 dependencies = [
  "anyhow",
  "clap",
  "config",
  "serde_json",
+]
 [[package]]
 name = "colorchoice"
 version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 [[package]]
 name = "config"
 version = "0.1.0"
 dependencies = [
  "figment",
  "serde",
  "thiserror",
  "toml",
  "url",
+]
 [[package]]
 name = "displaydoc"
 version = "0.2.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1ac70aa55017e108007fbaf5aa0f54b021c98f92ff8af59d42eda9da96e3dd4f"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
+]
 [[package]]
 name = "equivalent"
 version = "1.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
 [[package]]
 name = "errno"
 version = "0.3.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
  "windows-sys",
+]
 [[package]]
 name = "fabrica"
@@ @@ -26,29 +195,735 @@ dependencies = [ @@
+]
 [[package]]
 name = "fastrand"
 version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 [[package]]
 name = "figment"
 version = "0.10.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8cb01cd46b0cf372153850f4c6c272d9cbea2da513e07538405148f95bd789f3"
 dependencies = [
  "atomic",
  "parking_lot",
  "pear",
  "serde",
  "tempfile",
  "toml",
  "uncased",
  "version_check",
+]
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
 dependencies = [
  "percent-encoding",
+]
 [[package]]
 name = "getrandom"
 version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
 dependencies = [
  "cfg-if",
  "libc",
  "r-efi",
+]
 [[package]]
 name = "git"
 version = "0.1.0"
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 [[package]]
 name = "heck"
 version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 [[package]]
 name = "highlight"
 version = "0.1.0"
 [[package]]
 name = "icu_collections"
 version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4c6b649701667bbe825c3b7e6388cb521c23d88644678e83c0c4d0a621a34b43"
 dependencies = [
  "displaydoc",
  "potential_utf",
  "yoke",
  "zerofrom",
  "zerovec",
+]
 [[package]]
 name = "icu_locale_core"
 version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "edba7861004dd3714265b4db54a3c390e880ab658fec5f7db895fae2046b5bb6"
 dependencies = [
  "displaydoc",
  "litemap",
  "tinystr",
  "writeable",
  "zerovec",
+]
 [[package]]
 name = "icu_normalizer"
 version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5f6c8828b67bf8908d82127b2054ea1b4427ff0230ee9141c54251934ab1b599"
 dependencies = [
  "icu_collections",
  "icu_normalizer_data",
  "icu_properties",
  "icu_provider",
  "smallvec",
  "zerovec",
+]
 [[package]]
 name = "icu_normalizer_data"
 version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7aedcccd01fc5fe81e6b489c15b247b8b0690feb23304303a9e560f37efc560a"
 [[package]]
 name = "icu_properties"
 version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "020bfc02fe870ec3a66d93e677ccca0562506e5872c650f893269e08615d74ec"
 dependencies = [
  "icu_collections",
  "icu_locale_core",
  "icu_properties_data",
  "icu_provider",
  "zerotrie",
  "zerovec",
+]
 [[package]]
 name = "icu_properties_data"
 version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "616c294cf8d725c6afcd8f55abc17c56464ef6211f9ed59cccffe534129c77af"
 [[package]]
 name = "icu_provider"
 version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85962cf0ce02e1e0a629cc34e7ca3e373ce20dda4c4d7294bbd0bf1fdb59e614"
 dependencies = [
  "displaydoc",
  "icu_locale_core",
  "writeable",
  "yoke",
  "zerofrom",
  "zerotrie",
  "zerovec",
+]
 [[package]]
 name = "idna"
 version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
 dependencies = [
  "idna_adapter",
  "smallvec",
  "utf8_iter",
+]
 [[package]]
 name = "idna_adapter"
 version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344"
 dependencies = [
  "icu_normalizer",
  "icu_properties",
+]
 [[package]]
 name = "indexmap"
 version = "2.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
  "hashbrown",
+]
 [[package]]
 name = "inlinable_string"
 version = "0.1.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8fae54786f62fb2918dcfae3d568594e50eb9b5c25bf04371af6fe7516452fb"
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 [[package]]
 name = "itoa"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
 name = "libc"
 version = "0.2.189"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
 [[package]]
 name = "litemap"
 version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
 [[package]]
 name = "lock_api"
 version = "0.4.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
 dependencies = [
  "scopeguard",
+]
 [[package]]
 name = "mail"
 version = "0.1.0"
 [[package]]
 name = "memchr"
 version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 [[package]]
 name = "model"
 version = "0.1.0"
 [[package]]
 name = "once_cell"
 version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 [[package]]
 name = "once_cell_polyfill"
 version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
 dependencies = [
  "lock_api",
  "parking_lot_core",
+]
 [[package]]
 name = "parking_lot_core"
 version = "0.9.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
 dependencies = [
  "cfg-if",
  "libc",
  "redox_syscall",
  "smallvec",
  "windows-link",
+]
 [[package]]
 name = "pear"
 version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bdeeaa00ce488657faba8ebf44ab9361f9365a97bd39ffb8a60663f57ff4b467"
 dependencies = [
  "inlinable_string",
  "pear_codegen",
  "yansi",
+]
 [[package]]
 name = "pear_codegen"
 version = "0.2.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4bab5b985dc082b345f812b7df84e1bef27e7207b39e448439ba8bd69c93f147"
 dependencies = [
  "proc-macro2",
  "proc-macro2-diagnostics",
  "quote",
  "syn 2.0.119",
+]
 [[package]]
 name = "percent-encoding"
 version = "2.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 [[package]]
 name = "potential_utf"
 version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
 dependencies = [
  "zerovec",
+]
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
 dependencies = [
  "unicode-ident",
+]
 [[package]]
 name = "proc-macro2-diagnostics"
 version = "0.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "af066a9c399a26e020ada66a034357a868728e72cd426f3adcd35f80d88d88c8"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
  "version_check",
  "yansi",
+]
 [[package]]
 name = "quote"
 version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
  "proc-macro2",
+]
 [[package]]
 name = "r-efi"
 version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 [[package]]
 name = "redox_syscall"
 version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
  "bitflags",
+]
 [[package]]
 name = "rustix"
 version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
 dependencies = [
  "bitflags",
  "errno",
  "libc",
  "linux-raw-sys",
  "windows-sys",
+]
 [[package]]
 name = "scopeguard"
 version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 [[package]]
 name = "serde"
 version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
 dependencies = [
  "serde_core",
  "serde_derive",
+]
 [[package]]
 name = "serde_core"
 version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
 dependencies = [
  "serde_derive",
+]
 [[package]]
 name = "serde_derive"
 version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 3.0.3",
+]
 [[package]]
 name = "serde_json"
 version = "1.0.151"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
 dependencies = [
  "itoa",
  "memchr",
  "serde",
  "serde_core",
  "zmij",
+]
 [[package]]
 name = "serde_spanned"
 version = "0.6.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
 dependencies = [
  "serde",
+]
 [[package]]
 name = "smallvec"
 version = "1.15.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
 [[package]]
 name = "ssh"
 version = "0.1.0"
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 [[package]]
 name = "store"
 version = "0.1.0"
 [[package]]
 name = "strsim"
 version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 [[package]]
 name = "syn"
 version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
  "proc-macro2",
  "quote",
  "unicode-ident",
+]
 [[package]]
 name = "syn"
 version = "3.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
 dependencies = [
  "proc-macro2",
  "quote",
  "unicode-ident",
+]
 [[package]]
 name = "synstructure"
 version = "0.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
+]
 [[package]]
 name = "tempfile"
 version = "3.27.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
  "getrandom",
  "once_cell",
  "rustix",
  "windows-sys",
+]
 [[package]]
 name = "thiserror"
 version = "2.0.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9"
 dependencies = [
  "thiserror-impl",
+]
 [[package]]
 name = "thiserror-impl"
 version = "2.0.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 3.0.3",
+]
 [[package]]
 name = "tinystr"
 version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
 dependencies = [
  "displaydoc",
  "zerovec",
+]
 [[package]]
 name = "toml"
 version = "0.8.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
 dependencies = [
  "serde",
  "serde_spanned",
  "toml_datetime",
  "toml_edit",
+]
 [[package]]
 name = "toml_datetime"
 version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
 dependencies = [
  "serde",
+]
 [[package]]
 name = "toml_edit"
 version = "0.22.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
 dependencies = [
  "indexmap",
  "serde",
  "serde_spanned",
  "toml_datetime",
  "toml_write",
  "winnow",
+]
 [[package]]
 name = "toml_write"
 version = "0.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
 [[package]]
 name = "uncased"
 version = "0.9.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e1b88fcfe09e89d3866a5c11019378088af2d24c3fbd4f0543f96b479ec90697"
 dependencies = [
  "version_check",
+]
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 [[package]]
 name = "url"
 version = "2.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
 dependencies = [
  "form_urlencoded",
  "idna",
  "percent-encoding",
  "serde",
+]
 [[package]]
 name = "utf8_iter"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 [[package]]
 name = "utf8parse"
 version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 [[package]]
 name = "version_check"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 [[package]]
 name = "web"
 version = "0.1.0"
 [[package]]
 name = "windows-link"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 [[package]]
 name = "windows-sys"
 version = "0.61.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
 dependencies = [
  "windows-link",
+]
 [[package]]
 name = "winnow"
 version = "0.7.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
 dependencies = [
  "memchr",
+]
 [[package]]
 name = "writeable"
 version = "0.6.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
 [[package]]
 name = "yansi"
 version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
 [[package]]
 name = "yoke"
 version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
 dependencies = [
  "stable_deref_trait",
  "yoke-derive",
  "zerofrom",
+]
 [[package]]
 name = "yoke-derive"
 version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
  "synstructure",
+]
 [[package]]
 name = "zerofrom"
 version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
 dependencies = [
  "zerofrom-derive",
+]
 [[package]]
 name = "zerofrom-derive"
 version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
  "synstructure",
+]
 [[package]]
 name = "zerotrie"
 version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
 dependencies = [
  "displaydoc",
  "yoke",
  "zerofrom",
+]
 [[package]]
 name = "zerovec"
 version = "0.11.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
 dependencies = [
  "yoke",
  "zerofrom",
  "zerovec-derive",
+]
 [[package]]
 name = "zerovec-derive"
 version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
 dependencies = [
  "proc-macro2",
  "quote",
  "syn 2.0.119",
+]
 [[package]]
 name = "zmij"
 version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

@@ @@ -3,3 +3,423 @@ @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 //! Configuration loading, validation, and path resolution.
 //!
 //! Configuration is a TOML file plus environment overrides, merged with
 //! [`figment`]. The resolution order (later wins) is:
 //!
 //! 1. built-in defaults ([`Config::default`]);
 //! 2. `/etc/fabrica/fabrica.toml`;
 //! 3. `$XDG_CONFIG_HOME/fabrica/fabrica.toml`;
 //! 4. an explicit `--config <path>`;
 //! 5. `FABRICA__*` environment variables (nested keys use `__`, e.g.
 //!    `FABRICA__SERVER__PORT=8080`).
 //!
 //! Missing files at the fixed locations are skipped; a missing `--config` path
 //! is likewise tolerated so the same code path serves first-run.
 //!
 //! Any `*_file` key (`auth.secret_file`, `mail.password_file`) is read from disk
 //! after merging and supersedes its inline sibling. Secrets are wrapped in
 //! [`Secret`], which redacts itself in every `Debug`/`Serialize` context, so
 //! neither logging nor `fabrica config show` can leak them.
 mod secret;
 mod types;
 use std::path::{Path, PathBuf};
 use figment::Figment;
 use figment::providers::{Env, Format, Serialized, Toml};
 pub use crate::secret::{REDACTED, Secret};
 pub use crate::types::{
     Auth, Config, Database, Git, Instance, Log, LogFormat, LogLevel, Mail, MailBackend,
     MailEncryption, Server, Ssh, Storage, Ui,
 };
 /// System-wide configuration path, the lowest-priority file source.
 const ETC_PATH: &str = "/etc/fabrica/fabrica.toml";
 /// Prefix and nesting separator for environment overrides.
 const ENV_PREFIX: &str = "FABRICA__";
 /// Errors produced while loading or validating configuration.
 #[derive(Debug, thiserror::Error)]
 pub enum ConfigError {
     /// A file could not be parsed, a value had the wrong type, or an unknown key
     /// was present. Boxed because `figment::Error` is large relative to the
     /// other variants.
     #[error("failed to load configuration: {0}")]
     Load(Box<figment::Error>),
     /// A `*_file` secret could not be read. The path is included; the file's
     /// contents never are.
     #[error("failed to read secret file {path}: {source}")]
     SecretFile {
         /// The path that could not be read.
         path: PathBuf,
         /// The underlying I/O error.
         source: std::io::Error,
     },
     /// Validation failed. Each line is a distinct, actionable problem.
     #[error("invalid configuration:\n{0}")]
     Invalid(String),
     /// The effective configuration could not be serialized for display.
     #[error("failed to render configuration: {0}")]
     Render(#[from] toml::ser::Error),
+}
 /// A successfully loaded configuration together with any non-fatal warnings.
 #[derive(Debug, Clone)]
 pub struct Loaded {
     /// The validated, effective configuration.
     pub config: Config,
     /// Non-fatal advisories (e.g. an insecure cookie setting). The caller is
     /// expected to surface these to the operator.
     pub warnings: Vec<String>,
+}
 /// Load configuration from all standard sources, applying the `--config`
 /// override when supplied.
 ///
 /// # Errors
 ///
 /// Returns [`ConfigError`] if a source fails to parse, an unknown key is
 /// present, a `*_file` secret cannot be read, or validation fails.
 pub fn load(explicit: Option<&Path>) -> Result<Loaded, ConfigError> {
     load_from(&base_figment(explicit))
+}
 /// Load configuration from an already-assembled [`Figment`].
 ///
 /// This is the seam used by [`load`] and by tests that need to bypass the fixed
 /// filesystem locations. The provided figment is expected to include the
 /// [`Config::default`] layer as its base.
 ///
 /// # Errors
 ///
 /// Returns [`ConfigError`] under the same conditions as [`load`].
 pub fn load_from(figment: &Figment) -> Result<Loaded, ConfigError> {
     let mut config: Config = figment
         .extract()
         .map_err(|e| ConfigError::Load(Box::new(e)))?;
     resolve_secret_files(&mut config)?;
     let warnings = validate(&config)?;
     Ok(Loaded { config, warnings })
+}
 /// Assemble the layered figment for the standard load path.
 fn base_figment(explicit: Option<&Path>) -> Figment {
     let mut figment =
         Figment::from(Serialized::defaults(Config::default())).merge(Toml::file(ETC_PATH));
     if let Some(path) = xdg_config_path() {
         figment = figment.merge(Toml::file(path));
+    }
     if let Some(path) = explicit {
         figment = figment.merge(Toml::file(path));
+    }
     figment.merge(Env::prefixed(ENV_PREFIX).split("__"))
+}
 /// Resolve `$XDG_CONFIG_HOME/fabrica/fabrica.toml`, falling back to
 /// `$HOME/.config`.
 fn xdg_config_path() -> Option<PathBuf> {
     let base = match std::env::var_os("XDG_CONFIG_HOME") {
         Some(dir) if !dir.is_empty() => PathBuf::from(dir),
         _ => {
             let home = std::env::var_os("HOME").filter(|h| !h.is_empty())?;
             PathBuf::from(home).join(".config")
+        }
     };
     Some(base.join("fabrica").join("fabrica.toml"))
+}
 /// Read any `*_file` secrets and fold them onto their inline siblings.
 fn resolve_secret_files(config: &mut Config) -> Result<(), ConfigError> {
     if let Some(path) = &config.auth.secret_file {
         config.auth.secret = Some(read_secret(path)?);
+    }
     if let Some(path) = &config.mail.password_file {
         config.mail.password = Some(read_secret(path)?);
+    }
     Ok(())
+}
 /// Read a secret from a file, trimming a single trailing newline.
 fn read_secret(path: &Path) -> Result<Secret, ConfigError> {
     let raw = std::fs::read_to_string(path).map_err(|source| ConfigError::SecretFile {
         path: path.to_path_buf(),
         source,
     })?;
     Ok(Secret::new(raw.trim_end_matches(['\r', '\n']).to_string()))
+}
 /// Validate the effective configuration, failing fast with actionable messages.
 ///
 /// Returns the list of non-fatal warnings on success; returns
 /// [`ConfigError::Invalid`] with every hard error joined by newlines otherwise.
 fn validate(config: &Config) -> Result<Vec<String>, ConfigError> {
     let mut errors: Vec<String> = Vec::new();
     let mut warnings: Vec<String> = Vec::new();
     // instance.url must parse and must not carry a trailing slash.
     if let Err(e) = url::Url::parse(&config.instance.url) {
         errors.push(format!(
             "instance.url ({}) is not a valid URL: {e}",
             config.instance.url
         ));
     } else if config.instance.url.ends_with('/') {
         errors.push(format!(
             "instance.url ({}) must not have a trailing slash",
             config.instance.url
         ));
+    }
     if config.instance.default_branch.trim().is_empty() {
         errors.push("instance.default_branch must not be empty".to_string());
+    }
     // Storage directories must exist or be creatable.
     check_dir_creatable("storage.data_dir", &config.storage.data_dir, &mut errors);
     check_dir_creatable("storage.repo_dir", &config.storage.repo_dir, &mut errors);
     // SMTP delivery needs a host and a from address.
     if config.mail.backend == MailBackend::Smtp {
         if config.mail.host.trim().is_empty() {
             errors.push("mail.backend is \"smtp\" but mail.host is empty".to_string());
+        }
         if config.mail.from.trim().is_empty() {
             errors.push("mail.backend is \"smtp\" but mail.from is empty".to_string());
+        }
+    }
     // A secure cookie over plain HTTP will be dropped by browsers.
     if config.auth.cookie_secure && !config.instance.url.starts_with("https://") {
         warnings.push(
             "auth.cookie_secure is true but instance.url is not https; browsers will drop the \
              session cookie"
                 .to_string(),
         );
+    }
     if errors.is_empty() {
         Ok(warnings)
     } else {
         Err(ConfigError::Invalid(
             errors
                 .iter()
                 .map(|e| format!("  - {e}"))
                 .collect::<Vec<_>>()
                 .join("\n"),
         ))
+    }
+}
 /// Push an error unless `path` is an existing directory or has an existing
 /// directory ancestor (i.e. it could be created). Performs no filesystem
 /// mutation, so it is safe to call from `fabrica config check`.
 fn check_dir_creatable(label: &str, path: &Path, errors: &mut Vec<String>) {
     match path.metadata() {
         Ok(meta) if meta.is_dir() => {}
         Ok(_) => errors.push(format!(
             "{label} ({}) exists but is not a directory",
             path.display()
         )),
         Err(_) => {
             let mut ancestor = path.parent();
             while let Some(dir) = ancestor {
                 if dir.as_os_str().is_empty() {
                     break;
+                }
                 match dir.metadata() {
                     Ok(meta) if meta.is_dir() => return,
                     Ok(_) => {
                         errors.push(format!(
                             "{label} ({}) is not creatable: {} is not a directory",
                             path.display(),
                             dir.display()
                         ));
                         return;
+                    }
                     Err(_) => ancestor = dir.parent(),
+                }
+            }
             errors.push(format!(
                 "{label} ({}) does not exist and has no existing parent directory to create it in",
                 path.display()
             ));
+        }
+    }
+}
 impl Config {
     /// Render the effective configuration as TOML, with secrets redacted.
     ///
     /// # Errors
     ///
     /// Returns [`ConfigError::Render`] if serialization fails.
     pub fn to_toml_string(&self) -> Result<String, ConfigError> {
         Ok(toml::to_string_pretty(self)?)
+    }
+}
 #[cfg(test)]
 mod tests {
     #![allow(
         clippy::unwrap_used,
         clippy::expect_used,
         clippy::panic,
         clippy::result_large_err
     )]
     use figment::Jail;
     use figment::providers::{Format, Serialized, Toml};
     use super::*;
     /// Build a figment from defaults plus an inline TOML fragment — no
     /// filesystem or environment sources, so tests stay hermetic.
     fn from_toml(fragment: &str) -> Result<Loaded, ConfigError> {
         load_from(
             &Figment::from(Serialized::defaults(Config::default())).merge(Toml::string(fragment)),
+        )
+    }
     #[test]
     fn defaults_load_and_match() {
         // A bare config validates; the only advisory is the cookie-over-http
         // warning, since the default url is http and cookie_secure is true.
         let loaded = from_toml("").unwrap();
         assert_eq!(loaded.config, Config::default());
+    }
     #[test]
     fn later_sources_win() {
         let loaded = from_toml("[server]\nport = 9000\n").unwrap();
         assert_eq!(loaded.config.server.port, 9000);
         // Untouched keys keep their defaults.
         assert_eq!(loaded.config.server.address, "0.0.0.0");
+    }
     #[test]
     fn unknown_key_is_rejected() {
         let err = from_toml("[server]\nprot = 9000\n").unwrap_err();
         assert!(matches!(err, ConfigError::Load(_)), "got {err:?}");
         assert!(format!("{err}").contains("prot"));
+    }
     #[test]
     fn unknown_section_is_rejected() {
         let err = from_toml("[nope]\nx = 1\n").unwrap_err();
         assert!(matches!(err, ConfigError::Load(_)), "got {err:?}");
+    }
     #[test]
     fn enum_values_are_validated() {
         let err = from_toml("[mail]\nbackend = \"carrier-pigeon\"\n").unwrap_err();
         assert!(matches!(err, ConfigError::Load(_)), "got {err:?}");
+    }
     #[test]
     fn trailing_slash_url_is_rejected() {
         let err = from_toml("[instance]\nurl = \"https://git.example.com/\"\n").unwrap_err();
         match err {
             ConfigError::Invalid(msg) => assert!(msg.contains("trailing slash"), "{msg}"),
             other => panic!("expected Invalid, got {other:?}"),
+        }
+    }
     #[test]
     fn unparseable_url_is_rejected() {
         let err = from_toml("[instance]\nurl = \"not a url\"\n").unwrap_err();
         assert!(matches!(err, ConfigError::Invalid(_)), "got {err:?}");
+    }
     #[test]
     fn smtp_without_host_is_rejected() {
         let err = from_toml("[mail]\nbackend = \"smtp\"\n").unwrap_err();
         match err {
             ConfigError::Invalid(msg) => assert!(msg.contains("mail.host"), "{msg}"),
             other => panic!("expected Invalid, got {other:?}"),
+        }
+    }
     #[test]
     fn insecure_cookie_over_http_warns_but_loads() {
         // Default url is http and cookie_secure defaults to true.
         let loaded = from_toml("").unwrap();
         assert!(
             loaded.warnings.iter().any(|w| w.contains("cookie_secure")),
             "expected a cookie warning, got {:?}",
             loaded.warnings
         );
+    }
     #[test]
     fn https_url_produces_no_cookie_warning() {
         let loaded = from_toml("[instance]\nurl = \"https://git.example.com\"\n").unwrap();
         assert!(!loaded.warnings.iter().any(|w| w.contains("cookie_secure")));
+    }
     #[test]
     fn secrets_are_redacted_in_rendered_toml() {
         let loaded = from_toml("[auth]\nsecret = \"super-secret-key\"\n").unwrap();
         assert_eq!(
             loaded.config.auth.secret.as_ref().unwrap().expose(),
             "super-secret-key"
         );
         let rendered = loaded.config.to_toml_string().unwrap();
         assert!(rendered.contains(REDACTED));
         assert!(!rendered.contains("super-secret-key"));
+    }
     #[test]
     fn secret_file_supersedes_inline_and_reads_from_disk() {
         Jail::expect_with(|jail| {
             let path = jail.directory().join("secret.key");
             std::fs::write(&path, "from-file\n").unwrap();
             let fragment = format!(
                 "[auth]\nsecret = \"inline\"\nsecret_file = \"{}\"\n",
                 path.display()
             );
             let loaded = from_toml(&fragment).map_err(|e| e.to_string())?;
             assert_eq!(loaded.config.auth.secret.unwrap().expose(), "from-file");
             Ok(())
         });
+    }
     #[test]
     fn missing_secret_file_errors() {
         let err = from_toml("[auth]\nsecret_file = \"/no/such/fabrica/secret\"\n").unwrap_err();
         match err {
             ConfigError::SecretFile { path, .. } => {
                 assert!(path.ends_with("secret"));
+            }
             other => panic!("expected SecretFile, got {other:?}"),
+        }
+    }
     #[test]
     fn env_overrides_apply_with_double_underscore_nesting() {
         Jail::expect_with(|jail| {
             jail.set_env("FABRICA__SERVER__PORT", "7000");
             jail.set_env("FABRICA__INSTANCE__DEFAULT_BRANCH", "trunk");
             let loaded = load_from(&base_figment(None)).map_err(|e| e.to_string())?;
             assert_eq!(loaded.config.server.port, 7000);
             assert_eq!(loaded.config.instance.default_branch, "trunk");
             Ok(())
         });
+    }
     #[test]
     fn explicit_config_path_is_merged() {
         Jail::expect_with(|jail| {
             let path = jail.directory().join("fabrica.toml");
             std::fs::write(&path, "[instance]\nname = \"from-explicit\"\n").unwrap();
             let loaded = load_from(&base_figment(Some(&path))).map_err(|e| e.to_string())?;
             assert_eq!(loaded.config.instance.name, "from-explicit");
             Ok(())
         });
+    }
+}

@@ @@ -0,0 +1,101 @@ @@
 // 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/.
 //! A string wrapper that never reveals itself when logged or serialized.
 use std::fmt;
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 /// The placeholder rendered in every non-authorised view of a secret.
 pub const REDACTED: &str = "<redacted>";
 /// A secret string (signing key, SMTP password, …).
 ///
 /// The inner value is only reachable through [`Secret::expose`]. Both the
 /// [`fmt::Debug`] and [`Serialize`] implementations emit [`REDACTED`] instead of
 /// the real value, so a `Secret` can never leak through `tracing` output, a
 /// `Debug`-formatted [`crate::Config`], or `fabrica config show`.
 #[derive(Clone, PartialEq, Eq)]
 pub struct Secret(String);
 impl Secret {
     /// Wrap a value as a secret.
     #[must_use]
     pub fn new(value: String) -> Self {
         Self(value)
+    }
     /// Borrow the underlying secret value.
     ///
     /// This is the single deliberate escape hatch; call it only where the raw
     /// value is genuinely needed (e.g. signing a token or authenticating to an
     /// SMTP server), never for display or logging.
     #[must_use]
     pub fn expose(&self) -> &str {
         &self.0
+    }
+}
 impl fmt::Debug for Secret {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.write_str(REDACTED)
+    }
+}
 impl Serialize for Secret {
     fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
         serializer.serialize_str(REDACTED)
+    }
+}
 impl<'de> Deserialize<'de> for Secret {
     fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
         String::deserialize(deserializer).map(Self)
+    }
+}
 impl From<String> for Secret {
     fn from(value: String) -> Self {
         Self(value)
+    }
+}
 #[cfg(test)]
 mod tests {
     #![allow(clippy::unwrap_used, clippy::expect_used)]
     use serde::{Deserialize, Serialize};
     use super::*;
     #[test]
     fn debug_is_redacted() {
         let s = Secret::new("hunter2".to_string());
         assert_eq!(format!("{s:?}"), REDACTED);
         assert!(!format!("{s:?}").contains("hunter2"));
+    }
     #[derive(Serialize, Deserialize)]
     struct Holder {
         s: Secret,
+    }
     #[test]
     fn serialize_is_redacted_but_expose_is_not() {
         let holder = Holder {
             s: Secret::new("hunter2".to_string()),
         };
         let rendered = toml::to_string(&holder).unwrap();
         assert!(rendered.contains(REDACTED));
         assert!(!rendered.contains("hunter2"));
         assert_eq!(holder.s.expose(), "hunter2");
+    }
     #[test]
     fn deserialize_reads_the_real_value() {
         let holder: Holder = toml::from_str("s = \"real\"").unwrap();
         assert_eq!(holder.s.expose(), "real");
+    }
+}

@@ @@ -0,0 +1,384 @@ @@
 // 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/.
 //! The strongly-typed configuration tree.
 //!
 //! Field names and section layout mirror `fabrica.example.toml` exactly. Every
 //! struct is `deny_unknown_fields` so a typo in the TOML (or a stray
 //! `FABRICA__*` variable) is a load error rather than a silently ignored key.
 use std::path::PathBuf;
 use serde::{Deserialize, Serialize};
 use crate::secret::Secret;
 /// The complete, merged configuration.
 #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Config {
     /// Instance identity and global policy.
     pub instance: Instance,
     /// HTTP server binding and limits.
     pub server: Server,
     /// SSH server binding and advertised clone endpoint.
     pub ssh: Ssh,
     /// On-disk storage locations.
     pub storage: Storage,
     /// Database connection.
     pub database: Database,
     /// Authentication parameters and secrets.
     pub auth: Auth,
     /// Outbound mail.
     pub mail: Mail,
     /// Web UI presentation.
     pub ui: Ui,
     /// Git binary and pack-transport limits.
     pub git: Git,
     /// Logging.
     pub log: Log,
+}
 /// `[instance]` — identity and global policy.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Instance {
     /// Display name shown in the header and page titles.
     pub name: String,
     /// Canonical external URL, with no trailing slash.
     pub url: String,
     /// One-line description shown on the landing page.
     pub description: String,
     /// Default branch for newly created repositories.
     pub default_branch: String,
     /// Allow anonymous browse and clone of public repositories.
     pub allow_anonymous: bool,
+}
 impl Default for Instance {
     fn default() -> Self {
         Self {
             name: "fabrica".to_string(),
             url: "http://localhost:8080".to_string(),
             description: String::new(),
             default_branch: "main".to_string(),
             allow_anonymous: true,
+        }
+    }
+}
 /// `[server]` — HTTP binding and limits.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Server {
     /// Bind address for the HTTP listener.
     pub address: String,
     /// Bind port for the HTTP listener.
     pub port: u16,
     /// Trust `X-Forwarded-For` / `X-Forwarded-Proto` from a fronting proxy.
     pub behind_proxy: bool,
     /// Seconds to wait for in-flight requests to drain on shutdown.
     pub graceful_shutdown_secs: u64,
     /// Maximum request body size for non-pack routes, in bytes.
     pub max_body_bytes: u64,
+}
 impl Default for Server {
     fn default() -> Self {
         Self {
             address: "0.0.0.0".to_string(),
             port: 8080,
             behind_proxy: false,
             graceful_shutdown_secs: 20,
             max_body_bytes: 1_048_576,
+        }
+    }
+}
 /// `[ssh]` — SSH binding and advertised clone endpoint.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Ssh {
     /// Whether the SSH server is started at all.
     pub enabled: bool,
     /// Bind address for the SSH listener.
     pub address: String,
     /// Bind port for the SSH listener.
     pub port: u16,
     /// Path to the Ed25519 host key (generated on first run if absent).
     pub host_key_path: PathBuf,
     /// Hostname shown in clone URLs (may differ from the bind address).
     pub clone_host: String,
     /// Port shown in clone URLs (may differ from the bind port).
     pub clone_port: u16,
+}
 impl Default for Ssh {
     fn default() -> Self {
         Self {
             enabled: true,
             address: "0.0.0.0".to_string(),
             port: 2222,
             host_key_path: PathBuf::from("/var/lib/fabrica/ssh/host_ed25519"),
             clone_host: "localhost".to_string(),
             clone_port: 22,
+        }
+    }
+}
 /// `[storage]` — on-disk locations.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Storage {
     /// Base data directory (secrets, host key, SQLite database, tmp).
     pub data_dir: PathBuf,
     /// Directory holding the bare repositories, sharded by id prefix.
     pub repo_dir: PathBuf,
+}
 impl Default for Storage {
     fn default() -> Self {
         Self {
             data_dir: PathBuf::from("/var/lib/fabrica"),
             repo_dir: PathBuf::from("/var/lib/fabrica/repos"),
+        }
+    }
+}
 /// `[database]` — connection settings.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Database {
     /// Connection URL; `sqlite:` and `postgres:` schemes are detected at runtime.
     pub url: String,
     /// Maximum number of pooled connections.
     pub max_connections: u32,
+}
 impl Default for Database {
     fn default() -> Self {
         Self {
             url: "sqlite:///var/lib/fabrica/fabrica.db".to_string(),
             max_connections: 16,
+        }
+    }
+}
 /// `[auth]` — authentication parameters and secrets.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Auth {
     /// HS256 signing key. Generated on first run if neither this nor
     /// [`Auth::secret_file`] is set. Superseded by `secret_file` when present.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub secret: Option<Secret>,
     /// Path to a file holding the HS256 signing key; takes precedence over
     /// [`Auth::secret`].
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub secret_file: Option<PathBuf>,
     /// Session lifetime, in days.
     pub session_ttl_days: u32,
     /// API token lifetime, in days.
     pub token_ttl_days: u32,
     /// Name of the session cookie.
     pub cookie_name: String,
     /// Set the `Secure` attribute on the session cookie.
     pub cookie_secure: bool,
     /// Argon2id memory cost, in KiB.
     pub argon2_m_cost: u32,
     /// Argon2id time cost (iterations).
     pub argon2_t_cost: u32,
     /// Argon2id parallelism (lanes).
     pub argon2_p_cost: u32,
+}
 impl Default for Auth {
     fn default() -> Self {
         Self {
             secret: None,
             secret_file: None,
             session_ttl_days: 30,
             token_ttl_days: 90,
             cookie_name: "fabrica_session".to_string(),
             cookie_secure: true,
             argon2_m_cost: 19456,
             argon2_t_cost: 2,
             argon2_p_cost: 1,
+        }
+    }
+}
 /// Outbound mail backend.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum MailBackend {
     /// Deliver via SMTP (requires host and from).
     Smtp,
     /// Print messages to standard output (useful for development).
     Stdout,
     /// Discard messages; mail-dependent features are disabled.
     None,
+}
 /// Transport encryption for the SMTP backend.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum MailEncryption {
     /// Upgrade a plaintext connection with `STARTTLS`.
     Starttls,
     /// Connect with implicit TLS (SMTPS).
     Tls,
     /// No transport encryption.
     None,
+}
 /// `[mail]` — outbound mail.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Mail {
     /// Which delivery backend to use.
     pub backend: MailBackend,
     /// Envelope and header `From` address.
     pub from: String,
     /// SMTP server hostname.
     pub host: String,
     /// SMTP server port.
     pub port: u16,
     /// SMTP username.
     pub username: String,
     /// SMTP password. Superseded by [`Mail::password_file`] when present.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub password: Option<Secret>,
     /// Path to a file holding the SMTP password; takes precedence over
     /// [`Mail::password`].
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub password_file: Option<PathBuf>,
     /// Transport encryption.
     pub encryption: MailEncryption,
     /// Connection/handshake timeout, in seconds.
     pub timeout_secs: u64,
+}
 impl Default for Mail {
     fn default() -> Self {
         Self {
             backend: MailBackend::Stdout,
             from: "fabrica@localhost".to_string(),
             host: String::new(),
             port: 587,
             username: String::new(),
             password: None,
             password_file: None,
             encryption: MailEncryption::Starttls,
             timeout_secs: 15,
+        }
+    }
+}
 /// `[ui]` — web UI presentation.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Ui {
     /// Active theme: a file stem in [`Ui::themes_dir`] or an embedded theme name.
     pub theme: String,
     /// Directory scanned for additional `*.css` themes.
     pub themes_dir: PathBuf,
     /// Directory for asset overrides; embedded assets are used as a fallback.
     pub assets_dir: PathBuf,
     /// Show the theme picker and honour the per-visitor theme cookie.
     pub allow_theme_choice: bool,
     /// Show the (CI) runs navigation slot. Inert until CI ships.
     pub show_runs: bool,
     /// Lines of context shown around each diff hunk.
     pub diff_context_lines: u32,
     /// Skip syntax highlighting for blobs larger than this many bytes.
     pub max_highlight_bytes: u64,
     /// Refuse to render diffs larger than this many bytes.
     pub max_diff_bytes: u64,
     /// Maximum number of commits walked when annotating a tree listing.
     pub tree_history_limit: u32,
+}
 impl Default for Ui {
     fn default() -> Self {
         Self {
             theme: "dark".to_string(),
             themes_dir: PathBuf::from("/var/lib/fabrica/themes"),
             assets_dir: PathBuf::from("/var/lib/fabrica/assets"),
             allow_theme_choice: true,
             show_runs: false,
             diff_context_lines: 3,
             max_highlight_bytes: 1_048_576,
             max_diff_bytes: 5_242_880,
             tree_history_limit: 1000,
+        }
+    }
+}
 /// `[git]` — git binary and pack-transport limits.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Git {
     /// The `git` binary to spawn for pack transport and maintenance.
     pub binary: String,
     /// Maximum wall-clock time for a single pack transfer, in seconds.
     pub transport_timeout_secs: u64,
     /// Reject pushes whose received pack exceeds this many bytes.
     pub max_pack_size_bytes: u64,
+}
 impl Default for Git {
     fn default() -> Self {
         Self {
             binary: "git".to_string(),
             transport_timeout_secs: 3600,
             max_pack_size_bytes: 536_870_912,
+        }
+    }
+}
 /// Log output format.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum LogFormat {
     /// Human-readable, colourised when attached to a terminal.
     Pretty,
     /// One JSON object per line.
     Json,
+}
 /// Minimum log level. `RUST_LOG` is also honoured at runtime.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "lowercase")]
 pub enum LogLevel {
     /// Verbose tracing.
     Trace,
     /// Debugging detail.
     Debug,
     /// Normal operational messages.
     Info,
     /// Warnings only.
     Warn,
     /// Errors only.
     Error,
+}
 /// `[log]` — logging.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct Log {
     /// Minimum level emitted.
     pub level: LogLevel,
     /// Output format.
     pub format: LogFormat,
+}
 impl Default for Log {
     fn default() -> Self {
         Self {
             level: LogLevel::Info,
             format: LogFormat::Pretty,
+        }
+    }
+}

@@ @@ -0,0 +1,92 @@ @@
 # Configuration
 fabrica reads a single TOML file, layered over built-in defaults and overridable
 by the environment. A fully-commented starting point ships as
 [`fabrica.example.toml`](../fabrica.example.toml); copy it, keep only the keys
 you change, and validate with `fabrica config check`.
 ## Resolution order
 Sources are merged in the following order; a later source overrides an earlier
 one key-by-key:
 . Built-in defaults (every key has one — a bare config is valid).
 . `/etc/fabrica/fabrica.toml`
 . `$XDG_CONFIG_HOME/fabrica/fabrica.toml` (falls back to
    `$HOME/.config/fabrica/fabrica.toml`)
 . `--config <path>` passed on the command line
 . `FABRICA__*` environment variables
 Missing files are skipped silently, so the same binary serves a first-run
 machine and a fully-configured one.
 ### Environment overrides
 Environment variables are prefixed `FABRICA__` and nest with double
 underscores; single underscores inside a key are preserved:
 ```
 FABRICA__SERVER__PORT=8080              # -> server.port
 FABRICA__INSTANCE__DEFAULT_BRANCH=trunk # -> instance.default_branch
 FABRICA__LOG__LEVEL=debug               # -> log.level
 ```
 ### Secret files (`*_file`)
 Any key ending in `_file` reads its value from that file and takes precedence
 over its inline sibling. This keeps secrets out of the config file for
 agenix / systemd-creds / Docker secrets:
 | Inline key      | File key           | Contents                     |
 | --------------- | ------------------ | ---------------------------- |
 | `auth.secret`   | `auth.secret_file` | HS256 session-signing key    |
 | `mail.password` | `mail.password_file` | SMTP password              |
 A single trailing newline is trimmed from the file. Secrets are never logged,
 never appear in error messages, and render as `<redacted>` in
 `fabrica config show`.
 ## Validation
 Validation is strict and fails fast with actionable messages:
 - **Unknown keys are an error.** A typo (`prot` for `port`, a misplaced section)
   aborts the load rather than being ignored.
 - `instance.url` must be a valid URL and must not have a trailing slash.
 - `instance.default_branch` must not be empty.
 - `storage.data_dir` and `storage.repo_dir` must exist or be creatable (they may
   be created on first run).
 - `mail.backend = "smtp"` requires `mail.host` and `mail.from`.
 Some conditions are **warnings** — printed to stderr but non-fatal:
 - `auth.cookie_secure = true` with a non-`https` `instance.url`: browsers will
   drop the session cookie. Use this only for local development.
 ## Sections
 Each section maps one-to-one to a `[table]` in the TOML file. See
 `fabrica.example.toml` for the default value and a comment on every key.
 | Section      | Purpose                                                        |
 | ------------ | ------------------------------------------------------------- |
 | `[instance]` | Identity, canonical URL, default branch, anonymous access.    |
 | `[server]`   | HTTP bind address/port, proxy trust, body-size and drain limits. |
 | `[ssh]`      | SSH bind address/port, host key path, advertised clone endpoint. |
 | `[storage]`  | Data and repository directories on disk.                      |
 | `[database]` | Connection URL (`sqlite:`/`postgres:`) and pool size.         |
 | `[auth]`     | Session/token lifetimes, cookie settings, Argon2id cost, signing key. |
 | `[mail]`     | Backend (`smtp`/`stdout`/`none`), sender, SMTP endpoint and encryption. |
 | `[ui]`       | Theme, asset/theme directories, diff/highlight limits.        |
 | `[git]`      | `git` binary path and pack-transport limits.                  |
 | `[log]`      | Level and format (`pretty`/`json`).                           |
 ## Commands
 - `fabrica config check` — validate the effective configuration and exit. Prints
   `configuration ok` and exits `0` on success; prints the problems and exits `1`
   otherwise. Warnings are printed but do not change the exit status.
 - `fabrica config show` — print the effective, merged configuration with secrets
   redacted. Add `--json` for machine-readable output.
 Both honour the global `--config <path>` flag.

@@ @@ -85,3 +85,36 @@ the intended path if linear scan stops being fast enough. @@
 **Rationale:** flake-parts scales better as the flake grows (NixOS module,
 container image, multiple checks) and gives a cleaner multi-output structure. The
 spec permits either; picked one and stay consistent.
 ## 2026-07-24 — Secrets are a redact-by-default `Secret` newtype
 **Decision:** Secret configuration values (`auth.secret`, `mail.password`) are
 wrapped in a `config::Secret` newtype whose `Debug` and `Serialize` impls always
 emit `<redacted>`. The real value is reachable only through `Secret::expose`.
 **Alternatives:** Store secrets as plain `String` and redact them at each output
 site (`config show`, error messages, logs).
 **Rationale:** Redaction is the default and cannot be forgotten — a `Secret`
 cannot leak through `tracing`, a `Debug`-formatted `Config`, `fabrica config
 show`, or the JSON API, satisfying the spec's "secrets MUST NOT be logged,
 echoed, or included in error messages". Site-by-site redaction is one missed
 call away from a leak. Trade-off: serialization is lossy, so `Secret` is never
 round-tripped through our own `Serialize` (figment reads the raw value into the
 figment `Value` before deserialization, and `*_file` resolution reads from disk).
 ## 2026-07-24 — Strict config: unknown keys are errors, missing files are not
 **Decision:** Every config struct is `#[serde(deny_unknown_fields)]`, so an
 unknown key (typo, stale key, stray `FABRICA__*`) aborts the load. Missing files
 at the fixed locations (`/etc`, XDG) and a missing `--config` path are tolerated
 silently. Directory validation checks creatability without side effects (an
 existing directory ancestor), never creating anything during `config check`.
 **Alternatives:** Ignore unknown keys (serde default); require every file to
 exist; create directories during validation.
 **Rationale:** Failing fast on typos is worth more than forward-compatibility for
 a single-operator forge. Tolerating missing files lets one binary serve both a
 bare first-run machine and a fully-configured one. Side-effect-free validation
 keeps `config check` safe to run anywhere.

@@ @@ -0,0 +1,89 @@ @@
 # fabrica configuration — copy to /etc/fabrica/fabrica.toml (or point at it with
 # `fabrica --config <path>`) and edit. Every value shown below is the built-in
 # default, so you only need to keep the keys you actually change.
+#
 # Resolution order, later wins: built-in defaults -> /etc/fabrica/fabrica.toml
 # -> $XDG_CONFIG_HOME/fabrica/fabrica.toml -> --config <path> -> FABRICA__* env.
 # Environment overrides nest with double underscores, e.g.
 #   FABRICA__SERVER__PORT=8080
+#
 # Any *_file key reads its value from that file and wins over its inline sibling
 # (use it for agenix / systemd-creds / Docker secrets). Unknown keys are a hard
 # error, so a typo fails fast rather than being silently ignored.
+#
 # Validate with `fabrica config check`; print the effective config (secrets
 # redacted) with `fabrica config show`.
 [instance]
 name            = "fabrica"                 # shown in the header and page titles
 url             = "https://git.example.com" # canonical external URL, no trailing slash
 description     = "A small, private forge." # one line, shown on the landing page
 default_branch  = "main"                    # default branch for new repositories
 allow_anonymous = true                      # anonymous browse + clone of public repos
 [server]
 address                = "0.0.0.0"
 port                   = 8080
 behind_proxy           = false     # trust X-Forwarded-For / X-Forwarded-Proto
 graceful_shutdown_secs = 20        # drain in-flight requests for this long on shutdown
 max_body_bytes         = 1048576   # non-pack routes only
 [ssh]
 enabled       = true
 address       = "0.0.0.0"
 port          = 2222
 host_key_path = "/var/lib/fabrica/ssh/host_ed25519"  # generated on first run if absent
 clone_host    = "git.example.com"  # what the UI shows in clone URLs, may differ from bind
 clone_port    = 22
 [storage]
 data_dir = "/var/lib/fabrica"        # secrets, host key, SQLite db, scratch
 repo_dir = "/var/lib/fabrica/repos"  # bare repos, sharded by id prefix
 [database]
 url             = "sqlite:///var/lib/fabrica/fabrica.db"
 max_connections = 16
 # SQLite is opened with journal_mode=WAL, synchronous=NORMAL, foreign_keys=ON,
 # busy_timeout=5000. Postgres URLs (postgres://…) are detected automatically.
 [auth]
 # secret          = "…"                        # HS256 key; prefer secret_file below
 secret_file       = "/var/lib/fabrica/secret"  # generated on first run, mode 0600
 session_ttl_days  = 30
 token_ttl_days    = 90
 cookie_name       = "fabrica_session"
 cookie_secure     = true    # set false only if instance.url is plain http (dev)
 argon2_m_cost     = 19456   # KiB
 argon2_t_cost     = 2       # iterations
 argon2_p_cost     = 1       # lanes
 [mail]
 backend       = "smtp"                    # smtp | stdout | none
 from          = "fabrica@example.com"
 host          = "smtp.example.com"        # required when backend = "smtp"
 port          = 587
 username      = "fabrica"
 # password    = "…"                       # prefer password_file below
 password_file = "/run/secrets/fabrica-smtp"
 encryption    = "starttls"                # starttls | tls | none
 timeout_secs  = 15
 [ui]
 theme                = "dark"    # file stem in themes_dir, or an embedded theme name
 themes_dir           = "/var/lib/fabrica/themes"
 assets_dir           = "/var/lib/fabrica/assets"
 allow_theme_choice   = true      # show the theme picker; choice persists in a cookie
 show_runs            = false     # CI nav slot, inert until CI ships
 diff_context_lines   = 3
 max_highlight_bytes  = 1048576   # skip highlighting blobs larger than this
 max_diff_bytes       = 5242880   # refuse to render diffs larger than this
 tree_history_limit   = 1000      # commits walked when annotating a tree listing
 [git]
 binary                 = "git"       # must be >= 2.41 and on PATH
 transport_timeout_secs = 3600
 max_pack_size_bytes    = 536870912   # reject pushes with a larger received pack
 [log]
 level  = "info"     # trace | debug | info | warn | error (RUST_LOG also honoured)
 format = "pretty"   # pretty | json