aion-cli 0.30.0

//! Running a declared demonstration artifact, and reading the record its
//! output names.
//!
//! # Why the record is READ and not invented
//!
//! Every refusal this estate's instruments print carries `named cause: <code>`
//! — the command surface's own rendering, and the shape a gate script's
//! `GATE-RED:` line already uses. So a fired artifact's record is READ out of
//! the bytes it printed, not synthesised from an exit status: an exit code
//! says something failed, and the whole point of a known-answer red is that
//! the instrument said the RIGHT thing.
//!
//! An artifact whose output names no cause is refused rather than given one.
//! Inventing a code here would make every mismatch look like a match.

use std::path::{Path, PathBuf};

use aion_awl::command::recipe::{CommandLine, CommandRunner, SpecimenFirer, VerdictRecord};

/// The marker every instrument in this estate prints beside a refusal.
const CAUSE_MARKER: &str = "named cause: ";

/// The layer a fired artifact's record is filed under.
///
/// One string, stated once: a fired artifact is an instrument answering
/// about a tree, and `gate` is what such an instrument is called here.
const FIRED_LAYER: &str = "gate";

/// Fires a declared artifact as a real process, rooted.
pub(crate) struct ProcessFirer {
    root: PathBuf,
}

impl ProcessFirer {
    /// Root the firer at `root`.
    pub(crate) fn rooted(root: &Path) -> Self {
        Self {
            root: root.to_path_buf(),
        }
    }
}

impl SpecimenFirer for ProcessFirer {
    fn fire(&self, address: &str) -> Result<VerdictRecord, String> {
        let path = self.root.join(address);
        if !path.exists() {
            return Err(format!("{} does not exist", path.display()));
        }
        // Run to completion and read what it said. No timeout is imposed
        // here: a ceiling this command invented would be a number nobody
        // chose, and the declaration carries none. Nothing is spawned in the
        // background, so nothing needs killing.
        let output = std::process::Command::new(&path)
            .current_dir(&self.root)
            .output()
            .map_err(|error| format!("{} could not be run: {error}", path.display()))?;

        let mut said = String::from_utf8_lossy(&output.stdout).into_owned();
        said.push_str(&String::from_utf8_lossy(&output.stderr));
        let Some((code, line)) = named_cause(&said) else {
            return Err(format!(
                "{} exited {} and its output names no `{CAUSE_MARKER}<code>`, so there is nothing \
                 to compare a known answer against — an artifact fired as a known-answer red must \
                 say WHAT it found, not merely that it found something",
                path.display(),
                output
                    .status
                    .code()
                    .map_or_else(|| "by signal".to_owned(), |code| code.to_string())
            ));
        };
        VerdictRecord::new(code, FIRED_LAYER, line).map_err(|error| error.to_string())
    }
}

/// The first `named cause: <code>` an output carries, with the whole line it
/// stood on as the bytes observed.
fn named_cause(said: &str) -> Option<(String, String)> {
    said.lines().find_map(|line| {
        let at = line.find(CAUSE_MARKER)? + CAUSE_MARKER.len();
        let code: String = line[at..]
            .chars()
            .take_while(|character| character.is_ascii_lowercase() || *character == '_')
            .collect();
        (!code.is_empty()).then(|| (code, line.trim().to_owned()))
    })
}

/// Runs ONE line of a declared command's EMITTED argv as a real process,
/// rooted.
///
/// The argv arrives whole: one element per entry, never a string this side
/// re-splits. That is the property the command surface exists to keep, and
/// the executing side is the last place it could be lost — so it is spent
/// exactly as it arrived.
///
/// One line per call, because the body's sequencing — lines in order, the
/// first non-zero exit failing the command — belongs to the fire loop and is
/// answered there once.
///
/// # The world the line runs in
///
/// The same world the worker's declared-body executor establishes, and by the
/// same code: [`aion_worker::shell::place_in_declared_world`], which
/// `DeclaredCommandAction::run` calls with the document's exports
/// (`crates/aion-worker/src/shell/declared.rs`, the `place_in_declared_world`
/// call in its body loop). A recipe that fired a line into a different world
/// would be measuring a different program than the one a deployment runs,
/// which is the one thing an instrument may not do.
///
/// The worker executor's spawn — the whole of it, read off that loop rather
/// than sampled — is eight properties. Seven of them are here:
///
/// 1. the argv is spent whole — `Command::new(program)` plus `args(rest)`, an
///    `execve` with no shell interposed;
/// 2. standard input is CLOSED, so a line that reads it gets end-of-file
///    rather than the operator's terminal (`shell/world.rs`, one call);
/// 3. the host's environment is CLEARED — a fired line cannot read this
///    machine's credentials (same call);
/// 4. `PATH` alone is put back, at the host's value, so a bare program name
///    resolves (same call);
/// 5. the document's exports are applied in DECLARED ORDER over it (same
///    call);
/// 6. an exported `PATH` therefore overrides the inherited one (same call);
/// 7. the line runs in the declared working directory, resolved by the
///    executing side against ITS workspace — which is this run's root
///    (`current_dir`, as the worker does with the root its host resolved).
///
/// The eighth is where the two deliberately differ, stated rather than left to
/// be discovered: the worker CONTAINS the process in its own group and
/// captures both streams line by line onto the activity's transcript (its
/// `CommandTranscript::for_body_line` plus `run_cancellable_command`), because
/// an activity is cancellable and its output
/// is a durable record. A fired line is neither: `aion awl recipe fire` runs
/// one line to completion in the foreground, with no activity to cancel it and
/// no transcript to publish to, so the line's output goes where an operator
/// running a recipe expects it — this terminal — and the exit status is what
/// comes back. Nothing here can outlive the call to be left running.
pub(crate) struct ProcessRunner {
    root: PathBuf,
}

impl ProcessRunner {
    /// Root the runner at `root`.
    pub(crate) fn rooted(root: &Path) -> Self {
        Self {
            root: root.to_path_buf(),
        }
    }
}

impl CommandRunner for ProcessRunner {
    fn run(&self, line: &CommandLine<'_>) -> Result<i32, String> {
        let Some((program, arguments)) = line.argv.split_first() else {
            return Err("the emitted argv is empty, so there is no program to run".to_owned());
        };
        let mut process = std::process::Command::new(program);
        process.args(arguments);
        // Closed stdin, a cleared host environment, PATH, then the document's
        // exports in declared order — the one world a declared command runs
        // in, established by the one function the worker's executors call, so
        // a fired line and a deployed line cannot answer differently about
        // what the process can see.
        aion_worker::shell::place_in_declared_world(
            &mut process,
            line.env
                .iter()
                .map(|(name, value)| (name.as_str(), value.as_str())),
        );
        // `cwd` arrives with its placeholder UNEXPANDED, because expanding it
        // is the executing side's act against ITS workspace — which is here,
        // and the workspace is the root this run was given.
        let working = line.cwd.map_or_else(
            || self.root.clone(),
            |cwd| {
                self.root
                    .join(cwd.replace(aion_awl::WORKSPACE_ROOT_PLACEHOLDER, "."))
            },
        );
        process.current_dir(working);
        // Run to completion. Nothing is spawned in the background, so nothing
        // needs killing; no ceiling is imposed that the declaration did not
        // state, because a number this side invented would be a number nobody
        // chose.
        let status = process
            .status()
            .map_err(|error| format!("`{program}` could not be run: {error}"))?;
        status.code().ok_or_else(|| {
            format!("`{program}` was ended by a signal rather than exiting, so it named no status")
        })
    }
}

#[cfg(test)]
mod tests {
    use std::collections::BTreeMap;
    use std::io::Write as _;
    use std::path::Path;

    use aion_awl::command::recipe::{CommandLine, CommandRunner};

    use super::{ProcessRunner, named_cause};

    /// What a test returns. Every fallible step is carried rather than
    /// unwrapped, because the workspace denies panicking accessors in test code
    /// as firmly as in library code.
    type TestResult = Result<(), Box<dyn std::error::Error>>;

    /// The three names `sh` puts into its children's environment itself. Named
    /// rather than tolerated by a loose assertion: an environment census that
    /// waved through anything it did not recognise would wave through a leak.
    const SHELL_OWN_NAMES: [&str; 3] = ["PWD", "SHLVL", "_"];

    /// A `sh` script that writes everything this test wants to know about the
    /// world it was given into the file named by `$2`.
    ///
    /// Written to a FILE rather than to standard output because the runner
    /// reports a status and lets the line's output reach the operator's
    /// terminal — which is the runner's contract, not an omission — so the
    /// file is how a test reads what the child saw.
    fn probe_script() -> String {
        [
            "{ /usr/bin/env",
            "printf 'CWD=%s\\n' \"$(pwd)\"",
            "printf 'ARGC=%s\\n' \"$#\"",
            "printf 'ARG1=[%s]\\n' \"$1\"",
            "printf 'STDIN=[%s]\\n' \"$(cat)\"",
            "} > \"$2\" 2>&1",
        ]
        .join("; ")
    }

    /// The argv the probe is run as: `sh -c <script> probe <hostile> <file>`.
    fn probe_argv(hostile: &str, observations: &Path) -> Vec<String> {
        vec![
            "/bin/sh".to_owned(),
            "-c".to_owned(),
            probe_script(),
            "probe".to_owned(),
            hostile.to_owned(),
            observations.display().to_string(),
        ]
    }

    /// Every `NAME=VALUE` line the probe wrote, as a map. The probe's own
    /// answers (`CWD`, `ARGC`, `ARG1`, `STDIN`) share the shape, so they arrive
    /// in the same map and are read out of it by name.
    fn observed(
        observations: &Path,
    ) -> Result<BTreeMap<String, String>, Box<dyn std::error::Error>> {
        let text = std::fs::read_to_string(observations)?;
        Ok(text
            .lines()
            .filter_map(|line| line.split_once('='))
            .map(|(name, value)| (name.to_owned(), value.to_owned()))
            .collect())
    }

    fn read<'a>(
        observations: &'a BTreeMap<String, String>,
        name: &str,
    ) -> Result<&'a str, Box<dyn std::error::Error>> {
        observations
            .get(name)
            .map(String::as_str)
            .ok_or_else(|| format!("the probe wrote no `{name}`: {observations:?}").into())
    }

    /// THE WORLD CENSUS, taken against ONE probe process and asserted property
    /// by property — not sampled.
    ///
    /// The list is the worker declared-body executor's own spawn, read off the
    /// body loop of `DeclaredCommandAction::run`
    /// (`crates/aion-worker/src/shell/declared.rs`): argv spent whole
    /// with no shell interposed; standard input closed; the host environment
    /// cleared; `PATH` alone inherited at the host's value; the document's
    /// exports applied over it; an exported `PATH` winning (its own test
    /// below); and the declared working directory honoured. The eighth
    /// property of that spawn — process-group containment and transcript
    /// streaming — is the deliberate difference documented on
    /// [`ProcessRunner`], and is asserted nowhere here because the runner does
    /// not have it.
    #[test]
    fn a_fired_line_runs_in_the_world_the_worker_executor_establishes() -> TestResult {
        let directory = tempfile::tempdir()?;
        let workspace = directory.path().join("workspace");
        std::fs::create_dir(&workspace)?;
        let observations = directory.path().join("observed");
        let hostile = "hostile value; echo PWNED";
        let exports = vec![
            ("SEAT".to_owned(), "calliope".to_owned()),
            ("GREETING".to_owned(), "hello there".to_owned()),
        ];

        let runner = ProcessRunner::rooted(&workspace);
        let argv = probe_argv(hostile, &observations);
        let status = runner.run(&CommandLine {
            argv: &argv,
            env: &exports,
            cwd: None,
        })?;
        assert_eq!(status, 0, "the probe exits zero");

        let seen = observed(&observations)?;

        // 1. THE ARGV IS SPENT WHOLE. A value that would be two commands under
        //    a shell arrives as one argument, and the count proves nothing was
        //    re-split on the way.
        assert_eq!(read(&seen, "ARGC")?, "2");
        assert_eq!(read(&seen, "ARG1")?, format!("[{hostile}]"));

        // 2. STANDARD INPUT IS CLOSED: reading it yields end-of-file at once,
        //    not the operator's terminal. The positive control that this probe
        //    can see stdin bytes AT ALL is the next test.
        assert_eq!(read(&seen, "STDIN")?, "[]");

        // 3. THE HOST'S ENVIRONMENT IS CLEARED. Asserted two ways: no name
        //    beyond the declared ones and the shell's own three survives, and
        //    a variable this host actually holds is gone by name.
        let declared: Vec<&str> = vec!["PATH", "SEAT", "GREETING"];
        let leaked: Vec<&str> = seen
            .keys()
            .map(String::as_str)
            .filter(|name| {
                !declared.contains(name)
                    && !SHELL_OWN_NAMES.contains(name)
                    && !["CWD", "ARGC", "ARG1", "STDIN"].contains(name)
            })
            .collect();
        assert!(
            leaked.is_empty(),
            "the host's environment crossed into a fired line: {leaked:?}"
        );
        if let Some(present) = host_variable_other_than_path() {
            assert!(
                !seen.contains_key(&present),
                "the host's `{present}` leaked into a fired line"
            );
        } else {
            tracing::info!(
                "skipping the by-name leak arm: the host holds no variable besides PATH and the \
                 shell's own to prove non-inheritance with"
            );
        }

        // 4. `PATH` ALONE IS INHERITED, at the host's own value, so a bare
        //    program name still resolves.
        match std::env::var("PATH") {
            Ok(path) => assert_eq!(read(&seen, "PATH")?, path),
            Err(error) => tracing::info!(
                %error,
                "skipping the PATH arm: this host holds no readable PATH to inherit"
            ),
        }

        // 5. THE DOCUMENT'S EXPORTS REACH THE CHILD, values verbatim —
        //    including one carrying a space, which a world that re-split its
        //    bindings would lose.
        assert_eq!(read(&seen, "SEAT")?, "calliope");
        assert_eq!(read(&seen, "GREETING")?, "hello there");

        // 7. THE WORKING DIRECTORY is the one the executing side resolved:
        //    this run's root, since the line declares none.
        assert_eq!(
            Path::new(read(&seen, "CWD")?).canonicalize()?,
            workspace.canonicalize()?
        );
        Ok(())
    }

    /// THE POSITIVE CONTROL for the closed-standard-input arm above: the same
    /// probe, run with a pipe carrying bytes, reports them. Without this, an
    /// `STDIN=[]` would be equally consistent with a probe that cannot see
    /// standard input at all, and the arm would pass vacuously.
    #[test]
    fn the_stdin_probe_reports_bytes_when_a_pipe_carries_any() -> TestResult {
        let directory = tempfile::tempdir()?;
        let observations = directory.path().join("observed");
        let argv = probe_argv("unused", &observations);
        let (program, arguments) = argv.split_first().ok_or("the probe argv names a program")?;

        let mut child = std::process::Command::new(program)
            .args(arguments)
            .stdin(std::process::Stdio::piped())
            .spawn()?;
        child
            .stdin
            .take()
            .ok_or("the piped standard input must be available")?
            .write_all(b"LEAKED")?;
        let status = child.wait()?;
        assert!(status.success(), "the probe exits zero");

        assert_eq!(read(&observed(&observations)?, "STDIN")?, "[LEAKED]");
        Ok(())
    }

    /// An `export PATH := …` in the document wins over the inherited one,
    /// because the exports are applied after it. The same property the worker
    /// executor pins on its side, asserted here on a real child so the two
    /// cannot drift apart unnoticed.
    #[test]
    fn an_exported_path_wins_over_the_inherited_one() -> TestResult {
        let directory = tempfile::tempdir()?;
        let observations = directory.path().join("observed");
        let exports = vec![("PATH".to_owned(), "/usr/bin:/bin".to_owned())];

        let runner = ProcessRunner::rooted(directory.path());
        let argv = probe_argv("unused", &observations);
        let status = runner.run(&CommandLine {
            argv: &argv,
            env: &exports,
            cwd: None,
        })?;
        assert_eq!(status, 0);
        assert_eq!(read(&observed(&observations)?, "PATH")?, "/usr/bin:/bin");
        Ok(())
    }

    /// The declared working directory is resolved against THIS run's root, and
    /// the `{workspace_root}` placeholder is expanded by the executing side —
    /// which is here.
    #[test]
    fn a_declared_working_directory_is_resolved_against_this_runs_root() -> TestResult {
        let directory = tempfile::tempdir()?;
        let nested = directory.path().join("agents");
        std::fs::create_dir(&nested)?;
        let observations = directory.path().join("observed");
        let cwd = format!("{}/agents", aion_awl::WORKSPACE_ROOT_PLACEHOLDER);

        let runner = ProcessRunner::rooted(directory.path());
        let argv = probe_argv("unused", &observations);
        let status = runner.run(&CommandLine {
            argv: &argv,
            env: &[],
            cwd: Some(&cwd),
        })?;
        assert_eq!(status, 0);
        assert_eq!(
            Path::new(read(&observed(&observations)?, "CWD")?).canonicalize()?,
            nested.canonicalize()?
        );
        Ok(())
    }

    /// The status the line named comes back as the line's answer, and a line
    /// that named none — ended by a signal — is refused rather than given a
    /// number nobody chose.
    #[test]
    fn the_status_is_the_lines_own_and_a_signal_death_names_none() -> TestResult {
        let directory = tempfile::tempdir()?;
        let runner = ProcessRunner::rooted(directory.path());

        let exited = vec!["/bin/sh".to_owned(), "-c".to_owned(), "exit 7".to_owned()];
        assert_eq!(
            runner.run(&CommandLine {
                argv: &exited,
                env: &[],
                cwd: None,
            })?,
            7
        );

        let signalled = vec![
            "/bin/sh".to_owned(),
            "-c".to_owned(),
            "kill -TERM $$".to_owned(),
        ];
        let Err(refusal) = runner.run(&CommandLine {
            argv: &signalled,
            env: &[],
            cwd: None,
        }) else {
            return Err("a line ended by a signal names no status".into());
        };
        assert!(refusal.contains("signal"), "{refusal}");

        let empty: Vec<String> = Vec::new();
        let Err(refusal) = runner.run(&CommandLine {
            argv: &empty,
            env: &[],
            cwd: None,
        }) else {
            return Err("an empty argv names no program to run".into());
        };
        assert!(refusal.contains("no program to run"), "{refusal}");
        Ok(())
    }

    /// A variable this host actually holds, other than `PATH` and the ones a
    /// shell sets for itself — the specimen the leak arm looks for. Read from
    /// the host rather than set, because `std::env::set_var` is unsafe and the
    /// workspace denies unsafe outright.
    fn host_variable_other_than_path() -> Option<String> {
        std::env::vars_os()
            .filter_map(|(name, _)| name.into_string().ok())
            .find(|name| {
                name != "PATH"
                    && !name.is_empty()
                    && !name.contains('=')
                    && !SHELL_OWN_NAMES.contains(&name.as_str())
            })
    }

    /// The estate's own diagnostic shapes, read: a gate script's `GATE-RED:`
    /// line and a command-surface refusal both name their cause the same way.
    #[test]
    fn a_named_cause_is_read_out_of_the_shapes_this_estate_prints() {
        assert_eq!(
            named_cause(
                "GATE-RED: no changed file under crates/aion-awl/ — the census would have passed \
                 vacuously (named cause: deliverable_absent)"
            )
            .map(|(code, _)| code),
            Some("deliverable_absent".to_owned())
        );
        assert_eq!(
            named_cause("command `c` states nothing (observed: \"c\"; named cause: body_empty)")
                .map(|(code, _)| code),
            Some("body_empty".to_owned())
        );
    }

    /// An output naming no cause is NOTHING, never a nearest match.
    #[test]
    fn an_output_naming_no_cause_is_read_as_nothing() {
        assert_eq!(named_cause("everything is fine"), None);
        assert_eq!(named_cause(""), None);
        assert_eq!(named_cause("named cause: "), None);
        assert_eq!(named_cause("named cause: 404"), None);
    }

    /// The whole line rides as the bytes observed, so a receipt carries what
    /// the instrument actually printed.
    #[test]
    fn the_line_the_cause_stood_on_is_the_bytes_observed() {
        let Some((_, line)) = named_cause("  GATE-RED: x (named cause: tree_dirty)  ") else {
            unreachable!("the line names a cause");
        };
        assert_eq!(line, "GATE-RED: x (named cause: tree_dirty)");
    }
}