@alexey_platkovsky/taskpilot 0.1.0-beta.1

package/src/taskpilot/server/routes/projects.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Request
+
+from taskpilot.services.registry import RegistryEntry, list_projects as registry_list
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.server.schemas import (
+    ItemDetail,
+    ItemSummary,
+    ItemUpdateInput,
+    ProjectSummary,
+    ValidationFindingOut,
+    ValidationReportOut,
+)
+from taskpilot.core.validation import validate_workspace
+from taskpilot.services import comment_service as comment_svc
+from taskpilot.services import item_service as item_svc
+from taskpilot.services.errors import ValidationFailed
+
+router = APIRouter(tags=["projects"])
+
+
+def _registry_entry(request: Request, project_id: str) -> RegistryEntry:
+    registry_dir: str = request.app.state.registry_dir
+    for entry in registry_list(Path(registry_dir)):
+        if entry.id == project_id:
+            return entry
+    raise HTTPException(status_code=404, detail=f"Project not found: {project_id}")
+
+
+def _paths(entry: RegistryEntry) -> WorkspacePaths:
+    return WorkspacePaths.for_root(Path(entry.path))
+
+
+def _require_item_in_project(entry: RegistryEntry, item_id: str) -> None:
+    """Reject item ids that do not belong to the path project's key (404).
+
+    Item ids are project-key prefixed (e.g. ``VP-1``). Scoping the lookup to the
+    path ``project_id`` keeps the route honest if a workspace ever holds items
+    from more than one project key.
+    """
+    if not item_id.startswith(f"{entry.key}-"):
+        raise HTTPException(
+            status_code=404, detail=f"No item found with id {item_id!r}"
+        )
+
+
+def _item_summary(item) -> dict:
+    d = item.model_dump()
+    d["valid"] = True
+    return d
+
+
+def _item_detail(item, ws: WorkspacePaths) -> dict:
+    d = item.model_dump()
+    try:
+        comments = comment_svc.list_comments(ws, item.id)
+        d["comments"] = [c.model_dump() for c in comments]
+    except ValidationFailed:
+        d["comments"] = []
+    d["valid"] = True
+    return d
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@router.get("/projects", response_model=list[ProjectSummary])
+def list_all_projects(request: Request) -> list[ProjectSummary]:
+    registry_dir: str = request.app.state.registry_dir
+    entries = registry_list(Path(registry_dir))
+    return [
+        ProjectSummary(
+            id=e.id,
+            key=e.key,
+            name=e.name,
+            active=e.active,
+        )
+        for e in entries
+    ]
+
+
+@router.get(
+    "/projects/{project_id}/items",
+    response_model=list[ItemSummary],
+)
+def list_project_items(request: Request, project_id: str) -> list[ItemSummary]:
+    entry = _registry_entry(request, project_id)
+    ws = _paths(entry)
+    items = item_svc.list_items(ws, project=entry.key, include_deleted=False)
+    valid_summaries: list[ItemSummary] = [
+        ItemSummary(**_item_summary(i)) for i in items
+    ]
+
+    invalid_stubs = item_svc.list_invalid_item_stubs(ws, project=entry.key)
+    invalid_summaries: list[ItemSummary] = [
+        ItemSummary(
+            id=item_id,
+            title=f"[unparseable: {item_id}.yaml]",
+            type="unknown",
+            status="unknown",
+            priority="unknown",
+            valid=False,
+            findings=[
+                ValidationFindingOut(
+                    severity="error",
+                    code="parse_error",
+                    path=rel_path,
+                    message=error_msg,
+                )
+            ],
+        )
+        for item_id, rel_path, error_msg in invalid_stubs
+    ]
+
+    return valid_summaries + invalid_summaries
+
+
+@router.get(
+    "/projects/{project_id}/validate",
+    response_model=ValidationReportOut,
+)
+def validate_project(request: Request, project_id: str) -> ValidationReportOut:
+    entry = _registry_entry(request, project_id)
+    ws = _paths(entry)
+    return ValidationReportOut(**validate_workspace(ws).to_dict())
+
+
+@router.get(
+    "/projects/{project_id}/items/{item_id}",
+    response_model=ItemDetail,
+)
+def get_item_detail(request: Request, project_id: str, item_id: str) -> ItemDetail:
+    entry = _registry_entry(request, project_id)
+    _require_item_in_project(entry, item_id)
+    ws = _paths(entry)
+    item = item_svc.read_item(ws, item_id)
+    return ItemDetail(**_item_detail(item, ws))
+
+
+@router.patch(
+    "/projects/{project_id}/items/{item_id}",
+    response_model=ItemDetail,
+)
+def patch_item(
+    request: Request,
+    project_id: str,
+    item_id: str,
+    body: ItemUpdateInput,
+) -> ItemDetail:
+    entry = _registry_entry(request, project_id)
+    _require_item_in_project(entry, item_id)
+    ws = _paths(entry)
+    fields = body.model_dump(exclude_unset=True)
+    item = item_svc.update_item(ws, item_id, **fields)
+    return ItemDetail(**_item_detail(item, ws))

package/src/taskpilot/server/schemas.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+from taskpilot.core.models import Item
+
+
+class ProjectSummary(BaseModel):
+    id: str
+    key: str
+    name: str
+    active: bool
+
+
+class CommentOut(BaseModel):
+    schema_version: int
+    created_at: str
+    created_by: str | None = None
+    body: str
+
+
+class ValidationFindingOut(BaseModel):
+    severity: str
+    code: str
+    path: str
+    field: str | None = None
+    item_id: str | None = None
+    message: str
+
+
+class ValidationSummaryOut(BaseModel):
+    errors: int
+    warnings: int
+
+
+class ValidationReportOut(BaseModel):
+    ok: bool
+    summary: ValidationSummaryOut
+    findings: list[ValidationFindingOut]
+
+
+class ItemSummary(BaseModel):
+    id: str
+    title: str
+    type: str
+    status: str
+    priority: str
+    created_at: str | None = None
+    updated_at: str | None = None
+    parent_id: str | None = None
+    valid: bool = True
+    findings: list[ValidationFindingOut] = []
+
+
+class ItemDetail(Item):
+    """Full item representation returned by detail and patch endpoints.
+
+    Extends the domain Item with API-only fields: comments (populated from the
+    comment service) and validity metadata (valid flag + findings).  The config
+    override drops extra=allow so unknown YAML fields never leak into responses.
+    """
+
+    model_config = ConfigDict(
+        extra="ignore", use_enum_values=True, validate_default=True
+    )
+
+    comments: list[CommentOut] = []
+    valid: bool = True
+    findings: list[ValidationFindingOut] = []
+
+
+class ItemUpdateInput(BaseModel):
+    title: str | None = None
+    description: str | None = None
+    priority: str | None = None
+    status: str | None = None

package/src/taskpilot/services/__init__.py

@@ -0,0 +1,8 @@
+"""TaskPilot domain/service layer (feature F002).
+
+Stateless business-rule operations for projects, items, comments, and links.
+This is the single source of business rules shared by the CLI, REST API, and
+future MCP adapters. Services orchestrate the F001 storage primitives in
+``taskpilot.core`` and own domain rules (hierarchy, links, soft delete,
+pre-write validation); they never import adapter or framework code.
+"""

package/src/taskpilot/services/comment_service.py

@@ -0,0 +1,62 @@
+"""Comment domain service: add, list (task F002-T6, requirement F002-R6).
+
+Comments are append-only Markdown files under ``comments/<item_id>/``; the
+filename timestamp is the comment identity. Adding a comment never touches the
+item YAML. This service wraps the F001 comment primitives with domain rules:
+the target item must exist, and low-level parse/validation failures surface as
+:class:`ValidationFailed`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from taskpilot.core import comments as core_comments
+from taskpilot.core.comments import Comment, CommentParseError
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.timestamps import utc_now_iso
+from taskpilot.services.errors import NotFound, ValidationFailed
+
+__all__ = ["add_comment", "list_comments"]
+
+
+def add_comment(
+    paths: WorkspacePaths,
+    item_id: str,
+    *,
+    body: str,
+    created_by: str,
+    now: str | None = None,
+) -> Path:
+    """Add a comment to ``item_id`` and return the written file path (F002-R6).
+
+    A comment's identity *is* its filename (spec ``0002``), so the path — not the
+    in-memory model — is the useful result for callers such as the CLI, matching
+    the core ``write_comment`` contract. The owning item must exist; a timestamped
+    ``.md`` file is written (same-second collisions get ``-N`` suffixes) and the
+    item YAML is left untouched. Raises :class:`NotFound` for an unknown item and
+    :class:`ValidationFailed` for invalid comment fields (e.g. empty author).
+    """
+    if not paths.item_file(item_id).is_file():
+        raise NotFound(f"No item found with id {item_id!r}")
+    try:
+        comment = Comment(
+            created_at=now or utc_now_iso(), created_by=created_by, body=body
+        )
+    except ValidationError as exc:
+        raise ValidationFailed(f"Cannot add comment to {item_id!r}: {exc}") from exc
+    return core_comments.write_comment(paths, item_id, comment)
+
+
+def list_comments(paths: WorkspacePaths, item_id: str) -> list[Comment]:
+    """List ``item_id``'s comments ordered chronologically (F002-R6).
+
+    Returns an empty list when the item has no comments. Raises
+    :class:`ValidationFailed` if a stored comment file is malformed.
+    """
+    try:
+        return core_comments.list_comments(paths, item_id)
+    except (CommentParseError, ValidationError) as exc:
+        raise ValidationFailed(f"Invalid comment for {item_id!r}: {exc}") from exc

package/src/taskpilot/services/errors.py

@@ -0,0 +1,26 @@
+"""Domain-service error types (feature F002).
+
+Services raise these instead of leaking pydantic ``ValidationError``, ``OSError``,
+or other low-level exceptions to adapters. Each error carries a human-readable
+message so CLI/API adapters can render a descriptive response (F002-R8).
+"""
+
+from __future__ import annotations
+
+__all__ = ["ServiceError", "ValidationFailed", "NotFound", "ConflictError"]
+
+
+class ServiceError(Exception):
+    """Base class for all domain-service errors."""
+
+
+class ValidationFailed(ServiceError):
+    """Operation input failed validation before any file was written (F002-R8)."""
+
+
+class NotFound(ServiceError):
+    """A requested project or item does not exist."""
+
+
+class ConflictError(ServiceError):
+    """The operation conflicts with existing canonical state (e.g. create over an existing project)."""

package/src/taskpilot/services/hierarchy.py

@@ -0,0 +1,107 @@
+"""Type-based parent/child hierarchy rules (task F002-T3, requirement F002-R3).
+
+Enforced whenever an item's ``parent_id`` is set (on create or update). Allowed
+parent -> child types (see ``docs/architecture.md`` "Hierarchy"):
+
+    epic    -> feature, task
+    feature -> task
+    task    -> bug
+    bug     -> (none)
+
+Also rejects an item parenting itself and any change that would close a cycle.
+The strictly-decreasing type table already makes cycles impossible for valid
+types; the self/cycle guards are explicit so intent survives future table
+changes and so error messages are precise.
+"""
+
+from __future__ import annotations
+
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.services.errors import NotFound, ValidationFailed
+
+__all__ = ["ALLOWED_CHILD_TYPES", "validate_parent", "validate_can_parent_children"]
+
+#: Allowed child types keyed by parent type.
+ALLOWED_CHILD_TYPES: dict[str, set[str]] = {
+    "epic": {"feature", "task"},
+    "feature": {"task"},
+    "task": {"bug"},
+    "bug": set(),
+}
+
+
+def validate_parent(
+    paths: WorkspacePaths,
+    *,
+    child_id: str,
+    child_type: str,
+    parent_id: str | None,
+) -> None:
+    """Validate that ``child`` may have ``parent_id`` as its parent.
+
+    No-op when ``parent_id`` is ``None``. Raises :class:`ValidationFailed` when the
+    parent is the child itself, does not exist, is a type that cannot parent
+    ``child_type``, or when the assignment would close an ancestor cycle.
+    """
+    from taskpilot.services.item_service import read_item  # local import avoids a cycle
+
+    if parent_id is None:
+        return
+    if parent_id == child_id:
+        raise ValidationFailed(f"Item {child_id!r} cannot be its own parent")
+
+    try:
+        parent = read_item(paths, parent_id)
+    except NotFound as exc:
+        raise ValidationFailed(
+            f"parent_id references unknown item {parent_id!r}"
+        ) from exc
+
+    allowed = ALLOWED_CHILD_TYPES.get(parent.type, set())
+    if child_type not in allowed:
+        raise ValidationFailed(
+            f"A {parent.type} cannot be the parent of a {child_type} "
+            f"(allowed children of {parent.type}: {sorted(allowed) or 'none'})"
+        )
+
+    # Walk the parent's ancestors; reaching child_id means this closes a cycle.
+    seen: set[str] = set()
+    cursor = parent
+    while cursor.parent_id:
+        if cursor.parent_id == child_id:
+            raise ValidationFailed(
+                f"Setting parent of {child_id!r} to {parent_id!r} would create a cycle"
+            )
+        if cursor.parent_id in seen:
+            break  # pre-existing cycle elsewhere; stop rather than loop forever
+        seen.add(cursor.parent_id)
+        try:
+            cursor = read_item(paths, cursor.parent_id)
+        except (NotFound, ValidationFailed):
+            break
+
+
+def validate_can_parent_children(
+    paths: WorkspacePaths,
+    *,
+    parent_id: str,
+    parent_type: str,
+) -> None:
+    """Ensure ``parent_type`` may still parent every item currently pointing at it.
+
+    Called when an item's ``type`` changes: a parent must not be retyped into a
+    type that cannot legally parent its existing children (which would persist an
+    item-graph the hierarchy table forbids). Raises :class:`ValidationFailed`
+    naming the first offending child.
+    """
+    from taskpilot.services.item_service import (
+        list_items,
+    )  # local import avoids a cycle
+
+    allowed = ALLOWED_CHILD_TYPES.get(parent_type, set())
+    for child in list_items(paths, include_deleted=True):
+        if child.parent_id == parent_id and child.type not in allowed:
+            raise ValidationFailed(
+                f"Cannot change {parent_id!r} to type {parent_type!r}: it parents "
+                f"{child.id!r} (a {child.type}), which a {parent_type} cannot parent"
+            )