1use std::collections::{BTreeMap, BTreeSet};
25use std::io::Read as _;
26use std::path::Path;
27use std::process::{Command, Stdio};
28use std::time::{Duration, Instant};
29
30use serde::{Deserialize, Serialize};
31
32pub const DEFAULT_FILE: &str = "memfork-plan.toml";
34
35pub const DEFAULT_TIMEOUT_SECONDS: u64 = 600;
37
38pub const MAX_TIMEOUT_SECONDS: u64 = 3600;
40
41pub const OUTPUT_TAIL_BYTES: usize = 4096;
43
44pub const MAX_PLAN_TASKS: usize = 200;
46
47pub const MAX_DEPENDENCIES: usize = 32;
49
50pub const MAX_ACCEPT_CHARS: usize = 1000;
52
53#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
55#[serde(deny_unknown_fields)]
56pub struct PlanTask {
57 pub id: String,
59 pub title: String,
61 #[serde(default, skip_serializing_if = "Option::is_none")]
63 pub detail: Option<String>,
64 #[serde(default, skip_serializing_if = "Vec::is_empty")]
66 pub depends_on: Vec<String>,
67 #[serde(default, skip_serializing_if = "Option::is_none")]
69 pub accept: Option<String>,
70 #[serde(default, skip_serializing_if = "Option::is_none")]
72 pub timeout_seconds: Option<u64>,
73}
74
75#[derive(Deserialize)]
76#[serde(deny_unknown_fields)]
77struct PlanFile {
78 #[serde(default)]
80 description: Option<String>,
81 #[serde(default)]
82 task: Vec<PlanTask>,
83}
84
85const BUILT_IN: &[(&str, &str)] = &[
87 ("feature", include_str!("plan_templates/feature.toml")),
88 ("bugfix", include_str!("plan_templates/bugfix.toml")),
89 ("refactor", include_str!("plan_templates/refactor.toml")),
90 ("upgrade", include_str!("plan_templates/upgrade.toml")),
91 ("tests", include_str!("plan_templates/tests.toml")),
92];
93
94pub const TEMPLATES_DIR: &str = "plans";
96
97#[derive(Debug, Clone, PartialEq, Eq)]
99pub struct Template {
100 pub name: String,
102 pub description: String,
104 pub text: String,
106 pub source: String,
108 pub problem: Option<String>,
110}
111
112pub fn templates(data_dir: Option<&Path>) -> Vec<Template> {
116 let describe = |text: &str| -> (String, Option<String>) {
117 match toml::from_str::<PlanFile>(text) {
118 Ok(file) => {
119 let checked =
120 check_shape(&file.task).and_then(|()| check_alone(&file.task).map(|_| ()));
121 (file.description.unwrap_or_default(), checked.err())
122 }
123 Err(e) => (String::new(), Some(format!("does not parse: {e}"))),
124 }
125 };
126 let mut out: Vec<Template> = BUILT_IN
127 .iter()
128 .map(|(name, text)| {
129 let (description, problem) = describe(text);
130 Template {
131 name: (*name).to_owned(),
132 description,
133 text: (*text).to_owned(),
134 source: "built-in".to_owned(),
135 problem,
136 }
137 })
138 .collect();
139 let Some(dir) = data_dir.map(|d| d.join(TEMPLATES_DIR)) else {
140 return out;
141 };
142 let mut own: Vec<std::path::PathBuf> = std::fs::read_dir(&dir)
143 .map(|entries| {
144 entries
145 .flatten()
146 .map(|e| e.path())
147 .filter(|p| p.extension().is_some_and(|x| x == "toml"))
148 .collect()
149 })
150 .unwrap_or_default();
151 own.sort();
152 for path in own {
153 let Some(name) = path.file_stem().map(|s| s.to_string_lossy().into_owned()) else {
154 continue;
155 };
156 let Ok(text) = read_file(&path) else {
157 continue;
158 };
159 let (description, problem) = describe(&text);
160 let template = Template {
161 name: name.clone(),
162 description,
163 text,
164 source: path.display().to_string(),
165 problem,
166 };
167 match out.iter_mut().find(|t| t.name == name) {
168 Some(existing) => *existing = template,
169 None => out.push(template),
170 }
171 }
172 out
173}
174
175pub fn normalise_accept(accept: Option<&str>) -> Option<String> {
178 accept
179 .map(str::trim)
180 .filter(|a| !a.is_empty())
181 .map(str::to_owned)
182}
183
184pub fn parse(text: &str) -> Result<Vec<PlanTask>, String> {
206 let file: PlanFile =
207 toml::from_str(text).map_err(|e| format!("the plan does not parse: {e}"))?;
208 let mut tasks = file.task;
209 for task in &mut tasks {
210 task.accept = normalise_accept(task.accept.as_deref());
211 }
212 check_shape(&tasks)?;
213 Ok(tasks)
214}
215
216pub fn check_alone(tasks: &[PlanTask]) -> Result<Vec<String>, String> {
220 let ids: BTreeSet<&str> = tasks.iter().map(|t| t.id.as_str()).collect();
221 let outside: BTreeSet<String> = tasks
222 .iter()
223 .flat_map(|t| t.depends_on.iter())
224 .filter(|d| !ids.contains(d.as_str()))
225 .cloned()
226 .collect();
227 let others = outside.iter().map(|d| (d.clone(), Vec::new())).collect();
228 check_graph(tasks, &others)?;
229 Ok(outside.into_iter().collect())
230}
231
232pub fn check_shape(tasks: &[PlanTask]) -> Result<(), String> {
234 if tasks.is_empty() {
235 return Err(
236 "the plan has no tasks; each one is a `[[task]]` with an `id` and a `title`".to_owned(),
237 );
238 }
239 if tasks.len() > MAX_PLAN_TASKS {
240 return Err(format!(
241 "a plan may hold at most {MAX_PLAN_TASKS} tasks; this one has {}",
242 tasks.len()
243 ));
244 }
245 let mut seen = BTreeSet::new();
246 for task in tasks {
247 if !seen.insert(task.id.as_str()) {
248 return Err(format!("the plan names task `{}` twice", task.id));
249 }
250 if task.title.trim().is_empty() {
251 return Err(format!("task `{}` has no `title`", task.id));
252 }
253 if task.depends_on.len() > MAX_DEPENDENCIES {
254 return Err(format!(
255 "task `{}` depends on {} tasks; at most {MAX_DEPENDENCIES}",
256 task.id,
257 task.depends_on.len()
258 ));
259 }
260 for dep in &task.depends_on {
261 if dep.contains(':') {
262 return Err(format!(
263 "task `{}` depends on `{dep}`, which names another project; a plan's \
264 dependencies are tasks in its own project",
265 task.id
266 ));
267 }
268 }
269 if task.depends_on.contains(&task.id) {
270 return Err(format!("task `{}` depends on itself", task.id));
271 }
272 if task
273 .accept
274 .as_ref()
275 .is_some_and(|a| a.chars().count() > MAX_ACCEPT_CHARS)
276 {
277 return Err(format!(
278 "task `{}` has an acceptance command over {MAX_ACCEPT_CHARS} characters",
279 task.id
280 ));
281 }
282 if let Some(t) = task.timeout_seconds {
283 if t == 0 || t > MAX_TIMEOUT_SECONDS {
284 return Err(format!(
285 "task `{}`: `timeout_seconds` must be 1 to {MAX_TIMEOUT_SECONDS}",
286 task.id
287 ));
288 }
289 }
290 }
291 Ok(())
292}
293
294pub fn check_graph(
298 tasks: &[PlanTask],
299 others: &BTreeMap<String, Vec<String>>,
300) -> Result<(), String> {
301 let mut graph: BTreeMap<&str, Vec<&str>> = others
302 .iter()
303 .map(|(id, deps)| (id.as_str(), deps.iter().map(String::as_str).collect()))
304 .collect();
305 for task in tasks {
306 graph.insert(
307 task.id.as_str(),
308 task.depends_on.iter().map(String::as_str).collect(),
309 );
310 }
311 for task in tasks {
312 for dep in &task.depends_on {
313 if !graph.contains_key(dep.as_str()) {
314 return Err(format!(
315 "task `{}` depends on `{dep}`, which is not a task in this project or \
316 this plan",
317 task.id
318 ));
319 }
320 }
321 }
322 #[derive(Clone, Copy, PartialEq)]
324 enum Mark {
325 Visiting,
326 Done,
327 }
328 fn visit<'a>(
329 id: &'a str,
330 graph: &BTreeMap<&'a str, Vec<&'a str>>,
331 marks: &mut BTreeMap<&'a str, Mark>,
332 path: &mut Vec<&'a str>,
333 ) -> Result<(), String> {
334 match marks.get(id) {
335 Some(Mark::Done) => return Ok(()),
336 Some(Mark::Visiting) => {
337 let start = path.iter().position(|p| *p == id).unwrap_or(0);
338 let mut cycle: Vec<&str> = path[start..].to_vec();
339 cycle.push(id);
340 return Err(format!(
341 "the plan has a cycle, so none of it could ever be ready: {}",
342 cycle.join(" -> ")
343 ));
344 }
345 None => {}
346 }
347 marks.insert(id, Mark::Visiting);
348 path.push(id);
349 for dep in graph.get(id).into_iter().flatten() {
350 visit(dep, graph, marks, path)?;
351 }
352 path.pop();
353 marks.insert(id, Mark::Done);
354 Ok(())
355 }
356 let mut marks = BTreeMap::new();
357 for id in graph.keys() {
358 visit(id, &graph, &mut marks, &mut Vec::new())?;
359 }
360 Ok(())
361}
362
363#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
365pub struct Acceptance {
366 pub command: String,
368 pub exit_code: Option<i32>,
371 #[serde(default)]
373 pub timed_out: bool,
374 #[serde(default)]
376 pub seconds: u64,
377 #[serde(default)]
379 pub output: String,
380}
381
382impl Acceptance {
383 pub fn passed(&self) -> bool {
385 self.exit_code == Some(0) && !self.timed_out
386 }
387
388 pub fn last_line(&self) -> Option<&str> {
390 self.output
391 .lines()
392 .rev()
393 .map(str::trim)
394 .find(|l| !l.is_empty())
395 }
396}
397
398pub fn trusted(
402 root: &Path,
403 plan_file: Option<&str>,
404 id: &str,
405 command: &str,
406) -> Result<(), String> {
407 let relative = plan_file.unwrap_or(DEFAULT_FILE);
408 let parts = crate::facts::normalise(&[relative.to_owned()])
409 .map_err(|e| format!("the task's plan file cannot be used: {e}"))?;
410 let shown = parts
411 .first()
412 .cloned()
413 .unwrap_or_else(|| relative.to_owned());
414 let path = shown
415 .split('/')
416 .fold(root.to_path_buf(), |p, part| p.join(part));
417 let refuse = |why: String| {
418 format!(
419 "task `{id}` has the acceptance command `{command}`, but {why}. An acceptance \
420 command runs only when the repository's plan file holds the same command for \
421 the same task, so a command written into shared memory cannot run on its own. \
422 Add it to `{shown}` (then `memfork plan write {shown}`), or remove it from the task."
423 )
424 };
425 let text = std::fs::read_to_string(&path)
426 .map_err(|_| refuse(format!("there is no readable `{shown}` in this project")))?;
427 let tasks = parse(&text).map_err(|e| refuse(format!("`{shown}` could not be read: {e}")))?;
428 match tasks.iter().find(|t| t.id == id) {
429 Some(t) if t.accept.as_deref() == Some(command) => Ok(()),
430 Some(t) => Err(refuse(format!(
431 "`{shown}` gives task `{id}` {}",
432 t.accept
433 .as_deref()
434 .map_or_else(|| "no command".to_owned(), |a| format!("the command `{a}`"))
435 ))),
436 None => Err(refuse(format!("`{shown}` has no task `{id}`"))),
437 }
438}
439
440pub fn prepare_done(
444 root: &Path,
445 id: &str,
446 task: &serde_json::Value,
447) -> Result<Option<Acceptance>, String> {
448 let Some(command) = normalise_accept(task.get("accept").and_then(serde_json::Value::as_str))
449 else {
450 return Ok(None);
451 };
452 trusted(
453 root,
454 task.get("plan_file").and_then(serde_json::Value::as_str),
455 id,
456 &command,
457 )?;
458 let timeout = task
459 .get("timeout_seconds")
460 .and_then(serde_json::Value::as_u64)
461 .unwrap_or(DEFAULT_TIMEOUT_SECONDS)
462 .clamp(1, MAX_TIMEOUT_SECONDS);
463 Ok(Some(run(root, &command, Duration::from_secs(timeout))))
464}
465
466fn shell(command: &str) -> Command {
468 if cfg!(windows) {
469 let comspec = std::env::var_os("ComSpec").unwrap_or_else(|| {
470 let root = std::env::var_os("SystemRoot").unwrap_or_else(|| "C:\\Windows".into());
471 Path::new(&root)
472 .join("System32")
473 .join("cmd.exe")
474 .into_os_string()
475 });
476 let mut cmd = Command::new(comspec);
477 cmd.arg("/D").arg("/C").arg(command);
478 cmd
479 } else {
480 let mut cmd = Command::new("/bin/sh");
481 cmd.arg("-c").arg(command);
482 cmd
483 }
484}
485
486#[cfg(unix)]
488fn own_group(cmd: &mut Command) {
489 use std::os::unix::process::CommandExt as _;
490 cmd.process_group(0);
491}
492
493#[cfg(not(unix))]
494fn own_group(_cmd: &mut Command) {}
495
496fn kill_tree(child: &mut std::process::Child) {
498 let pid = child.id().to_string();
499 if cfg!(windows) {
500 let root = std::env::var_os("SystemRoot").unwrap_or_else(|| "C:\\Windows".into());
501 let taskkill = Path::new(&root).join("System32").join("taskkill.exe");
502 let _ = Command::new(taskkill)
503 .args(["/T", "/F", "/PID", &pid])
504 .stdin(Stdio::null())
505 .stdout(Stdio::null())
506 .stderr(Stdio::null())
507 .status();
508 } else {
509 let _ = Command::new("/bin/kill")
512 .args(["-KILL", "--", &format!("-{pid}")])
513 .stdin(Stdio::null())
514 .stdout(Stdio::null())
515 .stderr(Stdio::null())
516 .status();
517 }
518 let _ = child.kill();
519 let _ = child.wait();
520}
521
522const DRAIN: Duration = Duration::from_secs(2);
525
526fn tail_of(mut from: impl std::io::Read + Send + 'static) -> std::sync::mpsc::Receiver<Vec<u8>> {
529 let (tx, rx) = std::sync::mpsc::channel();
530 std::thread::spawn(move || {
531 let mut kept: Vec<u8> = Vec::new();
532 let mut buffer = [0u8; 8192];
533 while let Ok(n) = from.read(&mut buffer) {
534 if n == 0 {
535 break;
536 }
537 kept.extend_from_slice(&buffer[..n]);
538 if kept.len() > OUTPUT_TAIL_BYTES * 2 {
539 kept.drain(..kept.len() - OUTPUT_TAIL_BYTES);
540 }
541 }
542 let _ = tx.send(kept);
543 });
544 rx
545}
546
547pub fn run(root: &Path, command: &str, timeout: Duration) -> Acceptance {
549 let started = Instant::now();
550 let mut cmd = shell(command);
551 cmd.current_dir(root)
552 .stdin(Stdio::null())
553 .stdout(Stdio::piped())
554 .stderr(Stdio::piped());
555 own_group(&mut cmd);
556 let mut child = match cmd.spawn() {
557 Ok(child) => child,
558 Err(e) => {
559 return Acceptance {
560 command: command.to_owned(),
561 exit_code: None,
562 timed_out: false,
563 seconds: 0,
564 output: format!("the command could not be started: {e}"),
565 }
566 }
567 };
568 let out = child.stdout.take().map(tail_of);
569 let err = child.stderr.take().map(tail_of);
570 let deadline = started + timeout;
571 let (exit_code, timed_out) = loop {
572 match child.try_wait() {
573 Ok(Some(status)) => break (status.code(), false),
574 Ok(None) if Instant::now() >= deadline => {
575 kill_tree(&mut child);
576 break (None, true);
577 }
578 Ok(None) => std::thread::sleep(Duration::from_millis(50)),
579 Err(_) => {
580 kill_tree(&mut child);
581 break (None, false);
582 }
583 }
584 };
585 let wait = |rx: Option<std::sync::mpsc::Receiver<Vec<u8>>>| -> Vec<u8> {
588 rx.and_then(|rx| {
589 if timed_out {
590 rx.recv_timeout(DRAIN).ok()
591 } else {
592 rx.recv().ok()
593 }
594 })
595 .unwrap_or_default()
596 };
597 let mut bytes = wait(out);
598 bytes.extend(wait(err));
599 if bytes.len() > OUTPUT_TAIL_BYTES {
600 bytes.drain(..bytes.len() - OUTPUT_TAIL_BYTES);
601 }
602 let mut output = String::from_utf8_lossy(&bytes).into_owned();
603 if timed_out {
604 output.push_str(&format!("\n(stopped after {} seconds)", timeout.as_secs()));
605 }
606 Acceptance {
607 command: command.to_owned(),
608 exit_code,
609 timed_out,
610 seconds: started.elapsed().as_secs(),
611 output,
612 }
613}
614
615pub fn read_file(path: &Path) -> Result<String, String> {
617 let mut text = String::new();
618 std::fs::File::open(path)
619 .and_then(|mut f| f.read_to_string(&mut text))
620 .map_err(|e| format!("cannot read {}: {e}", path.display()))?;
621 Ok(text)
622}
623
624#[cfg(test)]
625mod tests {
626 use super::*;
627
628 fn task(id: &str, deps: &[&str]) -> PlanTask {
629 PlanTask {
630 id: id.to_owned(),
631 title: format!("do {id}"),
632 detail: None,
633 depends_on: deps.iter().map(|d| (*d).to_owned()).collect(),
634 accept: None,
635 timeout_seconds: None,
636 }
637 }
638
639 #[test]
640 fn every_built_in_template_is_a_short_valid_plan_with_a_command_to_fill_in() {
641 let all = templates(None);
642 assert_eq!(all.len(), 5);
643 for t in &all {
644 assert_eq!(t.problem, None, "{}", t.name);
645 assert!(!t.description.is_empty(), "{} has no description", t.name);
646 let tasks = parse(&t.text).expect("parses");
647 assert!(
648 (4..=6).contains(&tasks.len()),
649 "{} has {} tasks",
650 t.name,
651 tasks.len()
652 );
653 assert!(
654 check_alone(&tasks).expect("no cycle").is_empty(),
655 "{}",
656 t.name
657 );
658 assert!(
659 t.text.contains("accept = \"\""),
660 "{} has nothing to fill in",
661 t.name
662 );
663 assert!(tasks.iter().all(|task| task.accept.is_none()), "{}", t.name);
665 crate::secrets::check(&t.name, &t.text, &crate::secrets::Allow::default())
666 .expect("no secret-shaped text");
667 }
668 }
669
670 #[test]
671 fn a_persons_own_template_is_listed_and_can_replace_a_built_in_one() {
672 let data = tempfile::tempdir().expect("tempdir");
673 let dir = data.path().join(TEMPLATES_DIR);
674 std::fs::create_dir_all(&dir).expect("dir");
675 std::fs::write(
676 dir.join("release.toml"),
677 "description = \"cut a release\"\n[[task]]\nid = \"tag\"\ntitle = \"tag it\"\n",
678 )
679 .expect("w");
680 std::fs::write(
681 dir.join("bugfix.toml"),
682 "description = \"ours\"\n[[task]]\nid = \"a\"\ntitle = \"a\"\n",
683 )
684 .expect("w");
685 std::fs::write(dir.join("broken.toml"), "[[task]\n").expect("w");
686 let all = templates(Some(data.path()));
687 let names: Vec<&str> = all.iter().map(|t| t.name.as_str()).collect();
688 assert_eq!(
689 names,
690 ["feature", "bugfix", "refactor", "upgrade", "tests", "broken", "release"]
691 );
692 assert_eq!(all[1].description, "ours");
693 assert!(all[5].problem.is_some());
694 }
695
696 #[test]
697 fn a_cycle_is_named_and_refused() {
698 let err = check_graph(
699 &[task("a", &["c"]), task("b", &["a"]), task("c", &["b"])],
700 &BTreeMap::new(),
701 )
702 .expect_err("a cycle");
703 assert!(err.contains("a -> c -> b -> a"), "{err}");
704 assert!(check_graph(&[task("a", &[]), task("b", &["a"])], &BTreeMap::new()).is_ok());
705 }
706
707 #[test]
708 fn dependencies_must_exist_and_stay_in_the_project() {
709 let err = check_graph(&[task("b", &["a"])], &BTreeMap::new()).expect_err("missing");
710 assert!(err.contains("not a task"), "{err}");
711 let mut others = BTreeMap::new();
712 others.insert("a".to_owned(), Vec::new());
713 assert!(check_graph(&[task("b", &["a"])], &others).is_ok());
714 let err = check_shape(&[task("b", &["other:a"])]).expect_err("another project");
715 assert!(err.contains("another project"), "{err}");
716 }
717
718 #[test]
719 fn an_empty_accept_is_no_command() {
720 let tasks = parse(
721 "[[task]]\nid = \"a\"\ntitle = \"t\"\naccept = \"\"\n\n[[task]]\nid = \"b\"\ntitle = \"u\"\naccept = \" \"\n",
722 )
723 .expect("parsed");
724 assert!(tasks.iter().all(|t| t.accept.is_none()));
725 let root = tempfile::tempdir().expect("tempdir");
726 let answer = prepare_done(root.path(), "a", &serde_json::json!({"accept": ""}));
727 assert_eq!(answer, Ok(None));
728 }
729
730 #[test]
731 fn only_a_command_the_plan_file_holds_runs() {
732 let root = tempfile::tempdir().expect("tempdir");
733 let task = serde_json::json!({"accept": "exit 0"});
734 let err = prepare_done(root.path(), "a", &task).expect_err("no file");
735 assert!(err.contains("memfork-plan.toml"), "{err}");
736 std::fs::write(
737 root.path().join(DEFAULT_FILE),
738 "[[task]]\nid = \"a\"\ntitle = \"t\"\naccept = \"exit 1\"\n",
739 )
740 .expect("written");
741 let err = prepare_done(root.path(), "a", &task).expect_err("different");
742 assert!(err.contains("`exit 1`"), "{err}");
743 std::fs::write(
744 root.path().join(DEFAULT_FILE),
745 "[[task]]\nid = \"a\"\ntitle = \"t\"\naccept = \"exit 0\"\n",
746 )
747 .expect("written");
748 let ran = prepare_done(root.path(), "a", &task)
749 .expect("trusted")
750 .expect("ran");
751 assert!(ran.passed(), "{ran:?}");
752 }
753
754 #[test]
755 fn a_run_reports_its_exit_its_output_and_a_timeout() {
756 let root = tempfile::tempdir().expect("tempdir");
757 let failed = run(
758 root.path(),
759 "echo first && echo second && exit 3",
760 Duration::from_secs(60),
761 );
762 assert_eq!(failed.exit_code, Some(3), "{failed:?}");
763 assert_eq!(failed.last_line(), Some("second"));
764 assert!(!failed.passed());
765 let slow = if cfg!(windows) {
766 "ping -n 30 127.0.0.1 > NUL"
767 } else {
768 "sleep 30"
769 };
770 let started = Instant::now();
771 let stopped = run(root.path(), slow, Duration::from_secs(1));
772 assert!(stopped.timed_out && !stopped.passed(), "{stopped:?}");
773 assert!(
774 started.elapsed() < Duration::from_secs(20),
775 "the timeout did not stop it"
776 );
777 }
778
779 #[test]
780 fn output_is_bounded() {
781 let root = tempfile::tempdir().expect("tempdir");
782 let noisy = if cfg!(windows) {
783 "for /L %i in (1,1,3000) do @echo line %i"
784 } else {
785 "i=1; while [ $i -le 3000 ]; do echo line $i; i=$((i+1)); done"
786 };
787 let ran = run(root.path(), noisy, Duration::from_secs(60));
788 assert!(ran.passed(), "{ran:?}");
789 assert!(
790 ran.output.len() <= OUTPUT_TAIL_BYTES + 64,
791 "{}",
792 ran.output.len()
793 );
794 assert_eq!(ran.last_line(), Some("line 3000"));
795 }
796}