mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20:45:33 -08:00
225 lines
8.6 KiB
Rust
225 lines
8.6 KiB
Rust
//! 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());
|
|
}
|
|
}
|