handoff-mcp-server 0.10.0 → 0.12.0

package/src/storage/tasks.rs

@@ -4,6 +4,11 @@ use std::path::{Path, PathBuf};
 use anyhow::{Context, Result};
 use chrono::Utc;
 use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+fn is_empty_map(m: &HashMap<String, Value>) -> bool {
+    m.is_empty()
+}
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TaskData {
@@ -31,9 +36,13 @@ pub struct TaskData {
     pub dependencies: Vec<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub order: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub assignee: Option<String>,
+    #[serde(flatten, default, skip_serializing_if = "is_empty_map")]
+    pub extra: HashMap<String, Value>,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct Schedule {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub start_date: Option<String>,
@@ -44,7 +53,11 @@ pub struct Schedule {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub actual_hours: Option<f64>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub remaining_hours: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub milestone: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub pinned: Option<bool>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -65,6 +78,8 @@ pub struct TaskIndex {
     pub dependencies: Vec<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub order: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub assignee: Option<String>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub children: Vec<TaskIndex>,
 }
@@ -190,11 +205,60 @@ pub fn read_task(task_dir: &Path) -> Result<Option<(TaskData, String)>> {
 pub fn write_task(task_dir: &Path, status: &str, data: &TaskData) -> Result<()> {
     let file_path = task_dir.join(format!("_task.{status}.json"));
     let content = serde_json::to_string_pretty(data).context("Failed to serialize task")?;
-    std::fs::write(&file_path, content)
+    crate::storage::atomic_write(&file_path, content.as_bytes())
         .with_context(|| format!("Failed to write task: {}", file_path.display()))?;
     Ok(())
 }
 
+/// Read-modify-write a task with optimistic concurrency control.
+///
+/// Reads the current task, runs `mutate` on a copy, then re-reads just before
+/// writing: if the file's `updated_at` changed since the snapshot (another
+/// writer — e.g. the VSCode extension — won the race), the whole cycle retries
+/// up to `MAX_RETRIES` times. This matches the VSCode side's `updated_at`
+/// protocol (wiki/95-concurrency-safety.md) and prevents lost updates that
+/// atomic_write alone cannot (atomic_write stops *torn* reads, not *lost*
+/// updates).
+///
+/// `mutate` receives the current `TaskData` and the resolved status, and returns
+/// the new status the task should have after the change (usually unchanged).
+pub fn read_modify_write_task<F>(task_dir: &Path, mut mutate: F) -> Result<()>
+where
+    F: FnMut(&mut TaskData, &str) -> Result<String>,
+{
+    const MAX_RETRIES: usize = 5;
+
+    for attempt in 0..=MAX_RETRIES {
+        let (mut data, status) = read_task(task_dir)?
+            .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;
+        let snapshot_updated_at = data.updated_at.clone();
+
+        let new_status = mutate(&mut data, &status)?;
+
+        // Re-read to detect a concurrent writer before committing.
+        let current_updated_at = read_task(task_dir)?.and_then(|(d, _)| d.updated_at);
+        if current_updated_at != snapshot_updated_at {
+            // Someone else wrote between our read and write. Retry from scratch.
+            if attempt == MAX_RETRIES {
+                anyhow::bail!(
+                    "Concurrent modification of task in {} after {} retries; aborting to avoid \
+                     overwriting another writer's changes.",
+                    task_dir.display(),
+                    MAX_RETRIES
+                );
+            }
+            continue;
+        }
+
+        if new_status != status {
+            change_status(task_dir, &new_status)?;
+        }
+        write_task(task_dir, &new_status, &data)?;
+        return Ok(());
+    }
+    unreachable!("loop returns or bails within MAX_RETRIES iterations")
+}
+
 pub fn change_status(task_dir: &Path, new_status: &str) -> Result<()> {
     if !is_valid_status(new_status) {
         anyhow::bail!("Invalid status: {new_status}");
@@ -423,6 +487,7 @@ fn build_index_recursive(
             schedule: data.schedule,
             dependencies: data.dependencies,
             order: data.order,
+            assignee: data.assignee,
             children,
         });
     }
@@ -525,6 +590,61 @@ pub fn validate_skipped_transition(task_dir: &Path, data: &TaskData) -> Result<(
     Ok(())
 }
 
+/// Returns true if the task directory contains at least one child task
+/// (a non-`_`/`.`-prefixed subdirectory holding a task file).
+pub fn task_has_children(task_dir: &Path) -> Result<bool> {
+    if !task_dir.exists() {
+        return Ok(false);
+    }
+    for entry in std::fs::read_dir(task_dir)? {
+        let entry = entry?;
+        if !entry.file_type()?.is_dir() {
+            continue;
+        }
+        let name = entry.file_name().to_string_lossy().to_string();
+        if name.starts_with('_') || name.starts_with('.') {
+            continue;
+        }
+        if find_task_file(&entry.path())?.is_some() {
+            return Ok(true);
+        }
+    }
+    Ok(false)
+}
+
+/// Whether a task in the given status requires an effort estimate.
+/// Parent tasks (with children) and blocked/skipped tasks are exempt;
+/// this only covers the status dimension.
+pub fn status_requires_estimate(status: &str) -> bool {
+    matches!(status, "todo" | "in_progress" | "review" | "done")
+}
+
+/// Validate that a leaf task carries an `estimate_hours` when the project
+/// requires it. `has_children` lets the caller skip parent tasks.
+/// Returns an error guiding the caller to add an estimate.
+pub fn validate_estimate_required(
+    require_estimate_hours: bool,
+    status: &str,
+    has_children: bool,
+    schedule: Option<&Schedule>,
+) -> Result<()> {
+    if !require_estimate_hours || has_children || !status_requires_estimate(status) {
+        return Ok(());
+    }
+    let has_estimate = schedule
+        .and_then(|s| s.estimate_hours)
+        .is_some_and(|h| h > 0.0);
+    if !has_estimate {
+        anyhow::bail!(
+            "Task requires an effort estimate: set schedule.estimate_hours (hours, > 0) \
+             when creating or updating a leaf task in status '{status}'. \
+             Estimate the human-effort hours for this task. \
+             To disable this requirement project-wide, set settings.require_estimate_hours = false."
+        );
+    }
+    Ok(())
+}
+
 fn check_children_terminal(task_dir: &Path, parent_id: &str) -> Result<()> {
     if !task_dir.exists() {
         return Ok(());