safe_chains/registry/

build.rs

use std::collections::HashMap;

use crate::policy::{FlagTolerance, UnknownTolerance};
use crate::verdict::SafetyLevel;

use super::types::*;

/// A command definition is invalid. Returns `Err` from the enclosing function instead of panicking.
///
/// These checks run on USER-supplied configs as well as the built-in `commands/*.toml`: a
/// `~/.config/safe-chains.toml` or a repo `.safe-chains.toml` goes through exactly this code. An
/// abort there takes a PreToolUse hook down, and a crashed hook means the harness PROCEEDS — so a
/// typo in a config file used to disable safe-chains altogether. It was caught downstream by
/// `catch_unwind`, but panicking across a library boundary as control flow left two marks: the
/// default hook printed a panic and a backtrace to stderr on every invocation before anything could
/// catch it, and under libFuzzer a caught panic is still an abort, which is how `config_load` kept
/// failing.
///
/// The built-in definitions are compiled in and turn an `Err` back into a panic AT THE CALL SITE,
/// where it belongs: a broken `commands/*.toml` is a bug in this repository, not something a user
/// typed, and it should stop the process loudly.
macro_rules! fail {
    ($($arg:tt)*) => { return Err(format!($($arg)*)) };
}

/// `assert!` for the same checks: the condition must hold or the definition is rejected.
macro_rules! ensure {
    ($cond:expr, $($arg:tt)*) => {
        if !($cond) {
            return Err(format!($($arg)*));
        }
    };
}

#[path = "build_lower.rs"]
mod lower;
use lower::{lower_behavior, lower_output};

/// `optional_valued` compiles down to membership in BOTH other lists, and that is the whole
/// mechanism — the walk needs no third state.
///
/// Measured before choosing this (`policy::tests::a_flag_declared_in_both_lists_…`): `check_flags`
/// consults `standalone` first, so the BARE spelling matches there and cannot swallow the next
/// token; its `=` branch consults `valued`, so the GLUED spelling matches too. Both are honoured,
/// for different spellings, which is exactly what an optional-value flag means — and it matches
/// getopt, where an optional argument must be glued (`--flag=x`, never `--flag x`).
///
/// So this field buys INTENT, not behaviour. That distinction is the point: the same pair of
/// memberships previously meant either "a deliberate optional-value flag" or "somebody made a
/// mistake", and nothing could tell those apart — which is why the overlap audit was blocked on
/// this. Declaring it here says which one it is, and leaves a raw `standalone`+`valued` overlap
/// free to become a build error once the existing scopes are sorted.
///
/// NOT covered: the short glued form (`-r0`). That reaches the cluster loop, which walks byte by
/// byte and has no notion of "the rest of this token is my value". Recorded in TODO.md.
pub(super) fn build_policy(
    standalone: Vec<String>,
    valued: Vec<String>,
    optional_valued: Vec<String>,
    bare: Option<bool>,
    max_positional: Option<usize>,
    tolerate_unknown_short: Option<bool>,
    tolerate_unknown_long: Option<bool>,
    numeric_dash: Option<bool>,
) -> OwnedPolicy {
    let (mut standalone, mut valued) = (standalone, valued);
    for flag in optional_valued {
        standalone.push(flag.clone());
        valued.push(flag);
    }
    let unknown = match (tolerate_unknown_short.unwrap_or(false), tolerate_unknown_long.unwrap_or(false)) {
        (false, false) => UnknownTolerance::Strict,
        (true, false) => UnknownTolerance::Short,
        (false, true) => UnknownTolerance::Long,
        (true, true) => UnknownTolerance::Both,
    };
    OwnedPolicy {
        standalone,
        valued,
        bare: bare.unwrap_or(true),
        max_positional,
        tolerance: FlagTolerance { unknown, numeric_dash: numeric_dash.unwrap_or(false) },
    }
}

fn build_matrix(toml: TomlMatrix) -> MatrixSpec {
    let actions = toml
        .actions
        .into_iter()
        .map(|(name, action)| {
            let built = match action {
                TomlMatrixAction::Policy(policy_key) => MatrixAction { policy_key, guard: None, guard_short: None },
                TomlMatrixAction::Detailed(d) => MatrixAction { policy_key: d.policy, guard: d.guard, guard_short: d.guard_short },
            };
            (name, built)
        })
        .collect();
    MatrixSpec { parents: toml.parents, level: toml.level.into(), actions }
}

fn build_handler_policy(toml: TomlHandlerPolicy) -> OwnedPolicy {
    build_policy(
        toml.standalone, toml.valued, toml.optional_valued, toml.bare, toml.max_positional, toml.tolerate_unknown_short,
        toml.tolerate_unknown_long, toml.numeric_dash,
    )
}

fn build_verb_chain(toml: TomlVerbChain) -> VerbChainSpec {
    VerbChainSpec {
        level: toml.level.unwrap_or(TomlLevel::Inert).into(),
        separator: toml.separator.unwrap_or_else(|| "then".to_string()),
        main_standalone: toml.main_standalone,
        main_valued: toml.main_valued,
        main_variadic: toml.main_variadic,
        verbs: toml.verbs.into_iter().collect(),
    }
}

fn build_fallback(parent: &str, toml: TomlFallback) -> Result<FallbackSpec, String> {
    let policy = build_policy(
        toml.standalone, toml.valued, toml.optional_valued, toml.bare, toml.max_positional, toml.tolerate_unknown_short,
        toml.tolerate_unknown_long, toml.numeric_dash,
    );
    let level: SafetyLevel = toml.level.unwrap_or(TomlLevel::Inert).into();
    let positional_shape = match toml.positional_shape.as_deref() {
        None => None,
        Some(name) => match crate::policy::PositionalShape::from_name(name) {
            Some(shape) => Some(shape),
            None => fail!("{parent}: unknown fallback positional_shape `{name}` (known: path)"),
        },
    };
    let executor = match toml.executor.as_deref() {
        None => None,
        Some(name) => match ExecutorKind::from_name(name) {
            Some(kind) => Some(kind),
            None => fail!("{parent}: unknown fallback executor `{name}` (known: file, project)"),
        },
    };
    Ok(FallbackSpec {
        policy,
        level,
        positional_shape,
        executor,
        executor_redirect_flag: toml.executor_redirect_flag,
        passes_argv: toml.passes_argv.unwrap_or(false),
    })
}

fn allow_all_policy() -> OwnedPolicy {
    OwnedPolicy {
        standalone: Vec::new(),
        valued: Vec::new(),
        bare: true,
        max_positional: None,
        tolerance: FlagTolerance { unknown: UnknownTolerance::Both, numeric_dash: false },
    }
}

fn check_no_legacy_positional_style(name: &str, ps: Option<bool>) -> Result<(), String> {
    if ps.is_some() {
        fail!(
            "command '{name}': `positional_style` was removed. Use \
             `tolerate_unknown_short = true` for tools with single-dash \
             flags (pdftotext -help, sample -mayDie). Use \
             `tolerate_unknown_long = true` ONLY for tools whose \
             double-dash flag surface is genuinely unbounded (AWS CLI \
             style); double-dash unknowns silently pass when this is \
             on, which has caused safety bugs. Most tools need neither."
        );
    }
    Ok(())
}

fn filter_candidates(subs: Vec<TomlSub>) -> Result<impl Iterator<Item = TomlSub>, String> {
    // Asserted HERE, not in `build_subs`, because that is the whole point: a candidate sub is
    // dropped by this filter and never reaches `build_subs`, so a check placed there could never
    // fire for the case it targets. (It was written there first, and the red demo caught it.)
    //
    // Any nested subs a candidate declares are dropped with it — silently, since the file still
    // parses and builds. That is dead data wearing the shape of configuration: a reader sees the
    // nested surface declared and reasonably concludes it is in force. Same family as the
    // profiled-leaf assert in `build_subs`, where one field also makes another unreachable.
    for s in &subs {
        ensure!(
            !s.candidate.unwrap_or(false) || s.sub.is_empty(),
            "sub `{}`: a `candidate` sub is filtered out, so its nested subs are dead — drop the \
             nested subs, or drop `candidate` if the sub is meant to be live",
            s.name,
        );
    }
    // A `per_database` sub must not be a PREFIX of another declared task, or the two are
    // indistinguishable by shape and the suffix rule swallows the sibling.
    //
    // Rails makes this concrete: `db:migrate:primary` names a database and `db:migrate:redo` names
    // a different task, and nothing in the string says which. Marking `db:migrate` therefore read
    // `redo` as a database name and admitted a destructive task that is deliberately `candidate`.
    // The existing `examples_denied` entry caught it, which is why the check belongs here rather
    // than in a test.
    //
    // Checked in THIS function for the same reason the assert above is: candidates are filtered
    // out below, so a check placed after the filter could not see the very siblings that create
    // the ambiguity — `db:migrate:redo` and `db:migrate:reset` are both candidates.
    for s in &subs {
        if !s.per_database {
            continue;
        }
        let clash = subs.iter().find(|o| o.name.starts_with(&format!("{}:", s.name)));
        ensure!(
            clash.is_none(),
            "sub `{}`: `per_database` is unsound on a task that prefixes another (`{}`) — a \
             suffix cannot be told from a subtask name. Enumerate the variants, or drop the flag",
            s.name,
            clash.map(|c| c.name.as_str()).unwrap_or(""),
        );
    }
    Ok(subs.into_iter().filter(|s| !s.candidate.unwrap_or(false)))
}

/// Whether `name` is matched by a `first_arg` pattern (`get-*` prefix glob, or an exact token).
fn first_arg_matches(name: &str, patterns: &[String]) -> bool {
    patterns.iter().any(|p| match p.strip_suffix('*') {
        Some(prefix) => name.starts_with(prefix),
        None => p == name,
    })
}

/// Fail-closed guard for the `candidate`-under-glob footgun. A `candidate = true` sub is REMOVED from
/// the registry (so an older client sees "not found" and denies) — but if a sibling `first_arg` glob
/// would MATCH that removed name, the token falls through to the glob and AUTO-APPROVES, silently
/// inverting the author's intent (a deny becomes an allow). This panics at load when it detects that
/// shape, directing the author to a `profile`/explicit sub-sub instead. (The AWS blob-readers hit
/// exactly this: a `candidate` under `get-*` would have auto-approved.)
fn assert_no_candidate_shadowed_by_glob(parent: &str, subs: &[TomlSub], first_arg: &[String]) -> Result<(), String> {
    if first_arg.is_empty() {
        return Ok(());
    }
    for s in subs {
        if s.candidate.unwrap_or(false) && first_arg_matches(&s.name, first_arg) {
            fail!(
                "'{parent}' sub `{}` is `candidate = true` but its name is MATCHED by the sibling \
                 first_arg glob {first_arg:?} — it would fall through the filter and AUTO-APPROVE \
                 (a silent deny→allow inversion). Use `profile`/an explicit sub-sub to deny it, or \
                 drop it from the glob.",
                s.name,
            );
        }
    }
    Ok(())
}

/// Builds one SubSpec per alias (canonical name first, then each alias).
/// All entries share the same kind via Clone — the dispatcher doesn't care
/// which name the user invoked. `handler_policies` is consulted only by
/// subs that set `policy = "key"`.
pub(super) fn build_subs(
    parent: &str,
    toml: TomlSub,
    handler_policies: &std::collections::HashMap<String, OwnedPolicy>,
) -> Result<Vec<SubSpec>, String> {
    let aliases = toml.aliases.clone();
    let canonical = build_sub(parent, toml, handler_policies)?;
    let mut out = Vec::with_capacity(1 + aliases.len());
    for alias in aliases {
        out.push(SubSpec {
            name: alias,
            kind: canonical.kind.clone(),
            name_match: canonical.name_match,
            policy_ref: canonical.policy_ref.clone(),
            profile: canonical.profile.clone(),
            flags: canonical.flags.clone(),
            // An alias must inherit the allowlist: an empty list reads as "not yet enumerated" and
            // would let the alias spelling accept flags its canonical name rejects.
            allowed_standalone: canonical.allowed_standalone.clone(),
            allowed_valued: canonical.allowed_valued.clone(),
            allowed_unknown: canonical.allowed_unknown,
            eval_safe: canonical.eval_safe,
            eval_safe_flags: canonical.eval_safe_flags.clone(),
            eval_safe_flag_values: canonical.eval_safe_flag_values.clone(),
            eval_safe_required_flags: canonical.eval_safe_required_flags.clone(),
            // As with the flag allowlist: an alias spelling must carry the canonical sub's stdout
            // claim, or `$(git diff --name-only)` would be bounded while an aliased spelling of the
            // same sub fell back to unpinnable — the mirror of the sub-alias gate hole.
            output: canonical.output.clone(),
            network_destination: canonical.network_destination,
            destination_flag: canonical.destination_flag.clone(),
            loopback_valued: canonical.loopback_valued.clone(),
            loopback_effect: canonical.loopback_effect,
            output_path_flags: canonical.output_path_flags.clone(),
            writes_cwd: canonical.writes_cwd,
        });
    }
    out.push(canonical);
    Ok(out)
}

/// Enforce the research standard at build time (reading the TOML fields, so provenance is a
/// production-validated part of the tree, not dead metadata). A sub with a `profile` must name a
/// real archetype and cite a `fact` + `source`; each escalating `[[command.sub.flag]]` must name a
/// real archetype (or the `unclassified` fail-closed escape) and cite its own `fact` + `source`. A
/// mis-authored classification fails CLOSED — the registry panics at load rather than silently
/// under-recording why a subcommand sits above the auto-approve line.
fn assert_sub_provenance(parent: &str, toml: &TomlSub) -> Result<(), String> {
    let cited = |o: &Option<String>| o.as_deref().is_some_and(|s| !s.trim().is_empty());
    // A `judgment` is optional (the discretionary layer), but if given it must say something.
    let judged = |o: &Option<String>| o.as_deref().is_none_or(|s| !s.trim().is_empty());
    if let Some(p) = &toml.profile {
        ensure!(
            crate::engine::archetype::archetype(p).is_some(),
            "{parent} sub `{}`: profile `{p}` is not a known archetype (archetypes.toml)",
            toml.name,
        );
        ensure!(cited(&toml.fact), "{parent} sub `{}`: `profile` requires a `fact`", toml.name);
        ensure!(cited(&toml.source), "{parent} sub `{}`: `profile` requires a `source`", toml.name);
        ensure!(judged(&toml.judgment), "{parent} sub `{}`: `judgment`, if given, must not be blank", toml.name);
        // A profiled sub must say what flags it accepts. The engine classifies it from its archetype
        // without running the legacy flag walk, so an EMPTY list is not "nothing permitted" — before
        // this was enforced it meant "everything permitted", and `git rebase --exec 'rm -rf /'`
        // classified as an ordinary rebase. Declaring `tolerate_unknown_*` is the explicit way to say
        // a surface is genuinely unbounded; saying nothing at all is not an option.
        ensure!(
            !toml.standalone.is_empty()
                || !toml.valued.is_empty()
                || toml.tolerate_unknown_short == Some(true)
                || toml.tolerate_unknown_long == Some(true)
                || !toml.flag.is_empty(),
            "{parent} sub `{}`: a profiled sub must declare its flag surface — list `standalone`/\
             `valued`, or set `tolerate_unknown_long = true` if it is genuinely unbounded",
            toml.name,
        );
        // A profiled sub is a leaf: the engine classifies it by archetype, and its legacy kind is
        // forced to deny-all (below) — a nested Branching would sidestep that.
        ensure!(toml.sub.is_empty(), "{parent} sub `{}`: a profiled sub must be a leaf (no nested subs)", toml.name);
    }
    // `network_destination` classifies the destination onto the archetype's `locus.provenance`, so
    // it only has meaning on a profiled sub.
    ensure!(
        toml.network_destination != Some(true) || toml.profile.is_some(),
        "{parent} sub `{}`: `network_destination` requires a `profile`",
        toml.name,
    );
    ensure!(
        toml.destination_flag.is_none() || toml.network_destination == Some(true),
        "{parent} sub `{}`: `destination_flag` requires `network_destination`",
        toml.name,
    );
    // An output-file path is only meaningful on a profiled (`data-export`) sub — the engine gates
    // that file's write onto the sub's derived profile.
    ensure!(
        toml.output_path_flags.is_empty() || toml.profile.is_some(),
        "{parent} sub `{}`: `output_path_flags` requires a `profile`",
        toml.name,
    );
    for f in &toml.flag {
        ensure!(
            f.classifies == "unclassified" || crate::engine::archetype::archetype(&f.classifies).is_some(),
            "{parent} sub `{}` flag `{}`: classifies `{}` is not a known archetype",
            toml.name,
            f.name,
            f.classifies,
        );
        ensure!(cited(&f.fact), "{parent} sub `{}` flag `{}`: requires a `fact`", toml.name, f.name);
        ensure!(cited(&f.source), "{parent} sub `{}` flag `{}`: requires a `source`", toml.name, f.name);
        ensure!(judged(&f.judgment), "{parent} sub `{}` flag `{}`: `judgment`, if given, must not be blank", toml.name, f.name);
        ensure!(
            !(f.when_absent == Some(true) && f.value_prefix.is_some()),
            "{parent} sub `{}` flag `{}`: `when_absent` and `value_prefix` are mutually exclusive",
            toml.name,
            f.name,
        );
    }
    Ok(())
}

/// `loopback_localizes` says "pointed at this machine, clear the facets the destination decides".
/// Two things must hold or the claim is incoherent:
///
/// - it needs a `loopback_valued` flag, since nothing else can establish that the destination IS
///   this machine;
/// - a DESTROY archetype may not set it. The emulator claim is unverifiable — `ssh -L
///   8000:dynamodb.<region>.amazonaws.com:443` makes `localhost:8000` production — and a wrong
///   guess costs a stray write for a mutate and the data for a delete. Refusing it here rather than
///   relying on the resolver's runtime skip means no future sub opts out by accident.
fn assert_loopback_localizes_is_coherent(parent: &str, name: &str, toml: &TomlSub) -> Result<(), String> {
    // Both the admission gate (`presents_unlisted_flag`) and the delta (`sub_loopback_localizes`)
    // are reached only through the PROFILED sub walk, so on an unprofiled sub the declaration is
    // inert — the flag would simply be missing from the legacy lists and deny, with nothing saying
    // why. Fails closed, but silently, which is its own kind of bug.
    ensure!(
        toml.loopback_valued.is_empty() || toml.profile.is_some(),
        "{parent} sub `{name}`: `loopback_valued` needs `profile` — the gate is only consulted on \
         a profiled sub, so here it would do nothing at all",
    );
    if !toml.loopback_localizes.unwrap_or(false) {
        return Ok(());
    }
    ensure!(
        !toml.loopback_valued.is_empty(),
        "{parent} sub `{name}`: `loopback_localizes` requires a `loopback_valued` flag — without \
         one nothing can establish that the destination is this machine",
    );
    // Asked of the archetype's OPERATION facet, not of its name. A name test passes today only
    // because every destroy archetype happens to be called `*destroy*`; a later `remote-wipe` or
    // `bucket-purge` carrying `operation = "destroy"` would sail through it and localize. Deciding
    // by name rather than behavior is the exact mistake this classifier exists to avoid.
    let profile = toml.profile.as_deref().unwrap_or_default();
    let operation = crate::engine::archetype::archetype(profile).map(|c| c.operation);
    ensure!(
        operation != Some(crate::engine::facet::Operation::Destroy),
        "{parent} sub `{name}`: `profile = \"{profile}\"` carries `operation = destroy` and may \
         not set `loopback_localizes` — a loopback endpoint cannot be verified (an SSH tunnel makes \
         localhost mean production), and that is only unrecoverable for destroy",
    );
    Ok(())
}

pub(super) fn build_sub(
    parent: &str,
    mut toml: TomlSub,
    handler_policies: &std::collections::HashMap<String, OwnedPolicy>,
) -> Result<SubSpec, String> {
    check_no_legacy_positional_style(&toml.name, toml.positional_style)?;
    let name = toml.name.clone();
    let policy_ref = toml.policy.clone();
    let profile = toml.profile.clone();
    assert_sub_provenance(parent, &toml)?;
    assert_no_candidate_shadowed_by_glob(&format!("{parent} {}", toml.name), &toml.sub, &toml.first_arg)?;
    let flags = std::mem::take(&mut toml.flag)
        .into_iter()
        .map(|f| crate::registry::types::FlagProvenance {
            name: f.name,
            classifies: f.classifies,
            value_prefix: f.value_prefix,
            when_absent: f.when_absent.unwrap_or(false),
        })
        .collect();
    // A profiled sub is engine-classified and above the auto-approve line. Its LEGACY dispatch is
    // reached only when the engine ABSTAINS — e.g. a global flag (`git -c …`, `git -C …`) intervenes
    // before the subcommand, so `sub_archetypes`'s walk stops early. In that case the legacy kind
    // MUST deny outright (fail-closed), never fall through to a permissive default: force bare off,
    // no flags, no positionals.
    // Preserve the DECLARED lists before the legacy kind is zeroed: the engine classifies a profiled
    // sub from its archetype without ever running the legacy flag walk, so these are the only copy
    // that survives, and `sub_archetypes` validates against them.
    let (allowed_standalone, allowed_valued) = (toml.standalone.clone(), toml.valued.clone());
    let allowed_unknown = match (toml.tolerate_unknown_short.unwrap_or(false), toml.tolerate_unknown_long.unwrap_or(false)) {
        (false, false) => UnknownTolerance::Strict,
        (true, false) => UnknownTolerance::Short,
        (false, true) => UnknownTolerance::Long,
        (true, true) => UnknownTolerance::Both,
    };
    if profile.is_some() {
        toml.bare = Some(false);
        toml.standalone = Vec::new();
        toml.valued = Vec::new();
        toml.max_positional = Some(0);
    }
    let eval_safe = toml.eval_safe.unwrap_or(false);
    let eval_safe_flags = std::mem::take(&mut toml.eval_safe_flags);
    let eval_safe_flag_values = std::mem::take(&mut toml.eval_safe_flag_values);
    let eval_safe_required_flags = std::mem::take(&mut toml.eval_safe_required_flags);
    let network_destination = toml.network_destination.unwrap_or(false);
    let destination_flag = toml.destination_flag.clone();
    let output_path_flags = toml.output_path_flags.clone();
    let loopback_valued = toml.loopback_valued.clone();
    let loopback_effect = if toml.loopback_localizes.unwrap_or(false) { LoopbackEffect::Localizes } else { LoopbackEffect::AdmitOnly };
    assert_loopback_localizes_is_coherent(parent, &name, &toml)?;
    let valued_for_check = toml.valued.clone();
    assert_eval_safe_flags_require_tag(parent, &name, eval_safe, &eval_safe_flags)?;
    assert_eval_safe_flag_values_consistent(parent, &name, &eval_safe_flags, &eval_safe_flag_values)?;
    assert_eval_safe_valued_flags_declared(parent, &name, &eval_safe_flags, &valued_for_check, &eval_safe_flag_values)?;
    assert_eval_safe_required_flags_consistent(parent, &name, &eval_safe_flags, &eval_safe_required_flags)?;
    assert_sub_eval_safe_only_on_leaf(parent, &toml)?;
    let writes_cwd = super::cwd_writes::lower(parent, &name, toml.writes_cwd.as_deref(), &toml.output_dirs, toml.executor.as_deref())?;
    let output = lower_output(&format!("{parent} {name}"), toml.output.as_ref())?;
    Ok(SubSpec {
        name,
        output,
        writes_cwd,
        name_match: if toml.per_database { NameMatch::WithDatabaseSuffix } else { NameMatch::Exact },
        kind: build_sub_kind(parent, toml, handler_policies)?,
        policy_ref,
        profile,
        flags,
        allowed_standalone,
        allowed_valued,
        allowed_unknown,
        eval_safe,
        eval_safe_flags,
        eval_safe_flag_values,
        eval_safe_required_flags,
        network_destination,
        destination_flag,
        loopback_valued,
        loopback_effect,
        output_path_flags,
    })
}

fn assert_eval_safe_flag_values_consistent(
    parent: &str,
    name: &str,
    eval_safe_flags: &[String],
    eval_safe_flag_values: &std::collections::HashMap<String, Vec<String>>,
) -> Result<(), String> {
    for (flag, values) in eval_safe_flag_values {
        if !eval_safe_flags.iter().any(|f| f == flag) {
            fail!(
                "command '{parent}' sub `{name}` lists `{flag}` in \
                 `eval_safe_flag_values` but not in `eval_safe_flags`. \
                 A value allowlist only takes effect when the flag itself \
                 is allowed. Add `{flag}` to `eval_safe_flags` or remove \
                 the value entry."
            );
        }
        for value in values {
            if value.is_empty() || !value.chars().all(is_bare_literal_char) {
                fail!(
                    "command '{parent}' sub `{name}` has eval_safe_flag_values \
                     for `{flag}` containing value `{value:?}` with characters \
                     outside `[a-zA-Z0-9_./=-]`. The allowed-value set must \
                     itself be bare-literal so it can never embed a shell-\
                     expansion trigger into the substituted invocation."
                );
            }
        }
    }
    Ok(())
}

fn is_bare_literal_char(c: char) -> bool {
    c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '.' | '/' | '=')
}

fn assert_eval_safe_required_flags_consistent(
    parent: &str,
    name: &str,
    eval_safe_flags: &[String],
    eval_safe_required_flags: &[String],
) -> Result<(), String> {
    for flag in eval_safe_required_flags {
        if !eval_safe_flags.iter().any(|f| f == flag) {
            fail!(
                "command '{parent}' sub `{name}` lists `{flag}` in \
                 `eval_safe_required_flags` but not in `eval_safe_flags`. \
                 A required-flag constraint must be a subset of the \
                 allowed-flag set — otherwise the flag is required AND \
                 immediately denied. Add `{flag}` to `eval_safe_flags` or \
                 remove it from `eval_safe_required_flags`."
            );
        }
    }
    Ok(())
}

/// Every valued flag in `eval_safe_flags` must declare its value
/// posture in `eval_safe_flag_values`: either a concrete value
/// allowlist (`["env", "fish"]`) OR the explicit-unrestricted form
/// (`[]`). Without this, a contributor adding a short alias like
/// `-f` for an already-tagged `--format` would silently widen the
/// eval-safe surface to any value of `-f` — the v0.196.0 aws
/// near-miss in disguise.
fn assert_eval_safe_valued_flags_declared(
    parent: &str,
    name: &str,
    eval_safe_flags: &[String],
    valued: &[String],
    eval_safe_flag_values: &std::collections::HashMap<String, Vec<String>>,
) -> Result<(), String> {
    for flag in eval_safe_flags {
        if !valued.iter().any(|v| v == flag) {
            continue;
        }
        if !eval_safe_flag_values.contains_key(flag) {
            fail!(
                "command '{parent}' sub `{name}` lists `{flag}` in \
                 `eval_safe_flags` AND in `valued`, but `{flag}` has no \
                 entry in `eval_safe_flag_values`. Every valued flag \
                 tagged eval-safe must declare its value posture: \
                 either a concrete allowlist of safe values \
                 (`{flag} = [\"value-a\", \"value-b\"]`) or the \
                 explicit-unrestricted form (`{flag} = []`) signaling \
                 the contributor vetted that any value preserves shell-\
                 init output. Omitting an entry means the walker can't \
                 tell whether the value-following-flag is supposed to \
                 be checked, and a future short alias of `{flag}` \
                 could silently widen the eval-safe surface."
            );
        }
    }
    Ok(())
}

fn assert_eval_safe_flags_require_tag(parent: &str, name: &str, eval_safe: bool, flags: &[String]) -> Result<(), String> {
    if !flags.is_empty() && !eval_safe {
        fail!(
            "command '{parent}' sub `{name}` declares `eval_safe_flags` without \
             `eval_safe = true`. The flag allowlist only takes effect when the \
             sub is tagged eval-safe. Add `eval_safe = true` or drop \
             `eval_safe_flags`."
        );
    }
    Ok(())
}

fn assert_sub_eval_safe_only_on_leaf(parent: &str, toml: &TomlSub) -> Result<(), String> {
    if toml.eval_safe != Some(true) {
        return Ok(());
    }
    if !toml.sub.is_empty() {
        fail!(
            "command '{parent}' sub `{}` sets `eval_safe = true` AND has \
             nested [[command.sub.sub]] blocks. eval_safe must be tagged on \
             a leaf node — move the tag onto the specific sub-sub that emits \
             shell-init code. Otherwise the walker accepts any unmatched \
             sub-sub name as a positional, which is counter-intuitive.",
            toml.name,
        );
    }
    if toml.handler.is_some() {
        fail!(
            "command '{parent}' sub `{}` sets `eval_safe = true` AND \
             `handler = \"...\"`. Handler-based subs run Rust dispatch logic \
             whose shape the eval walker cannot introspect — eval-safety \
             requires a declarative leaf the registry can reason about.",
            toml.name,
        );
    }
    if toml.delegate_after.is_some() || toml.delegate_skip.is_some() {
        fail!(
            "command '{parent}' sub `{}` sets `eval_safe = true` AND \
             delegates to an inner command (delegate_after / delegate_skip). \
             The inner command's output is unrelated to this sub's vetting \
             — drop `eval_safe`.",
            toml.name,
        );
    }
    Ok(())
}

fn assert_eval_safe_tagged_command_has_researched_version(toml: &TomlCommand) -> Result<(), String> {
    let command_tagged = toml.eval_safe == Some(true);
    let any_sub_tagged = toml_has_any_eval_safe_sub(&toml.sub);
    if !command_tagged && !any_sub_tagged {
        return Ok(());
    }
    if toml.researched_version.is_none() {
        fail!(
            "command '{}' has `eval_safe = true` (on the command or a sub) \
             but no `researched_version`. eval-safe tags pin a per-tag trust \
             claim against a specific upstream snapshot — add the version \
             you researched (e.g. `researched_version = \"v2026.5.3\"`) so \
             the next contributor knows what to diff against.",
            toml.name,
        );
    }
    Ok(())
}

fn toml_has_any_eval_safe_sub(subs: &[TomlSub]) -> bool {
    subs.iter().any(|s| s.eval_safe == Some(true) || toml_has_any_eval_safe_sub(&s.sub))
}

fn assert_command_eval_safe_only_on_leaf(toml: &TomlCommand) -> Result<(), String> {
    if toml.eval_safe != Some(true) {
        return Ok(());
    }
    if !toml.sub.is_empty() {
        fail!(
            "command '{}' sets `eval_safe = true` at the command level AND \
             has [[command.sub]] blocks. Move the tag onto the specific \
             sub that emits shell-init code (e.g. `mise activate`) — \
             command-level tagging on a structured command is counter-\
             intuitive.",
            toml.name,
        );
    }
    // Note: command-level eval_safe IS allowed alongside `handler =
    // "..."`. The walker reads `spec.eval_safe` directly at the leaf
    // — it does not need to introspect the handler's dispatch logic.
    // The contributor takes responsibility for vouching that every
    // invocation the handler accepts AND that passes the eval_safe_*
    // flag checks produces shell-init stdout (typically narrowed via
    // `eval_safe_required_flags`). See fzf's TOML for the canonical
    // pattern.
    if toml.wrapper.is_some() {
        fail!(
            "command '{}' sets `eval_safe = true` AND `[command.wrapper]`. \
             Wrappers forward to an inner command — tagging the wrapper \
             would tag every wrapped invocation. Drop `eval_safe`.",
            toml.name,
        );
    }
    if toml.deny.unwrap_or(false) {
        fail!(
            "command '{}' sets both `deny = true` and `eval_safe = true`. \
             These are contradictory — deny silently dominates. Drop one.",
            toml.name,
        );
    }
    Ok(())
}

fn build_sub_kind(
    parent: &str,
    toml: TomlSub,
    handler_policies: &std::collections::HashMap<String, OwnedPolicy>,
) -> Result<DispatchKind, String> {
    if let Some(handler_name) = toml.handler {
        return Ok(DispatchKind::Custom {
            handler_name,
            doc_body: toml.doc_body,
            subs: Vec::new(),
            fallback: None,
            handler_policies: std::collections::HashMap::new(),
            matrices: Vec::new(),
        });
    }
    if toml.allow_all.unwrap_or(false) {
        return Ok(DispatchKind::Policy { policy: allow_all_policy(), level: toml.level.unwrap_or(TomlLevel::Inert).into() });
    }
    if let Some(sep) = toml.delegate_after {
        return Ok(DispatchKind::DelegateAfterSeparator { separator: sep });
    }
    if let Some(skip) = toml.delegate_skip {
        return Ok(DispatchKind::DelegateSkip { skip });
    }
    // A `credential_first_arg` gate forces the Branching path even with no sub-subs: only Branching
    // runs `skip_pre_flags`, so the credential check sees the real resource arg (`get -o yaml secret`),
    // not a leading flag — `FirstArg` reads `tokens[1]` verbatim and would be bypassed by a flag.
    if !toml.sub.is_empty() || !toml.credential_first_arg.is_empty() {
        // A sub may carry BOTH explicit sub-subs AND a fallback `first_arg` glob (a service that
        // auto-approves its read verbs via `get-*`/`describe-*` but carves specific dangerous actions
        // out to profiled sub-subs). Dispatch checks the explicit subs FIRST, then the glob
        // (dispatch.rs), so the carve-outs escalate while the benign reads still glob-match. Mirror
        // the command-level Branching, which already threads `first_arg` through; the sub level used
        // to hard-drop it (`Vec::new()`), which made "glob + carve-out" inexpressible.
        let first_arg_level = toml.level.unwrap_or(TomlLevel::Inert).into();
        return Ok(DispatchKind::Branching {
            subs: filter_candidates(toml.sub)?
                .map(|s| build_subs(parent, s, handler_policies))
                .collect::<Result<Vec<_>, _>>()?
                .into_iter()
                .flatten()
                .collect(),
            bare_flags: Vec::new(),
            bare_ok: toml.nested_bare.unwrap_or(false),
            pre_standalone: toml.standalone,
            pre_valued: toml.valued,
            first_arg: toml.first_arg,
            first_arg_level,
            first_arg_standalone: toml.first_arg_standalone,
            first_arg_valued: toml.first_arg_valued,
            first_arg_loopback_valued: toml.first_arg_loopback_valued,
            credential_first_arg: toml.credential_first_arg,
            // A nested sub level; the selector is only ever leading, so it belongs to the command.
            toolchain_selector: false,
        });
    }
    build_policy_sub_kind(parent, toml, handler_policies)
}

fn build_policy_sub_kind(
    parent: &str,
    toml: TomlSub,
    handler_policies: &std::collections::HashMap<String, OwnedPolicy>,
) -> Result<DispatchKind, String> {
    let policy = if let Some(key) = &toml.policy {
        if !toml.standalone.is_empty() || !toml.valued.is_empty() {
            fail!(
                "command '{parent}' sub `{}` sets both `policy = \"{}\"` and \
                 inline standalone/valued — pick one. Either drop the inline \
                 lists (and rely on the referenced handler_policy) or drop \
                 the `policy` field.",
                toml.name,
                key,
            );
        }
        match handler_policies.get(key).cloned() {
            Some(p) => p,
            None => fail!(
                "command '{parent}' sub `{}` references handler_policy \
                 `{key}` which is not declared. Add a \
                 [command.handler_policy.{key}] block or fix the typo.",
                toml.name,
            ),
        }
    } else {
        build_policy(
            toml.standalone, toml.valued, toml.optional_valued, toml.bare, toml.max_positional, toml.tolerate_unknown_short,
            toml.tolerate_unknown_long, toml.numeric_dash,
        )
    };
    let level: SafetyLevel = toml.level.unwrap_or(TomlLevel::Inert).into();
    if let Some(name) = toml.executor.as_deref() {
        let Some(kind) = ExecutorKind::from_name(name) else {
            fail!("command '{parent}' sub `{}`: unknown executor `{name}` (known: file, project)", toml.name)
        };
        let shape = match toml.positional_shape.as_deref() {
            None => None,
            Some(s) => match crate::policy::PositionalShape::from_name(s) {
                Some(shape) => Some(shape),
                None => fail!("command '{parent}' sub `{}`: unknown positional_shape `{s}`", toml.name),
            },
        };
        return Ok(DispatchKind::Executor {
            policy,
            level,
            kind,
            redirect_flag: toml.executor_redirect_flag,
            shape,
            passes_argv: toml.passes_argv.unwrap_or(false),
        });
    }
    if !toml.write_flags.is_empty() {
        return Ok(DispatchKind::WriteFlagged { policy, base_level: level, write_flags: toml.write_flags });
    }
    if let Some(guard) = toml.guard {
        let mut require_any = vec![guard];
        if let Some(short) = toml.guard_short {
            require_any.push(short);
        }
        return Ok(DispatchKind::RequireAny { require_any, policy, level, accept_bare_help: true });
    }
    if !toml.first_arg.is_empty() {
        return Ok(DispatchKind::FirstArg {
            patterns: toml.first_arg,
            level,
            standalone: toml.first_arg_standalone,
            valued: toml.first_arg_valued,
            loopback_valued: toml.first_arg_loopback_valued,
        });
    }
    if !toml.require_any.is_empty() {
        return Ok(DispatchKind::RequireAny { require_any: toml.require_any, policy, level, accept_bare_help: false });
    }
    Ok(DispatchKind::Policy { policy, level })
}

/// Diagnostic for a configuration class that silently breaks flag dispatch:
/// a structured command (with `[[command.sub]]` blocks) cannot also use the
/// flat-style top-level fields. When subs are present, top-level standalone/
/// valued/max_positional/positional_style/numeric_dash are dropped — the
/// dispatch routes through the Branching path. The fix is to either remove
/// the subs (if the command is meant to be flat) or move global flags into
/// a `[command.wrapper]` block.
fn assert_flat_or_structured(toml: &TomlCommand) -> Result<(), String> {
    if toml.sub.is_empty() {
        return Ok(());
    }
    let mut conflicts = Vec::new();
    if !toml.standalone.is_empty() {
        conflicts.push("standalone");
    }
    if !toml.valued.is_empty() {
        conflicts.push("valued");
    }
    if toml.max_positional.is_some() {
        conflicts.push("max_positional");
    }
    if toml.tolerate_unknown_short.is_some() {
        conflicts.push("tolerate_unknown_short");
    }
    if toml.tolerate_unknown_long.is_some() {
        conflicts.push("tolerate_unknown_long");
    }
    if toml.numeric_dash.is_some() {
        conflicts.push("numeric_dash");
    }
    if !conflicts.is_empty() {
        fail!(
            "command '{}' mixes flat-style top-level fields ({}) with [[command.sub]] blocks. \
             When subs are present these fields are silently dropped. \
             Either drop the subs (if the command is flat) or move global \
             flags into a [command.wrapper] block.",
            toml.name,
            conflicts.join(", "),
        );
    }
    Ok(())
}

fn assert_matrix_policy_keys_exist(toml: &TomlCommand) -> Result<(), String> {
    if toml.matrix.is_empty() {
        return Ok(());
    }
    for matrix in &toml.matrix {
        for (action_name, action) in &matrix.actions {
            let policy_key = match action {
                TomlMatrixAction::Policy(k) => k,
                TomlMatrixAction::Detailed(d) => &d.policy,
            };
            if !toml.handler_policy.contains_key(policy_key) {
                fail!(
                    "command '{}' matrix action `{}` references \
                     handler_policy `{}` which is not declared. \
                     Add a [command.handler_policy.{}] block or fix the typo.",
                    toml.name,
                    action_name,
                    policy_key,
                    policy_key,
                );
            }
        }
    }
    Ok(())
}

fn assert_matrix_no_duplicate_parent_action(toml: &TomlCommand) -> Result<(), String> {
    if toml.matrix.len() < 2 {
        return Ok(());
    }
    let mut seen: std::collections::HashSet<(String, String)> = std::collections::HashSet::new();
    for matrix in &toml.matrix {
        for parent in &matrix.parents {
            for action in matrix.actions.keys() {
                let key = (parent.clone(), action.clone());
                if !seen.insert(key) {
                    fail!(
                        "command '{}' matrix has duplicate (parent, action) pair \
                         (`{}`, `{}`). The first match would silently win — \
                         consolidate into one matrix block or remove the duplicate.",
                        toml.name,
                        parent,
                        action,
                    );
                }
            }
        }
    }
    Ok(())
}

fn assert_fallback_requires_handler(toml: &TomlCommand) -> Result<(), String> {
    if toml.fallback.is_some() && toml.handler.is_none() {
        fail!(
            "command '{}' declares [command.fallback] without a handler. \
             Fallback grammars are only consulted via \
             registry::try_fallback_grammar() from a Rust handler — without \
             handler = \"...\" the block is silently dropped. \
             Either set handler or remove [command.fallback].",
            toml.name,
        );
    }
    Ok(())
}

/// Validate and lower a top-level command's `[[command.flag]]` classifying flags — the flat-command
/// analog of a profiled sub's escalating flags. Each must name a known archetype (or `unclassified`)
/// and cite `fact`/`source`; `when_absent`/`value_prefix` are mutually exclusive. Mirrors the per-sub
/// check in `assert_sub_provenance`.
fn build_command_archetype_flags(cmd: &str, flags: Vec<TomlSubFlag>) -> Result<Vec<crate::registry::types::FlagProvenance>, String> {
    let cited = |o: &Option<String>| o.as_deref().is_some_and(|s| !s.trim().is_empty());
    let judged = |o: &Option<String>| o.as_deref().is_none_or(|s| !s.trim().is_empty());
    flags
        .into_iter()
        .map(|f| {
            ensure!(
                f.classifies == "unclassified" || crate::engine::archetype::archetype(&f.classifies).is_some(),
                "command `{cmd}` flag `{}`: classifies `{}` is not a known archetype",
                f.name,
                f.classifies,
            );
            ensure!(cited(&f.fact), "command `{cmd}` flag `{}`: requires a `fact`", f.name);
            ensure!(cited(&f.source), "command `{cmd}` flag `{}`: requires a `source`", f.name);
            ensure!(judged(&f.judgment), "command `{cmd}` flag `{}`: `judgment`, if given, must not be blank", f.name);
            ensure!(
                !(f.when_absent == Some(true) && f.value_prefix.is_some()),
                "command `{cmd}` flag `{}`: `when_absent` and `value_prefix` are mutually exclusive",
                f.name,
            );
            Ok(crate::registry::types::FlagProvenance {
                name: f.name,
                classifies: f.classifies,
                value_prefix: f.value_prefix,
                when_absent: f.when_absent.unwrap_or(false),
            })
        })
        .collect()
}

#[allow(clippy::too_many_lines)]
pub(super) fn build_command(toml: TomlCommand, category: &str) -> Result<CommandSpec, String> {
    assert_flat_or_structured(&toml)?;
    assert_fallback_requires_handler(&toml)?;
    assert_matrix_policy_keys_exist(&toml)?;
    assert_no_candidate_shadowed_by_glob(&toml.name, &toml.sub, &toml.first_arg)?;
    assert_matrix_no_duplicate_parent_action(&toml)?;
    assert_command_eval_safe_only_on_leaf(&toml)?;
    assert_eval_safe_tagged_command_has_researched_version(&toml)?;
    check_no_legacy_positional_style(&toml.name, toml.positional_style)?;
    let cat = category.to_string();
    let desc = toml.description.unwrap_or_default();
    let researched_version = toml.researched_version;
    let examples_safe = toml.examples_safe;
    let examples_denied = toml.examples_denied;
    let eval_safe = toml.eval_safe.unwrap_or(false);
    let eval_safe_flags = toml.eval_safe_flags;
    let eval_safe_flag_values = toml.eval_safe_flag_values;
    let eval_safe_required_flags = toml.eval_safe_required_flags;
    if !eval_safe_flags.is_empty() && !eval_safe {
        fail!(
            "command '{}' declares `eval_safe_flags` without `eval_safe = true`. \
             The flag allowlist only takes effect when the command is tagged \
             eval-safe. Add `eval_safe = true` or drop `eval_safe_flags`.",
            toml.name,
        );
    }
    assert_eval_safe_flag_values_consistent(&toml.name, "<command>", &eval_safe_flags, &eval_safe_flag_values)?;
    assert_eval_safe_valued_flags_declared(&toml.name, "<command>", &eval_safe_flags, &toml.valued, &eval_safe_flag_values)?;
    assert_eval_safe_required_flags_consistent(&toml.name, "<command>", &eval_safe_flags, &eval_safe_required_flags)?;
    let behavior = lower_behavior(&toml.name, toml.behavior.as_ref())?;
    let output = lower_output(&toml.name, toml.output.as_ref())?;
    let writes_cwd = super::cwd_writes::lower(&toml.name, "<command>", toml.writes_cwd.as_deref(), &toml.output_dirs, None)?;
    let env_assignment_positionals = toml.env_assignment_positionals.unwrap_or(false);
    let archetype_flags = build_command_archetype_flags(&toml.name, toml.flag)?;
    if toml.deny.unwrap_or(false) {
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::Policy {
                policy: OwnedPolicy {
                    standalone: Vec::new(),
                    valued: Vec::new(),
                    bare: false,
                    max_positional: Some(0),
                    tolerance: FlagTolerance::default(),
                },
                level: SafetyLevel::Inert,
            },
        });
    }
    if let Some(vc) = toml.verb_chain {
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::VerbChain(build_verb_chain(vc)),
        });
    }

    if let Some(handler_name) = toml.handler {
        // Build handler_policies first so subs that use `policy = "key"`
        // can resolve the reference at build time.
        let handler_policies: std::collections::HashMap<String, OwnedPolicy> =
            toml.handler_policy.into_iter().map(|(k, v)| (k, build_handler_policy(v))).collect();
        let parent_name = toml.name.clone();
        let subs: Vec<SubSpec> = filter_candidates(toml.sub)?
            .map(|s| build_subs(&parent_name, s, &handler_policies))
            .collect::<Result<Vec<_>, _>>()?
            .into_iter()
            .flatten()
            .collect();
        let fallback = toml.fallback.map(|f| build_fallback(&toml.name, f)).transpose()?;
        let matrices = toml.matrix.into_iter().map(build_matrix).collect();
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::Custom { handler_name, doc_body: toml.doc_body, subs, fallback, handler_policies, matrices },
        });
    }

    if let Some(w) = toml.wrapper {
        if !toml.sub.is_empty() || !toml.bare_flags.is_empty() {
            let first_arg_level = toml.level.unwrap_or(TomlLevel::Inert).into();
            let parent_name = toml.name.clone();
            return Ok(CommandSpec {
                name: toml.name,
                description: desc,
                aliases: toml.aliases,
                url: toml.url,
                category: cat,
                researched_version,
                examples_safe,
                examples_denied,
                eval_safe,
                eval_safe_flags: eval_safe_flags.clone(),
                eval_safe_flag_values: eval_safe_flag_values.clone(),
                eval_safe_required_flags: eval_safe_required_flags.clone(),
                path_gate: toml.path_gate,
                archetype_flags: archetype_flags.clone(),
                behavior: behavior.clone(),
                output,
                writes_cwd,
                env_assignment_positionals,
                kind: DispatchKind::Branching {
                    bare_flags: toml.bare_flags,
                    subs: filter_candidates(toml.sub)?
                        .map(|s| build_subs(&parent_name, s, &std::collections::HashMap::new()))
                        .collect::<Result<Vec<_>, _>>()?
                        .into_iter()
                        .flatten()
                        .collect(),
                    pre_standalone: w.standalone,
                    pre_valued: w.valued,
                    bare_ok: toml.bare.unwrap_or(false),
                    first_arg: toml.first_arg,
                    first_arg_standalone: toml.first_arg_standalone,
                    first_arg_valued: toml.first_arg_valued,
                    first_arg_loopback_valued: toml.first_arg_loopback_valued,
                    first_arg_level,
                    credential_first_arg: toml.credential_first_arg,
                    toolchain_selector: w.toolchain_selector.unwrap_or(false),
                },
            });
        }
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::Wrapper {
                standalone: w.standalone,
                valued: w.valued,
                positional_skip: w.positional_skip.unwrap_or(0),
                separator: w.separator,
                bare_ok: w.bare_ok.unwrap_or(false),
            },
        });
    }

    if !toml.sub.is_empty() || !toml.bare_flags.is_empty() {
        let first_arg_level = toml.level.unwrap_or(TomlLevel::Inert).into();
        let parent_name = toml.name.clone();
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::Branching {
                bare_flags: toml.bare_flags,
                subs: filter_candidates(toml.sub)?
                    .map(|s| build_subs(&parent_name, s, &std::collections::HashMap::new()))
                    .collect::<Result<Vec<_>, _>>()?
                    .into_iter()
                    .flatten()
                    .collect(),
                pre_standalone: Vec::new(),
                pre_valued: Vec::new(),
                bare_ok: toml.bare.unwrap_or(false),
                first_arg: toml.first_arg,
                first_arg_level,
                first_arg_standalone: toml.first_arg_standalone,
                first_arg_valued: toml.first_arg_valued,
                first_arg_loopback_valued: toml.first_arg_loopback_valued,
                credential_first_arg: toml.credential_first_arg,
                // Declared on `[command.wrapper]`, which this arm is the no-wrapper case of.
                toolchain_selector: false,
            },
        });
    }

    let policy = build_policy(
        toml.standalone, toml.valued, toml.optional_valued, toml.bare, toml.max_positional, toml.tolerate_unknown_short,
        toml.tolerate_unknown_long, toml.numeric_dash,
    );

    let level = toml.level.unwrap_or(TomlLevel::Inert).into();

    if !toml.first_arg.is_empty() {
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::FirstArg {
                patterns: toml.first_arg,
                level,
                standalone: toml.first_arg_standalone,
                valued: toml.first_arg_valued,
                loopback_valued: toml.first_arg_loopback_valued,
            },
        });
    }

    if !toml.write_flags.is_empty() {
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::WriteFlagged { policy, base_level: level, write_flags: toml.write_flags },
        });
    }

    if !toml.require_any.is_empty() {
        return Ok(CommandSpec {
            name: toml.name,
            description: desc,
            aliases: toml.aliases,
            url: toml.url,
            category: cat,
            researched_version,
            examples_safe,
            examples_denied,
            eval_safe,
            eval_safe_flags: eval_safe_flags.clone(),
            eval_safe_flag_values: eval_safe_flag_values.clone(),
            eval_safe_required_flags: eval_safe_required_flags.clone(),
            path_gate: toml.path_gate,
            archetype_flags: archetype_flags.clone(),
            behavior: behavior.clone(),
            output,
            writes_cwd,
            env_assignment_positionals,
            kind: DispatchKind::RequireAny { require_any: toml.require_any, policy, level, accept_bare_help: false },
        });
    }

    Ok(CommandSpec {
        env_assignment_positionals,
        name: toml.name,
        description: desc,
        aliases: toml.aliases,
        url: toml.url,
        category: cat,
        researched_version,
        examples_safe,
        examples_denied,
        eval_safe,
        eval_safe_flags,
        eval_safe_flag_values,
        eval_safe_required_flags,
        path_gate: toml.path_gate,
        archetype_flags,
        behavior,
        output,
        writes_cwd,
        kind: DispatchKind::Policy { policy, level },
    })
}

/// Build every command definition in `source`, or the first reason one is invalid.
///
/// Returns `Err` rather than panicking because this reads USER files too — see the `fail!` macro at
/// the top of this module. The built-in `commands/*.toml` are compiled in and unwrap the result at
/// their call site, so a broken definition in this repository still stops the process loudly.
pub fn load_toml(source: &str, category: &str) -> Result<Vec<CommandSpec>, String> {
    let file: TomlFile = match toml::from_str(source) {
        Ok(f) => f,
        Err(e) => {
            let preview: String = source.chars().take(80).collect();
            fail!("invalid TOML command definition: {e}\n  source begins: {preview}");
        }
    };
    file.command
        .into_iter()
        .filter(|cmd| !cmd.candidate.unwrap_or(false))
        .map(|cmd| build_command(cmd, category))
        .collect()
}

pub fn build_registry(specs: Vec<CommandSpec>) -> HashMap<String, CommandSpec> {
    let mut map = HashMap::new();
    for spec in specs {
        insert_spec(&mut map, spec);
    }
    map
}

/// Insert a CommandSpec into the registry, registering both its canonical
/// name and each alias. Existing entries for the same command name are
/// removed first, so a custom-TOML override of `gh` replaces every
/// built-in alias of `gh` rather than leaving stale aliases pointing at
/// the old spec.
pub fn insert_spec(map: &mut HashMap<String, CommandSpec>, spec: CommandSpec) {
    map.retain(|_, s| s.name != spec.name);
    for alias in &spec.aliases {
        map.insert(
            alias.clone(),
            CommandSpec {
                // Carried, not defaulted: `typeset` is an alias of `declare`, and dropping this here
                // would let the alias put a variable into the environment unclassified while the
                // canonical spelling denied.
                env_assignment_positionals: spec.env_assignment_positionals,
                name: spec.name.clone(),
                description: spec.description.clone(),
                aliases: vec![],
                url: spec.url.clone(),
                category: spec.category.clone(),
                researched_version: spec.researched_version.clone(),
                examples_safe: vec![],
                examples_denied: vec![],
                eval_safe: spec.eval_safe,
                eval_safe_flags: spec.eval_safe_flags.clone(),
                eval_safe_flag_values: spec.eval_safe_flag_values.clone(),
                eval_safe_required_flags: spec.eval_safe_required_flags.clone(),
                // Aliases are canonicalized (`registry::canonical_name`) before `should_deny` and
                // before the engine's behavior lookup, so the canonical spec's `path_gate` /
                // `behavior` is what's consulted — the alias entry never needs either.
                path_gate: None,
                archetype_flags: Vec::new(),
                behavior: None,
                output: None,
                writes_cwd: None,
                kind: spec.kind.clone(),
            },
        );
    }
    map.insert(spec.name.clone(), spec);
}