draft-board 0.1.0-beta.0

package/app/backend/app/templates/registry.py

@@ -0,0 +1,243 @@
+"""Project template registry with pre-configured board setups."""
+
+from typing import TypedDict
+
+
+class TemplateGoal(TypedDict, total=False):
+    """A starter goal for a template."""
+
+    title: str
+    description: str
+
+
+class ProjectTemplate(TypedDict):
+    """A project template with pre-configured settings and starter goals."""
+
+    id: str
+    name: str
+    description: str
+    icon: str
+    category: str
+    config: dict
+    starter_goals: list[TemplateGoal]
+    tags: list[str]
+
+
+TEMPLATES: list[ProjectTemplate] = [
+    {
+        "id": "web-app",
+        "name": "Web Application",
+        "description": "Modern web app with React, Next.js, or Vue. Optimized for UI development.",
+        "icon": "🌐",
+        "category": "Frontend",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 300,
+            }
+        },
+        "starter_goals": [
+            {
+                "title": "Set up project structure",
+                "description": "Initialize the web app with proper folder structure, routing, and build configuration.",
+            },
+            {
+                "title": "Implement responsive layout",
+                "description": "Create a mobile-first responsive layout with navigation and theming support.",
+            },
+        ],
+        "tags": ["react", "nextjs", "vue", "frontend", "ui"],
+    },
+    {
+        "id": "api-service",
+        "name": "API Service",
+        "description": "REST or GraphQL API with FastAPI, Express, or Django. Optimized for backend development.",
+        "icon": "🔌",
+        "category": "Backend",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 400,
+            }
+        },
+        "starter_goals": [
+            {
+                "title": "Set up API framework",
+                "description": "Initialize the API with routing, middleware, and database connection.",
+            },
+            {
+                "title": "Add authentication",
+                "description": "Implement JWT or OAuth authentication with proper security.",
+            },
+            {
+                "title": "Add API documentation",
+                "description": "Generate OpenAPI/Swagger docs with examples and schemas.",
+            },
+        ],
+        "tags": ["api", "fastapi", "express", "django", "backend", "rest", "graphql"],
+    },
+    {
+        "id": "mobile-app",
+        "name": "Mobile App",
+        "description": "Cross-platform mobile app with React Native or Flutter. Optimized for mobile development.",
+        "icon": "📱",
+        "category": "Mobile",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 350,
+            }
+        },
+        "starter_goals": [
+            {
+                "title": "Set up navigation",
+                "description": "Configure screen navigation and routing for iOS and Android.",
+            },
+            {
+                "title": "Implement offline support",
+                "description": "Add local data persistence and offline-first architecture.",
+            },
+        ],
+        "tags": ["mobile", "react-native", "flutter", "ios", "android"],
+    },
+    {
+        "id": "data-pipeline",
+        "name": "Data Pipeline",
+        "description": "ETL/analytics pipeline with longer timeout for data processing tasks.",
+        "icon": "📊",
+        "category": "Data",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 600,  # 10 minutes for data processing
+            }
+        },
+        "starter_goals": [
+            {
+                "title": "Set up data sources",
+                "description": "Configure connections to databases, APIs, or file sources.",
+            },
+            {
+                "title": "Build transformation pipeline",
+                "description": "Implement data cleaning, validation, and transformation logic.",
+            },
+            {
+                "title": "Add monitoring and alerts",
+                "description": "Set up pipeline monitoring, error handling, and alerting.",
+            },
+        ],
+        "tags": ["data", "etl", "analytics", "pipeline", "airflow", "spark"],
+    },
+    {
+        "id": "docs-site",
+        "name": "Documentation Site",
+        "description": "Documentation with Docusaurus, MkDocs, or VitePress. Optimized for content writing.",
+        "icon": "📚",
+        "category": "Content",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 250,
+            }
+        },
+        "starter_goals": [
+            {
+                "title": "Set up docs structure",
+                "description": "Organize content into sections with proper navigation.",
+            },
+            {
+                "title": "Add search functionality",
+                "description": "Implement full-text search across documentation.",
+            },
+        ],
+        "tags": ["docs", "documentation", "docusaurus", "mkdocs", "vitepress"],
+    },
+    {
+        "id": "library",
+        "name": "Library/Package",
+        "description": "Reusable library or NPM/PyPI package. Optimized for library development.",
+        "icon": "📦",
+        "category": "Library",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 300,
+            }
+        },
+        "starter_goals": [
+            {
+                "title": "Set up build and packaging",
+                "description": "Configure build tools, TypeScript/types, and package.json/pyproject.toml.",
+            },
+            {
+                "title": "Add comprehensive tests",
+                "description": "Implement unit tests with high coverage and CI integration.",
+            },
+            {
+                "title": "Create usage examples",
+                "description": "Write clear examples and API documentation for library users.",
+            },
+        ],
+        "tags": ["library", "package", "npm", "pypi", "sdk"],
+    },
+    {
+        "id": "ml-model",
+        "name": "Machine Learning",
+        "description": "ML/AI model with training pipelines. Extended timeout for model training.",
+        "icon": "🤖",
+        "category": "AI/ML",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 900,  # 15 minutes for training
+            }
+        },
+        "starter_goals": [
+            {
+                "title": "Set up training pipeline",
+                "description": "Configure data loading, model architecture, and training loop.",
+            },
+            {
+                "title": "Add experiment tracking",
+                "description": "Integrate MLflow, Weights & Biases, or similar for experiment tracking.",
+            },
+            {
+                "title": "Implement model evaluation",
+                "description": "Create evaluation metrics, validation splits, and model comparison.",
+            },
+        ],
+        "tags": [
+            "ml",
+            "ai",
+            "machine-learning",
+            "pytorch",
+            "tensorflow",
+            "scikit-learn",
+        ],
+    },
+    {
+        "id": "blank",
+        "name": "Blank Project",
+        "description": "Start from scratch with default settings. No starter goals.",
+        "icon": "✨",
+        "category": "Other",
+        "config": {
+            "execute_config": {
+                "executor_model": "sonnet-4.5",
+                "timeout": 300,
+            }
+        },
+        "starter_goals": [],
+        "tags": ["blank", "custom"],
+    },
+]
+
+
+def get_template(template_id: str) -> ProjectTemplate | None:
+    """Get a template by ID."""
+    return next((t for t in TEMPLATES if t["id"] == template_id), None)
+
+
+def list_templates() -> list[ProjectTemplate]:
+    """List all available templates."""
+    return TEMPLATES

package/app/backend/app/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility modules for the backend application."""
+
+from app.utils.artifact_reader import read_artifact
+
+__all__ = ["read_artifact"]

package/app/backend/app/utils/artifact_reader.py

@@ -0,0 +1,87 @@
+"""Safe artifact reading utilities.
+
+Security Policy:
+    - Only reads files under central data dir or <repo_root>/.draft (legacy)
+    - Rejects absolute paths (unless under central data dir)
+    - Resolves canonical paths (follows symlinks)
+    - Caps file size to prevent memory exhaustion
+"""
+
+import os
+from pathlib import Path
+
+# Maximum artifact file size to read (2MB)
+MAX_ARTIFACT_BYTES = 2_000_000
+
+
+def _is_under(target: Path, allowed_root: Path) -> bool:
+    """Check if target path is under allowed_root using canonical paths."""
+    try:
+        common = os.path.commonpath(
+            [str(target.resolve(strict=False)), str(allowed_root.resolve(strict=False))]
+        )
+    except ValueError:
+        return False
+    return common == str(allowed_root.resolve(strict=False))
+
+
+def _read_with_cap(target: Path) -> str | None:
+    """Read a file with size cap to prevent memory exhaustion."""
+    if not target.is_file():
+        return None
+    try:
+        size = target.stat().st_size
+        if size > MAX_ARTIFACT_BYTES:
+            with target.open("rb") as f:
+                data = f.read(MAX_ARTIFACT_BYTES)
+            return data.decode("utf-8", errors="replace") + "\n\n[truncated]"
+        return target.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+
+
+def read_artifact(repo_root: Path, relpath: str | None) -> str | None:
+    """Safely read an artifact file, enforcing security constraints.
+
+    Security Policy:
+        - Accepts absolute paths under central data dir (~/.draft/)
+        - Accepts relative paths under <repo_root>/.draft (legacy)
+        - Resolves canonical path (follows symlinks)
+        - Caps file size to prevent memory exhaustion
+
+    Args:
+        repo_root: Absolute path to the repository root
+        relpath: Path to the artifact (absolute under data dir, or relative)
+
+    Returns:
+        File content if safe and exists, None otherwise
+    """
+    if not relpath:
+        return None
+
+    from app.data_dir import get_data_dir
+
+    rel = Path(relpath)
+
+    # If absolute path, check if it's under the central data dir
+    if rel.is_absolute():
+        data_dir = get_data_dir()
+        if _is_under(rel, data_dir):
+            return _read_with_cap(rel)
+        return None
+
+    # Try central data dir first (new paths)
+    data_dir = get_data_dir()
+    target = (data_dir / rel).resolve(strict=False)
+    if _is_under(target, data_dir):
+        result = _read_with_cap(target)
+        if result is not None:
+            return result
+
+    # Fall back to legacy <repo_root>/.draft
+    allowed_root = (repo_root / ".draft").resolve(strict=False)
+    target = (repo_root / rel).resolve(strict=False)
+    if _is_under(target, allowed_root):
+        return _read_with_cap(target)
+
+    return None

package/app/backend/app/utils/circuit_breaker.py

@@ -0,0 +1,229 @@
+"""Circuit breaker pattern for resilient external API calls.
+
+Prevents cascading failures by temporarily stopping requests to a failing service,
+giving it time to recover.
+"""
+
+import logging
+import threading
+from collections.abc import Callable
+from datetime import datetime, timedelta
+from enum import StrEnum
+from typing import TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class CircuitState(StrEnum):
+    """Circuit breaker states."""
+
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Failing, reject requests immediately
+    HALF_OPEN = "half_open"  # Testing if service recovered
+
+
+class CircuitBreakerError(Exception):
+    """Raised when circuit breaker is open."""
+
+    pass
+
+
+class CircuitBreaker:
+    """Circuit breaker for external API calls with automatic recovery.
+
+    States:
+        - CLOSED: Normal operation, requests pass through
+        - OPEN: Too many failures, reject all requests immediately
+        - HALF_OPEN: Testing recovery, allow limited requests
+
+    Transitions:
+        - CLOSED -> OPEN: After failure_threshold consecutive failures
+        - OPEN -> HALF_OPEN: After timeout_seconds elapsed
+        - HALF_OPEN -> CLOSED: After success_threshold consecutive successes
+        - HALF_OPEN -> OPEN: On any failure
+
+    Thread-safe.
+    """
+
+    def __init__(
+        self,
+        name: str = "default",
+        failure_threshold: int = 5,
+        success_threshold: int = 2,
+        timeout_seconds: int = 60,
+    ):
+        """Initialize circuit breaker.
+
+        Args:
+            name: Name for logging
+            failure_threshold: Number of failures before opening circuit
+            success_threshold: Number of successes needed to close circuit (from half-open)
+            timeout_seconds: Seconds to wait before trying half-open
+        """
+        self.name = name
+        self.failure_threshold = failure_threshold
+        self.success_threshold = success_threshold
+        self.timeout_seconds = timeout_seconds
+
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._success_count = 0
+        self._last_failure_time: datetime | None = None
+        self._lock = threading.RLock()
+
+    @property
+    def state(self) -> CircuitState:
+        """Get current circuit state (thread-safe)."""
+        with self._lock:
+            return self._state
+
+    @property
+    def failure_count(self) -> int:
+        """Get current failure count (thread-safe)."""
+        with self._lock:
+            return self._failure_count
+
+    def call(self, func: Callable[..., T], *args, **kwargs) -> T:
+        """Execute a function with circuit breaker protection.
+
+        Args:
+            func: Function to call
+            *args: Positional arguments for func
+            **kwargs: Keyword arguments for func
+
+        Returns:
+            Return value from func
+
+        Raises:
+            CircuitBreakerError: If circuit is open
+            Exception: If func raises an exception
+        """
+        with self._lock:
+            current_state = self._state
+
+            # Check if we should transition from OPEN to HALF_OPEN
+            if current_state == CircuitState.OPEN:
+                if self._should_attempt_reset():
+                    logger.info(
+                        f"Circuit breaker '{self.name}' transitioning OPEN -> HALF_OPEN "
+                        f"(timeout elapsed: {self.timeout_seconds}s)"
+                    )
+                    self._state = CircuitState.HALF_OPEN
+                    self._success_count = 0
+                    current_state = CircuitState.HALF_OPEN
+                else:
+                    # Still open, reject immediately
+                    time_since_failure = (
+                        datetime.now() - self._last_failure_time
+                    ).total_seconds()
+                    raise CircuitBreakerError(
+                        f"Circuit breaker '{self.name}' is OPEN "
+                        f"({self._failure_count} failures, retry in "
+                        f"{self.timeout_seconds - time_since_failure:.0f}s)"
+                    )
+
+        # Execute the function (outside lock to avoid blocking other threads)
+        try:
+            result = func(*args, **kwargs)
+            self._on_success()
+            return result
+        except Exception as e:
+            self._on_failure(e)
+            raise
+
+    def _should_attempt_reset(self) -> bool:
+        """Check if enough time has passed to attempt reset (must hold lock)."""
+        if self._last_failure_time is None:
+            return True
+        elapsed = datetime.now() - self._last_failure_time
+        return elapsed >= timedelta(seconds=self.timeout_seconds)
+
+    def _on_success(self):
+        """Handle successful call (transitions HALF_OPEN -> CLOSED)."""
+        with self._lock:
+            if self._state == CircuitState.HALF_OPEN:
+                self._success_count += 1
+                logger.info(
+                    f"Circuit breaker '{self.name}' success in HALF_OPEN "
+                    f"({self._success_count}/{self.success_threshold})"
+                )
+
+                if self._success_count >= self.success_threshold:
+                    logger.info(
+                        f"Circuit breaker '{self.name}' transitioning HALF_OPEN -> CLOSED "
+                        f"(service recovered)"
+                    )
+                    self._state = CircuitState.CLOSED
+                    self._failure_count = 0
+                    self._success_count = 0
+                    self._last_failure_time = None
+
+            elif self._state == CircuitState.CLOSED:
+                # Reset failure count on success in closed state
+                if self._failure_count > 0:
+                    logger.debug(
+                        f"Circuit breaker '{self.name}' success, "
+                        f"resetting failure count from {self._failure_count}"
+                    )
+                    self._failure_count = 0
+
+    def _on_failure(self, exception: Exception):
+        """Handle failed call (transitions CLOSED -> OPEN, HALF_OPEN -> OPEN)."""
+        with self._lock:
+            self._failure_count += 1
+            self._last_failure_time = datetime.now()
+
+            if self._state == CircuitState.HALF_OPEN:
+                # Any failure in half-open immediately opens circuit
+                logger.warning(
+                    f"Circuit breaker '{self.name}' failed in HALF_OPEN -> OPEN "
+                    f"(service still failing: {exception})"
+                )
+                self._state = CircuitState.OPEN
+                self._success_count = 0
+
+            elif self._state == CircuitState.CLOSED:
+                if self._failure_count >= self.failure_threshold:
+                    logger.error(
+                        f"Circuit breaker '{self.name}' CLOSED -> OPEN "
+                        f"(threshold reached: {self._failure_count} failures)"
+                    )
+                    self._state = CircuitState.OPEN
+                else:
+                    logger.warning(
+                        f"Circuit breaker '{self.name}' failure "
+                        f"{self._failure_count}/{self.failure_threshold}: {exception}"
+                    )
+
+    def reset(self):
+        """Manually reset circuit breaker to CLOSED state."""
+        with self._lock:
+            logger.info(f"Circuit breaker '{self.name}' manually reset to CLOSED")
+            self._state = CircuitState.CLOSED
+            self._failure_count = 0
+            self._success_count = 0
+            self._last_failure_time = None
+
+    def get_status(self) -> dict:
+        """Get circuit breaker status (for monitoring/debugging)."""
+        with self._lock:
+            status = {
+                "name": self.name,
+                "state": self._state.value,
+                "failure_count": self._failure_count,
+                "success_count": self._success_count,
+                "failure_threshold": self.failure_threshold,
+                "success_threshold": self.success_threshold,
+                "timeout_seconds": self.timeout_seconds,
+            }
+
+            if self._last_failure_time:
+                status["last_failure_time"] = self._last_failure_time.isoformat()
+                time_since_failure = (
+                    datetime.now() - self._last_failure_time
+                ).total_seconds()
+                status["seconds_since_failure"] = int(time_since_failure)
+
+            return status