#![allow(
clippy::disallowed_methods,
clippy::disallowed_types,
reason = "Workflow contract I/O is synchronous local file access, not async network I/O"
)]
use std::{
collections::BTreeMap,
fmt,
io::Write,
path::{Path, PathBuf},
};
use chrono::{DateTime, TimeDelta, Utc};
use clap::{Subcommand, ValueEnum};
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ValueEnum)]
#[serde(rename_all = "lowercase")]
pub enum WorkflowMode {
Full,
Fast,
}
impl fmt::Display for WorkflowMode {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Full => write!(f, "full"),
Self::Fast => write!(f, "fast"),
}
}
}
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PhaseStatus {
#[default]
Pending,
InProgress,
Complete,
Skipped,
}
#[derive(Debug, Default, Serialize, Deserialize)]
pub struct PhaseEvidence {
#[serde(skip_serializing_if = "Option::is_none")]
pub issue_url: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub comment_id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub spec_path: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub ticket_refs: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
pub user_approved: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub branch: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub pr_url: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub tests_passed: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub pipeline_ok: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub review_report_path: Option<String>,
}
#[derive(Debug, Default, Serialize, Deserialize)]
pub struct Phase {
pub name: String,
pub status: PhaseStatus,
pub started_at: Option<String>,
pub completed_at: Option<String>,
pub executor: Option<String>,
#[serde(default)]
pub evidence: PhaseEvidence,
}
#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum GateCheck {
Pass,
MissingEvidence(String),
PhaseNotComplete(u8),
}
#[derive(Debug, Serialize, Deserialize)]
pub struct WorkflowContract {
pub version: String,
pub workflow_id: String,
pub title: String,
pub mode: WorkflowMode,
#[serde(skip_serializing_if = "Option::is_none")]
pub skill_source: Option<String>,
pub created_at: String,
pub updated_at: String,
pub current_phase: u8,
pub phases: BTreeMap<String, Phase>,
}
impl WorkflowContract {
#[must_use]
pub fn can_enter_phase(&self, target: u8) -> GateCheck {
match target {
2 => {
let Some(phase1) = self.phases.get("1") else {
return GateCheck::PhaseNotComplete(1);
};
if phase1.status != PhaseStatus::Complete {
return GateCheck::PhaseNotComplete(1);
}
if phase1.evidence.issue_url.is_none() {
return GateCheck::MissingEvidence("issue_url".into());
}
if self.mode == WorkflowMode::Full && phase1.evidence.comment_id.is_none() {
return GateCheck::MissingEvidence("comment_id".into());
}
GateCheck::Pass
}
3 => {
let Some(phase1) = self.phases.get("1") else {
return GateCheck::PhaseNotComplete(1);
};
if phase1.status != PhaseStatus::Complete {
return GateCheck::PhaseNotComplete(1);
}
if phase1.evidence.issue_url.is_none() {
return GateCheck::MissingEvidence("issue_url".into());
}
if self.mode == WorkflowMode::Fast {
return GateCheck::Pass;
}
let Some(phase2) = self.phases.get("2") else {
return GateCheck::PhaseNotComplete(2);
};
if phase2.status != PhaseStatus::Complete {
return GateCheck::PhaseNotComplete(2);
}
if phase2.evidence.spec_path.is_none() {
return GateCheck::MissingEvidence("spec_path".into());
}
if phase2.evidence.user_approved != Some(true) {
return GateCheck::MissingEvidence("user_approved".into());
}
GateCheck::Pass
}
4 => {
let Some(phase3) = self.phases.get("3") else {
return GateCheck::PhaseNotComplete(3);
};
if phase3.status != PhaseStatus::Complete {
return GateCheck::PhaseNotComplete(3);
}
if phase3.evidence.pr_url.is_none() {
return GateCheck::MissingEvidence("pr_url".into());
}
if phase3.evidence.tests_passed != Some(true) {
return GateCheck::MissingEvidence("tests_passed".into());
}
GateCheck::Pass
}
_ => GateCheck::MissingEvidence("invalid phase".into()),
}
}
}
#[derive(Debug, Subcommand)]
pub enum WorkflowCommand {
Create {
#[arg(long)]
title: String,
#[arg(long, value_enum, default_value_t = WorkflowMode::Full)]
mode: WorkflowMode,
},
List,
Status {
workflow_id: String,
},
Archive {
workflow_id: String,
},
Cleanup {
#[arg(long, default_value = "90")]
older_than: i64,
},
}
pub fn handle(command: WorkflowCommand) -> miette::Result<()> {
match command {
WorkflowCommand::Create { title, mode } => create_workflow(&title, mode),
WorkflowCommand::List => list_workflows(),
WorkflowCommand::Status { workflow_id } => show_status(&workflow_id),
WorkflowCommand::Archive { workflow_id } => archive_workflow(&workflow_id),
WorkflowCommand::Cleanup { older_than } => cleanup_archives(older_than),
}
}
fn workflow_dir() -> PathBuf {
let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
cwd.join(".cache/workflows/active")
}
fn archive_dir() -> PathBuf {
let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
cwd.join(".cache/workflows/archive")
}
fn validate_workflow_id(workflow_id: &str) -> miette::Result<()> {
let pattern = regex::Regex::new(r"^wf-\d{4}-\d{2}-\d{2}-\d{3}$")
.map_err(|e| miette::miette!("内部错误:workflow_id 正则编译失败: {e}"))?;
if pattern.is_match(workflow_id) {
Ok(())
} else {
Err(miette::miette!(
"无效的 workflow_id '{workflow_id}',格式应为 wf-YYYY-MM-DD-NNN"
))
}
}
fn list_workflows() -> miette::Result<()> {
let dir = workflow_dir();
if !dir.exists() {
println!("(无 active workflows)");
return Ok(());
}
let mut found = 0;
for entry in std::fs::read_dir(&dir).map_err(|e| miette::miette!("读取目录失败: {e}"))? {
let entry = entry.map_err(|e| miette::miette!("读取条目失败: {e}"))?;
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) == Some("json") {
let content =
std::fs::read_to_string(&path).map_err(|e| miette::miette!("读取合同失败: {e}"))?;
let contract: WorkflowContract =
serde_json::from_str(&content).map_err(|e| miette::miette!("解析合同失败: {e}"))?;
println!(
" {} | {} | Phase {} | {}",
contract.workflow_id, contract.title, contract.current_phase, contract.mode
);
found += 1;
}
}
if found == 0 {
println!("(无 active workflows)");
} else {
println!("\n共 {found} 个 active workflows");
}
Ok(())
}
fn show_status(workflow_id: &str) -> miette::Result<()> {
validate_workflow_id(workflow_id)?;
let path = workflow_dir().join(format!("{workflow_id}.json"));
if !path.exists() {
return Err(miette::miette!("workflow {workflow_id} 不存在"));
}
let content =
std::fs::read_to_string(&path).map_err(|e| miette::miette!("读取合同失败: {e}"))?;
let contract: WorkflowContract =
serde_json::from_str(&content).map_err(|e| miette::miette!("解析合同失败: {e}"))?;
println!(
"{}",
serde_json::to_string_pretty(&contract).map_err(|e| miette::miette!("{e}"))?
);
print_gate_status(&contract);
Ok(())
}
fn print_gate_status(contract: &WorkflowContract) {
println!("\n门控检查(当前可进入的 Phase):");
for target in 2u8..=4 {
match contract.can_enter_phase(target) {
GateCheck::Pass => println!(" Phase {target}: 可进入"),
GateCheck::MissingEvidence(ev) => {
println!(" Phase {target}: 阻止(缺少证据 {ev})");
}
GateCheck::PhaseNotComplete(p) => {
println!(" Phase {target}: 阻止(阶段 {p} 未完成)");
}
}
}
}
fn create_workflow(title: &str, mode: WorkflowMode) -> miette::Result<()> {
let dir = workflow_dir();
let id = create_workflow_at(&dir, &archive_dir(), title, mode)?;
println!("✅ Workflow 已创建: {id}");
println!(" 合同: {}", dir.join(format!("{id}.json")).display());
Ok(())
}
fn create_workflow_at(
active_dir: &Path,
archive_root: &Path,
title: &str,
mode: WorkflowMode,
) -> miette::Result<String> {
if title.trim().is_empty() {
return Err(miette::miette!("title 不能为空"));
}
let date = Utc::now().format("%Y-%m-%d").to_string();
let mut seq = max_existing_seq(active_dir, archive_root, &date)?.saturating_add(1);
loop {
if seq > 999 {
return Err(miette::miette!(
"当日 workflow 序号已用尽(999),无法继续创建: {date}"
));
}
let id = format!("wf-{date}-{seq:03}");
std::fs::create_dir_all(active_dir)
.map_err(|e| miette::miette!("创建 active 目录失败: {e}"))?;
let path = active_dir.join(format!("{id}.json"));
match std::fs::OpenOptions::new()
.write(true)
.create_new(true)
.open(&path)
{
Ok(mut file) => {
let contract = new_contract(&id, title, mode);
let json = serde_json::to_string_pretty(&contract)
.map_err(|e| miette::miette!("序列化合同失败: {e}"))?;
file.write_all(json.as_bytes())
.map_err(|e| miette::miette!("写入合同失败: {e}"))?;
return Ok(id);
}
Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
seq = seq.saturating_add(1);
}
Err(e) => return Err(miette::miette!("创建合同文件失败: {e}")),
}
}
}
fn max_existing_seq(active_dir: &Path, archive_root: &Path, date: &str) -> miette::Result<u32> {
let prefix = format!("wf-{date}-");
let mut dirs: Vec<PathBuf> = Vec::new();
if active_dir.is_dir() {
dirs.push(active_dir.to_path_buf());
}
if archive_root.is_dir() {
for entry in std::fs::read_dir(archive_root)
.map_err(|e| miette::miette!("读取归档根目录失败: {e}"))?
{
let path = entry
.map_err(|e| miette::miette!("读取归档条目失败: {e}"))?
.path();
if path.is_dir() {
dirs.push(path);
}
}
}
let mut max_seq = 0u32;
for dir in &dirs {
let Ok(entries) = std::fs::read_dir(dir) else {
continue;
};
for entry in entries.flatten() {
let file_name = entry.file_name();
let Some(name) = file_name.to_str() else {
continue;
};
let Some(stem) = name.strip_suffix(".json") else {
continue;
};
let Some(seq_str) = stem.strip_prefix(&prefix) else {
continue;
};
if let Ok(seq) = seq_str.parse::<u32>() {
max_seq = max_seq.max(seq);
}
}
}
Ok(max_seq)
}
fn new_contract(workflow_id: &str, title: &str, mode: WorkflowMode) -> WorkflowContract {
let now = Utc::now().to_rfc3339();
let phase = |name: &str, status: PhaseStatus, started_at: Option<&str>| Phase {
name: name.to_string(),
status,
started_at: started_at.map(String::from),
completed_at: None,
executor: None,
evidence: PhaseEvidence::default(),
};
let mut phases = BTreeMap::new();
phases.insert(
"1".to_string(),
phase("Clarification", PhaseStatus::InProgress, Some(&now)),
);
phases.insert(
"2".to_string(),
phase("Planning", PhaseStatus::Pending, None),
);
phases.insert(
"3".to_string(),
phase("Execution", PhaseStatus::Pending, None),
);
phases.insert(
"4".to_string(),
phase("Delivery", PhaseStatus::Pending, None),
);
WorkflowContract {
version: "1.0".to_string(),
workflow_id: workflow_id.to_string(),
title: title.trim().to_string(),
mode,
skill_source: None,
created_at: now.clone(),
updated_at: now,
current_phase: 1,
phases,
}
}
fn archive_workflow(workflow_id: &str) -> miette::Result<()> {
archive_workflow_at(&workflow_dir(), &archive_dir(), workflow_id)
}
fn archive_workflow_at(
active_dir: &Path,
archive_root: &Path,
workflow_id: &str,
) -> miette::Result<()> {
validate_workflow_id(workflow_id)?;
let src = active_dir.join(format!("{workflow_id}.json"));
if !src.exists() {
return Err(miette::miette!("workflow {workflow_id} 不存在"));
}
let content =
std::fs::read_to_string(&src).map_err(|e| miette::miette!("读取合同失败: {e}"))?;
let contract: WorkflowContract =
serde_json::from_str(&content).map_err(|e| miette::miette!("解析合同失败: {e}"))?;
let phase4_status = contract.phases.get("4").map(|p| p.status);
if contract.current_phase != 4 || phase4_status != Some(PhaseStatus::Complete) {
return Err(miette::miette!(
"workflow 未完成(current_phase={}, phase_4_status={:?})",
contract.current_phase,
phase4_status
));
}
let now = Utc::now();
let month_dir = archive_root.join(now.format("%Y-%m").to_string());
std::fs::create_dir_all(&month_dir).map_err(|e| miette::miette!("创建归档目录失败: {e}"))?;
let dst = month_dir.join(format!("{workflow_id}.json"));
if dst.exists() {
return Err(miette::miette!(
"归档目标已存在: {},拒绝覆盖(可能是 workflow_id 复用,见 Issue #142)",
dst.display()
));
}
std::fs::copy(&src, &dst).map_err(|e| miette::miette!("复制到归档失败: {e}"))?;
std::fs::remove_file(&src).map_err(|e| miette::miette!("删除 active 合同失败: {e}"))?;
println!("workflow {workflow_id} 已归档到 {}", month_dir.display());
Ok(())
}
fn cleanup_archives(older_than_days: i64) -> miette::Result<()> {
cleanup_archives_at(&archive_dir(), older_than_days)
}
fn cleanup_archives_at(dir: &Path, older_than_days: i64) -> miette::Result<()> {
if !dir.exists() {
println!("(无归档)");
return Ok(());
}
let duration = TimeDelta::try_days(older_than_days)
.ok_or_else(|| miette::miette!("无效的天数: {older_than_days}"))?;
let threshold = Utc::now() - duration;
let mut cleaned = 0;
for month_entry in
std::fs::read_dir(dir).map_err(|e| miette::miette!("读取归档目录失败: {e}"))?
{
let month_entry = month_entry.map_err(|e| miette::miette!("读取月份目录失败: {e}"))?;
let month_dir = month_entry.path();
if !month_dir.is_dir() {
continue;
}
for entry in
std::fs::read_dir(&month_dir).map_err(|e| miette::miette!("读取归档条目失败: {e}"))?
{
let entry = entry.map_err(|e| miette::miette!("读取文件失败: {e}"))?;
let path = entry.path();
if path.extension().and_then(|e| e.to_str()) != Some("json") {
continue;
}
let content =
std::fs::read_to_string(&path).map_err(|e| miette::miette!("读取合同失败: {e}"))?;
let contract: WorkflowContract =
serde_json::from_str(&content).map_err(|e| miette::miette!("解析合同失败: {e}"))?;
if let Ok(created) = DateTime::parse_from_rfc3339(&contract.created_at)
&& created.with_timezone(&Utc) < threshold
{
std::fs::remove_file(&path)
.map_err(|e| miette::miette!("删除过期归档失败: {e}"))?;
cleaned += 1;
}
}
if std::fs::read_dir(&month_dir).is_ok_and(|mut d| d.next().is_none()) {
std::fs::remove_dir(&month_dir).ok();
}
}
println!("已清理 {cleaned} 个过期归档");
Ok(())
}
#[cfg(test)]
#[allow(
clippy::panic,
reason = "Test code: panic is acceptable for assertion failures"
)]
mod tests {
use super::*;
fn base_contract(mode: &str) -> WorkflowContract {
let json = format!(
r#"{{
"version": "1.0",
"workflow_id": "wf-2026-07-09-001",
"title": "feat: test",
"mode": "{mode}",
"created_at": "2026-07-09T00:00:00Z",
"updated_at": "2026-07-09T00:00:00Z",
"current_phase": 1,
"phases": {{
"1": {{ "name": "Clarification", "status": "in_progress", "started_at": "2026-07-09T00:00:00Z" }},
"2": {{ "name": "Planning", "status": "pending" }},
"3": {{ "name": "Execution", "status": "pending" }},
"4": {{ "name": "Delivery", "status": "pending" }}
}}
}}"#
);
serde_json::from_str(&json).expect("deserialize base contract")
}
#[test]
fn test_should_accept_valid_workflow_id() {
assert!(validate_workflow_id("wf-2026-07-09-001").is_ok());
}
#[test]
fn test_should_reject_workflow_id_with_path_traversal() {
assert!(validate_workflow_id("../../etc/passwd").is_err());
assert!(validate_workflow_id("wf-2026-07-09-001/../secret").is_err());
assert!(validate_workflow_id("wf-2026-7-9-1").is_err());
assert!(validate_workflow_id("").is_err());
}
#[test]
fn test_should_reject_archive_with_path_traversal_id() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
std::fs::create_dir_all(&active).expect("create active");
let result = archive_workflow_at(&active, &archive, "../../evil");
assert!(
result.is_err(),
"path traversal id must be rejected before any file I/O"
);
}
#[test]
fn test_should_roundtrip_contract_serialization() {
let contract = base_contract("fast");
let json = serde_json::to_string_pretty(&contract).expect("serialize");
let deserialized: WorkflowContract = serde_json::from_str(&json).expect("deserialize");
assert_eq!(deserialized.workflow_id, contract.workflow_id);
assert_eq!(deserialized.title, contract.title);
assert!(matches!(deserialized.mode, WorkflowMode::Fast));
}
#[test]
fn test_gate_1_to_2_blocks_without_issue_url() {
let mut contract = base_contract("full");
contract.phases.get_mut("1").expect("phase 1").status = PhaseStatus::Complete;
let result = contract.can_enter_phase(2);
assert!(
matches!(result, GateCheck::MissingEvidence(_)),
"should block without issue_url"
);
}
#[test]
fn test_gate_1_to_2_passes_with_issue_url() {
let mut contract = base_contract("full");
let phase1 = contract.phases.get_mut("1").expect("phase 1");
phase1.status = PhaseStatus::Complete;
phase1.evidence.issue_url = Some("https://github.com/org/repo/issues/1".to_string());
phase1.evidence.comment_id = Some("12345".to_string());
let result = contract.can_enter_phase(2);
assert!(matches!(result, GateCheck::Pass));
}
#[test]
fn test_gate_2_to_3_fast_mode_passes_after_phase1() {
let mut contract = base_contract("fast");
let phase1 = contract.phases.get_mut("1").expect("phase 1");
phase1.status = PhaseStatus::Complete;
phase1.evidence.issue_url = Some("https://github.com/org/repo/issues/1".to_string());
let result = contract.can_enter_phase(3);
assert!(
matches!(result, GateCheck::Pass),
"fast mode should pass gate 3 once phase 1 is complete"
);
}
#[test]
fn test_gate_2_to_3_fast_mode_blocked_without_phase1() {
let contract = base_contract("fast");
let result = contract.can_enter_phase(3);
assert!(
matches!(result, GateCheck::PhaseNotComplete(1)),
"fast mode must not bypass phase 1 completion"
);
}
#[test]
fn test_gate_2_to_3_fast_mode_blocked_without_issue_url() {
let mut contract = base_contract("fast");
contract.phases.get_mut("1").expect("phase 1").status = PhaseStatus::Complete;
let result = contract.can_enter_phase(3);
assert!(
matches!(result, GateCheck::MissingEvidence(_)),
"fast mode still requires issue_url"
);
}
#[test]
fn test_gate_3_to_4_never_fast_exempt() {
let mut contract = base_contract("fast");
contract.phases.get_mut("3").expect("phase 3").status = PhaseStatus::Complete;
let result = contract.can_enter_phase(4);
assert!(
matches!(result, GateCheck::MissingEvidence(_)),
"Gate 3→4 must never be fast-exempt"
);
}
const SCHEMA_EXAMPLE_CONTRACT: &str = r#"{
"version": "1.0",
"workflow_id": "wf-2026-07-09-001",
"title": "feat: TOON 输出格式",
"mode": "full",
"created_at": "2026-07-09T02:59:32Z",
"updated_at": "2026-07-09T03:30:00Z",
"current_phase": 3,
"phases": {
"1": {
"name": "Clarification",
"status": "complete",
"started_at": "2026-07-09T02:59:32Z",
"completed_at": "2026-07-09T03:10:00Z",
"executor": "claude-code-3.7",
"evidence": {
"issue_url": "https://github.com/org/repo/issues/74",
"comment_id": "4921173903"
}
},
"2": {
"name": "Planning",
"status": "complete",
"started_at": "2026-07-09T03:10:00Z",
"completed_at": "2026-07-09T03:20:00Z",
"executor": "claude-code-3.7",
"evidence": {
"spec_path": "docs/superpowers/specs/2026-07-09-toon-design.md",
"user_approved": true
}
},
"3": {
"name": "Execution",
"status": "in_progress",
"started_at": "2026-07-09T03:20:00Z",
"completed_at": null,
"executor": "subagent-task-3",
"evidence": {}
},
"4": {
"name": "Delivery",
"status": "pending",
"started_at": null,
"completed_at": null,
"executor": null,
"evidence": {}
}
}
}"#;
#[test]
fn test_should_deserialize_schema_example_contract() {
let contract: WorkflowContract =
serde_json::from_str(SCHEMA_EXAMPLE_CONTRACT).expect("deserialize schema example");
assert_eq!(contract.version, "1.0");
assert!(matches!(contract.mode, WorkflowMode::Full));
assert_eq!(contract.current_phase, 3);
assert_eq!(contract.phases.len(), 4);
let phase1 = contract.phases.get("1").expect("phase 1");
assert_eq!(phase1.name, "Clarification");
assert_eq!(phase1.status, PhaseStatus::Complete);
assert_eq!(
phase1.evidence.issue_url.as_deref(),
Some("https://github.com/org/repo/issues/74")
);
let phase3 = contract.phases.get("3").expect("phase 3");
assert_eq!(phase3.status, PhaseStatus::InProgress);
let phase4 = contract.phases.get("4").expect("phase 4");
assert_eq!(phase4.status, PhaseStatus::Pending);
}
#[test]
fn test_should_serialize_mode_lowercase_and_phases_object() {
let contract = base_contract("full");
let json = serde_json::to_string(&contract).expect("serialize");
assert!(
json.contains(r#""mode":"full""#),
"mode must be lowercase: {json}"
);
assert!(
json.contains(r#""phases":{"#),
"phases must be an object: {json}"
);
assert!(
json.contains(r#""1":"#),
"phases must be keyed by string: {json}"
);
}
#[test]
fn test_should_omit_none_evidence_fields_on_serialize() {
let mut contract = base_contract("full");
let phase1 = contract.phases.get_mut("1").expect("phase 1");
phase1.evidence.issue_url = Some("https://github.com/org/repo/issues/1".to_string());
let json = serde_json::to_string(&contract).expect("serialize");
assert!(
json.contains(r#""issue_url":"https://github.com/org/repo/issues/1""#),
"set evidence field must be present: {json}"
);
assert!(
!json.contains(r#""comment_id":null"#),
"unset evidence fields must be omitted: {json}"
);
assert!(
!json.contains(r#""spec_path":null"#),
"unset evidence fields must be omitted: {json}"
);
assert!(
json.contains(r#""evidence":{}"#),
"empty evidence should be an empty object: {json}"
);
}
#[test]
fn test_should_archive_completed_workflow() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
std::fs::create_dir_all(&active).expect("create active");
let mut contract = base_contract("full");
contract.current_phase = 4;
contract.phases.get_mut("4").expect("phase 4").status = PhaseStatus::Complete;
let id = contract.workflow_id.clone();
std::fs::write(
active.join(format!("{id}.json")),
serde_json::to_string_pretty(&contract).expect("serialize"),
)
.expect("write contract");
archive_workflow_at(&active, &archive, &id).expect("archive should succeed");
assert!(
!active.join(format!("{id}.json")).exists(),
"active contract should be removed after archive"
);
let month = Utc::now().format("%Y-%m").to_string();
assert!(
archive.join(&month).join(format!("{id}.json")).exists(),
"contract should be archived under YYYY-MM"
);
}
#[test]
fn test_should_reject_archive_of_incomplete_workflow() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
std::fs::create_dir_all(&active).expect("create active");
let contract = base_contract("full");
let id = contract.workflow_id.clone();
std::fs::write(
active.join(format!("{id}.json")),
serde_json::to_string_pretty(&contract).expect("serialize"),
)
.expect("write contract");
let result = archive_workflow_at(&active, &archive, &id);
assert!(result.is_err(), "incomplete workflow must not be archived");
assert!(
active.join(format!("{id}.json")).exists(),
"active contract must remain when archive is rejected"
);
}
#[test]
fn test_should_cleanup_only_expired_archives() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let archive = tmp.path().join("archive");
let old_month = archive.join("2020-01");
let fresh_month = archive.join(Utc::now().format("%Y-%m").to_string());
std::fs::create_dir_all(&old_month).expect("create old month");
std::fs::create_dir_all(&fresh_month).expect("create fresh month");
let mut old = base_contract("full");
old.created_at = "2020-01-01T00:00:00Z".to_string();
std::fs::write(
old_month.join("wf-2020-01-01-001.json"),
serde_json::to_string(&old).expect("serialize"),
)
.expect("write old contract");
let mut fresh = base_contract("full");
fresh.created_at = Utc::now().to_rfc3339();
std::fs::write(
fresh_month.join("wf-fresh-001.json"),
serde_json::to_string(&fresh).expect("serialize"),
)
.expect("write fresh contract");
cleanup_archives_at(&archive, 90).expect("cleanup should succeed");
assert!(
!old_month.join("wf-2020-01-01-001.json").exists(),
"expired contract should be deleted"
);
assert!(
!old_month.exists(),
"empty month directory should be removed"
);
assert!(
fresh_month.join("wf-fresh-001.json").exists(),
"fresh contract should be retained"
);
}
fn today() -> String {
Utc::now().format("%Y-%m-%d").to_string()
}
fn seed_archived(archive: &Path, seq: u32) {
let date = today();
let month_dir = archive.join(&date[..7]);
std::fs::create_dir_all(&month_dir).expect("create month dir");
let mut contract = base_contract("full");
contract.workflow_id = format!("wf-{date}-{seq:03}");
std::fs::write(
month_dir.join(format!("wf-{date}-{seq:03}.json")),
serde_json::to_string(&contract).expect("serialize"),
)
.expect("write archived contract");
}
fn seed_active(active: &Path, seq: u32) {
let date = today();
std::fs::create_dir_all(active).expect("create active dir");
let mut contract = base_contract("full");
contract.workflow_id = format!("wf-{date}-{seq:03}");
std::fs::write(
active.join(format!("wf-{date}-{seq:03}.json")),
serde_json::to_string(&contract).expect("serialize"),
)
.expect("write active contract");
}
#[test]
fn test_should_create_001_when_no_existing_contracts() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
let id = create_workflow_at(&active, &archive, "feat: test", WorkflowMode::Full)
.expect("create should succeed");
assert_eq!(id, format!("wf-{}-001", today()));
assert!(active.join(format!("{id}.json")).exists());
}
#[test]
fn test_should_increment_id_after_previous_contract_archived() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
seed_archived(&archive, 1);
let id = create_workflow_at(&active, &archive, "feat: second", WorkflowMode::Full)
.expect("create should succeed");
assert_eq!(
id,
format!("wf-{}-002", today()),
"archived -001 must not be reused"
);
}
#[test]
fn test_create_should_scan_both_active_and_archive_for_max_id() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
seed_active(&active, 2);
seed_archived(&archive, 3);
let id = create_workflow_at(&active, &archive, "feat: fourth", WorkflowMode::Fast)
.expect("create should succeed");
assert_eq!(id, format!("wf-{}-004", today()));
}
#[test]
fn test_should_not_reuse_id_on_repeated_creates() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
let id1 =
create_workflow_at(&active, &archive, "feat: a", WorkflowMode::Full).expect("first");
let id2 =
create_workflow_at(&active, &archive, "feat: b", WorkflowMode::Full).expect("second");
assert_ne!(id1, id2, "repeated creates must never share an ID");
assert!(active.join(format!("{id1}.json")).exists());
assert!(active.join(format!("{id2}.json")).exists());
}
#[test]
fn test_created_contract_should_match_schema_shape() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
let id = create_workflow_at(&active, &archive, "feat: shape", WorkflowMode::Fast)
.expect("create should succeed");
let content =
std::fs::read_to_string(active.join(format!("{id}.json"))).expect("read contract");
let contract: WorkflowContract = serde_json::from_str(&content).expect("parse contract");
assert_eq!(contract.workflow_id, id);
assert_eq!(contract.title, "feat: shape");
assert_eq!(contract.current_phase, 1);
assert!(matches!(contract.mode, WorkflowMode::Fast));
assert_eq!(contract.phases.len(), 4);
assert_eq!(
contract.phases.get("1").expect("phase 1").status,
PhaseStatus::InProgress
);
assert_eq!(
contract.phases.get("2").expect("phase 2").status,
PhaseStatus::Pending
);
}
#[test]
fn test_should_reject_empty_title_on_create() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
assert!(
create_workflow_at(&active, &archive, " ", WorkflowMode::Full).is_err(),
"blank title must be rejected"
);
}
#[test]
fn test_should_reject_archive_when_destination_exists() {
let tmp = tempfile::TempDir::new().expect("temp dir");
let active = tmp.path().join("active");
let archive = tmp.path().join("archive");
std::fs::create_dir_all(&active).expect("create active");
let mut contract = base_contract("full");
contract.current_phase = 4;
contract.phases.get_mut("4").expect("phase 4").status = PhaseStatus::Complete;
let id = contract.workflow_id.clone();
let serialized = serde_json::to_string_pretty(&contract).expect("serialize");
std::fs::write(active.join(format!("{id}.json")), &serialized).expect("write active");
let month = Utc::now().format("%Y-%m").to_string();
let month_dir = archive.join(&month);
std::fs::create_dir_all(&month_dir).expect("create month dir");
let dst = month_dir.join(format!("{id}.json"));
std::fs::write(&dst, r#"{"sentinel":"original"}"#).expect("write sentinel");
let result = archive_workflow_at(&active, &archive, &id);
assert!(
result.is_err(),
"archive must refuse to overwrite an existing destination"
);
let preserved = std::fs::read_to_string(&dst).expect("read destination");
assert_eq!(
preserved, r#"{"sentinel":"original"}"#,
"existing archive must be preserved"
);
assert!(
active.join(format!("{id}.json")).exists(),
"active contract must remain when archive is rejected"
);
}
#[test]
fn test_should_roundtrip_skill_source_and_ticket_refs() {
let mut contract = base_contract("full");
contract.skill_source = Some("mattpocock".to_string());
contract
.phases
.get_mut("2")
.expect("phase 2")
.evidence
.ticket_refs = Some(vec![
".scratch/demo/issues/01-setup.md".to_string(),
"https://github.com/org/repo/issues/10".to_string(),
]);
let json = serde_json::to_string(&contract).expect("serialize");
assert!(
json.contains(r#""skill_source":"mattpocock""#),
"skill_source must serialize: {json}"
);
assert!(
json.contains(r#""ticket_refs":["#),
"ticket_refs must serialize: {json}"
);
let back: WorkflowContract = serde_json::from_str(&json).expect("deserialize");
assert_eq!(back.skill_source.as_deref(), Some("mattpocock"));
let refs = back
.phases
.get("2")
.expect("phase 2")
.evidence
.ticket_refs
.as_ref()
.expect("ticket_refs");
assert_eq!(refs.len(), 2);
}
#[test]
fn test_should_omit_absent_skill_source_and_ticket_refs() {
let contract = base_contract("full");
let json = serde_json::to_string(&contract).expect("serialize");
assert!(
!json.contains("skill_source"),
"absent skill_source must be omitted: {json}"
);
assert!(
!json.contains("ticket_refs"),
"absent ticket_refs must be omitted: {json}"
);
}
#[test]
fn test_should_deserialize_legacy_contract_without_skill_source() {
let contract: WorkflowContract =
serde_json::from_str(SCHEMA_EXAMPLE_CONTRACT).expect("legacy contract");
assert!(contract.skill_source.is_none());
}
}