bevy-agent-feedback-plugin 0.5.0

Let AI coding agents see and control your Bevy app: input injection, labeled screenshots, and frame-synced feedback over a JSON-lines TCP protocol.
Documentation
use super::*;
use std::time::{SystemTime, UNIX_EPOCH};

const RUN_PROBE_SCENARIO: &str = "BEVY_FEEDBACK_TEST_RUN_SCENARIO";
const RUN_PROBE_ARTIFACTS: &str = "BEVY_FEEDBACK_TEST_RUN_ARTIFACTS";

#[test]
fn spawn_error_hints_when_executable_contains_whitespace() {
    let error = spawn_error(
        "--game",
        &["cargo run --features agent".into()],
        std::io::Error::new(std::io::ErrorKind::NotFound, "missing"),
    );

    assert!(
        error.contains("spawn --game [\"cargo run --features agent\"]: missing"),
        "{error}"
    );
    assert!(error.contains("pass each argv word separately"), "{error}");
}

#[test]
fn copies_only_png_captures_sorted() {
    let root = temp_root("copy-captures");
    let from = root.join("from");
    let to = root.join("to");
    fs::create_dir_all(&from).expect("from dir");
    fs::write(from.join("capture-000002-b.png"), b"b").expect("capture b");
    fs::write(from.join("capture-000001-a.png"), b"a").expect("capture a");
    fs::write(from.join("notes.txt"), b"skip").expect("notes");

    let copied = copy_captures(&from, &to).expect("copy captures");

    assert_eq!(
        copied,
        vec![
            to.join("capture-000001-a.png"),
            to.join("capture-000002-b.png")
        ]
    );
    assert_eq!(fs::read(to.join("capture-000001-a.png")).expect("a"), b"a");
    assert!(!to.join("notes.txt").exists());
    let _ = fs::remove_dir_all(root);
}

#[cfg(unix)]
#[test]
fn prepare_failures_are_typed_and_always_write_run_summary() {
    for (name, script, timeout, code) in [
        (
            "nonzero",
            "exit 7",
            Duration::from_secs(1),
            "prepare_nonzero_exit",
        ),
        (
            "timeout",
            "exec sleep 2",
            Duration::from_millis(50),
            "prepare_timeout",
        ),
    ] {
        let root = temp_root(&format!("prepare-{name}"));
        let artifacts = root.join("artifacts");
        let args = RunArgs {
            protocol_file: root.join("protocol.json"),
            artifacts: artifacts.clone(),
            required_window_size: None,
            prepare_timeout: timeout,
            protocol_timeout: Duration::from_secs(1),
            shutdown_timeout: Duration::from_millis(50),
            driver_timeout: Duration::from_secs(1),
            game_cwd: None,
            prepare: Some(vec!["sh".into(), "-c".into(), script.into()]),
            game: vec!["game-must-not-start".into()],
            driver: None,
            used_legacy_ready_timeout: false,
        };

        let error = run(args).expect_err("prepare must fail");
        let summary: Value = serde_json::from_slice(
            &fs::read(artifacts.join("run-summary.json")).expect("run summary"),
        )
        .expect("summary JSON");

        assert_eq!(summary["schema_version"], 1);
        assert_eq!(summary["phase"], "prepare");
        assert_eq!(summary["result"]["code"], code);
        assert_eq!(summary["result"]["success"], false);
        assert!(error.starts_with(&format!("[{code}] ")), "{error}");
        assert!(
            error.contains(&format!(
                "prepare log: {}",
                artifacts.join("prepare.log").display()
            )),
            "{error}"
        );
        assert!(artifacts.join("prepare.log").exists());
        assert!(!artifacts.join("game.log").exists());
        let _ = fs::remove_dir_all(root);
    }
}

#[cfg(unix)]
#[test]
fn live_protocol_timeout_and_game_cwd_are_recorded() {
    let root = temp_root("live-timeout");
    let artifacts = root.join("artifacts");
    let game_cwd = root.join("game-cwd");
    fs::create_dir_all(&game_cwd).expect("game cwd");
    let marker = game_cwd.join("cwd.txt");
    let script = format!("pwd > '{}'; exec sleep 2", marker.display());
    let args = RunArgs {
        protocol_file: root.join("protocol.json"),
        artifacts: artifacts.clone(),
        required_window_size: None,
        prepare_timeout: Duration::from_secs(1),
        protocol_timeout: Duration::from_millis(50),
        shutdown_timeout: Duration::from_millis(50),
        driver_timeout: Duration::from_secs(1),
        game_cwd: Some(game_cwd.clone()),
        prepare: None,
        game: vec!["sh".into(), "-c".into(), script],
        driver: None,
        used_legacy_ready_timeout: false,
    };

    let error = run(args).expect_err("live unready game must time out");
    let summary: Value =
        serde_json::from_slice(&fs::read(artifacts.join("run-summary.json")).expect("run summary"))
            .expect("summary JSON");

    assert!(error.contains("protocol_timeout"), "{error}");
    assert_eq!(summary["result"]["code"], "protocol_timeout");
    assert_eq!(summary["phase"], "protocol_startup");
    assert_eq!(
        summary["launch"]["game_cwd"],
        game_cwd.to_string_lossy().as_ref()
    );
    assert_eq!(
        fs::read_to_string(marker).expect("cwd marker").trim(),
        game_cwd.to_string_lossy()
    );
    assert_eq!(summary["teardown"]["forced_termination"], true);
    let _ = fs::remove_dir_all(root);
}

#[test]
fn both_cli_failure_paths_write_focused_failure_artifacts() {
    let cases = [
        (
            "readiness",
            "game exited before protocol was ready",
            r#"{"phase":"startup","reason":"protocol-missing"}"#,
            false,
        ),
        (
            "dead-game",
            "game exited with status",
            "semantic evidence: unavailable",
            true,
        ),
    ];

    for (scenario, original_failure, diagnostic, copies_protocol) in cases {
        let root = temp_root(scenario);
        let artifacts = root.join("artifacts");
        let output = Command::new(std::env::current_exe().expect("current test executable"))
            .args([
                "--ignored",
                "--exact",
                "tests::cli_run_failure_probe",
                "--nocapture",
            ])
            .env(RUN_PROBE_SCENARIO, scenario)
            .env(RUN_PROBE_ARTIFACTS, &artifacts)
            .output()
            .expect("run CLI failure probe");
        assert!(
            output.status.success(),
            "{scenario} probe failed\nstdout:\n{}\nstderr:\n{}",
            String::from_utf8_lossy(&output.stdout),
            String::from_utf8_lossy(&output.stderr)
        );
        if scenario == "dead-game" {
            let stdout = String::from_utf8_lossy(&output.stdout);
            assert!(
                stdout.contains(
                    "protocol ready != game ready; use semantic readiness for animated games or strict stability for static scenes before capturing"
                ),
                "{stdout}"
            );
            assert!(
                !stdout.contains("wait for a stable frame before capturing"),
                "{stdout}"
            );
        }
        let summary =
            fs::read_to_string(artifacts.join("failure-summary.txt")).expect("failure summary");
        let run_summary: Value = serde_json::from_slice(
            &fs::read(artifacts.join("run-summary.json")).expect("run summary"),
        )
        .expect("run summary JSON");

        assert_eq!(
            run_summary["result"]["code"],
            if scenario == "readiness" {
                "protocol_early_exit"
            } else {
                "game_nonzero_exit"
            }
        );
        let code = if scenario == "readiness" {
            "protocol_early_exit"
        } else {
            "game_nonzero_exit"
        };
        assert!(
            summary.starts_with(&format!("[{code}] ")),
            "{scenario}: {summary}"
        );
        assert!(summary.contains(original_failure), "{scenario}: {summary}");
        assert!(summary.contains(diagnostic), "{scenario}: {summary}");
        assert!(
            summary.contains("teardown: inputs="),
            "{scenario}: {summary}"
        );
        assert!(
            summary.contains(&format!(
                "game log: {}",
                artifacts.join("game.log").display()
            )),
            "{scenario}: {summary}"
        );
        assert_eq!(
            artifacts.join("protocol.json").exists(),
            copies_protocol,
            "{scenario}: protocol artifact"
        );
        let _ = fs::remove_dir_all(root);
    }
}

#[test]
#[ignore = "subprocess harness for both_cli_failure_paths_write_focused_failure_artifacts"]
fn cli_run_failure_probe() {
    let Some(scenario) = std::env::var_os(RUN_PROBE_SCENARIO) else {
        return;
    };
    let artifacts =
        PathBuf::from(std::env::var_os(RUN_PROBE_ARTIFACTS).expect("probe artifacts directory"));
    let executable = std::env::current_exe().expect("current test executable");
    let game = vec![
        executable.to_string_lossy().into_owned(),
        "--ignored".to_string(),
        "--exact".to_string(),
        "tests::cli_fake_game_probe".to_string(),
        "--nocapture".to_string(),
    ];
    let args = RunArgs {
        protocol_file: artifacts.join("live-protocol.json"),
        artifacts,
        required_window_size: None,
        prepare_timeout: Duration::from_secs(3),
        protocol_timeout: Duration::from_secs(3),
        shutdown_timeout: Duration::from_millis(100),
        driver_timeout: Duration::from_secs(1),
        game_cwd: None,
        prepare: None,
        game,
        driver: None,
        used_legacy_ready_timeout: false,
    };

    let error = run(args).expect_err("probe run should fail");

    match scenario.to_str().expect("UTF-8 scenario") {
        "readiness" => assert!(error.contains("game exited before protocol was ready")),
        "dead-game" => assert!(error.contains("game exited with status")),
        other => panic!("unknown run probe scenario {other}"),
    }
}

#[test]
#[ignore = "fake game subprocess for cli_run_failure_probe"]
fn cli_fake_game_probe() {
    let scenario = std::env::var(RUN_PROBE_SCENARIO).expect("probe scenario");
    let transcript =
        PathBuf::from(std::env::var_os("BEVY_FEEDBACK_TRANSCRIPT").expect("transcript path"));
    if scenario == "readiness" {
        write_envelopes(
            &transcript,
            &[serde_json::json!({
                "response": {
                    "error": {
                        "context": {
                            "phase": "startup",
                            "reason": "protocol-missing"
                        }
                    }
                }
            })],
        );
        std::process::exit(17);
    }

    assert_eq!(scenario, "dead-game");
    let protocol_file =
        PathBuf::from(std::env::var_os("BEVY_FEEDBACK_PROTOCOL").expect("protocol path"));
    let capture_dir =
        PathBuf::from(std::env::var_os("BEVY_FEEDBACK_CAPTURE_DIR").expect("capture path"));
    let heartbeat = protocol_file.with_extension("heartbeat");
    let listener = std::net::TcpListener::bind(("127.0.0.1", 0)).expect("bind fake game");
    listener
        .set_nonblocking(true)
        .expect("nonblocking fake game");
    let now_ms = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .expect("system clock before unix epoch")
        .as_millis();
    fs::write(&heartbeat, now_ms.to_string()).expect("heartbeat");
    fs::write(
        &protocol_file,
        serde_json::to_vec(&serde_json::json!({
            "protocol": "bevy-agent-feedback/0.5",
            "session_id": "dead-game-probe",
            "pid": std::process::id(),
            "heartbeat_file": heartbeat,
            "stale_after_ms": 5_000,
            "socket_addr": listener.local_addr().expect("listener address"),
            "capture_dir": capture_dir,
            "deterministic_time": false,
            "max_wait_frames": 60,
            "max_time_advance_steps": 60,
            "max_time_advance_seconds": 1.0
        }))
        .expect("protocol JSON"),
    )
    .expect("protocol file");

    for _ in 0..300 {
        match listener.accept() {
            Ok((_stream, _address)) => std::process::exit(9),
            Err(error) if error.kind() == io::ErrorKind::WouldBlock => {
                thread::sleep(Duration::from_millis(10));
            }
            Err(error) => panic!("fake game accept failed: {error}"),
        }
    }
    panic!("CLI did not connect to fake game within three seconds");
}

fn write_envelopes(path: &Path, envelopes: &[Value]) {
    let mut bytes = Vec::new();
    for envelope in envelopes {
        serde_json::to_writer(&mut bytes, envelope).expect("serialize transcript envelope");
        bytes.push(b'\n');
    }
    fs::write(path, bytes).expect("write transcript");
}

fn temp_root(name: &str) -> PathBuf {
    let nonce = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .expect("system clock before unix epoch")
        .as_nanos();
    std::env::temp_dir().join(format!(
        "bevy-feedback-cli-{name}-{}-{nonce}",
        std::process::id()
    ))
}