caudate-cli 0.1.0__py3-none-any.whl

planning/forge_models.py

@@ -0,0 +1,718 @@
+"""Forge — autonomous coding-harness data model.
+
+Ports the LocalForge schema (Drizzle/SQLite) onto Cognos's existing
+SQLAlchemy infrastructure. Tables live in `data/cognos.db` alongside
+the existing `strategies` and `performance_log` tables — no new DB,
+no new migration tool, idempotent `create_all` on import.
+
+Tables:
+  forge_projects         one row per project (= sandbox/projects/<slug>)
+  forge_features         backlog cards: title, description, AC, status, priority
+  forge_feature_deps     DAG edges (feature → depends-on-feature)
+  forge_sessions         one row per agent run (coding | bootstrapper)
+  forge_logs             streamed agent log lines (info|action|error|test|screenshot)
+  forge_chat_messages    bootstrapper conversation history
+  forge_settings         per-project key/value overrides (4th settings layer)
+
+Lifecycle of a feature:
+  backlog -> in_progress -> completed   (success path)
+  backlog -> in_progress -> backlog     (failure: priority demoted by 1)
+
+Session statuses mirror LocalForge:
+  in_progress -> completed | failed | terminated
+
+This module is pure data + simple CRUD — no LLM calls, no subagent
+spawning. The orchestrator (planning/orchestrator.py) drives state
+transitions; the bootstrapper (planning/planner.py extension) populates
+features; the kanban UI / CLI just renders these tables.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Iterator
+
+import sqlalchemy as sa
+from sqlalchemy import (
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    create_engine,
+)
+from sqlalchemy.orm import Session, declarative_base, relationship
+
+from config import SQLITE_PATH
+
+logger = logging.getLogger(__name__)
+
+# Forge has its own declarative base so its tables don't get tangled
+# with `memory/procedural.py`'s base — but they share the same SQLite
+# file, so a single `create_all` per file is enough.
+Base = declarative_base()
+
+
+# ──────────────────────────── Status enums ─────────────────────────────
+# Stored as plain TEXT to mirror LocalForge's Drizzle schema and stay
+# query-friendly from the sqlite3 CLI. Constants exposed for callers
+# instead of an Enum class so the validator doubles as documentation.
+
+PROJECT_STATUSES = ("active", "completed", "archived")
+FEATURE_STATUSES = ("backlog", "in_progress", "completed")
+FEATURE_CATEGORIES = ("functional", "style")
+SESSION_TYPES = ("coding", "bootstrapper")
+SESSION_STATUSES = ("in_progress", "completed", "failed", "terminated")
+MESSAGE_TYPES = ("info", "action", "error", "screenshot", "test_result")
+CHAT_ROLES = ("user", "assistant")
+
+
+def _now() -> datetime:
+    """UTC clock — kept as a function so tests can monkey-patch."""
+    return datetime.utcnow()
+
+
+# ──────────────────────────────── Tables ──────────────────────────────
+
+
+class ForgeProject(Base):
+    """A buildable project. Maps 1:1 to a folder under sandbox/projects/."""
+
+    __tablename__ = "forge_projects"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    name = Column(String(200), nullable=False)
+    description = Column(Text, nullable=True)
+    folder_path = Column(String, nullable=False, unique=True)
+    status = Column(String(20), nullable=False, default="active")
+    created_at = Column(DateTime, nullable=False, default=_now)
+    updated_at = Column(DateTime, nullable=False, default=_now, onupdate=_now)
+
+    features = relationship(
+        "ForgeFeature",
+        back_populates="project",
+        cascade="all, delete-orphan",
+    )
+    sessions = relationship(
+        "ForgeSession",
+        back_populates="project",
+        cascade="all, delete-orphan",
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<ForgeProject {self.id} {self.name!r}>"
+
+
+class ForgeFeature(Base):
+    """A unit of work the agent will implement. Cards on the kanban."""
+
+    __tablename__ = "forge_features"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    project_id = Column(
+        Integer,
+        ForeignKey("forge_projects.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    title = Column(String(200), nullable=False)
+    description = Column(Text, nullable=True)
+    acceptance_criteria = Column(Text, nullable=True)
+    status = Column(String(20), nullable=False, default="backlog")
+    priority = Column(Integer, nullable=False, default=0)
+    category = Column(String(20), nullable=False, default="functional")
+    # Optional shell command that must exit 0 to count this feature as
+    # passing post-implementation. Bootstrapper suggests one per stack
+    # (pytest / playwright / tsc / cargo test / etc).
+    verify_command = Column(Text, nullable=True)
+    # ADR 0003 — how many times the bootstrapper has been asked to
+    # revise this feature. The cap is 1: a feature parked at the
+    # 3-failure mark gets exactly one re-decompose attempt before
+    # being marked `failed` permanently.
+    revision_count = Column(Integer, nullable=False, default=0)
+    created_at = Column(DateTime, nullable=False, default=_now)
+    updated_at = Column(DateTime, nullable=False, default=_now, onupdate=_now)
+
+    project = relationship("ForgeProject", back_populates="features")
+    # Outgoing edges — features this one depends on.
+    outgoing_deps = relationship(
+        "ForgeFeatureDep",
+        foreign_keys="ForgeFeatureDep.feature_id",
+        back_populates="feature",
+        cascade="all, delete-orphan",
+    )
+
+    __table_args__ = (
+        Index("ix_forge_features_project", "project_id"),
+        Index("ix_forge_features_status", "status"),
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<ForgeFeature {self.id} {self.title!r} {self.status}>"
+
+
+class ForgeFeatureDep(Base):
+    """DAG edge: feature_id depends on depends_on_feature_id."""
+
+    __tablename__ = "forge_feature_deps"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    feature_id = Column(
+        Integer,
+        ForeignKey("forge_features.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    depends_on_feature_id = Column(
+        Integer,
+        ForeignKey("forge_features.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    feature = relationship(
+        "ForgeFeature",
+        foreign_keys=[feature_id],
+        back_populates="outgoing_deps",
+    )
+
+    __table_args__ = (
+        UniqueConstraint("feature_id", "depends_on_feature_id", name="uq_forge_dep"),
+        Index("ix_forge_deps_feature", "feature_id"),
+        Index("ix_forge_deps_dependson", "depends_on_feature_id"),
+    )
+
+
+class ForgeSession(Base):
+    """One agent run. Bootstrapper sessions produce features; coding
+    sessions implement them."""
+
+    __tablename__ = "forge_sessions"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    project_id = Column(
+        Integer,
+        ForeignKey("forge_projects.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    feature_id = Column(
+        Integer,
+        ForeignKey("forge_features.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    session_type = Column(String(20), nullable=False)  # coding | bootstrapper
+    status = Column(String(20), nullable=False, default="in_progress")
+    started_at = Column(DateTime, nullable=False, default=_now)
+    ended_at = Column(DateTime, nullable=True)
+
+    project = relationship("ForgeProject", back_populates="sessions")
+    logs = relationship(
+        "ForgeLog",
+        back_populates="session",
+        cascade="all, delete-orphan",
+    )
+    messages = relationship(
+        "ForgeChatMessage",
+        back_populates="session",
+        cascade="all, delete-orphan",
+    )
+
+    __table_args__ = (
+        Index("ix_forge_sessions_project", "project_id"),
+        Index("ix_forge_sessions_status", "status"),
+    )
+
+
+class ForgeLog(Base):
+    """Streamed agent log line. Mirrors LocalForge's `agent_logs`."""
+
+    __tablename__ = "forge_logs"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    session_id = Column(
+        Integer,
+        ForeignKey("forge_sessions.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    feature_id = Column(
+        Integer,
+        ForeignKey("forge_features.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    message = Column(Text, nullable=False)
+    message_type = Column(String(20), nullable=False, default="info")
+    screenshot_path = Column(String, nullable=True)
+    created_at = Column(DateTime, nullable=False, default=_now)
+
+    session = relationship("ForgeSession", back_populates="logs")
+
+    __table_args__ = (
+        Index("ix_forge_logs_session", "session_id"),
+    )
+
+
+class ForgeChatMessage(Base):
+    """Bootstrapper conversation history."""
+
+    __tablename__ = "forge_chat_messages"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    session_id = Column(
+        Integer,
+        ForeignKey("forge_sessions.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    role = Column(String(20), nullable=False)
+    content = Column(Text, nullable=False)
+    created_at = Column(DateTime, nullable=False, default=_now)
+
+    session = relationship("ForgeSession", back_populates="messages")
+
+    __table_args__ = (
+        Index("ix_forge_chat_session", "session_id"),
+    )
+
+
+class ForgeSetting(Base):
+    """Per-project key/value override. Sits above ./.cognos/settings.json
+    in the merge order, below CLI flags. Used for max_concurrent_agents,
+    coder_prompt, dev_server_port, playwright_enabled, etc."""
+
+    __tablename__ = "forge_settings"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    project_id = Column(
+        Integer,
+        ForeignKey("forge_projects.id", ondelete="CASCADE"),
+        nullable=True,
+    )  # NULL means "global forge default"
+    key = Column(String(100), nullable=False)
+    value = Column(Text, nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint("project_id", "key", name="uq_forge_setting"),
+    )
+
+
+# ─────────────────────────── Engine + sessions ─────────────────────────
+
+
+_engine: sa.Engine | None = None
+
+
+def get_engine() -> sa.Engine:
+    """Lazy-build the SQLAlchemy engine on first call. Reuses the same
+    SQLite file as the rest of Cognos."""
+    global _engine
+    if _engine is None:
+        # `check_same_thread=False` — Cognos's HTTP server runs requests
+        # on uvicorn worker threads; we need the connection to be
+        # shareable across threads. SQLite serialises writes internally.
+        _engine = create_engine(
+            f"sqlite:///{SQLITE_PATH}",
+            connect_args={"check_same_thread": False},
+            future=True,
+        )
+
+        # SQLite ignores foreign key declarations by default. Without
+        # this, deleting a project would orphan its features. Set the
+        # PRAGMA on every fresh connection so cascade rules actually
+        # fire.
+        @sa.event.listens_for(_engine, "connect")
+        def _fk_on(dbapi_conn, _conn_record):  # pragma: no cover
+            cur = dbapi_conn.cursor()
+            cur.execute("PRAGMA foreign_keys=ON")
+            cur.close()
+
+        Base.metadata.create_all(_engine)
+
+        # Runtime migrations for existing DBs — SQLAlchemy create_all
+        # is no-op on existing tables, so we manually ALTER for any
+        # columns we've added after first deploy. Idempotent.
+        _migrate_forge_schema(_engine)
+
+        logger.info(
+            "forge tables ready in %s (forge_projects, forge_features, "
+            "forge_feature_deps, forge_sessions, forge_logs, "
+            "forge_chat_messages, forge_settings)",
+            SQLITE_PATH,
+        )
+    return _engine
+
+
+def _migrate_forge_schema(engine: sa.Engine) -> None:
+    """Add columns SQLAlchemy create_all won't add to existing tables.
+
+    Each migration is idempotent — checks PRAGMA table_info first
+    before issuing ALTER. Safe to run on every startup."""
+    with engine.connect() as conn:
+        rows = conn.execute(sa.text("PRAGMA table_info(forge_features)")).fetchall()
+        cols = {r[1] for r in rows}  # name is column index 1
+        if "revision_count" not in cols:
+            conn.execute(sa.text(
+                "ALTER TABLE forge_features ADD COLUMN "
+                "revision_count INTEGER NOT NULL DEFAULT 0"
+            ))
+            conn.commit()
+            logger.info("forge: migrated forge_features +revision_count")
+
+
+@contextmanager
+def session_scope() -> Iterator[Session]:
+    """Yield a SQLAlchemy session, commit on exit, rollback on error.
+    Standard unit-of-work pattern — callers should not commit inside."""
+    sess = Session(get_engine(), future=True)
+    try:
+        yield sess
+        sess.commit()
+    except Exception:
+        sess.rollback()
+        raise
+    finally:
+        sess.close()
+
+
+def init() -> None:
+    """Force-create the tables. Useful as a CLI smoke test:
+        python -c "from planning.forge_models import init; init()"
+    Idempotent — calling twice is a no-op (CREATE IF NOT EXISTS semantics
+    via SQLAlchemy's `create_all`)."""
+    get_engine()
+
+
+# ──────────────────────── Convenience CRUD helpers ──────────────────────
+# These are deliberately small. The orchestrator and CLI compose them.
+# Anything more complex (joins, stats, kanban projection) lives in the
+# orchestrator module.
+
+
+def create_project(
+    name: str,
+    description: str | None,
+    folder_path: str,
+) -> int:
+    """Create a project row. Returns the new id."""
+    folder_path = str(Path(folder_path).resolve())
+    with session_scope() as sess:
+        proj = ForgeProject(
+            name=name,
+            description=description,
+            folder_path=folder_path,
+            status="active",
+        )
+        sess.add(proj)
+        sess.flush()
+        return proj.id
+
+
+def list_projects() -> list[dict[str, Any]]:
+    """Return a list of project rows as plain dicts (for JSON / CLI)."""
+    with session_scope() as sess:
+        rows = sess.query(ForgeProject).order_by(ForgeProject.id).all()
+        return [_project_row_to_dict(r) for r in rows]
+
+
+def get_project(project_id: int) -> dict[str, Any] | None:
+    with session_scope() as sess:
+        row = sess.get(ForgeProject, project_id)
+        return _project_row_to_dict(row) if row else None
+
+
+def create_feature(
+    project_id: int,
+    title: str,
+    description: str | None = None,
+    acceptance_criteria: str | None = None,
+    priority: int = 0,
+    category: str = "functional",
+    verify_command: str | None = None,
+) -> int:
+    """Insert a feature in the backlog. Returns the new id."""
+    if category not in FEATURE_CATEGORIES:
+        raise ValueError(f"invalid category {category!r}")
+    with session_scope() as sess:
+        feat = ForgeFeature(
+            project_id=project_id,
+            title=title,
+            description=description,
+            acceptance_criteria=acceptance_criteria,
+            status="backlog",
+            priority=priority,
+            category=category,
+            verify_command=verify_command,
+        )
+        sess.add(feat)
+        sess.flush()
+        return feat.id
+
+
+def add_dependency(feature_id: int, depends_on_feature_id: int) -> None:
+    """Wire feature_id → depends_on_feature_id. No-op if the edge
+    already exists (UNIQUE constraint catches the duplicate). Raises
+    ValueError if the new edge would create a cycle."""
+    if feature_id == depends_on_feature_id:
+        raise ValueError("a feature cannot depend on itself")
+    if _would_form_cycle(feature_id, depends_on_feature_id):
+        raise ValueError(
+            f"adding {feature_id} → {depends_on_feature_id} would create a cycle"
+        )
+    with session_scope() as sess:
+        existing = (
+            sess.query(ForgeFeatureDep)
+            .filter_by(feature_id=feature_id, depends_on_feature_id=depends_on_feature_id)
+            .first()
+        )
+        if existing:
+            return
+        sess.add(
+            ForgeFeatureDep(
+                feature_id=feature_id,
+                depends_on_feature_id=depends_on_feature_id,
+            )
+        )
+
+
+def list_features(project_id: int) -> list[dict[str, Any]]:
+    """All features for a project, ordered by (priority asc, id asc).
+    Each row carries a `depends_on` list of feature ids."""
+    with session_scope() as sess:
+        rows = (
+            sess.query(ForgeFeature)
+            .filter_by(project_id=project_id)
+            .order_by(ForgeFeature.priority.asc(), ForgeFeature.id.asc())
+            .all()
+        )
+        out = []
+        for r in rows:
+            deps = [d.depends_on_feature_id for d in r.outgoing_deps]
+            out.append(_feature_row_to_dict(r, deps))
+        return out
+
+
+def get_feature(feature_id: int) -> dict[str, Any] | None:
+    with session_scope() as sess:
+        row = sess.get(ForgeFeature, feature_id)
+        if row is None:
+            return None
+        deps = [d.depends_on_feature_id for d in row.outgoing_deps]
+        return _feature_row_to_dict(row, deps)
+
+
+def update_feature(feature_id: int, **fields: Any) -> dict[str, Any] | None:
+    """Patch arbitrary feature columns. Validates status / category.
+
+    Side effect: if this update flipped a feature to ``completed`` and
+    every other feature for the project is already done, the project
+    is auto-promoted to ``completed`` so the celebration overlay can
+    fire. Mirrors LocalForge's ``markProjectCompletedIfAllDone``."""
+    if "status" in fields and fields["status"] not in FEATURE_STATUSES:
+        raise ValueError(f"invalid status {fields['status']!r}")
+    if "category" in fields and fields["category"] not in FEATURE_CATEGORIES:
+        raise ValueError(f"invalid category {fields['category']!r}")
+    project_id_for_promote: int | None = None
+    with session_scope() as sess:
+        row = sess.get(ForgeFeature, feature_id)
+        if row is None:
+            return None
+        for k, v in fields.items():
+            if v is None and k in ("title",):
+                continue  # don't blank required fields
+            setattr(row, k, v)
+        sess.flush()
+        deps = [d.depends_on_feature_id for d in row.outgoing_deps]
+        result = _feature_row_to_dict(row, deps)
+        # Capture project_id while still in session; promotion runs outside.
+        if fields.get("status") == "completed":
+            project_id_for_promote = row.project_id
+    if project_id_for_promote is not None:
+        mark_project_completed_if_all_done(project_id_for_promote)
+    return result
+
+
+def delete_feature(feature_id: int) -> bool:
+    with session_scope() as sess:
+        row = sess.get(ForgeFeature, feature_id)
+        if row is None:
+            return False
+        pid = row.project_id
+        sess.delete(row)
+    # If the deletion left the project with all-done features, promote.
+    mark_project_completed_if_all_done(pid)
+    return True
+
+
+def mark_project_completed_if_all_done(project_id: int) -> bool:
+    """Promote project.status → 'completed' iff it has ≥ 1 feature and
+    every feature is 'completed'. Returns True if a promotion happened.
+    Idempotent — a no-op if the status is already 'completed' or there
+    are still incomplete features."""
+    with session_scope() as sess:
+        proj = sess.get(ForgeProject, project_id)
+        if proj is None or proj.status == "completed":
+            return False
+        feats = (
+            sess.query(ForgeFeature)
+            .filter_by(project_id=project_id)
+            .all()
+        )
+        if not feats:
+            return False
+        if any(f.status != "completed" for f in feats):
+            return False
+        proj.status = "completed"
+        return True
+
+
+def remove_dependency(feature_id: int, depends_on_feature_id: int) -> bool:
+    with session_scope() as sess:
+        row = (
+            sess.query(ForgeFeatureDep)
+            .filter_by(
+                feature_id=feature_id,
+                depends_on_feature_id=depends_on_feature_id,
+            )
+            .first()
+        )
+        if row is None:
+            return False
+        sess.delete(row)
+        return True
+
+
+def set_dependencies(
+    feature_id: int, depends_on: list[int],
+) -> list[dict[str, Any]]:
+    """Bulk-replace deps for a feature; returns the prerequisite features.
+    Rejects the entire request if any single edge would form a cycle —
+    we check edge-by-edge against the in-progress state so partial
+    application can't leave the graph cyclic on rollback."""
+    with session_scope() as sess:
+        if sess.get(ForgeFeature, feature_id) is None:
+            raise ValueError(f"feature {feature_id} not found")
+        # Drop existing deps
+        sess.query(ForgeFeatureDep).filter_by(feature_id=feature_id).delete()
+        sess.flush()
+        out: list[dict[str, Any]] = []
+        added: list[int] = []
+        for did in depends_on:
+            if did == feature_id:
+                continue
+            prereq = sess.get(ForgeFeature, did)
+            if prereq is None:
+                raise ValueError(f"prerequisite feature {did} not found")
+            if _would_form_cycle(feature_id, did):
+                raise ValueError(
+                    f"adding {feature_id} → {did} would create a cycle "
+                    f"(already added: {added})"
+                )
+            sess.add(
+                ForgeFeatureDep(
+                    feature_id=feature_id, depends_on_feature_id=did,
+                )
+            )
+            sess.flush()  # so _would_form_cycle sees this edge for subsequent loops
+            added.append(did)
+            out.append({"id": prereq.id, "title": prereq.title})
+    return out
+
+
+def _would_form_cycle(
+    feature_id: int, depends_on_feature_id: int,
+) -> bool:
+    """True iff adding feature_id → depends_on_feature_id creates a cycle.
+    A cycle exists if depends_on_feature_id can already reach feature_id
+    via the existing dep graph."""
+    if feature_id == depends_on_feature_id:
+        return True
+    with session_scope() as sess:
+        # BFS from depends_on_feature_id following outgoing_deps; if we
+        # ever reach feature_id, the new edge would close a cycle.
+        seen = set()
+        frontier = [depends_on_feature_id]
+        while frontier:
+            cur = frontier.pop()
+            if cur in seen:
+                continue
+            seen.add(cur)
+            if cur == feature_id:
+                return True
+            edges = (
+                sess.query(ForgeFeatureDep.depends_on_feature_id)
+                .filter_by(feature_id=cur)
+                .all()
+            )
+            frontier.extend(e[0] for e in edges)
+    return False
+
+
+# ────────────────────────── Row → dict marshallers ──────────────────────
+
+
+def _project_row_to_dict(row: ForgeProject | None) -> dict[str, Any]:
+    if row is None:
+        return {}
+    return {
+        "id": row.id,
+        "name": row.name,
+        "description": row.description,
+        "folder_path": row.folder_path,
+        "status": row.status,
+        "created_at": row.created_at.isoformat() if row.created_at else None,
+        "updated_at": row.updated_at.isoformat() if row.updated_at else None,
+    }
+
+
+def _feature_row_to_dict(
+    row: ForgeFeature, deps: list[int] | None = None
+) -> dict[str, Any]:
+    return {
+        "id": row.id,
+        "project_id": row.project_id,
+        "title": row.title,
+        "description": row.description,
+        "acceptance_criteria": row.acceptance_criteria,
+        "status": row.status,
+        "priority": row.priority,
+        "category": row.category,
+        "verify_command": row.verify_command,
+        "depends_on": deps or [],
+        "created_at": row.created_at.isoformat() if row.created_at else None,
+        "updated_at": row.updated_at.isoformat() if row.updated_at else None,
+    }
+
+
+__all__ = [
+    "Base",
+    "ForgeProject",
+    "ForgeFeature",
+    "ForgeFeatureDep",
+    "ForgeSession",
+    "ForgeLog",
+    "ForgeChatMessage",
+    "ForgeSetting",
+    "PROJECT_STATUSES",
+    "FEATURE_STATUSES",
+    "FEATURE_CATEGORIES",
+    "SESSION_TYPES",
+    "SESSION_STATUSES",
+    "MESSAGE_TYPES",
+    "CHAT_ROLES",
+    "get_engine",
+    "session_scope",
+    "init",
+    "create_project",
+    "list_projects",
+    "get_project",
+    "create_feature",
+    "add_dependency",
+    "list_features",
+    "get_feature",
+    "update_feature",
+    "delete_feature",
+    "remove_dependency",
+    "set_dependencies",
+]