mind-cli 0.30.1

//! The `mind` command-line surface.
//!
//! Verbs use a knowledge metaphor:
//!   meld   -> connect to a source repo
//!   learn  -> install an item
//!   forget -> remove an item
//!   sync   -> refresh source catalogs
//!   upgrade -> upgrade installed items
//!   evolve -> upgrade the mind binary itself
//!   recall -> show what's installed
//!   probe  -> find available items
//!   introspect -> diagnose drift

use clap::{Parser, Subcommand, ValueEnum};

/// The lifecycle event for `mind hooks run --event`.
// spec: CLI-195
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum HookEventArg {
    /// Run install hooks (default). Valid for source and item targets.
    Install,
    /// Run update hooks: what runs at `upgrade` in place of the install hooks.
    /// Valid for source and item targets.
    /// Not `mind update`, which is the alias of `sync` and runs no hooks.
    Update,
    /// Run uninstall hooks. Valid for source and item targets.
    Uninstall,
    /// Re-install the item through the transactional build path (stage, build,
    /// swap). Valid for item targets only; a source has no build hook.
    Build,
}

use crate::error::ItemKind;

/// An item kind as accepted on the command line
/// (`--kind skill|agent|rule|command|workflow|tool|resource`).
#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum KindArg {
    Skill,
    Agent,
    Rule,
    Command,
    // spec: WF-6 -- a plain comment, not a doc comment: clap renders a doc
    // comment on a value variant as its help text.
    Workflow,
    Tool,
    Resource,
}

impl KindArg {
    pub fn to_kind(self) -> ItemKind {
        match self {
            KindArg::Skill => ItemKind::Skill,
            KindArg::Agent => ItemKind::Agent,
            KindArg::Rule => ItemKind::Rule,
            KindArg::Command => ItemKind::Command,
            KindArg::Workflow => ItemKind::Workflow,
            KindArg::Tool => ItemKind::Tool,
            KindArg::Resource => ItemKind::Resource,
        }
    }
}

/// A file item link's kind, as declared on the command line (`meld`/`learn
/// --kind agent|rule|command`, CLI-239). Narrower than [`KindArg`] (no
/// `skill`/`tool`: a file link can never resolve to a directory kind, LNK-21)
/// so an invalid value is rejected by clap before any clone, with real shell
/// completions, rather than parsed by hand and only caught after a clone.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum LinkKindArg {
    Agent,
    Rule,
    Command,
}

impl LinkKindArg {
    pub fn to_kind(self) -> ItemKind {
        match self {
            LinkKindArg::Agent => ItemKind::Agent,
            LinkKindArg::Rule => ItemKind::Rule,
            LinkKindArg::Command => ItemKind::Command,
        }
    }
}

// spec: CLI-207 -- with no arguments, print full help to stdout and exit 0
// (clap's default for a required subcommand with no arguments is a usage
// error on stderr at exit 2). `command` stays a required (non-Option) enum:
// bare `mind` still does not launch the TUI (TUI-1/TUI-2), it prints help.
#[derive(Debug, Parser)]
#[command(
    name = "mind",
    version,
    about = "A manager for agent tooling: skills, agents, rules, commands, workflows, and tools.",
    propagate_version = true,
    arg_required_else_help = true
)]
pub struct Cli {
    /// Emit machine-readable JSON instead of formatted text. `dump`,
    /// `completions`, `man`, and `init-source` emit their own artifact
    /// (a TOML/script/roff/manifest document) regardless of this flag.
    #[arg(long, global = true, help_heading = "Global options")]
    pub json: bool,

    /// Skip confirmation prompts (assume yes).
    #[arg(short = 'y', long, global = true, help_heading = "Global options")]
    pub yes: bool,

    /// Force plain ASCII output (no color, no Unicode glyphs).
    #[arg(long, global = true, help_heading = "Global options")]
    pub ascii: bool,

    /// Emit extra advisory output (e.g. unguarded-reference warnings on meld).
    #[arg(short = 'v', long, global = true, help_heading = "Global options")]
    pub verbose: bool,

    /// Ceiling on every metadata file `mind` reads from a source: a `mind.toml`,
    /// an item's frontmatter, a plugin or marketplace manifest, a workflow's
    /// `meta` (default 8MiB).
    ///
    /// Takes a byte count (`16777216`), a suffixed size (`32MiB`, `512KiB`,
    /// `16MB`), or `unlimited` or `none` for no ceiling. A zero value (`0`,
    /// `0B`, `0MiB`) also turns the cap off, with a warning; prefer
    /// `unlimited` to do that on purpose. Raise it for a source with a
    /// legitimately large metadata file; lower it to bound how much a source
    /// you do not trust can make `mind` allocate while scanning it. The flag
    /// applies to this invocation only; set the `max-metadata-size` config key
    /// or `MIND_MAX_METADATA_SIZE` to make a value last (this flag outranks
    /// both).
    // spec: CLI-240 DSC-110
    #[arg(
        long,
        global = true,
        value_name = "SIZE",
        help_heading = "Global options"
    )]
    pub max_metadata_size: Option<String>,

    #[command(subcommand)]
    pub command: Command,
}

#[derive(Debug, Subcommand)]
pub enum Command {
    /// Meld with a source repo and install its items (prompts to install; use `--register-only` to skip).
    // spec: CLI-173
    #[command(
        visible_alias = "add",
        after_help = "\
EXAMPLES:
    mind meld owner/repo
    mind meld https://github.com/owner/repo --namespace acme
    mind meld owner/repo --learn review --yes
    mind meld . --register-only"
    )]
    Meld(MeldArgs),

    /// Scaffold a `mind.toml` and report the references among a source's items.
    ///
    /// For source maintainers: discovers the items the repo offers, reports which
    /// items reference which siblings, and creates a starter `mind.toml` if none
    /// exists. With `--template`, also rewrites bare sibling references into
    /// `{{ns:}}` tokens so the source stays resolvable under a prefix.
    InitSource {
        /// The source repo directory (default the current directory).
        path: Option<String>,

        /// Rewrite bare sibling references into `{{ns:name}}` tokens. This edits
        /// the repo's item files; it is heuristic, so review the result. Like
        /// `review --fix`, it leaves `.js` files (workflows) alone.
        #[arg(long)]
        template: bool,

        /// Generate `.claude-plugin/marketplace.json` for Claude plugin
        /// compatibility. Skipped if the file already exists.
        #[arg(long)]
        marketplace: bool,

        /// Set `flat-skills = true` in `[source]` in `mind.toml` and use flat
        /// skill layout for discovery. With `--marketplace`, populates the
        /// `skills` array in the generated manifest.
        #[arg(long)]
        flat_skills: bool,

        /// Override the plugin name / `[source].prefix` written to `mind.toml`
        /// and the marketplace manifest `name` field.
        // spec: CLI-163 - short moved to -N (uppercase).
        #[arg(short = 'N', long)]
        namespace: Option<String>,
    },

    /// Unmeld a source, uninstalling every item the source installed.
    ///
    /// Unmelds a source and uninstalls every item the source installed; use
    /// `--keep-items` to keep them.
    ///
    /// `<name>` is a REF: it must resolve to exactly one source. It may be the
    /// full `host/owner/repo` or an unambiguous trailing suffix (e.g. `repo`
    /// or `owner/repo`); a non-glob name matching more than one source errors
    /// instead of guessing. A glob (`*`, `?`, `[`) removes every matching
    /// source. Contrast `sync`'s `[source]`, which is a FILTER: it may match
    /// several sources even without a glob, and every match is acted on.
    // spec: CLI-174 - long_about leads with the uninstall default.
    // spec: CLI-172 - the former `detach` alias is removed.
    // spec: CLI-230 - `remove`/`rm` visible aliases, for symmetry with learn's
    // install/uninstall aliases.
    #[command(visible_aliases = ["remove", "rm"], after_help = "\
EXAMPLES:
    mind unmeld github.com/acme/agents
    mind unmeld acme/agents --keep-items
    mind unmeld '*agents' --yes")]
    Unmeld {
        /// The source ref (see `mind recall --sources`): must resolve to
        /// exactly one source, unless it is a glob.
        name: String,

        /// Remove only the source, leaving its installed items in place (the
        /// opt-out from the default item removal, mirroring `meld --register-only`).
        // spec: CLI-166 - canonical name; --unlink-only is a hidden deprecated alias.
        #[arg(long, alias = "unlink-only")]
        keep_items: bool,

        /// Supply or override the source's uninstall hook: a shell command run
        /// in the clone before the source is removed. Replaces the source's
        /// declared uninstall hook(s); the override is shown loudly in the prompt.
        #[arg(long, value_name = "CMD")]
        uninstall_hook: Option<String>,

        /// Run uninstall hooks without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the hook and prints a note.
        /// `--dangerously-skip-install-hook-check` is a deprecated alias kept for
        /// backwards compatibility.
        // spec: CLI-227 - renamed from --dangerously-skip-install-hook-check,
        // which gated an UNINSTALL hook despite its name; old spelling is a
        // hidden alias.
        #[arg(
            long = "dangerously-skip-hook-check",
            alias = "dangerously-skip-install-hook-check"
        )]
        dangerously_skip_install_hook_check: bool,
    },

    /// Install items into every configured agent home (default ~/.claude).
    ///
    /// The item ref may be exact, or a glob to install many: `'*'` for everything,
    /// `'skill:*'` for all skills, `'owner/repo#*'` for all of one source.
    ///
    /// When selecting a subset of a source's items, `learn` also installs the
    /// intra-source `{{ns:}}` dependencies those items reference (the closure),
    /// printing a dependency tree and prompting before installing; `--dry-run`
    /// previews the closure without installing anything and `--yes` skips the prompt.
    // spec: CLI-172
    #[command(
        visible_alias = "install",
        after_help = "\
EXAMPLES:
    mind learn review
    mind learn 'skill:*'
    mind learn owner/repo --all"
    )]
    Learn {
        /// Item ref or glob: `name`, `skill:name`, `owner/repo#name`, `'review*'`, `'*'`.
        /// Also accepts a deep tree/blob URL to one item
        /// (`https://host/owner/repo/tree/<ref>/<path>` for a skill,
        /// `.../blob/<ref>/<file>.md` for one agent, rule, or command): the repo
        /// registers as a single-item source and the item installs in one step.
        item: String,

        /// Install every item of the source named by the ref. Shorthand for the
        /// `<source>#*` selector; rejected if the ref already has a `#` selector.
        #[arg(long, conflicts_with_all = ["profiles", "all_profiles"])]
        all: bool,

        /// Install this profile of the source named by the ref (an
        /// already-melded source, selected as for `--all`) and add it to the
        /// source's enabled profiles (repeatable; a comma-separated list is
        /// accepted). Only the named profiles are installed; `default` is not
        /// added. The dependency-closure prompt and `--dry-run` apply as for
        /// any `learn`.
        // spec: PROF-17
        #[arg(long = "profile", value_name = "NAME")]
        profiles: Vec<String>,

        /// Accepted for symmetry with `meld`; `learn` never enables the
        /// `default` profile on its own, so it changes nothing here.
        // spec: PROF-17
        #[arg(long)]
        no_default_profile: bool,

        /// Install every profile the source named by the ref declares, and add
        /// them all to its enabled profiles. Unlike `--all`, an item in no
        /// profile is not installed.
        // spec: PROF-17
        #[arg(long)]
        all_profiles: bool,

        /// For a deep tree/blob URL, freeze the link's branch ref to its current
        /// commit when registering the single-item source, so the instance is an
        /// immutable snapshot instead of tracking the branch. This is a bare flag
        /// that takes NO value (unlike `meld --pin <REF>`, which takes one): the
        /// ref to freeze comes from the URL itself, so there is nothing to
        /// supply. Ignored (with a note) for a non-URL item ref, which names an
        /// already-melded source.
        // spec: CLI-200 - learn's --pin is intentionally bare (arity 0), NOT
        // symmetric with meld's `--pin <value>`: learn resolves items from an
        // already-melded source or a URL whose ref is in the URL, so there is no
        // ref value for the flag to accept.
        #[arg(long)]
        pin: bool,

        /// Declare what kind of item a `blob` item link's file is: `agent`,
        /// `rule`, or `command`. Same rule as `meld --kind`; item links only.
        // spec: CLI-239, LNK-21
        #[arg(long)]
        kind: Option<LinkKindArg>,

        /// Show what would be installed without installing anything.
        #[arg(short = 'n', long = "dry-run")]
        dry_run: bool,

        /// Overwrite a link target that already exists and is not managed by
        /// mind (a user's file/dir/foreign link). Without it, a conflict prompts
        /// on a TTY and otherwise refuses.
        #[arg(short = 'f', long)]
        force: bool,

        /// Run an item's install hook without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the hook and prints a note.
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run an item's build hook without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the build hook and prints a
        /// note, so the item's tooling is not built.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,

        /// Install the item(s) into ONLY the current project's lobe -- a
        /// registered lobe whose directory lives under the current working
        /// directory -- instead of fanning them into every configured agent home
        /// (the default). Errors when the current directory is not inside any
        /// registered project lobe.
        // spec: HARN-20 HARN-21
        #[arg(long)]
        local: bool,
    },

    /// Remove an installed item, or many via a glob.
    ///
    /// With `--unmanaged`, the removal is scoped to unmanaged lobe items only
    /// (the deliberate inverse of the default, which matches managed items only).
    /// With no `<item>` and `--unmanaged`, every unmanaged item across all
    /// configured lobes is removed.
    // spec: CLI-172 - added `uninstall` visible alias; `unlearn` kept.
    #[command(
        visible_aliases = ["unlearn", "uninstall"],
        after_help = "\
EXAMPLES:
    mind forget review
    mind forget 'skill:*' --yes
    mind forget --unmanaged
    mind forget owner/repo --profile full"
    )]
    Forget {
        /// The installed item ref or glob: `name`, `skill:name`, `'review*'`, `'*'`.
        /// With `--unmanaged`: the ref or glob scopes removal to unmanaged items only;
        /// omit to remove every unmanaged item across all lobes.
        /// With `--profile`: the melded source whose profile to disable.
        #[arg(required_unless_present = "unmanaged")]
        item: Option<String>,

        /// Disable this install profile of the source named by `<item>`: drop
        /// it from the source's enabled profiles and forget each item that was
        /// installed only for disabled profiles (an item you learned by name,
        /// or one another installed item depends on, is kept). `--profile
        /// default` disables the default profile.
        // spec: PROF-25
        #[arg(long, value_name = "NAME", conflicts_with = "unmanaged")]
        profile: Option<String>,

        /// Scope removal to unmanaged lobe items only (the deliberate inverse of the
        /// default, which matches managed items only). With no ref it removes every
        /// unmanaged item across all configured lobes.
        #[arg(long)]
        unmanaged: bool,

        /// Skip the dependents confirmation when removing a single item that
        /// other installed items depend on. Without this flag, `forget` warns
        /// and prompts; with it, removal proceeds immediately. The global
        /// `--yes` also skips this same prompt, but additionally skips the
        /// separate confirmation shown when a glob would remove more than one
        /// item; `--force` alone skips only the dependents prompt.
        // spec: DEP-60 CLI-42
        #[arg(short = 'f', long)]
        force: bool,

        /// Run an item's uninstall hook without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the hook and prints a note.
        /// `--dangerously-skip-install-hook-check` is a deprecated alias kept for
        /// backwards compatibility.
        // spec: CLI-227 - renamed from --dangerously-skip-install-hook-check,
        // which gated an UNINSTALL hook despite its name; old spelling is a
        // hidden alias.
        #[arg(
            long = "dangerously-skip-hook-check",
            alias = "dangerously-skip-install-hook-check"
        )]
        dangerously_skip_install_hook_check: bool,
    },

    /// Refresh melded source clones and catalogs (all, or only those matching
    /// `[source]`).
    ///
    /// `[source]` is a FILTER, not a ref (contrast `unmeld`'s source-name
    /// selection, which must resolve to exactly one source): it may match
    /// several sources with no ambiguity check, and every match is synced --
    /// that is intentional, since `sync` is a non-destructive refresh.
    // spec: CLI-172
    #[command(visible_alias = "update")]
    Sync {
        /// Only sync the source(s) matching this filter: an exact name, a
        /// trailing suffix like `repo` or `owner/repo` (every source it
        /// matches is synced -- unlike `unmeld`'s ref-style source
        /// selection, a filter is never ambiguous: more than one match is
        /// normal, not an error), or a glob. With no filter, every melded
        /// source is synced. A filter also skips the whole-set-only steps:
        /// managed-policy auto-meld provisioning and the nested-source
        /// re-walk run only on an unscoped `sync`.
        // spec: CLI-231 CLI-50
        source: Option<String>,

        /// After refreshing, run an `upgrade` pass (report + prompt) to apply
        /// upgrades, scoped to the source(s) the filter matched (every
        /// installed item when no filter is given). When the scope spans more
        /// than one source, a disclosure names every matched source before
        /// the install-hook re-run pass -- even when nothing is pending --
        /// since a filter's blast radius can exceed what the name alone
        /// suggests; unlike the `[Y/n]` confirmation itself, this disclosure
        /// is NOT suppressed by `--yes`. Deprecated: prefer `mind upgrade`,
        /// which now syncs first by default.
        // spec: CLI-169 CLI-232 CLI-233
        #[arg(long)]
        upgrade: bool,

        /// Run install- and update-hook re-runs without the safety prompt during
        /// the `--upgrade` pass (executes arbitrary code; only with `--upgrade`).
        #[arg(long, requires = "upgrade")]
        dangerously_skip_install_hook_check: bool,

        /// Run item build hooks without the safety prompt during the `--upgrade`
        /// pass. This executes arbitrary code from the source; only use it for a
        /// source you trust. Without this flag, a non-TTY run skips build hooks
        /// and prints a note. Only valid with `--upgrade`.
        #[arg(long, requires = "upgrade")]
        dangerously_skip_build_hook_check: bool,
    },

    /// Upgrade installed items to their latest source version.
    ///
    /// By default, syncs each involved source first (fetches from remote), then
    /// reports pending upgrades and prompts before applying. Use `--no-sync` to
    /// skip the fetch and compute deltas from the current clone.
    // spec: CLI-169
    Upgrade {
        /// Only upgrade this item; default is every installed item. This is a
        /// filter over installed items: a glob may match several, and a bare
        /// non-glob name multi-matches only across kinds (the manifest is
        /// keyed `kind:name`, e.g. `upgrade greet` hitting both `skill:greet`
        /// and `agent:greet`) -- item names themselves are never
        /// suffix-matched. An embedded `owner/repo#` source qualifier is a
        /// filter too, not a ref like `unmeld`'s source name: it is a
        /// trailing-suffix match with no ambiguity check, so it can match
        /// several sources at once, upgrading every matched source's items
        /// and re-running each one's install hook. When the resolved scope
        /// spans more than one source, a disclosure names every matched
        /// source before the install-hook re-run pass -- even when nothing is
        /// pending -- and this disclosure is NOT suppressed by `--yes`.
        item: Option<String>,

        /// Skip the automatic source sync before computing deltas. By default,
        /// `upgrade` fetches each involved source before checking for changes.
        // spec: CLI-169
        #[arg(long)]
        no_sync: bool,

        /// Re-run a source's install or update hook without the safety prompt
        /// when its commit advanced. This executes arbitrary code from the source; only
        /// use it for a source you trust. Without this flag, a non-TTY upgrade
        /// (CI, scripts) skips the hook re-run and just prints a note; pass this
        /// to run it unattended.
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run item build hooks without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY upgrade skips build hooks and prints a
        /// note, so the item's tooling is not rebuilt.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,
    },

    /// Upgrade the `mind` binary itself to the latest release (or a version
    /// pinned with `--to`). Distinct from `sync`'s `update` alias, which
    /// refreshes melded sources, not the binary.
    ///
    /// Downloads the release binary for this platform and replaces the running
    /// executable in place. `--check` reports whether a newer release is
    /// available and changes nothing. A prerelease running version (e.g. a
    /// `-dev` source build) is offered its own matching release even though
    /// the version numbers match. Without `--yes` it prompts before replacing.
    // Disable clap's auto `--version` flag on this subcommand so the explicit
    // `--to <VERSION>` argument below (pin a target release) owns the name
    // rather than shadowing the global `-V`/`--version` flag other verbs carry.
    // spec: CLI-172
    #[command(disable_version_flag = true, visible_alias = "self-update")]
    Evolve {
        /// Report whether a newer release is available, then exit without
        /// changing anything.
        #[arg(long)]
        check: bool,
        /// Upgrade to this exact version instead of the latest release. This
        /// is the only way to reach a prerelease (e.g. `--to 1.2.3-rc1`),
        /// since the latest-release lookup never surfaces one. A single
        /// leading `v` is accepted and stripped (`--to v1.2.3` works).
        /// `--version` is a deprecated alias kept for backwards compatibility.
        // spec: CLI-229 - renamed from --version, which shadowed the global
        // -V/--version flag other verbs carry; old spelling is a hidden alias.
        #[arg(long = "to", alias = "version", value_name = "VERSION")]
        version: Option<String>,
    },

    /// List installed items, or show one item's details.
    // spec: CLI-172 - added `list` visible alias; `status` kept.
    #[command(visible_aliases = ["status", "list"])]
    Recall {
        /// Show melded sources instead of installed items.
        #[arg(long)]
        sources: bool,

        /// Show details for a single installed item.
        item: Option<String>,

        /// Only list items of this kind (listing only).
        #[arg(long, value_enum)]
        kind: Option<KindArg>,

        /// Only list items from a source matching this filter: an exact
        /// name, a trailing suffix, or a glob (listing only; a multi-source
        /// match is normal, not an error).
        #[arg(long)]
        source: Option<String>,

        /// Render installed items as a dependency forest. With no item, shows
        /// the full forest; with an item ref, scopes to that item's subtree.
        // spec: DEP-61
        #[arg(long)]
        tree: bool,
    },

    /// Search melded catalogs for available items, or launch the interactive TUI.
    ///
    /// With a TTY and no opt-out, `probe` launches the interactive browser.
    /// Falls back to the catalog listing when `--no-tui`, `--json` (global), or
    /// stdout is not a TTY (piped or redirected). The query, `--kind`, and
    /// `--source` arguments seed the initial search/filter state in both modes.
    // spec: CLI-172
    #[command(visible_alias = "search")]
    Probe {
        /// Case-insensitive substring matched against item names and descriptions; empty lists everything.
        query: Option<String>,

        /// Only list items of this kind.
        #[arg(long, value_enum)]
        kind: Option<KindArg>,

        /// Only list items from a source matching this filter: an exact
        /// name, a trailing suffix, or a glob (a multi-source match is
        /// normal, not an error).
        #[arg(long)]
        source: Option<String>,

        /// Skip the interactive TUI and use the plain catalog listing.
        // spec: CLI-164, TUI-54 - long-only; former -n short removed (CLI-163 reserves -n for --dry-run).
        #[arg(long)]
        no_tui: bool,
    },

    /// Validate a source or a managed policy file (author-side, read-only).
    ///
    /// Source mode: `<target>` may be a local path, a melded-source selector
    /// (same forms as `unmeld`), or a repo spec (same forms as `meld`). A repo
    /// spec is shallow-cloned to a temp area and removed afterward. With no
    /// `<target>`, the current directory is validated.
    ///
    /// Policy mode: `--policy <path>` validates a managed policy TOML file at an
    /// explicit path without consulting the system policy path or env. Supplying
    /// both `<target>` and `--policy` is an error.
    Review {
        /// The source to validate: a local path, melded-source selector, or repo
        /// spec. Defaults to the current directory (`.`) when omitted.
        /// Cannot be used with `--policy`.
        #[arg(conflicts_with = "policy")]
        target: Option<String>,

        /// Evaluate the source under this prospective prefix (affects effective
        /// names, `{{ns:}}` expansion, and the unguarded-reference scan).
        /// Ignored when `--policy` is given. `--as` is a hidden deprecated
        /// alias for backwards compatibility.
        // spec: CLI-163 - short moved to -N (uppercase).
        #[arg(short = 'N', long = "namespace", alias = "as", value_name = "PREFIX")]
        alias: Option<String>,

        /// Validate a managed policy TOML file at this path instead of a source.
        /// Cannot be used with `<target>`; supply exactly one of the two.
        #[arg(long, value_name = "PATH", conflicts_with = "target")]
        policy: Option<std::path::PathBuf>,

        /// Rewrite the source in place: hardcoded install paths become tokens and
        /// bare sibling names become `{{ns:}}`. Local-path target only; the sole
        /// `review` mode that writes to disk. Ignored with `--policy`.
        #[arg(long, conflicts_with = "policy")]
        fix: bool,
    },

    /// Diagnose drift, broken symlinks, and unsynced sources.
    // spec: CLI-172
    #[command(visible_alias = "doctor")]
    Introspect {
        /// Repair what is fixable without changing versions (recreate missing links).
        #[arg(long)]
        fix: bool,
    },

    /// View and edit configuration (`~/.mind/config.toml`).
    Config {
        #[command(subcommand)]
        action: ConfigCmd,
    },

    /// Link installed skills into a project's harness skills directory.
    ///
    /// A shorthand for `config lobes add [dir] --preset <name>`. The project
    /// directory `dir` defaults to the current working directory; `--preset`
    /// defaults to `windsurf` (lobe at `<dir>/.windsurf`, skill-only). Existing
    /// installed skills are linked (or, with `--snapshot`, copied as real files)
    /// into the project dir immediately.
    ///
    /// For a managed (non-snapshot) add, gitignore guidance is printed: the skills
    /// directory contains symlinks into `~/.mind/store` and should be gitignored so
    /// the symlinks are not committed.
    // spec: CLI-198 HARN-11
    #[command(name = "link-project")]
    LinkProject {
        /// Project directory to link into (default: current working directory).
        dir: Option<String>,

        /// Harness preset to use (default: windsurf).
        #[arg(long, value_name = "NAME")]
        preset: Option<String>,

        /// Lobe subdirectory under the project dir instead of the preset default.
        /// Conflicts with `--preset`.
        #[arg(long, value_name = "REL", conflicts_with = "preset")]
        subdir: Option<String>,

        /// Write frozen real-file copies instead of registering a managed lobe.
        ///
        /// The copies are real files, not managed by mind: they are committable to
        /// the repo, but a later `mind learn` does not propagate into them (no
        /// auto-propagation). Managed (non-snapshot) lobes use symlinks instead.
        #[arg(long)]
        snapshot: bool,

        /// Overwrite a colliding target: a snapshot file, or a foreign file
        /// blocking backfill of already-installed items into a newly added lobe.
        #[arg(short = 'f', long)]
        force: bool,
    },

    /// Print a shell completion script to stdout.
    Completions {
        /// Shell to generate completions for.
        #[arg(value_enum)]
        shell: clap_complete::Shell,
    },

    /// Print the mind man page (roff) to stdout.
    Man,

    /// Run or list a source's or item's hooks on demand, outside the
    /// meld/learn/forget/upgrade flows.
    ///
    /// Lets you run hooks that were skipped earlier, re-run a hook whose effect
    /// was later lost (a deleted build output or side effect), or re-run an
    /// install or uninstall whose prior run failed for a transient reason.
    ///
    /// Subcommands:
    ///   `hooks run <target>`  -- run hooks with the same disclosure+consent model
    ///   `hooks list <target>` -- list declared hooks without running any
    // spec: CLI-194 CLI-195 CLI-196
    Hooks {
        #[command(subcommand)]
        action: HooksCmd,
    },

    /// Apply what your curators now declare.
    ///
    /// A curator is a melded source that lists other sources
    /// (`[discover].sources`, or a Claude marketplace catalog). Unlike `sync`
    /// (which registers a newly listed entry but installs nothing) and
    /// `upgrade` (which only ever acts on already-installed items), `curate` is
    /// the one command that applies a curator's own decisions: entries listed
    /// upstream but not registered (registered and installed here), items a
    /// curator declares that are not installed, sources whose pin no longer
    /// matches the curator's directive, curated sources whose items are out of
    /// date, and sources no curator lists any more.
    ///
    /// `curate` only ever changes a source it (or a curator) actually
    /// registered: it fetches every curator and every source it owns, then
    /// prints the plan and asks once before applying it. A source curated
    /// before this changed nothing: run `mind curate --adopt <identity>` (the
    /// identity is named in the plan's `adopt` line) to let a curator that
    /// lists it start managing it.
    #[command(visible_alias = "reconcile")]
    Curate {
        /// Report the plan and change nothing. Outranks `--yes`.
        #[arg(long)]
        check: bool,

        /// Also apply `unlist` changes, which uninstall a source's items and
        /// drop the source. Without it they are reported and left alone, so an
        /// unattended `curate --yes` never uninstalls anything.
        #[arg(long)]
        prune: bool,

        /// Plan against the clones already on disk instead of fetching first.
        /// Without it, `curate` (even under `--check`) still fetches every
        /// curator and every source it owns, so a --check run is read-only
        /// with respect to the plan but not with respect to those clones.
        #[arg(long)]
        no_sync: bool,

        /// Claim ownership of one listed-but-unowned identity (named in the
        /// plan's `adopt` line) on behalf of the curator that lists it, and do
        /// nothing else. Never implied by `--yes`.
        #[arg(long, value_name = "IDENTITY")]
        adopt: Option<String>,

        /// Run install- and update-hook re-runs without the safety prompt
        /// (executes arbitrary code from the source).
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run item build hooks without the safety prompt.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,
    },

    /// Write a super-source `mind.toml` reproducing the current melded and
    /// installed state so melding the output recreates the same source set.
    ///
    /// By default, `dump` filters each source to the items actually installed
    /// and stamps the per-entry install directive accordingly. Pass
    /// `--whole-sources` to emit `install = true` for every source regardless
    /// of how many items are installed.
    Dump {
        /// Write to this file instead of stdout.
        #[arg(long, value_name = "PATH")]
        output: Option<std::path::PathBuf>,

        /// Emit `install = true` for every melded source, ignoring how many
        /// of its items are currently installed.
        #[arg(long = "whole-sources")]
        whole_sources: bool,
    },

    /// Claim an unmanaged lobe item into a version-controlled source and install
    /// it as a managed item (the constructive inverse of `forget --unmanaged`).
    ///
    /// Resolves <ref> to a single unmanaged item (an exact `kind:name`; a kind
    /// prefix disambiguates across kinds). Moves the item to the destination source
    /// at the convention path for its kind (`skills/<name>/`, `agents/<name>.md`,
    /// `rules/<name>.md`, `commands/<name>.md`, `workflows/<name>.js`), commits it, melds the source if not yet registered, and
    /// installs it via `learn`. After absorb the item is an ordinary managed item.
    ///
    /// The destination source is resolved from, in precedence order:
    ///   1. `--to <path>` (this flag) takes precedence over all others
    ///   2. `MIND_ABSORB_TO` environment variable
    ///   3. `absorb-to` key in `~/.mind/config.toml` (the legacy `absorb_to`
    ///      spelling is still read)
    ///
    /// If none of these is set and the run is interactive, `absorb` prompts for
    /// a destination and offers `~/.mind/personal` as the built-in default,
    /// creating and `git init`-ing it on demand. Passing `--yes` with no configured
    /// destination automatically uses (and persists) `~/.mind/personal` without
    /// prompting. In a non-interactive (non-TTY) run with no destination configured,
    /// `absorb` refuses with an error.
    Absorb {
        /// The unmanaged item ref: `name`, `skill:name`, `agent:name`,
        /// `rule:name`, `command:name`, or `workflow:name`. A kind prefix disambiguates when the same name exists
        /// across kinds. Glob refs are rejected (absorb claims exactly one item).
        item_ref: String,

        /// Destination source directory. Takes precedence over `MIND_ABSORB_TO`
        /// and the `absorb-to` key in `config.toml`.
        #[arg(long, value_name = "PATH")]
        to: Option<String>,

        /// Overwrite the destination convention path if it already exists
        /// (a `kind:name` collision). Without `--force`, a collision is an error.
        #[arg(short = 'f', long)]
        force: bool,
    },
}

// The `meld` verb's arguments, split out of `Command` so the probe TUI's
// meld input can parse the same flags (TUI-77). A plain comment, not a doc
// comment: the variant's doc comment above stays the subcommand's about.
#[derive(Debug, Clone, Default, PartialEq, Eq, clap::Args)]
pub struct MeldArgs {
    /// Repo spec to meld. Supported forms:
    ///
    /// - Local path:   `/path/to/repo`  or  `file:///path/to/repo`  or  `.`
    ///
    /// - GitHub HTTPS: `owner/repo`  or  `https://github.com/owner/repo`
    ///
    /// - GitHub SSH:   `git@github.com:owner/repo`
    ///
    /// - Any git URL:  `https://example.com/repo.git`
    ///
    /// - Item link:    `https://host/owner/repo/tree/<ref>/<path>` (or the
    ///   `blob/.../SKILL.md` form): registers a single-item source offering
    ///   just that skill. A `blob/.../<file>.md` link does the same for one
    ///   agent, rule, or command (see `--kind`)
    ///
    /// Defaults to the current directory (`.`) when omitted.
    pub repo: Option<String>,

    /// Namespace every item from this source under this prefix
    /// (overrides the repo's own `[source].prefix`). The prefix is part of
    /// the source's identity: melding an already-melded repo under a
    /// different prefix registers a distinct `host/owner/repo@<prefix>`
    /// instance that coexists with the original, rather than re-prefixing it.
    /// `--as` is a hidden deprecated alias for backwards compatibility.
    // spec: CLI-163 - short moved to -N (uppercase); -n is reserved for --dry-run.
    #[arg(short = 'N', long = "namespace", alias = "as", value_name = "PREFIX")]
    pub alias: Option<String>,

    /// Set the version this source tracks (overrides the repo's [source] pin
    /// directive). Takes one required value. `HEAD` freezes the current
    /// resolved tip (the point that would otherwise be melded) to its commit.
    /// A bare `<tag|sha|branch>` resolves that ref to its current commit and
    /// freezes it (a snapshot, not a track). `branch=<name>` follows that
    /// branch (floating; `sync` advances it); `tag=<name>` follows that tag
    /// (re-points on `sync` if it moves). With no `--pin`, the repo's
    /// `[source]` pin directive (else the remote default branch) applies.
    /// Unlike the discovery flags below, this ALSO takes effect against an
    /// already-melded source: a re-meld with `--pin` re-pins it, re-checking
    /// out the clone if the resolved commit differs and reporting what changed.
    // spec: CLI-200, CLI-201, CLI-209
    #[arg(long, value_name = "HEAD|REF|branch=NAME|tag=NAME")]
    pub pin: Option<String>,

    /// Deprecated: use `--pin branch=<name>`.
    // spec: CLI-202
    #[arg(long, value_name = "BRANCH", hide = true)]
    pub follow_branch: Option<String>,

    /// Deprecated: use `--pin tag=<name>`.
    // spec: CLI-202
    #[arg(long, value_name = "TAG", hide = true)]
    pub pin_tag: Option<String>,

    /// Deprecated: use `--pin <commit>`.
    // spec: CLI-202
    #[arg(long, value_name = "COMMIT", hide = true)]
    pub pin_ref: Option<String>,

    /// Set the source's convention-scan roots to one or more repo-root-relative
    /// directories (repeatable). Overrides `[source].roots` in mind.toml.
    /// Persisted on the source and used by later scans and sync. Only takes
    /// effect at the meld that registers the source: passing it against an
    /// already-melded source is ignored (a note lists it and points at
    /// `unmeld` + `meld` to change it).
    // spec: CLI-206
    #[arg(long = "root", value_name = "DIR")]
    pub roots: Vec<String>,

    /// Add convention-scan roots that compose with the source's own
    /// discovery (repeatable): a plugin/marketplace manifest or an
    /// authoritative mind.toml keeps its items and each added root is
    /// convention-scanned in addition, so items the source does not
    /// declare become installable. Unlike --root, this does not override
    /// or suppress anything. Persisted on the source and used by later
    /// scans and sync. Only takes effect at the meld that registers the
    /// source: passing it against an already-melded source is ignored (a
    /// note lists it and points at `unmeld` + `meld` to change it).
    // spec: CLI-206
    #[arg(long = "add-root", value_name = "DIR")]
    pub add_roots: Vec<String>,

    /// Force-enable flat skill discovery: skills are bare-name directories at
    /// each scan root, with no `skills/` container. Turns the layout on for a
    /// source that did not declare `[source].flat-skills`; there is no way to
    /// disable a source's declared flat layout. Applies to skills only (agent,
    /// rule, command, workflow, and tool discovery are unaffected) and to convention discovery
    /// only (ignored for an authoritative `mind.toml`). Persisted on the source
    /// and used by later scans and sync. Only takes effect at the meld that
    /// registers the source: passing it against an already-melded source is
    /// ignored (a note lists it and points at `unmeld` + `meld` to change it).
    // spec: CLI-206
    #[arg(long)]
    pub flat_skills: bool,

    /// Supply or override the source's install hook: a shell command run
    /// after checkout to build the tooling its items rely on. Before it runs,
    /// a prompt offers three choices: run it (the default, a bare Enter),
    /// skip it but still install the source, or abort and install nothing.
    /// Overriding a declared `[source].install` is shown loudly in that
    /// prompt. The command replaces the source's declared install and
    /// update hooks: `upgrade` offers your command in place of the
    /// author's for either event.
    /// Use `mind review <repo>` to see a source's declared hook
    /// before melding. Only takes effect at the meld that registers the
    /// source: passing it against an already-melded source is ignored (a
    /// note lists it and points at `unmeld` + `meld` to change it).
    // spec: CLI-206
    #[arg(long, value_name = "CMD")]
    pub install_hook: Option<String>,

    /// Run the install hook without the safety prompt. This executes
    /// arbitrary code from the source; only use it for a source you trust.
    /// Without this flag, a non-TTY run (CI, scripts) skips the hook and just
    /// prints a note, so the tooling is not built; pass this to run it unattended.
    #[arg(long)]
    pub dangerously_skip_install_hook_check: bool,

    /// Run item build hooks without the safety prompt during the install-all
    /// pass. This executes arbitrary code from the source; only use it for a
    /// source you trust. Without this flag, a non-TTY run skips build hooks
    /// and prints a note, so the item's tooling is not built.
    #[arg(long)]
    pub dangerously_skip_build_hook_check: bool,

    /// Only register the source; do not prompt to install its items. By
    /// default, `meld` previews the source's items and offers to install them
    /// all (the interactive form of `learn '<source>#*'`).
    // spec: CLI-165 - canonical name; --link-only is a hidden deprecated alias.
    #[arg(long, alias = "link-only")]
    pub register_only: bool,

    /// Declare what kind of item a `blob` item link's file is: `agent`,
    /// `rule`, or `command`. Only needed for a file that neither sits under
    /// an `agents/`, `rules/`, or `commands/` directory nor declares
    /// `kind:` in its frontmatter. Item links only. A workflow cannot be
    /// item-linked (a blob link takes a `.md` file, a tree link a skill
    /// directory); meld the repo, or use `learn workflow:<name>` instead.
    // spec: CLI-239, LNK-21
    #[arg(long)]
    pub kind: Option<LinkKindArg>,

    /// Install only the items matching this name or glob instead of
    /// offering the source's whole set (repeatable). The pattern selects
    /// within the source being melded, so pass just an item name or glob
    /// (`review`, `skill:*`, `pdf-*`), never a source-qualified ref; quote
    /// a glob so the shell does not expand it first.
    /// `*`, `?`, and `[` are always glob syntax here, so an item whose
    /// name contains one of them cannot be selected as a literal.
    /// A name matches whether or not the source namespaces its items, so
    /// `--learn review` finds an item that installs as `team:review`.
    /// Each match installs through the ordinary `learn` path, so its
    /// intra-source dependencies come with it, and `--yes` (or a TTY
    /// prompt) still gates the install. A pattern matching nothing in
    /// the source is an error. Scoped to the melded
    /// source's own items: the sources a super-source curates are still
    /// registered, but none of their items are installed. Conflicts with
    /// `--register-only`.
    // spec: CLI-236
    #[arg(
        long = "learn",
        value_name = "NAME|GLOB",
        conflicts_with = "register_only"
    )]
    pub learn_patterns: Vec<String>,

    /// Enable this install profile of the source in addition to its
    /// `default` profile (repeatable; a comma-separated list is accepted).
    /// A profile is a named set of the source's items declared in its
    /// `mind.toml` `[profiles]` table; the install offer then covers the
    /// enabled profiles' items instead of the whole source. Composes with
    /// `--learn` (the union is offered). A name the source does not declare
    /// is an error that lists the declared ones. Conflicts with
    /// `--register-only`.
    // spec: PROF-9 PROF-14 PROF-15
    #[arg(
        long = "profile",
        value_name = "NAME",
        conflicts_with = "register_only"
    )]
    pub profiles: Vec<String>,

    /// Do not enable the source's `default` profile. With no `--profile`,
    /// nothing is installed: the source is registered and `mind learn
    /// <source> --profile <name>` installs a profile later.
    // spec: PROF-10
    #[arg(long)]
    pub no_default_profile: bool,

    /// Enable every profile the source declares. An item in no profile is
    /// still not installed; `mind learn <source> --all` installs the whole
    /// source. Conflicts with `--register-only`.
    // spec: PROF-11 PROF-15
    #[arg(long, conflicts_with = "register_only")]
    pub all_profiles: bool,

    /// Offer to install the items of every nested source a super-source
    /// curates (`[discover].sources`), not just the super-source's own items
    /// and the nested sources the curator marked `install = true`.
    #[arg(short = 'r', long)]
    pub recursive: bool,

    /// When installing, overwrite link targets that already exist and are not
    /// managed by mind. Without it, a conflict prompts on a TTY. On a re-meld
    /// of an already-melded source, `--force` ALSO re-offers every one of the
    /// source's install hooks, even those already run at the current commit
    /// (not just the pending ones an ordinary re-meld re-offers).
    // spec: HOOK-60
    #[arg(short = 'f', long)]
    pub force: bool,

    /// Install the source's item(s) into ONLY the current project's lobe --
    /// a registered lobe whose directory lives under the current working
    /// directory -- instead of fanning them into every configured agent
    /// home (the default). Errors when the current directory is not inside
    /// any registered project lobe.
    // spec: HARN-20 HARN-21
    #[arg(long)]
    pub local: bool,
}

#[derive(Debug, Subcommand)]
pub enum ConfigCmd {
    /// Print the current config and where the file lives.
    Show,

    /// Manage agent homes ("lobes") - the directories items are linked into.
    // spec: CLI-172 - the former `target` alias is removed.
    Lobes {
        #[command(subcommand)]
        action: LobesCmd,
    },
}

#[derive(Debug, Subcommand)]
pub enum LobesCmd {
    /// Add an agent home, by path or by a `--preset <name>` harness preset.
    ///
    /// With `--preset`, the lobe path is `[base]/preset.rel_path`. For a global
    /// preset (gemini, codex, universal) the default base is `~`; for a project
    /// preset (windsurf) the default base is cwd. An explicit positional `base`
    /// overrides the default. With `--subdir <REL>` (no preset), the lobe path is
    /// `[base]/<REL>` with a skill-only kinds filter; base defaults to cwd.
    // spec: HARN-10 CLI-199
    Add {
        /// Base directory for the lobe. With `--preset`, the lobe lives at
        /// `base/preset.rel_path`; with `--subdir`, at `base/<REL>`; as a bare
        /// argument, the lobe IS the directory (all kinds, no filter). A leading
        /// `~` is expanded. Omitting this for a project preset defaults to cwd;
        /// omitting it with no preset and no `--subdir` is an error: `add` needs
        /// a path or `--preset <name>`.
        path: Option<String>,

        /// Add a known harness preset (gemini, codex, universal, windsurf).
        /// Resolves the lobe path and kinds filter from the preset definition.
        /// May be combined with a positional base directory.
        #[arg(long, value_name = "NAME")]
        preset: Option<String>,

        /// Lobe subdirectory under the base (or cwd when base is omitted).
        /// The lobe path is `base/<REL>` with a skill-only kinds filter.
        /// Conflicts with `--preset`.
        #[arg(long, value_name = "REL", conflicts_with = "preset")]
        subdir: Option<String>,

        /// Write frozen real-file copies of installed items instead of
        /// registering a managed lobe. No config entry is created. A colliding
        /// target blocks the copy unless `--force` is also given.
        #[arg(long)]
        snapshot: bool,

        /// Overwrite a colliding target: a snapshot file, or a foreign file
        /// blocking backfill of already-installed items into a newly added lobe.
        #[arg(short = 'f', long)]
        force: bool,
    },

    /// List configured agent homes.
    List,

    /// Detect installed agent homes (lobes) and offer to add their presets.
    /// Honors the global `-y`/`--yes` flag to add without prompting.
    Detect,

    /// Remove an agent home.
    Remove {
        /// The configured directory to drop.
        path: String,

        /// Before removing the config entry, convert symlinks confined under
        /// this lobe to frozen real-file copies of the store content (detach
        /// mode). The links are stripped from the manifest and the entry is
        /// dropped from config. Without this flag, symlinks are left in place
        /// and the lobe is simply unregistered.
        // spec: HARN-12 CLI-199
        #[arg(long)]
        snapshot: bool,
    },
}

/// Subcommands of `mind hooks`.
// spec: CLI-194 CLI-195 CLI-196
#[derive(Debug, Subcommand)]
pub enum HooksCmd {
    /// Run a source's or item's hooks on demand, outside meld/learn/forget/upgrade.
    ///
    /// `<target>` is a source FILTER (e.g. `repo`, `owner/repo`, or a glob
    /// like `'*'`) or an item ref `<source>#<item>` (e.g. `agents#skill:scan`).
    /// There is no ambiguity check: a filter matching several sources, or an
    /// item ref matching several items, runs the hook for each in turn.
    ///
    /// For a source or item target with `--event install` (the default) or
    /// `--event update`, only *pending* hooks run by default -- those that
    /// never ran or did not run at the current commit. `--force` re-runs every
    /// install or update hook regardless, for both a source target and an item
    /// target. Uninstall hooks (source or item) carry no recorded run state and
    /// always run.
    ///
    /// Every hook goes through the same disclosure and consent prompt as an
    /// automatic run; it is never more silently than meld/learn would run it.
    // spec: CLI-194 CLI-195
    Run {
        /// The hook target: a source filter (e.g. `repo`, `owner/repo`, `'*'`)
        /// or an item ref `<source>#<item>` (e.g. `agents#skill:scan`).
        target: String,

        /// The lifecycle event to run (default: install).
        ///
        /// `install`, `update`, and `uninstall` are valid for source and item targets.
        /// `build` is valid only for an item target and re-installs the item
        /// through the transactional path (stage, expand, build, swap), leaving
        /// the existing copy untouched if the build fails.
        #[arg(long, value_enum, default_value = "install")]
        event: HookEventArg,

        /// Re-run every install or update hook (source OR item target) even if
        /// it was already recorded at the current commit (for lost outputs or
        /// transient failures), mirroring `meld --force`. No effect on
        /// `--event uninstall` or `--event build`, neither of which filters by
        /// a recorded commit.
        /// `--rerun` is a visible alias that names this flag's actual meaning
        /// here more directly than the borrowed `--force`.
        // spec: CLI-228
        #[arg(long, visible_alias = "rerun")]
        force: bool,

        /// Run install or update hooks without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips install or update hooks and
        /// prints a note.
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run the item build hook without the safety prompt when `--event build`
        /// is given. This executes arbitrary code; only use it for a source
        /// you trust.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,
    },

    /// List the hooks for a source or item without running any.
    ///
    /// For a source target, shows all hooks declared in the source's `mind.toml`
    /// with their event, required/optional flag, and command; for recorded
    /// source install and update hooks, also shows whether the hook is pending
    /// and the commit it last ran at. Also lists any hooks declared by the
    /// source's installed items.
    ///
    /// For an item ref `<source>#<item>`, shows only that item's hooks.
    // spec: CLI-196
    List {
        /// The hook target: a source filter or `<source>#<item>` item ref.
        target: String,
    },
}