@alexey_platkovsky/taskpilot 0.1.0-beta.1

package/src/taskpilot/core/validation.py

@@ -0,0 +1,385 @@
+"""Item validation producing non-crashing findings (task F001-T7, F001-R6).
+
+Validation never blocks loading: every problem becomes a :class:`Finding` with a
+severity, stable code, file path, and message. Errors flip ``ok`` to ``False``
+(and make ``taskpilot validate`` exit non-zero); warnings do not.
+
+Covered rules (see ``docs/specs/0002`` "Validation"):
+
+- unparseable YAML / non-mapping documents (error);
+- required fields and valid enums/timestamps via the :class:`Item` model (error);
+- ``id`` must match the filename stem (error);
+- duplicate ``id`` across files (error on every offending file);
+- ``parent_id`` and link targets must reference existing items (missing -> error;
+  target is ``deleted`` -> warning);
+- attachment paths must be relative and inside the repo (absolute/escape -> error;
+  missing file -> warning).
+
+Hierarchy *type* rules (epic/feature/task/bug parent-child) are F002-T3.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from enum import Enum
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ValidationError
+
+from taskpilot.core.comments import (
+    CommentParseError,
+    comment_filename_timestamp,
+    parse_comment_text,
+)
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.models import Item
+from taskpilot.core.yaml_io import load_yaml
+
+__all__ = ["Severity", "Finding", "ValidationReport", "validate_workspace"]
+
+
+class Severity(str, Enum):
+    error = "error"
+    warning = "warning"
+
+
+class Finding(BaseModel):
+    """A single validation result. ``field``/``item_id`` are null when not applicable."""
+
+    severity: Severity
+    code: str
+    path: str
+    field: str | None = None
+    item_id: str | None = None
+    message: str
+
+    def to_dict(self) -> dict:
+        return {
+            "severity": self.severity.value,
+            "code": self.code,
+            "path": self.path,
+            "field": self.field,
+            "item_id": self.item_id,
+            "message": self.message,
+        }
+
+
+class ValidationReport(BaseModel):
+    """Aggregated findings. ``ok`` is True when there are no error-severity findings."""
+
+    findings: list[Finding]
+
+    @property
+    def ok(self) -> bool:
+        return not any(f.severity == Severity.error for f in self.findings)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.error)
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == Severity.warning)
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "summary": {"errors": self.error_count, "warnings": self.warning_count},
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+
+def _finding_from_pydantic(err: dict, *, path: str, item_id: str | None) -> Finding:
+    field = ".".join(str(p) for p in err["loc"])
+    etype = err["type"]
+    if etype == "missing":
+        return Finding(
+            severity=Severity.error,
+            code="missing_required_field",
+            path=path,
+            field=field,
+            item_id=item_id,
+            message=f"Missing required field: {field}",
+        )
+    if etype == "enum":
+        expected = err.get("ctx", {}).get("expected", "")
+        return Finding(
+            severity=Severity.error,
+            code="invalid_enum",
+            path=path,
+            field=field,
+            item_id=item_id,
+            message=f"Invalid value for {field}: expected one of {expected}",
+        )
+    return Finding(
+        severity=Severity.error,
+        code="invalid_field",
+        path=path,
+        field=field,
+        item_id=item_id,
+        message=f"{field}: {err['msg']}",
+    )
+
+
+def _validate_attachment(
+    value: str, *, paths: WorkspacePaths, path: str, item_id: str
+) -> Finding | None:
+    if not value.strip():
+        return Finding(
+            severity=Severity.error,
+            code="attachment_empty",
+            path=path,
+            field="attachments",
+            item_id=item_id,
+            message="Attachment path is empty",
+        )
+    if Path(value).is_absolute():
+        return Finding(
+            severity=Severity.error,
+            code="attachment_not_relative",
+            path=path,
+            field="attachments",
+            item_id=item_id,
+            message=f"Attachment path must be relative: {value}",
+        )
+    resolved = (paths.root / value).resolve()
+    if not resolved.is_relative_to(paths.root):
+        return Finding(
+            severity=Severity.error,
+            code="attachment_outside_repo",
+            path=path,
+            field="attachments",
+            item_id=item_id,
+            message=f"Attachment path escapes the repository: {value}",
+        )
+    if not resolved.exists():
+        return Finding(
+            severity=Severity.warning,
+            code="missing_attachment",
+            path=path,
+            field="attachments",
+            item_id=item_id,
+            message=f"Attachment file not found: {value}",
+        )
+    return None
+
+
+def _validate_comments(paths: WorkspacePaths) -> list[Finding]:
+    """Validate ``comments/<ITEM_ID>/*.md`` files without crashing the run.
+
+    Reports unreadable/malformed comment files as errors and a filename whose
+    timestamp does not match the frontmatter ``created_at`` as a warning. The
+    owning item id is the comment folder name.
+    """
+    findings: list[Finding] = []
+    if not paths.comments_dir.is_dir():
+        return findings
+
+    for item_dir in sorted(p for p in paths.comments_dir.iterdir() if p.is_dir()):
+        item_id = item_dir.name
+        for file in sorted(f for f in item_dir.glob("*.md") if f.is_file()):
+            rel = paths.relative_posix(file)
+            try:
+                text = file.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, OSError) as exc:
+                findings.append(
+                    Finding(
+                        severity=Severity.error,
+                        code="comment_unreadable",
+                        path=rel,
+                        item_id=item_id,
+                        message=f"Cannot read comment file as UTF-8: {exc}",
+                    )
+                )
+                continue
+
+            try:
+                comment = parse_comment_text(text)
+            except CommentParseError as exc:
+                findings.append(
+                    Finding(
+                        severity=Severity.error,
+                        code="invalid_comment",
+                        path=rel,
+                        item_id=item_id,
+                        message=str(exc),
+                    )
+                )
+                continue
+            except ValidationError as exc:
+                for err in exc.errors():
+                    findings.append(
+                        _finding_from_pydantic(err, path=rel, item_id=item_id)
+                    )
+                continue
+
+            expected = comment_filename_timestamp(file.name)
+            if expected is None:
+                findings.append(
+                    Finding(
+                        severity=Severity.warning,
+                        code="comment_filename_not_timestamp",
+                        path=rel,
+                        item_id=item_id,
+                        message=f"Comment filename does not encode a timestamp: {file.name}",
+                    )
+                )
+            elif expected != comment.created_at:
+                findings.append(
+                    Finding(
+                        severity=Severity.warning,
+                        code="comment_timestamp_mismatch",
+                        path=rel,
+                        field="created_at",
+                        item_id=item_id,
+                        message=f"created_at {comment.created_at!r} does not match filename timestamp {expected!r}",
+                    )
+                )
+    return findings
+
+
+def validate_workspace(paths: WorkspacePaths) -> ValidationReport:
+    """Validate every ``items/*.yaml`` and ``comments/**/*.md`` file in the workspace."""
+    findings: list[Finding] = []
+    valid_items: list[tuple[Item, str]] = []
+    status_by_id: dict[str, str] = {}
+    paths_by_id: dict[str, list[str]] = defaultdict(list)
+
+    if paths.items_dir.is_dir():
+        item_files = sorted(p for p in paths.items_dir.glob("*.yaml") if p.is_file())
+    else:
+        item_files = []
+
+    for file in item_files:
+        rel = paths.relative_posix(file)
+        filename_id = file.stem
+        try:
+            text = file.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError) as exc:
+            findings.append(
+                Finding(
+                    severity=Severity.error,
+                    code="unreadable_file",
+                    path=rel,
+                    message=f"Cannot read item file as UTF-8: {exc}",
+                )
+            )
+            continue
+
+        try:
+            data = load_yaml(text)
+        except yaml.YAMLError as exc:
+            findings.append(
+                Finding(
+                    severity=Severity.error,
+                    code="invalid_yaml",
+                    path=rel,
+                    message=f"Invalid YAML: {exc}",
+                )
+            )
+            continue
+        if not isinstance(data, dict):
+            findings.append(
+                Finding(
+                    severity=Severity.error,
+                    code="invalid_yaml",
+                    path=rel,
+                    message="Item file is not a YAML mapping",
+                )
+            )
+            continue
+
+        recoverable_id = data["id"] if isinstance(data.get("id"), str) else None
+
+        try:
+            item = Item.model_validate(data)
+        except ValidationError as exc:
+            for err in exc.errors():
+                findings.append(
+                    _finding_from_pydantic(err, path=rel, item_id=recoverable_id)
+                )
+            if recoverable_id is not None:
+                paths_by_id[recoverable_id].append(rel)
+            continue
+
+        if item.id != filename_id:
+            findings.append(
+                Finding(
+                    severity=Severity.error,
+                    code="id_filename_mismatch",
+                    path=rel,
+                    field="id",
+                    item_id=item.id,
+                    message=f"Item id {item.id!r} does not match filename {file.name!r}",
+                )
+            )
+        paths_by_id[item.id].append(rel)
+        status_by_id[item.id] = item.status
+        valid_items.append((item, rel))
+
+    # Duplicate IDs: flag every offending file.
+    for item_id, rels in paths_by_id.items():
+        if len(rels) > 1:
+            for rel in rels:
+                findings.append(
+                    Finding(
+                        severity=Severity.error,
+                        code="duplicate_id",
+                        path=rel,
+                        item_id=item_id,
+                        message=f"Duplicate item id {item_id!r} (also in {len(rels) - 1} other file(s))",
+                    )
+                )
+
+    known_ids = set(paths_by_id)
+
+    def _check_reference(target: str, *, rel: str, source_id: str, field: str) -> None:
+        if target not in known_ids:
+            findings.append(
+                Finding(
+                    severity=Severity.error,
+                    code="missing_reference",
+                    path=rel,
+                    field=field,
+                    item_id=source_id,
+                    message=f"{field} references unknown item: {target}",
+                )
+            )
+        elif status_by_id.get(target) == "deleted":
+            findings.append(
+                Finding(
+                    severity=Severity.warning,
+                    code="link_to_deleted",
+                    path=rel,
+                    field=field,
+                    item_id=source_id,
+                    message=f"{field} references deleted item: {target}",
+                )
+            )
+
+    for item, rel in valid_items:
+        if item.parent_id:
+            _check_reference(
+                item.parent_id, rel=rel, source_id=item.id, field="parent_id"
+            )
+        if item.links:
+            for target in item.links.blocks:
+                _check_reference(
+                    target, rel=rel, source_id=item.id, field="links.blocks"
+                )
+            for target in item.links.relates_to:
+                _check_reference(
+                    target, rel=rel, source_id=item.id, field="links.relates_to"
+                )
+        for attachment in item.attachments or []:
+            finding = _validate_attachment(
+                attachment, paths=paths, path=rel, item_id=item.id
+            )
+            if finding is not None:
+                findings.append(finding)
+
+    findings.extend(_validate_comments(paths))
+
+    findings.sort(key=lambda f: (f.path, f.code, f.field or "", f.message))
+    return ValidationReport(findings=findings)

package/src/taskpilot/core/yaml_io.py

@@ -0,0 +1,57 @@
+"""Deterministic YAML serialization for canonical TaskPilot files.
+
+TaskPilot owns canonical YAML formatting (see ``docs/specs/0002``). Canonical
+files are written with a single, stable style so that re-serializing parsed data
+is reproducible and Git-friendly. This module centralizes that style; project
+and item writers must serialize through :func:`dump_yaml`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+__all__ = ["dump_yaml", "load_yaml"]
+
+
+class _CanonicalLoader(yaml.SafeLoader):
+    """SafeLoader that does not auto-convert ISO timestamps to ``datetime``.
+
+    TaskPilot owns canonical timestamp formatting and stores timestamps as
+    strings, so implicit timestamp resolution would corrupt round-trip fidelity.
+    """
+
+
+_CanonicalLoader.yaml_implicit_resolvers = {
+    first_char: [
+        (tag, regexp)
+        for tag, regexp in resolvers
+        if tag != "tag:yaml.org,2002:timestamp"
+    ]
+    for first_char, resolvers in yaml.SafeLoader.yaml_implicit_resolvers.items()
+}
+
+
+def dump_yaml(data: Any) -> str:
+    """Serialize ``data`` to canonical YAML text.
+
+    Key order is preserved (not sorted) so callers control field order; output
+    uses block style and allows unicode. The result ends with a single trailing
+    newline.
+    """
+    return yaml.safe_dump(
+        data,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+        width=4096,
+    )
+
+
+def load_yaml(text: str) -> Any:
+    """Parse YAML ``text`` into Python data using the canonical safe loader.
+
+    ISO timestamps are kept as strings (see :class:`_CanonicalLoader`).
+    """
+    return yaml.load(text, Loader=_CanonicalLoader)

package/src/taskpilot/server/app.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from taskpilot.server.routes import projects
+from taskpilot.services.errors import NotFound, ValidationFailed
+
+#: Environment variable carrying the registry directory for :func:`create_app_from_env`.
+REGISTRY_DIR_ENV = "TASKPILOT_REGISTRY_DIR"
+
+#: Environment variable pointing to the staged WebUI production assets directory.
+WEB_DIST_ENV = "TASKPILOT_WEB_DIST"
+
+
+def create_app(*, registry_dir: str) -> FastAPI:
+    app = FastAPI(
+        title="TaskPilot API",
+        version="0.0.0",
+        docs_url="/docs",
+    )
+
+    app.state.registry_dir = registry_dir
+
+    app.include_router(projects.router, prefix="/api")
+
+    _mount_webui(app)
+
+    @app.exception_handler(NotFound)
+    def _not_found(request: Request, exc: NotFound) -> JSONResponse:
+        return JSONResponse(status_code=404, content={"detail": str(exc)})
+
+    @app.exception_handler(ValidationFailed)
+    def _validation_failed(request: Request, exc: ValidationFailed) -> JSONResponse:
+        return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+    return app
+
+
+def _mount_webui(app: FastAPI) -> None:
+    """Mount the WebUI static files from ``TASKPILOT_WEB_DIST`` if available.
+
+    When the directory exists and contains ``index.html`` the app serves:
+    - static assets under ``/assets/``
+    - ``index.html`` as the SPA fallback for all non-API routes
+
+    When the directory is missing or unreadable the WebUI route returns
+    a clear packaging error instead of a blank page.
+    """
+    web_dist = os.environ.get(WEB_DIST_ENV)
+    if not web_dist:
+        return
+
+    web_dist_path = Path(web_dist)
+
+    if web_dist_path.is_dir() and (web_dist_path / "index.html").is_file():
+        # Mount static assets (JS, CSS, SVGs, etc.)
+        app.mount(
+            "/assets",
+            StaticFiles(directory=str(web_dist_path / "assets")),
+            name="webui_assets",
+        )
+
+        # SPA fallback: serve index.html for all non-API routes
+        index_path = web_dist_path / "index.html"
+
+        @app.get("/{full_path:path}", include_in_schema=False)
+        async def _spa_fallback(request: Request, full_path: str) -> FileResponse:
+            return FileResponse(index_path)
+
+        @app.get("/", include_in_schema=False)
+        async def _root_fallback(request: Request) -> FileResponse:
+            return FileResponse(index_path)
+    else:
+        # WebUI assets are missing or unreadable — show a clear error
+        error_body = _PACKAGING_ERROR_HTML
+
+        @app.get("/{full_path:path}", include_in_schema=False)
+        async def _packaging_error(request: Request, full_path: str) -> HTMLResponse:
+            return HTMLResponse(content=error_body, status_code=503)
+
+        @app.get("/", include_in_schema=False)
+        async def _root_packaging_error(request: Request) -> HTMLResponse:
+            return HTMLResponse(content=error_body, status_code=503)
+
+
+_PACKAGING_ERROR_HTML = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>TaskPilot — WebUI unavailable</title>
+<style>
+  body { font-family: system-ui, sans-serif; max-width: 600px; margin: 80px auto; padding: 0 20px; color: #333; }
+  h1 { font-size: 1.4rem; }
+  code { background: #f0f0f0; padding: 2px 6px; border-radius: 4px; }
+</style>
+</head>
+<body>
+<h1>WebUI assets are not available</h1>
+<p>
+  The TaskPilot API is running, but the packaged WebUI assets could not be found.
+  This can happen when the npm package was built without WebUI assets, or
+  the <code>TASKPILOT_WEB_DIST</code> environment variable points to a missing
+  or unreadable directory.
+</p>
+<p>
+  To fix this, reinstall the TaskPilot npm package or set
+  <code>TASKPILOT_WEB_DIST</code> to a directory containing a production
+  WebUI build.
+</p>
+<p>
+  The REST API is still available at <a href="/docs">/docs</a>.
+</p>
+</body>
+</html>
+"""
+
+
+def create_app_from_env() -> FastAPI:
+    """Build the app from the ``TASKPILOT_REGISTRY_DIR`` environment variable.
+
+    Used as a uvicorn import-string factory (``taskpilot.server.app:create_app_from_env``)
+    so adapters such as the CLI ``serve`` command can launch the server without importing
+    this module directly, keeping the cli/server adapter boundary intact (TP-4).
+    """
+    registry_dir = os.environ.get(REGISTRY_DIR_ENV)
+    if not registry_dir:
+        raise RuntimeError(f"{REGISTRY_DIR_ENV} is not set; cannot build the API app")
+    return create_app(registry_dir=registry_dir)