mind-cli 0.12.0

//! Implementation of `mind dump` (DUMP-1 through DUMP-8).
//!
//! Writes a super-source `mind.toml` that reproduces the current melded and
//! installed state, so melding the output recreates the same source set and
//! install selection.

use std::collections::{BTreeSet, HashMap};
use std::io::Write;
use std::path::PathBuf;

use serde::Serialize;

use crate::catalog;
use crate::error::{MindError, Result};
use crate::manifest::Manifest;
use crate::mindfile::MindToml;
use crate::paths::Paths;
use crate::source::{Registry, Source};

// ---------------------------------------------------------------------------
// Serializable shapes that round-trip through `toml::from_str::<MindToml>`.
// Field names match the serde renames in mindfile.rs exactly (deny_unknown_fields).
// ---------------------------------------------------------------------------

/// Top-level emitted document.
#[derive(Serialize)]
struct DumpDoc {
    source: DumpSource,
    discover: DumpDiscover,
}

/// `[source]` section of the emitted document.
#[derive(Serialize)]
struct DumpSource {
    description: String,
}

/// `[discover]` section of the emitted document.
#[derive(Serialize)]
struct DumpDiscover {
    sources: Vec<DumpEntry>,
}

/// One `[[discover.sources]]` entry in the emitted document.
///
/// Fields must match the serde renames of `mindfile::NestedSource` exactly so
/// `toml::from_str::<MindToml>` accepts the output (DUMP-7, DSC-30).
///
/// DUMP-1 / DUMP-4 / DSC-65: the pin is emitted as `pin-ref = <commit>` for
/// every source with a recorded commit, regardless of the source's pin kind.
/// This is the authoritative per-entry pin (DSC-65) that re-melding the output
/// will apply unconditionally. A source with no recorded commit (e.g. a
/// never-synced linked local source) emits no pin field.
#[derive(Serialize)]
struct DumpEntry {
    source: String,

    #[serde(rename = "namespace", skip_serializing_if = "Option::is_none")]
    namespace: Option<String>,

    #[serde(skip_serializing_if = "Option::is_none")]
    roots: Option<Vec<String>>,

    /// Flat skill layout (DUMP-10): emitted as `flat-skills = true` when flat
    /// discovery is in effect for the source (the consumer override STO-44 or the
    /// source's own `[source].flat-skills`, DSC-74). Absent otherwise. Mirrors how
    /// `roots` (DUMP-4) is emitted.
    #[serde(rename = "flat-skills", skip_serializing_if = "Option::is_none")]
    flat_skills: Option<bool>,

    /// Pin: emit the recorded commit sha as `pin-ref` (DUMP-1, DUMP-4, DSC-65).
    /// Absent when no commit has been recorded for this source.
    #[serde(rename = "pin-ref", skip_serializing_if = "Option::is_none")]
    pin_ref: Option<String>,

    // Exactly one of these two is emitted per entry (never both, never neither).
    // When install_items is Some the install bool is absent; when install_items
    // is None the bool is emitted. The filtering logic guarantees mutual
    // exclusion.
    #[serde(skip_serializing_if = "Option::is_none")]
    install: Option<bool>,

    #[serde(rename = "install-items", skip_serializing_if = "Option::is_none")]
    install_items: Option<Vec<String>>,
}

// ---------------------------------------------------------------------------
// Public entry point
// ---------------------------------------------------------------------------

/// Run `mind dump`.
///
/// - `paths` - resolved paths for this invocation
/// - `output` - write to this file instead of stdout when `Some`
/// - `whole_sources` - when true, emit `install = true` for every source
///   regardless of what is actually installed (DUMP-3)
pub fn run(paths: &Paths, output: Option<PathBuf>, whole_sources: bool) -> Result<()> {
    // spec: DUMP-1 DUMP-2 DUMP-3 DUMP-4 DUMP-5 DUMP-6 DUMP-7 DUMP-8 DUMP-9

    // DUMP-9: dump always writes TOML; --json has no effect on the output format.
    // Print a note to stderr so the caller is not confused by the TOML output.
    if crate::render::ctx().json {
        eprintln!("note: --json does not apply to dump; output is always TOML");
    }

    let registry = Registry::load(paths)?;
    let manifest = Manifest::load(paths)?;

    // spec: DUMP-8 — with no melded sources, emit a valid super-source whose
    // [discover].sources is empty, and exit 0.
    let entries = build_entries(paths, &registry, &manifest, whole_sources)?;

    let doc = DumpDoc {
        source: DumpSource {
            description: "Generated by `mind dump`. Meld this file to reproduce the recorded \
                          source set and install selection."
                .to_string(),
        },
        discover: DumpDiscover { sources: entries },
    };

    let text = toml::to_string(&doc).map_err(|e| MindError::TomlWrite {
        path: output.clone().unwrap_or_else(|| PathBuf::from("<stdout>")),
        source: e,
    })?;

    match output {
        None => {
            // spec: DUMP-1 — stdout by default
            let stdout = std::io::stdout();
            let mut out = stdout.lock();
            out.write_all(text.as_bytes())
                .and_then(|_| out.flush())
                .map_err(|e| MindError::io("<stdout>", e))
        }
        Some(path) => {
            // spec: DUMP-1 — --output <path>
            std::fs::write(&path, &text).map_err(|e| MindError::io(&path, e))
        }
    }
}

// ---------------------------------------------------------------------------
// Core logic
// ---------------------------------------------------------------------------

/// Build the `[[discover.sources]]` entry list.
fn build_entries(
    paths: &Paths,
    registry: &Registry,
    manifest: &Manifest,
    whole_sources: bool,
) -> Result<Vec<DumpEntry>> {
    let mut entries = Vec::with_capacity(registry.sources.len());

    for source in &registry.sources {
        let entry = build_entry(paths, source, manifest, whole_sources)?;
        entries.push(entry);
    }

    Ok(entries)
}

/// Build one `[[discover.sources]]` entry for a single melded source.
fn build_entry(
    paths: &Paths,
    source: &Source,
    manifest: &Manifest,
    whole_sources: bool,
) -> Result<DumpEntry> {
    // spec: DUMP-1 — use source URL for remote sources; use URL (path) for local.
    // For local sources `source.url` holds the filesystem path (see parse_spec).
    let source_spec = source.url.clone();

    // spec: DUMP-4 — effective prefix: consumer alias wins over the source's
    // own [source].prefix (the same precedence as catalog::scan_source_at).
    let effective_alias = effective_prefix(paths, source);

    // spec: DUMP-4 — scan roots recorded at meld time (STO-17).
    let roots = source.roots.clone();

    // spec: DUMP-10 — emit flat-skills from the STO-44 consumer override only,
    // exactly mirroring how `roots` (DUMP-4) emits `source.roots` and NOT the
    // source's own `[source].flat-skills`. A source's own flat-skills is re-read
    // from its mind.toml when the output is re-melded, so emitting it here would
    // be redundant and would trip the DSC-60 "ignored" gate on re-meld.
    let flat_skills = source.flat_skills.then_some(true);

    // spec: DUMP-1 / DUMP-4 / DSC-65 — emit the recorded commit sha as `pin-ref`
    // for every source that has one. This is the authoritative per-entry pin
    // (DSC-65): a re-meld of the output will apply it unconditionally, pinning
    // each source to the exact revision recorded at dump time. A source with no
    // recorded commit (e.g. a never-synced linked local source) emits no pin.
    let pin_ref = source.commit.clone();

    // spec: DUMP-2 / DUMP-3 — item filtering.
    let (install, install_items) = if whole_sources {
        // spec: DUMP-3 — --whole-sources: always install = true.
        (Some(true), None)
    } else {
        compute_install_directive(paths, source, manifest)?
    };

    Ok(DumpEntry {
        source: source_spec,
        namespace: effective_alias,
        roots,
        flat_skills,
        pin_ref,
        install,
        install_items,
    })
}

/// Compute the effective namespace prefix for a source, mirroring the
/// precedence used in `catalog::scan_source_at` (DUMP-4).
///
/// Returns `None` when neither the consumer alias nor the source's own
/// `[source].prefix` is set (or both are empty strings).
fn effective_prefix(paths: &Paths, source: &Source) -> Option<String> {
    // Consumer alias wins.
    if let Some(alias) = &source.alias {
        if !alias.is_empty() {
            return Some(alias.clone());
        }
        // An explicit empty alias suppresses the source's own prefix.
        return None;
    }
    // Fall back to the source's own [source].prefix from its mind.toml.
    let clone_root = source.clone_dir(paths);
    if let Ok(Some(mt)) = MindToml::load(&clone_root)
        && let Some(prefix) = mt.source.prefix
        && !prefix.is_empty()
    {
        return Some(prefix);
    }
    None
}

/// Compute the install directive for one source (DUMP-2).
///
/// Returns `(install, install_items)` where exactly one is `Some`.
///
/// - All offered items installed -> `(Some(true), None)`
/// - No offered items installed -> `(Some(false), None)`
/// - Proper subset installed -> `(None, Some(sorted_bare_refs))`
///
/// The `install_items = []` form is NEVER emitted; that case becomes
/// `install = false` (DUMP-2).
fn compute_install_directive(
    paths: &Paths,
    source: &Source,
    manifest: &Manifest,
) -> Result<(Option<bool>, Option<Vec<String>>)> {
    // Scan the source to find its offered items (bare names).
    let mut offered_items = Vec::new();
    catalog::scan_source(paths, source, &mut offered_items)?;

    // Build the set of offered bare "kind:name" refs from the catalog.
    let offered: BTreeSet<String> = offered_items
        .iter()
        .map(|item| format!("{}:{}", item.kind.as_str(), item.name))
        .collect();

    // Build the set of installed bare "kind:name" refs from the manifest that
    // belong to this source.
    // DUMP-5: items are listed by bare kind:name (catalog/source truth).
    // DUMP-6: items installed as within-source dependencies are included.
    let installed_for_source: HashMap<String, ()> = manifest
        .items
        .values()
        .filter(|item| item.source == source.name)
        .map(|item| {
            let bare_ref = format!("{}:{}", item.kind.as_str(), item.bare_name);
            (bare_ref, ())
        })
        .collect();

    // Intersect: only count installed items that the source actually offers
    // (an item installed from a previous catalog state but no longer offered
    // is excluded from the intersection).
    let installed_and_offered: BTreeSet<String> = offered
        .iter()
        .filter(|ref_| installed_for_source.contains_key(*ref_))
        .cloned()
        .collect();

    if offered.is_empty() {
        // Source offers nothing; emit install = false.
        return Ok((Some(false), None));
    }

    if installed_and_offered.is_empty() {
        // spec: DUMP-2 — none installed -> install = false.
        // Never emit install_items = [].
        return Ok((Some(false), None));
    }

    if installed_and_offered == offered {
        // spec: DUMP-2 — all offered items installed -> install = true.
        return Ok((Some(true), None));
    }

    // spec: DUMP-2 — proper subset -> install_items listing exactly those items.
    // Items are sorted deterministically (BTreeSet is already sorted).
    let items: Vec<String> = installed_and_offered.into_iter().collect();
    Ok((None, Some(items)))
}

// ---------------------------------------------------------------------------
// Unit tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::ItemKind;
    use crate::manifest::InstalledItem;
    use crate::source::Source;

    // Helper: build a minimal Source struct for testing.
    fn make_source(name: &str, url: &str, commit: Option<&str>) -> Source {
        Source {
            name: name.to_string(),
            url: url.to_string(),
            host: "local".to_string(),
            owner: "test".to_string(),
            repo: name.split('/').next_back().unwrap_or(name).to_string(),
            commit: commit.map(str::to_string),
            description: None,
            alias: None,
            pin: crate::source::Pin::default(),
            roots: None,
            flat_skills: false,
            origin: None,
            plugin_version: None,
            install_hooks: vec![],
            install_hook: None,
            install_hook_commit: None,
        }
    }

    // Helper: build a minimal InstalledItem.
    fn make_installed(kind: ItemKind, name: &str, bare: &str, source: &str) -> InstalledItem {
        InstalledItem {
            kind,
            name: name.to_string(),
            bare_name: bare.to_string(),
            source: source.to_string(),
            commit: "abc".to_string(),
            hash: "def".to_string(),
            store: "store/path".to_string(),
            links: vec![],
            description: None,
        }
    }

    // ----- Filtering logic (DUMP-2) -----

    #[test]
    fn filtering_all_installed_yields_install_true() {
        // spec: DUMP-2 — every offered item installed -> install = true.
        // (compute_install_directive requires disk access; we test the
        // all-installed branch via the emitted-TOML round-trip below.)
        //
        // Directly test the TOML emitter shape with a hand-crafted entry.
        let entry = DumpEntry {
            source: "/some/path".into(),
            namespace: None,
            roots: None,
            flat_skills: None,
            pin_ref: None,
            install: Some(true),
            install_items: None,
        };
        let doc = DumpDoc {
            source: DumpSource {
                description: "test".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry],
            },
        };
        let text = toml::to_string(&doc).unwrap();
        assert!(text.contains("install = true"), "must emit install = true");
        assert!(
            !text.contains("install-items"),
            "must NOT emit install-items when install = true"
        );
        // spec: DUMP-7 — parses back as a valid MindToml (DSC-3/DSC-30).
        let back: MindToml = toml::from_str(&text)
            .unwrap_or_else(|e| panic!("install=true output must parse as MindToml: {e}"));
        let ns = &back.discover.unwrap().sources[0];
        assert!(ns.install);
        assert!(ns.install_items.is_none());
    }

    #[test]
    fn filtering_none_installed_yields_install_false() {
        // spec: DUMP-2 — none installed -> install = false; never emit [].
        let entry = DumpEntry {
            source: "/some/path".into(),
            namespace: None,
            roots: None,
            flat_skills: None,
            pin_ref: None,
            install: Some(false),
            install_items: None,
        };
        let doc = DumpDoc {
            source: DumpSource {
                description: "test".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry],
            },
        };
        let text = toml::to_string(&doc).unwrap();
        assert!(
            text.contains("install = false"),
            "must emit install = false"
        );
        assert!(
            !text.contains("install-items"),
            "must NOT emit install-items when none installed"
        );
        // spec: DUMP-7
        let back: MindToml = toml::from_str(&text)
            .unwrap_or_else(|e| panic!("install=false output must parse as MindToml: {e}"));
        let ns = &back.discover.unwrap().sources[0];
        assert!(!ns.install);
        assert!(ns.install_items.is_none());
    }

    #[test]
    fn filtering_proper_subset_yields_install_items() {
        // spec: DUMP-2 DUMP-5 — proper subset -> install_items listing bare kind:name.
        // Never emit install_items = [].
        let items = vec!["agent:dev".to_string(), "skill:review".to_string()];
        let entry = DumpEntry {
            source: "/some/path".into(),
            namespace: None,
            roots: None,
            flat_skills: None,
            pin_ref: None,
            install: None,
            install_items: Some(items.clone()),
        };
        let doc = DumpDoc {
            source: DumpSource {
                description: "test".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry],
            },
        };
        let text = toml::to_string(&doc).unwrap();
        assert!(
            text.contains("install-items"),
            "must emit install-items for subset"
        );
        assert!(
            !text.contains("install = true"),
            "must NOT emit install = true when emitting install-items"
        );
        // spec: DUMP-7
        let back: MindToml = toml::from_str(&text)
            .unwrap_or_else(|e| panic!("install_items output must parse as MindToml: {e}"));
        let ns = &back.discover.unwrap().sources[0];
        assert!(
            !ns.install,
            "install bool must be false/absent for subset form"
        );
        let got = ns
            .install_items
            .as_deref()
            .expect("install_items must be present");
        assert_eq!(got, &["agent:dev", "skill:review"][..]);
    }

    #[test]
    fn empty_install_items_is_never_emitted() {
        // spec: DUMP-2 — install_items = [] is NEVER emitted; that case is
        // install = false.
        let entry = DumpEntry {
            source: "/some/path".into(),
            namespace: None,
            roots: None,
            flat_skills: None,
            pin_ref: None,
            install: Some(false),
            install_items: None, // None, not Some([])
        };
        let doc = DumpDoc {
            source: DumpSource {
                description: "test".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry],
            },
        };
        let text = toml::to_string(&doc).unwrap();
        assert!(
            !text.contains("install-items"),
            "install_items=[] must never appear; got: {text}"
        );
        assert!(text.contains("install = false"));
    }

    #[test]
    fn emitted_toml_parses_as_valid_mindtoml() {
        // spec: DUMP-7 — the emitted file is a valid super-source (parses under
        // DSC-3 and DSC-30 deny_unknown_fields) and carries [source].description.
        let doc = DumpDoc {
            source: DumpSource {
                description: "Generated by `mind dump`. Meld this file to reproduce the \
                              recorded source set and install selection."
                    .to_string(),
            },
            discover: DumpDiscover {
                sources: vec![
                    DumpEntry {
                        source: "/path/to/repo".into(),
                        namespace: Some("pfx".into()),
                        roots: Some(vec!["packages".into()]),
                        flat_skills: Some(true),
                        pin_ref: Some("deadbeefdeadbeef1234".into()),
                        install: Some(true),
                        install_items: None,
                    },
                    DumpEntry {
                        source: "https://github.com/owner/repo".into(),
                        namespace: None,
                        roots: None,
                        flat_skills: None,
                        pin_ref: None,
                        install: None,
                        install_items: Some(vec!["skill:review".into(), "agent:dev".into()]),
                    },
                ],
            },
        };
        let text =
            toml::to_string(&doc).unwrap_or_else(|e| panic!("serialization must not fail: {e}"));
        // Must parse back cleanly without unknown-field errors.
        let back: MindToml = toml::from_str(&text)
            .unwrap_or_else(|e| panic!("emitted TOML must parse as MindToml: {e}\nTOML:\n{text}"));
        // [source].description is present.
        assert!(
            back.source.description.is_some(),
            "emitted TOML must carry [source].description"
        );
        // Only [discover].sources; no items of its own.
        assert!(back.items.is_empty(), "emitted TOML must have no [[items]]");
        let disc = back.discover.expect("must have [discover]");
        assert_eq!(disc.sources.len(), 2);
        // First entry: install = true, pin-ref (commit pin) present, alias present.
        let e0 = &disc.sources[0];
        assert!(e0.install, "first entry: install must be true");
        assert_eq!(e0.namespace.as_deref(), Some("pfx"));
        assert_eq!(e0.roots.as_deref(), Some(&["packages".to_string()][..]));
        // spec: DUMP-10 — flat-skills round-trips: emitted as `flat-skills = true`
        // and parses back as NestedSource.flat_skills on the first entry, while the
        // second entry (no flat layout) parses back false.
        assert!(
            text.contains("flat-skills = true"),
            "must emit flat-skills = true"
        );
        assert!(
            e0.flat_skills,
            "first entry: flat_skills must parse back true"
        );
        assert!(
            e0.pin_ref.is_some(),
            "pin-ref must be present for pinned entry"
        );
        // Second entry: install_items present, no install = true.
        let e1 = &disc.sources[1];
        assert!(!e1.install, "second entry: install must be false");
        assert!(
            !e1.flat_skills,
            "second entry: flat_skills must parse back false (no key emitted)"
        );
        let items = e1
            .install_items
            .as_deref()
            .expect("install_items must be present");
        assert_eq!(items, &["skill:review", "agent:dev"][..]);
    }

    #[test]
    fn spec_string_round_trips_for_local_path() {
        // Verify that the spec string we emit for a local source round-trips
        // through parse_spec back to the same URL.
        // spec: DUMP-1 DUMP-4
        let source = make_source("local/dev/agents", "/home/dev/agents", Some("abc123"));
        // The emitted spec is source.url for local sources.
        let spec = source.url.clone();
        let parsed = crate::source::parse_spec(&spec)
            .unwrap_or_else(|e| panic!("local spec must round-trip: {e}"));
        assert_eq!(
            parsed.url, source.url,
            "local path spec must round-trip through parse_spec"
        );
    }

    #[test]
    fn spec_string_round_trips_for_https_url() {
        // spec: DUMP-1 DUMP-4
        let url = "https://github.com/owner/repo";
        let source = make_source("github.com/owner/repo", url, None);
        let spec = source.url.clone();
        let parsed = crate::source::parse_spec(&spec)
            .unwrap_or_else(|e| panic!("https spec must round-trip: {e}"));
        assert_eq!(parsed.url, url);
    }

    #[test]
    fn pin_ref_emitted_when_commit_recorded_regardless_of_pin_kind() {
        // spec: DUMP-1 DUMP-4 DSC-65 — the pin is always emitted as `pin-ref`
        // (the recorded commit sha) when the source has a recorded commit,
        // regardless of the source's pin kind (FollowBranch, Tag, Ref, or
        // DefaultBranch). A source with no recorded commit emits no pin.
        let entry_with_commit = DumpEntry {
            source: "/a/b".into(),
            namespace: None,
            roots: None,
            flat_skills: None,
            pin_ref: Some("deadbeefdeadbeef".into()),
            install: Some(true),
            install_items: None,
        };
        let entry_no_commit = DumpEntry {
            source: "/a/b".into(),
            namespace: None,
            roots: None,
            flat_skills: None,
            pin_ref: None,
            install: Some(false),
            install_items: None,
        };

        let text_with = toml::to_string(&DumpDoc {
            source: DumpSource {
                description: "t".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry_with_commit],
            },
        })
        .unwrap();
        let text_without = toml::to_string(&DumpDoc {
            source: DumpSource {
                description: "t".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry_no_commit],
            },
        })
        .unwrap();

        assert!(
            text_with.contains("pin-ref"),
            "must emit pin-ref when a commit is recorded: {text_with}"
        );
        assert!(
            text_with.contains("deadbeefdeadbeef"),
            "must emit the recorded commit sha as pin-ref: {text_with}"
        );
        assert!(
            !text_with.contains("follow-branch"),
            "must NOT emit follow-branch (replaced by pin-ref): {text_with}"
        );
        assert!(
            !text_without.contains("pin-ref"),
            "must NOT emit pin-ref when no commit is recorded: {text_without}"
        );
        // Both must parse as valid MindToml (DUMP-7): NestedSource now accepts pin-ref.
        let _: MindToml = toml::from_str(&text_with)
            .unwrap_or_else(|e| panic!("pinned entry must parse: {e}\n{text_with}"));
        let _: MindToml = toml::from_str(&text_without)
            .unwrap_or_else(|e| panic!("unpinned entry must parse: {e}\n{text_without}"));
    }

    #[test]
    fn install_items_sorted_deterministically() {
        // spec: DUMP-5 — install_items are sorted (kind then name) so output is stable.
        let mut items = [
            "skill:review".to_string(),
            "agent:dev".to_string(),
            "rule:style".to_string(),
        ];
        items.sort();
        assert_eq!(items[0], "agent:dev");
        assert_eq!(items[1], "rule:style");
        assert_eq!(items[2], "skill:review");
    }

    #[test]
    fn emitted_toml_has_no_items_of_its_own() {
        // spec: DUMP-7 — the emitted file declares only [discover].sources;
        // no [[items]] or item globs of its own.
        let doc = DumpDoc {
            source: DumpSource {
                description: "Generated by `mind dump`. test".into(),
            },
            discover: DumpDiscover { sources: vec![] },
        };
        let text = toml::to_string(&doc).unwrap();
        let back: MindToml =
            toml::from_str(&text).unwrap_or_else(|e| panic!("empty doc must parse: {e}"));
        assert!(back.items.is_empty(), "must have no [[items]]");
        assert!(
            !back.is_authoritative(),
            "empty discover.sources must not be authoritative (only sources, no item globs)"
        );
    }

    #[test]
    fn whole_sources_entry_has_install_true() {
        // spec: DUMP-3 — --whole-sources always emits install = true.
        let entry = DumpEntry {
            source: "/a/b".into(),
            namespace: None,
            roots: None,
            flat_skills: None,
            pin_ref: None,
            install: Some(true),
            install_items: None,
        };
        let text = toml::to_string(&DumpDoc {
            source: DumpSource {
                description: "t".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry],
            },
        })
        .unwrap();
        assert!(text.contains("install = true"));
        let back: MindToml = toml::from_str(&text).unwrap();
        assert!(back.discover.unwrap().sources[0].install);
    }

    #[test]
    fn dependency_item_treated_like_any_installed_item() {
        // spec: DUMP-6 — an item installed only as a within-source dependency
        // is part of the installed set just like any other manifest entry.
        // Here we verify that bare_name is what goes into install_items, not
        // the effective name (which may be prefixed).
        let item = make_installed(ItemKind::Skill, "pfx:review", "review", "local/dev/agents");
        // The bare_name is "review", so install_items should list "skill:review".
        let bare_ref = format!("{}:{}", item.kind.as_str(), item.bare_name);
        assert_eq!(bare_ref, "skill:review");
    }

    #[test]
    fn namespace_field_emitted_not_as_key() {
        // spec: DSC-78 — dump emits `namespace = "pfx"` (canonical key), not the
        // legacy `as = "pfx"`, and the value round-trips through NestedSource::namespace.
        let entry = DumpEntry {
            source: "/a/b".into(),
            namespace: Some("pfx".into()),
            roots: None,
            flat_skills: None,
            pin_ref: None,
            install: Some(true),
            install_items: None,
        };
        let doc = DumpDoc {
            source: DumpSource {
                description: "t".into(),
            },
            discover: DumpDiscover {
                sources: vec![entry],
            },
        };
        let text = toml::to_string(&doc).unwrap();
        assert!(
            text.contains("namespace = \"pfx\""),
            "must emit `namespace = \"pfx\"` (canonical key): {text}"
        );
        assert!(
            !text.contains("as = "),
            "must NOT emit the legacy `as = ` key: {text}"
        );
        // Round-trip: the emitted `namespace` key populates NestedSource::namespace,
        // not ::alias.
        let back: MindToml = toml::from_str(&text)
            .unwrap_or_else(|e| panic!("namespace output must parse as MindToml: {e}\n{text}"));
        let ns = &back.discover.unwrap().sources[0];
        assert_eq!(
            ns.namespace.as_deref(),
            Some("pfx"),
            "emitted namespace key must populate NestedSource::namespace"
        );
        assert!(
            ns.alias.is_none(),
            "emitted namespace key must NOT populate NestedSource::alias"
        );
    }

    #[test]
    fn dump_8_empty_registry_produces_valid_super_source() {
        // spec: DUMP-8 — with no melded sources the document is valid with
        // [discover].sources = [].
        let doc = DumpDoc {
            source: DumpSource {
                description: "Generated by `mind dump`. Meld this file to reproduce the \
                              recorded source set and install selection."
                    .to_string(),
            },
            discover: DumpDiscover { sources: vec![] },
        };
        let text = toml::to_string(&doc).unwrap();
        let back: MindToml =
            toml::from_str(&text).unwrap_or_else(|e| panic!("empty-registry doc must parse: {e}"));
        let disc = back.discover.expect("must have [discover]");
        assert!(disc.sources.is_empty(), "sources must be empty");
    }
}