FabledScribe/src/scribe/routes/systems.py

"""System routes nested under /api/projects/<project_id>/systems, plus the
project's open-issues list. A System is a per-project, reusable subsystem/area
that records (notes/tasks/issues) associate with."""
import logging

from quart import Blueprint, jsonify, request

from scribe.auth import login_required, get_current_user_id
from scribe.routes.utils import not_found
from scribe.services import systems as systems_svc
from scribe.services.access import can_write_project
from scribe.services.projects import get_project_for_user
from scribe.services import system_usage as system_usage_svc

logger = logging.getLogger(__name__)

systems_bp = Blueprint("systems", __name__, url_prefix="/api/projects")


def _truthy(v: str | None) -> bool:
    return (v or "").lower() in ("1", "true", "yes")


def _split_records(records: list) -> tuple[list, list, list]:
    issues, tasks, notes = [], [], []
    for r in records:
        d = r.to_dict()
        if r.status is None:
            notes.append(d)
        elif r.task_kind == "issue":
            issues.append(d)
        else:
            tasks.append(d)
    return issues, tasks, notes


@systems_bp.route("/<int:project_id>/systems", methods=["GET"])
@login_required
async def list_systems_route(project_id: int):
    uid = get_current_user_id()
    if await get_project_for_user(uid, project_id) is None:
        return not_found("Project")
    systems = await systems_svc.list_systems(
        uid, project_id, include_archived=_truthy(request.args.get("include_archived")),
    )
    counts = await systems_svc.open_issue_counts_by_system(uid, project_id)
    # How often each area's rulings reached a session (#4769) — one GROUP BY
    # for the page, and a zero shape for an area nothing has touched.
    usage = await system_usage_svc.usage_for_systems([s.id for s in systems])
    out = []
    for s in systems:
        d = s.to_dict()
        d["open_issue_count"] = counts.get(s.id, 0)
        d["usage"] = usage.get(s.id, system_usage_svc.empty_system_usage())
        out.append(d)
    return jsonify({"systems": out})


@systems_bp.route("/<int:project_id>/systems", methods=["POST"])
@login_required
async def create_system_route(project_id: int):
    uid = get_current_user_id()
    if await get_project_for_user(uid, project_id) is None:
        return not_found("Project")
    if not await can_write_project(uid, project_id):
        return jsonify({"error": "Permission denied"}), 403
    data = await request.get_json() or {}
    if not (data.get("name") or "").strip():
        return jsonify({"error": "name is required"}), 400
    # The same gate the MCP door enforces. It lived only in the tool layer
    # until now, which is exactly how the web UI shipped without gates the
    # agent surface had (#2482) — one service call, one answer (rule 33).
    assessment = await systems_svc.assess_system_name(uid, project_id, data["name"])
    duplicate = assessment["duplicate"]
    if duplicate and not data.get("force"):
        return jsonify({
            "duplicate": True,
            "existing_id": duplicate["id"],
            "error": (
                f"“{duplicate['name']}” already covers this area in this "
                "project. Tag records to it, or rename it if its charter has "
                "moved on — a second System with the same name splits the "
                "area's records across two piles."
            ),
        }), 409
    canonical = assessment["canonical"]
    # Exact is mechanical and applied; overlap is a judgment call and is only
    # offered back for the form to present.
    applied = canonical["id"] if canonical and canonical["basis"] == "exact" else None
    try:
        system = await systems_svc.create_system(
            uid, project_id=project_id, name=data["name"],
            description=data.get("description"), color=data.get("color"),
            order_index=data.get("order_index", 0),
            canonical_id=data.get("canonical_id") or applied,
            path_patterns=data.get("path_patterns"),
        )
    except ValueError as e:
        return jsonify({"error": str(e)}), 400
    if system is None:
        return jsonify({"error": "Permission denied"}), 403
    out = system.to_dict()
    if canonical and canonical["basis"] == "overlap" and not system.canonical_id:
        out["canonical_suggestion"] = canonical
    return jsonify(out), 201


@systems_bp.route("/<int:project_id>/systems/<int:system_id>", methods=["GET"])
@login_required
async def get_system_route(project_id: int, system_id: int):
    uid = get_current_user_id()
    if await get_project_for_user(uid, project_id) is None:
        return not_found("Project")
    system = await systems_svc.get_system(uid, system_id)
    if system is None or system.project_id != project_id:
        return not_found("System")
    issues, tasks, notes = _split_records(
        await systems_svc.list_records_for_system(uid, system_id)
    )
    data = system.to_dict()
    data["issues"], data["tasks"], data["notes"] = issues, tasks, notes
    data["usage"] = (await system_usage_svc.usage_for_systems([system.id]))[system.id]
    return jsonify(data)


@systems_bp.route("/<int:project_id>/systems/<int:system_id>", methods=["PATCH"])
@login_required
async def update_system_route(project_id: int, system_id: int):
    uid = get_current_user_id()
    if await get_project_for_user(uid, project_id) is None:
        return not_found("Project")
    if not await can_write_project(uid, project_id):
        return jsonify({"error": "Permission denied"}), 403
    system = await systems_svc.get_system(uid, system_id)
    if system is None or system.project_id != project_id:
        return not_found("System")
    data = await request.get_json() or {}
    allowed = {"name", "description", "color", "status", "order_index", "path_patterns"}
    fields = {k: v for k, v in data.items() if k in allowed}
    if "status" in fields and fields["status"] not in ("active", "archived"):
        return jsonify({"error": "status must be 'active' or 'archived'"}), 400
    try:
        updated = await systems_svc.update_system(uid, system_id, **fields)
    except ValueError as e:
        return jsonify({"error": str(e)}), 400
    if updated is None:
        return not_found("System")
    return jsonify(updated.to_dict())


@systems_bp.route("/<int:project_id>/systems/<int:system_id>", methods=["DELETE"])
@login_required
async def delete_system_route(project_id: int, system_id: int):
    uid = get_current_user_id()
    if await get_project_for_user(uid, project_id) is None:
        return not_found("Project")
    if not await can_write_project(uid, project_id):
        return jsonify({"error": "Permission denied"}), 403
    system = await systems_svc.get_system(uid, system_id)
    if system is None or system.project_id != project_id:
        return not_found("System")
    await systems_svc.delete_system(uid, system_id)
    return "", 204


@systems_bp.route("/<int:project_id>/systems/<int:system_id>/records", methods=["GET"])
@login_required
async def system_records_route(project_id: int, system_id: int):
    uid = get_current_user_id()
    if await get_project_for_user(uid, project_id) is None:
        return not_found("Project")
    system = await systems_svc.get_system(uid, system_id)
    if system is None or system.project_id != project_id:
        return not_found("System")
    records = await systems_svc.list_records_for_system(
        uid, system_id,
        kind=request.args.get("kind") or None,
        open_only=_truthy(request.args.get("open_only")),
    )
    return jsonify({"records": [r.to_dict() for r in records]})


@systems_bp.route("/<int:project_id>/issues", methods=["GET"])
@login_required
async def project_issues_route(project_id: int):
    """A project's issues (open by default — pass open_only=false for all)."""
    uid = get_current_user_id()
    if await get_project_for_user(uid, project_id) is None:
        return not_found("Project")
    open_only = request.args.get("open_only", "true").lower() in ("1", "true", "yes")
    issues = await systems_svc.list_issues(uid, project_id, open_only=open_only)
    return jsonify({"issues": [n.to_dict() for n in issues]})