draft-board 0.1.0-beta.0

package/app/backend/app/services/worktree_validator.py

@@ -0,0 +1,213 @@
+"""Worktree validation service - enforces safety checks for execution.
+
+This module provides hard validation that execution only happens in
+properly isolated worktrees, not the main repository.
+"""
+
+import subprocess
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from app.data_dir import LEGACY_WORKTREES_DIR, get_worktrees_root
+
+
+class WorktreeValidationError(StrEnum):
+    """Types of worktree validation failures."""
+
+    NOT_IN_DRAFT_DIR = "not_in_draft_dir"
+    ON_PROTECTED_BRANCH = "on_protected_branch"
+    IS_MAIN_REPO = "is_main_repo"
+    NOT_A_GIT_REPO = "not_a_git_repo"
+    PATH_MISMATCH = "path_mismatch"
+
+
+@dataclass
+class WorktreeValidationResult:
+    """Result of worktree validation."""
+
+    valid: bool
+    error: WorktreeValidationError | None = None
+    message: str | None = None
+    worktree_path: str | None = None
+    branch: str | None = None
+    main_repo_path: str | None = None
+
+    @classmethod
+    def success(cls, worktree_path: str, branch: str) -> "WorktreeValidationResult":
+        """Create a successful validation result."""
+        return cls(valid=True, worktree_path=worktree_path, branch=branch)
+
+    @classmethod
+    def failure(
+        cls,
+        error: WorktreeValidationError,
+        message: str,
+        worktree_path: str | None = None,
+        branch: str | None = None,
+        main_repo_path: str | None = None,
+    ) -> "WorktreeValidationResult":
+        """Create a failed validation result."""
+        return cls(
+            valid=False,
+            error=error,
+            message=message,
+            worktree_path=worktree_path,
+            branch=branch,
+            main_repo_path=main_repo_path,
+        )
+
+
+class WorktreeValidator:
+    """Validates that a path is a safe, isolated worktree for execution.
+
+    Safety Checks:
+    1. Path must be under .draft/worktrees/
+    2. Branch must NOT be main/master/develop (protected branches)
+    3. git rev-parse --show-toplevel must match the worktree path
+    4. Worktree path must be different from the main repo path
+
+    These checks prevent accidental execution in the main repository.
+    """
+
+    # Protected branches that should never be modified by automated execution
+    PROTECTED_BRANCHES = {"main", "master", "develop", "production", "staging"}
+
+    # Required path component for worktrees (central dir or legacy)
+    WORKTREE_PATH_MARKER = str(get_worktrees_root())
+    LEGACY_WORKTREE_PATH_MARKER = LEGACY_WORKTREES_DIR
+
+    def __init__(self, main_repo_path: Path | str):
+        """
+        Initialize the validator.
+
+        Args:
+            main_repo_path: Path to the main repository (not a worktree).
+        """
+        self.main_repo_path = Path(main_repo_path).resolve()
+
+    def validate(self, worktree_path: Path | str) -> WorktreeValidationResult:
+        """
+        Validate that a path is a safe worktree for execution.
+
+        Args:
+            worktree_path: Path to validate as a worktree.
+
+        Returns:
+            WorktreeValidationResult with validation status and details.
+        """
+        worktree = Path(worktree_path).resolve()
+        worktree_str = str(worktree)
+
+        # Check 1: Path must be under central data dir or legacy .draft/worktrees/
+        in_central = worktree_str.startswith(str(get_worktrees_root()))
+        in_legacy = self.LEGACY_WORKTREE_PATH_MARKER in worktree_str
+        if not in_central and not in_legacy:
+            return WorktreeValidationResult.failure(
+                error=WorktreeValidationError.NOT_IN_DRAFT_DIR,
+                message=(
+                    f"Worktree path must be under {self.WORKTREE_PATH_MARKER}/ "
+                    f"or legacy {self.LEGACY_WORKTREE_PATH_MARKER}/. "
+                    f"Got: {worktree_str}"
+                ),
+                worktree_path=worktree_str,
+            )
+
+        # Check 2: Must be a git repository
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--show-toplevel"],
+                cwd=worktree,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode != 0:
+                return WorktreeValidationResult.failure(
+                    error=WorktreeValidationError.NOT_A_GIT_REPO,
+                    message=f"Not a git repository: {worktree_str}",
+                    worktree_path=worktree_str,
+                )
+            git_toplevel = Path(result.stdout.strip()).resolve()
+        except subprocess.TimeoutExpired:
+            return WorktreeValidationResult.failure(
+                error=WorktreeValidationError.NOT_A_GIT_REPO,
+                message="git rev-parse timed out",
+                worktree_path=worktree_str,
+            )
+        except Exception as e:
+            return WorktreeValidationResult.failure(
+                error=WorktreeValidationError.NOT_A_GIT_REPO,
+                message=f"Failed to check git status: {e}",
+                worktree_path=worktree_str,
+            )
+
+        # Check 3: git toplevel must match worktree path (or be under it)
+        # This catches cases where someone symlinks or mounts a worktree elsewhere
+        if git_toplevel != worktree and not str(git_toplevel).startswith(str(worktree)):
+            return WorktreeValidationResult.failure(
+                error=WorktreeValidationError.PATH_MISMATCH,
+                message=(
+                    f"Git toplevel doesn't match worktree path. "
+                    f"Toplevel: {git_toplevel}, Worktree: {worktree}"
+                ),
+                worktree_path=worktree_str,
+            )
+
+        # Check 4: Worktree must NOT be the main repo
+        if git_toplevel == self.main_repo_path:
+            return WorktreeValidationResult.failure(
+                error=WorktreeValidationError.IS_MAIN_REPO,
+                message=(
+                    f"Cannot execute in main repository. "
+                    f"Use a worktree under {self.WORKTREE_PATH_MARKER}/. "
+                    f"Main repo: {self.main_repo_path}"
+                ),
+                worktree_path=worktree_str,
+                main_repo_path=str(self.main_repo_path),
+            )
+
+        # Check 5: Get current branch and verify it's not protected
+        try:
+            branch_result = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                cwd=worktree,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if branch_result.returncode != 0:
+                branch = "unknown"
+            else:
+                branch = branch_result.stdout.strip()
+        except Exception:
+            branch = "unknown"
+
+        if branch.lower() in self.PROTECTED_BRANCHES:
+            return WorktreeValidationResult.failure(
+                error=WorktreeValidationError.ON_PROTECTED_BRANCH,
+                message=(
+                    f"Cannot execute on protected branch '{branch}'. "
+                    f"Protected branches: {', '.join(sorted(self.PROTECTED_BRANCHES))}"
+                ),
+                worktree_path=worktree_str,
+                branch=branch,
+            )
+
+        # All checks passed
+        return WorktreeValidationResult.success(
+            worktree_path=worktree_str,
+            branch=branch,
+        )
+
+    def is_safe_for_execution(self, worktree_path: Path | str) -> bool:
+        """
+        Quick check if a path is safe for execution.
+
+        Args:
+            worktree_path: Path to check.
+
+        Returns:
+            True if the path passes all safety checks.
+        """
+        return self.validate(worktree_path).valid

package/app/backend/app/sqlite_kv.py

@@ -0,0 +1,278 @@
+"""Low-level SQLite operations for middleware (sync, used via asyncio.to_thread).
+
+These functions use raw SQLite connections (not SQLAlchemy sessions) for
+atomicity and to avoid interfering with the async session lifecycle.
+The middleware runs outside of route handlers, so it cannot use get_db().
+"""
+
+import os
+import sqlite3
+import time
+from pathlib import Path
+
+_BACKEND_DIR = Path(__file__).parent.parent.resolve()
+_DB_PATH = os.getenv("SQLITE_BACKEND_DB", str(_BACKEND_DIR / "kanban.db"))
+
+# Parse async DATABASE_URL to extract path if set
+_DATABASE_URL = os.getenv("DATABASE_URL", "")
+if _DATABASE_URL:
+    # Handle both sqlite:///path and sqlite+aiosqlite:///path
+    for prefix in ("sqlite+aiosqlite:///", "sqlite:///"):
+        if _DATABASE_URL.startswith(prefix):
+            _extracted = _DATABASE_URL[len(prefix) :]
+            if _extracted:
+                _DB_PATH = _extracted
+            break
+
+
+def _get_conn() -> sqlite3.Connection:
+    """Get a SQLite connection with WAL mode."""
+    conn = sqlite3.connect(_DB_PATH, timeout=30)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA busy_timeout=30000")
+    return conn
+
+
+# ─── Idempotency operations ───
+
+
+def idempotency_try_acquire(cache_key: str, lock_value: str, ttl_seconds: int) -> bool:
+    """Try to acquire an idempotency lock. Returns True if acquired."""
+    now = time.time()
+    now + ttl_seconds
+    conn = _get_conn()
+    try:
+        # Clean expired locks first
+        conn.execute(
+            "DELETE FROM idempotency_cache WHERE lock_expires_at IS NOT NULL "
+            "AND lock_expires_at < datetime('now')"
+        )
+        # Try atomic insert
+        cursor = conn.execute(
+            "INSERT OR IGNORE INTO idempotency_cache "
+            "(cache_key, lock_value, lock_expires_at, created_at) "
+            "VALUES (?, ?, datetime('now', ?), datetime('now'))",
+            (cache_key, lock_value, f"+{ttl_seconds} seconds"),
+        )
+        conn.commit()
+        return cursor.rowcount == 1
+    finally:
+        conn.close()
+
+
+def idempotency_get_lock(cache_key: str) -> str | None:
+    """Get the lock value for a key (None if not locked or expired)."""
+    conn = _get_conn()
+    try:
+        row = conn.execute(
+            "SELECT lock_value FROM idempotency_cache "
+            "WHERE cache_key = ? AND (lock_expires_at IS NULL OR lock_expires_at >= datetime('now'))",
+            (cache_key,),
+        ).fetchone()
+        return row[0] if row else None
+    finally:
+        conn.close()
+
+
+def idempotency_store_result(
+    cache_key: str, result_value: str, ttl_seconds: int
+) -> None:
+    """Store the result and clear the lock."""
+    conn = _get_conn()
+    try:
+        conn.execute(
+            "UPDATE idempotency_cache SET result_value = ?, "
+            "result_expires_at = datetime('now', ?), "
+            "lock_value = NULL, lock_expires_at = NULL "
+            "WHERE cache_key = ?",
+            (result_value, f"+{ttl_seconds} seconds", cache_key),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def idempotency_get_result(cache_key: str) -> str | None:
+    """Get cached result (None if not found or expired)."""
+    conn = _get_conn()
+    try:
+        row = conn.execute(
+            "SELECT result_value FROM idempotency_cache "
+            "WHERE cache_key = ? AND result_value IS NOT NULL "
+            "AND (result_expires_at IS NULL OR result_expires_at >= datetime('now'))",
+            (cache_key,),
+        ).fetchone()
+        return row[0] if row else None
+    finally:
+        conn.close()
+
+
+def idempotency_release_lock(cache_key: str) -> None:
+    """Release lock (delete entry if no result stored)."""
+    conn = _get_conn()
+    try:
+        conn.execute(
+            "DELETE FROM idempotency_cache WHERE cache_key = ? AND result_value IS NULL",
+            (cache_key,),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+# ─── Rate limit operations ───
+
+
+def rate_limit_check_and_record(
+    client_key: str, cost: int, window_seconds: int
+) -> tuple[int, float]:
+    """Check current usage and record new cost entry.
+
+    Returns (current_cost_before_recording, oldest_entry_time).
+    """
+    now = time.time()
+    window_start = now - window_seconds
+    expires_at = now + window_seconds
+
+    conn = _get_conn()
+    try:
+        # Cleanup expired
+        conn.execute("DELETE FROM rate_limit_entries WHERE expires_at < ?", (now,))
+
+        # Sum current cost in window (also filter by expires_at for consistency)
+        row = conn.execute(
+            "SELECT COALESCE(SUM(cost), 0) FROM rate_limit_entries "
+            "WHERE client_key = ? AND recorded_at > ? AND expires_at >= ?",
+            (client_key, window_start, now),
+        ).fetchone()
+        current_cost = row[0] if row else 0
+
+        # Get oldest entry time for retry-after calculation
+        oldest_row = conn.execute(
+            "SELECT MIN(recorded_at) FROM rate_limit_entries "
+            "WHERE client_key = ? AND recorded_at > ? AND expires_at >= ?",
+            (client_key, window_start, now),
+        ).fetchone()
+        oldest_time = oldest_row[0] if oldest_row and oldest_row[0] else now
+
+        # Record new entry
+        conn.execute(
+            "INSERT INTO rate_limit_entries (client_key, cost, recorded_at, expires_at) "
+            "VALUES (?, ?, ?, ?)",
+            (client_key, cost, now, expires_at),
+        )
+        conn.commit()
+
+        return current_cost, oldest_time
+    finally:
+        conn.close()
+
+
+def rate_limit_check_only(client_key: str, window_seconds: int) -> tuple[int, float]:
+    """Check current usage without recording. Returns (current_cost, oldest_time)."""
+    now = time.time()
+    window_start = now - window_seconds
+
+    conn = _get_conn()
+    try:
+        # Cleanup expired
+        conn.execute("DELETE FROM rate_limit_entries WHERE expires_at < ?", (now,))
+
+        row = conn.execute(
+            "SELECT COALESCE(SUM(cost), 0) FROM rate_limit_entries "
+            "WHERE client_key = ? AND recorded_at > ? AND expires_at >= ?",
+            (client_key, window_start, now),
+        ).fetchone()
+        current_cost = row[0] if row else 0
+
+        oldest_row = conn.execute(
+            "SELECT MIN(recorded_at) FROM rate_limit_entries "
+            "WHERE client_key = ? AND recorded_at > ? AND expires_at >= ?",
+            (client_key, window_start, now),
+        ).fetchone()
+        oldest_time = oldest_row[0] if oldest_row and oldest_row[0] else now
+
+        conn.commit()
+        return current_cost, oldest_time
+    finally:
+        conn.close()
+
+
+# ─── KV store operations (for queued messages) ───
+
+
+def kv_set(key: str, value: str, ttl_seconds: int | None = None) -> None:
+    """Set a key-value pair with optional TTL."""
+    conn = _get_conn()
+    try:
+        if ttl_seconds:
+            conn.execute(
+                "INSERT OR REPLACE INTO kv_store (key, value, expires_at, created_at) "
+                "VALUES (?, ?, datetime('now', ?), datetime('now'))",
+                (key, value, f"+{ttl_seconds} seconds"),
+            )
+        else:
+            conn.execute(
+                "INSERT OR REPLACE INTO kv_store (key, value, created_at) "
+                "VALUES (?, ?, datetime('now'))",
+                (key, value),
+            )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def kv_get(key: str) -> str | None:
+    """Get a value by key (None if not found or expired)."""
+    conn = _get_conn()
+    try:
+        row = conn.execute(
+            "SELECT value FROM kv_store WHERE key = ? "
+            "AND (expires_at IS NULL OR expires_at >= datetime('now'))",
+            (key,),
+        ).fetchone()
+        return row[0] if row else None
+    finally:
+        conn.close()
+
+
+def kv_take(key: str) -> str | None:
+    """Get and delete a value atomically (None if not found or expired)."""
+    conn = _get_conn()
+    try:
+        # Atomic get-and-delete using DELETE...RETURNING (SQLite 3.35+)
+        row = conn.execute(
+            "DELETE FROM kv_store WHERE key = ? "
+            "AND (expires_at IS NULL OR expires_at >= datetime('now')) "
+            "RETURNING value",
+            (key,),
+        ).fetchone()
+        conn.commit()
+        return row[0] if row else None
+    finally:
+        conn.close()
+
+
+def kv_delete(key: str) -> bool:
+    """Delete a key. Returns True if deleted."""
+    conn = _get_conn()
+    try:
+        cursor = conn.execute("DELETE FROM kv_store WHERE key = ?", (key,))
+        conn.commit()
+        return cursor.rowcount > 0
+    finally:
+        conn.close()
+
+
+def kv_exists(key: str) -> bool:
+    """Check if a key exists (and is not expired)."""
+    conn = _get_conn()
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM kv_store WHERE key = ? "
+            "AND (expires_at IS NULL OR expires_at >= datetime('now'))",
+            (key,),
+        ).fetchone()
+        return row is not None
+    finally:
+        conn.close()

package/app/backend/app/state_machine.py

@@ -0,0 +1,128 @@
+"""State machine implementation for ticket workflow.
+
+This module contains the TicketState enum and state transition rules.
+Event types and actor types are defined in models/enums.py but re-exported
+here for backwards compatibility.
+"""
+
+from enum import StrEnum
+
+# Re-export event types and actor types for backwards compatibility
+# The canonical definitions are in models/enums.py
+from app.models.enums import ActorType, EventType
+
+__all__ = [
+    "TicketState",
+    "ActorType",
+    "EventType",
+    "ALLOWED_TRANSITIONS",
+    "TERMINAL_STATES",
+    "validate_transition",
+    "get_allowed_transitions",
+    "is_terminal_state",
+]
+
+
+class TicketState(StrEnum):
+    """Enum representing valid ticket states."""
+
+    PROPOSED = "proposed"
+    PLANNED = "planned"
+    EXECUTING = "executing"
+    VERIFYING = "verifying"
+    NEEDS_HUMAN = "needs_human"
+    BLOCKED = "blocked"
+    DONE = "done"
+    ABANDONED = "abandoned"
+
+
+# Allowed state transitions map
+# Key: current state, Value: list of valid next states
+ALLOWED_TRANSITIONS: dict[TicketState, list[TicketState]] = {
+    TicketState.PROPOSED: [
+        TicketState.PLANNED,
+        TicketState.ABANDONED,
+    ],
+    TicketState.PLANNED: [
+        TicketState.PROPOSED,
+        TicketState.EXECUTING,
+        TicketState.BLOCKED,
+        TicketState.ABANDONED,
+    ],
+    TicketState.EXECUTING: [
+        TicketState.VERIFYING,
+        TicketState.NEEDS_HUMAN,
+        TicketState.BLOCKED,
+    ],
+    TicketState.VERIFYING: [
+        TicketState.EXECUTING,  # Rework needed
+        TicketState.NEEDS_HUMAN,  # Verification passed, awaiting human review
+        TicketState.BLOCKED,  # Verification failed
+        TicketState.DONE,  # Auto-approved (autonomy mode, skips NEEDS_HUMAN)
+    ],
+    TicketState.NEEDS_HUMAN: [
+        TicketState.EXECUTING,  # Human resolved, back to executing
+        TicketState.PLANNED,  # Human replanned
+        TicketState.DONE,  # Human approved revision
+        TicketState.ABANDONED,
+    ],
+    TicketState.BLOCKED: [
+        TicketState.PLANNED,  # Unblocked, back to planning
+        TicketState.EXECUTING,  # Retry execution (e.g., after fixing blocker or retrying failed execution)
+        TicketState.ABANDONED,
+    ],
+    TicketState.DONE: [
+        TicketState.EXECUTING,  # Human requested changes on revision
+    ],
+    TicketState.ABANDONED: [
+        TicketState.PLANNED,  # Reactivate accidentally abandoned tickets
+    ],
+}
+
+
+def validate_transition(from_state: TicketState, to_state: TicketState) -> bool:
+    """
+    Validate if a state transition is allowed.
+
+    Args:
+        from_state: The current state of the ticket
+        to_state: The desired new state
+
+    Returns:
+        True if the transition is valid, False otherwise
+    """
+    if from_state not in ALLOWED_TRANSITIONS:
+        return False
+    return to_state in ALLOWED_TRANSITIONS[from_state]
+
+
+def get_allowed_transitions(current_state: TicketState) -> list[TicketState]:
+    """
+    Get list of valid next states from the current state.
+
+    Args:
+        current_state: The current state of the ticket
+
+    Returns:
+        List of valid next states
+    """
+    return ALLOWED_TRANSITIONS.get(current_state, [])
+
+
+# Terminal states for workspace cleanup and watchdog purposes.
+# Note: DONE can transition back to EXECUTING if human requests changes on revision,
+# but is still considered "terminal" for cleanup purposes (workspace recreated if needed).
+TERMINAL_STATES: set[TicketState] = {TicketState.DONE, TicketState.ABANDONED}
+
+
+def is_terminal_state(state: TicketState) -> bool:
+    """
+    Check if a state is a terminal state.
+
+    Args:
+        state: The ticket state to check
+
+    Returns:
+        True if the state is terminal (DONE or ABANDONED)
+    """
+    return state in TERMINAL_STATES

package/app/backend/app/templates/__init__.py

@@ -0,0 +1,5 @@
+"""Project templates for Draft boards."""
+
+from .registry import TEMPLATES, get_template, list_templates
+
+__all__ = ["TEMPLATES", "get_template", "list_templates"]