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

+4624
View File
File diff suppressed because it is too large. Load diff
+3
View File
@@ -0,0 +1,3 @@
[workspace]
resolver = "2"
members = ["src-tauri", "fake-agent"]
+34
View File
@@ -0,0 +1,34 @@
# plan2code-app
The Plan2Code desktop app (v3.0): one window with the dashboard, a terminal panel for the agent, and a Restart button. Built with Tauri 2 (Rust and a web view).
The app is optional. The Node web console and the skills never depend on it, so running `/plan2code` inside an agent with no app works exactly as before.
## Layout
| Path | What it is |
|---|---|
| `src-tauri/` | The Rust app |
| `ui/` | The app page (plain HTML, CSS and JavaScript, no framework) |
| `fake-agent/` | A stand-in agent program the tests run in a real pseudo-terminal |
| `package.json` | The app's own npm packages (xterm, the Tauri CLI). Separate from the repo root so the root and the console stay dependency-free |
## Build and run
Needs the Rust toolchain pinned in `rust-toolchain.toml`, Node 18+, and the Tauri 2 system packages for your system (WebView2 on Windows, WebKitGTK on Linux).
```
cd plan2code-app
npm install
npm run dev # run the app
npm run build # build the installable bundle
```
## Tests
```
cd plan2code-app
cargo test --workspace
```
Real Claude, Devin and Codex are never started by a test. The real window and terminal panel are checked by hand before each release.
+105
View File
@@ -0,0 +1,105 @@
# Release checklist
Run this before every release of the desktop app, on each system the release builds for: Windows
x64, macOS Apple silicon and Linux x64. Automated tests cover the logic and never start a real
window, a real terminal panel, or a real Claude, Devin or Codex, so everything here is by hand.
Work from the pre-release build: publish a GitHub pre-release so `release-app.yml` attaches the files,
then install from it. Tick each box per system and note anything that is a rough edge rather than a
failure.
## Before you start
- [ ] `node scripts/check-versions.mjs --tag v<version>` passes (version.json, package.json,
CHANGELOG.md and the app's tauri.conf.json, package.json and Cargo.toml all agree)
- [ ] `npm test` passes at the repo root, with the app absent
- [ ] `cargo test --workspace` passes in `plan2code-app/`, and the `app` workflow is green on all
three systems
- [ ] The pre-release has one `plan2code-app-<version>-<os>-<arch>` file per system and a
`plan2code-app-<version>-SHA256SUMS.txt`
## Install and launch (each system)
- [ ] Run the installer from the pre-release: it offers the app, downloads it, verifies the checksum
and places it in `~/.plan2code/app/`
- [ ] A deliberately corrupted download is rejected with the checksum message, and the skills and
the `plan2code` command are still installed
- [ ] `plan2code` in a project asks for the agent and model, then opens the app on that folder
- [ ] The agent and model picked in the launcher are the ones the app starts at once, with no
launch card or checklist shown first, and Restart keeps them
- [ ] `plan2code --classic` runs the agent in the terminal with the app installed
- [ ] Linux only: with `DISPLAY` and `WAYLAND_DISPLAY` unset, `plan2code` runs the terminal flow
- [ ] The desktop shortcut opens the folder picker and then the app
- [ ] macOS: the first start is stopped by Gatekeeper, **Open Anyway** in System Settings (Privacy &
Security) lets it through, and `docs/desktop-app.md` describes what you saw
- [ ] macOS and Linux: start the app from the Dock, Finder or a `.desktop` file (not a terminal) on
a machine where Node is only on PATH through nvm, Homebrew or Volta: the first-run checklist
still finds Node and the installed CLIs, and the console and an agent still start
- [ ] Windows: SmartScreen's **More info**, then **Run anyway**, lets it through, and
`docs/desktop-app.md` describes what you saw
- [ ] `plan2code update` updates the skills, the command and the app, including while the app is
running (Windows replaces the file by renaming the old one aside)
## The window (each system)
- [ ] The dashboard shows in the frame and the terminal panel is visible beneath it
- [ ] Resizing the window keeps both usable; dragging the handle resizes the panel
- [ ] The bar shows the project folder and the context meter; the permission note appears only
while an agent started with checks off is running, never otherwise
- [ ] The first run (no `firstRunDone` saved yet) shows the checklist (Node, an agent CLI, the
project folder, the skills version) before the launch card; a later launch goes straight to
the launch card
- [ ] The launch card offers agent, model, effort (Claude and Codex only) and permission mode
(off is an explicit tick, never the default); a CLI it could not find is named, not just
disabled
- [ ] **Dock the terminal to the right**: the splitter becomes vertical, the toolbar stacks, and the
dashboard keeps the rest of the width; dock it back to the bottom
- [ ] **Collapse** the terminal to a thin strip (either dock) and **Expand** it back; its size from
before collapsing is remembered
- [ ] Collapse the terminal (or shrink it small), let the agent go quiet for a while mid-answer: the
"agent may need you" badge appears on the strip; expanding it clears the badge
- [ ] **Change project** in the top bar, with an agent running: it asks first, then the folder
picker opens; cancelling the picker leaves the running agent and its project untouched
- [ ] Change project, pick a different folder: the old agent and console stop, the new folder opens
on the launch card (or the checklist, if its own first run has not passed yet)
- [ ] Reload the window (or navigate away and back) while an agent is running: the terminal redraws
from where it was, not blank, and the dashboard reconnects to the same session
- [ ] When the app and the installed skills differ in version, the bar offers **Update skills**, and
nothing updates until it is pressed
## The terminal panel, with each real agent (each system)
Do each of Claude Code, Devin and Codex for a few minutes:
- [ ] Startup screen draws correctly
- [ ] Typing a prompt and getting an answer
- [ ] A long streamed answer scrolls and stays readable
- [ ] Resizing the window reflows the agent's screen
- [ ] Pasting several lines
- [ ] A line with Unicode and emoji
- [ ] Select text in the terminal: it copies on its own; Ctrl+Shift+C (Windows, Linux) or Cmd+C
(macOS) copies the selection too; Ctrl+V / Cmd+V pastes
- [ ] Exiting the agent: the bar says it ended and offers Restart
## Agent lifecycle
- [ ] Start, then **Restart**: it confirms once, then a fresh agent starts on the same agent, model,
effort and permission mode, and the dashboard shows the pick-up chip with a brief that
matches the session
- [ ] An agent that ends by itself leaves the app asking nothing until Restart or **Change agent**
is pressed; Change agent reopens the launch card with a real choice to make again
- [ ] Closing the window while an agent runs asks first, and "no" keeps the window open
- [ ] Cmd+Q on macOS asks the same
- [ ] Windows only: start a CLI installed through npm (a `.cmd` shim), then Restart; check Task
Manager and confirm no leftover `node.exe` (or the CLI's own process) is left running
## Context meter
- [ ] Claude Code and Codex: the meter moves during a long session and the nudge appears once
- [ ] Devin: the meter is labeled as an estimate
- [ ] `~/.claude/settings.json` and your own status line are byte-identical before and after a session
## Standalone path
- [ ] `/plan2code` typed inside an agent with the app closed opens the dashboard exactly as before
- [ ] `npm test` still passes with the app installed on this machine
+9
View File
@@ -0,0 +1,9 @@
[package]
name = "fake-agent"
version = "3.0.0"
description = "A stand-in agent program for the Plan2Code app's tests"
edition = "2021"
publish = false
[dependencies]
terminal_size = "0.4"
+130
View File
@@ -0,0 +1,130 @@
//! A stand-in for Claude, Devin and Codex in the app's tests.
//!
//! It behaves the same on Windows, macOS and Linux. Commands, one per line on
//! stdin (these words are the contract the app's integration tests rely on):
//!
//! STEP <n> print one progress line a second for n seconds, then `STEP DONE`
//! EXIT <c> exit with code c
//! SIZE print the terminal size once
//! PID print the agent's process id as `PID <n>`
//! <other> echoed back as `echo: <line>`
//!
//! A change in terminal size is reported on its own as `SIZE <cols>x<rows>`.
use std::io::{self, BufRead, Write};
use std::thread;
use std::time::Duration;
use terminal_size::{terminal_size, Height, Width};
fn size_text() -> Option<String> {
terminal_size().map(|(Width(w), Height(h))| format!("SIZE {w}x{h}"))
}
fn say(line: &str) {
let mut out = io::stdout().lock();
let _ = writeln!(out, "{line}\r");
let _ = out.flush();
}
/// What a command line asks the agent to do.
#[derive(Debug, PartialEq, Eq)]
pub enum Command {
Step(u64),
Exit(i32),
Size,
Pid,
/// `ENV NAME`: print the variable's value, for tests of what an agent is given.
Env(String),
Echo(String),
}
pub fn parse(line: &str) -> Command {
let line = line.trim();
if let Some(rest) = line.strip_prefix("STEP ") {
if let Ok(n) = rest.trim().parse() {
return Command::Step(n);
}
}
if let Some(rest) = line.strip_prefix("EXIT ") {
if let Ok(code) = rest.trim().parse() {
return Command::Exit(code);
}
}
if line == "SIZE" {
return Command::Size;
}
if line == "PID" {
return Command::Pid;
}
if let Some(name) = line.strip_prefix("ENV ") {
return Command::Env(name.trim().to_string());
}
Command::Echo(line.to_string())
}
fn main() {
say("FAKE-AGENT ready");
if let Some(size) = size_text() {
say(&size);
}
// Report a resize on its own, by watching the size, so the same code works
// where there is no resize signal (Windows).
thread::spawn(|| {
let mut last = size_text();
loop {
thread::sleep(Duration::from_millis(100));
let now = size_text();
if now != last {
if let Some(text) = &now {
say(text);
}
last = now;
}
}
});
let stdin = io::stdin();
for line in stdin.lock().lines() {
let Ok(line) = line else { break };
match parse(&line) {
Command::Step(n) => {
for i in 1..=n {
say(&format!("working {i}/{n}"));
thread::sleep(Duration::from_secs(1));
}
say("STEP DONE");
}
Command::Exit(code) => {
say(&format!("exiting {code}"));
std::process::exit(code);
}
Command::Size => say(&size_text().unwrap_or_else(|| "SIZE unknown".into())),
Command::Pid => say(&format!("PID {}", std::process::id())),
Command::Env(name) => say(&format!("ENV {name}={}", std::env::var(&name).unwrap_or_default())),
Command::Echo(text) => say(&format!("echo: {text}")),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_the_command_words() {
assert_eq!(parse("STEP 3"), Command::Step(3));
assert_eq!(parse("EXIT 7\r\n"), Command::Exit(7));
assert_eq!(parse("SIZE"), Command::Size);
assert_eq!(parse("PID"), Command::Pid);
assert_eq!(parse("ENV PLAN2CODE_IN_APP"), Command::Env("PLAN2CODE_IN_APP".into()));
assert_eq!(parse("hello there"), Command::Echo("hello there".into()));
}
#[test]
fn a_bad_number_is_just_an_echo() {
assert_eq!(parse("STEP x"), Command::Echo("STEP x".into()));
assert_eq!(parse("EXIT"), Command::Echo("EXIT".into()));
}
}
+19
View File
@@ -0,0 +1,19 @@
{
"name": "plan2code-app",
"version": "3.0.0",
"private": true,
"description": "Plan2Code desktop app (Tauri). Separate from the repo root so the root and the web console stay dependency-free.",
"scripts": {
"tauri": "tauri",
"dev": "tauri dev",
"build": "tauri build"
},
"dependencies": {
"@tauri-apps/api": "2.12.4",
"@xterm/addon-fit": "0.11.0",
"@xterm/xterm": "6.0.0"
},
"devDependencies": {
"@tauri-apps/cli": "2.12.3"
}
}
+3
View File
@@ -0,0 +1,3 @@
[toolchain]
channel = "1.98.1"
profile = "minimal"
+17
View File
@@ -0,0 +1,17 @@
// Copies the xterm files the page loads from node_modules into ui/vendor/, so the
// page is plain files with no bundler. Run before `tauri dev` and `tauri build`.
import { copyFileSync, mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
const root = join(dirname(fileURLToPath(import.meta.url)), '..');
const out = join(root, 'ui', 'vendor');
mkdirSync(out, { recursive: true });
const files = [
['node_modules/@xterm/xterm/lib/xterm.js', 'xterm.js'],
['node_modules/@xterm/xterm/css/xterm.css', 'xterm.css'],
['node_modules/@xterm/addon-fit/lib/addon-fit.js', 'addon-fit.js'],
];
for (const [from, to] of files) copyFileSync(join(root, from), join(out, to));
console.log(`vendored ${files.length} xterm files into ui/vendor/`);
+30
View File
@@ -0,0 +1,30 @@
[package]
name = "plan2code-app"
version = "3.0.0"
description = "Plan2Code desktop app"
edition = "2021"
publish = false
[lib]
name = "plan2code_app_lib"
path = "src/lib.rs"
[build-dependencies]
tauri-build = { version = "2.5", features = [] }
[dependencies]
tauri = { version = "2.12", features = [] }
tauri-plugin-dialog = "2"
portable-pty = "0.9.0"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
chrono = "0.4"
[target.'cfg(unix)'.dependencies]
libc = "0.2"
[target.'cfg(windows)'.dependencies]
# Already pulled in by portable-pty itself; named directly here only for the
# Job Object APIs it does not expose (ending a `cmd /c` npm shim's whole
# process tree, not just the shim).
winapi = { version = "0.3.9", features = ["handleapi", "jobapi2", "minwindef", "ntdef", "winnt"] }
+3
View File
@@ -0,0 +1,3 @@
fn main() {
tauri_build::build()
}
@@ -0,0 +1,7 @@
{
"$schema": "../gen/schemas/desktop-schema.json",
"identifier": "default",
"description": "Permissions for the main window: its own commands need none, so only listening to the page events the app sends",
"windows": ["main"],
"permissions": ["core:event:allow-listen", "core:event:allow-unlisten"]
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 6.0 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.3 KiB

Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

@@ -0,0 +1,409 @@
//! At most one agent per project folder: start it, end it, restart it (always
//! at once: the app confirms with the person first, so nothing here waits for
//! a quiet moment), and notice when it ends by itself.
//! Knows nothing about Tauri: state changes and output go to one callback.
use std::path::PathBuf;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex, MutexGuard};
use std::thread;
use serde::Serialize;
use crate::agents::{launch_spec, AgentKind, PermissionMode};
use crate::pty_host::{PtyHost, StartOptions};
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
#[serde(tag = "state", rename_all = "lowercase")]
pub enum AgentState {
Idle,
Running,
/// The agent ended without a Restart press, or could not be started.
Ended { reason: String },
}
/// Runs just before a Restart starts the fresh agent, and returns the line the
/// bar shows about it (`None` for no line). It must not call back into the
/// manager: it runs with the manager's state locked.
pub type BeforeFresh = Arc<dyn Fn() -> Option<String> + Send + Sync>;
/// What the page needs to draw the bar. `generation` counts the agents started
/// so far: a new number means a fresh agent, so the terminal clears.
#[derive(Clone, Debug, Serialize)]
pub struct AgentSnapshot {
#[serde(flatten)]
pub state: AgentState,
pub kind: Option<AgentKind>,
pub generation: u64,
/// The running (or last started) agent's permission mode, so the bar's
/// note can name it instead of assuming bypass.
pub mode: Option<PermissionMode>,
/// What the last Restart left for the dashboard, for the bar.
#[serde(rename = "briefNote", skip_serializing_if = "Option::is_none")]
pub brief_note: Option<String>,
}
pub enum AgentEvent {
Output(Vec<u8>),
State(AgentSnapshot),
}
/// Receives events from several threads. State events are sent while the
/// manager holds its lock, so a sink must not call back into the manager.
pub type Sink = Arc<dyn Fn(AgentEvent) + Send + Sync>;
struct Running {
host: Arc<PtyHost>,
}
/// What a Restart starts again, besides the brief: the agent, its model and
/// effort (when it has one), and its permission mode. Restart reuses this
/// whole, unchanged choice (Task 9.6).
#[derive(Clone)]
struct StartChoice {
kind: AgentKind,
model: Option<String>,
effort: Option<String>,
mode: PermissionMode,
}
/// Recent output from the current generation is kept bounded, so a page
/// reload or a fresh output channel can redraw the screen instead of staying
/// blank. About enough for a full screen redraw with some headroom, never
/// the whole scrollback.
const REPLAY_LIMIT: usize = 256 * 1024;
/// Appends `bytes` to `replay`, dropping from the front (the oldest) when
/// that would put it over `limit`: the tail, what a redraw actually needs,
/// is always what is kept.
fn append_replay(replay: &mut Vec<u8>, bytes: &[u8], limit: usize) {
replay.extend_from_slice(bytes);
if replay.len() > limit {
let excess = replay.len() - limit;
replay.drain(..excess);
}
}
struct Inner {
state: AgentState,
running: Option<Running>,
/// What a Restart starts again: the choice and the brief.
last_start: Option<(StartChoice, Option<String>)>,
size: (u16, u16),
brief_note: Option<String>,
/// Cleared when a fresh agent starts; see `REPLAY_LIMIT`.
replay: Vec<u8>,
}
struct Shared {
folder: PathBuf,
sink: Sink,
before_fresh: Mutex<Option<BeforeFresh>>,
/// Environment every agent this manager starts gets, on top of its own:
/// the in-app signal that sends the agent's console pages to this window.
extra_env: Mutex<Vec<(String, String)>>,
/// Bumped for every agent started. Output and exits from an older agent
/// compare against it and are dropped.
generation: AtomicU64,
inner: Mutex<Inner>,
}
pub struct AgentManager {
shared: Arc<Shared>,
}
fn lock(inner: &Mutex<Inner>) -> MutexGuard<'_, Inner> {
// A panic in another thread must not take the whole app's agent control down.
inner.lock().unwrap_or_else(|poisoned| poisoned.into_inner())
}
impl AgentManager {
pub fn new(folder: PathBuf, sink: Sink) -> AgentManager {
AgentManager {
shared: Arc::new(Shared {
folder,
sink,
before_fresh: Mutex::new(None),
extra_env: Mutex::new(Vec::new()),
generation: AtomicU64::new(0),
inner: Mutex::new(Inner {
state: AgentState::Idle,
running: None,
last_start: None,
size: (80, 24),
brief_note: None,
replay: Vec::new(),
}),
}),
}
}
pub fn folder(&self) -> &PathBuf {
&self.shared.folder
}
/// Run `hook` before every Restart starts its fresh agent.
pub fn set_before_fresh(&self, hook: BeforeFresh) {
if let Ok(mut slot) = self.shared.before_fresh.lock() {
*slot = Some(hook);
}
}
/// Give every agent started from now on these variables (replacing any set before).
pub fn set_env(&self, env: Vec<(String, String)>) {
if let Ok(mut slot) = self.shared.extra_env.lock() {
*slot = env;
}
}
/// Start `kind` on `model`, `effort` and `mode`, with `brief` (`None` is
/// the placeholder brief: the plain `/plan2code` prompt, which opens the
/// dashboard). A second start while an agent runs is refused. Restart
/// reuses this exact choice, so a later call replaces it for good.
pub fn start(
&self,
kind: AgentKind,
model: Option<String>,
effort: Option<String>,
mode: PermissionMode,
brief: Option<String>,
) -> Result<(), String> {
let mut inner = lock(&self.shared.inner);
if inner.state == AgentState::Running {
return Err("an agent is already running for this project".to_string());
}
inner.brief_note = None;
let previous = inner.last_start.replace((StartChoice { kind, model, effort, mode }, brief));
match self.shared.spawn(&mut inner) {
Ok(()) => Ok(()),
Err(e) => {
// A start that never ran must not take away what Restart would
// have started again.
inner.last_start = previous;
Err(e)
}
}
}
pub fn snapshot(&self) -> AgentSnapshot {
self.shared.snapshot(&lock(&self.shared.inner))
}
/// The current generation's recent output, for a page that just mounted
/// (a reload or a fresh window) to redraw instead of staying blank.
pub fn replay(&self) -> Vec<u8> {
lock(&self.shared.inner).replay.clone()
}
/// The model and effort the current (or last) start chose. The bar only
/// ever needs `snapshot`'s `kind` and `mode`; this exists so a test can
/// confirm Restart keeps the other two of the four just as unchanged.
pub fn model_and_effort(&self) -> (Option<String>, Option<String>) {
match &lock(&self.shared.inner).last_start {
Some((choice, _)) => (choice.model.clone(), choice.effort.clone()),
None => (None, None),
}
}
pub fn is_active(&self) -> bool {
lock(&self.shared.inner).state == AgentState::Running
}
pub fn input(&self, bytes: &[u8]) -> Result<(), String> {
let host = lock(&self.shared.inner).running.as_ref().map(|r| Arc::clone(&r.host));
match host {
Some(host) => host.write(bytes),
None => Ok(()),
}
}
/// The terminal changed size. Remembered, so a fresh agent starts at it.
pub fn resize(&self, cols: u16, rows: u16) -> Result<(), String> {
let mut inner = lock(&self.shared.inner);
inner.size = (cols, rows);
match &inner.running {
Some(running) => running.host.resize(cols, rows),
None => Ok(()),
}
}
/// Kill the agent (if any) and start a fresh one on the same brief, at
/// once, whatever it is doing. The app asks the person to confirm before
/// calling this: there is no in-between "waiting" state here, because the
/// agent's own output (status lines, a spinner) never truly goes quiet, so
/// a "wait for it to finish" rule would wait forever in practice. Restart
/// also answers an ended agent, where nothing is lost by it.
pub fn restart(&self) -> Result<(), String> {
let mut inner = lock(&self.shared.inner);
if inner.state == AgentState::Idle {
return Err("no agent has been started".to_string());
}
self.shared.replace(&mut inner)
}
/// End the agent for good (quitting). Nothing starts afterwards, and the
/// agent's process is gone when this returns.
pub fn stop(&self) {
let host = {
let mut inner = lock(&self.shared.inner);
// Older agents' output and exits stop counting from here.
self.shared.generation.fetch_add(1, Ordering::SeqCst);
let host = inner.running.take().map(|r| r.host);
inner.state = AgentState::Idle;
inner.last_start = None;
self.shared.emit(&inner);
host
};
if let Some(host) = host {
let _ = host.kill();
let _ = host.wait();
}
}
}
impl Drop for AgentManager {
fn drop(&mut self) {
self.stop();
}
}
impl Shared {
fn snapshot(&self, inner: &Inner) -> AgentSnapshot {
AgentSnapshot {
state: inner.state.clone(),
kind: inner.last_start.as_ref().map(|(choice, _)| choice.kind),
mode: inner.last_start.as_ref().map(|(choice, _)| choice.mode),
generation: self.generation.load(Ordering::SeqCst),
brief_note: inner.brief_note.clone(),
}
}
fn emit(&self, inner: &Inner) {
(self.sink)(AgentEvent::State(self.snapshot(inner)));
}
/// Start the agent in `inner.last_start` and watch for it to end.
fn spawn(self: &Arc<Self>, inner: &mut Inner) -> Result<(), String> {
let (choice, brief) = inner.last_start.clone().ok_or("no agent has been started")?;
let prompt = brief.unwrap_or_else(|| choice.kind.default_prompt().to_string());
let mut spec =
launch_spec(choice.kind, &self.folder, choice.model.as_deref(), choice.effort.as_deref(), choice.mode, &prompt);
if let Ok(extra) = self.extra_env.lock() {
spec.env.extend(extra.iter().cloned());
}
let generation = self.generation.fetch_add(1, Ordering::SeqCst) + 1;
let on_output = {
let shared = Arc::clone(self);
move |bytes: Vec<u8>| {
// Taking the lock here, briefly, keeps this behind the state
// change that announces its agent (`spawn`'s caller holds the
// lock until it has emitted), so the page clears its screen
// before the banner. It is released before the send below,
// which can be slow, so typing (`input`) is never stuck
// behind a flood of output.
let stale = {
let mut in_order = lock(&shared.inner);
if shared.generation.load(Ordering::SeqCst) != generation {
true
} else {
append_replay(&mut in_order.replay, &bytes, REPLAY_LIMIT);
false
}
};
if stale {
return;
}
(shared.sink)(AgentEvent::Output(bytes));
}
};
let host = Arc::new(PtyHost::start(
StartOptions {
program: spec.program,
args: spec.args,
env: spec.env,
cwd: Some(spec.cwd),
cols: inner.size.0,
rows: inner.size.1,
},
on_output,
)?);
inner.running = Some(Running { host: Arc::clone(&host) });
inner.state = AgentState::Running;
// A fresh agent starts on a clean screen; its replay must too.
inner.replay.clear();
self.emit(inner);
let shared = Arc::clone(self);
thread::spawn(move || {
let reason = match host.wait_described() {
Ok((_, Some(signal))) => format!("was ended by a signal ({signal})"),
Ok((code, None)) => format!("exited with code {code}"),
Err(e) => format!("stopped: {e}"),
};
shared.on_exit(generation, reason);
});
Ok(())
}
/// Kill the running agent (if any) and start a fresh one on the same
/// brief. A fresh agent that cannot start leaves the state `Ended`.
fn replace(self: &Arc<Self>, inner: &mut Inner) -> Result<(), String> {
// Bumping the generation first drops whatever the old agent still says.
self.generation.fetch_add(1, Ordering::SeqCst);
if let Some(old) = inner.running.take() {
let _ = old.host.kill();
}
let hook = self.before_fresh.lock().ok().and_then(|slot| slot.clone());
inner.brief_note = hook.and_then(|run| run());
match self.spawn(inner) {
Ok(()) => Ok(()),
Err(e) => {
inner.state = AgentState::Ended { reason: format!("could not start the agent: {e}") };
self.emit(inner);
Err(e)
}
}
}
/// The agent's process ended. Stale if a newer agent has replaced it.
fn on_exit(self: &Arc<Self>, generation: u64, reason: String) {
let mut inner = lock(&self.inner);
if self.generation.load(Ordering::SeqCst) != generation {
return;
}
inner.running = None;
// Ended on its own: say why and start nothing.
inner.state = AgentState::Ended { reason };
self.emit(&inner);
}
}
#[cfg(test)]
mod replay_tests {
use super::*;
#[test]
fn under_the_limit_keeps_everything() {
let mut replay = b"hello ".to_vec();
append_replay(&mut replay, b"world", 20);
assert_eq!(replay, b"hello world");
}
#[test]
fn over_the_limit_drops_the_oldest_bytes_and_keeps_the_tail() {
let mut replay = b"0123456789".to_vec();
append_replay(&mut replay, b"ABCDE", 10);
// 15 bytes written, a 10-byte limit: the oldest 5 ("01234") are gone.
assert_eq!(replay, b"56789ABCDE");
assert_eq!(replay.len(), 10);
}
#[test]
fn a_single_write_longer_than_the_limit_keeps_only_its_own_tail() {
let mut replay = Vec::new();
append_replay(&mut replay, b"0123456789", 4);
assert_eq!(replay, b"6789");
}
}
+473
View File
@@ -0,0 +1,473 @@
//! The agents the app can run and the command line each one starts with. The
//! flags are the ones `src/launcher/plan2code.js` uses today, so the app and
//! `plan2code` start an agent the same way. Knows nothing about Tauri.
use std::path::{Path, PathBuf};
use serde::Serialize;
/// Tests only: run this program instead of the real agent, for any `AgentKind`,
/// so the fake agent stands in for Claude, Devin and Codex.
pub const AGENT_BIN_ENV: &str = "PLAN2CODE_APP_AGENT_BIN";
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum AgentKind {
Claude,
Devin,
Codex,
}
impl AgentKind {
pub const ALL: [AgentKind; 3] = [AgentKind::Claude, AgentKind::Devin, AgentKind::Codex];
/// The id the page and the settings file use.
pub fn id(self) -> &'static str {
match self {
AgentKind::Claude => "claude",
AgentKind::Devin => "devin",
AgentKind::Codex => "codex",
}
}
pub fn from_id(id: &str) -> Option<AgentKind> {
AgentKind::ALL.into_iter().find(|kind| kind.id() == id)
}
pub fn label(self) -> &'static str {
match self {
AgentKind::Claude => "Claude Code",
AgentKind::Devin => "Devin",
AgentKind::Codex => "Codex",
}
}
/// What a first start types: the skill that opens the dashboard. Codex
/// mentions a skill with `$name`.
pub fn default_prompt(self) -> &'static str {
match self {
AgentKind::Codex => "$plan2code",
_ => "/plan2code",
}
}
/// The program this agent runs as, before any PATH resolution.
pub fn program_name(self) -> &'static str {
match self {
AgentKind::Claude => "claude",
AgentKind::Devin => "devin",
AgentKind::Codex => "codex",
}
}
/// Whether this agent takes a separate reasoning effort. Devin's model
/// ids already carry effort (`swe-2-high`), so it has none of its own.
pub fn has_effort(self) -> bool {
matches!(self, AgentKind::Claude | AgentKind::Codex)
}
/// Where to install this agent: an npm command or, with no package of its
/// own, the site to install from. The same text `src/launcher/plan2code.js`
/// shows for a missing CLI.
pub fn install_hint(self) -> &'static str {
match self {
AgentKind::Claude => "npm i -g @anthropic-ai/claude-code",
AgentKind::Devin => "https://devin.ai",
AgentKind::Codex => "npm i -g @openai/codex",
}
}
}
/// Whether permission checks run while the agent works. Bypass is always an
/// explicit pick, shown with a banner while it runs; it is never the silent
/// default.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum PermissionMode {
/// The agent's own approval flow: it asks before a sensitive action.
Checked,
/// Permission checks are off.
Bypass,
}
impl PermissionMode {
pub fn id(self) -> &'static str {
match self {
PermissionMode::Checked => "checked",
PermissionMode::Bypass => "bypass",
}
}
pub fn from_id(id: &str) -> Option<PermissionMode> {
match id {
"checked" => Some(PermissionMode::Checked),
"bypass" => Some(PermissionMode::Bypass),
_ => None,
}
}
}
/// Whether `program` exists on `path_var`: an exact file on macOS and Linux,
/// or with `.exe`, `.cmd` or `.bat` on Windows (as `windows_command` resolves
/// a program to run).
pub fn find_on_path(program: &str, path_var: &str) -> Option<PathBuf> {
let exts: &[&str] = if cfg!(windows) { &["exe", "cmd", "bat"] } else { &[""] };
path_var.split(if cfg!(windows) { ';' } else { ':' }).filter(|dir| !dir.is_empty()).find_map(|dir| {
exts.iter().find_map(|ext| {
let name = if ext.is_empty() { program.to_string() } else { format!("{program}.{ext}") };
let candidate = Path::new(dir).join(name);
candidate.is_file().then_some(candidate)
})
})
}
/// Where `kind`'s CLI runs from: the test override when it is set, else its
/// program name on PATH. `None` means it cannot be run.
pub fn installed_at(kind: AgentKind) -> Option<PathBuf> {
let bin = std::env::var(AGENT_BIN_ENV).ok().filter(|b| !b.is_empty());
let program = bin.unwrap_or_else(|| kind.program_name().to_string());
find_on_path(&program, crate::node_check::resolved_path())
}
/// Whether `kind`'s CLI can be run at all.
pub fn is_installed(kind: AgentKind) -> bool {
installed_at(kind).is_some()
}
/// A command to run in the pseudo-terminal.
#[derive(Debug, PartialEq, Eq)]
pub struct LaunchSpec {
pub program: String,
pub args: Vec<String>,
pub env: Vec<(String, String)>,
pub cwd: PathBuf,
}
/// How to start `kind` in `folder`. An empty `prompt` starts the agent with
/// nothing typed. `PLAN2CODE_APP_AGENT_BIN` replaces the program (tests only).
pub fn launch_spec(
kind: AgentKind,
folder: &Path,
model: Option<&str>,
effort: Option<&str>,
mode: PermissionMode,
prompt: &str,
) -> LaunchSpec {
let bin = std::env::var(AGENT_BIN_ENV).ok().filter(|bin| !bin.is_empty());
let mut spec = launch_spec_with(kind, folder, model, effort, mode, prompt, bin.as_deref());
// The override names a program to run as it is; a real agent is looked up on PATH.
if cfg!(windows) && bin.is_none() {
let (program, args) = windows_command(&spec.program, spec.args, &std::env::var("PATH").unwrap_or_default());
spec.program = program;
spec.args = args;
}
spec
}
fn launch_spec_with(
kind: AgentKind,
folder: &Path,
model: Option<&str>,
effort: Option<&str>,
mode: PermissionMode,
prompt: &str,
bin_override: Option<&str>,
) -> LaunchSpec {
let cwd = folder.to_path_buf();
if let Some(bin) = bin_override {
return LaunchSpec { program: bin.to_string(), args: vec![], env: vec![], cwd };
}
let strings = |list: &[&str]| list.iter().map(|s| s.to_string()).collect::<Vec<_>>();
let model_args = |args: &mut Vec<String>| {
if let Some(model) = model {
args.push("--model".to_string());
args.push(model.to_string());
}
};
let bypass = mode == PermissionMode::Bypass;
let mut args = Vec::new();
let program = match kind {
AgentKind::Claude => {
if !prompt.is_empty() {
args.push(prompt.to_string());
}
if bypass {
args.extend(strings(&["--permission-mode", "bypassPermissions"]));
}
model_args(&mut args);
if let Some(effort) = effort {
args.push("--effort".to_string());
args.push(effort.to_string());
}
"claude"
}
AgentKind::Devin => {
if bypass {
args.extend(strings(&["--permission-mode", "bypass"]));
}
model_args(&mut args);
if !prompt.is_empty() {
args.push("--".to_string());
args.push(prompt.to_string());
}
"devin"
}
AgentKind::Codex => {
if bypass {
args.extend(strings(&["--dangerously-bypass-approvals-and-sandbox"]));
}
model_args(&mut args);
if let Some(effort) = effort {
args.push("-c".to_string());
args.push(format!("model_reasoning_effort={effort}"));
}
if !prompt.is_empty() {
args.push(prompt.to_string());
}
"codex"
}
};
// A Dock or Start-menu launch often lacks nvm, Homebrew or Volta's
// directories (Task 9.9): the agent CLI itself, and anything it shells
// out to, needs a PATH that finds them anyway.
let env = vec![("PATH".to_string(), crate::node_check::resolved_path().to_string())];
LaunchSpec { program: program.to_string(), args, env, cwd }
}
/// An agent installed with npm is, on Windows, a `.cmd` shim beside an
/// extensionless script, and `CreateProcess` cannot run the script. Look the
/// program up on `path_var` for an `.exe` (run as is), `.cmd` or `.bat` (run
/// through `cmd /c`); a program found as none of them is left alone.
pub fn windows_command(program: &str, args: Vec<String>, path_var: &str) -> (String, Vec<String>) {
for dir in path_var.split(';').filter(|dir| !dir.is_empty()) {
for ext in ["exe", "cmd", "bat"] {
let candidate = Path::new(dir).join(format!("{program}.{ext}"));
if !candidate.is_file() {
continue;
}
if ext == "exe" {
return (candidate.to_string_lossy().into_owned(), args);
}
// The bare file name, not the full path: a path with a space gets
// quoted, and `cmd /c` mangles a command line that starts with a quote.
// `cmd` finds the shim on PATH itself.
let mut wrapped = vec!["/c".to_string(), format!("{program}.{ext}")];
wrapped.extend(args);
return ("cmd".to_string(), wrapped);
}
}
(program.to_string(), args)
}
#[cfg(test)]
mod tests {
use super::*;
fn folder() -> PathBuf {
PathBuf::from("project")
}
fn args(kind: AgentKind, model: Option<&str>, mode: PermissionMode, prompt: &str) -> Vec<String> {
launch_spec_with(kind, &folder(), model, None, mode, prompt, None).args
}
#[test]
fn claude_puts_the_prompt_first() {
let spec = launch_spec_with(AgentKind::Claude, &folder(), None, None, PermissionMode::Bypass, "/plan2code", None);
assert_eq!(spec.program, "claude");
assert_eq!(spec.args, ["/plan2code", "--permission-mode", "bypassPermissions"]);
assert_eq!(spec.cwd, folder());
// A PATH that can still find nvm, Homebrew or Volta's directories (Task 9.9).
assert_eq!(spec.env.iter().filter(|(k, _)| k == "PATH").count(), 1);
}
#[test]
fn claude_with_a_model() {
assert_eq!(
args(AgentKind::Claude, Some("sonnet"), PermissionMode::Bypass, "/plan2code"),
["/plan2code", "--permission-mode", "bypassPermissions", "--model", "sonnet"]
);
}
#[test]
fn claude_checked_mode_skips_the_bypass_flag() {
assert_eq!(args(AgentKind::Claude, None, PermissionMode::Checked, "/plan2code"), ["/plan2code"]);
}
#[test]
fn claude_with_an_effort() {
let spec =
launch_spec_with(AgentKind::Claude, &folder(), None, Some("high"), PermissionMode::Bypass, "/plan2code", None);
assert_eq!(spec.args, ["/plan2code", "--permission-mode", "bypassPermissions", "--effort", "high"]);
}
#[test]
fn a_full_launch_card_choice_carries_model_effort_and_mode_together() {
let spec = launch_spec_with(
AgentKind::Claude,
&folder(),
Some("opus"),
Some("xhigh"),
PermissionMode::Bypass,
"/plan2code",
None,
);
assert_eq!(
spec.args,
["/plan2code", "--permission-mode", "bypassPermissions", "--model", "opus", "--effort", "xhigh"]
);
let checked = launch_spec_with(
AgentKind::Codex,
&folder(),
Some("gpt-5"),
Some("medium"),
PermissionMode::Checked,
"$plan2code",
None,
);
assert_eq!(checked.args, ["--model", "gpt-5", "-c", "model_reasoning_effort=medium", "$plan2code"]);
}
#[test]
fn devin_puts_the_prompt_after_a_double_dash() {
let spec = launch_spec_with(AgentKind::Devin, &folder(), None, None, PermissionMode::Bypass, "/plan2code", None);
assert_eq!(spec.program, "devin");
assert_eq!(spec.args, ["--permission-mode", "bypass", "--", "/plan2code"]);
}
#[test]
fn devin_with_a_model_keeps_the_prompt_last() {
assert_eq!(
args(AgentKind::Devin, Some("opus"), PermissionMode::Bypass, "/plan2code"),
["--permission-mode", "bypass", "--model", "opus", "--", "/plan2code"]
);
}
#[test]
fn devin_checked_mode_skips_the_bypass_flag() {
assert_eq!(args(AgentKind::Devin, None, PermissionMode::Checked, "/plan2code"), ["--", "/plan2code"]);
}
#[test]
fn codex_uses_its_own_flag_and_dollar_prompt() {
let prompt = AgentKind::Codex.default_prompt();
let spec = launch_spec_with(AgentKind::Codex, &folder(), None, None, PermissionMode::Bypass, prompt, None);
assert_eq!(spec.program, "codex");
assert_eq!(spec.args, ["--dangerously-bypass-approvals-and-sandbox", "$plan2code"]);
}
#[test]
fn codex_with_a_model() {
assert_eq!(
args(AgentKind::Codex, Some("gpt-5"), PermissionMode::Bypass, "$plan2code"),
["--dangerously-bypass-approvals-and-sandbox", "--model", "gpt-5", "$plan2code"]
);
}
#[test]
fn codex_with_an_effort_uses_a_config_override() {
let spec =
launch_spec_with(AgentKind::Codex, &folder(), None, Some("low"), PermissionMode::Bypass, "$plan2code", None);
assert_eq!(
spec.args,
["--dangerously-bypass-approvals-and-sandbox", "-c", "model_reasoning_effort=low", "$plan2code"]
);
}
#[test]
fn codex_checked_mode_skips_the_bypass_flag() {
assert_eq!(args(AgentKind::Codex, None, PermissionMode::Checked, "$plan2code"), ["$plan2code"]);
}
#[test]
fn no_prompt_means_nothing_typed() {
assert_eq!(args(AgentKind::Claude, None, PermissionMode::Bypass, ""), ["--permission-mode", "bypassPermissions"]);
assert_eq!(args(AgentKind::Devin, None, PermissionMode::Bypass, ""), ["--permission-mode", "bypass"]);
assert_eq!(args(AgentKind::Codex, None, PermissionMode::Bypass, ""), ["--dangerously-bypass-approvals-and-sandbox"]);
}
#[test]
fn a_custom_prompt_is_passed_through() {
assert_eq!(
args(AgentKind::Claude, None, PermissionMode::Bypass, "/plan2code pick up the brief"),
["/plan2code pick up the brief", "--permission-mode", "bypassPermissions"]
);
}
#[test]
fn devin_has_no_effort_of_its_own() {
assert!(!AgentKind::Devin.has_effort());
assert!(AgentKind::Claude.has_effort());
assert!(AgentKind::Codex.has_effort());
}
#[test]
fn permission_mode_ids_round_trip() {
for mode in [PermissionMode::Checked, PermissionMode::Bypass] {
assert_eq!(PermissionMode::from_id(mode.id()), Some(mode));
}
assert_eq!(PermissionMode::from_id("nope"), None);
}
#[test]
fn the_override_replaces_the_program_for_every_kind() {
for kind in AgentKind::ALL {
let spec = launch_spec_with(
kind,
&folder(),
Some("m"),
Some("high"),
PermissionMode::Bypass,
"/plan2code",
Some("fake-agent"),
);
assert_eq!(spec.program, "fake-agent");
assert!(spec.args.is_empty());
}
}
#[test]
fn find_on_path_sees_only_what_is_really_there() {
let dir = std::env::temp_dir().join(format!("plan2code-findonpath-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
let name = if cfg!(windows) { "tool.exe" } else { "tool" };
std::fs::write(dir.join(name), "").unwrap();
let path = dir.to_string_lossy().into_owned();
assert_eq!(find_on_path("tool", &path), Some(dir.join(name)));
assert_eq!(find_on_path("missing-tool", &path), None);
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn a_cmd_shim_runs_through_cmd_and_the_extensionless_script_is_ignored() {
let dir = std::env::temp_dir().join(format!("plan2code-shim-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("tool"), "#!/bin/sh").unwrap();
std::fs::write(dir.join("tool.cmd"), "@echo off").unwrap();
std::fs::write(dir.join("real.exe"), "").unwrap();
let path = dir.to_string_lossy().into_owned();
let args = vec!["--flag".to_string()];
let (program, wrapped) = windows_command("tool", args.clone(), &path);
assert_eq!(program, "cmd");
assert_eq!(wrapped, ["/c".to_string(), "tool.cmd".to_string(), "--flag".to_string()]);
let (program, same) = windows_command("real", args.clone(), &path);
assert_eq!(program, dir.join("real.exe").to_string_lossy());
assert_eq!(same, args);
assert_eq!(windows_command("missing", args.clone(), &path), ("missing".to_string(), args));
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn ids_round_trip() {
for kind in AgentKind::ALL {
assert_eq!(AgentKind::from_id(kind.id()), Some(kind));
}
assert_eq!(AgentKind::from_id("nope"), None);
}
}
+365
View File
@@ -0,0 +1,365 @@
//! This window's announce endpoint: `console.mjs open`, run by the agent inside
//! the app, POSTs the page it wants shown here instead of opening a browser.
//! Loopback only, one random token per window, so two windows never hear each
//! other's agents. Knows nothing about Tauri: the caller gets each accepted
//! notice through a callback.
use std::collections::hash_map::RandomState;
use std::hash::{BuildHasher, Hasher};
use std::io::{Read, Write};
use std::net::{Ipv4Addr, SocketAddr, TcpListener, TcpStream};
use std::sync::{Arc, Mutex};
use std::thread;
use std::time::Duration;
use serde::{Deserialize, Serialize};
/// The most an announce request may weigh: a URL and two short names.
const MAX_REQUEST: usize = 8 * 1024;
const READ_TIMEOUT: Duration = Duration::from_secs(3);
/// A page the console wants shown: where it is, the session it belongs to and
/// the skill it runs.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct PageNotice {
pub url: String,
pub sid: String,
pub workflow: String,
}
pub type OnPage = Arc<dyn Fn(PageNotice) + Send + Sync>;
pub struct AnnounceServer {
port: u16,
token: String,
/// The page most recently announced: what `GET /session` answers, so an
/// agent's `open` joins the window's current session whatever its own
/// environment (fixed when it started) says.
current: Arc<Mutex<Option<PageNotice>>>,
}
/// What a checked request asks for.
#[derive(Debug, PartialEq, Eq)]
pub enum Request {
/// `POST /page`: show this page.
Page(PageNotice),
/// `GET /session`: name the session the window shows now.
Session,
}
/// Why a request was refused, as the status the caller answers with.
#[derive(Debug, PartialEq, Eq)]
pub struct Refused(pub u16, pub &'static str);
/// A random token from the OS-seeded hasher: 128 bits as hex. The standard
/// library's `RandomState` keys come from the operating system's random source.
fn random_token() -> String {
let mut out = String::new();
for round in 0..2u8 {
let mut hasher = RandomState::new().build_hasher();
hasher.write_u8(round);
hasher.write_u128(
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_nanos())
.unwrap_or(0),
);
out.push_str(&format!("{:016x}", hasher.finish()));
}
out
}
fn same_token(a: &str, b: &str) -> bool {
// Compared in full whatever the first difference, so timing says nothing.
let (a, b) = (a.as_bytes(), b.as_bytes());
let mut diff = (a.len() != b.len()) as u8;
for i in 0..a.len().min(b.len()) {
diff |= a[i] ^ b[i];
}
diff == 0
}
/// A console page URL the app may show: plain http on loopback with a port and
/// a `/s/<token>/` path, which is all the console ever hands out.
pub fn acceptable_url(url: &str) -> bool {
let Some(rest) = url.strip_prefix("http://127.0.0.1:") else {
return false;
};
let Some((port, path)) = rest.split_once('/') else {
return false;
};
port.parse::<u16>().is_ok_and(|p| p > 0) && path.starts_with("s/") && !url.contains(char::is_whitespace)
}
/// Check one request (its head as text, its body as bytes) against `token`.
pub fn check_request(head: &str, body: &[u8], token: &str) -> Result<Request, Refused> {
let mut lines = head.split("\r\n");
let request_line = lines.next().unwrap_or("");
let route = request_line.split(' ').take(2).collect::<Vec<_>>();
if route != ["POST", "/page"] && route != ["GET", "/session"] {
return Err(Refused(404, "not found"));
}
let mut given = None;
for line in lines {
let Some((name, value)) = line.split_once(':') else { continue };
match name.trim().to_ascii_lowercase().as_str() {
"x-plan2code-token" => given = Some(value.trim().to_string()),
// A browser page sending this would be some site guessing at the port.
"origin" => return Err(Refused(403, "not from a page")),
_ => {}
}
}
if !given.is_some_and(|given| same_token(&given, token)) {
return Err(Refused(403, "bad token"));
}
if route[0] == "GET" {
return Ok(Request::Session);
}
let notice: PageNotice = serde_json::from_slice(body).map_err(|_| Refused(400, "bad body"))?;
if !acceptable_url(&notice.url) || notice.sid.len() > 128 || notice.workflow.len() > 64 {
return Err(Refused(400, "bad page"));
}
Ok(Request::Page(notice))
}
fn reason(status: u16) -> &'static str {
match status {
200 => "OK",
204 => "No Content",
400 => "Bad Request",
403 => "Forbidden",
_ => "Not Found",
}
}
fn respond(stream: &mut TcpStream, status: u16, body: &str) {
let _ = write!(
stream,
"HTTP/1.1 {status} {}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
reason(status),
body.len()
);
}
/// Read one request: the head up to the blank line, then the body the
/// `Content-Length` header names. Anything over `MAX_REQUEST` is refused.
fn read_request(stream: &mut TcpStream) -> Result<(String, Vec<u8>), Refused> {
let _ = stream.set_read_timeout(Some(READ_TIMEOUT));
let mut buf = Vec::new();
let mut chunk = [0u8; 1024];
let split = loop {
if let Some(at) = buf.windows(4).position(|w| w == b"\r\n\r\n") {
break at;
}
if buf.len() > MAX_REQUEST {
return Err(Refused(400, "too big"));
}
match stream.read(&mut chunk) {
Ok(0) | Err(_) => return Err(Refused(400, "incomplete")),
Ok(n) => buf.extend_from_slice(&chunk[..n]),
}
};
let head = String::from_utf8_lossy(&buf[..split]).into_owned();
let length = head
.split("\r\n")
.filter_map(|line| line.split_once(':'))
.find(|(name, _)| name.trim().eq_ignore_ascii_case("content-length"))
.and_then(|(_, value)| value.trim().parse::<usize>().ok())
.unwrap_or(0);
if length > MAX_REQUEST {
return Err(Refused(400, "too big"));
}
let mut body = buf[split + 4..].to_vec();
while body.len() < length {
match stream.read(&mut chunk) {
Ok(0) | Err(_) => return Err(Refused(400, "incomplete")),
Ok(n) => body.extend_from_slice(&chunk[..n]),
}
}
body.truncate(length);
Ok((head, body))
}
impl AnnounceServer {
/// Listen on a random loopback port. `on_page` runs on the server's own
/// thread for every accepted notice.
pub fn start(on_page: OnPage) -> Result<AnnounceServer, String> {
let listener = TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0))).map_err(|e| e.to_string())?;
let port = listener.local_addr().map_err(|e| e.to_string())?.port();
let token = random_token();
let expected = token.clone();
let current: Arc<Mutex<Option<PageNotice>>> = Arc::new(Mutex::new(None));
let shared = Arc::clone(&current);
thread::spawn(move || {
for stream in listener.incoming() {
let Ok(mut stream) = stream else { continue };
let (status, body) = match read_request(&mut stream)
.and_then(|(head, body)| check_request(&head, &body, &expected))
{
Ok(Request::Page(notice)) => {
if let Ok(mut slot) = shared.lock() {
*slot = Some(notice.clone());
}
on_page(notice);
(204, String::new())
}
Ok(Request::Session) => {
let now = shared.lock().ok().and_then(|slot| slot.clone());
(200, serde_json::to_string(&now).unwrap_or_else(|_| "null".to_string()))
}
Err(Refused(status, _)) => (status, String::new()),
};
respond(&mut stream, status, &body);
}
});
Ok(AnnounceServer { port, token, current })
}
pub fn url(&self) -> String {
format!("http://127.0.0.1:{}/page", self.port)
}
pub fn token(&self) -> &str {
&self.token
}
/// The page most recently announced, if any.
pub fn current(&self) -> Option<PageNotice> {
self.current.lock().ok().and_then(|slot| slot.clone())
}
/// What goes on the agent's process so its `console.mjs open` shows pages
/// here. Every value belongs to this window. `embed_origin` is the origin of
/// the app page, so a console the agent starts allows being framed by it.
pub fn agent_env(&self, embed_origin: &str, app_version: &str) -> Vec<(String, String)> {
vec![
("PLAN2CODE_IN_APP".to_string(), "1".to_string()),
("PLAN2CODE_APP_VERSION".to_string(), app_version.to_string()),
("PLAN2CODE_EMBED_ORIGIN".to_string(), embed_origin.to_string()),
("PLAN2CODE_APP_ANNOUNCE".to_string(), self.url()),
("PLAN2CODE_APP_TOKEN".to_string(), self.token.clone()),
]
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::mpsc::channel;
use std::sync::Mutex;
fn request(token: &str, body: &str) -> (String, Vec<u8>) {
(
format!("POST /page HTTP/1.1\r\nHost: 127.0.0.1\r\nx-plan2code-token: {token}\r\ncontent-length: {}", body.len()),
body.as_bytes().to_vec(),
)
}
const GOOD: &str = r#"{"url":"http://127.0.0.1:5000/s/abc/","sid":"s1","workflow":"plan"}"#;
#[test]
fn accepts_a_good_notice() {
let (head, body) = request("t", GOOD);
let Ok(Request::Page(notice)) = check_request(&head, &body, "t") else { panic!("not accepted") };
assert_eq!((notice.sid.as_str(), notice.workflow.as_str()), ("s1", "plan"));
let get = "GET /session HTTP/1.1\r\nx-plan2code-token: t";
assert_eq!(check_request(get, b"", "t"), Ok(Request::Session));
assert_eq!(check_request(get, b"", "other"), Err(Refused(403, "bad token")));
}
#[test]
fn refuses_a_wrong_or_missing_token() {
let (head, body) = request("nope", GOOD);
assert_eq!(check_request(&head, &body, "t"), Err(Refused(403, "bad token")));
let head = "POST /page HTTP/1.1\r\nHost: x";
assert_eq!(check_request(head, GOOD.as_bytes(), "t"), Err(Refused(403, "bad token")));
}
#[test]
fn refuses_a_browser_origin_and_other_routes() {
let (head, body) = request("t", GOOD);
let with_origin = format!("{head}\r\nOrigin: http://evil.example");
assert_eq!(check_request(&with_origin, &body, "t"), Err(Refused(403, "not from a page")));
let other = head.replace("/page", "/other");
assert_eq!(check_request(&other, &body, "t"), Err(Refused(404, "not found")));
let get = head.replace("POST", "GET");
assert_eq!(check_request(&get, &body, "t"), Err(Refused(404, "not found")), "GET is for /session only");
}
#[test]
fn refuses_a_bad_body_and_a_url_that_is_not_the_console() {
let (head, _) = request("t", "x");
assert_eq!(check_request(&head, b"not json", "t"), Err(Refused(400, "bad body")));
for url in ["http://example.com/s/abc/", "https://127.0.0.1:5/s/a/", "http://127.0.0.1:5/other", "javascript:alert(1)", "http://127.0.0.1:0/s/a/"] {
let body = format!(r#"{{"url":"{url}","sid":"s","workflow":"w"}}"#);
assert_eq!(check_request(&head, body.as_bytes(), "t"), Err(Refused(400, "bad page")), "{url}");
}
}
#[test]
fn tokens_differ_between_windows() {
assert_ne!(random_token(), random_token());
assert_eq!(random_token().len(), 32);
assert!(same_token("abc", "abc") && !same_token("abc", "abd") && !same_token("abc", "ab"));
}
fn post(port: u16, token: &str, body: &str) -> u16 {
let mut stream = TcpStream::connect(("127.0.0.1", port)).unwrap();
write!(
stream,
"POST /page HTTP/1.1\r\nHost: 127.0.0.1\r\nx-plan2code-token: {token}\r\ncontent-length: {}\r\nConnection: close\r\n\r\n{body}",
body.len()
)
.unwrap();
let mut answer = String::new();
stream.read_to_string(&mut answer).unwrap();
answer.split(' ').nth(1).unwrap().parse().unwrap()
}
#[test]
fn two_windows_hear_only_their_own_agent() {
let (tx_a, rx_a) = channel();
let (tx_b, rx_b) = channel();
let (tx_a, tx_b) = (Mutex::new(tx_a), Mutex::new(tx_b));
let a = AnnounceServer::start(Arc::new(move |n| tx_a.lock().unwrap().send(n).unwrap())).unwrap();
let b = AnnounceServer::start(Arc::new(move |n| tx_b.lock().unwrap().send(n).unwrap())).unwrap();
assert_ne!(a.url(), b.url());
let port = |s: &AnnounceServer| s.url().rsplit_once(':').unwrap().1.trim_end_matches("/page").parse::<u16>().unwrap();
assert_eq!(post(port(&a), a.token(), GOOD), 204);
assert_eq!(post(port(&b), a.token(), GOOD), 403, "window A's token does nothing in window B");
assert_eq!(rx_a.recv_timeout(Duration::from_secs(3)).unwrap().sid, "s1");
assert!(rx_b.recv_timeout(Duration::from_millis(300)).is_err());
}
#[test]
fn agent_env_names_this_windows_values() {
let server = AnnounceServer::start(Arc::new(|_| {})).unwrap();
let env = server.agent_env("http://127.0.0.1:1430", "3.0.0");
let get = |key: &str| env.iter().find(|(k, _)| k == key).map(|(_, v)| v.clone());
assert_eq!(get("PLAN2CODE_IN_APP").as_deref(), Some("1"));
assert_eq!(get("PLAN2CODE_EMBED_ORIGIN").as_deref(), Some("http://127.0.0.1:1430"));
assert_eq!(get("PLAN2CODE_APP_VERSION").as_deref(), Some("3.0.0"));
assert_eq!(get("PLAN2CODE_APP_ANNOUNCE"), Some(server.url()));
assert_eq!(get("PLAN2CODE_APP_TOKEN").as_deref(), Some(server.token()));
assert_eq!(get("PLAN2CODE_CONSOLE_SID"), None, "the window's session is asked for, not fixed at start");
}
#[test]
fn the_current_session_is_what_was_announced_last() {
let server = AnnounceServer::start(Arc::new(|_| {})).unwrap();
let port: u16 = server.url().rsplit_once(':').unwrap().1.trim_end_matches("/page").parse().unwrap();
let ask = |token: &str| {
let mut stream = TcpStream::connect(("127.0.0.1", port)).unwrap();
write!(stream, "GET /session HTTP/1.1\r\nHost: 127.0.0.1\r\nx-plan2code-token: {token}\r\nConnection: close\r\n\r\n").unwrap();
let mut answer = String::new();
stream.read_to_string(&mut answer).unwrap();
answer
};
assert!(ask(server.token()).ends_with("null"), "nothing announced yet");
assert_eq!(post(port, server.token(), GOOD), 204);
assert!(ask(server.token()).contains(r#""sid":"s1""#));
assert!(ask("wrong").starts_with("HTTP/1.1 403"));
assert_eq!(server.current().unwrap().workflow, "plan");
}
}
+461
View File
@@ -0,0 +1,461 @@
//! The restart brief: what a fresh agent needs to pick a session up where it
//! stopped, written from the console's session files and the spec on disk. It
//! is derived on demand and never cached. The Ask chat is left out (FR-7).
use std::fs;
use std::io::Read;
use std::path::Path;
use std::process::{Command, Stdio};
use std::thread;
use std::time::{Duration, Instant};
use serde_json::Value;
/// How many of the person's most recent answers the brief carries.
const RECENT_ANSWERS: usize = 10;
/// How many of the session's most recent `events.ndjson` lines the brief carries.
const RECENT_EVENTS: usize = 5;
/// The git argument for the last five commits, one line each.
const RECENT_COMMITS: &str = "-5";
/// How long the one-line next step may run before it is cut.
const NEXT_STEP_MAX: usize = 200;
/// The skill a console workflow runs, as the dashboard launches it.
pub fn skill_for_workflow(workflow: &str) -> Option<&'static str> {
Some(match workflow {
"init" => "plan2code-init",
"init-update" => "plan2code-init-update",
"pathfinder" => "plan2code-0-pathfinder",
"plan" => "plan2code-1-plan",
"revise-plan" => "plan2code-1b-revise-plan",
"quick-task" => "plan2code-quick-task",
"document" => "plan2code-2-document",
"implement" => "plan2code-3-implement",
"implement-review" => "plan2code-3-implement-review",
"review" => "plan2code-review",
"finalize" => "plan2code-4-finalize",
"handoff" => "plan2code-handoff",
"git" => "plan2code-git",
"changelog" => "plan2code-changelog",
"xray" => "plan2code-xray",
"diagnose" => "plan2code-diagnose",
_ => return None,
})
}
/// What the repository looks like now: `git status --short`, and the last
/// commits. `None` when the folder is not a git repository.
pub struct GitSummary {
pub status: String,
pub log: String,
}
pub fn git_summary(folder: &Path) -> Option<GitSummary> {
let status = git(folder, &["status", "--short"])?;
// A repository with no commits yet has no log: the status alone is the record.
let log = git(folder, &["log", RECENT_COMMITS, "--oneline"]).unwrap_or_default();
Some(GitSummary { status, log })
}
/// Longest a git call may hold up the caller. The brief is built while the
/// agent's state is locked, so a slow repository must not stall the window.
const GIT_TIMEOUT: Duration = Duration::from_secs(2);
fn git(folder: &Path, args: &[&str]) -> Option<String> {
let mut command = Command::new("git");
command.arg("-C").arg(folder).args(args).stdout(Stdio::piped()).stderr(Stdio::null());
#[cfg(windows)]
{
use std::os::windows::process::CommandExt;
command.creation_flags(0x08000000); // CREATE_NO_WINDOW, as the console calls are
}
let mut child = command.spawn().ok()?;
let mut out = child.stdout.take()?;
let reader = thread::spawn(move || {
let mut bytes = Vec::new();
let _ = out.read_to_end(&mut bytes);
bytes
});
let deadline = Instant::now() + GIT_TIMEOUT;
let status = loop {
if let Some(status) = child.try_wait().ok()? {
break status;
}
if Instant::now() >= deadline {
let _ = child.kill();
let _ = child.wait();
return None;
}
thread::sleep(Duration::from_millis(20));
};
let bytes = reader.join().ok()?;
status.success().then(|| String::from_utf8_lossy(&bytes).trim_end().to_string())
}
/// The brief as Markdown. `state` is a session's `state.json`; `spec_dir` is
/// the spec folder on disk, when the session has one; `git` is the repository
/// summary, when the folder is one; `events` is the session's `events.ndjson`,
/// oldest first.
pub fn build_brief(state: &Value, spec_dir: Option<&Path>, git: Option<&GitSummary>, events: &[Value]) -> String {
let workflow = str_field(state, "workflow").unwrap_or("");
let skill = skill_for_workflow(workflow);
let spec = str_field(state, "specDir");
let mut out = String::new();
out.push_str("## Where you were\n\n");
match skill {
Some(skill) => out.push_str(&format!("- Skill: {skill} (workflow `{workflow}`)\n")),
None => out.push_str(&format!("- Workflow: `{workflow}`\n")),
}
match spec {
Some(spec) => out.push_str(&format!("- Spec: {spec}\n")),
None => out.push_str("- Spec: none yet\n"),
}
out.push('\n');
out.push_str("## Progress\n\n");
let headline = state.get("headline");
let stage = headline.and_then(|h| str_field(h, "stage")).unwrap_or("");
let cleared = headline.and_then(|h| h.get("cleared")).and_then(Value::as_u64).unwrap_or(0);
let total = headline.and_then(|h| h.get("total")).and_then(Value::as_u64).unwrap_or(0);
let activity = state.get("agent").and_then(|a| str_field(a, "activity")).map(str::trim).filter(|a| !a.is_empty());
if !stage.is_empty() {
out.push_str(&format!("{stage}: {cleared} of {total} done.\n"));
if let Some(activity) = activity {
out.push_str(&format!("Doing: {activity}\n"));
}
out.push('\n');
} else if let Some(activity) = activity {
out.push_str(&format!("Doing: {activity}\n\n"));
} else {
out.push_str("No progress posted yet.\n\n");
}
let items = state.get("items").and_then(Value::as_array).map(Vec::as_slice).unwrap_or(&[]);
out.push_str("### Open questions\n\n");
let open: Vec<&Value> = items.iter().filter(|i| matches!(str_field(i, "status"), Some("open" | "reopened"))).collect();
if open.is_empty() {
out.push_str("None.\n\n");
} else {
for item in open {
out.push_str(&format!("- {}\n", title_of(item)));
}
out.push('\n');
}
out.push_str("## Recent answers and decisions\n\n");
let answered: Vec<&Value> = items.iter().filter(|i| str_field(i, "status") == Some("answered")).collect();
let recent = &answered[answered.len().saturating_sub(RECENT_ANSWERS)..];
if recent.is_empty() {
out.push_str("None yet.\n\n");
} else {
for item in recent {
let answer = answer_text(item);
let answer = if answer.is_empty() { "answered".to_string() } else { answer };
out.push_str(&format!("- {}: {answer}\n", title_of(item)));
}
out.push('\n');
}
if let Some(git) = git {
out.push_str("## Git\n\n");
out.push_str("Changes:\n\n```\n");
out.push_str(if git.status.is_empty() { "clean" } else { &git.status });
out.push_str("\n```\n\n");
if !git.log.is_empty() {
out.push_str("Last commits:\n\n```\n");
out.push_str(&git.log);
out.push_str("\n```\n\n");
}
}
if !events.is_empty() {
out.push_str("## Recent activity\n\n");
let recent = &events[events.len().saturating_sub(RECENT_EVENTS)..];
for event in recent {
out.push_str(&format!("- {}\n", render_event(event)));
}
out.push('\n');
}
out.push_str("## Next task\n\n");
out.push_str(&next_step(spec_dir, skill));
out.push('\n');
out
}
/// One `events.ndjson` line, as a terse line for a fresh agent. A shape this
/// does not special-case falls back to its raw `type`.
fn render_event(event: &Value) -> String {
let kind = str_field(event, "type").unwrap_or("event");
match kind {
"post" => {
let items = event.get("items").and_then(Value::as_u64).unwrap_or(0);
format!("post ({items} items)")
}
"consume" => match str_field(event, "kind") {
Some(kind) => format!("consume: {kind}"),
None => "consume".to_string(),
},
"open" => {
if event.get("resumed").and_then(Value::as_bool).unwrap_or(false) {
"open (resumed)".to_string()
} else {
"open".to_string()
}
}
other => other.to_string(),
}
}
/// The one-line next step: the first open task of the spec's in-progress phase
/// (or, failing that, the first phase not started); otherwise the skill's name;
/// otherwise "Open the dashboard".
pub fn next_step(spec_dir: Option<&Path>, skill: Option<&str>) -> String {
if let Some(task) = spec_dir.and_then(open_task) {
return cut(&task);
}
match skill {
Some(skill) => format!("Continue with {skill}"),
None => "Open the dashboard".to_string(),
}
}
/// The first `- [ ]` task line of the active phase file, as one line of text.
fn open_task(spec_dir: &Path) -> Option<String> {
let overview = fs::read_to_string(spec_dir.join("overview.md")).ok()?;
let phase = active_phase(&overview)?;
let text = fs::read_to_string(spec_dir.join(format!("phase-{phase}.md"))).ok()?;
let line = text.lines().map(str::trim_start).find(|l| l.starts_with("- [ ]"))?;
Some(line.trim_start_matches("- [ ]").trim().replace("**", ""))
}
/// The phase number the overview marks in progress (`[/]`), else the first
/// one not started (`[ ]`).
fn active_phase(overview: &str) -> Option<u32> {
let phase_of = |line: &str| {
let rest = &line[line.find("phase-")? + "phase-".len()..];
let digits: String = rest.chars().take_while(|c| c.is_ascii_digit()).collect();
digits.parse::<u32>().ok()
};
let rows = || overview.lines().map(str::trim_start).filter(|l| l.starts_with("- ["));
rows().find(|l| l.starts_with("- [/]")).and_then(phase_of).or_else(|| rows().find(|l| l.starts_with("- [ ]")).and_then(phase_of))
}
fn cut(text: &str) -> String {
let mut out: String = text.chars().take(NEXT_STEP_MAX).collect();
if text.chars().count() > NEXT_STEP_MAX {
out.push('…');
}
out
}
fn str_field<'a>(value: &'a Value, key: &str) -> Option<&'a str> {
value.get(key).and_then(Value::as_str)
}
fn title_of(item: &Value) -> String {
let title = str_field(item, "title").or_else(|| str_field(item, "id")).unwrap_or("(untitled)");
title.trim().to_string()
}
/// An answer as the person gave it: the option's label for a pick, plus any
/// words they typed. Empty when the answer carries nothing to show.
fn answer_text(item: &Value) -> String {
let Some(answer) = item.get("answer") else { return String::new() };
let options = item.get("options").and_then(Value::as_array);
let label = |k: &str| {
options
.and_then(|list| list.iter().find(|o| str_field(o, "k") == Some(k)))
.and_then(|o| str_field(o, "text"))
.unwrap_or(k)
.to_string()
};
let mut parts: Vec<String> = Vec::new();
if let Some(k) = str_field(answer, "k") {
parts.push(label(k));
}
if let Some(list) = answer.get("ks").and_then(Value::as_array) {
let picks: Vec<String> = list.iter().filter_map(Value::as_str).map(label).collect();
if !picks.is_empty() {
parts.push(picks.join(", "));
}
}
if let Some(yes) = answer.get("yes").and_then(Value::as_bool) {
parts.push(if yes { "yes" } else { "no" }.to_string());
}
if let Some(verdict) = str_field(answer, "verdict") {
parts.push(verdict.to_string());
}
if let Some(text) = str_field(answer, "text").map(str::trim).filter(|t| !t.is_empty()) {
parts.push(text.to_string());
}
parts.join("; ")
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn fixture(name: &str) -> std::path::PathBuf {
let dir = std::env::temp_dir().join(format!("plan2code-brief-{}-{name}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
dir
}
fn mid_implement_spec() -> std::path::PathBuf {
let spec = fixture("spec").join("specs").join("feature");
fs::create_dir_all(&spec).unwrap();
fs::write(
spec.join("overview.md"),
"- [x] [Phase 1: Foundations](./phase-1.md)\n- [/] [Phase 2: Restart](./phase-2.md)\n- [ ] [Phase 3: Later](./phase-3.md)\n",
)
.unwrap();
fs::write(spec.join("phase-2.md"), "## Tasks\n\n- [x] **Task 2.1:** Done already\n- [ ] **Task 2.2:** Write the **reader**\n- [ ] **Task 2.3:** Later\n").unwrap();
spec
}
fn mid_implement_state() -> Value {
json!({
"schema": 1,
"workflow": "implement",
"specDir": "specs/feature",
"headline": { "stage": "Phase 2: Restart", "cleared": 1, "total": 3 },
"items": [
{ "id": "q1", "title": "Which format", "status": "answered", "kind": "choice",
"options": [{ "k": "A", "text": "Markdown" }, { "k": "B", "text": "Plain text" }],
"answer": { "k": "A" } },
{ "id": "q2", "title": "Keep the header", "status": "answered", "kind": "confirm", "answer": { "yes": true } },
{ "id": "q3", "title": "Anything else?", "status": "open", "kind": "text" }
]
})
}
#[test]
fn a_mid_implement_session_carries_every_section() {
let spec = mid_implement_spec();
let git = GitSummary { status: " M src/lib.rs".to_string(), log: "abc1234 Add the reader".to_string() };
let brief = build_brief(&mid_implement_state(), Some(&spec), Some(&git), &[]);
assert!(brief.contains("Skill: plan2code-3-implement (workflow `implement`)"));
assert!(brief.contains("Spec: specs/feature"));
assert!(brief.contains("Phase 2: Restart: 1 of 3 done."));
assert!(brief.contains("### Open questions\n\n- Anything else?"));
assert!(brief.contains("- Which format: Markdown"));
assert!(brief.contains("- Keep the header: yes"));
assert!(brief.contains(" M src/lib.rs"));
assert!(brief.contains("abc1234 Add the reader"));
assert!(brief.contains("## Next task\n\nTask 2.2: Write the reader"));
}
#[test]
fn the_brief_names_only_the_last_ten_answers() {
let items: Vec<Value> = (0..12)
.map(|n| json!({ "id": format!("q{n}"), "title": format!("Question {n}"), "status": "answered", "answer": { "text": format!("Answer {n}") } }))
.collect();
let state = json!({ "schema": 1, "workflow": "pathfinder", "items": items });
let brief = build_brief(&state, None, None, &[]);
assert!(!brief.contains("Question 0:"));
assert!(!brief.contains("Question 1:"));
assert!(brief.contains("- Question 2: Answer 2"));
assert!(brief.contains("- Question 11: Answer 11"));
}
#[test]
fn a_pathfinder_session_without_a_spec_says_so() {
let state = json!({ "schema": 1, "workflow": "pathfinder", "headline": { "stage": "Charting", "cleared": 2, "total": 5 } });
let brief = build_brief(&state, None, None, &[]);
assert!(brief.contains("Skill: plan2code-0-pathfinder"));
assert!(brief.contains("- Spec: none yet"));
assert!(!brief.contains("## Git"));
assert!(brief.contains("## Next task\n\nContinue with plan2code-0-pathfinder"));
}
#[test]
fn a_session_with_no_spec_and_no_skill_opens_the_dashboard() {
let state = json!({ "schema": 1, "workflow": "dashboard" });
assert!(build_brief(&state, None, None, &[]).ends_with("## Next task\n\nOpen the dashboard\n"));
}
#[test]
fn chat_entries_never_reach_the_brief() {
let home = fixture("chat");
let dir = home.join("sessions").join("s1");
fs::create_dir_all(&dir).unwrap();
fs::write(dir.join("state.json"), r#"{"schema": 1, "workflow": "implement"}"#).unwrap();
fs::write(dir.join("chat.ndjson"), "{\"kind\":\"ask\",\"text\":\"CHAT-ONLY-WORDS\"}\n").unwrap();
let session = crate::session_reader::load(&home, "s1").unwrap();
let brief = build_brief(&session.state, None, None, &[]);
assert!(!brief.contains("CHAT-ONLY-WORDS"));
}
#[test]
fn a_folder_that_is_not_a_repository_has_no_git_summary() {
assert!(git_summary(&fixture("not-a-repo")).is_none());
}
#[test]
fn the_brief_names_what_the_agent_was_doing() {
let state = json!({
"schema": 1,
"workflow": "implement",
"headline": { "stage": "Phase 2: Restart", "cleared": 1, "total": 3 },
"agent": { "status": "working", "activity": "Spiking Claude's context signal (Task 10.1)" },
});
let brief = build_brief(&state, None, None, &[]);
assert!(brief.contains("Phase 2: Restart: 1 of 3 done.\nDoing: Spiking Claude's context signal (Task 10.1)\n"));
}
#[test]
fn an_activity_without_a_headline_still_shows() {
let state = json!({ "schema": 1, "workflow": "implement", "agent": { "status": "working", "activity": "Reading the spec" } });
let brief = build_brief(&state, None, None, &[]);
assert!(brief.contains("Doing: Reading the spec\n"));
assert!(!brief.contains("No progress posted yet."));
}
#[test]
fn an_empty_activity_falls_back_to_no_progress_posted() {
let state = json!({ "schema": 1, "workflow": "implement", "agent": { "status": "idle", "activity": "" } });
let brief = build_brief(&state, None, None, &[]);
assert!(brief.contains("No progress posted yet."));
}
#[test]
fn the_brief_names_a_few_recent_events() {
let state = json!({ "schema": 1, "workflow": "implement" });
let events = vec![
json!({ "at": "2026-10-23T01:00:00.000Z", "type": "listening", "port": 4100 }),
json!({ "at": "2026-10-23T01:08:00.000Z", "type": "open", "resumed": true }),
json!({ "at": "2026-10-23T01:08:47.152Z", "type": "post", "items": 3 }),
json!({ "at": "2026-10-23T01:09:00.000Z", "type": "consume", "kind": "submit" }),
];
let brief = build_brief(&state, None, None, &events);
assert!(brief.contains("## Recent activity\n\n- listening\n- open (resumed)\n- post (3 items)\n- consume: submit\n"));
}
#[test]
fn only_the_last_five_events_are_named() {
let state = json!({ "schema": 1, "workflow": "implement" });
let events: Vec<Value> = (0..8).map(|n| json!({ "type": "upload", "id": format!("f{n}") })).collect();
let brief = build_brief(&state, None, None, &events);
assert_eq!(brief.matches("- upload\n").count(), RECENT_EVENTS);
}
#[test]
fn no_events_means_no_recent_activity_section() {
let state = json!({ "schema": 1, "workflow": "implement" });
assert!(!build_brief(&state, None, None, &[]).contains("## Recent activity"));
}
#[test]
fn a_skill_name_maps_to_its_workflow() {
assert_eq!(skill_for_workflow("quick-task"), Some("plan2code-quick-task"));
assert_eq!(skill_for_workflow("unknown"), None);
}
}
@@ -0,0 +1,373 @@
//! The Node web console as a supervised child: `console.mjs open` starts a
//! detached server and prints the session's JSON, `stop` ends it, and a plain
//! GET on the session URL is the health check. Knows nothing about Tauri.
use std::io::{Read, Write};
use std::net::{TcpStream, ToSocketAddrs};
use std::path::{Path, PathBuf};
use std::process::Command;
use std::time::Duration;
use serde::Serialize;
/// How long a health check waits for the console before calling it dead. The
/// server is on loopback, so anything longer is a hang, not a slow network.
const HEALTH_TIMEOUT: Duration = Duration::from_secs(3);
/// A running console session, as `console.mjs open` reports it.
#[derive(Clone, Serialize)]
pub struct ConsoleSession {
pub sid: String,
pub url: String,
pub pid: u32,
pub port: u16,
/// The console says it can be framed by the app. An older one does not
/// print this, and its page would be refused in the frame.
pub embed: bool,
}
/// What the person is told when the installed console is too old for the app.
pub const OLD_CONSOLE: &str =
"The installed Plan2Code console is too old to show inside the app. Press Update skills, then try again.";
/// One supervised console for one project folder.
pub struct ConsoleSupervisor {
console_dir: PathBuf,
project_dir: PathBuf,
embed_origin: String,
session: ConsoleSession,
stopped: bool,
}
fn err<E: std::fmt::Display>(e: E) -> String {
e.to_string()
}
/// A `node console.mjs ...` call with no console window on Windows: the app is
/// a GUI program, so a bare Command would flash one open per call.
fn node_command(console_dir: &Path) -> Command {
let mut command = Command::new("node");
// A Dock or Start-menu launch often lacks nvm, Homebrew or Volta's
// directories (Task 9.9): run `node` with the PATH that finds it anyway.
command.env("PATH", crate::node_check::resolved_path());
command.arg(console_dir.join("console.mjs"));
#[cfg(windows)]
{
use std::os::windows::process::CommandExt;
command.creation_flags(0x08000000); // CREATE_NO_WINDOW
}
command
}
/// The origin the app's own page has, which is what the console's embed mode
/// must be told to allow as the frame parent. Tauri serves the page on
/// `http://tauri.localhost` on Windows (and Android) and `tauri://localhost`
/// on macOS and Linux.
pub fn app_origin() -> &'static str {
if cfg!(windows) {
"http://tauri.localhost"
} else {
"tauri://localhost"
}
}
/// The origin (`scheme://host[:port]`) of the app page's own URL, which is what
/// the console's embed mode must allow as the frame parent. In a release build
/// that is `app_origin()`, but `tauri dev` serves the page from its own dev
/// server on a loopback port, so the real URL is asked rather than assumed.
pub fn origin_of(url: &str) -> Option<String> {
let (scheme, rest) = url.split_once("://")?;
let authority = rest.split(['/', '?', '#']).next()?;
if authority.is_empty() || !matches!(scheme, "http" | "https" | "tauri") {
return None;
}
Some(format!("{scheme}://{authority}"))
}
/// Where the installed console lives: an explicit override first (tests and
/// dev), then the file the console keeps for the app, then the skill install.
pub fn find_console_dir() -> Result<PathBuf, String> {
let has_console = |dir: &Path| dir.join("console.mjs").is_file();
if let Ok(dir) = std::env::var("PLAN2CODE_CONSOLE_DIR") {
let dir = PathBuf::from(dir);
if has_console(&dir) {
return Ok(dir);
}
}
// The console writes its pointer under PLAN2CODE_CONSOLE_HOME when that
// relocates it, else under ~/.plan2code/console.
let pointer = match std::env::var("PLAN2CODE_CONSOLE_HOME") {
Ok(home) => PathBuf::from(home).join("console-dir"),
Err(_) => {
let home = std::env::home_dir().ok_or("no home folder found")?;
home.join(".plan2code").join("console").join("console-dir")
}
};
if let Ok(text) = std::fs::read_to_string(&pointer) {
let dir = PathBuf::from(text.trim());
if has_console(&dir) {
return Ok(dir);
}
}
let dir = std::env::home_dir()
.ok_or("no home folder found")?
.join(".agents")
.join("skills")
.join("plan2code")
.join("references")
.join("web-console");
if has_console(&dir) {
return Ok(dir);
}
Err(format!(
"the web console is not installed (looked in $PLAN2CODE_CONSOLE_DIR, {} and {})",
pointer.display(),
dir.display()
))
}
/// Parse the one JSON object `console.mjs open` prints on stdout.
fn parse_open_output(stdout: &[u8]) -> Result<ConsoleSession, String> {
let text = String::from_utf8_lossy(stdout);
let line = text
.lines()
.rev()
.find(|l| l.trim_start().starts_with('{'))
.ok_or_else(|| format!("console open printed no JSON: {}", text.trim()))?;
let value: serde_json::Value = serde_json::from_str(line.trim()).map_err(err)?;
let get = |key: &str| value.get(key).and_then(|v| v.as_str().map(String::from));
let num = |key: &str| value.get(key).and_then(|v| v.as_u64());
Ok(ConsoleSession {
sid: get("sid").ok_or("console open: no sid in output")?,
url: get("url").ok_or("console open: no url in output")?,
pid: num("pid").ok_or("console open: no pid in output")? as u32,
port: num("port").ok_or("console open: no port in output")? as u16,
embed: num("embed").is_some_and(|n| n >= 1),
})
}
/// Split `http://<host>:<port><path>` into its parts; the console only ever
/// listens on loopback http.
fn split_url(url: &str) -> Result<(String, u16, String), String> {
let rest = url.strip_prefix("http://").ok_or_else(|| format!("not an http url: {url}"))?;
let (authority, path) = match rest.split_once('/') {
Some((a, p)) => (a, format!("/{p}")),
None => (rest, "/".to_string()),
};
let (host, port) = authority
.rsplit_once(':')
.ok_or_else(|| format!("no port in url: {url}"))?;
let port: u16 = port.parse().map_err(|_| format!("bad port in url: {url}"))?;
Ok((host.to_string(), port, path))
}
impl ConsoleSupervisor {
/// Find the installed console, run `open --workflow dashboard --no-open` in
/// the project folder with `PLAN2CODE_EMBED_ORIGIN` set, and keep the
/// session it prints.
pub fn start(project_dir: PathBuf, embed_origin: String) -> Result<ConsoleSupervisor, String> {
let console_dir = find_console_dir()?;
let session = Self::open_session(&console_dir, &project_dir, &embed_origin, None)?;
Ok(ConsoleSupervisor { console_dir, project_dir, embed_origin, session, stopped: false })
}
/// `open` for the dashboard, or, with `resume`, the same session again on
/// a new server (so the page and its place in a skill survive a dead server).
/// A console the agent's `open` started and announced: this supervisor
/// now owns its health and its stop, though it did not start it.
pub fn adopt(
project_dir: PathBuf,
embed_origin: String,
url: &str,
sid: &str,
) -> Result<ConsoleSupervisor, String> {
let console_dir = find_console_dir()?;
let (_, port, _) = split_url(url)?;
let session = ConsoleSession { sid: sid.to_string(), url: url.to_string(), pid: 0, port, embed: true };
Ok(ConsoleSupervisor { console_dir, project_dir, embed_origin, session, stopped: false })
}
fn open_session(
console_dir: &Path,
project_dir: &Path,
embed_origin: &str,
resume: Option<&str>,
) -> Result<ConsoleSession, String> {
let mut command = node_command(console_dir);
command.arg("open");
match resume {
Some(sid) => command.args(["--resume", sid, "--no-open"]),
None => command.args(["--workflow", "dashboard", "--no-open"]),
};
let output = command
.current_dir(project_dir)
.env("PLAN2CODE_EMBED_ORIGIN", embed_origin)
.output()
.map_err(err)?;
if !output.status.success() {
return Err(format!(
"console open failed: {}",
String::from_utf8_lossy(&output.stderr).trim()
));
}
let session = parse_open_output(&output.stdout)?;
if !session.embed {
// Do not leave an old console running that the frame cannot show.
let _ = node_command(console_dir)
.args(["stop", "--session", &session.sid])
.current_dir(project_dir)
.output();
return Err(OLD_CONSOLE.to_string());
}
Ok(session)
}
pub fn session(&self) -> &ConsoleSession {
&self.session
}
/// The console moved to another address or session (an announced page that
/// is not the one this supervisor opened): health, stop and the restart
/// brief follow it from now on.
pub fn follow(&mut self, url: &str, sid: &str) {
if self.session.url == url && self.session.sid == sid {
return;
}
if let Ok((_, port, _)) = split_url(url) {
self.session.port = port;
}
self.session.url = url.to_string();
self.session.sid = sid.to_string();
}
/// Was `stop()` called on this supervisor.
pub fn stopped(&self) -> bool {
self.stopped
}
/// A GET on the session URL: any HTTP answer means the server is alive.
pub fn health(&self) -> bool {
if self.stopped {
return false;
}
let Ok((host, port, path)) = split_url(&self.session.url) else {
return false;
};
let Some(addr) = (host.as_str(), port).to_socket_addrs().ok().and_then(|mut a| a.next())
else {
return false;
};
let Ok(mut stream) = TcpStream::connect_timeout(&addr, HEALTH_TIMEOUT) else {
return false;
};
let _ = stream.set_read_timeout(Some(HEALTH_TIMEOUT));
let _ = stream.set_write_timeout(Some(HEALTH_TIMEOUT));
let request = format!("GET {path} HTTP/1.1\r\nHost: {host}\r\nConnection: close\r\n\r\n");
if stream.write_all(request.as_bytes()).is_err() {
return false;
}
let mut status = [0u8; 64];
match stream.read(&mut status) {
Ok(n) => String::from_utf8_lossy(&status[..n]).starts_with("HTTP/"),
Err(_) => false,
}
}
/// Health check plus a fresh `open` when the server is gone. Returns true
/// when a new session was started. Never loops: the caller (the bar) asks
/// and shows the outcome.
pub fn restart_if_dead(&mut self) -> Result<bool, String> {
if self.stopped || self.health() {
return Ok(false);
}
// The same session first, so the page and a skill's place in it survive;
// a session that cannot be resumed (gone from disk) starts a new one.
let sid = self.session.sid.clone();
self.session = Self::open_session(&self.console_dir, &self.project_dir, &self.embed_origin, Some(&sid))
.or_else(|_| Self::open_session(&self.console_dir, &self.project_dir, &self.embed_origin, None))?;
self.stopped = false;
Ok(true)
}
/// `console.mjs stop --session <sid>`: the console's own orderly shutdown.
pub fn stop(&mut self) -> Result<(), String> {
if self.stopped {
return Ok(());
}
let output = node_command(&self.console_dir)
.args(["stop", "--session", &self.session.sid])
.current_dir(&self.project_dir)
.output()
.map_err(err)?;
self.stopped = true;
if !output.status.success() {
return Err(format!(
"console stop failed: {}",
String::from_utf8_lossy(&output.stderr).trim()
));
}
Ok(())
}
}
impl Drop for ConsoleSupervisor {
/// The app going away takes the console it started with it. `stop` is
/// idempotent, so a session ended by hand just returns early here.
fn drop(&mut self) {
let _ = self.stop();
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn splits_the_session_url() {
let (host, port, path) = split_url("http://127.0.0.1:51617/s/abc/").unwrap();
assert_eq!((host.as_str(), port, path.as_str()), ("127.0.0.1", 51617, "/s/abc/"));
let (_, _, path) = split_url("http://localhost:9").unwrap();
assert_eq!(path, "/");
assert!(split_url("https://127.0.0.1:1/x").is_err());
assert!(split_url("http://127.0.0.1/x").is_err());
}
#[test]
fn origin_comes_from_the_pages_own_url() {
assert_eq!(origin_of("http://127.0.0.1:1430/index.html").as_deref(), Some("http://127.0.0.1:1430"));
assert_eq!(origin_of("http://tauri.localhost/").as_deref(), Some("http://tauri.localhost"));
assert_eq!(origin_of("https://tauri.localhost").as_deref(), Some("https://tauri.localhost"));
assert_eq!(origin_of("tauri://localhost/index.html?x=1").as_deref(), Some("tauri://localhost"));
assert_eq!(origin_of("file:///x"), None);
assert_eq!(origin_of("not a url"), None);
assert_eq!(origin_of("http:///x"), None);
}
#[test]
fn an_announced_console_is_adopted_with_its_port() {
// Only needs a console to be installed; skipped where there is none.
let Ok(dir) = find_console_dir() else { return };
let _ = dir;
let mut sup = ConsoleSupervisor::adopt(PathBuf::from("."), "http://tauri.localhost".into(), "http://127.0.0.1:5555/s/t/", "sid-9").unwrap();
assert_eq!((sup.session().port, sup.session().sid.as_str()), (5555, "sid-9"));
assert!(sup.session().embed);
assert!(ConsoleSupervisor::adopt(PathBuf::from("."), String::new(), "https://x/", "s").is_err());
sup.follow("http://127.0.0.1:6000/s/u/", "sid-10");
assert_eq!((sup.session().port, sup.session().sid.as_str()), (6000, "sid-10"));
// Never started a server here: nothing for Drop to stop.
sup.stopped = true;
}
#[test]
fn parses_open_output() {
let json = br#"{"ok":true,"sid":"s1","url":"http://127.0.0.1:5/s/t/","port":5,"pid":42,"embed":1}
"#;
let session = parse_open_output(json).unwrap();
assert_eq!((session.sid.as_str(), session.port, session.pid), ("s1", 5, 42));
assert!(session.embed);
let old = br#"{"ok":true,"sid":"s1","url":"http://127.0.0.1:5/s/t/","port":5,"pid":42}"#;
assert!(!parse_open_output(old).unwrap().embed, "a console that does not say it embeds is too old");
assert!(parse_open_output(b"not json\n").is_err());
assert!(parse_open_output(br#"{"ok":true,"sid":"s1"}"#).is_err());
}
}
@@ -0,0 +1,228 @@
//! Claude's context, read from its own transcript: the last `assistant` message's
//! token usage, as a fraction of its context window. Claude Code writes one file
//! per session under `~/.claude/projects/<cwd, every non-alphanumeric character
//! replaced with `-`>/<session id>.jsonl` (relocatable via `CLAUDE_CONFIG_DIR`),
//! and names it after the session's own id, so a project folder's newest file
//! since the agent started is this run's transcript (Task 10.1's spike; the
//! same approach `codex.rs` uses for Codex's log). The entry format is
//! undocumented ("internal and may change between versions" per Claude's own
//! docs), so a usable reading is `BestEffort`, never `Real`. An unreadable line
//! is skipped, and a transcript with no usable line, or no transcript at all,
//! is `Unknown`.
use std::fs::{self, File};
use std::io::{Read, Seek, SeekFrom};
use std::path::{Path, PathBuf};
use std::time::SystemTime;
use serde_json::Value;
use super::{ContextReader, ContextReading};
/// How much of a transcript's end is read; the newest usage is near the end.
pub const TAIL_BYTES: u64 = 256 * 1024;
pub struct ClaudeReader {
pub projects_dir: PathBuf,
pub folder: PathBuf,
/// Only a transcript written at or after this moment belongs to the running agent.
pub since: SystemTime,
/// The context window to read the usage against (`super::window_for`).
pub window: u64,
}
impl ContextReader for ClaudeReader {
fn read(&self) -> ContextReading {
match newest_transcript(&self.projects_dir.join(encode(&self.folder)), self.since) {
Some(file) => reading_from_file(&file, self.window),
None => ContextReading::Unknown,
}
}
}
/// `folder` with every non-alphanumeric character replaced by `-`, the way
/// Claude Code names a project's transcripts directory.
fn encode(folder: &Path) -> String {
folder.to_string_lossy().chars().map(|c| if c.is_ascii_alphanumeric() { c } else { '-' }).collect()
}
/// The newest `*.jsonl` file directly under `dir` that was written at or after `since`.
fn newest_transcript(dir: &Path, since: SystemTime) -> Option<PathBuf> {
let entries = fs::read_dir(dir).ok()?;
let mut newest: Option<(SystemTime, PathBuf)> = None;
for entry in entries.flatten() {
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) != Some("jsonl") {
continue;
}
let Ok(modified) = entry.metadata().and_then(|m| m.modified()) else { continue };
if modified < since {
continue;
}
if newest.as_ref().is_none_or(|(best, _)| modified > *best) {
newest = Some((modified, path));
}
}
newest.map(|(_, path)| path)
}
/// The percent of `window` the last usable `assistant` usage line in `text` used.
pub fn reading_from_text(text: &str, window: u64) -> ContextReading {
for line in text.lines().rev() {
if let Some(percent) = percent_from_line(line, window) {
return ContextReading::BestEffort { percent };
}
}
ContextReading::Unknown
}
fn percent_from_line(line: &str, window: u64) -> Option<u8> {
if window == 0 {
return None;
}
let value: Value = serde_json::from_str(line).ok()?;
if value.get("type")?.as_str()? != "assistant" {
return None;
}
let usage = value.get("message")?.get("usage")?;
let input = usage.get("input_tokens")?.as_u64()?;
let cache_read = usage.get("cache_read_input_tokens").and_then(Value::as_u64).unwrap_or(0);
let cache_creation = usage.get("cache_creation_input_tokens").and_then(Value::as_u64).unwrap_or(0);
let used = input.saturating_add(cache_read).saturating_add(cache_creation);
Some((used.saturating_mul(100) / window).min(100) as u8)
}
/// Reads the end of `file`. A file that cannot be opened or read is `Unknown`.
fn reading_from_file(file: &Path, window: u64) -> ContextReading {
let Ok(mut handle) = File::open(file) else { return ContextReading::Unknown };
let Ok(len) = handle.metadata().map(|m| m.len()) else { return ContextReading::Unknown };
if len > TAIL_BYTES && handle.seek(SeekFrom::Start(len - TAIL_BYTES)).is_err() {
return ContextReading::Unknown;
}
let mut bytes = Vec::new();
if handle.read_to_end(&mut bytes).is_err() {
return ContextReading::Unknown;
}
// The first line of a partial tail is cut short; it fails to parse and is skipped.
reading_from_text(&String::from_utf8_lossy(&bytes), window)
}
#[cfg(test)]
mod tests {
use super::*;
use std::time::Duration;
const GOOD: &str = r#"{"type":"assistant","message":{"usage":{"input_tokens":2,"cache_creation_input_tokens":724,"cache_read_input_tokens":205907}}}"#;
fn temp_dir(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("plan2code-claude-{}-{name}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
dir
}
fn epoch_plus(secs: u64) -> SystemTime {
SystemTime::UNIX_EPOCH + Duration::from_secs(secs)
}
fn write_transcript(dir: &Path, name: &str, body: &str, modified: SystemTime) -> PathBuf {
fs::create_dir_all(dir).unwrap();
let file = dir.join(format!("{name}.jsonl"));
fs::write(&file, body).unwrap();
File::options().write(true).open(&file).unwrap().set_modified(modified).unwrap();
file
}
#[test]
fn the_last_assistant_usage_gives_the_percent_of_the_window() {
assert_eq!(reading_from_text(GOOD, 206_633), ContextReading::BestEffort { percent: 100 });
assert_eq!(reading_from_text(GOOD, 1_000_000), ContextReading::BestEffort { percent: 20 });
}
#[test]
fn a_normal_transcript_is_read_from_the_newest_assistant_line() {
let early = r#"{"type":"assistant","message":{"usage":{"input_tokens":2,"cache_creation_input_tokens":0,"cache_read_input_tokens":99998}}}"#;
let text = format!("{early}\n{GOOD}");
assert_eq!(reading_from_text(&text, 206_633), ContextReading::BestEffort { percent: 100 });
}
#[test]
fn a_partial_last_line_is_skipped_in_favour_of_the_line_before_it() {
let text = format!("{GOOD}\n{{\"type\":\"assistant\",\"mess");
assert_eq!(reading_from_text(&text, 1_000_000), ContextReading::BestEffort { percent: 20 });
}
#[test]
fn non_assistant_and_malformed_lines_are_skipped() {
let text = format!("not json\n{{bad\n{{\"type\":\"user\",\"message\":{{}}}}\n{GOOD}");
assert_eq!(reading_from_text(&text, 1_000_000), ContextReading::BestEffort { percent: 20 });
}
#[test]
fn a_line_with_no_usable_usage_is_unknown() {
assert_eq!(reading_from_text("", 1_000_000), ContextReading::Unknown);
assert_eq!(reading_from_text(r#"{"type":"assistant","message":{}}"#, 1_000_000), ContextReading::Unknown);
assert_eq!(reading_from_text(GOOD, 0), ContextReading::Unknown);
}
#[test]
fn a_missing_file_is_unknown() {
let reader = ClaudeReader {
projects_dir: temp_dir("missing").join("projects"),
folder: PathBuf::from(r"C:\git\project"),
since: epoch_plus(0),
window: 200_000,
};
assert_eq!(reader.read(), ContextReading::Unknown);
}
#[test]
fn a_long_transcript_is_read_from_its_end() {
let dir = temp_dir("long");
let file = write_transcript(&dir, "long", &format!("{}\n{GOOD}", "x".repeat(TAIL_BYTES as usize + 100)), epoch_plus(0));
assert_eq!(reading_from_file(&file, 206_633), ContextReading::BestEffort { percent: 100 });
let _ = fs::remove_dir_all(dir);
}
#[test]
fn the_newest_transcript_for_this_folder_is_read() {
let root = temp_dir("newest");
let projects = root.join("projects");
let dir = projects.join(encode(Path::new(r"C:\git\project")));
write_transcript(&dir, "a-old", GOOD, epoch_plus(100));
let newest = write_transcript(&dir, "b-new", &GOOD.replace("205907", "500000"), epoch_plus(200));
let reader = ClaudeReader { projects_dir: projects, folder: PathBuf::from(r"C:\git\project"), since: epoch_plus(0), window: 1_000_000 };
assert_eq!(reader.read(), ContextReading::BestEffort { percent: 50 });
let _ = fs::remove_dir_all(root);
let _ = newest;
}
#[test]
fn a_rotated_file_is_read_from_the_new_one() {
let root = temp_dir("rotated");
let projects = root.join("projects");
let dir = projects.join(encode(Path::new(r"C:\git\project")));
write_transcript(&dir, "first", GOOD, epoch_plus(100));
let reader = ClaudeReader { projects_dir: projects.clone(), folder: PathBuf::from(r"C:\git\project"), since: epoch_plus(0), window: 1_000_000 };
assert_eq!(reader.read(), ContextReading::BestEffort { percent: 20 });
write_transcript(&dir, "second", &GOOD.replace("205907", "500000"), epoch_plus(200));
assert_eq!(reader.read(), ContextReading::BestEffort { percent: 50 });
let _ = fs::remove_dir_all(root);
}
#[test]
fn a_transcript_from_before_the_agent_started_is_ignored() {
let root = temp_dir("since");
let projects = root.join("projects");
let dir = projects.join(encode(Path::new(r"C:\git\project")));
write_transcript(&dir, "old", GOOD, epoch_plus(100));
let reader = ClaudeReader { projects_dir: projects, folder: PathBuf::from(r"C:\git\project"), since: epoch_plus(200), window: 1_000_000 };
assert_eq!(reader.read(), ContextReading::Unknown);
let _ = fs::remove_dir_all(root);
}
#[test]
fn the_cwd_is_encoded_the_way_claude_code_names_its_projects_folder() {
assert_eq!(encode(Path::new(r"C:\git\plan2code")), "C--git-plan2code");
}
}
@@ -0,0 +1,315 @@
//! Codex's context, read from its session log. Codex writes each run to
//! `sessions/YYYY/MM/DD/rollout-*.jsonl` under its home folder (`CODEX_HOME`,
//! or `~/.codex`). The app reads the newest log for its project folder, from
//! its end, and never writes there. The format is undocumented, so the reading
//! is `BestEffort`: an unrecognised line is skipped, and a log with no usable
//! line, or no log at all, is `Unknown`. Nothing here is an error.
use std::fs::{self, File};
use std::io::{BufRead, BufReader, Read, Seek, SeekFrom};
use std::path::{Path, PathBuf};
use std::time::SystemTime;
use serde_json::Value;
use super::{ContextReader, ContextReading};
/// How much of a log's end is read. The newest token count is near the end,
/// so a long log is never read whole.
pub const TAIL_BYTES: u64 = 256 * 1024;
/// How deep the sessions folder is searched: year, month, day, file.
const SEARCH_DEPTH: u32 = 4;
pub struct CodexReader {
pub sessions_dir: PathBuf,
pub folder: PathBuf,
/// Only logs written at or after this moment belong to the running agent.
pub since: SystemTime,
}
impl ContextReader for CodexReader {
fn read(&self) -> ContextReading {
match newest_log(&self.sessions_dir, &self.folder, self.since) {
Some(file) => reading_from_file(&file),
None => ContextReading::Unknown,
}
}
}
/// The percent of the model's window the newest request used, from the last
/// usable `token_count` line in `text`.
pub fn reading_from_text(text: &str) -> ContextReading {
for line in text.lines().rev() {
if let Some(percent) = percent_from_line(line) {
return ContextReading::BestEffort { percent };
}
}
ContextReading::Unknown
}
fn percent_from_line(line: &str) -> Option<u8> {
let value: Value = serde_json::from_str(line).ok()?;
if value.get("type")?.as_str()? != "event_msg" {
return None;
}
let payload = value.get("payload")?;
if payload.get("type")?.as_str()? != "token_count" {
return None;
}
let info = payload.get("info")?;
let used = info.get("last_token_usage")?.get("input_tokens")?.as_u64()?;
let window = info.get("model_context_window")?.as_u64()?;
if window == 0 {
return None;
}
Some((used.saturating_mul(100) / window).min(100) as u8)
}
/// Reads the end of `file`. A file that cannot be opened or read is `Unknown`.
fn reading_from_file(file: &Path) -> ContextReading {
let Ok(mut handle) = File::open(file) else { return ContextReading::Unknown };
let Ok(len) = handle.metadata().map(|m| m.len()) else { return ContextReading::Unknown };
if len > TAIL_BYTES && handle.seek(SeekFrom::Start(len - TAIL_BYTES)).is_err() {
return ContextReading::Unknown;
}
let mut bytes = Vec::new();
if handle.read_to_end(&mut bytes).is_err() {
return ContextReading::Unknown;
}
// The first line of a partial tail is cut short; it fails to parse and is skipped.
reading_from_text(&String::from_utf8_lossy(&bytes))
}
/// The newest log under `sessions_dir` that was written since `since` and
/// whose first line names `folder` as its working directory.
pub fn newest_log(sessions_dir: &Path, folder: &Path, since: SystemTime) -> Option<PathBuf> {
let mut logs = Vec::new();
collect_logs(sessions_dir, SEARCH_DEPTH, since, &mut logs);
let mut recent: Vec<(SystemTime, PathBuf)> = logs
.into_iter()
.filter_map(|file| {
let modified = fs::metadata(&file).ok()?.modified().ok()?;
(modified >= since).then_some((modified, file))
})
.collect();
recent.sort_by(|a, b| b.0.cmp(&a.0));
recent.into_iter().map(|(_, file)| file).find(|file| names_folder(file, folder))
}
// A day folder not touched since `since` holds no log of this run (creating a
// log updates its own folder, and only that one), so it is skipped: the walk
// stays short however many old logs Codex has kept. Year and month folders are
// always entered, as their own times say nothing about the logs below them.
// `depth` is 2 while the entries of a month folder are listed.
fn collect_logs(dir: &Path, depth: u32, since: SystemTime, out: &mut Vec<PathBuf>) {
let Ok(entries) = fs::read_dir(dir) else { return };
for entry in entries.flatten() {
let path = entry.path();
if path.is_dir() {
let touched = fs::metadata(&path).and_then(|m| m.modified()).is_ok_and(|m| m >= since);
if depth > 0 && (depth != 2 || touched) {
collect_logs(&path, depth - 1, since, out);
}
} else if is_rollout(&path) {
out.push(path);
}
}
}
fn is_rollout(path: &Path) -> bool {
path.file_name()
.and_then(|name| name.to_str())
.is_some_and(|name| name.starts_with("rollout-") && name.ends_with(".jsonl"))
}
/// True when the log's first line is a `session_meta` for `folder`.
fn names_folder(file: &Path, folder: &Path) -> bool {
let Ok(handle) = File::open(file) else { return false };
let mut first = String::new();
if BufReader::new(handle).read_line(&mut first).is_err() {
return false;
}
let Ok(value) = serde_json::from_str::<Value>(&first) else { return false };
if value.get("type").and_then(Value::as_str) != Some("session_meta") {
return false;
}
value
.get("payload")
.and_then(|payload| payload.get("cwd"))
.and_then(Value::as_str)
.is_some_and(|cwd| same_folder(cwd, folder))
}
/// Compares two folder paths the way Windows does: case, slash style and a
/// trailing separator do not count.
fn same_folder(cwd: &str, folder: &Path) -> bool {
let norm = |s: &str| {
s.trim_start_matches(r"\\?\").trim_end_matches(['\\', '/']).replace('/', "\\").to_ascii_lowercase()
};
norm(cwd) == norm(&folder.to_string_lossy())
}
#[cfg(test)]
mod tests {
use super::*;
use std::time::Duration;
const GOOD: &str = r#"{"type":"event_msg","payload":{"type":"token_count","info":{"last_token_usage":{"input_tokens":21839},"model_context_window":258400}}}"#;
fn temp_dir(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("plan2code-codex-{}-{name}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
dir
}
// A log whose first line names `cwd`, then `body` lines, dated `modified`.
fn write_log(sessions: &Path, name: &str, cwd: &str, body: &str, modified: SystemTime) -> PathBuf {
let day = sessions.join("2026").join("10").join("22");
fs::create_dir_all(&day).unwrap();
let file = day.join(format!("rollout-{name}.jsonl"));
let meta = serde_json::json!({ "type": "session_meta", "payload": { "cwd": cwd } });
fs::write(&file, format!("{meta}\n{body}")).unwrap();
// `meta` is a JSON value, so its text is escaped for the log.
fs::File::options().write(true).open(&file).unwrap().set_modified(modified).unwrap();
file
}
fn epoch_plus(secs: u64) -> SystemTime {
SystemTime::UNIX_EPOCH + Duration::from_secs(secs)
}
#[test]
fn the_last_token_count_gives_the_percent_of_the_window() {
assert_eq!(reading_from_text(GOOD), ContextReading::BestEffort { percent: 8 });
}
#[test]
fn unrecognised_and_malformed_lines_are_skipped() {
let text = format!("not json\n{{bad\n{GOOD}\n{}", r#"{"type":"event_msg","payload":{"type":"other"}}"#);
assert_eq!(reading_from_text(&text), ContextReading::BestEffort { percent: 8 });
}
#[test]
fn a_log_with_no_usable_line_is_unknown() {
assert_eq!(reading_from_text(""), ContextReading::Unknown);
assert_eq!(reading_from_text("garbage\n{}"), ContextReading::Unknown);
let zero_window = GOOD.replace("258400", "0");
assert_eq!(reading_from_text(&zero_window), ContextReading::Unknown);
}
#[test]
fn an_early_token_count_without_info_is_skipped() {
let early = r#"{"type":"event_msg","payload":{"type":"token_count","info":null}}"#;
assert_eq!(reading_from_text(&format!("{GOOD}\n{early}")), ContextReading::BestEffort { percent: 8 });
assert_eq!(reading_from_text(early), ContextReading::Unknown);
}
#[test]
fn only_a_session_meta_with_this_folder_names_it() {
let root = temp_dir("names");
let folder = Path::new(r"C:\git\project");
let verbatim = serde_json::json!({ "type": "session_meta", "payload": { "cwd": r"\\?\C:\git\project" } });
let cases = [
("not json".to_string(), false),
(r#"{"type":"other","payload":{"cwd":"x"}}"#.to_string(), false),
(r#"{"type":"session_meta","payload":{}}"#.to_string(), false),
(verbatim.to_string(), true),
];
for (i, (line, expected)) in cases.iter().enumerate() {
let file = root.join(format!("rollout-{i}.jsonl"));
fs::write(&file, format!("{line}\n{GOOD}\n")).unwrap();
assert_eq!(names_folder(&file, folder), *expected, "{line}");
}
let _ = fs::remove_dir_all(root);
}
#[test]
fn a_long_log_is_read_from_its_end() {
let dir = temp_dir("long");
let file = dir.join("long.jsonl");
fs::write(&file, format!("{}\n{GOOD}\n", "x".repeat(TAIL_BYTES as usize + 100))).unwrap();
assert_eq!(reading_from_file(&file), ContextReading::BestEffort { percent: 8 });
let _ = fs::remove_dir_all(dir);
}
#[test]
fn a_missing_log_is_unknown() {
assert_eq!(reading_from_file(Path::new("no-such-dir/rollout-x.jsonl")), ContextReading::Unknown);
}
#[test]
fn a_missing_sessions_folder_is_unknown() {
let reader = CodexReader {
sessions_dir: temp_dir("none").join("sessions"),
folder: PathBuf::from(r"C:\git\project"),
since: epoch_plus(0),
};
assert_eq!(reader.read(), ContextReading::Unknown);
}
#[test]
fn the_newest_log_for_this_folder_is_read() {
let root = temp_dir("newest");
let sessions = root.join("sessions");
write_log(&sessions, "a-old", r"C:\git\project", GOOD, epoch_plus(100));
write_log(&sessions, "b-other", r"C:\git\elsewhere", GOOD, epoch_plus(300));
let newest = write_log(&sessions, "c-new", r"c:\git\project\", &GOOD.replace("21839", "129200"), epoch_plus(200));
assert_eq!(newest_log(&sessions, Path::new(r"C:\git\project"), epoch_plus(0)), Some(newest));
let _ = fs::remove_dir_all(root);
}
// Sets a folder's modified time; Windows needs the backup-semantics flag to open one.
fn set_dir_modified(dir: &Path, time: SystemTime) {
let mut options = fs::OpenOptions::new();
#[cfg(windows)]
{
use std::os::windows::fs::OpenOptionsExt;
options.write(true).custom_flags(0x0200_0000);
}
#[cfg(not(windows))]
options.read(true);
options.open(dir).unwrap().set_modified(time).unwrap();
}
#[test]
fn old_year_and_month_folders_do_not_hide_todays_log() {
let root = temp_dir("parents");
let sessions = root.join("sessions");
let log = write_log(&sessions, "today", r"C:\git\project", GOOD, epoch_plus(500));
// Creating a log touches only its day folder: the parents keep their old times.
set_dir_modified(&sessions.join("2026"), epoch_plus(10));
set_dir_modified(&sessions.join("2026").join("10"), epoch_plus(20));
assert_eq!(newest_log(&sessions, Path::new(r"C:\git\project"), epoch_plus(100)), Some(log));
// A day folder untouched since the agent started is skipped.
set_dir_modified(&sessions.join("2026").join("10").join("22"), epoch_plus(30));
assert_eq!(newest_log(&sessions, Path::new(r"C:\git\project"), epoch_plus(100)), None);
let _ = fs::remove_dir_all(root);
}
#[test]
fn a_log_from_before_the_agent_started_is_ignored() {
let root = temp_dir("since");
let sessions = root.join("sessions");
write_log(&sessions, "old", r"C:\git\project", GOOD, epoch_plus(100));
assert_eq!(newest_log(&sessions, Path::new(r"C:\git\project"), epoch_plus(200)), None);
let _ = fs::remove_dir_all(root);
}
#[test]
fn a_rotated_log_is_read_from_the_new_file() {
let root = temp_dir("rotated");
let sessions = root.join("sessions");
write_log(&sessions, "first", r"C:\git\project", GOOD, epoch_plus(100));
let reader = CodexReader {
sessions_dir: sessions.clone(),
folder: PathBuf::from(r"C:\git\project"),
since: epoch_plus(0),
};
assert_eq!(reader.read(), ContextReading::BestEffort { percent: 8 });
write_log(&sessions, "second", r"C:\git\project", &GOOD.replace("21839", "129200"), epoch_plus(200));
assert_eq!(reader.read(), ContextReading::BestEffort { percent: 50 });
let _ = fs::remove_dir_all(root);
}
}
+313
View File
@@ -0,0 +1,313 @@
//! How full the agent's context is. A reader says one of four things: a real
//! number (`Real`, documented by the agent and verified), a best-effort number
//! (`BestEffort`, works today but undocumented), a labeled estimate (`Estimate`)
//! or `Unknown`. Knows nothing about Tauri: the page asks for a reading and
//! draws what it gets.
pub mod claude;
pub mod codex;
use std::time::SystemTime;
use serde::Serialize;
use crate::agents::AgentKind;
/// A rough token window used only by the estimate, and by `claude.rs` when no
/// window comes with the signal it reads. The estimate is labeled as one
/// everywhere it is shown, so the exact size does not have to be right.
pub const ESTIMATE_TOKEN_WINDOW: u64 = 200_000;
/// The window for a model whose id names it a long-context one (Claude Code's
/// `[1m]` model id suffix).
pub const LONG_CONTEXT_TOKEN_WINDOW: u64 = 1_000_000;
/// The usual rule of thumb: about four characters of text per token.
pub const BYTES_PER_TOKEN: u64 = 4;
/// The context window to read `kind`'s usage against, or `None` when no
/// window is documented for it at all (Devin today), in which case a byte
/// count is not even a meaningful guess. `model` is the id the person picked,
/// if any; one naming a long-context model (Claude Code's `[1m]` suffix) gets
/// the bigger window.
pub fn window_for(kind: Option<AgentKind>, model: Option<&str>) -> Option<u64> {
match kind {
Some(AgentKind::Claude) | Some(AgentKind::Codex) => {
let long_context = model.is_some_and(|m| m.to_ascii_lowercase().contains("[1m]"));
Some(if long_context { LONG_CONTEXT_TOKEN_WINDOW } else { ESTIMATE_TOKEN_WINDOW })
}
Some(AgentKind::Devin) | None => None,
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(tag = "kind", rename_all = "lowercase")]
pub enum ContextReading {
Real { percent: u8 },
BestEffort { percent: u8 },
Estimate { percent: u8 },
Unknown,
}
/// One agent's way of reading its context. The estimate is the fallback every
/// agent has; a reader for an agent that documents its usage returns `Real`.
pub trait ContextReader {
fn read(&self) -> ContextReading;
}
/// The percent of `window` that `bytes` of text fills, capped at 100 and
/// rounded up: any text at all reads as at least 1 percent, never a flat 0
/// while the agent is working.
pub fn estimate_percent(bytes: u64, window: u64) -> u8 {
let tokens = bytes / BYTES_PER_TOKEN;
if tokens == 0 || window == 0 {
return 0;
}
tokens.saturating_mul(100).div_ceil(window).min(100) as u8
}
/// Where the output scan is inside a terminal control sequence.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
enum Escape {
#[default]
None,
Esc,
Intermediate,
Csi,
Osc,
OscEnd,
}
/// Counts the text an agent run has produced and been given. A new agent
/// (a new `generation`) starts the count over, and nothing is counted while
/// no agent runs.
#[derive(Debug, Default)]
pub struct Meter {
generation: u64,
seen: bool,
running: bool,
bytes: u64,
escape: Escape,
kind: Option<AgentKind>,
// When the current agent run began: its own log must be written after this.
since: Option<SystemTime>,
}
impl Meter {
/// Called on every agent state change: a new generation resets the count.
pub fn observe(&mut self, generation: u64, running: bool) {
if !self.seen || generation != self.generation {
self.generation = generation;
self.seen = true;
self.bytes = 0;
self.escape = Escape::None;
self.since = Some(SystemTime::now());
}
self.running = running;
}
pub fn set_kind(&mut self, kind: Option<AgentKind>) {
self.kind = kind;
}
pub fn kind(&self) -> Option<AgentKind> {
self.kind
}
pub fn since(&self) -> Option<SystemTime> {
self.since
}
/// Output from the agent, or text typed to it, while it runs.
/// Output from the agent. Terminal control sequences (colours, cursor
/// moves, window titles) are not text the agent holds, so only the visible
/// bytes count. A sequence cut across two chunks is still skipped whole.
pub fn add_output(&mut self, chunk: &[u8]) {
let mut visible = 0usize;
for &byte in chunk {
self.escape = match self.escape {
Escape::None => match byte {
0x1b => Escape::Esc,
b'\n' | b'\t' => {
visible += 1;
Escape::None
}
0x20..=0x7e | 0x80..=0xff => {
visible += 1;
Escape::None
}
_ => Escape::None,
},
Escape::Esc => match byte {
b'[' => Escape::Csi,
// OSC, and the other strings that end the same way: DCS, SOS, PM, APC.
b']' | b'P' | b'X' | b'^' | b'_' => Escape::Osc,
// `ESC ( B` and the like: intermediate bytes, then one final byte.
0x20..=0x2f => Escape::Intermediate,
_ => Escape::None,
},
Escape::Intermediate => match byte {
0x20..=0x2f => Escape::Intermediate,
_ => Escape::None,
},
Escape::Csi => match byte {
0x40..=0x7e => Escape::None,
_ => Escape::Csi,
},
Escape::Osc => match byte {
0x07 => Escape::None,
0x1b => Escape::OscEnd,
_ => Escape::Osc,
},
Escape::OscEnd => Escape::None,
};
}
self.add(visible);
}
/// Text typed to the agent, or any count of visible bytes.
pub fn add(&mut self, bytes: usize) {
if self.running {
self.bytes = self.bytes.saturating_add(bytes as u64);
}
}
pub fn reading(&self) -> ContextReading {
if !self.seen || !self.running {
return ContextReading::Unknown;
}
match window_for(self.kind, None) {
Some(window) => ContextReading::Estimate { percent: estimate_percent(self.bytes, window) },
None => ContextReading::Unknown,
}
}
}
impl ContextReader for Meter {
fn read(&self) -> ContextReading {
self.reading()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn no_text_is_zero_percent() {
assert_eq!(estimate_percent(0, ESTIMATE_TOKEN_WINDOW), 0);
}
#[test]
fn half_the_window_is_fifty_percent() {
assert_eq!(estimate_percent(ESTIMATE_TOKEN_WINDOW * BYTES_PER_TOKEN / 2, ESTIMATE_TOKEN_WINDOW), 50);
}
#[test]
fn more_than_the_window_caps_at_one_hundred() {
assert_eq!(estimate_percent(u64::MAX / 2, ESTIMATE_TOKEN_WINDOW), 100);
}
#[test]
fn any_text_at_all_rounds_up_instead_of_reading_zero() {
assert_eq!(estimate_percent(BYTES_PER_TOKEN, ESTIMATE_TOKEN_WINDOW), 1);
}
#[test]
fn a_long_context_model_gets_the_bigger_window() {
assert_eq!(window_for(Some(AgentKind::Claude), Some("claude-sonnet-4-5-20250929[1m]")), Some(LONG_CONTEXT_TOKEN_WINDOW));
assert_eq!(window_for(Some(AgentKind::Claude), Some("sonnet")), Some(ESTIMATE_TOKEN_WINDOW));
assert_eq!(window_for(Some(AgentKind::Claude), None), Some(ESTIMATE_TOKEN_WINDOW));
}
#[test]
fn devin_and_an_unknown_agent_have_no_basis_for_a_window() {
assert_eq!(window_for(Some(AgentKind::Devin), None), None);
assert_eq!(window_for(None, None), None);
}
fn counted(chunks: &[&[u8]]) -> u64 {
let mut meter = Meter::default();
meter.observe(1, true);
for chunk in chunks {
meter.add_output(chunk);
}
meter.bytes
}
#[test]
fn plain_text_counts_and_control_sequences_do_not() {
assert_eq!(counted(&[b"hello\n"]), 6);
assert_eq!(counted(&[b"\x1b[31mred\x1b[0m"]), 3);
assert_eq!(counted(&[b"\x1b[2K\x1b[1A\x1b[Gx"]), 1);
assert_eq!(counted(&[b"\x1b]0;a title\x07ok"]), 2);
assert_eq!(counted(&[b"\x1b]0;a title\x1b\\ok"]), 2);
}
#[test]
fn charset_and_string_sequences_are_skipped() {
assert_eq!(counted(&[b"\x1b(Bok"]), 2);
assert_eq!(counted(&[b"\x1bPq#0;2;0;0;0\x1b\\ok"]), 2);
}
#[test]
fn a_sequence_split_across_chunks_is_still_skipped() {
assert_eq!(counted(&[b"ab\x1b[3", b"1mcd"]), 4);
assert_eq!(counted(&[b"\x1b", b"[0m", b"z"]), 1);
}
#[test]
fn nothing_running_is_unknown() {
let mut meter = Meter::default();
assert_eq!(meter.reading(), ContextReading::Unknown);
meter.observe(1, false);
meter.add(10_000);
assert_eq!(meter.reading(), ContextReading::Unknown);
}
#[test]
fn a_running_agent_is_an_estimate_of_what_it_has_seen() {
let mut meter = Meter::default();
meter.set_kind(Some(AgentKind::Claude));
meter.observe(1, true);
meter.add((ESTIMATE_TOKEN_WINDOW * BYTES_PER_TOKEN / 4) as usize);
assert_eq!(meter.reading(), ContextReading::Estimate { percent: 25 });
}
#[test]
fn a_fresh_agent_starts_the_count_over() {
let mut meter = Meter::default();
meter.set_kind(Some(AgentKind::Claude));
meter.observe(1, true);
meter.add(400_000);
meter.observe(2, true);
assert_eq!(meter.reading(), ContextReading::Estimate { percent: 0 });
}
#[test]
fn a_stopped_agent_is_unknown_again() {
let mut meter = Meter::default();
meter.set_kind(Some(AgentKind::Claude));
meter.observe(1, true);
meter.add(400_000);
meter.observe(1, false);
assert_eq!(meter.reading(), ContextReading::Unknown);
}
#[test]
fn an_agent_with_no_documented_window_is_unknown_not_a_guess() {
let mut meter = Meter::default();
meter.set_kind(Some(AgentKind::Devin));
meter.observe(1, true);
meter.add(400_000);
assert_eq!(meter.reading(), ContextReading::Unknown);
}
#[test]
fn no_kind_set_yet_is_unknown_not_a_guess() {
let mut meter = Meter::default();
meter.observe(1, true);
meter.add(400_000);
assert_eq!(meter.reading(), ContextReading::Unknown);
}
}
+224
View File
@@ -0,0 +1,224 @@
//! Writes a handoff the dashboard already knows how to list: a `.md` document
//! and its `.json` record in `~/.plan2code/handoffs/`, in the shape
//! `src/web-console/handoffs.mjs` reads (`v: 1`, the local-minute id, `usedAt`
//! null). The console is not changed for this, so the dashboard's **Pick it up
//! here** chip appears as it does for a handoff the Handoff skill wrote.
use std::fs::{self, OpenOptions};
use std::io::Write;
use std::path::{Path, PathBuf};
use chrono::{DateTime, Datelike, Local, SecondsFormat, Timelike, Utc};
use serde_json::json;
/// `~/.plan2code/handoffs`, or `PLAN2CODE_HANDOFFS_DIR` when it is moved.
pub fn handoffs_dir() -> Option<PathBuf> {
if let Ok(dir) = std::env::var("PLAN2CODE_HANDOFFS_DIR") {
return Some(PathBuf::from(dir));
}
Some(std::env::home_dir()?.join(".plan2code").join("handoffs"))
}
/// What the dashboard needs to resume the session the handoff came from.
pub struct Record<'a> {
pub title: &'a str,
pub worktree: &'a str,
pub project: &'a str,
/// `specs/<name>`, or none.
pub spec: Option<&'a str>,
pub workflow: &'a str,
pub skill: &'a str,
}
/// Write `body` as the handoff's document and the record beside it, under an
/// id made from `when`'s local minute. Returns the id. The record is claimed
/// exclusively, so two writes in the same minute never share an id; a failed
/// write leaves nothing behind.
pub fn write(dir: &Path, when: DateTime<Local>, record: &Record, body: &str) -> Result<String, String> {
validate(record)?;
fs::create_dir_all(dir).map_err(|e| e.to_string())?;
let base = format!(
"{:04}-{:02}-{:02}-{:02}{:02}-handoff",
when.year(),
when.month(),
when.day(),
when.hour(),
when.minute()
);
let written = when.with_timezone(&Utc).to_rfc3339_opts(SecondsFormat::Millis, true);
for n in 1.. {
let id = if n == 1 { base.clone() } else { format!("{base}-{n}") };
let md = dir.join(format!("{id}.md"));
let json_file = dir.join(format!("{id}.json"));
if md.exists() {
continue;
}
let mut claim = match OpenOptions::new().write(true).create_new(true).open(&json_file) {
Ok(file) => file,
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(e) => return Err(e.to_string()),
};
let meta = json!({
"v": 1,
"id": id,
"title": record.title,
"worktree": record.worktree,
"project": record.project,
"spec": record.spec,
"workflow": record.workflow,
"skill": record.skill,
"written": written,
"fromStop": false,
"usedAt": null,
});
let text = serde_json::to_string_pretty(&meta).map_err(|e| e.to_string())? + "\n";
if let Err(e) = claim.write_all(text.as_bytes()) {
let _ = fs::remove_file(&json_file);
return Err(e.to_string());
}
if let Err(e) = write_document(&md, &title_line(record.title), body) {
let _ = fs::remove_file(&json_file);
return Err(e);
}
return Ok(id);
}
unreachable!("the id loop only ends by returning")
}
fn write_document(md: &Path, heading: &str, body: &str) -> Result<(), String> {
let mut file = OpenOptions::new().write(true).create_new(true).open(md).map_err(|e| e.to_string())?;
file.write_all(format!("{heading}\n\n{body}").as_bytes()).map_err(|e| e.to_string())
}
fn title_line(title: &str) -> String {
format!("# Handoff: {title}")
}
/// Delete a handoff the person has not picked up (its record has no `usedAt`),
/// both files. A picked-up one, or one already gone, is left alone.
pub fn retire_if_unused(dir: &Path, id: &str) -> Result<(), String> {
let json_file = dir.join(format!("{id}.json"));
let Ok(text) = fs::read_to_string(&json_file) else { return Ok(()) };
let used = serde_json::from_str::<serde_json::Value>(&text).ok().is_some_and(|meta| !meta["usedAt"].is_null());
if used {
return Ok(());
}
for file in [json_file, dir.join(format!("{id}.md"))] {
match fs::remove_file(&file) {
Ok(()) => {}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
Err(e) => return Err(e.to_string()),
}
}
Ok(())
}
/// The same rules the console applies to the record, so a bad field is refused
/// here rather than written and then ignored.
fn validate(record: &Record) -> Result<(), String> {
let lower_dashes = |s: &str| !s.is_empty() && s.chars().all(|c| c.is_ascii_lowercase() || c == '-');
if !lower_dashes(record.workflow) {
return Err(format!("workflow must be lowercase letters and dashes, got {:?}", record.workflow));
}
let skill_ok = !record.skill.is_empty() && record.skill.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-');
if !skill_ok {
return Err(format!("skill must be a skill name, got {:?}", record.skill));
}
if let Some(spec) = record.spec {
let name = spec.strip_prefix("specs/");
if name.is_none_or(|n| n.is_empty() || n == "." || n == ".." || n.contains('/') || n.contains('\\')) {
return Err(format!("spec must be specs/<name>, got {spec:?}"));
}
}
Ok(())
}
/// The clock's local time, for the id. Tests pass their own.
pub fn now() -> DateTime<Local> {
Local::now()
}
#[cfg(test)]
mod tests {
use super::*;
use chrono::TimeZone;
fn fixture(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("plan2code-handoff-{}-{name}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
dir
}
fn record() -> Record<'static> {
Record {
title: "Restart of plan2code-3-implement",
worktree: "C:\\git\\plan2code",
project: "C:\\git\\plan2code",
spec: Some("specs/feature"),
workflow: "implement",
skill: "plan2code-3-implement",
}
}
fn at(hour: u32, minute: u32) -> DateTime<Local> {
Local.with_ymd_and_hms(2026, 10, 21, hour, minute, 0).unwrap()
}
#[test]
fn the_record_has_the_shape_the_dashboard_reads() {
let dir = fixture("shape");
let id = write(&dir, at(13, 52), &record(), "## Next task\n\nTask 5.2").unwrap();
assert_eq!(id, "2026-10-21-1352-handoff");
let meta: serde_json::Value = serde_json::from_str(&fs::read_to_string(dir.join(format!("{id}.json"))).unwrap()).unwrap();
assert_eq!(meta["v"], 1);
assert_eq!(meta["id"], id.as_str());
assert_eq!(meta["workflow"], "implement");
assert_eq!(meta["skill"], "plan2code-3-implement");
assert_eq!(meta["spec"], "specs/feature");
assert_eq!(meta["fromStop"], false);
assert!(meta["usedAt"].is_null());
assert!(meta["written"].as_str().unwrap().ends_with('Z'));
let doc = fs::read_to_string(dir.join(format!("{id}.md"))).unwrap();
assert!(doc.starts_with("# Handoff: Restart of plan2code-3-implement\n\n"));
assert!(doc.contains("## Next task"));
}
#[test]
fn a_second_write_in_the_same_minute_takes_the_next_id() {
let dir = fixture("clash");
let first = write(&dir, at(9, 0), &record(), "one").unwrap();
let second = write(&dir, at(9, 0), &record(), "two").unwrap();
assert_eq!(first, "2026-10-21-0900-handoff");
assert_eq!(second, "2026-10-21-0900-handoff-2");
}
#[test]
fn a_bad_workflow_is_refused_before_anything_is_written() {
let dir = fixture("bad");
let mut bad = record();
bad.workflow = "Implement";
assert!(write(&dir, at(9, 0), &bad, "x").is_err());
assert!(!dir.exists());
}
#[test]
fn an_unused_handoff_is_retired_and_a_picked_up_one_is_kept() {
let dir = fixture("retire");
let unused = write(&dir, at(10, 0), &record(), "one").unwrap();
let used = write(&dir, at(10, 1), &record(), "two").unwrap();
fs::write(dir.join(format!("{used}.json")), r#"{"v":1,"usedAt":"2026-10-21T10:02:00.000Z"}"#).unwrap();
retire_if_unused(&dir, &unused).unwrap();
retire_if_unused(&dir, &used).unwrap();
assert!(!dir.join(format!("{unused}.json")).exists());
assert!(!dir.join(format!("{unused}.md")).exists());
assert!(dir.join(format!("{used}.json")).exists());
assert!(dir.join(format!("{used}.md")).exists());
}
#[test]
fn a_spec_must_be_one_folder_under_specs() {
let mut bad = record();
bad.spec = Some("specs/a/b");
assert!(validate(&bad).is_err());
}
}
+16
View File
@@ -0,0 +1,16 @@
//! The parts of the app that tests reach directly.
pub mod agent_manager;
pub mod agents;
pub mod announce;
pub mod brief;
pub mod console_supervisor;
pub mod context;
pub mod handoff;
pub mod node_check;
pub mod project;
pub mod pty_host;
pub mod restart_brief;
pub mod session_reader;
pub mod settings;
pub mod versions;
+737
View File
@@ -0,0 +1,737 @@
// Hide the extra console window on Windows release builds.
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
use std::sync::{Arc, Mutex};
use plan2code_app_lib::announce::AnnounceServer;
use plan2code_app_lib::agent_manager::{AgentEvent, AgentManager, AgentState, Sink};
use plan2code_app_lib::agents::{self, AgentKind, PermissionMode};
use plan2code_app_lib::console_supervisor::{app_origin, origin_of, ConsoleSupervisor};
use plan2code_app_lib::context::claude::ClaudeReader;
use plan2code_app_lib::context::codex::CodexReader;
use plan2code_app_lib::context::{self, ContextReader, ContextReading, Meter};
use plan2code_app_lib::node_check;
use plan2code_app_lib::project::{self, ProjectDir};
use plan2code_app_lib::restart_brief;
use plan2code_app_lib::settings;
use plan2code_app_lib::versions;
use tauri::ipc::{Channel, InvokeResponseBody};
use tauri::{Emitter, Manager, State};
use tauri_plugin_dialog::{DialogExt, MessageDialogButtons, MessageDialogKind};
type PageChannel = Arc<Mutex<Option<Channel<InvokeResponseBody>>>>;
// The project the app is working on, the console it supervises for it and the
// agent it runs there.
#[derive(Default)]
struct AppState {
project: Mutex<Option<ProjectDir>>,
// The agent and model the launcher chose, from its arguments.
launch: project::LaunchChoice,
console: Arc<Mutex<Option<ConsoleSupervisor>>>,
agent: Mutex<Option<Arc<AgentManager>>>,
// Where the agent's output and state changes go: the page's latest channel.
page: PageChannel,
// How much text the running agent has produced and been given, for the meter.
context: Arc<Mutex<Meter>>,
// This window's endpoint for pages the agent's `console.mjs open` wants shown here.
announce: Mutex<Option<AnnounceServer>>,
// The Node version `main()` found before opening the window (Task 1.7 exits
// cleanly on anything else, so this is always a passing version once the
// window exists), and which binary that was, with `resolved_path`'s PATH
// (Task 9.9): the first-run checklist's Node row names both.
node_version: Option<String>,
node_binary: Option<String>,
}
// The operating system and, on Windows, the build number xterm needs for ConPTY.
#[tauri::command]
fn platform_info() -> serde_json::Value {
let build = if cfg!(windows) { windows_build() } else { None };
serde_json::json!({ "os": std::env::consts::OS, "windowsBuild": build })
}
// What the launch card offers per agent: whether its CLI is on PATH (else how
// to install it), and whether it takes its own reasoning effort.
#[tauri::command]
fn agent_availability() -> serde_json::Value {
let entries: Vec<_> = AgentKind::ALL
.iter()
.map(|&kind| {
let at = agents::installed_at(kind);
serde_json::json!({
"id": kind.id(),
"label": kind.label(),
"installed": at.is_some(),
// Which binary was used (Task 9.9), when one was found.
"path": at.map(|p| p.to_string_lossy().into_owned()),
"installHint": kind.install_hint(),
"hasEffort": kind.has_effort(),
})
})
.collect();
serde_json::json!(entries)
}
// `cmd /c ver` prints e.g. `Microsoft Windows [Version 10.0.26300.1234]`.
fn windows_build() -> Option<u32> {
let out = std::process::Command::new("cmd").args(["/c", "ver"]).output().ok()?;
let text = String::from_utf8_lossy(&out.stdout);
let version = text.split("Version ").nth(1)?;
version.split('.').nth(2)?.trim().parse().ok()
}
// Sends the agent's output as raw bytes and its state changes as JSON, on the
// page's latest channel. Nothing is sent while no page has registered one.
// The meter sees every output and state change too, page or no page.
fn page_sink(page: PageChannel, meter: Arc<Mutex<Meter>>) -> Sink {
Arc::new(move |event| {
if let Ok(mut meter) = meter.lock() {
match &event {
AgentEvent::Output(bytes) => meter.add_output(bytes),
AgentEvent::State(snapshot) => {
let running = snapshot.state == AgentState::Running;
meter.observe(snapshot.generation, running);
meter.set_kind(snapshot.kind);
}
}
}
let Ok(guard) = page.lock() else { return };
let Some(channel) = guard.as_ref() else { return };
let body = match event {
AgentEvent::Output(bytes) => InvokeResponseBody::Raw(bytes),
AgentEvent::State(snapshot) => match serde_json::to_string(&snapshot) {
Ok(json) => InvokeResponseBody::Json(json),
Err(_) => return,
},
};
let _ = channel.send(body);
})
}
// The manager for the current project, made on first use. A manager for a
// different folder replaces an idle one.
fn agent_for_project(state: &AppState) -> Result<Arc<AgentManager>, String> {
let dir = {
let project = state.project.lock().map_err(|e| e.to_string())?;
project.as_ref().map(|p| p.dir.clone()).ok_or("no project folder chosen")?
};
let mut guard = state.agent.lock().map_err(|e| e.to_string())?;
if let Some(agent) = guard.as_ref() {
// Only the same folder's manager is reused: an active agent for a
// folder the project has since moved away from must not be handed
// back as if it belonged to the new one.
if agent.folder() == &dir {
return Ok(Arc::clone(agent));
}
}
let sink = page_sink(Arc::clone(&state.page), Arc::clone(&state.context));
let agent = Arc::new(AgentManager::new(dir, sink));
// A Restart leaves the brief for the dashboard, from the console that is running now.
let console = Arc::clone(&state.console);
agent.set_before_fresh(Arc::new(move || {
let sid = console.lock().ok()?.as_ref()?.session().sid.clone();
restart_brief::note_for_restart(&sid)
}));
*guard = Some(Arc::clone(&agent));
Ok(agent)
}
fn current_agent(state: &AppState) -> Option<Arc<AgentManager>> {
state.agent.lock().ok().and_then(|guard| guard.clone())
}
// The origin the app page has, which the console must allow as its frame
// parent. In a release build that is a constant, but `tauri dev` serves the
// page from a loopback dev server, so the window is asked for its real URL.
fn window_origin(app: &tauri::AppHandle) -> String {
app.get_webview_window("main")
.and_then(|window| window.url().ok())
.and_then(|url| origin_of(url.as_str()))
.unwrap_or_else(|| app_origin().to_string())
}
// Gives the agent the in-app signal: this window's announce endpoint and the
// origin its console must allow. The agent's own `open` then shows its pages
// here (it asks the window which session is current). Without an endpoint the
// agent gets nothing and opens pages the plain way.
fn sync_agent_env(app: &tauri::AppHandle) {
let state = app.state::<AppState>();
let Some(agent) = current_agent(&state) else { return };
let env = match state.announce.lock().ok() {
Some(guard) => guard
.as_ref()
.map(|server| server.agent_env(&window_origin(app), &app.package_info().version.to_string()))
.unwrap_or_default(),
None => Vec::new(),
};
agent.set_env(env);
}
#[tauri::command]
fn agent_start(
app: tauri::AppHandle,
state: State<'_, AppState>,
kind: String,
model: Option<String>,
effort: Option<String>,
mode: String,
cols: u16,
rows: u16,
on_output: Channel<InvokeResponseBody>,
) -> Result<(), String> {
let kind = AgentKind::from_id(&kind).ok_or_else(|| format!("unknown agent: {kind}"))?;
let mode = PermissionMode::from_id(&mode).ok_or_else(|| format!("unknown permission mode: {mode}"))?;
*state.page.lock().map_err(|e| e.to_string())? = Some(on_output);
let agent = agent_for_project(&state)?;
agent.resize(cols, rows)?;
sync_agent_env(&app);
agent.start(kind, model, effort, mode, None)?;
// A settings file that cannot be written must not stop the agent.
if let Some(file) = settings::settings_file() {
let _ = settings::save_last_agent(&file, kind);
}
Ok(())
}
#[tauri::command]
fn agent_input(state: State<'_, AppState>, data: String) -> Result<(), String> {
if let Ok(mut meter) = state.context.lock() {
meter.add(data.len());
}
match current_agent(&state) {
Some(agent) => agent.input(data.as_bytes()),
None => Ok(()),
}
}
#[tauri::command]
fn agent_resize(state: State<'_, AppState>, cols: u16, rows: u16) -> Result<(), String> {
match current_agent(&state) {
Some(agent) => agent.resize(cols, rows),
None => Ok(()),
}
}
#[tauri::command]
fn agent_restart(state: State<'_, AppState>) -> Result<(), String> {
current_agent(&state).ok_or("no agent has been started")?.restart()
}
#[tauri::command]
fn agent_state(state: State<'_, AppState>) -> serde_json::Value {
match current_agent(&state) {
Some(agent) => serde_json::to_value(agent.snapshot()).unwrap_or_default(),
None => idle_snapshot_json(),
}
}
fn idle_snapshot_json() -> serde_json::Value {
serde_json::json!({ "state": "idle", "kind": null, "mode": null, "generation": 0 })
}
/// A page that just mounted (a reload, or this window's first paint while an
/// agent survived it) registers its output channel here instead of through
/// `agent_start`, which would try to start a second agent. Replays the
/// current generation's recent output on it at once, so the terminal does
/// not come up blank, and returns the same shape `agent_state` does.
#[tauri::command]
fn agent_reattach(state: State<'_, AppState>, on_output: Channel<InvokeResponseBody>) -> Result<serde_json::Value, String> {
let agent = current_agent(&state);
*state.page.lock().map_err(|e| e.to_string())? = Some(on_output.clone());
if let Some(agent) = &agent {
let replay = agent.replay();
if !replay.is_empty() {
let _ = on_output.send(InvokeResponseBody::Raw(replay));
}
}
Ok(match &agent {
Some(agent) => serde_json::to_value(agent.snapshot()).unwrap_or_default(),
None => idle_snapshot_json(),
})
}
// The bar's meter, polled at most every two seconds: how full the running
// agent's context looks, labeled by how it was read.
#[tauri::command]
fn agent_context(state: State<'_, AppState>) -> serde_json::Value {
let (estimate, kind, since) = match state.context.lock() {
Ok(meter) => (meter.read(), meter.kind(), meter.since()),
Err(_) => (ContextReading::Unknown, None, None),
};
let agent = current_agent(&state);
let model = agent.as_ref().and_then(|agent| agent.model_and_effort().0);
// Claude's own transcript, or Codex's own log, is read when there is one;
// an unknown reading from either falls back to the labeled estimate.
// Nothing is read while no agent runs.
let reading = match (estimate, kind, agent, since) {
(ContextReading::Unknown, _, _, _) => ContextReading::Unknown,
(_, Some(AgentKind::Claude), Some(agent), Some(since)) => {
// `window_for` always has a window for Claude; the fallback here only
// guards against a future change to that rule.
let window = context::window_for(kind, model.as_deref()).unwrap_or(context::ESTIMATE_TOKEN_WINDOW);
let claude = ClaudeReader { projects_dir: claude_projects_dir(), folder: agent.folder().clone(), since, window };
match claude.read() {
ContextReading::Unknown => estimate,
read => read,
}
}
(_, Some(AgentKind::Codex), Some(agent), Some(since)) => {
let codex = CodexReader {
sessions_dir: codex_sessions_dir(),
folder: agent.folder().clone(),
since,
};
match codex.read() {
ContextReading::Unknown => estimate,
read => read,
}
}
_ => estimate,
};
serde_json::to_value(reading).unwrap_or_default()
}
// Claude Code's transcripts folder: `CLAUDE_CONFIG_DIR` when it is set, else `~/.claude`.
fn claude_projects_dir() -> std::path::PathBuf {
let home = std::env::var_os("CLAUDE_CONFIG_DIR")
.map(std::path::PathBuf::from)
.or_else(|| std::env::home_dir().map(|home| home.join(".claude")))
.unwrap_or_default();
home.join("projects")
}
// Codex's sessions folder: `CODEX_HOME` when it is set, else `~/.codex`.
fn codex_sessions_dir() -> std::path::PathBuf {
let home = std::env::var_os("CODEX_HOME")
.map(std::path::PathBuf::from)
.or_else(|| std::env::home_dir().map(|home| home.join(".codex")))
.unwrap_or_default();
home.join("sessions")
}
// Asks before quitting while an agent runs; "no" keeps the app open.
fn confirm_quit(app: &tauri::AppHandle) {
let app = app.clone();
app.dialog()
.message("An agent is still running. Quit and stop it?")
.title("Quit Plan2Code")
.kind(MessageDialogKind::Warning)
.buttons(MessageDialogButtons::YesNo)
.show({
let app = app.clone();
move |quit| {
if quit {
quit_app(&app);
}
}
});
}
fn agent_is_active(app: &tauri::AppHandle) -> bool {
current_agent(&app.state::<AppState>()).is_some_and(|agent| agent.is_active())
}
// Stops the agent, then the console, then exits.
fn quit_app(app: &tauri::AppHandle) {
let state = app.state::<AppState>();
if let Some(agent) = current_agent(&state) {
agent.stop();
}
if let Ok(mut guard) = state.console.lock() {
if let Some(mut console) = guard.take() {
let _ = console.stop();
}
}
app.exit(0);
}
/// What the page draws its bar from: the folder (or that none is chosen yet)
/// and the agent the picker starts on.
#[tauri::command]
fn app_state(state: State<'_, AppState>) -> serde_json::Value {
let project = state.project.lock().ok().and_then(|p| p.clone());
let settings_file = settings::settings_file();
// The agent picked in the launcher starts the bar's picker, ahead of the app's own last one.
let last_agent = state
.launch
.agent
.or_else(|| settings_file.as_ref().and_then(|file| settings::load_last_agent(file)))
.or_else(project::remembered_agent);
let nudge = settings_file
.as_ref()
.map_or(settings::DEFAULT_NUDGE_PERCENT, |file| settings::load_nudge_percent(file));
let term_panel = settings_file.as_ref().map_or(
settings::TermPanelSettings {
dock: settings::DEFAULT_TERM_DOCK.to_string(),
fraction: settings::DEFAULT_TERM_FRACTION,
collapsed: false,
},
|file| settings::load_term_panel(file),
);
let first_run_done = settings_file.as_ref().is_some_and(|file| settings::load_first_run_done(file));
serde_json::json!({
"projectDir": project.as_ref().map(|p| p.dir.to_string_lossy().into_owned()),
"projectDirSource": project.as_ref().map(|p| p.source),
"lastAgent": last_agent.map(|kind| kind.id()),
"launchModel": state.launch.model,
"contextNudgePercent": nudge,
// Task 1.7 already exits before the window opens on a missing or too-old
// Node, so this is always a pass; the checklist's Node row just names it.
"nodeVersion": state.node_version,
"nodeBinary": state.node_binary,
"skillsVersion": versions::installed_skills_version(),
"firstRunDone": first_run_done,
// The launcher always passes `--project` alongside `--agent`, so an
// explicit `--agent` means skip straight to starting it, no checklist
// or launch card shown.
"autoStart": state.launch.agent.map(|kind| kind.id()),
"termPanel": term_panel,
})
}
/// The terminal pane's toolbar remembers its shape here: dock side, size and
/// whether it was left collapsed. A settings file that cannot be written is
/// reported to the caller; the pane itself keeps working either way.
#[tauri::command]
fn save_term_panel(dock: String, fraction: f64, collapsed: bool) -> Result<(), String> {
let file = settings::settings_file().ok_or("no home folder found")?;
settings::save_term_panel(&file, &dock, fraction, collapsed)
}
/// The first-run checklist passed once: later launches go straight to the
/// launch card (Task 9.4).
#[tauri::command]
fn save_first_run_done() -> Result<(), String> {
let file = settings::settings_file().ok_or("no home folder found")?;
settings::save_first_run_done(&file)
}
/// The app's version (`tauri.conf.json`'s, which Tauri puts in the package info) beside the
/// installed skills' version. The bar shows its Update line when they differ (FR-14).
#[tauri::command]
fn version_status(app: tauri::AppHandle) -> versions::VersionStatus {
versions::status(&app.package_info().version.to_string(), versions::installed_skills_version())
}
/// What `update_skills` resolves with: the installer's last line, and the version status
/// re-read afterwards, so the bar can say plainly whether the mismatch is actually gone.
#[derive(serde::Serialize)]
struct UpdateOutcome {
message: String,
status: versions::VersionStatus,
}
/// Run the existing installer's update, pinned to this app's own release tag. Only the bar's
/// button asks for it: never silently. `progress` carries each line of the installer's own
/// output live, for the bar to show while it runs.
#[tauri::command]
async fn update_skills(app: tauri::AppHandle, progress: Channel<String>) -> Result<UpdateOutcome, String> {
let version = app.package_info().version.to_string();
let message = tauri::async_runtime::spawn_blocking(move || {
versions::run_update(&version, |line| {
let _ = progress.send(line.to_string());
})
})
.await
.map_err(|e| e.to_string())??;
let status = versions::status(&app.package_info().version.to_string(), versions::installed_skills_version());
Ok(UpdateOutcome { message, status })
}
/// The OS folder picker, shown when no folder is known; a choice becomes the
/// launcher's remembered folder.
#[tauri::command]
fn pick_project_folder(app: tauri::AppHandle, state: State<'_, AppState>) -> Result<Option<String>, String> {
let picked = app
.dialog()
.file()
.blocking_pick_folder()
.and_then(|p| p.as_path().map(|dir| dir.to_path_buf()));
let Some(dir) = picked else {
return Ok(None);
};
let choice = project::remember_folder(&dir)?;
let text = choice.dir.to_string_lossy().into_owned();
*state.project.lock().map_err(|e| e.to_string())? = Some(choice);
Ok(Some(text))
}
/// Stops the old project's agent and console and clears both from state, so
/// neither `agent_for_project` nor `console_start` can hand either back once
/// the project has moved on (Task 9.5). The old agent's `Idle` state still
/// reaches the page's current channel here; only after that does this take
/// the channel away.
fn teardown_project(state: &AppState) -> Result<(), String> {
if let Some(agent) = current_agent(state) {
agent.stop();
}
*state.agent.lock().map_err(|e| e.to_string())? = None;
*state.page.lock().map_err(|e| e.to_string())? = None;
if let Ok(mut guard) = state.console.lock() {
if let Some(mut sup) = guard.take() {
let _ = sup.stop();
}
}
Ok(())
}
/// Switch to a different project folder, picked fresh: a clean teardown of
/// the old one (its agent stopped, its console stopped) before the new
/// folder is remembered, so `agent_for_project` and `console_start` start
/// fresh for it rather than reusing anything from the one just left. Picking
/// nothing (cancelled) leaves the current project untouched. One project per
/// window stays; this replaces it, it does not add a second.
#[tauri::command]
fn change_project(app: tauri::AppHandle, state: State<'_, AppState>) -> Result<Option<String>, String> {
let picked = app
.dialog()
.file()
.blocking_pick_folder()
.and_then(|p| p.as_path().map(|dir| dir.to_path_buf()));
let Some(dir) = picked else {
return Ok(None);
};
teardown_project(&state)?;
let choice = project::remember_folder(&dir)?;
let text = choice.dir.to_string_lossy().into_owned();
*state.project.lock().map_err(|e| e.to_string())? = Some(choice);
Ok(Some(text))
}
/// The console the agent opened, alive and as it is now, or restarted on the
/// same session when it died. The app never starts a dashboard of its own:
/// the agent does, by running the skill, and announces it. Nothing to show yet
/// is an error the page words for the person.
#[tauri::command]
fn console_start(state: State<'_, AppState>) -> Result<serde_json::Value, String> {
console_start_impl(&state)
}
fn console_start_impl(state: &AppState) -> Result<serde_json::Value, String> {
let mut guard = state.console.lock().map_err(|e| e.to_string())?;
let sup = guard.as_mut().ok_or("The agent has not opened the dashboard yet.")?;
if !sup.health() {
sup.restart_if_dead()?;
}
serde_json::to_value(sup.session()).map_err(|e| e.to_string())
}
/// The bar's poll: none (never started or stopped on purpose), running, or
/// dead (started but not answering).
#[tauri::command]
fn console_status(state: State<'_, AppState>) -> serde_json::Value {
let Ok(guard) = state.console.lock() else {
return serde_json::json!({ "state": "none", "url": null });
};
match guard.as_ref() {
Some(sup) if sup.stopped() => serde_json::json!({ "state": "none", "url": null }),
Some(sup) if sup.health() => serde_json::json!({ "state": "running", "url": sup.session().url }),
Some(sup) => serde_json::json!({ "state": "dead", "url": sup.session().url }),
None => serde_json::json!({ "state": "none", "url": null }),
}
}
#[tauri::command]
fn console_stop(state: State<'_, AppState>) -> Result<(), String> {
let mut guard = state.console.lock().map_err(|e| e.to_string())?;
if let Some(mut sup) = guard.take() {
sup.stop()?;
}
Ok(())
}
fn main() {
// Without Node 18+ the console and skills cannot run: say so and stop (FR-13).
let status = node_check::check_node();
let node_problem = node_check::problem_message(&status);
let node_version = match &status {
node_check::NodeStatus::Ok(version) => Some(version.clone()),
_ => None,
};
let node_binary = node_version.as_ref().and_then(|_| node_check::node_binary_path());
let args = std::env::args().collect::<Vec<_>>();
tauri::Builder::default()
.plugin(tauri_plugin_dialog::init())
.manage(AppState {
project: Mutex::new(project::resolve(&args)),
launch: project::launch_choice(&args),
node_version,
node_binary,
..AppState::default()
})
.invoke_handler(tauri::generate_handler![
platform_info,
agent_availability,
agent_start,
agent_input,
agent_resize,
agent_restart,
agent_state,
agent_reattach,
agent_context,
app_state,
save_term_panel,
save_first_run_done,
version_status,
update_skills,
pick_project_folder,
change_project,
console_start,
console_status,
console_stop
])
.on_window_event(|window, event| {
// Closing with an agent running asks first; "no" keeps the window open.
if let tauri::WindowEvent::CloseRequested { api, .. } = event {
let app = window.app_handle().clone();
if agent_is_active(&app) {
api.prevent_close();
confirm_quit(&app);
}
}
})
.setup(move |app| {
// Pages the agent's `open` announces: the supervisor and the agent's
// environment follow the console, and the page frame shows it.
let handle = app.handle().clone();
let server = AnnounceServer::start(Arc::new(move |notice| {
let state = handle.state::<AppState>();
if let Ok(mut guard) = state.console.lock() {
match guard.as_mut() {
Some(sup) => sup.follow(&notice.url, &notice.sid),
// The agent started the console: the app owns its stop from here.
None => {
let dir = state.project.lock().ok().and_then(|p| p.as_ref().map(|p| p.dir.clone()));
if let Some(dir) = dir {
if let Ok(sup) =
ConsoleSupervisor::adopt(dir, window_origin(&handle), &notice.url, &notice.sid)
{
*guard = Some(sup);
}
}
}
}
}
let _ = handle.emit("console-page", &notice);
}));
match server {
Ok(server) => {
if let Ok(mut slot) = app.state::<AppState>().announce.lock() {
*slot = Some(server);
}
}
// Without it the agent opens pages the plain way; nothing else breaks.
Err(error) => eprintln!("plan2code: no announce endpoint: {error}"),
}
if let Some(message) = &node_problem {
app.dialog()
.message(message)
.title("Plan2Code needs Node.js")
.kind(MessageDialogKind::Error)
.blocking_show();
std::process::exit(1);
}
Ok(())
})
.build(tauri::generate_context!())
.expect("error while building the Plan2Code app")
.run(|app, event| {
// Cmd+Q and the app menu's Quit on macOS end the app without closing the
// window first. An exit asked for in code (`code` is set) is `quit_app`'s own.
if let tauri::RunEvent::ExitRequested { api, code: None, .. } = event {
if agent_is_active(app) {
api.prevent_exit();
confirm_quit(app);
}
}
});
}
#[cfg(test)]
mod tests {
use super::*;
use std::path::PathBuf;
fn state_for(dir: &str) -> AppState {
AppState {
project: Mutex::new(Some(ProjectDir { dir: PathBuf::from(dir), source: project::ProjectSource::Picked })),
..AppState::default()
}
}
// Covers the folder-matching rule itself (Task 9.5's fix); a genuinely
// *active* agent for the old folder needs a real spawned process to
// prove against, which only the `tests/agent_manager.rs` harness (the
// fake agent) can build — out of reach for an inline test here. The
// by-hand "Change project" check (RELEASE-CHECKLIST.md) covers that case.
#[test]
fn a_different_folder_never_gets_the_old_manager_back() {
let state = state_for("project-a");
let first = agent_for_project(&state).expect("a manager for project-a");
assert_eq!(first.folder(), &PathBuf::from("project-a"));
// The project moved on; the slot still holds project-a's manager
// until a fresh call replaces it.
*state.project.lock().unwrap() = Some(ProjectDir { dir: PathBuf::from("project-b"), source: project::ProjectSource::Picked });
let second = agent_for_project(&state).expect("a manager for project-b");
assert_eq!(second.folder(), &PathBuf::from("project-b"));
assert!(!Arc::ptr_eq(&first, &second), "project-a's manager must never stand in for project-b's");
}
#[test]
fn the_same_folder_reuses_the_same_manager() {
let state = state_for("project-a");
let first = agent_for_project(&state).unwrap();
let second = agent_for_project(&state).unwrap();
assert!(Arc::ptr_eq(&first, &second), "the same folder should not make a second manager");
}
fn have_node() -> bool {
std::process::Command::new("node").arg("--version").output().map(|o| o.status.success()).unwrap_or(false)
}
/// A real console, the same way `tests/console_supervisor.rs` sets one
/// up: `PLAN2CODE_CONSOLE_DIR` points at the repo's own console source,
/// `PLAN2CODE_CONSOLE_HOME` keeps its session files out of the real one.
fn real_console() -> Option<plan2code_app_lib::console_supervisor::ConsoleSupervisor> {
if !have_node() {
eprintln!("skipping: node is not on PATH");
return None;
}
let console_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../src/web-console");
if !console_dir.join("console.mjs").is_file() {
eprintln!("skipping: console source missing at {}", console_dir.display());
return None;
}
let pid = std::process::id();
let project = std::env::temp_dir().join(format!("p2c-main-test-project-{pid}"));
std::fs::create_dir_all(&project).unwrap();
std::env::set_var("PLAN2CODE_CONSOLE_DIR", &console_dir);
std::env::set_var("PLAN2CODE_CONSOLE_HOME", std::env::temp_dir().join(format!("p2c-main-test-home-{pid}")));
std::env::set_var("PLAN2CODE_NO_BROWSER", "1");
Some(
plan2code_app_lib::console_supervisor::ConsoleSupervisor::start(
project,
plan2code_app_lib::console_supervisor::app_origin().to_string(),
)
.expect("start a real console for the test"),
)
}
#[test]
fn teardown_clears_the_console_so_console_start_refuses_not_reconnects() {
let Some(sup) = real_console() else { return };
let state = state_for("project-a");
*state.console.lock().unwrap() = Some(sup);
assert!(console_start_impl(&state).is_ok(), "console_start should work before the project changes");
teardown_project(&state).unwrap();
let err = console_start_impl(&state).expect_err("console_start must refuse, not reconnect to the old session");
assert!(err.contains("has not opened the dashboard"), "unexpected message: {err:?}");
}
}
+175
View File
@@ -0,0 +1,175 @@
//! The Node 18+ check (FR-13). The console and the skills run on Node, so the
//! app refuses to start without it and says what to install.
//!
//! An app started from the Dock, Finder or a `.desktop` file, rather than a
//! terminal, inherits a minimal PATH: none of nvm, Homebrew or Volta's
//! directories, which a login shell's own profile adds. `resolved_path`
//! (Task 9.9) is what every process this app spawns (the console, an update,
//! an agent CLI) should run with, not the bare inherited one; `node_check`,
//! `console_supervisor`, `versions` and `agents` all use it.
use std::process::Command;
use std::sync::OnceLock;
pub const MIN_NODE_MAJOR: u32 = 18;
#[derive(Debug, PartialEq, Eq)]
pub enum NodeStatus {
Ok(String),
TooOld(String),
Missing,
}
/// Major version from `node --version` output such as `v20.11.1`.
pub fn parse_node_major(output: &str) -> Option<u32> {
let text = output.trim().strip_prefix('v')?;
text.split('.').next()?.parse().ok()
}
/// Classify the output of `node --version`.
pub fn classify(output: &str) -> NodeStatus {
let version = output.trim().to_string();
match parse_node_major(output) {
Some(major) if major >= MIN_NODE_MAJOR => NodeStatus::Ok(version),
Some(_) => NodeStatus::TooOld(version),
None => NodeStatus::Missing,
}
}
pub fn check_node() -> NodeStatus {
match Command::new("node").env("PATH", resolved_path()).arg("--version").output() {
Ok(out) if out.status.success() => classify(&String::from_utf8_lossy(&out.stdout)),
_ => NodeStatus::Missing,
}
}
/// `--node <path>` or `--node=<path>`: the launcher's own `node`, already
/// resolved under the person's real shell. Only its directory is used here,
/// so it joins the PATH the normal way rather than replacing every lookup.
fn node_override_dir(args: &[String]) -> Option<String> {
let mut i = 1; // args[0] is the program name
while i < args.len() {
let value = if args[i] == "--node" {
args.get(i + 1).cloned()
} else {
args[i].strip_prefix("--node=").map(str::to_string)
};
if let Some(path) = value.filter(|v| !v.is_empty()) {
return std::path::Path::new(&path).parent().map(|dir| dir.to_string_lossy().into_owned());
}
i += 1;
}
None
}
/// The login shell's own PATH: running it as a login shell sources
/// `.zprofile`, `.bash_profile` or `.profile`, which a GUI launch never does.
/// Windows sets PATH outside any shell's startup files, so this is unix only.
#[cfg(unix)]
fn login_shell_path() -> Option<String> {
let shell = std::env::var("SHELL").unwrap_or_else(|_| "/bin/sh".to_string());
let out = Command::new(&shell).args(["-lc", "echo $PATH"]).output().ok()?;
let path = String::from_utf8_lossy(&out.stdout).trim().to_string();
(out.status.success() && !path.is_empty()).then_some(path)
}
/// The PATH every process this app spawns should run with: an explicit
/// `--node`'s directory first, then (macOS and Linux) the login shell's own
/// PATH, then this process's own PATH, each included only once. Resolved
/// once per launch: none of these change while the app runs.
pub fn resolved_path() -> &'static str {
static PATH: OnceLock<String> = OnceLock::new();
PATH.get_or_init(|| {
let args: Vec<String> = std::env::args().collect();
let inherited = std::env::var("PATH").unwrap_or_default();
let mut parts = Vec::new();
if let Some(dir) = node_override_dir(&args) {
parts.push(dir);
}
#[cfg(unix)]
if let Some(login) = login_shell_path() {
parts.push(login);
}
if !inherited.is_empty() {
parts.push(inherited);
}
parts.join(if cfg!(windows) { ";" } else { ":" })
})
}
/// Where `node` actually resolves, with `resolved_path`: for the first-run
/// checklist to name (Task 9.9), not for `check_node` itself to decide with.
pub fn node_binary_path() -> Option<String> {
let (program, arg) = if cfg!(windows) { ("where", "node") } else { ("which", "node") };
let out = Command::new(program).env("PATH", resolved_path()).arg(arg).output().ok()?;
if !out.status.success() {
return None;
}
String::from_utf8_lossy(&out.stdout).lines().next().map(str::trim).filter(|s| !s.is_empty()).map(str::to_string)
}
/// The plain message shown when the check fails; `None` when Node is fine.
pub fn problem_message(status: &NodeStatus) -> Option<String> {
match status {
NodeStatus::Ok(_) => None,
NodeStatus::TooOld(v) => Some(format!(
"Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and this computer has {v}.\n\nInstall the current LTS release from https://nodejs.org and start Plan2Code again."
)),
NodeStatus::Missing => Some(format!(
"Plan2Code needs Node.js {MIN_NODE_MAJOR} or newer, and it was not found.\n\nInstall the current LTS release from https://nodejs.org and start Plan2Code again."
)),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn accepts_node_18_and_newer() {
assert_eq!(classify("v18.0.0\n"), NodeStatus::Ok("v18.0.0".into()));
assert_eq!(classify("v20.11.1"), NodeStatus::Ok("v20.11.1".into()));
assert_eq!(classify("v24.12.0\r\n"), NodeStatus::Ok("v24.12.0".into()));
}
#[test]
fn rejects_node_older_than_18() {
assert_eq!(classify("v16.20.2"), NodeStatus::TooOld("v16.20.2".into()));
assert_eq!(classify("v17.9.1"), NodeStatus::TooOld("v17.9.1".into()));
}
#[test]
fn treats_garbage_as_missing() {
assert_eq!(classify("not a version"), NodeStatus::Missing);
assert_eq!(classify(""), NodeStatus::Missing);
assert_eq!(classify("v"), NodeStatus::Missing);
assert_eq!(classify("vx.1.2"), NodeStatus::Missing);
}
#[test]
fn message_only_for_a_problem() {
assert!(problem_message(&NodeStatus::Ok("v20.0.0".into())).is_none());
assert!(problem_message(&NodeStatus::Missing).unwrap().contains("nodejs.org"));
assert!(problem_message(&NodeStatus::TooOld("v16.0.0".into())).unwrap().contains("v16.0.0"));
}
fn args(list: &[&str]) -> Vec<String> {
std::iter::once("plan2code-app").chain(list.iter().copied()).map(str::to_string).collect()
}
#[test]
fn the_node_override_names_its_directory_in_both_forms() {
let want = if cfg!(windows) { "C:\\nvm\\v20" } else { "/home/x/.nvm/v20" };
let bin = if cfg!(windows) { "C:\\nvm\\v20\\node.exe" } else { "/home/x/.nvm/v20/node" };
assert_eq!(node_override_dir(&args(&["--node", bin])).as_deref(), Some(want));
assert_eq!(node_override_dir(&args(&[&format!("--node={bin}")])).as_deref(), Some(want));
}
#[test]
fn no_override_or_a_missing_value_is_none() {
assert_eq!(node_override_dir(&args(&[])), None);
assert_eq!(node_override_dir(&args(&["--node"])), None);
assert_eq!(node_override_dir(&args(&["--node="])), None);
assert_eq!(node_override_dir(&args(&["--agent", "claude"])), None);
}
}
+191
View File
@@ -0,0 +1,191 @@
//! Which project folder the app works on: the folder the launcher passes in,
//! else the one the launcher remembers, else the person picks. The launcher's
//! memory is `~/.plan2code/launcher.json` (`lastFolder`, `lastCli`), shared so
//! the app and `plan2code` agree on both.
use std::path::{Path, PathBuf};
use serde::Serialize;
use crate::agents::AgentKind;
/// Where the project folder came from, in the order it is tried.
#[derive(Clone, Copy, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ProjectSource {
Argument,
Remembered,
Picked,
}
#[derive(Clone)]
pub struct ProjectDir {
pub dir: PathBuf,
pub source: ProjectSource,
}
fn err<E: std::fmt::Display>(e: E) -> String {
e.to_string()
}
fn launcher_file() -> Option<PathBuf> {
Some(std::env::home_dir()?.join(".plan2code").join("launcher.json"))
}
fn read_launcher() -> serde_json::Map<String, serde_json::Value> {
launcher_file()
.and_then(|file| std::fs::read_to_string(file).ok())
.and_then(|text| serde_json::from_str(&text).ok())
.unwrap_or_default()
}
/// The folder the launcher remembers, when it is still a directory.
fn remembered_folder() -> Option<PathBuf> {
let dir = PathBuf::from(read_launcher().get("lastFolder")?.as_str()?);
dir.is_dir().then_some(dir)
}
/// The agent the launcher last ran. The bar's picker starts on it until the
/// app has a choice of its own (`settings.rs`).
pub fn remembered_agent() -> Option<AgentKind> {
AgentKind::from_id(read_launcher().get("lastCli")?.as_str()?)
}
/// `--project <dir>`, `--project=<dir>` or the first bare argument: the folder
/// the launcher passed in when it started the app.
fn argument_folder(args: &[String]) -> Option<PathBuf> {
let mut i = 1; // args[0] is the program name
while i < args.len() {
let arg = &args[i];
if arg == "--agent" || arg == "--model" {
// Their values are not folders, even when a folder of that name exists.
i += 2;
continue;
}
if arg == "--project" {
i += 1;
if i < args.len() {
let dir = PathBuf::from(&args[i]);
return dir.is_dir().then_some(dir);
}
} else if let Some(dir) = arg.strip_prefix("--project=") {
let dir = PathBuf::from(dir);
return dir.is_dir().then_some(dir);
} else if !arg.starts_with('-') {
let dir = PathBuf::from(arg);
return dir.is_dir().then_some(dir);
}
i += 1;
}
None
}
/// What the launcher chose before it opened the app: `--agent <id>` and `--model <id>` (or the
/// `=` forms). An unknown agent or a missing value is ignored, and a model only counts beside
/// an agent, since a model name belongs to one agent.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct LaunchChoice {
pub agent: Option<AgentKind>,
pub model: Option<String>,
}
fn flag_value(args: &[String], flag: &str) -> Option<String> {
let prefix = format!("{flag}=");
let mut i = 1;
while i < args.len() {
let arg = &args[i];
if arg == flag {
return args.get(i + 1).filter(|v| !v.is_empty() && !v.starts_with('-')).cloned();
}
if let Some(value) = arg.strip_prefix(&prefix) {
return (!value.is_empty()).then(|| value.to_string());
}
i += 1;
}
None
}
pub fn launch_choice(args: &[String]) -> LaunchChoice {
let agent = flag_value(args, "--agent").and_then(|id| AgentKind::from_id(&id.to_lowercase()));
let model = agent.and_then(|_| flag_value(args, "--model"));
LaunchChoice { agent, model }
}
/// The folder to open on: the launcher's argument wins, then its memory, then
/// nothing (the page asks with the folder picker).
pub fn resolve(args: &[String]) -> Option<ProjectDir> {
if let Some(dir) = argument_folder(args) {
return Some(ProjectDir { dir, source: ProjectSource::Argument });
}
remembered_folder().map(|dir| ProjectDir { dir, source: ProjectSource::Remembered })
}
/// A folder the person picked becomes the remembered one, so the next start
/// (app or launcher) opens on it. The launcher's other keys are kept.
pub fn remember_folder(dir: &Path) -> Result<ProjectDir, String> {
let file = launcher_file().ok_or("no home folder found")?;
let mut state = read_launcher();
state.insert(
"lastFolder".to_string(),
serde_json::Value::String(dir.to_string_lossy().into_owned()),
);
if let Some(parent) = file.parent() {
std::fs::create_dir_all(parent).map_err(err)?;
}
let json = serde_json::to_string_pretty(&serde_json::Value::Object(state)).map_err(err)?;
std::fs::write(file, json).map_err(err)?;
Ok(ProjectDir { dir: dir.to_path_buf(), source: ProjectSource::Picked })
}
#[cfg(test)]
mod tests {
use super::*;
fn args(list: &[&str]) -> Vec<String> {
std::iter::once("plan2code-app").chain(list.iter().copied()).map(str::to_string).collect()
}
#[test]
fn the_launcher_choice_reads_agent_and_model_in_both_forms() {
let want = LaunchChoice { agent: Some(AgentKind::Codex), model: Some("gpt-5".into()) };
assert_eq!(launch_choice(&args(&["--project", ".", "--agent", "codex", "--model", "gpt-5"])), want);
assert_eq!(launch_choice(&args(&["--agent=codex", "--model=gpt-5"])), want);
assert_eq!(launch_choice(&args(&["--agent", "CODEX", "--model", "gpt-5"])), want);
}
#[test]
fn an_agent_alone_is_a_choice_and_a_model_alone_is_not() {
assert_eq!(
launch_choice(&args(&["--agent", "claude"])),
LaunchChoice { agent: Some(AgentKind::Claude), model: None }
);
assert_eq!(launch_choice(&args(&["--model", "opus"])), LaunchChoice::default());
}
#[test]
fn an_unknown_agent_or_a_missing_value_is_ignored() {
assert_eq!(launch_choice(&args(&["--agent", "emacs", "--model", "x"])), LaunchChoice::default());
assert_eq!(launch_choice(&args(&["--agent"])), LaunchChoice::default());
assert_eq!(launch_choice(&args(&["--agent", "--model", "x"])), LaunchChoice::default());
assert_eq!(launch_choice(&args(&["--agent=", "--model=x"])), LaunchChoice::default());
assert_eq!(launch_choice(&args(&[])), LaunchChoice::default());
assert_eq!(
launch_choice(&args(&["--agent", "devin", "--model"])),
LaunchChoice { agent: Some(AgentKind::Devin), model: None }
);
}
#[test]
fn the_agent_and_model_values_are_never_taken_for_a_folder() {
// A folder named like the agent exists right here, so a bare-argument reading would pick it.
let cwd = std::env::temp_dir().join(format!("p2c-project-args-{}", std::process::id()));
std::fs::create_dir_all(cwd.join("codex")).unwrap();
let named = cwd.join("codex").to_string_lossy().into_owned();
let found = argument_folder(&args(&["--agent", &named, "--model", &named]));
assert_eq!(found, None);
// Beside --project, the folder wins as before.
let found = argument_folder(&args(&["--project", &named, "--agent", "codex"]));
assert_eq!(found, Some(cwd.join("codex")));
let _ = std::fs::remove_dir_all(&cwd);
}
}
+280
View File
@@ -0,0 +1,280 @@
//! A command running in a pseudo-terminal, so full-screen agent programs see a
//! real terminal. Knows nothing about Tauri: output goes to a callback.
use std::io::{Read, Write};
use std::path::PathBuf;
#[cfg(unix)]
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc;
use std::sync::{Arc, Mutex};
use std::thread;
use std::time::{Duration, Instant};
use portable_pty::{native_pty_system, Child, ChildKiller, CommandBuilder, MasterPty, PtySize};
/// Output is sent to the page at most once per this long, so a flood of text
/// does not stall the web view.
pub const BATCH_INTERVAL: Duration = Duration::from_millis(16);
/// On macOS and Linux the kill is a hang-up signal, which a program can ignore.
/// This long after it, a command that is still running is killed outright.
#[cfg(unix)]
const HANGUP_GRACE: Duration = Duration::from_secs(2);
/// What to run, where, and how big the terminal starts.
pub struct StartOptions {
pub program: String,
pub args: Vec<String>,
pub env: Vec<(String, String)>,
pub cwd: Option<PathBuf>,
pub cols: u16,
pub rows: u16,
}
/// A running command in a pseudo-terminal.
pub struct PtyHost {
master: Mutex<Box<dyn MasterPty + Send>>,
writer: Mutex<Box<dyn Write + Send>>,
child: Arc<Mutex<Box<dyn Child + Send + Sync>>>,
killer: Mutex<Box<dyn ChildKiller + Send + Sync>>,
#[cfg(unix)]
pid: Option<u32>,
/// Set once the command has been waited for, so a late kill never signals
/// a process id that may have been given to something else.
#[cfg(unix)]
exited: Arc<AtomicBool>,
/// A Windows Job Object the spawned process was assigned to, so ending
/// it (`kill`, or this host simply being dropped) ends every process
/// still in it, not just the one directly spawned: a `cmd /c` npm shim's
/// real agent process is a child of that child, invisible to a plain
/// `TerminateProcess`. A raw handle value, not `HANDLE`, so the struct
/// stays `Send`. `None` when the job could not be made; `kill` then
/// falls back to ending just the one process, as before.
#[cfg(windows)]
job: Option<usize>,
}
fn size(cols: u16, rows: u16) -> PtySize {
PtySize { rows, cols, pixel_width: 0, pixel_height: 0 }
}
fn err<E: std::fmt::Display>(e: E) -> String {
e.to_string()
}
impl PtyHost {
/// Start the command. `on_output` gets the output in chunks, at most one per
/// `BATCH_INTERVAL`, until the command's output ends.
pub fn start<F>(options: StartOptions, mut on_output: F) -> Result<PtyHost, String>
where
F: FnMut(Vec<u8>) + Send + 'static,
{
let pair = native_pty_system()
.openpty(size(options.cols, options.rows))
.map_err(err)?;
let mut command = CommandBuilder::new(&options.program);
command.args(&options.args);
// What the agent CLIs expect from a terminal that can show colour.
command.env("TERM", "xterm-256color");
command.env("COLORTERM", "truecolor");
for (key, value) in &options.env {
command.env(key, value);
}
if let Some(cwd) = &options.cwd {
command.cwd(cwd);
}
let child = pair.slave.spawn_command(command).map_err(err)?;
// The child holds its own end; keeping ours open would stop the reader
// from ever seeing the end of the output.
drop(pair.slave);
let mut reader = pair.master.try_clone_reader().map_err(err)?;
let writer = pair.master.take_writer().map_err(err)?;
let killer = child.clone_killer();
#[cfg(unix)]
let pid = child.process_id();
#[cfg(windows)]
let job = windows_job::assign(child.as_ref());
// One thread reads as fast as the terminal produces; another gathers
// what arrived into one send per interval.
let (tx, rx) = mpsc::channel::<Vec<u8>>();
thread::spawn(move || {
let mut buf = [0u8; 8192];
loop {
match reader.read(&mut buf) {
Ok(0) | Err(_) => break,
Ok(n) => {
if tx.send(buf[..n].to_vec()).is_err() {
break;
}
}
}
}
});
thread::spawn(move || {
// Blocks for the first chunk, then collects until the interval is up.
while let Ok(first) = rx.recv() {
let mut batch = first;
let deadline = Instant::now() + BATCH_INTERVAL;
loop {
let left = deadline.saturating_duration_since(Instant::now());
if left.is_zero() {
break;
}
match rx.recv_timeout(left) {
Ok(more) => batch.extend_from_slice(&more),
Err(mpsc::RecvTimeoutError::Timeout) => break,
Err(mpsc::RecvTimeoutError::Disconnected) => {
on_output(batch);
return;
}
}
}
on_output(batch);
}
});
Ok(PtyHost {
master: Mutex::new(pair.master),
writer: Mutex::new(writer),
child: Arc::new(Mutex::new(child)),
killer: Mutex::new(killer),
#[cfg(unix)]
pid,
#[cfg(unix)]
exited: Arc::new(AtomicBool::new(false)),
#[cfg(windows)]
job,
})
}
/// Send keystrokes (or pasted text) to the command.
pub fn write(&self, bytes: &[u8]) -> Result<(), String> {
let mut writer = self.writer.lock().map_err(err)?;
writer.write_all(bytes).map_err(err)?;
writer.flush().map_err(err)
}
/// Tell the command the terminal changed size.
pub fn resize(&self, cols: u16, rows: u16) -> Result<(), String> {
self.master.lock().map_err(err)?.resize(size(cols, rows)).map_err(err)
}
/// End the command. Safe to call while `wait` is blocked in another thread.
pub fn kill(&self) -> Result<(), String> {
let result = self.killer.lock().map_err(err)?.kill().map_err(err);
// The job object, when there is one, ends the whole process tree:
// killing just the directly spawned process (above) leaves a
// `cmd /c` npm shim's real agent process running.
#[cfg(windows)]
if let Some(job) = self.job {
windows_job::terminate(job);
}
// portable-pty 0.9 on Windows has the TerminateProcess result inverted: it
// returns Err (a stale error) when the kill worked and Ok when it failed, so
// its answer says nothing there.
if cfg!(windows) {
return Ok(());
}
// portable-pty only sends SIGHUP on macOS and Linux; follow it with
// SIGKILL if the command is still there after the grace period.
#[cfg(unix)]
if let Some(pid) = self.pid {
let exited = Arc::clone(&self.exited);
thread::spawn(move || {
thread::sleep(HANGUP_GRACE);
if !exited.load(Ordering::SeqCst) {
// SAFETY: plain signal to a process id the command still holds.
unsafe { libc::kill(pid as i32, libc::SIGKILL) };
}
});
}
result
}
/// Block until the command ends and return its exit code. A command ended by
/// a signal reports 1.
pub fn wait(&self) -> Result<u32, String> {
self.wait_described().map(|(code, _)| code)
}
/// Like `wait`, with the name of the signal that ended the command, when
/// there was one (macOS and Linux).
pub fn wait_described(&self) -> Result<(u32, Option<String>), String> {
let child = Arc::clone(&self.child);
let mut child = child.lock().map_err(err)?;
let status = child.wait().map_err(err)?;
#[cfg(unix)]
self.exited.store(true, Ordering::SeqCst);
Ok((status.exit_code(), status.signal().map(str::to_string)))
}
}
/// Closing the job's last handle ends every process still in it (`job` was
/// made with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`): a safety net for a host
/// dropped without `kill` ever being called, on top of `kill`'s own explicit
/// `TerminateJobObject`.
#[cfg(windows)]
impl Drop for PtyHost {
fn drop(&mut self) {
if let Some(job) = self.job {
windows_job::close(job);
}
}
}
/// A Windows Job Object groups a spawned process with every process it goes
/// on to spawn itself (a child joins its parent's job automatically, unless
/// it asks to break away, which `cmd /c` does not), so ending the job ends
/// the whole tree. Nothing here calls back into `PtyHost`.
#[cfg(windows)]
mod windows_job {
use portable_pty::Child;
use std::os::windows::io::RawHandle;
use winapi::shared::minwindef::DWORD;
use winapi::shared::ntdef::HANDLE;
use winapi::um::handleapi::CloseHandle;
use winapi::um::jobapi2::{AssignProcessToJobObject, CreateJobObjectW, SetInformationJobObject, TerminateJobObject};
use winapi::um::winnt::{JobObjectExtendedLimitInformation, JOBOBJECT_EXTENDED_LIMIT_INFORMATION, JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE};
/// Create a job, set it to kill everything in it when its last handle
/// closes, and assign `child` to it. `None` on any failure (an older
/// Windows without nested-job support, say): `kill` then falls back to
/// ending just the one process, as it always did.
pub fn assign(child: &(dyn Child + Send + Sync)) -> Option<usize> {
let process: RawHandle = child.as_raw_handle()?;
unsafe {
let job = CreateJobObjectW(std::ptr::null_mut(), std::ptr::null());
if job.is_null() {
return None;
}
let mut info: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = std::mem::zeroed();
info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
let set = SetInformationJobObject(
job,
JobObjectExtendedLimitInformation,
&mut info as *mut _ as *mut _,
std::mem::size_of::<JOBOBJECT_EXTENDED_LIMIT_INFORMATION>() as DWORD,
);
if set == 0 || AssignProcessToJobObject(job, process as HANDLE) == 0 {
CloseHandle(job);
return None;
}
Some(job as usize)
}
}
pub fn terminate(job: usize) {
unsafe {
TerminateJobObject(job as HANDLE, 1);
}
}
pub fn close(job: usize) {
unsafe {
CloseHandle(job as HANDLE);
}
}
}
@@ -0,0 +1,182 @@
//! What a Restart leaves for the dashboard: the restart brief, written as a
//! pick-up handoff, so the fresh agent (which starts on the plain `/plan2code`
//! prompt and lands on the dashboard) finds the chip waiting. Nothing new is
//! stored anywhere: the brief is built from the session's files each time.
use std::path::Path;
use std::sync::Mutex;
use chrono::{DateTime, Local};
use serde_json::Value;
use crate::brief;
use crate::handoff;
use crate::session_reader;
pub const READY_NOTE: &str = "Brief ready on the dashboard";
/// The handoff the last Restart wrote. The next Restart retires it if the person
/// has not picked it up, so unused briefs do not pile up as chips.
static LAST_BRIEF: Mutex<Option<String>> = Mutex::new(None);
/// The skill named on a handoff record for a workflow `brief::skill_for_workflow`
/// does not map, such as `dashboard`: the console's own name for that pseudo-skill.
const UNMAPPED_SKILL: &str = "plan2code";
/// Write the brief for session `sid` as a handoff. A workflow with no mapped
/// skill (a dashboard, or one not yet known) still gets a short, honest chip
/// rather than nothing. Returns the handoff's id, or `None` when there is
/// truly nothing to write (the session names no worktree is an error, not a
/// `None`, since that is a broken session rather than an empty one).
pub fn leave_brief(console_home: &Path, handoffs: &Path, sid: &str, when: DateTime<Local>) -> Result<Option<String>, String> {
let session = session_reader::load(console_home, sid).map_err(|e| e.to_string())?;
let state = &session.state;
let workflow = text(state, "workflow").unwrap_or("");
let skill = brief::skill_for_workflow(workflow);
let worktree = text(state, "worktree").ok_or("the session names no worktree")?;
let project = text(state, "project").unwrap_or(worktree);
let spec = text(state, "specDir").filter(|s| valid_spec(s));
let spec_dir = spec.map(|s| Path::new(worktree).join(s));
let git = brief::git_summary(Path::new(worktree));
let events = session_reader::read_ndjson(&session.dir.join("events.ndjson"));
let body = brief::build_brief(state, spec_dir.as_deref(), git.as_ref(), &events);
let title = match skill {
Some(skill) => match spec {
Some(spec) => format!("Restart of {skill} on {spec}"),
None => format!("Restart of {skill}"),
},
None => format!("Restart while on {workflow}"),
};
let record = handoff::Record { title: &title, worktree, project, spec, workflow, skill: skill.unwrap_or(UNMAPPED_SKILL) };
handoff::write(handoffs, when, &record, &body).map(Some)
}
/// The bar's line for a Restart on session `sid`, written to the real console
/// and handoff folders. `None` when there was nothing to leave.
pub fn note_for_restart(sid: &str) -> Option<String> {
let console_home = session_reader::console_home()?;
let handoffs = handoff::handoffs_dir()?;
match leave_brief(&console_home, &handoffs, sid, handoff::now()) {
Ok(Some(id)) => {
let previous = LAST_BRIEF.lock().ok().and_then(|mut last| last.replace(id.clone()));
if let Some(previous) = previous.filter(|p| *p != id) {
let _ = handoff::retire_if_unused(&handoffs, &previous);
}
Some(READY_NOTE.to_string())
}
Ok(None) => None,
Err(why) => Some(format!("The brief could not be written: {why}")),
}
}
fn text<'a>(state: &'a Value, key: &str) -> Option<&'a str> {
state.get(key).and_then(Value::as_str).filter(|s| !s.is_empty())
}
fn valid_spec(spec: &str) -> bool {
spec.strip_prefix("specs/").is_some_and(|name| !name.is_empty() && name != "." && name != ".." && !name.contains(['/', '\\']))
}
#[cfg(test)]
mod tests {
use super::*;
use chrono::TimeZone;
use std::fs;
use std::path::PathBuf;
fn fixture(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("plan2code-restart-{}-{name}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
dir
}
/// A console home with one session on `workflow`, and a project with a spec.
fn session(name: &str, workflow: &str, spec: Option<&str>) -> (PathBuf, PathBuf, PathBuf) {
let root = fixture(name);
let home = root.join("console");
let project = root.join("project");
let dir = home.join("sessions").join("s1");
fs::create_dir_all(&dir).unwrap();
fs::create_dir_all(&project).unwrap();
let state = serde_json::json!({
"schema": 1,
"workflow": workflow,
"specDir": spec,
"worktree": project.to_string_lossy(),
"project": project.to_string_lossy(),
"headline": { "stage": "Phase 5: Restart brief", "cleared": 4, "total": 11 },
"items": [],
});
fs::write(dir.join("state.json"), state.to_string()).unwrap();
(home, project, root.join("handoffs"))
}
fn when() -> DateTime<Local> {
Local.with_ymd_and_hms(2026, 10, 21, 14, 5, 0).unwrap()
}
#[test]
fn a_mid_implement_session_leaves_a_pick_up_the_dashboard_lists() {
let (home, project, handoffs) = session("pickup", "implement", Some("specs/feature"));
let spec = project.join("specs").join("feature");
fs::create_dir_all(&spec).unwrap();
fs::write(spec.join("overview.md"), "- [/] [Phase 5: Restart](./phase-5.md)\n").unwrap();
fs::write(spec.join("phase-5.md"), "- [ ] **Task 5.1:** Create the reader\n").unwrap();
let id = leave_brief(&home, &handoffs, "s1", when()).unwrap().expect("a handoff");
assert_eq!(id, "2026-10-21-1405-handoff");
let record: Value = serde_json::from_str(&fs::read_to_string(handoffs.join(format!("{id}.json"))).unwrap()).unwrap();
assert_eq!(record["workflow"], "implement");
assert_eq!(record["spec"], "specs/feature");
let doc = fs::read_to_string(handoffs.join(format!("{id}.md"))).unwrap();
assert!(doc.contains("## Next task\n\nTask 5.1: Create the reader"));
assert!(doc.contains("Phase 5: Restart brief: 4 of 11 done."));
}
#[test]
fn a_dashboard_session_still_leaves_a_chip() {
let (home, _, handoffs) = session("dashboard", "dashboard", None);
let id = leave_brief(&home, &handoffs, "s1", when()).unwrap().expect("a handoff");
let record: Value = serde_json::from_str(&fs::read_to_string(handoffs.join(format!("{id}.json"))).unwrap()).unwrap();
assert_eq!(record["title"], "Restart while on dashboard");
assert_eq!(record["skill"], "plan2code");
assert_eq!(record["workflow"], "dashboard");
let doc = fs::read_to_string(handoffs.join(format!("{id}.md"))).unwrap();
assert!(doc.contains("- Workflow: `dashboard`"));
assert!(doc.contains("## Next task\n\nOpen the dashboard"));
}
#[test]
fn the_brief_carries_the_agent_activity_and_recent_events() {
let (home, _project, handoffs) = session("activity", "implement", None);
let dir = home.join("sessions").join("s1");
let mut state: Value = serde_json::from_str(&fs::read_to_string(dir.join("state.json")).unwrap()).unwrap();
state["agent"] = serde_json::json!({ "status": "working", "activity": "Spiking Claude's context signal (Task 10.1)" });
fs::write(dir.join("state.json"), state.to_string()).unwrap();
fs::write(
dir.join("events.ndjson"),
"{\"at\":\"2026-10-23T01:08:47.152Z\",\"type\":\"post\",\"items\":0}\n{\"at\":\"2026-10-23T01:09:00.000Z\",\"type\":\"consume\",\"kind\":\"submit\"}\n",
)
.unwrap();
let id = leave_brief(&home, &handoffs, "s1", when()).unwrap().expect("a handoff");
let doc = fs::read_to_string(handoffs.join(format!("{id}.md"))).unwrap();
assert!(doc.contains("Doing: Spiking Claude's context signal (Task 10.1)"));
assert!(doc.contains("## Recent activity\n\n- post (0 items)\n- consume: submit\n"));
}
#[test]
fn a_session_that_does_not_exist_is_an_error_not_a_brief() {
let (home, _, handoffs) = session("missing", "implement", None);
assert!(leave_brief(&home, &handoffs, "nope", when()).is_err());
}
#[test]
fn a_spec_that_is_not_one_folder_is_left_out_of_the_record() {
let (home, _, handoffs) = session("badspec", "pathfinder", Some("specs/a/b"));
let id = leave_brief(&home, &handoffs, "s1", when()).unwrap().unwrap();
let record: Value = serde_json::from_str(&fs::read_to_string(handoffs.join(format!("{id}.json"))).unwrap()).unwrap();
assert!(record["spec"].is_null());
}
}
@@ -0,0 +1,217 @@
//! Reads a console session's files without disturbing them. The console owns
//! `~/.plan2code/console/sessions/<sid>/`: this module only opens files for
//! reading. It never creates, locks, renames or removes anything there, so the
//! console's own writes are never blocked by the app (NFR-3).
use std::io;
use std::path::{Path, PathBuf};
use std::thread::sleep;
use std::time::Duration;
use serde_json::Value;
/// The one session schema this reader understands (`state.json`'s `schema`).
pub const SCHEMA: u64 = 1;
/// How many times a locked `state.json` is tried again. The console renames
/// the file while it writes, so Windows can refuse a read for a moment.
const LOCKED_RETRIES: u32 = 5;
const RETRY_EVERY: Duration = Duration::from_millis(50);
/// Windows: ERROR_SHARING_VIOLATION and ERROR_LOCK_VIOLATION.
const WINDOWS_SHARING: [i32; 2] = [32, 33];
#[derive(Debug, PartialEq, Eq)]
pub enum ReadError {
/// The file is not there.
Missing(PathBuf),
/// Still locked after every retry.
Busy,
/// Some other read failure.
Unreadable(String),
/// Not a JSON object.
Malformed(String),
/// A schema this app does not read.
Schema(u64),
}
impl std::fmt::Display for ReadError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
ReadError::Missing(file) => write!(f, "{} is missing", file.display()),
ReadError::Busy => write!(f, "session busy: the console is still writing its state"),
ReadError::Unreadable(why) => write!(f, "could not read the session: {why}"),
ReadError::Malformed(why) => write!(f, "the session file is not valid: {why}"),
ReadError::Schema(found) => {
write!(f, "session schema {found} is not supported (this app reads schema {SCHEMA})")
}
}
}
}
/// A session's `state.json`, read once. Nothing else in the session folder is
/// read here: the Ask chat lives in `chat.ndjson` and stays out of the brief.
pub struct Session {
pub dir: PathBuf,
pub state: Value,
}
/// `~/.plan2code/console`, or `PLAN2CODE_CONSOLE_HOME` when the console is
/// relocated (the same rule the console and the supervisor follow).
pub fn console_home() -> Option<PathBuf> {
if let Ok(home) = std::env::var("PLAN2CODE_CONSOLE_HOME") {
return Some(PathBuf::from(home));
}
Some(std::env::home_dir()?.join(".plan2code").join("console"))
}
/// `<console home>/sessions/<sid>`.
pub fn session_dir(console_home: &Path, sid: &str) -> PathBuf {
console_home.join("sessions").join(sid)
}
/// Open and parse the session `sid` under `console_home`.
pub fn load(console_home: &Path, sid: &str) -> Result<Session, ReadError> {
let dir = session_dir(console_home, sid);
let text = read_with_retry(&dir.join("state.json"), |file| std::fs::read_to_string(file))?;
let state = parse_state(&text)?;
Ok(Session { dir, state })
}
/// Read `file` through `read`. A locked file (a sharing or permission error) is
/// tried again up to `LOCKED_RETRIES` times, `RETRY_EVERY` apart; then the
/// session is reported busy. `read` is a parameter so a test can stand in a
/// reader that fails a few times.
pub fn read_with_retry<F>(file: &Path, mut read: F) -> Result<String, ReadError>
where
F: FnMut(&Path) -> io::Result<String>,
{
let mut retries = 0;
loop {
match read(file) {
Ok(text) => return Ok(text),
Err(e) if e.kind() == io::ErrorKind::NotFound => return Err(ReadError::Missing(file.to_path_buf())),
Err(e) if is_locked(&e) => {
if retries == LOCKED_RETRIES {
return Err(ReadError::Busy);
}
retries += 1;
sleep(RETRY_EVERY);
}
Err(e) => return Err(ReadError::Unreadable(e.to_string())),
}
}
}
fn is_locked(e: &io::Error) -> bool {
e.kind() == io::ErrorKind::PermissionDenied || e.raw_os_error().is_some_and(|code| WINDOWS_SHARING.contains(&code))
}
/// Parse `state.json` text: a JSON object whose `schema` is `SCHEMA`.
pub fn parse_state(text: &str) -> Result<Value, ReadError> {
let state: Value = serde_json::from_str(text).map_err(|e| ReadError::Malformed(e.to_string()))?;
if !state.is_object() {
return Err(ReadError::Malformed("not a JSON object".to_string()));
}
let schema = state
.get("schema")
.and_then(Value::as_u64)
.ok_or_else(|| ReadError::Malformed("no schema number".to_string()))?;
if schema != SCHEMA {
return Err(ReadError::Schema(schema));
}
Ok(state)
}
/// Each line of a `.ndjson` file that parses as JSON, in order. A partial last
/// line (the console was mid-write) does not parse and is dropped; so is any
/// other line that does not parse. A missing file has no lines.
pub fn read_ndjson(file: &Path) -> Vec<Value> {
match std::fs::read_to_string(file) {
Ok(text) => parse_ndjson(&text),
Err(_) => Vec::new(),
}
}
pub fn parse_ndjson(text: &str) -> Vec<Value> {
text.lines().filter(|line| !line.trim().is_empty()).filter_map(|line| serde_json::from_str(line).ok()).collect()
}
#[cfg(test)]
mod tests {
use super::*;
use std::cell::Cell;
fn fixture(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("plan2code-reader-{}-{name}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
dir
}
const STATE: &str = r#"{"schema": 1, "sid": "s1", "workflow": "implement", "specDir": "specs/x"}"#;
#[test]
fn a_complete_session_loads() {
let home = fixture("complete");
let dir = session_dir(&home, "s1");
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("state.json"), STATE).unwrap();
let session = load(&home, "s1").unwrap();
assert_eq!(session.state["workflow"], "implement");
assert_eq!(session.dir, dir);
}
#[test]
fn a_partial_last_line_is_dropped() {
let lines = parse_ndjson("{\"a\":1}\n{\"b\":2}\n{\"c\":");
assert_eq!(lines, vec![serde_json::json!({"a": 1}), serde_json::json!({"b": 2})]);
}
#[test]
fn a_missing_ndjson_file_has_no_lines() {
assert!(read_ndjson(&fixture("no-ndjson").join("events.ndjson")).is_empty());
}
#[test]
fn a_missing_state_file_is_reported() {
let home = fixture("missing");
match load(&home, "nope") {
Err(ReadError::Missing(file)) => assert!(file.ends_with("state.json")),
other => panic!("expected Missing, got {:?}", other.map(|s| s.dir)),
}
}
#[test]
fn another_schema_is_rejected_with_a_clear_message() {
let err = parse_state(r#"{"schema": 2}"#).unwrap_err();
assert_eq!(err, ReadError::Schema(2));
assert!(err.to_string().contains("schema 2 is not supported"));
}
#[test]
fn a_locked_file_that_frees_up_on_the_third_retry_is_read() {
let tries = Cell::new(0);
let text = read_with_retry(Path::new("state.json"), |_| {
tries.set(tries.get() + 1);
if tries.get() < 4 {
Err(io::Error::from(io::ErrorKind::PermissionDenied))
} else {
Ok(STATE.to_string())
}
});
assert_eq!(text.unwrap(), STATE);
assert_eq!(tries.get(), 4);
}
#[test]
fn a_file_that_stays_locked_is_busy_not_a_failure() {
let tries = Cell::new(0);
let result = read_with_retry(Path::new("state.json"), |_| {
tries.set(tries.get() + 1);
Err(io::Error::from_raw_os_error(32))
});
assert_eq!(result, Err(ReadError::Busy));
assert_eq!(tries.get(), LOCKED_RETRIES + 1);
}
}
+242
View File
@@ -0,0 +1,242 @@
//! The app's own settings file, `~/.plan2code/app.json`. It holds what only the
//! app remembers (today: the agent last picked in the bar). The console's
//! folders under `~/.plan2code/console/` are never written to from here.
use std::path::{Path, PathBuf};
use crate::agents::AgentKind;
const LAST_AGENT_KEY: &str = "lastAgent";
const NUDGE_KEY: &str = "CONTEXT_NUDGE_PERCENT";
const TERM_DOCK_KEY: &str = "termDock";
const TERM_FRACTION_KEY: &str = "termFraction";
const TERM_COLLAPSED_KEY: &str = "termCollapsed";
const FIRST_RUN_DONE_KEY: &str = "firstRunDone";
/// The context percent at which the bar suggests a Restart, when the file
/// names no other.
pub const DEFAULT_NUDGE_PERCENT: u8 = 70;
/// The terminal pane's remembered shape: which edge it docks to, how much of
/// the window it takes (a fraction, not collapsed or maximized), and whether
/// it was left collapsed.
#[derive(Clone, Debug, PartialEq, serde::Serialize)]
pub struct TermPanelSettings {
pub dock: String,
pub fraction: f64,
pub collapsed: bool,
}
pub const DEFAULT_TERM_DOCK: &str = "bottom";
pub const DEFAULT_TERM_FRACTION: f64 = 0.25;
const TERM_FRACTION_MIN: f64 = 0.05;
const TERM_FRACTION_MAX: f64 = 0.9;
pub fn settings_file() -> Option<PathBuf> {
Some(std::env::home_dir()?.join(".plan2code").join("app.json"))
}
fn read(file: &Path) -> serde_json::Map<String, serde_json::Value> {
std::fs::read_to_string(file)
.ok()
.and_then(|text| serde_json::from_str(&text).ok())
.unwrap_or_default()
}
/// The agent saved in `file`, when it still names one the app can run.
pub fn load_last_agent(file: &Path) -> Option<AgentKind> {
AgentKind::from_id(read(file).get(LAST_AGENT_KEY)?.as_str()?)
}
/// The context percent that triggers the Restart suggestion. A value outside
/// 1 to 100, or one that is not a number, means the default.
pub fn load_nudge_percent(file: &Path) -> u8 {
read(file)
.get(NUDGE_KEY)
.and_then(|value| value.as_u64())
.filter(|percent| (1..=100).contains(percent))
.map_or(DEFAULT_NUDGE_PERCENT, |percent| percent as u8)
}
/// Save the pick, keeping any other key the file holds.
pub fn save_last_agent(file: &Path, kind: AgentKind) -> Result<(), String> {
let mut settings = read(file);
settings.insert(LAST_AGENT_KEY.to_string(), serde_json::Value::String(kind.id().to_string()));
write(file, settings)
}
/// The terminal pane's shape, from the file or the defaults. A dock other
/// than `bottom` or `right`, or a fraction outside its range, is the default.
pub fn load_term_panel(file: &Path) -> TermPanelSettings {
let settings = read(file);
let dock = settings
.get(TERM_DOCK_KEY)
.and_then(|v| v.as_str())
.filter(|d| *d == "bottom" || *d == "right")
.unwrap_or(DEFAULT_TERM_DOCK)
.to_string();
let fraction = settings
.get(TERM_FRACTION_KEY)
.and_then(|v| v.as_f64())
.filter(|f| (TERM_FRACTION_MIN..=TERM_FRACTION_MAX).contains(f))
.unwrap_or(DEFAULT_TERM_FRACTION);
let collapsed = settings.get(TERM_COLLAPSED_KEY).and_then(|v| v.as_bool()).unwrap_or(false);
TermPanelSettings { dock, fraction, collapsed }
}
/// Save the terminal pane's shape, keeping any other key the file holds. An
/// invalid dock or an out-of-range fraction is rejected rather than saved.
pub fn save_term_panel(file: &Path, dock: &str, fraction: f64, collapsed: bool) -> Result<(), String> {
if dock != "bottom" && dock != "right" {
return Err(format!("unknown dock: {dock}"));
}
if !(TERM_FRACTION_MIN..=TERM_FRACTION_MAX).contains(&fraction) {
return Err(format!("fraction out of range: {fraction}"));
}
let mut settings = read(file);
settings.insert(TERM_DOCK_KEY.to_string(), serde_json::Value::String(dock.to_string()));
settings.insert(
TERM_FRACTION_KEY.to_string(),
serde_json::Number::from_f64(fraction).map(serde_json::Value::Number).unwrap_or(serde_json::Value::Null),
);
settings.insert(TERM_COLLAPSED_KEY.to_string(), serde_json::Value::Bool(collapsed));
write(file, settings)
}
/// Whether the first-run checklist has already passed once. Once it has,
/// later launches go straight to the launch card (Task 9.4).
pub fn load_first_run_done(file: &Path) -> bool {
read(file).get(FIRST_RUN_DONE_KEY).and_then(|v| v.as_bool()).unwrap_or(false)
}
/// Remember that the checklist passed, keeping any other key the file holds.
pub fn save_first_run_done(file: &Path) -> Result<(), String> {
let mut settings = read(file);
settings.insert(FIRST_RUN_DONE_KEY.to_string(), serde_json::Value::Bool(true));
write(file, settings)
}
fn write(file: &Path, settings: serde_json::Map<String, serde_json::Value>) -> Result<(), String> {
if let Some(parent) = file.parent() {
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
}
let json = serde_json::to_string_pretty(&serde_json::Value::Object(settings)).map_err(|e| e.to_string())?;
std::fs::write(file, json).map_err(|e| e.to_string())
}
#[cfg(test)]
mod tests {
use super::*;
fn temp_file(name: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("plan2code-settings-{}-{name}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
dir.join("app.json")
}
#[test]
fn a_missing_file_has_no_choice() {
assert_eq!(load_last_agent(&temp_file("missing")), None);
}
#[test]
fn the_choice_round_trips_and_other_keys_survive() {
let file = temp_file("round-trip");
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, r#"{"other": 1}"#).unwrap();
save_last_agent(&file, AgentKind::Devin).unwrap();
assert_eq!(load_last_agent(&file), Some(AgentKind::Devin));
assert!(std::fs::read_to_string(&file).unwrap().contains("\"other\""));
let _ = std::fs::remove_dir_all(file.parent().unwrap());
}
#[test]
fn the_nudge_defaults_to_seventy() {
assert_eq!(load_nudge_percent(&temp_file("nudge-missing")), 70);
}
#[test]
fn the_nudge_reads_a_named_percent() {
let file = temp_file("nudge-set");
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, r#"{"CONTEXT_NUDGE_PERCENT": 85}"#).unwrap();
assert_eq!(load_nudge_percent(&file), 85);
let _ = std::fs::remove_dir_all(file.parent().unwrap());
}
#[test]
fn a_nudge_outside_one_to_one_hundred_or_not_a_number_is_the_default() {
for text in [
r#"{"CONTEXT_NUDGE_PERCENT": 0}"#,
r#"{"CONTEXT_NUDGE_PERCENT": 150}"#,
r#"{"CONTEXT_NUDGE_PERCENT": "high"}"#,
] {
let file = temp_file("nudge-bad");
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, text).unwrap();
assert_eq!(load_nudge_percent(&file), 70, "{text}");
let _ = std::fs::remove_dir_all(file.parent().unwrap());
}
}
#[test]
fn an_unknown_agent_is_ignored() {
let file = temp_file("unknown");
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, r#"{"lastAgent": "nope"}"#).unwrap();
assert_eq!(load_last_agent(&file), None);
let _ = std::fs::remove_dir_all(file.parent().unwrap());
}
#[test]
fn the_term_panel_defaults_to_bottom_at_a_quarter() {
let want = TermPanelSettings { dock: "bottom".into(), fraction: 0.25, collapsed: false };
assert_eq!(load_term_panel(&temp_file("term-missing")), want);
}
#[test]
fn the_term_panel_round_trips_and_other_keys_survive() {
let file = temp_file("term-round-trip");
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, r#"{"other": 1}"#).unwrap();
save_term_panel(&file, "right", 0.4, true).unwrap();
assert_eq!(
load_term_panel(&file),
TermPanelSettings { dock: "right".into(), fraction: 0.4, collapsed: true }
);
assert!(std::fs::read_to_string(&file).unwrap().contains("\"other\""));
let _ = std::fs::remove_dir_all(file.parent().unwrap());
}
#[test]
fn an_unknown_dock_or_an_out_of_range_fraction_is_refused() {
let file = temp_file("term-bad-save");
assert!(save_term_panel(&file, "top", 0.3, false).is_err());
assert!(save_term_panel(&file, "bottom", 0.0, false).is_err());
assert!(save_term_panel(&file, "bottom", 1.0, false).is_err());
assert!(!file.exists());
}
#[test]
fn first_run_is_not_done_until_it_is_saved() {
let file = temp_file("first-run");
assert!(!load_first_run_done(&file));
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, r#"{"other": 1}"#).unwrap();
save_first_run_done(&file).unwrap();
assert!(load_first_run_done(&file));
assert!(std::fs::read_to_string(&file).unwrap().contains("\"other\""));
let _ = std::fs::remove_dir_all(file.parent().unwrap());
}
#[test]
fn a_bad_dock_or_out_of_range_fraction_on_disk_reads_as_the_default() {
let file = temp_file("term-bad-load");
std::fs::create_dir_all(file.parent().unwrap()).unwrap();
std::fs::write(&file, r#"{"termDock": "top", "termFraction": 5}"#).unwrap();
let loaded = load_term_panel(&file);
assert_eq!(loaded.dock, "bottom");
assert_eq!(loaded.fraction, 0.25);
let _ = std::fs::remove_dir_all(file.parent().unwrap());
}
}
+273
View File
@@ -0,0 +1,273 @@
//! Whether the app and the installed skills are on the same Plan2Code version, and the
//! one-click way to bring them level. The app's own version is the one in `tauri.conf.json`
//! (Tauri reads it into the package info); the skills' version is the `version.json` the
//! installer writes beside the launcher in `~/.plan2code/bin/` on every install and update.
use std::io::{BufRead, BufReader};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::mpsc;
use std::time::{Duration, Instant};
use serde::Serialize;
/// How long `run_update` lets the installer run before giving up on it.
pub const UPDATE_TIMEOUT: Duration = Duration::from_secs(300);
#[derive(Debug, PartialEq, Eq, Serialize)]
pub struct VersionStatus {
pub app: String,
/// The installed skills' version, or none when it cannot be read.
pub skills: Option<String>,
/// True only when both are readable `X.Y.Z` versions and they differ: an unknown version is
/// never a reason to nag.
pub mismatch: bool,
/// Only meaningful when `mismatch` is true: the skills are ahead of this app, so another
/// Update skills run cannot fix it (a newer app is what is missing), as against the usual
/// case of the skills sitting behind the app.
pub skills_ahead: bool,
}
/// `~/.plan2code/bin`, or `PLAN2CODE_LAUNCHER_DIR` when it is set (tests only, the same
/// convention `PLAN2CODE_CONSOLE_HOME` and `PLAN2CODE_APP_AGENT_BIN` already use).
fn launcher_dir() -> Option<PathBuf> {
if let Ok(dir) = std::env::var("PLAN2CODE_LAUNCHER_DIR") {
return Some(PathBuf::from(dir));
}
Some(std::env::home_dir()?.join(".plan2code").join("bin"))
}
/// `X.Y.Z` as three numbers; anything else (a pre-release tag, a missing part) is none.
fn parse(version: &str) -> Option<(u64, u64, u64)> {
let mut parts = version.trim().split('.');
let triple = (
parts.next()?.parse().ok()?,
parts.next()?.parse().ok()?,
parts.next()?.parse().ok()?,
);
parts.next().is_none().then_some(triple)
}
/// The `version` field of a `version.json` file.
pub fn version_in(file: &Path) -> Option<String> {
let text = std::fs::read_to_string(file).ok()?;
let json: serde_json::Value = serde_json::from_str(&text).ok()?;
json.get("version")?.as_str().map(str::to_string)
}
/// The skills' version as the installer last wrote it.
pub fn installed_skills_version() -> Option<String> {
version_in(&launcher_dir()?.join("version.json"))
}
pub fn status(app: &str, skills: Option<String>) -> VersionStatus {
let (mismatch, skills_ahead) = match (parse(app), skills.as_deref().and_then(parse)) {
(Some(a), Some(s)) => (a != s, s > a),
_ => (false, false),
};
VersionStatus { app: app.to_string(), skills, mismatch, skills_ahead }
}
/// Run the existing installer's update (`plan2code update`, through the launcher's own copy),
/// which brings the skills, the launcher and the app level. Pinned to the release tag `app_version`
/// names, not `main`, so Update skills never pulls in work the app does not know about yet. Blocks
/// until it ends or `UPDATE_TIMEOUT` passes, whichever comes first; the page asks for it with a
/// click, never on its own. `on_line` is called with each line of output as it is produced, for a
/// live progress readout. Returns the installer's last non-empty line on success.
pub fn run_update(app_version: &str, on_line: impl FnMut(&str)) -> Result<String, String> {
run_update_within(app_version, UPDATE_TIMEOUT, on_line)
}
/// `run_update`, with the timeout as a parameter so a test can use a short one instead of
/// `UPDATE_TIMEOUT`'s real five minutes.
fn run_update_within(app_version: &str, timeout: Duration, mut on_line: impl FnMut(&str)) -> Result<String, String> {
let launcher = launcher_dir().ok_or("no home folder found")?.join("plan2code.js");
if !launcher.is_file() {
return Err(format!("the plan2code command is not installed ({} is missing)", launcher.display()));
}
let mut command = Command::new("node");
// A Dock or Start-menu launch often lacks nvm, Homebrew or Volta's
// directories (Task 9.9): the update script itself shells out to `npx`
// and `git`, which need a PATH that finds them too.
command.env("PATH", crate::node_check::resolved_path());
command
.arg(&launcher)
.arg("update")
.arg("--tag")
.arg(format!("v{app_version}"))
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::piped());
#[cfg(windows)]
{
use std::os::windows::process::CommandExt;
command.creation_flags(0x08000000); // CREATE_NO_WINDOW, as the console calls are
}
let mut child = command.spawn().map_err(|e| format!("could not run node: {e}"))?;
let stdout = child.stdout.take().ok_or("no stdout from the update")?;
let stderr = child.stderr.take().ok_or("no stderr from the update")?;
let (tx, rx) = mpsc::channel::<String>();
let err_tx = tx.clone();
let out_thread = std::thread::spawn(move || {
for line in BufReader::new(stdout).lines().map_while(Result::ok) {
if tx.send(line).is_err() {
break;
}
}
});
let err_thread = std::thread::spawn(move || {
for line in BufReader::new(stderr).lines().map_while(Result::ok) {
if err_tx.send(line).is_err() {
break;
}
}
});
let deadline = Instant::now() + timeout;
let poll = Duration::from_millis(200).min(timeout);
let mut last_line = String::new();
loop {
match rx.recv_timeout(poll) {
Ok(line) => {
if !line.trim().is_empty() {
last_line = line.clone();
}
on_line(&line);
}
Err(mpsc::RecvTimeoutError::Timeout) if Instant::now() < deadline => continue,
Err(mpsc::RecvTimeoutError::Timeout) => {
let _ = child.kill();
let _ = child.wait();
return Err(format!("the update timed out after {}s", timeout.as_secs()));
}
Err(mpsc::RecvTimeoutError::Disconnected) => break,
}
}
let _ = out_thread.join();
let _ = err_thread.join();
let status = child.wait().map_err(|e| e.to_string())?;
if status.success() {
Ok(last_line)
} else {
Err(format!("the update did not finish: {last_line}"))
}
}
#[cfg(test)]
mod tests {
use super::*;
fn temp_file(name: &str, content: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("p2c-versions-{}-{name}", std::process::id()));
std::fs::create_dir_all(&dir).unwrap();
let file = dir.join("version.json");
std::fs::write(&file, content).unwrap();
file
}
#[test]
fn equal_versions_do_not_mismatch() {
let s = status("3.0.0", Some("3.0.0".into()));
assert_eq!(
s,
VersionStatus { app: "3.0.0".into(), skills: Some("3.0.0".into()), mismatch: false, skills_ahead: false }
);
}
#[test]
fn different_versions_mismatch_in_either_direction() {
assert!(status("3.0.0", Some("2.11.0".into())).mismatch);
assert!(status("3.0.0", Some("3.1.0".into())).mismatch);
}
#[test]
fn skills_ahead_names_which_direction_the_mismatch_runs() {
assert!(!status("3.0.0", Some("2.11.0".into())).skills_ahead);
assert!(status("3.0.0", Some("3.1.0".into())).skills_ahead);
assert!(!status("3.0.0", Some("3.0.0".into())).skills_ahead);
}
#[test]
fn an_unknown_or_odd_version_never_mismatches() {
assert!(!status("3.0.0", None).mismatch);
assert!(!status("3.0.0", Some("3.0.0-beta".into())).mismatch);
assert!(!status("3.0", Some("3.0.0".into())).mismatch);
assert!(!status("3.0.0", Some("".into())).mismatch);
}
#[test]
fn reads_the_version_field_of_a_version_file() {
let file = temp_file("ok", r#"{ "name": "Plan2Code", "version": "2.11.0" }"#);
assert_eq!(version_in(&file).as_deref(), Some("2.11.0"));
}
#[test]
fn a_missing_or_broken_version_file_reads_as_none() {
let missing = std::env::temp_dir().join("p2c-versions-does-not-exist").join("version.json");
assert_eq!(version_in(&missing), None);
assert_eq!(version_in(&temp_file("broken", "{ not json")), None);
assert_eq!(version_in(&temp_file("nover", r#"{ "name": "x" }"#)), None);
}
// `PLAN2CODE_LAUNCHER_DIR` is process-global, so these tests serialize on it.
static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
/// Points `launcher_dir()` at a fresh folder holding a fake `plan2code.js` (plain Node
/// source, no quoting needed), runs `body`, then restores the environment.
fn with_fake_launcher<T>(name: &str, script: &str, body: impl FnOnce() -> T) -> T {
let _guard = ENV_LOCK.lock().unwrap();
let dir = std::env::temp_dir().join(format!("p2c-versions-launcher-{}-{name}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("plan2code.js"), script).unwrap();
std::env::set_var("PLAN2CODE_LAUNCHER_DIR", &dir);
let result = body();
std::env::remove_var("PLAN2CODE_LAUNCHER_DIR");
let _ = std::fs::remove_dir_all(&dir);
result
}
#[test]
fn run_update_streams_lines_live_and_returns_the_last_one_on_success() {
let lines = std::sync::Mutex::new(Vec::<String>::new());
let result = with_fake_launcher("ok", "console.log('line1'); console.log('line2');", || {
run_update_within("9.9.9", Duration::from_secs(10), |line| lines.lock().unwrap().push(line.to_string()))
});
assert_eq!(result, Ok("line2".to_string()));
assert_eq!(*lines.lock().unwrap(), vec!["line1".to_string(), "line2".to_string()]);
}
#[test]
fn run_update_pins_the_install_to_the_app_s_own_release_tag() {
let result = with_fake_launcher(
"tag",
"console.log(process.argv.slice(2).join(' '));",
|| run_update_within("9.9.9", Duration::from_secs(10), |_| {}),
);
assert_eq!(result, Ok("update --tag v9.9.9".to_string()));
}
#[test]
fn run_update_fails_with_the_installer_s_own_last_line() {
let result = with_fake_launcher("fail", "console.log('oops'); process.exit(1);", || {
run_update_within("9.9.9", Duration::from_secs(10), |_| {})
});
assert_eq!(result, Err("the update did not finish: oops".to_string()));
}
#[test]
fn run_update_gives_up_after_its_timeout_and_kills_the_child() {
let result = with_fake_launcher("hang", "setInterval(() => {}, 1000);", || {
run_update_within("9.9.9", Duration::from_millis(300), |_| {})
});
assert_eq!(result, Err("the update timed out after 0s".to_string()));
}
#[test]
fn a_missing_launcher_is_an_error_not_a_panic() {
let result = with_fake_launcher("missing", "", || {
std::fs::remove_file(launcher_dir().unwrap().join("plan2code.js")).unwrap();
run_update_within("9.9.9", Duration::from_secs(10), |_| {})
});
assert!(result.unwrap_err().contains("is missing"));
}
}
+35
View File
@@ -0,0 +1,35 @@
{
"$schema": "https://schema.tauri.app/config/2",
"productName": "Plan2Code",
"version": "3.0.0",
"identifier": "com.plan2code.app",
"build": {
"frontendDist": "../ui",
"beforeDevCommand": "node scripts/vendor.mjs",
"beforeBuildCommand": "node scripts/vendor.mjs"
},
"app": {
"windows": [
{
"title": "Plan2Code",
"width": 1280,
"height": 800,
"url": "index.html"
}
],
"security": {
"csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src ipc: http://ipc.localhost; frame-src http://127.0.0.1:*; object-src 'none'; base-uri 'none'"
},
"withGlobalTauri": true
},
"bundle": {
"active": true,
"targets": "all",
"icon": [
"icons/32x32.png",
"icons/128x128.png",
"icons/icon.icns",
"icons/icon.ico"
]
}
}
@@ -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);
}
+857
View File
@@ -0,0 +1,857 @@
// The app page: the top bar, the console dashboard in an iframe, and the
// agent's terminal panel docked at the bottom with a drag handle.
import { mountTerminal } from './terminal.js';
import { nudgeDue } from './meter.js';
const { invoke, Channel } = window.__TAURI__.core;
const projectDirEl = document.getElementById('project-dir');
const agentNameEl = document.getElementById('agent-name');
const agentStatusEl = document.getElementById('agent-status');
const restartBtn = document.getElementById('agent-restart');
const changeAgentBtn = document.getElementById('change-agent');
const changeProjectBtn = document.getElementById('change-project');
const launchCard = document.getElementById('launch-card');
const launchAgentEl = document.getElementById('launch-agent');
const launchMissingEl = document.getElementById('launch-missing');
const launchModelEl = document.getElementById('launch-model');
const launchEffortRow = document.getElementById('launch-effort-row');
const launchEffortEl = document.getElementById('launch-effort');
const launchBypassEl = document.getElementById('launch-bypass');
const launchBypassWarningEl = document.getElementById('launch-bypass-warning');
const launchStartBtn = document.getElementById('launch-start');
const firstRunEl = document.getElementById('first-run');
const firstRunListEl = document.getElementById('first-run-list');
const firstRunStartBtn = document.getElementById('first-run-start');
const meterSlot = document.getElementById('bar-slot-meter');
const nudgeEl = document.getElementById('context-nudge');
const nudgeRestartBtn = document.getElementById('context-restart');
const versionEl = document.getElementById('version-update');
const versionTextEl = document.getElementById('version-update-text');
const versionBtn = document.getElementById('version-update-button');
const versionRestartBtn = document.getElementById('version-update-restart');
const consoleStatusEl = document.getElementById('console-status');
const permissionsNoteEl = document.getElementById('permissions-note');
const consoleAgainBtn = document.getElementById('console-again');
const frame = document.getElementById('console-frame');
const stateBox = document.getElementById('dashboard-state');
const stateText = document.getElementById('dashboard-state-text');
const stateButton = document.getElementById('dashboard-state-button');
const stateCancelEl = document.getElementById('dashboard-state-cancel');
const workspaceEl = document.getElementById('workspace');
const termPanel = document.getElementById('term-panel');
const termHandle = document.getElementById('term-handle');
const termDockBtn = document.getElementById('term-dock');
const termMaximizeBtn = document.getElementById('term-maximize');
const termCollapseBtn = document.getElementById('term-collapse');
const termBadgeEl = document.getElementById('term-badge');
const currentPageEl = document.getElementById('current-page');
const STATUS_POLL_MS = 5000;
const METER_POLL_MS = 2000;
const BADGE_POLL_MS = 2000;
const MIN_PANE = 0.10;
const MAX_PANE = 0.60;
const MAXIMIZED_PANE = 0.80;
// Below this share of the window, a collapsed-or-small pane can hide a
// question the agent is quietly waiting on.
const SMALL_PANE = 0.15;
const QUIET_BADGE_MS = 10000;
const AGENT_LABELS = { claude: 'Claude Code', devin: 'Devin', codex: 'Codex' };
// Devin's model ids already carry their effort (`swe-2-high`); only these two
// take a separate effort, at the levels their own CLI documents.
const EFFORT_OPTIONS = {
claude: ['low', 'medium', 'high', 'xhigh', 'max'],
codex: ['low', 'medium', 'high'],
};
// What the Rust agent host last said: idle, running or ended.
let agent = { state: 'idle', kind: null, generation: 0 };
const agentActive = () => agent.state === 'running';
// The context percent that triggers the Restart suggestion, from the app's
// settings (main() reads it), and the agent run the suggestion was shown for:
// it appears once per run, not again after it is dismissed by a Restart.
let nudgePercent = 70;
let nudgeShownFor = null;
const terminal = await mountTerminal(document.getElementById('term'), {
onInput: (data) => {
if (agentActive()) invoke('agent_input', { data });
},
onResize: (cols, rows) => {
if (agentActive()) invoke('agent_resize', { cols, rows });
},
});
// One channel for the page's life: the agent's output arrives as bytes and its
// state changes as objects, across restarts too.
const agentChannel = new Channel();
agentChannel.onmessage = (message) => {
if (message instanceof ArrayBuffer) {
terminal.write(new Uint8Array(message));
lastOutputAt = Date.now();
updateBadge();
} else if (message && typeof message === 'object' && 'state' in message) {
applyAgentState(message);
}
};
function applyAgentState(next, { skipReset } = {}) {
const wasEnded = agent.state === 'ended';
// A new generation is a fresh agent: it starts on a clean screen. Skipped
// when catching up to an agent that was already running before this page
// mounted (a reload): its replayed output, not a blank screen, belongs here,
// and the channel that delivers it races this call, not waits for it.
const freshScreen = next.generation !== agent.generation && !skipReset;
if (freshScreen) {
terminal.reset();
lastOutputAt = Date.now();
}
agent = next;
const label = AGENT_LABELS[agent.kind] || '';
const active = agentActive();
agentNameEl.textContent = active ? label : '';
if (active) {
// Only ever auto-*hides* the card (the agent just started); it must
// never auto-*show* it on 'ended' or 'idle' — that is Change agent's
// job alone, so the card does not pop up over the dashboard uninvited.
launchCard.hidden = true;
hideFirstRun();
}
// One rule throughout: Restart while running or ended (it keeps the
// previous agent, model, effort and mode); Change agent only once ended,
// when there is a real choice to make again.
restartBtn.hidden = !(active || agent.state === 'ended');
changeAgentBtn.hidden = agent.state !== 'ended';
// Checked mode needs no banner; bypass always gets one, naming the agent it
// applies to, for exactly as long as that agent runs.
const bypassActive = active && agent.mode === 'bypass';
permissionsNoteEl.hidden = !bypassActive;
permissionsNoteEl.textContent = bypassActive ? `Permission checks are off for ${label || 'the running agent'}` : '';
restartBtn.title = agent.state === 'ended' ? 'Start a fresh agent on the same brief' : 'Replace the agent with a fresh one, on a fresh context window';
if (freshScreen || agent.state !== 'running') nudgeEl.hidden = true;
if (!agentActive()) renderMeter({ kind: 'unknown' });
// The agent is back (a fresh generation, running): the restart message stays
// on screen (restarting() below) until its dashboard page is announced.
if (restarting && freshScreen && agent.state === 'running') {
terminal.write('
[Fresh agent started. Waiting for the dashboard...]
');
}
if (agent.state === 'ended') {
agentStatusEl.textContent = `${label || 'The agent'} ended: ${agent.reason}. Nothing starts until you press Restart.`;
// A failed Restart clears the screen too, so it says so again.
if (!wasEnded || freshScreen) {
terminal.write(`\r\n[${label || 'The agent'} ended: ${agent.reason}. Press Restart in the bar to start a fresh one.]\r\n`);
}
} else {
// After a Restart the bar says what it left for the dashboard, if anything.
agentStatusEl.textContent = agent.briefNote || '';
}
agentStatusEl.title = agentStatusEl.textContent;
updateBadge();
}
// True from a confirmed Restart until the fresh agent's dashboard page is
// announced (showAnnounced below): the frame stays blanked with a message the
// whole time, since the restarted agent must boot and run the skill again
// before anything can show.
let restarting = false;
function confirmRestart(onYes) {
if (agent.state !== 'running') {
onYes();
return;
}
showState(
'Restart the agent on a fresh context window? What it was doing is not saved.',
'Restart',
() => {
restarting = true;
currentUrl = null;
frameReady = false;
currentPageEl.textContent = '';
showState('The agent is restarting on a fresh context window. Please wait for the dashboard to load.');
onYes();
},
() => (frameReady ? hideState() : showState('No dashboard has loaded yet.'))
);
}
// What the launch card offers for each agent: whether its CLI was found on
// PATH (else how to install it) and whether it takes its own effort.
let agentAvailability = {};
async function loadAgentAvailability() {
try {
const list = await invoke('agent_availability');
agentAvailability = Object.fromEntries(list.map((entry) => [entry.id, entry]));
} catch {
// Nothing to show is not a reason to block the card: Start just tries it.
agentAvailability = {};
}
}
function refreshLaunchCard() {
const kind = launchAgentEl.value;
const info = agentAvailability[kind];
const installed = info ? info.installed : true;
launchStartBtn.disabled = !installed;
launchMissingEl.hidden = installed;
launchMissingEl.replaceChildren();
if (!installed) {
const label = (info && info.label) || AGENT_LABELS[kind] || kind;
launchMissingEl.append(`${label} was not found on PATH. Install it: `);
const code = document.createElement('code');
code.textContent = (info && info.installHint) || '';
launchMissingEl.append(code);
}
const levels = EFFORT_OPTIONS[kind] || [];
launchEffortRow.hidden = levels.length === 0;
launchEffortEl.replaceChildren();
const def = document.createElement('option');
def.value = '';
def.textContent = 'Default';
launchEffortEl.append(def);
for (const level of levels) {
const option = document.createElement('option');
option.value = level;
option.textContent = level[0].toUpperCase() + level.slice(1);
launchEffortEl.append(option);
}
}
launchAgentEl.onchange = refreshLaunchCard;
launchBypassEl.onchange = () => {
launchBypassWarningEl.hidden = !launchBypassEl.checked;
};
function showLaunchCard() {
hideState();
hideFirstRun();
refreshLaunchCard();
launchCard.hidden = false;
}
function hideLaunchCard() {
launchCard.hidden = true;
}
// One row of the first-run checklist: a pass/fail mark, a title and a detail
// line (plain text or a built node, such as the CLI-by-CLI list).
function firstRunRow(pass, title, detail) {
const row = document.createElement('li');
row.className = `first-run-row ${pass ? 'is-pass' : 'is-fail'}`;
const mark = document.createElement('span');
mark.className = 'first-run-mark';
mark.textContent = pass ? '✓' : '!';
const body = document.createElement('div');
body.className = 'first-run-body';
const titleEl = document.createElement('div');
titleEl.className = 'first-run-title';
titleEl.textContent = title;
body.append(titleEl);
if (detail) {
const detailEl = document.createElement('div');
detailEl.className = 'first-run-detail';
if (typeof detail === 'string') detailEl.textContent = detail;
else detailEl.append(detail);
body.append(detailEl);
}
row.append(mark, body);
return row;
}
// Node is always a pass here: `main()` on the Rust side already exits before
// the window opens on anything else (Task 1.7), so this row is a confirmation,
// never a way to recover from a real failure.
function renderFirstRun(state) {
firstRunListEl.replaceChildren();
const nodeDetail = `${state.nodeVersion || 'found'} (18 or newer)${state.nodeBinary ? ` — ${state.nodeBinary}` : ''}`;
firstRunListEl.append(firstRunRow(true, 'Node.js', nodeDetail));
const agentsKnown = Object.values(agentAvailability);
const anyAgentInstalled = agentsKnown.length === 0 || agentsKnown.some((a) => a.installed);
const agentsDetail = document.createElement('span');
if (agentsKnown.length === 0) {
agentsDetail.textContent = 'Could not check.';
} else {
agentsKnown.forEach((a, i) => {
if (i > 0) agentsDetail.append(', ');
agentsDetail.append(`${a.label}: ${a.installed ? a.path : 'not found'}`);
});
}
firstRunListEl.append(firstRunRow(anyAgentInstalled, 'An agent CLI', agentsDetail));
firstRunListEl.append(firstRunRow(Boolean(state.projectDir), 'Project folder', state.projectDir || 'not chosen yet'));
const skillsOk = Boolean(state.skillsVersion);
const skillsDetail = skillsOk ? `v${state.skillsVersion}` : 'not found; run `plan2code update`';
firstRunListEl.append(firstRunRow(skillsOk, 'Plan2Code skills', skillsDetail));
firstRunStartBtn.disabled = !(anyAgentInstalled && state.projectDir && skillsOk);
}
function showFirstRun(state) {
hideState();
hideLaunchCard();
renderFirstRun(state);
firstRunEl.hidden = false;
}
function hideFirstRun() {
firstRunEl.hidden = true;
}
firstRunStartBtn.onclick = async () => {
hideFirstRun();
try {
await invoke('save_first_run_done');
} catch {
// Not remembered is not fatal: the checklist just shows again next launch.
}
showLaunchCard();
};
async function startAgent(event) {
if (event) event.preventDefault();
const kind = launchAgentEl.value;
const model = launchModelEl.value.trim() || null;
const effort = (EFFORT_OPTIONS[kind] || []).length > 0 ? launchEffortEl.value || null : null;
const mode = launchBypassEl.checked ? 'bypass' : 'checked';
agentStatusEl.textContent = '';
showState('Waiting for the agent to open the dashboard');
const { cols, rows } = terminal.size();
try {
await invoke('agent_start', { kind, model, effort, mode, cols, rows, onOutput: agentChannel });
terminal.focus();
} catch (error) {
agentStatusEl.textContent = `Could not start the agent: ${error}`;
showLaunchCard();
}
}
async function agentAction(command) {
try {
await invoke(command);
terminal.focus();
} catch (error) {
agentStatusEl.textContent = String(error);
}
}
launchCard.addEventListener('submit', startAgent);
restartBtn.onclick = () => confirmRestart(() => agentAction('agent_restart'));
nudgeRestartBtn.onclick = () => confirmRestart(() => agentAction('agent_restart'));
// Only ever enabled once the agent has ended: nothing active to lose, so no confirm.
changeAgentBtn.onclick = () => showLaunchCard();
// The pane's shape: which edge it docks to, its share of the window when it
// is neither collapsed nor maximized (dragging and the settings file both
// deal in that share, never in pixels), and whether it is collapsed.
// Maximized is a transient view, never saved: the pane comes back at its
// last saved share on the next launch.
let paneDock = 'bottom';
let paneFraction = 0.25;
let paneCollapsed = false;
let paneMaximized = false;
const paneExtent = () => (paneDock === 'right' ? window.innerWidth : window.innerHeight);
function applyPaneLayout() {
workspaceEl.classList.toggle('dock-right', paneDock === 'right');
termPanel.classList.toggle('collapsed', paneCollapsed);
termHandle.hidden = paneCollapsed;
const sizeProp = paneDock === 'right' ? 'width' : 'height';
const otherProp = paneDock === 'right' ? 'height' : 'width';
termPanel.style[otherProp] = '';
if (paneCollapsed) {
termPanel.style[sizeProp] = '';
} else {
const fraction = paneMaximized ? MAXIMIZED_PANE : paneFraction;
termPanel.style[sizeProp] = `${Math.round(paneExtent() * fraction)}px`;
}
termDockBtn.textContent = paneDock === 'right' ? 'Dock bottom' : 'Dock right';
termMaximizeBtn.textContent = paneMaximized ? 'Restore' : 'Maximize';
termMaximizeBtn.setAttribute('aria-pressed', String(paneMaximized));
termCollapseBtn.textContent = paneCollapsed ? 'Expand' : 'Collapse';
termCollapseBtn.setAttribute('aria-pressed', String(paneCollapsed));
updateBadge();
}
function savePaneSettings() {
invoke('save_term_panel', { dock: paneDock, fraction: paneFraction, collapsed: paneCollapsed }).catch(() => {
// A settings file that cannot be written must not stop the pane from working.
});
}
termDockBtn.onclick = () => {
paneDock = paneDock === 'right' ? 'bottom' : 'right';
applyPaneLayout();
savePaneSettings();
};
termMaximizeBtn.onclick = () => {
paneMaximized = !paneMaximized;
applyPaneLayout();
};
termCollapseBtn.onclick = () => {
paneCollapsed = !paneCollapsed;
if (!paneCollapsed) terminal.focus();
applyPaneLayout();
savePaneSettings();
};
// Dragging the handle sets the panel's share of the window, along whichever
// edge it is docked to.
termHandle.addEventListener('pointerdown', (event) => {
event.preventDefault();
termHandle.setPointerCapture(event.pointerId);
});
termHandle.addEventListener('pointermove', (event) => {
if (!termHandle.hasPointerCapture(event.pointerId)) return;
const extent = paneExtent();
const wanted = paneDock === 'right' ? window.innerWidth - event.clientX : window.innerHeight - event.clientY;
const clamped = Math.min(Math.max(wanted, extent * MIN_PANE), extent * MAX_PANE);
paneFraction = clamped / extent;
paneMaximized = false;
applyPaneLayout();
});
termHandle.addEventListener('pointerup', (event) => {
if (termHandle.hasPointerCapture(event.pointerId)) termHandle.releasePointerCapture(event.pointerId);
savePaneSettings();
});
// When the pane is collapsed or small, the agent's own status line can keep
// redrawing while it is really waiting on a prompt no one is watching: a
// stretch of no new output at all is the giveaway.
let lastOutputAt = Date.now();
function updateBadge() {
const small = paneCollapsed || (!paneMaximized && paneFraction < SMALL_PANE);
const quiet = agentActive() && Date.now() - lastOutputAt >= QUIET_BADGE_MS;
termBadgeEl.hidden = !(small && quiet);
}
// The frame is "showing" only once the console page itself says so (it posts a
// hello to its parent when it draws). The frame's own load event also fires for
// an error page, so it proves nothing: a blocked or dead frame must not look
// like a loaded one.
const HELLO_WAIT_MS = 8000;
let currentUrl = null;
let frameReady = false;
let helloTimer = null;
// Nothing has shown here yet: no agent has opened the dashboard. No polling,
// no "reconnect" button makes sense until that first page lands.
let consoleKnown = false;
function loadFrame(url) {
currentUrl = url;
frameReady = false;
clearTimeout(helloTimer);
helloTimer = setTimeout(onNoHello, HELLO_WAIT_MS);
frame.src = url;
}
window.addEventListener('message', (event) => {
if (event.source !== frame.contentWindow) return;
if (!event.data || event.data.plan2code !== 'console-ready') return;
frameReady = true;
clearTimeout(helloTimer);
hideState();
});
// No hello in time: ask the console why, and say so with a way forward.
async function onNoHello() {
if (frameReady || !consoleKnown || restarting) return;
let status = null;
try {
status = await invoke('console_status');
} catch {
// The status check itself failed; treat it as a console that is not answering.
}
if (!status || status.state !== 'running') {
showState('The console stopped, so the page could not show.', 'Restart the console', reconnectConsole);
} else {
showState('The console is running but its page did not show in this window.', 'Reload the page', () => {
showState('Reloading the page');
loadFrame(currentUrl);
});
}
}
function showState(text, buttonLabel, onButton, onCancel) {
hideLaunchCard();
hideFirstRun();
stateText.textContent = text;
stateButton.hidden = !buttonLabel;
stateButton.textContent = buttonLabel || '';
stateButton.onclick = onButton || null;
stateCancelEl.hidden = !onCancel;
stateCancelEl.onclick = onCancel || null;
stateBox.hidden = false;
}
function hideState() {
stateBox.hidden = true;
}
let pollTimer = null;
// Only once the agent has opened a page: brings an idle or dead console back
// on its own session. The app never opens a dashboard on its own (the agent
// does, by running the skill), so there is nothing to start before that.
async function reconnectConsole() {
markConsoleAlive();
showState('Reconnecting to the console');
try {
const info = await invoke('console_start');
loadFrame(info.url);
} catch (error) {
showState(`The console could not be reached: ${error}`, 'Retry', reconnectConsole);
// An old console cannot be framed: the fix is the skills update, so offer it.
if (String(error).includes('too old')) {
versionTextEl.textContent = 'The installed console is too old for the app';
versionEl.hidden = false;
}
}
}
// Health check on a timer. A console that dies after its page showed (it idles
// out, or something ended it) is brought back on the same session, a few times
// at most; before the page ever showed, the person decides with a button.
const RECONNECT_LIMIT = 3;
let reconnects = 0;
async function pollConsole() {
try {
const status = await invoke('console_status');
if (status.state === 'running') {
markConsoleAlive();
return;
}
markConsoleDead();
if (frameReady && reconnects < RECONNECT_LIMIT) {
reconnects += 1;
showState('The console stopped. Reconnecting');
await reconnectConsole();
} else if (!frameReady) {
onNoHello();
}
} catch {
// A failed check is not proof the console died; look again next tick.
}
}
// The meter: a bar and a percent for a real or best-effort reading, a dashed
// bar with "about N%" and an "estimate" tag for an estimate, "unknown" when
// nothing is available. Built with DOM calls, never innerHTML.
function renderMeter(reading) {
meterSlot.replaceChildren();
// Left empty, not even an "unknown" label: #bar-slot-meter:empty hides it,
// so the bar carries nothing until the reading means something.
if (reading.kind === 'unknown') return;
const label = document.createElement('span');
const track = document.createElement('span');
track.className = `meter-track ${reading.kind}`;
const fill = document.createElement('span');
fill.className = 'meter-fill';
fill.style.width = `${reading.percent}%`;
track.append(fill);
label.textContent = reading.kind === 'estimate' ? `about ${reading.percent}%` : `${reading.percent}%`;
meterSlot.append(track, label);
if (reading.kind === 'estimate') {
const tag = document.createElement('span');
tag.className = 'meter-tag';
tag.textContent = 'estimate';
meterSlot.append(tag);
meterSlot.title = 'Estimated from the text so far: the agent does not report its context size';
} else if (reading.kind === 'besteffort') {
meterSlot.title = 'Read from the agent\'s session log: undocumented, so it may stop working after an update';
} else {
meterSlot.title = 'How full the agent context is, as the agent reports it';
}
}
// Every two seconds while an agent runs: draw the meter and, once per run,
// suggest a Restart when the context reaches the nudge percent.
async function pollMeter() {
if (!agentActive()) return;
try {
// The reading may land after a Restart: only a reading for the same run counts.
const { generation, state } = agent;
const reading = await invoke('agent_context');
if (agent.generation !== generation || agent.state !== state) return;
renderMeter(reading);
if (nudgeDue(reading, nudgePercent) && state === 'running' && nudgeShownFor !== generation) {
nudgeShownFor = generation;
nudgeEl.hidden = false;
}
} catch {
// A failed read is not a reading: look again on the next tick.
}
}
// Once, at start: when the app and the installed skills are on different versions the bar
// says so and offers Update skills. Nothing runs until that button is pressed.
async function checkVersions() {
try {
const status = await invoke('version_status');
if (!status.mismatch) return;
if (status.skills_ahead) {
// The skills are ahead of this app: another Update skills run cannot help.
versionTextEl.textContent = `The installed skills are v${status.skills}, newer than this app (v${status.app}). Get the new app.`;
versionBtn.hidden = true;
} else {
versionTextEl.textContent = `Skills are v${status.skills}, this app is v${status.app}`;
versionBtn.hidden = false;
}
versionEl.hidden = false;
} catch {
// No version to compare is no reason to nag.
}
}
versionBtn.onclick = async () => {
versionBtn.disabled = true;
versionRestartBtn.hidden = true;
versionTextEl.textContent = 'Updating Plan2Code...';
const progress = new Channel();
progress.onmessage = (line) => {
if (line) versionTextEl.textContent = line;
};
try {
const outcome = await invoke('update_skills', { progress });
versionTextEl.textContent = outcome.status.mismatch
? `Updated, but the mismatch remains (skills v${outcome.status.skills}, app v${outcome.status.app}).`
: 'Updated. Restart the console to use the new version.';
versionBtn.hidden = true;
versionRestartBtn.hidden = outcome.status.mismatch;
} catch (error) {
versionTextEl.textContent = String(error);
versionBtn.disabled = false;
}
};
versionRestartBtn.onclick = async () => {
versionRestartBtn.disabled = true;
try {
await invoke('console_stop');
} catch {
// Nothing to stop is fine: reconnectConsole starts a fresh one either way.
}
versionEl.hidden = true;
await reconnectConsole();
};
// A page the agent's `console.mjs open` asked this window to show.
const pageLabel = (workflow) => (workflow || '').replace(/-/g, ' ').replace(/^./, (c) => c.toUpperCase());
function showAnnounced(notice) {
restarting = false;
currentPageEl.textContent = pageLabel(notice.workflow);
if (!consoleKnown) {
consoleKnown = true;
if (!pollTimer) pollTimer = setInterval(pollConsole, STATUS_POLL_MS);
}
markConsoleAlive();
if (notice.url !== currentUrl) {
showState('Opening the page');
loadFrame(notice.url);
}
}
window.__TAURI__.event.listen('console-page', (event) => showAnnounced(event.payload));
function markConsoleAlive() {
consoleStatusEl.textContent = '';
consoleAgainBtn.hidden = true;
}
function markConsoleDead() {
consoleStatusEl.textContent = 'The console stopped.';
consoleAgainBtn.hidden = false;
}
consoleAgainBtn.onclick = () => reconnectConsole();
function setProjectDir(dir) {
projectDirEl.textContent = dir;
projectDirEl.title = dir;
}
// The state `main()` read at startup: `pickFolder()` and the first-run
// checklist both need it once a folder lands, after the fact.
let appState = null;
// Opens the OS folder picker. A cancelled pick (or a failed one) lands on the
// "No project folder chosen" state with a button that tries again.
async function pickFolder() {
try {
const dir = await invoke('pick_project_folder');
if (!dir) {
showState('No project folder chosen', 'Choose folder', pickFolder);
return;
}
setProjectDir(dir);
if (appState) appState.projectDir = dir;
afterProjectKnown();
} catch (error) {
showState(`Could not open the folder picker: ${error}`, 'Choose folder', pickFolder);
}
}
// Once a project folder is known: the first-run checklist (once, until it
// passes) or straight to the launch card.
function afterProjectKnown() {
if (appState && !appState.firstRunDone) {
showFirstRun(appState);
} else {
showLaunchCard();
}
}
// Switches to a folder picked fresh: the Rust side tears the old project's
// agent and console down before the new one is remembered, so nothing from
// it carries over. Picking nothing (cancelled) leaves the current project as
// it was.
async function doChangeProject() {
showState('Choose the new project folder...');
try {
const dir = await invoke('change_project');
if (!dir) {
if (agentActive()) hideState();
else afterProjectKnown();
return;
}
setProjectDir(dir);
if (appState) appState.projectDir = dir;
restarting = false;
currentUrl = null;
frameReady = false;
currentPageEl.textContent = '';
afterProjectKnown();
} catch (error) {
showState(`Could not switch project: ${error}`, 'Try again', doChangeProject);
}
}
function changeProject() {
if (agentActive()) {
showState(
'Stop the running agent and switch to a different project? What it was doing is not saved.',
'Change project',
doChangeProject,
() => (frameReady ? hideState() : showLaunchCard())
);
return;
}
doChangeProject();
}
changeProjectBtn.onclick = changeProject;
// The launcher passed `--agent`: start it at once, on its model, with the
// same bypass flags the terminal launcher itself always runs that agent with
// (it offers no permission-mode choice of its own).
async function autoStartAgent(state) {
launchAgentEl.value = state.autoStart;
if (typeof state.launchModel === 'string' && state.launchModel) launchModelEl.value = state.launchModel;
agentStatusEl.textContent = '';
showState('Starting the agent...');
const { cols, rows } = terminal.size();
try {
await invoke('agent_start', {
kind: state.autoStart,
model: state.launchModel || null,
effort: null,
mode: 'bypass',
cols,
rows,
onOutput: agentChannel,
});
terminal.focus();
} catch (error) {
agentStatusEl.textContent = `Could not start the agent: ${error}`;
showLaunchCard();
}
}
// A page that just mounted registers its output channel and, if an agent
// already ran before it (a reload, or this is the window's first paint
// after one survived a restart), gets its recent output replayed onto a
// clean xterm at once instead of starting blank.
async function recoverAfterReload(snapshot) {
applyAgentState(snapshot, { skipReset: true });
terminal.focus();
hideState();
consoleKnown = true;
if (!pollTimer) pollTimer = setInterval(pollConsole, STATUS_POLL_MS);
try {
const status = await invoke('console_status');
if (status.state === 'running' && status.url) {
loadFrame(status.url);
} else {
onNoHello();
}
} catch {
onNoHello();
}
}
async function main() {
let state;
try {
state = await invoke('app_state');
} catch (error) {
showState(`Could not read the app state: ${error}`, 'Retry', main);
return;
}
appState = state;
if (AGENT_LABELS[state.lastAgent]) launchAgentEl.value = state.lastAgent;
if (typeof state.launchModel === 'string' && state.launchModel) launchModelEl.value = state.launchModel;
if (Number.isInteger(state.contextNudgePercent)) nudgePercent = state.contextNudgePercent;
if (state.termPanel) {
paneDock = state.termPanel.dock === 'right' ? 'right' : 'bottom';
paneFraction = state.termPanel.fraction;
paneCollapsed = Boolean(state.termPanel.collapsed);
}
applyPaneLayout();
await loadAgentAvailability();
refreshLaunchCard();
setInterval(pollMeter, METER_POLL_MS);
setInterval(updateBadge, BADGE_POLL_MS);
checkVersions();
let reattach = null;
try {
reattach = await invoke('agent_reattach', { onOutput: agentChannel });
} catch {
// Nothing to reattach to is not fatal: carry on as a plain first paint.
}
if (reattach && reattach.state !== 'idle') {
if (state.projectDir) setProjectDir(state.projectDir);
await recoverAfterReload(reattach);
return;
}
if (state.autoStart) {
if (state.projectDir) setProjectDir(state.projectDir);
await autoStartAgent(state);
return;
}
if (state.projectDir) {
setProjectDir(state.projectDir);
afterProjectKnown();
} else {
pickFolder();
}
}
main();
+212
View File
@@ -0,0 +1,212 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' ipc: http://ipc.localhost; frame-src http://127.0.0.1:*; object-src 'none'; base-uri 'none'">
<title>Plan2Code</title>
<link rel="stylesheet" href="vendor/xterm.css">
<style>
html, body { margin: 0; height: 100%; font-family: system-ui, sans-serif; background: #1e1e1e; color: #ddd; }
body { display: flex; flex-direction: column; overflow: hidden; }
#bar { flex: none; display: flex; flex-direction: column; border-bottom: 1px solid #444; }
#bar-top { height: 32px; flex: none; display: flex; align-items: center; gap: 12px; padding: 0 10px; white-space: nowrap; overflow-x: auto; overflow-y: hidden; }
#bar-status { flex: none; display: flex; align-items: center; gap: 12px; padding: 3px 10px; font-size: 12px; white-space: nowrap; overflow-x: auto; overflow-y: hidden; border-top: 1px solid #2a2a2a; }
#title { font-weight: 600; }
#project-dir { color: #9ab; overflow: hidden; text-overflow: ellipsis; min-width: 0; max-width: 40%; }
#current-page { color: #8c8; }
#current-page:not(:empty)::before { content: "page: "; color: #666; }
#agent-name { color: #9ab; }
#agent-name:not(:empty)::before { content: "agent: "; color: #666; }
#console-status, #agent-status { color: #d7ba7d; overflow: hidden; text-overflow: ellipsis; min-width: 0; }
#agent-restart[hidden], #change-agent[hidden] { display: none; }
.bar-slot { flex: none; }
#permissions-note { color: #888; }
#context-nudge { display: flex; align-items: center; gap: 6px; color: #d7ba7d; font-size: 12px; }
#context-nudge[hidden] { display: none; }
#version-update { display: flex; align-items: center; gap: 6px; color: #d7ba7d; font-size: 12px; }
#version-update[hidden], #version-update-button[hidden] { display: none; }
#bar-slot-meter { display: flex; align-items: center; gap: 6px; color: #9ab; font-size: 12px; }
#bar-slot-meter:empty { display: none; }
.meter-track { display: inline-block; width: 64px; height: 8px; border: 1px solid #666; border-radius: 2px; overflow: hidden; background: #2a2a2a; }
.meter-track.estimate { border-style: dashed; }
.meter-fill { display: block; height: 100%; background: #6a9955; }
.meter-track.estimate .meter-fill { background: repeating-linear-gradient(45deg, #6a9955 0 4px, transparent 4px 8px); }
.meter-tag { color: #d7ba7d; font-style: italic; }
#workspace { flex: 1; min-height: 0; display: flex; flex-direction: column; }
#workspace.dock-right { flex-direction: row; }
#dashboard { flex: 1; min-height: 0; min-width: 0; position: relative; }
#console-frame { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; background: #1e1e1e; }
#dashboard-state { position: absolute; inset: 0; z-index: 1; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 12px; background: #1e1e1e; text-align: center; padding: 16px; box-sizing: border-box; }
#dashboard-state[hidden] { display: none; }
#dashboard-state-text { margin: 0; max-width: 60ch; overflow-wrap: anywhere; color: #bbb; }
#launch-card {
position: absolute; inset: 0; z-index: 1; display: flex; flex-direction: column;
align-items: stretch; justify-content: center; gap: 10px; background: #1e1e1e;
padding: 24px; box-sizing: border-box; width: min(360px, 100%); margin: 0 auto;
}
#launch-card[hidden] { display: none; }
#launch-card h2 { margin: 0 0 6px; font-size: 17px; text-align: center; }
#launch-card label { font-size: 12px; color: #9ab; }
#launch-card select, #launch-card input[type="text"] {
width: 100%; box-sizing: border-box; margin: 4px 0 2px; padding: 6px 8px;
background: #2a2a2a; color: #ddd; border: 1px solid #555; border-radius: 4px; font: inherit;
}
#launch-missing { margin: 0; font-size: 12px; color: #d7ba7d; }
#launch-missing code { color: #ddd; }
#launch-effort-row[hidden] { display: none; }
#launch-bypass-row { display: flex; align-items: center; gap: 8px; color: #ccc; font-size: 13px; cursor: pointer; }
#launch-bypass-row input { margin: 0; }
#launch-bypass-warning { margin: 0; font-size: 12px; color: #d7ba7d; }
#launch-bypass-warning[hidden] { display: none; }
#launch-start {
margin-top: 6px; padding: 8px; background: #2d6a4f; color: #fff; border: 0; border-radius: 4px;
font: inherit; font-weight: 600; cursor: pointer;
}
#launch-start:hover { background: #357a5c; }
#launch-start:disabled { background: #444; color: #888; cursor: not-allowed; }
#first-run {
position: absolute; inset: 0; z-index: 1; display: flex; flex-direction: column;
align-items: stretch; justify-content: center; gap: 14px; background: #1e1e1e;
padding: 24px; box-sizing: border-box; width: min(420px, 100%); margin: 0 auto;
}
#first-run[hidden] { display: none; }
#first-run h2 { margin: 0; font-size: 17px; text-align: center; }
#first-run-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 10px; }
.first-run-row { display: flex; align-items: flex-start; gap: 8px; font-size: 13px; }
.first-run-mark { flex: none; width: 16px; text-align: center; font-weight: 700; }
.first-run-row.is-pass .first-run-mark { color: #6a9955; }
.first-run-row.is-fail .first-run-mark { color: #d7ba7d; }
.first-run-body { flex: 1; min-width: 0; }
.first-run-title { color: #ddd; }
.first-run-detail { color: #9ab; font-size: 12px; margin-top: 2px; }
.first-run-detail code { color: #ddd; }
.first-run-row button {
margin-top: 4px; background: none; border: 1px solid #555; color: #ccc; border-radius: 3px;
font: inherit; font-size: 12px; padding: 3px 8px; cursor: pointer;
}
.first-run-row button:hover { background: #333; }
#first-run-start {
margin-top: 6px; padding: 8px; background: #2d6a4f; color: #fff; border: 0; border-radius: 4px;
font: inherit; font-weight: 600; cursor: pointer;
}
#first-run-start:hover { background: #357a5c; }
#first-run-start:disabled { background: #444; color: #888; cursor: not-allowed; }
#term-handle { flex: none; background: #2a2a2a; }
#term-handle:hover { background: #3d3d3d; }
#term-handle[hidden] { display: none; }
#workspace:not(.dock-right) #term-handle { height: 6px; cursor: row-resize; }
#workspace.dock-right #term-handle { width: 6px; cursor: col-resize; }
#term-panel { flex: none; display: flex; flex-direction: column; min-height: 0; min-width: 0; }
#workspace:not(.dock-right) #term-panel { border-top: 1px solid #444; }
#workspace.dock-right #term-panel { border-left: 1px solid #444; }
#term-panel.collapsed { height: 28px !important; }
#workspace.dock-right #term-panel.collapsed { width: 28px !important; height: auto !important; }
#term-panel.collapsed #term { display: none; }
#term-toolbar { flex: none; display: flex; align-items: center; gap: 6px; padding: 3px 6px; background: #252525; font-size: 11px; }
#workspace.dock-right #term-toolbar { flex-direction: column; align-items: stretch; }
#term-toolbar-spacer { flex: 1; min-height: 0; }
#term-toolbar button {
background: none; border: 1px solid #555; color: #ccc; border-radius: 3px;
font-size: 11px; padding: 2px 6px; cursor: pointer; font-family: inherit;
}
#term-toolbar button:hover { background: #333; }
#term-toolbar button[aria-pressed="true"] { color: #fff; border-color: #888; }
#term-panel.collapsed #term-dock, #term-panel.collapsed #term-maximize { display: none; }
#term-badge { color: #d7ba7d; font-size: 14px; line-height: 1; }
#term-badge[hidden] { display: none; }
#term { flex: 1; min-height: 0; min-width: 0; padding: 4px; }
</style>
</head>
<body>
<header id="bar">
<div id="bar-top">
<span id="title">Plan2Code</span>
<span id="project-dir"></span>
<span id="bar-slot-restart" class="bar-slot"><button id="agent-restart" hidden>Restart</button></span>
<span id="bar-slot-change-agent" class="bar-slot"><button id="change-agent" hidden>Change agent</button></span>
<span id="bar-slot-change-project" class="bar-slot"><button id="change-project">Change project</button></span>
</div>
<div id="bar-status">
<span id="current-page" title="The page the agent opened"></span>
<span id="agent-name"></span>
<span id="agent-status" role="status"></span>
<span id="console-status"></span>
<button id="console-again" hidden>Start it again</button>
<span id="context-nudge" class="bar-slot" hidden>
<span>Context is getting full: consider Restart</span>
<button id="context-restart">Restart</button>
</span>
<!-- Shown only when the app and the installed skills are on different versions. -->
<span id="version-update" class="bar-slot" hidden>
<span id="version-update-text"></span>
<button id="version-update-button">Update skills</button>
<button id="version-update-restart" hidden>Restart the console</button>
</span>
<span id="bar-slot-meter" class="bar-slot"></span>
<!-- Shown only while an agent is running, naming the real mode it started with. -->
<span id="permissions-note" hidden></span>
</div>
</header>
<div id="workspace">
<main id="dashboard">
<iframe id="console-frame" title="Plan2Code console dashboard"></iframe>
<div id="dashboard-state" hidden>
<p id="dashboard-state-text"></p>
<span>
<button id="dashboard-state-button" hidden></button>
<button id="dashboard-state-cancel" hidden>Cancel</button>
</span>
</div>
<div id="first-run" hidden>
<h2>Before you start</h2>
<ul id="first-run-list"></ul>
<button id="first-run-start" type="button" disabled>Start</button>
</div>
<form id="launch-card" hidden>
<h2>Start an agent</h2>
<label for="launch-agent">Agent</label>
<select id="launch-agent">
<option value="claude">Claude Code</option>
<option value="devin">Devin</option>
<option value="codex">Codex</option>
</select>
<p id="launch-missing" hidden></p>
<label for="launch-model">Model</label>
<input id="launch-model" type="text" placeholder="Default (your account setting)" autocomplete="off">
<div id="launch-effort-row">
<label for="launch-effort">Effort</label>
<select id="launch-effort"></select>
</div>
<label id="launch-bypass-row">
<input id="launch-bypass" type="checkbox">
Turn permission checks off for this agent
</label>
<p id="launch-bypass-warning" hidden>Permission checks will be off: the agent can run commands and change files without asking first.</p>
<button id="launch-start" type="submit">Start agent</button>
</form>
</main>
<div id="term-handle" title="Drag to resize the terminal panel"></div>
<section id="term-panel">
<div id="term-toolbar">
<span id="term-badge" title="The agent has been quiet a while" hidden>●</span>
<span id="term-toolbar-spacer"></span>
<button id="term-dock" type="button">Dock right</button>
<button id="term-maximize" type="button" aria-pressed="false">Maximize</button>
<button id="term-collapse" type="button" aria-pressed="false">Collapse</button>
</div>
<div id="term"></div>
</section>
</div>
<script src="vendor/xterm.js"></script>
<script src="vendor/addon-fit.js"></script>
<script type="module" src="app.js"></script>
</body>
</html>
+15
View File
@@ -0,0 +1,15 @@
// The context meter's pure decisions, kept out of app.js so they can be
// imported and tested without a DOM or `window.__TAURI__` (app.js touches
// both at module scope, the same reason the web console keeps its own pure
// logic in answers.js rather than app.js).
/**
* Whether `reading` (what the `agent_context` command returns) should fire
* the Restart nudge at `nudgePercent`. Only a real or best-effort number
* counts, per the context policy (pathfinder Question 11): an estimate is
* not precise enough for "about 70%" to mean the window really is close to
* full, so an estimate-only agent gets the meter but never the nudge.
*/
export function nudgeDue(reading, nudgePercent) {
return (reading.kind === 'real' || reading.kind === 'besteffort') && reading.percent >= nudgePercent;
}
+89
View File
@@ -0,0 +1,89 @@
// The terminal panel: an xterm instance. It knows nothing about agents; the
// page decides what goes in and where the keystrokes and size changes go.
// Needs xterm.js and addon-fit.js loaded first (they set window.Terminal and
// window.FitAddon), and withGlobalTauri for window.__TAURI__.
const { invoke } = window.__TAURI__.core;
export async function mountTerminal(container, { onInput, onResize }) {
// Windows' pseudo-terminal rewraps lines itself; xterm needs to know the
// backend and build to cope with that.
const platform = await invoke('platform_info');
const windowsPty = platform.os === 'windows'
? { backend: 'conpty', buildNumber: platform.windowsBuild }
: undefined;
const term = new window.Terminal({
cursorBlink: true,
fontFamily: 'Consolas, Menlo, "DejaVu Sans Mono", monospace',
fontSize: 13,
scrollback: 5000,
windowsPty,
});
const fit = new window.FitAddon.FitAddon();
term.loadAddon(fit);
term.open(container);
fit.fit();
// Keystrokes and pasted text go on as typed.
term.onData((data) => onInput(data));
// A size change in the page becomes a size change in the pseudo-terminal.
// The window's own resize event and the container's ResizeObserver both
// fire for the same change, and a drag can fire either one many times a
// second: `fit.fit()` stays immediate (cheap, local, keeps the screen
// looking right as it happens), but the pty resize call is debounced to
// one, on the settled size, so xterm and the pty always end up agreeing.
const RESIZE_DEBOUNCE_MS = 100;
let resizeTimer = null;
const refit = () => {
fit.fit();
clearTimeout(resizeTimer);
resizeTimer = setTimeout(() => {
resizeTimer = null;
onResize(term.cols, term.rows);
}, RESIZE_DEBOUNCE_MS);
};
window.addEventListener('resize', refit);
new ResizeObserver(refit).observe(container);
// Copy on selection, and an explicit shortcut for it: Ctrl+C is the pty's
// own interrupt, so Ctrl+Shift+C (Windows, Linux) or Cmd+C (macOS) copies
// instead, without being typed. Ctrl+V / Cmd+V paste from the clipboard
// explicitly, rather than depending on the hidden textarea's own native
// paste making it through every webview the same way.
term.onSelectionChange(() => {
const text = term.getSelection();
if (text && navigator.clipboard) navigator.clipboard.writeText(text).catch(() => {});
});
term.attachCustomKeyEventHandler((event) => {
if (event.type !== 'keydown' || !navigator.clipboard) return true;
const key = event.key.toLowerCase();
if (key === 'c' && ((event.ctrlKey && event.shiftKey) || (event.metaKey && !event.ctrlKey))) {
const text = term.getSelection();
if (text) navigator.clipboard.writeText(text).catch(() => {});
return false;
}
if (key === 'v' && (event.ctrlKey || event.metaKey)) {
navigator.clipboard
.readText()
.then((text) => {
if (text) onInput(text);
})
.catch(() => {});
return false;
}
return true;
});
return {
size: () => ({ cols: term.cols, rows: term.rows }),
// A fresh agent starts on a clean screen.
reset() {
term.reset();
fit.fit();
},
write: (data) => term.write(data),
focus: () => term.focus(),
};
}