forgex-cli 0.1.0__py3-none-any.whl

forgex/schemas/task.py

@@ -0,0 +1,118 @@
+"""Task system (spec section 54).
+
+Tasks support dependency ordering, priority, attempts, per-task files
+and acceptance criteria. The graph operations (topological order,
+readiness, cycle detection) live here so every consumer — engine, CLI,
+tests — shares one implementation.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import UTC, datetime
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from forgex.schemas.error import TaskGraphError
+
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+class TaskPriority(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+_PRIORITY_RANK = {
+    TaskPriority.LOW: 0,
+    TaskPriority.MEDIUM: 1,
+    TaskPriority.HIGH: 2,
+    TaskPriority.CRITICAL: 3,
+}
+
+
+class Task(BaseModel):
+    """A single unit of work produced by the Architect, executed by the Builder."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str  # e.g. "TASK-004"
+    description: str
+    priority: TaskPriority = TaskPriority.MEDIUM
+    status: TaskStatus = TaskStatus.PENDING
+    depends_on: list[str] = Field(default_factory=list)
+    files: list[str] = Field(default_factory=list)
+    acceptance_criteria: list[str] = Field(default_factory=list)
+    attempts: int = 0
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    result: str | None = None
+
+
+def topological_order(tasks: list[Task]) -> list[Task]:
+    """Return tasks in topological order, with priority breaking ties among ready tasks.
+
+    Raises TaskGraphError on duplicate IDs, unknown dependencies, or cycles.
+    """
+    task_map: dict[str, Task] = {}
+    for task in tasks:
+        if task.id in task_map:
+            raise TaskGraphError(f"Duplicate task ID: {task.id}")
+        task_map[task.id] = task
+
+    in_degree: dict[str, int] = {t.id: 0 for t in tasks}
+    dependents: dict[str, list[str]] = defaultdict(list)
+
+    for task in tasks:
+        for dep in task.depends_on:
+            if dep not in task_map:
+                raise TaskGraphError(f"Task {task.id} depends on unknown task: {dep}")
+            dependents[dep].append(task.id)
+            in_degree[task.id] += 1
+
+    # Ready heap or list sorted by priority descending
+    ready: list[str] = [t.id for t in tasks if in_degree[t.id] == 0]
+    ready.sort(key=lambda tid: (-_PRIORITY_RANK[task_map[tid].priority], tid))
+
+    ordered: list[Task] = []
+
+    while ready:
+        curr_id = ready.pop(0)
+        ordered.append(task_map[curr_id])
+
+        newly_ready: list[str] = []
+        for dep_id in dependents[curr_id]:
+            in_degree[dep_id] -= 1
+            if in_degree[dep_id] == 0:
+                newly_ready.append(dep_id)
+
+        if newly_ready:
+            ready.extend(newly_ready)
+            ready.sort(key=lambda tid: (-_PRIORITY_RANK[task_map[tid].priority], tid))
+
+    if len(ordered) != len(tasks):
+        raise TaskGraphError("Dependency cycle detected in tasks")
+
+    return ordered
+
+
+def ready_tasks(tasks: list[Task]) -> list[Task]:
+    """Return list of tasks that are PENDING and whose dependencies are COMPLETED or SKIPPED."""
+    completed_or_skipped = {
+        t.id for t in tasks if t.status in (TaskStatus.COMPLETED, TaskStatus.SKIPPED)
+    }
+
+    ready = []
+    for t in tasks:
+        if t.status == TaskStatus.PENDING and all(dep in completed_or_skipped for dep in t.depends_on):
+            ready.append(t)
+    return ready

forgex/storage/__init__.py

@@ -0,0 +1,25 @@
+"""Storage package: SQLite database, migrations, and repositories."""
+
+from forgex.storage.database import Database
+from forgex.storage.migrations import run_migrations
+from forgex.storage.repositories import (
+    CheckpointRepository,
+    ErrorRepository,
+    EventRepository,
+    ModelUsageRepository,
+    ProjectRepository,
+    RunRepository,
+    TaskRepository,
+)
+
+__all__ = [
+    "CheckpointRepository",
+    "Database",
+    "ErrorRepository",
+    "EventRepository",
+    "ModelUsageRepository",
+    "ProjectRepository",
+    "RunRepository",
+    "TaskRepository",
+    "run_migrations",
+]

forgex/storage/database.py

@@ -0,0 +1,40 @@
+"""SQLite access layer (spec section 25).
+
+The project database lives at .forgex/state.db (gitignored): a
+rebuildable query index and run history. WAL mode keeps concurrent
+readers safe; foreign keys are enforced.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from forgex.storage.migrations import run_migrations
+
+
+class Database:
+    """Lazy-connecting wrapper around a project-local SQLite database."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self._conn: sqlite3.Connection | None = None
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            conn = sqlite3.connect(str(self.path))
+            conn.row_factory = sqlite3.Row
+            conn.execute("PRAGMA foreign_keys = ON")
+            conn.execute("PRAGMA journal_mode = WAL")
+            conn.execute("PRAGMA synchronous = NORMAL")
+            conn.execute("PRAGMA busy_timeout = 5000")
+            run_migrations(conn)
+            self._conn = conn
+        return self._conn
+
+    def close(self) -> None:
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None

forgex/storage/migrations.py

@@ -0,0 +1,130 @@
+"""Forward-only schema migrations for the project database.
+
+  v1 (Phase 2): projects, runs, tasks, events, errors
+  v2 (Phase 3): model_usage
+  v3 (Phase 6): checkpoints
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+SCHEMA_V1 = """
+CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER PRIMARY KEY
+);
+
+CREATE TABLE IF NOT EXISTS projects (
+    project_id TEXT PRIMARY KEY,
+    path       TEXT NOT NULL,
+    name       TEXT NOT NULL,
+    status     TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS runs (
+    run_id      TEXT PRIMARY KEY,
+    project_id  TEXT NOT NULL REFERENCES projects(project_id),
+    request     TEXT NOT NULL,
+    status      TEXT NOT NULL,
+    phase       TEXT NOT NULL,
+    iteration   INTEGER NOT NULL DEFAULT 0,
+    started_at  TEXT NOT NULL,
+    finished_at TEXT,
+    summary     TEXT,
+    error       TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_runs_project ON runs(project_id);
+
+CREATE TABLE IF NOT EXISTS tasks (
+    id                  TEXT NOT NULL,
+    project_id          TEXT NOT NULL REFERENCES projects(project_id),
+    description         TEXT NOT NULL,
+    priority            TEXT NOT NULL DEFAULT 'medium',
+    status              TEXT NOT NULL DEFAULT 'pending',
+    depends_on          TEXT NOT NULL DEFAULT '[]',
+    files               TEXT NOT NULL DEFAULT '[]',
+    acceptance_criteria TEXT NOT NULL DEFAULT '[]',
+    attempts            INTEGER NOT NULL DEFAULT 0,
+    created_at          TEXT NOT NULL,
+    updated_at          TEXT NOT NULL,
+    result              TEXT,
+    PRIMARY KEY (id, project_id)
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_project ON tasks(project_id);
+
+CREATE TABLE IF NOT EXISTS events (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts         TEXT NOT NULL,
+    type       TEXT NOT NULL,
+    run_id     TEXT,
+    data       TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+
+CREATE TABLE IF NOT EXISTS errors (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_id TEXT NOT NULL REFERENCES projects(project_id),
+    run_id     TEXT,
+    ts         TEXT NOT NULL,
+    source     TEXT NOT NULL,
+    kind       TEXT NOT NULL,
+    message    TEXT NOT NULL,
+    detail     TEXT
+);
+"""
+
+SCHEMA_V2 = """
+CREATE TABLE IF NOT EXISTS model_usage (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts            TEXT NOT NULL,
+    run_id        TEXT,
+    agent         TEXT NOT NULL,
+    provider      TEXT NOT NULL,
+    model         TEXT NOT NULL,
+    input_tokens  INTEGER,
+    output_tokens INTEGER,
+    total_tokens  INTEGER,
+    latency_ms    REAL,
+    attempts      INTEGER NOT NULL DEFAULT 1,
+    success       INTEGER NOT NULL DEFAULT 1,
+    error         TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_model_usage_run ON model_usage(run_id);
+"""
+
+SCHEMA_V3 = """
+CREATE TABLE IF NOT EXISTS checkpoints (
+    id          TEXT PRIMARY KEY,
+    project_id  TEXT NOT NULL,
+    label       TEXT NOT NULL,
+    git_commit  TEXT,
+    description TEXT,
+    created_at  TEXT NOT NULL,
+    run_id      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_checkpoints_project ON checkpoints(project_id);
+"""
+
+MIGRATIONS: list[tuple[int, str]] = [
+    (1, SCHEMA_V1),
+    (2, SCHEMA_V2),
+    (3, SCHEMA_V3),
+]
+
+
+def run_migrations(conn: sqlite3.Connection) -> int:
+    """Run all unapplied migrations in order. Returns the current schema version."""
+    conn.execute("CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY)")
+    row = conn.execute("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1").fetchone()
+    current_version = row[0] if row else 0
+
+    for version, script in MIGRATIONS:
+        if version > current_version:
+            conn.executescript(script)
+            conn.execute("INSERT OR REPLACE INTO schema_version (version) VALUES (?)", (version,))
+            conn.commit()
+            current_version = version
+
+    return current_version