fundaia 0.36.2

//! What is true about this platform, for whatever is driving the binary.
//!
//! The second command that talks to nothing. `AGENT.md` travels inside the
//! executable the way `CHANGELOG.md` does, and for a sharper reason: a caller
//! reading this has not signed in yet — working out what it may do here *is*
//! the step before signing in — so an orientation that needed a token would be
//! an orientation nobody reads at the moment it is useful.
//!
//! **The platform serves the same briefing at `/agent.md`, and that copy is the
//! authoritative one.** `AgentBriefing.ts` is where the truths are written, and
//! `test/instructions.test.ts` fails when this file stops carrying them. Two
//! copies rather than a fetch because this command has to answer offline, and
//! the check is what makes two copies safe.

use anyhow::Result;
use owo_colors::OwoColorize;

use crate::output::{self, Format};
use crate::render::markdown;
use crate::render::theme;

/// Eight kilobytes, alongside the changelog's eight. The binary is held under
/// 8 MiB by `cli.yml`, so both together are a fifth of a percent of it.
pub const GUIDE: &str = include_str!("../../AGENT.md");

pub fn run(format: Format) -> Result<()> {
    if format.is_json() {
        // Markdown in a field rather than the sections as a tree: the text is
        // the artefact here — something to put in a context window whole — and
        // a caller that wanted it structured wants `fundaia schema` instead.
        output::emit(&serde_json::json!({
            "version": env!("CARGO_PKG_VERSION"),
            "markdown": GUIDE,
        }));
        return Ok(());
    }

    println!();
    println!("{}", markdown::body(GUIDE));
    println!();
    println!(
        "  {}",
        "`fundaia schema --json` es la superficie entera, comando por comando."
            .style(theme::muted()),
    );
    println!();
    Ok(())
}

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

    /// The one a caller cannot discover by trying, because the wrong call
    /// *succeeds*: `new` then `deploy` is two deployments, not one.
    #[test]
    fn it_should_warn_that_creating_a_service_deploys_it() {
        assert!(GUIDE.contains("Creating a service deploys it."));
    }

    /// The contract this whole file exists to state. Without the numbers a
    /// caller is back to parsing a sentence written for somebody else.
    #[test]
    fn it_should_say_what_the_exit_codes_mean() {
        assert!(GUIDE.contains("The exit code says which kind of failure it was"));
    }

    /// An agent that speaks MCP should be told so before it learns sixty
    /// argument shapes it did not need.
    #[test]
    fn it_should_send_a_caller_that_speaks_mcp_to_the_instance_instead() {
        assert!(GUIDE.contains("/api/infra/mcp"));
    }

    #[test]
    fn it_should_say_that_nothing_ever_prompts() {
        assert!(GUIDE.contains("Nothing ever prompts."));
    }

    /// `--confirm` takes the name of the thing. A caller that assumed a boolean
    /// writes `--confirm yes`, which is refused, which costs a round trip.
    #[test]
    fn it_should_say_that_a_confirmation_is_the_name_and_not_a_yes() {
        assert!(GUIDE.contains("the name of the\n  thing, not a `yes`"));
    }

    /// `render::markdown` reads a line at a time, so a code span or a bold run
    /// that wraps opens on one line and closes on the next — which prints the
    /// delimiter and swallows the words after it. The shape of this file is
    /// therefore part of the contract, and this is the assertion that keeps a
    /// reflow from quietly mangling a paragraph nobody re-reads in a terminal.
    #[test]
    fn it_should_close_every_delimiter_on_the_line_that_opened_it() {
        let wrapped: Vec<&str> = GUIDE
            .lines()
            .filter(|line| line.matches('`').count() % 2 != 0 || unbalanced_bold(line))
            .collect();

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

    /// Counted before the single asterisks, because `**` contains one: a line
    /// with `**bold**` in it has two runs and no stray emphasis.
    fn unbalanced_bold(line: &str) -> bool {
        line.matches("**").count() % 2 != 0
    }

    /// A guide that names a command the parser does not accept sends whoever
    /// followed it into a usage error, on the tool's own advice. The hint table
    /// said `fundaia logs --stage` for a week and the flag is `--step`; this is
    /// the same mistake one level up, and the parser is right here to ask.
    #[test]
    fn it_should_name_no_command_the_parser_does_not_accept() {
        let parser = crate::built();
        let invented: Vec<&str> = commands_named_in(GUIDE)
            .into_iter()
            .filter(|named| {
                !parser
                    .get_subcommands()
                    .any(|command| command.get_name() == *named)
            })
            .collect();

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

    /// The word after `fundaia`, wherever the guide writes one — inside a code
    /// span or in the middle of a sentence. `<command>` is the placeholder in
    /// "`fundaia <command> --help`" and names nothing.
    fn commands_named_in(text: &str) -> Vec<&str> {
        text.split("fundaia ")
            .skip(1)
            .filter_map(|after| after.split([' ', '`', '\n', ',', '.']).next())
            .filter(|word| !word.is_empty() && !word.starts_with('<'))
            .collect()
    }
}