fundaia 0.32.1

use clap::{Arg, ArgAction, Command};
use owo_colors::OwoColorize;
use serde::Serialize;

use crate::exit::Exit;
use crate::output::Format;
use crate::render::table::{Cell, Table};
use crate::render::theme;

/// The whole command surface, as one machine-readable answer.
///
/// **`completions` for something that is not a shell.** A shell is handed the
/// arguments it may complete because guessing them is worse than asking; an
/// agent is in exactly that position and had nothing to ask. Its options were
/// `--help` on sixty commands — prose, written for a person, in Spanish, with
/// the shape of each argument implied by its punctuation — or a guess. Both are
/// how a session gets spent on discovering that `--confirm` takes the name and
/// not a `yes`.
///
/// Generated from `Cli::command()` for the same reason the completion scripts
/// are: it is the parser describing itself, so it cannot disagree with what the
/// parser accepts. A hand-written manifest would be wrong the first time an
/// argument moved, and wrong in the one document whose entire job is saying
/// what the arguments are.
///
/// Three things are published that clap does not know. `effect` says whether a
/// command reads, writes, starts something or destroys something — the same four
/// words the MCP tools are annotated with, so an agent that knows one surface
/// recognises the other. The exit table says what the process will leave in
/// `$?`. And the `--json` contract says what shape to expect back, which is the
/// one fact that decides whether a caller reads stdout as a value or as a
/// stream.
#[derive(Serialize)]
struct Schema {
    tool: &'static str,
    version: &'static str,
    /// What the tool is for, in the words the parser itself carries.
    about: String,
    json: JsonContract,
    /// What each `effect` below means. The vocabulary, before the list that uses it.
    effects: Vec<Effect>,
    exits: Vec<ExitClass>,
    /// The flags accepted before the command, on every command.
    globals: Vec<Argument>,
    /// Flat rather than nested: `path` is what somebody types, and a tree would
    /// make a caller walk it to find that out.
    commands: Vec<CommandEntry>,
}

#[derive(Serialize)]
struct JsonContract {
    flag: &'static str,
    environment: &'static str,
    /// What stdout carries with the flag on.
    answers: &'static str,
    /// What stderr carries when it fails.
    failures: &'static str,
}

#[derive(Serialize)]
struct Effect {
    name: &'static str,
    means: &'static str,
}

#[derive(Serialize)]
struct ExitClass {
    code: i32,
    name: &'static str,
    means: &'static str,
    /// Whether the identical invocation can be expected to work later.
    retryable: bool,
    /// What to try next, in the words the terminal prints. Spanish, like every
    /// other sentence this tool shows a person — `means` above is the half
    /// written for whatever is driving it.
    #[serde(skip_serializing_if = "Option::is_none")]
    hint: Option<&'static str>,
}

#[derive(Serialize)]
struct CommandEntry {
    /// What is typed after `fundaia`: `project new`, `variables set`.
    path: String,
    /// Other spellings of the last word. `vars` for `variables`.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    aliases: Vec<String>,
    about: String,
    /// The long help, where the reason for the command is written down.
    #[serde(skip_serializing_if = "Option::is_none")]
    detail: Option<String>,
    effect: &'static str,
    arguments: Vec<Argument>,
    /// The commands nested under this one, by their own `path`.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    subcommands: Vec<String>,
}

#[derive(Serialize)]
struct Argument {
    name: String,
    /// `positional`, `flag` — present or absent — or `option`, which takes a value.
    kind: &'static str,
    required: bool,
    /// Whether it may be given more than once, or as a comma-separated list.
    many: bool,
    #[serde(skip_serializing_if = "Option::is_none")]
    long: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    short: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    value: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    default: Option<String>,
    /// The environment variable that fills it in, for a caller configured once.
    #[serde(skip_serializing_if = "Option::is_none")]
    environment: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    help: Option<String>,
}

/// What a command does to the platform, in the four words MCP annotates with.
///
/// `local` is the fifth and it is not a write of any kind: `login`, `changelog`
/// and this command itself touch this machine and nothing else, and calling one
/// twice is the same as calling it once because there is nothing there to
/// change. Lumping them in with the reads would have said they ask the instance
/// something, which is the fact that decides whether a caller needs a token.
///
/// Published with their meanings rather than as five bare words, because the
/// difference between `writes` and `starts` is the whole reason the annotation
/// is worth having and it is not guessable from the name.
const EFFECTS: &[(&str, &str)] = &[
    (
        "local",
        "Touches this machine and nothing else. No instance, no token, no network.",
    ),
    ("reads", "Asks the instance something and changes nothing."),
    (
        "writes",
        "Adds or replaces something. Calling it twice is the same as calling it once.",
    ),
    (
        "starts",
        "Sets something running. Calling it twice is two of them — deploying twice is two deployments.",
    ),
    (
        "destroys",
        "Removes or overwrites something. Takes --confirm <name>, and calling it again will not undo it.",
    ),
];

/// Every command, with what it does. The table nothing else could derive.
///
/// Keyed on the path as typed, and exhaustive by test: a command added without
/// a line here fails `it_should_say_what_every_command_does`, and a line naming
/// a command that no longer exists fails the one after it. That pairing is the
/// point — an annotation table that is allowed to go stale is worse than none,
/// because a caller trusts it.
const EFFECT_OF: &[(&str, &str)] = &[
    // Nothing but this machine.
    ("login", "local"),
    ("logout", "local"),
    ("upgrade", "local"),
    ("changelog", "local"),
    ("completions", "local"),
    ("schema", "local"),
    ("guide", "local"),
    // Questions.
    ("whoami", "reads"),
    ("status", "reads"),
    ("projects", "reads"),
    ("services", "reads"),
    ("service", "reads"),
    ("canvas", "reads"),
    ("canvas show", "reads"),
    ("templates", "reads"),
    ("uploads", "reads"),
    ("history", "reads"),
    ("commit", "reads"),
    ("activity", "reads"),
    ("sign-ins", "reads"),
    ("sessions", "reads"),
    ("watch", "reads"),
    ("logs", "reads"),
    ("incidents", "reads"),
    ("workflows", "reads"),
    ("workflows list", "reads"),
    ("workflows runs", "reads"),
    ("workflows show", "reads"),
    ("workflows logs", "reads"),
    ("workflows artifact", "reads"),
    ("workflows run", "starts"),
    ("workflows rerun", "starts"),
    ("workflows cancel", "writes"),
    ("approvals", "reads"),
    ("autofix", "reads"),
    ("metrics", "reads"),
    ("consumption", "reads"),
    ("agent-activity", "reads"),
    ("variables", "reads"),
    ("variables list", "reads"),
    ("data", "reads"),
    ("data tables", "reads"),
    ("data query", "reads"),
    ("capacity", "reads"),
    ("capabilities", "reads"),
    ("connectable", "reads"),
    ("volumes", "reads"),
    ("volumes list", "reads"),
    ("domains", "reads"),
    ("domains list", "reads"),
    ("backups", "reads"),
    ("backups list", "reads"),
    ("access", "reads"),
    ("access status", "reads"),
    ("recipe", "reads"),
    ("recipe show", "reads"),
    ("config", "reads"),
    ("config show", "reads"),
    ("workspace", "reads"),
    ("workspace list", "reads"),
    ("workspace members", "reads"),
    ("workspace credits", "reads"),
    ("project", "reads"),
    // Changes that can be repeated without further effect.
    ("agent", "writes"),
    ("rename", "writes"),
    ("settings", "writes"),
    ("expose", "writes"),
    ("encrypt", "writes"),
    ("connect", "writes"),
    ("disconnect", "writes"),
    ("incident", "writes"),
    ("reject", "writes"),
    ("canvas move", "writes"),
    ("canvas arrange", "writes"),
    ("variables set", "writes"),
    ("variables import", "writes"),
    ("variables seal", "writes"),
    ("volumes add", "writes"),
    ("volumes resize", "writes"),
    ("domains add", "writes"),
    ("domains verify", "writes"),
    ("backups schedule", "writes"),
    ("backups keep", "writes"),
    ("backups unkeep", "writes"),
    ("access request", "writes"),
    ("recipe edit", "writes"),
    ("config edit", "writes"),
    ("project new", "writes"),
    ("project rename", "writes"),
    ("project move", "writes"),
    ("workspace invite", "writes"),
    // Changes where twice is not once: each call starts something.
    ("new", "starts"),
    ("up", "starts"),
    ("deploy", "starts"),
    ("redeploy", "starts"),
    ("rollback", "starts"),
    ("cancel", "starts"),
    ("stop", "starts"),
    ("approve", "starts"),
    ("fix", "starts"),
    ("backups new", "starts"),
    // Changes that take something away.
    ("delete", "destroys"),
    ("project delete", "destroys"),
    ("variables unset", "destroys"),
    // One statement against somebody's database, committed. `--preview` rolls
    // it back, but the command is annotated by the worst it can do.
    ("data run", "destroys"),
    ("volumes remove", "destroys"),
    ("domains remove", "destroys"),
    ("backups restore", "destroys"),
    ("backups remove", "destroys"),
    ("sessions revoke", "destroys"),
    ("workspace revoke", "destroys"),
    ("workspace remove", "destroys"),
];

/// Nothing that talks to an instance, so this answers with no token and no
/// network — like `changelog`, and for the same reason: a caller working out
/// what it may do has not signed in yet.
pub fn run(root: &Command, format: Format) -> anyhow::Result<()> {
    let schema = describe(root);

    if format.answered_in_json(&schema) {
        return Ok(());
    }

    draw(&schema);
    Ok(())
}

fn describe(root: &Command) -> Schema {
    let mut commands = Vec::new();
    collect(root, "", &mut commands);

    Schema {
        tool: "fundaia",
        version: env!("CARGO_PKG_VERSION"),
        about: root
            .get_about()
            .map(ToString::to_string)
            .unwrap_or_default(),
        json: JsonContract {
            flag: "--json",
            environment: "FUNDAIA_JSON=1",
            answers:
                "One compact JSON value on stdout, on one line. On a stream (logs, watch) one object per line, as they arrive. A write confirms by its exit code and prints nothing.",
            failures:
                "One object on stderr: { error: { code, message, exit, retryable, causes?, hint? } }. `code` is the platform's own, `exit` is the number the process leaves.",
        },
        effects: EFFECTS
            .iter()
            .map(|(name, means)| Effect { name, means })
            .collect(),
        exits: Exit::all()
            .into_iter()
            .map(|exit| ExitClass {
                code: exit.code(),
                name: exit.name(),
                means: exit.meaning(),
                retryable: exit.retryable(),
                hint: crate::exit::hint(exit),
            })
            .collect(),
        globals: root
            .get_arguments()
            .filter(|argument| worth_publishing(argument))
            .map(describe_argument)
            .collect(),
        commands,
    }
}

/// Depth first, so a parent is listed before its children and a caller reading
/// top to bottom meets `project` before `project delete`.
fn collect(parent: &Command, prefix: &str, into: &mut Vec<CommandEntry>) {
    for command in parent.get_subcommands() {
        // `help`, and `help <command>` under every parent: clap's own, added by
        // `build()`, and the same noise as publishing `--help` sixty times.
        // Whatever reads this has `about` on every entry already.
        if command.get_name() == "help" {
            continue;
        }

        let path = if prefix.is_empty() {
            command.get_name().to_owned()
        } else {
            format!("{prefix} {}", command.get_name())
        };

        into.push(CommandEntry {
            path: path.clone(),
            aliases: command
                .get_visible_aliases()
                .map(ToOwned::to_owned)
                .collect(),
            about: command
                .get_about()
                .map(ToString::to_string)
                .unwrap_or_default(),
            detail: command.get_long_about().map(ToString::to_string),
            effect: effect_of(&path),
            arguments: command
                .get_arguments()
                .filter(|argument| worth_publishing(argument))
                .map(describe_argument)
                .collect(),
            subcommands: command
                .get_subcommands()
                .map(|child| format!("{path} {}", child.get_name()))
                .collect(),
        });

        collect(command, &path, into);
    }
}

/// `--help` and `--version` are clap's own and sit on every command. Publishing
/// them sixty times would be sixty entries that say nothing about this tool.
fn worth_publishing(argument: &Arg) -> bool {
    !matches!(argument.get_id().as_str(), "help" | "version")
}

fn describe_argument(argument: &Arg) -> Argument {
    let takes_value = !matches!(
        argument.get_action(),
        ArgAction::SetTrue | ArgAction::SetFalse | ArgAction::Count
    );

    Argument {
        name: argument.get_id().to_string(),
        kind: if argument.is_positional() {
            "positional"
        } else if takes_value {
            "option"
        } else {
            "flag"
        },
        required: argument.is_required_set(),
        // A list either repeats or arrives comma-separated; both are the same
        // question for a caller building the invocation.
        many: matches!(argument.get_action(), ArgAction::Append)
            || argument.get_value_delimiter().is_some(),
        long: argument.get_long().map(ToOwned::to_owned),
        short: argument.get_short().map(|short| short.to_string()),
        // Only where there is a value to name. clap gives a flag a value name
        // and a `false` default of its own, and publishing them would say
        // `--upload FALSE` takes an argument, which is how a caller writes an
        // invocation the parser then refuses.
        value: takes_value
            .then(|| argument.get_value_names().and_then(|names| names.first()))
            .flatten()
            .map(ToString::to_string),
        default: takes_value
            .then(|| argument.get_default_values().first())
            .flatten()
            .map(|value| value.to_string_lossy().into_owned()),
        environment: argument
            .get_env()
            .map(|name| name.to_string_lossy().into_owned()),
        help: argument.get_help().map(ToString::to_string),
    }
}

fn effect_of(path: &str) -> &'static str {
    EFFECT_OF
        .iter()
        .find(|(command, _)| *command == path)
        // Unannotated reads as the safest thing it could be rather than as a
        // read: a caller that gates on `destroys` should not be told a command
        // it has never heard of is harmless.
        .map_or("destroys", |(_, effect)| effect)
}

/// The same list for a person: one row per command, widest column first.
///
/// Not a replacement for `--help`, which explains one command properly. This is
/// the index — what exists and what each one touches — which is the question
/// `--help` answers badly because it answers it sixty times.
fn draw(schema: &Schema) {
    println!();
    println!(
        "  {} {}",
        "fundaia".style(theme::strong()),
        schema.version.style(theme::muted()),
    );
    println!(
        "  {}",
        "`fundaia schema --json` trae esto mismo con cada argumento.".style(theme::muted())
    );
    println!();

    let mut commands = Table::new(&["COMANDO", "EFECTO", "QUÉ HACE"]);
    for command in &schema.commands {
        commands.push(vec![
            Cell::styled(command.path.as_str(), theme::strong()),
            Cell::styled(command.effect, effect_style(command.effect)),
            Cell::plain(command.about.as_str()),
        ]);
    }
    commands.print();

    println!();
    // The advice rather than the meaning: the meaning is in `--json` for
    // whatever is driving this, and what the person watching wants is the next
    // move — in the language every other line of this tool speaks.
    let mut exits = Table::new(&["SALIDA", "CLASE", "REPETIR", "QUÉ HACER"]);
    for exit in &schema.exits {
        exits.push(vec![
            Cell::plain(exit.code.to_string()),
            Cell::styled(exit.name, theme::strong()),
            Cell::plain(if exit.retryable { "sí" } else { "no" }),
            Cell::plain(exit.hint.unwrap_or("—")),
        ]);
    }
    exits.print();
    println!();
}

fn effect_style(effect: &str) -> owo_colors::Style {
    match effect {
        "destroys" => theme::danger(),
        "starts" => theme::warning(),
        "reads" | "local" => theme::muted(),
        _ => theme::strong(),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The pair of assertions that keeps the table honest. This one catches a
    /// command added without an annotation, which would otherwise be published
    /// as `destroys` — safe, and wrong.
    #[test]
    fn it_should_say_what_every_command_does() {
        let unannotated: Vec<String> = paths()
            .into_iter()
            .filter(|path| !EFFECT_OF.iter().any(|(command, _)| command == path))
            .collect();

        assert_eq!(unannotated, Vec::<String>::new());
    }

    /// And this one catches a command renamed or removed, which would leave an
    /// annotation describing something nobody can type.
    #[test]
    fn it_should_annotate_nothing_that_cannot_be_typed() {
        let known = paths();
        let stale: Vec<&str> = EFFECT_OF
            .iter()
            .map(|(command, _)| *command)
            .filter(|command| !known.iter().any(|path| path == command))
            .collect();

        assert_eq!(stale, Vec::<&str>::new());
    }

    #[test]
    fn it_should_annotate_every_command_with_one_of_the_five_effects() {
        let invented: Vec<&str> = EFFECT_OF
            .iter()
            .map(|(_, effect)| *effect)
            .filter(|effect| !EFFECTS.iter().any(|(name, _)| name == effect))
            .collect();

        assert_eq!(invented, Vec::<&str>::new());
    }

    #[test]
    fn it_should_name_every_command_once() {
        let paths = paths();
        assert_eq!(
            paths.iter().collect::<std::collections::HashSet<_>>().len(),
            paths.len()
        );
    }

    /// Deleting a service is the command a caller most needs told about in
    /// advance, and the annotation is the only place it is said before it runs.
    #[test]
    fn it_should_mark_deleting_a_service_as_destructive() {
        assert_eq!(effect_of("delete"), "destroys");
    }

    /// Twice is two deployments, which is the distinction `writes` would lose.
    #[test]
    fn it_should_mark_deploying_as_something_that_starts() {
        assert_eq!(effect_of("deploy"), "starts");
    }

    #[test]
    fn it_should_treat_a_command_it_has_never_heard_of_as_the_worst_case() {
        assert_eq!(effect_of("something-added-later"), "destroys");
    }

    /// The parser's own knowledge, not a restatement of it: an argument that
    /// moves moves here too.
    #[test]
    fn it_should_publish_the_confirmation_that_deleting_a_service_needs() {
        let schema = describe(&crate::built());
        let delete = schema
            .commands
            .iter()
            .find(|command| command.path == "delete")
            .expect("`delete` is a command");

        assert!(delete
            .arguments
            .iter()
            .any(|argument| argument.name == "confirm"));
    }

    #[test]
    fn it_should_publish_the_environment_variable_that_carries_the_token() {
        let schema = describe(&crate::built());
        let token = schema
            .globals
            .iter()
            .find(|argument| argument.name == "token")
            .expect("`--token` is global");

        assert_eq!(token.environment.as_deref(), Some("FUNDAIA_TOKEN"));
    }

    #[test]
    fn it_should_publish_a_list_argument_as_one_that_takes_many() {
        let schema = describe(&crate::built());
        let new = schema
            .commands
            .iter()
            .find(|command| command.path == "new")
            .expect("`new` is a command");

        let connect = new
            .arguments
            .iter()
            .find(|argument| argument.name == "connect_to")
            .expect("`--connect-to` is an argument of `new`");

        assert!(connect.many);
    }

    /// clap names a flag's value and defaults it to `false`; both would read as
    /// "this takes an argument", which is an invocation the parser refuses.
    #[test]
    fn it_should_publish_no_value_for_a_flag_that_takes_none() {
        let schema = describe(&crate::built());
        let upload = schema
            .commands
            .iter()
            .find(|command| command.path == "new")
            .and_then(|command| {
                command
                    .arguments
                    .iter()
                    .find(|argument| argument.name == "upload")
            })
            .expect("`--upload` is a flag of `new`");

        assert_eq!(upload.value, None);
    }

    #[test]
    fn it_should_publish_no_default_for_a_flag_that_takes_none() {
        let schema = describe(&crate::built());
        let upload = schema
            .commands
            .iter()
            .find(|command| command.path == "new")
            .and_then(|command| {
                command
                    .arguments
                    .iter()
                    .find(|argument| argument.name == "upload")
            })
            .expect("`--upload` is a flag of `new`");

        assert_eq!(upload.default, None);
    }

    /// And the branch an option takes is published, so a caller knows `main` is
    /// what it gets without asking.
    #[test]
    fn it_should_publish_the_default_of_an_option_that_has_one() {
        let schema = describe(&crate::built());
        let branch = schema
            .commands
            .iter()
            .find(|command| command.path == "new")
            .and_then(|command| {
                command
                    .arguments
                    .iter()
                    .find(|argument| argument.name == "branch")
            })
            .expect("`--branch` is an option of `new`");

        assert_eq!(branch.default.as_deref(), Some("main"));
    }

    #[test]
    fn it_should_publish_clap_s_own_flags_nowhere() {
        let schema = describe(&crate::built());
        let clap_s_own: Vec<&Argument> = schema
            .commands
            .iter()
            .flat_map(|command| command.arguments.iter())
            .filter(|argument| argument.name == "help" || argument.name == "version")
            .collect();

        assert_eq!(clap_s_own.len(), 0);
    }

    #[test]
    fn it_should_explain_every_effect_it_annotates_with() {
        let unexplained: Vec<&str> = EFFECTS
            .iter()
            .filter(|(_, means)| means.is_empty())
            .map(|(name, _)| *name)
            .collect();

        assert_eq!(unexplained, Vec::<&str>::new());
    }

    #[test]
    fn it_should_publish_every_exit_class_the_binary_can_leave() {
        assert_eq!(describe(&crate::built()).exits.len(), Exit::all().len());
    }

    /// Both halves on the same row: the sentence for a model and the one for
    /// the person reading the terminal it ran in.
    #[test]
    fn it_should_publish_an_exit_class_with_its_advice_as_well_as_its_meaning() {
        let schema = describe(&crate::built());
        let unauthorized = schema
            .exits
            .iter()
            .find(|class| class.name == "unauthorized")
            .expect("`unauthorized` is a class");

        assert!(unauthorized
            .hint
            .is_some_and(|advice| advice.contains("fundaia login")));
    }

    /// Every path the parser accepts, parents included: a parent with an
    /// optional subcommand is a command somebody types on its own.
    fn paths() -> Vec<String> {
        let mut found = Vec::new();
        collect(&crate::built(), "", &mut found);
        found.into_iter().map(|entry| entry.path).collect()
    }
}