Add the plan2code-app desktop app, its CI workflows and docs

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-23 10:09:18 -07:00
1 parent 681c4a4b85
commit a5a3a81c5f
55 files changed
+13277

No files matched your search

@@ -0,0 +1,301 @@
//! The agent lifecycle against the fake agent in a real pseudo-terminal. Real
//! agents are never started here: `PLAN2CODE_APP_AGENT_BIN` points every agent
//! kind at the fake one.
use std::path::PathBuf;
use std::sync::mpsc::{channel, Receiver, RecvTimeoutError};
use std::sync::{Arc, Mutex, Once};
use std::time::{Duration, Instant};
use plan2code_app_lib::agent_manager::{AgentEvent, AgentManager, AgentSnapshot, AgentState};
use plan2code_app_lib::agents::{AgentKind, PermissionMode, AGENT_BIN_ENV};
mod common;
use common::process_alive;
const TIMEOUT: Duration = Duration::from_secs(20);
const READY: &str = "FAKE-AGENT ready";
struct Harness {
manager: AgentManager,
rx: Receiver<AgentEvent>,
/// Everything the agents printed, in order.
seen: String,
/// Every state change, in order.
states: Vec<AgentSnapshot>,
/// How many of `states` `wait_state` has already looked at.
cursor: usize,
}
impl Harness {
fn new() -> Harness {
static BIN: Once = Once::new();
BIN.call_once(|| std::env::set_var(AGENT_BIN_ENV, common::fake_agent()));
let (tx, rx) = channel();
let tx = Mutex::new(tx);
let sink = Arc::new(move |event| {
let _ = tx.lock().unwrap().send(event);
});
Harness { manager: AgentManager::new(PathBuf::from("."), sink), rx, seen: String::new(), states: Vec::new(), cursor: 0 }
}
fn take(&mut self, event: AgentEvent) {
match event {
AgentEvent::Output(bytes) => {
let text = String::from_utf8_lossy(&bytes).into_owned();
// Windows' pseudo-terminal asks where the cursor is (ESC [ 6 n)
// and holds the output until told, as xterm does on its own.
for _ in text.matches("[6n") {
self.manager.input(b"\x1b[1;1R").unwrap();
}
self.seen.push_str(&text);
}
AgentEvent::State(snapshot) => self.states.push(snapshot),
}
}
/// Handle events for `how_long`, answering the terminal's questions.
fn pump_for(&mut self, how_long: Duration) {
let deadline = Instant::now() + how_long;
loop {
let left = deadline.saturating_duration_since(Instant::now());
match self.rx.recv_timeout(left) {
Ok(event) => self.take(event),
Err(_) => return,
}
}
}
fn wait_for_output(&mut self, needle: &str, times: usize) {
let deadline = Instant::now() + TIMEOUT;
while self.seen.matches(needle).count() < times {
let left = deadline.saturating_duration_since(Instant::now());
match self.rx.recv_timeout(left) {
Ok(event) => self.take(event),
Err(RecvTimeoutError::Timeout) | Err(RecvTimeoutError::Disconnected) => {
panic!("never saw {needle:?} {times} time(s); got {:?}", self.seen)
}
}
}
}
/// The next state change (after the last one this returned) that matches.
fn wait_state(&mut self, what: &str, matches: impl Fn(&AgentSnapshot) -> bool) -> AgentSnapshot {
let deadline = Instant::now() + TIMEOUT;
loop {
while self.cursor < self.states.len() {
let snapshot = self.states[self.cursor].clone();
self.cursor += 1;
if matches(&snapshot) {
return snapshot;
}
}
let left = deadline.saturating_duration_since(Instant::now());
match self.rx.recv_timeout(left) {
Ok(event) => self.take(event),
Err(_) => panic!("never saw the state {what}; got {:?}", self.states),
}
}
}
fn start_and_wait_ready(&mut self) {
self.manager.start(AgentKind::Claude, None, None, PermissionMode::Bypass, None).expect("start the fake agent");
self.wait_for_output(READY, 1);
}
fn type_line(&self, line: &str) {
self.manager.input(format!("{line}\r").as_bytes()).unwrap();
}
}
fn is_running(snapshot: &AgentSnapshot) -> bool {
snapshot.state == AgentState::Running
}
#[test]
fn a_second_start_while_running_is_refused() {
let mut h = Harness::new();
h.start_and_wait_ready();
let generation = h.manager.snapshot().generation;
let refused = h.manager.start(AgentKind::Devin, None, None, PermissionMode::Bypass, None);
assert!(refused.is_err(), "a second start must be refused");
let after = h.manager.snapshot();
assert_eq!(after.state, AgentState::Running);
assert_eq!(after.generation, generation, "the running agent was replaced");
h.manager.stop();
}
#[test]
fn restart_keeps_the_previous_agent_kind_mode_model_and_effort() {
let mut h = Harness::new();
h.manager
.start(AgentKind::Codex, Some("gpt-5".to_string()), Some("high".to_string()), PermissionMode::Checked, None)
.expect("start the fake agent");
h.wait_for_output(READY, 1);
let before = h.manager.snapshot();
assert_eq!(before.kind, Some(AgentKind::Codex));
assert_eq!(before.mode, Some(PermissionMode::Checked));
assert_eq!(h.manager.model_and_effort(), (Some("gpt-5".to_string()), Some("high".to_string())));
h.manager.restart().unwrap();
h.wait_for_output(READY, 2);
let after = h.manager.snapshot();
assert_eq!(after.kind, Some(AgentKind::Codex), "restart must keep the same agent");
assert_eq!(after.mode, Some(PermissionMode::Checked), "restart must keep the same permission mode");
assert_eq!(
h.manager.model_and_effort(),
(Some("gpt-5".to_string()), Some("high".to_string())),
"restart must keep the same model and effort"
);
h.manager.stop();
}
#[test]
fn restart_between_steps_replaces_the_agent_at_once() {
let mut h = Harness::new();
h.start_and_wait_ready();
let generation = h.manager.snapshot().generation;
h.manager.restart().unwrap();
let now = h.manager.snapshot();
assert_eq!(now.state, AgentState::Running);
assert!(now.generation > generation, "a fresh agent was not started");
h.wait_for_output(READY, 2);
h.manager.stop();
}
#[test]
fn restart_mid_step_kills_the_step_at_once_instead_of_waiting_for_it() {
let mut h = Harness::new();
h.start_and_wait_ready();
h.type_line("STEP 30");
h.wait_for_output("working 1/30", 1);
let started = Instant::now();
h.manager.restart().unwrap();
// Running again straight away: no wait for the step to finish.
h.wait_state("Running again", is_running);
h.wait_for_output(READY, 2);
assert!(started.elapsed() < Duration::from_secs(5), "restart must not wait on the step; took {:?}", started.elapsed());
assert!(!h.seen.contains("STEP DONE"), "the step should have been cut short, not finished");
h.manager.stop();
}
#[test]
fn an_agent_that_exits_by_itself_ends_with_its_code_and_nothing_restarts() {
let mut h = Harness::new();
h.start_and_wait_ready();
h.type_line("EXIT 7");
let ended = h.wait_state("Ended", |s| matches!(s.state, AgentState::Ended { .. }));
match &ended.state {
AgentState::Ended { reason } => assert!(reason.contains('7'), "reason was {reason:?}"),
other => panic!("expected Ended, got {other:?}"),
}
// Nothing starts without a press.
h.pump_for(Duration::from_millis(1500));
assert!(matches!(h.manager.snapshot().state, AgentState::Ended { .. }));
assert_eq!(h.seen.matches(READY).count(), 1, "an agent started by itself");
assert!(!h.manager.is_active());
// A press of Restart starts a fresh one on the same brief.
h.manager.restart().unwrap();
h.wait_for_output(READY, 2);
assert_eq!(h.manager.snapshot().state, AgentState::Running);
h.manager.stop();
}
#[test]
fn quitting_with_a_running_agent_stops_it() {
let mut h = Harness::new();
h.start_and_wait_ready();
assert!(h.manager.is_active());
h.type_line("PID");
h.wait_for_output("PID ", 1);
let pid = h.seen.rsplit("PID ").next().unwrap().trim_start().split(|c: char| !c.is_ascii_digit()).next().unwrap().parse::<u32>().expect("the agent's pid");
assert!(process_alive(pid), "the agent should be running before the stop");
h.manager.stop();
assert!(!process_alive(pid), "the agent's process outlived stop()");
assert_eq!(h.manager.snapshot().state, AgentState::Idle);
assert!(!h.manager.is_active());
// The stopped agent does not come back or print again.
let before = h.seen.len();
h.pump_for(Duration::from_millis(1000));
assert!(!h.seen[before..].contains(READY), "an agent started after the stop");
assert!(h.manager.restart().is_err(), "there is nothing left to restart");
}
#[test]
fn the_replay_buffer_holds_recent_output_and_clears_on_a_fresh_agent() {
let mut h = Harness::new();
h.start_and_wait_ready();
let replay = String::from_utf8_lossy(&h.manager.replay()).into_owned();
assert!(replay.contains(READY), "replay should hold what was just printed; got {replay:?}");
h.manager.restart().unwrap();
h.wait_for_output(READY, 2);
let replay = String::from_utf8_lossy(&h.manager.replay()).into_owned();
assert_eq!(replay.matches(READY).count(), 1, "a fresh agent's replay must not carry the old one's output");
h.manager.stop();
}
#[test]
fn a_restart_runs_the_brief_hook_and_the_bar_gets_its_note() {
let mut h = Harness::new();
let runs = Arc::new(Mutex::new(0));
let counter = Arc::clone(&runs);
h.manager.set_before_fresh(Arc::new(move || {
*counter.lock().unwrap() += 1;
Some("Brief ready on the dashboard".to_string())
}));
h.start_and_wait_ready();
assert_eq!(*runs.lock().unwrap(), 0, "a first start leaves no brief");
assert_eq!(h.manager.snapshot().brief_note, None);
h.manager.restart().unwrap();
assert_eq!(*runs.lock().unwrap(), 1, "the restart did not run the brief once");
assert_eq!(h.manager.snapshot().brief_note.as_deref(), Some("Brief ready on the dashboard"));
h.manager.stop();
}
#[test]
fn the_agent_gets_the_in_app_signal_and_a_restart_keeps_it() {
let mut h = Harness::new();
h.manager.set_env(vec![
("PLAN2CODE_IN_APP".to_string(), "1".to_string()),
("PLAN2CODE_CONSOLE_SID".to_string(), "sid-window-a".to_string()),
]);
h.start_and_wait_ready();
h.type_line("ENV PLAN2CODE_IN_APP");
h.wait_for_output("ENV PLAN2CODE_IN_APP=1", 1);
h.type_line("ENV PLAN2CODE_CONSOLE_SID");
h.wait_for_output("ENV PLAN2CODE_CONSOLE_SID=sid-window-a", 1);
// The signal changes with the console; a Restart starts on the newest.
h.manager.set_env(vec![("PLAN2CODE_CONSOLE_SID".to_string(), "sid-window-b".to_string())]);
h.manager.restart().unwrap();
h.wait_for_output(READY, 2);
h.type_line("ENV PLAN2CODE_CONSOLE_SID");
h.wait_for_output("ENV PLAN2CODE_CONSOLE_SID=sid-window-b", 1);
h.type_line("ENV PLAN2CODE_IN_APP");
h.wait_for_output("ENV PLAN2CODE_IN_APP=\r", 1);
h.manager.stop();
}
#[test]
fn an_agent_with_no_signal_set_gets_none() {
let mut h = Harness::new();
h.start_and_wait_ready();
h.type_line("ENV PLAN2CODE_IN_APP");
h.wait_for_output("ENV PLAN2CODE_IN_APP=", 1);
assert!(!h.seen.contains("ENV PLAN2CODE_IN_APP=1"));
h.manager.stop();
}
@@ -0,0 +1,38 @@
//! Shared by the integration tests: where the fake agent program is, and
//! whether a process id is still alive.
use std::path::PathBuf;
use std::process::Command;
use std::sync::Once;
/// Is a process with this id still there? Asks the operating system.
#[allow(dead_code)]
pub fn process_alive(pid: u32) -> bool {
if cfg!(windows) {
let out = Command::new("tasklist").args(["/FI", &format!("PID eq {pid}"), "/NH"]).output().unwrap();
String::from_utf8_lossy(&out.stdout).split_whitespace().any(|word| word == pid.to_string())
} else {
Command::new("kill").args(["-0", &pid.to_string()]).status().map(|s| s.success()).unwrap_or(false)
}
}
pub fn fake_agent() -> PathBuf {
// `cargo test` does not build another package's program, so build it once.
static BUILD: Once = Once::new();
BUILD.call_once(|| {
let status = Command::new(env!("CARGO"))
.args(["build", "-p", "fake-agent"])
.status()
.expect("run cargo");
assert!(status.success(), "could not build the fake agent");
});
// The test binary is in target/<profile>/deps; the fake agent is one up.
let exe = std::env::current_exe().unwrap();
let path = exe
.parent()
.and_then(|deps| deps.parent())
.unwrap()
.join(format!("fake-agent{}", std::env::consts::EXE_SUFFIX));
assert!(path.exists(), "{} is missing after building the fake agent", path.display());
path
}
@@ -0,0 +1,100 @@
//! The supervisor against the real console: a temp project, no agent, no
//! Tauri. `PLAN2CODE_CONSOLE_DIR` points the lookup at the repo's own console
//! source and `PLAN2CODE_CONSOLE_HOME` keeps the sessions out of the user's
//! real console folder. Skipped entirely when node is not on PATH.
use std::path::PathBuf;
use std::process::Command;
use std::time::{Duration, Instant};
use plan2code_app_lib::console_supervisor::{app_origin, ConsoleSupervisor};
fn have_node() -> bool {
Command::new("node")
.arg("--version")
.output()
.map(|o| o.status.success())
.unwrap_or(false)
}
fn repo_console_dir() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../src/web-console")
}
fn temp_dir(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("p2c-sup-{name}-{}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
dir
}
fn setup() -> Option<PathBuf> {
if !have_node() {
eprintln!("skipping: node is not on PATH");
return None;
}
let console = repo_console_dir();
assert!(console.join("console.mjs").is_file(), "console source missing at {}", console.display());
std::env::set_var("PLAN2CODE_CONSOLE_DIR", &console);
std::env::set_var("PLAN2CODE_CONSOLE_HOME", temp_dir("home"));
std::env::set_var("PLAN2CODE_NO_BROWSER", "1");
Some(temp_dir("project"))
}
fn kill_pid(pid: u32) {
#[cfg(windows)]
let _ = Command::new("taskkill")
.args(["/PID", &pid.to_string(), "/F"])
.output();
#[cfg(not(windows))]
let _ = Command::new("kill").args(["-9", &pid.to_string()]).output();
}
/// The detached server can take a beat to bind or die; ask until `want` holds.
fn until_health(sup: &ConsoleSupervisor, want: bool) -> bool {
let deadline = Instant::now() + Duration::from_secs(15);
while Instant::now() < deadline {
if sup.health() == want {
return true;
}
std::thread::sleep(Duration::from_millis(200));
}
false
}
#[test]
fn starts_answers_and_stops() {
let Some(project) = setup() else { return };
let mut sup = ConsoleSupervisor::start(project, app_origin().to_string()).expect("start");
assert!(!sup.session().sid.is_empty());
assert!(sup.session().url.starts_with("http://127.0.0.1:"));
assert!(sup.session().pid > 0);
assert!(until_health(&sup, true), "the console URL never answered");
sup.stop().expect("stop");
assert!(until_health(&sup, false), "the console still answered after stop()");
}
#[test]
fn a_killed_console_is_dead_and_restarts() {
let Some(project) = setup() else { return };
let mut sup = ConsoleSupervisor::start(project, app_origin().to_string()).expect("start");
assert!(until_health(&sup, true), "the console URL never answered");
let first_sid = sup.session().sid.clone();
kill_pid(sup.session().pid);
assert!(until_health(&sup, false), "a killed console still looked alive");
assert!(sup.restart_if_dead().expect("restart"), "restart_if_dead did nothing");
assert_eq!(sup.session().sid, first_sid, "a dead console comes back on the same session, so its page and place survive");
assert!(until_health(&sup, true), "the restarted console never answered");
sup.stop().expect("stop");
}
#[test]
fn a_live_console_is_not_restarted() {
let Some(project) = setup() else { return };
let mut sup = ConsoleSupervisor::start(project, app_origin().to_string()).expect("start");
assert!(until_health(&sup, true), "the console URL never answered");
assert!(!sup.restart_if_dead().expect("restart check"));
sup.stop().expect("stop");
}
+154
View File
@@ -0,0 +1,154 @@
//! The PTY host against the fake agent in a real pseudo-terminal. Real agents
//! are never started here.
use std::sync::mpsc::{channel, Receiver, RecvTimeoutError};
use std::time::{Duration, Instant};
use plan2code_app_lib::pty_host::{PtyHost, StartOptions};
mod common;
use common::{fake_agent, process_alive};
fn start_fake() -> (PtyHost, Receiver<Vec<u8>>) {
let (tx, rx) = channel();
let host = PtyHost::start(
StartOptions {
program: fake_agent().to_string_lossy().into_owned(),
args: vec![],
env: vec![],
cwd: None,
cols: 80,
rows: 24,
},
move |bytes| {
let _ = tx.send(bytes);
},
)
.expect("start the fake agent");
(host, rx)
}
/// Collect output until `needle` appears; panic with what arrived if it does not.
/// Windows' pseudo-terminal asks where the cursor is (ESC [ 6 n) and holds the
/// output until it is told, as a real terminal such as xterm does on its own.
fn wait_for(host: &PtyHost, rx: &Receiver<Vec<u8>>, seen: &mut String, needle: &str) {
let deadline = Instant::now() + Duration::from_secs(20);
while !seen.contains(needle) {
let left = deadline.saturating_duration_since(Instant::now());
match rx.recv_timeout(left) {
Ok(bytes) => {
let text = String::from_utf8_lossy(&bytes);
for _ in text.matches("") {
host.write(b"").unwrap();
}
seen.push_str(&text);
}
Err(RecvTimeoutError::Timeout) | Err(RecvTimeoutError::Disconnected) => {
panic!("never saw {needle:?}; got {seen:?}")
}
}
}
}
#[test]
fn banner_arrives() {
let (host, rx) = start_fake();
let mut seen = String::new();
wait_for(&host, &rx, &mut seen, "FAKE-AGENT ready");
host.kill().unwrap();
}
#[test]
fn typed_line_is_echoed() {
let (host, rx) = start_fake();
let mut seen = String::new();
wait_for(&host, &rx, &mut seen, "FAKE-AGENT ready");
host.write(b"hello there\r").unwrap();
wait_for(&host, &rx, &mut seen, "echo: hello there");
host.kill().unwrap();
}
#[test]
fn resize_reaches_the_child() {
let (host, rx) = start_fake();
let mut seen = String::new();
wait_for(&host, &rx, &mut seen, "SIZE 80x24");
host.resize(100, 30).unwrap();
wait_for(&host, &rx, &mut seen, "SIZE 100x30");
host.kill().unwrap();
}
#[test]
fn exit_code_is_returned() {
let (host, rx) = start_fake();
let mut seen = String::new();
wait_for(&host, &rx, &mut seen, "FAKE-AGENT ready");
host.write(b"EXIT 3\r").unwrap();
assert_eq!(host.wait().unwrap(), 3);
}
#[test]
fn kill_ends_a_running_step() {
let (host, rx) = start_fake();
let mut seen = String::new();
wait_for(&host, &rx, &mut seen, "FAKE-AGENT ready");
host.write(b"STEP 30\r").unwrap();
wait_for(&host, &rx, &mut seen, "working 1/30");
let started = Instant::now();
host.kill().unwrap();
host.wait().unwrap();
assert!(started.elapsed() < Duration::from_secs(10), "kill took too long");
}
/// An npm `.cmd` shim: `cmd.exe` is the directly spawned process, the real
/// program (here, the fake agent) its grandchild. `kill` must end both, not
/// just `cmd.exe` (Task 9.8).
#[cfg(windows)]
#[test]
fn kill_ends_a_cmd_wrapped_grandchild_too() {
use plan2code_app_lib::agents::windows_command;
use std::fs;
let dir = std::env::temp_dir().join(format!("plan2code-pty-cmdshim-{}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
let shim = dir.join("shim.cmd");
fs::write(&shim, format!("@echo off\r\n\"{}\" %*\r\n", fake_agent().display())).unwrap();
let (program, args) = windows_command("shim", vec![], &dir.to_string_lossy());
let path = format!("{};{}", dir.to_string_lossy(), std::env::var("PATH").unwrap_or_default());
let (tx, rx) = channel();
let host = PtyHost::start(
// `cmd /c shim.cmd` is a bare name: like a real npm shim, cmd.exe
// only finds it on PATH, never by the current directory alone.
StartOptions { program, args, env: vec![("PATH".to_string(), path)], cwd: None, cols: 80, rows: 24 },
move |bytes| {
let _ = tx.send(bytes);
},
)
.expect("start the cmd-wrapped fake agent");
let mut seen = String::new();
wait_for(&host, &rx, &mut seen, "FAKE-AGENT ready");
host.write(b"PID\r").unwrap();
wait_for(&host, &rx, &mut seen, "PID ");
let pid: u32 = seen
.rsplit("PID ")
.next()
.unwrap()
.trim_start()
.split(|c: char| !c.is_ascii_digit())
.next()
.unwrap()
.parse()
.expect("the grandchild's pid");
assert!(process_alive(pid), "the grandchild should be running before kill");
host.kill().unwrap();
let deadline = Instant::now() + Duration::from_secs(10);
while process_alive(pid) && Instant::now() < deadline {
std::thread::sleep(Duration::from_millis(50));
}
assert!(!process_alive(pid), "the grandchild outlived kill()");
let _ = fs::remove_dir_all(&dir);
}