@alexey_platkovsky/taskpilot 0.1.0-beta.1

package/src/taskpilot/core/layout.py

@@ -0,0 +1,137 @@
+"""Workspace layout constants and path resolution for the ``.taskpilot/`` tree.
+
+This module is the storage foundation for feature F001 (task F001-T1). Every
+other storage task (parser, writer, validator, project loader) resolves
+canonical file locations through :class:`WorkspacePaths` rather than hard-coding
+path fragments.
+
+Canonical layout (see ``docs/specs/0002-alpha-product-and-stack-decisions.md``)::
+
+    repo-root/
+      .taskpilot/
+        project.yaml
+        items/
+          TP-1.yaml
+        comments/
+          TP-1/
+            2026-06-23T10-00-00Z.md
+
+This module only resolves and validates paths. It does not touch the filesystem
+except for :meth:`WorkspacePaths.exists`, and it never reads, writes, or creates
+canonical files — that belongs to later tasks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = [
+    "WORKSPACE_DIRNAME",
+    "PROJECT_FILENAME",
+    "ITEMS_DIRNAME",
+    "COMMENTS_DIRNAME",
+    "ITEM_FILE_SUFFIX",
+    "COMMENT_FILE_SUFFIX",
+    "WorkspacePaths",
+]
+
+#: Repository-local directory that holds all canonical TaskPilot data.
+WORKSPACE_DIRNAME = ".taskpilot"
+#: Canonical project identity file inside the workspace.
+PROJECT_FILENAME = "project.yaml"
+#: Directory holding one YAML file per item.
+ITEMS_DIRNAME = "items"
+#: Directory holding per-item comment folders.
+COMMENTS_DIRNAME = "comments"
+#: Suffix for canonical item files (``TP-1.yaml``).
+ITEM_FILE_SUFFIX = ".yaml"
+#: Suffix for canonical comment files (``<timestamp>.md``).
+COMMENT_FILE_SUFFIX = ".md"
+
+
+def _require_safe_segment(value: str, *, kind: str) -> str:
+    """Reject values that are empty or would escape their parent directory.
+
+    Path resolution must never let a caller-supplied identifier or filename
+    traverse outside the workspace. Item IDs and comment filenames are always
+    single path segments, so anything containing a separator or a ``..``
+    component is rejected.
+    """
+    if not value:
+        raise ValueError(f"{kind} must not be empty")
+    if "/" in value or "\\" in value:
+        raise ValueError(f"{kind} must not contain a path separator: {value!r}")
+    if value in (".", ".."):
+        raise ValueError(f"{kind} must not be a relative traversal segment: {value!r}")
+    return value
+
+
+@dataclass(frozen=True)
+class WorkspacePaths:
+    """Resolves canonical ``.taskpilot/`` paths relative to a repository root.
+
+    Construct with :meth:`for_root`. Path-returning members never touch the
+    filesystem; :meth:`exists` is the only member that reads disk state.
+    """
+
+    root: Path
+
+    @classmethod
+    def for_root(cls, root: Path | str) -> "WorkspacePaths":
+        """Build a resolver for the repository ``root`` that contains ``.taskpilot/``.
+
+        The root is normalized to an absolute path so resolved paths are stable
+        regardless of the current working directory.
+        """
+        return cls(root=Path(root).resolve())
+
+    @property
+    def workspace_dir(self) -> Path:
+        """The ``.taskpilot/`` directory."""
+        return self.root / WORKSPACE_DIRNAME
+
+    @property
+    def project_file(self) -> Path:
+        """The canonical ``project.yaml`` file."""
+        return self.workspace_dir / PROJECT_FILENAME
+
+    @property
+    def items_dir(self) -> Path:
+        """The ``items/`` directory holding one YAML file per item."""
+        return self.workspace_dir / ITEMS_DIRNAME
+
+    @property
+    def comments_dir(self) -> Path:
+        """The ``comments/`` directory holding per-item comment folders."""
+        return self.workspace_dir / COMMENTS_DIRNAME
+
+    def item_file(self, item_id: str) -> Path:
+        """Path to the canonical YAML file for ``item_id`` (e.g. ``items/TP-1.yaml``)."""
+        _require_safe_segment(item_id, kind="item id")
+        return self.items_dir / f"{item_id}{ITEM_FILE_SUFFIX}"
+
+    def item_comments_dir(self, item_id: str) -> Path:
+        """Path to the comment folder owned by ``item_id`` (e.g. ``comments/TP-1``)."""
+        _require_safe_segment(item_id, kind="item id")
+        return self.comments_dir / item_id
+
+    def comment_file(self, item_id: str, filename: str) -> Path:
+        """Path to a single comment file under ``item_id``'s comment folder."""
+        _require_safe_segment(filename, kind="comment filename")
+        return self.item_comments_dir(item_id) / filename
+
+    def relative_posix(self, path: Path) -> str:
+        """Render ``path`` relative to the root using ``/`` separators on all platforms.
+
+        Canonical references (validation findings, JSON output) use forward
+        slashes regardless of the host OS, e.g. ``.taskpilot/items/TP-1.yaml``.
+
+        Raises :class:`ValueError` when ``path`` is not located under the
+        workspace root.
+        """
+        return path.resolve().relative_to(self.root).as_posix()
+
+    def exists(self) -> bool:
+        """True only when the ``.taskpilot/`` workspace directory exists."""
+        return self.workspace_dir.is_dir()

package/src/taskpilot/core/loader.py

@@ -0,0 +1,102 @@
+"""Project loader that separates valid items from validation errors (task F001-T8).
+
+Loading is fault-tolerant (F001-R7): structurally valid items load and are
+returned even when sibling files are invalid, and every problem is surfaced
+through the :class:`~taskpilot.core.validation.ValidationReport` rather than
+crashing or being silently dropped.
+
+The authoritative findings come from :func:`validate_workspace`; this loader adds
+the parsed item objects (so callers get usable data) and project-metadata
+findings.
+"""
+
+from __future__ import annotations
+
+import yaml
+from pydantic import BaseModel, ValidationError
+
+from taskpilot.core.item_io import ItemParseError, parse_item_file
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.models import Item
+from taskpilot.core.project import ProjectMeta, read_project
+from taskpilot.core.validation import (
+    Finding,
+    Severity,
+    ValidationReport,
+    validate_workspace,
+)
+
+__all__ = ["LoadedProject", "load_project"]
+
+
+class LoadedProject(BaseModel):
+    """Result of loading a project: metadata, the parsed items, and all findings.
+
+    ``items`` contains every *structurally parseable* item (sorted by numeric id).
+    An item can be structurally valid yet still carry cross-file error findings
+    (e.g. ``duplicate_id`` or ``id_filename_mismatch``), so it appears in ``items``
+    while ``ok`` is ``False``. ``items`` is therefore not a pre-filtered "valid and
+    listable" set; adapters (CLI/WebUI) apply listability rules such as
+    deleted-exclusion and the invalid marker, correlating items with ``report`` by
+    id/path.
+    """
+
+    project: ProjectMeta | None
+    items: list[Item]
+    report: ValidationReport
+
+    @property
+    def ok(self) -> bool:
+        return self.report.ok
+
+
+def _numeric_id_key(item: Item) -> tuple[int, str]:
+    """Sort key for items by trailing numeric id suffix (``TP-2`` before ``TP-10``)."""
+    _, _, suffix = item.id.rpartition("-")
+    return (int(suffix), item.id) if suffix.isdigit() else (-1, item.id)
+
+
+def load_project(paths: WorkspacePaths) -> LoadedProject:
+    """Load a project's items and validation report without crashing on bad files."""
+    report = validate_workspace(paths)
+    findings: list[Finding] = list(report.findings)
+
+    # Project metadata: surface a finding when missing or invalid, but keep loading.
+    project: ProjectMeta | None = None
+    project_rel = paths.relative_posix(paths.project_file)
+    if not paths.project_file.exists():
+        findings.append(
+            Finding(
+                severity=Severity.error,
+                code="project_missing",
+                path=project_rel,
+                message="Project file project.yaml is missing",
+            )
+        )
+    else:
+        try:
+            project = read_project(paths)
+        except (ValidationError, yaml.YAMLError, UnicodeDecodeError, OSError) as exc:
+            findings.append(
+                Finding(
+                    severity=Severity.error,
+                    code="project_invalid",
+                    path=project_rel,
+                    message=f"Invalid project.yaml: {exc}",
+                )
+            )
+
+    # Parse the structurally valid items; invalid files are already in the report.
+    items: list[Item] = []
+    if paths.items_dir.is_dir():
+        for file in sorted(p for p in paths.items_dir.glob("*.yaml") if p.is_file()):
+            try:
+                items.append(parse_item_file(file))
+            except (ItemParseError, ValidationError, UnicodeDecodeError, OSError):
+                continue
+    items.sort(key=_numeric_id_key)
+
+    findings.sort(key=lambda f: (f.path, f.code, f.field or "", f.message))
+    return LoadedProject(
+        project=project, items=items, report=ValidationReport(findings=findings)
+    )

package/src/taskpilot/core/models.py

@@ -0,0 +1,114 @@
+"""Canonical item domain models (task F001-T3).
+
+Pydantic models for TaskPilot items, their enums, and non-parent links, matching
+``docs/specs/0002`` ("Item Fields", "Item Types", "Statuses", "Priority",
+"Links"). Field declaration order is the canonical write order so deterministic
+serialization (F001-T4) can rely on it.
+
+Type/enum validation happens here at construction time. Cross-file rules
+(unique IDs, id/filename match, reference existence) are validation-layer
+concerns (F001-T7), not model concerns.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, field_validator
+from typing_extensions import Annotated
+
+from taskpilot.core.timestamps import is_canonical_iso
+
+__all__ = ["SCHEMA_VERSION", "ItemType", "ItemStatus", "Priority", "ItemLinks", "Item"]
+
+#: Current canonical schema version for item files.
+SCHEMA_VERSION = 1
+
+
+class ItemType(str, Enum):
+    """Fixed item types through Release."""
+
+    epic = "epic"
+    feature = "feature"
+    task = "task"
+    bug = "bug"
+
+
+class ItemStatus(str, Enum):
+    """Alpha workflow statuses plus the reserved system status ``deleted``."""
+
+    backlog = "backlog"
+    ready = "ready"
+    in_progress = "in_progress"
+    done = "done"
+    cancelled = "cancelled"
+    deleted = "deleted"
+
+
+class Priority(str, Enum):
+    """Item priority; required, defaults to ``normal``."""
+
+    low = "low"
+    normal = "normal"
+    high = "high"
+
+
+NonEmptyStr = Annotated[str, StringConstraints(min_length=1)]
+
+
+class ItemLinks(BaseModel):
+    """Non-parent links: a map of link type to target item IDs.
+
+    Alpha supports only ``blocks`` and ``relates_to``; unknown link types (e.g.
+    ``duplicates``) are rejected.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    blocks: list[str] = Field(default_factory=list)
+    relates_to: list[str] = Field(default_factory=list)
+
+
+class Item(BaseModel):
+    """A canonical TaskPilot item.
+
+    Unknown top-level fields are preserved (``extra="allow"``) so updates to
+    parseable files do not drop data TaskPilot does not yet model.
+    """
+
+    # validate_default ensures defaulted enums (e.g. priority) are coerced to
+    # their string values just like supplied ones, so model_dump() never yields a
+    # raw enum object that breaks deterministic YAML serialization.
+    model_config = ConfigDict(
+        extra="allow", use_enum_values=True, validate_default=True
+    )
+
+    # Mandatory fields (canonical order first).
+    schema_version: int = SCHEMA_VERSION
+    id: NonEmptyStr
+    title: NonEmptyStr
+    priority: Priority = Priority.normal
+    type: ItemType
+    status: ItemStatus
+    created_at: str
+    updated_at: str
+    # Optional fields, in canonical order. Absent -> None (omitted on write).
+    parent_id: str | None = None
+    tags: list[str] | None = None
+    description: str | None = None
+    attachments: list[str] | None = None
+    dor: list[str] | None = None
+    dod: list[str] | None = None
+    links: ItemLinks | None = None
+    created_by: str | None = None
+    performed_by: str | None = None
+    external_refs: list[str] | None = None
+
+    @field_validator("created_at", "updated_at")
+    @classmethod
+    def _check_timestamp(cls, value: str, info) -> str:
+        if not is_canonical_iso(value):
+            raise ValueError(
+                f"{info.field_name} must be canonical UTC ISO 8601 (YYYY-MM-DDTHH:MM:SSZ): {value!r}"
+            )
+        return value

package/src/taskpilot/core/project.py

@@ -0,0 +1,151 @@
+"""Project metadata model and workspace initialization (task F001-T2).
+
+This is the storage-layer primitive that lays down the canonical ``.taskpilot/``
+tree and a minimal ``project.yaml``. It does not handle the CLI command, the
+local project registry, or project-service orchestration (those are F003/F002).
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, StringConstraints, field_validator
+from typing_extensions import Annotated
+
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.timestamps import is_canonical_iso, utc_now_iso
+from taskpilot.core.yaml_io import dump_yaml, load_yaml
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "ProjectMeta",
+    "InitResult",
+    "init_workspace",
+    "read_project",
+    "write_project",
+]
+
+#: Current canonical schema version for project.yaml.
+SCHEMA_VERSION = 1
+
+
+class ProjectMeta(BaseModel):
+    """Canonical project identity, persisted as ``.taskpilot/project.yaml``.
+
+    Field declaration order is the canonical write order (see ``docs/specs/0002``
+    "Project Metadata").
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: int = SCHEMA_VERSION
+    id: Annotated[str, StringConstraints(min_length=1)]
+    key: Annotated[str, StringConstraints(min_length=1)]
+    name: Annotated[str, StringConstraints(min_length=1)]
+    created_at: str
+
+    @field_validator("created_at")
+    @classmethod
+    def _check_created_at(cls, value: str) -> str:
+        if not is_canonical_iso(value):
+            raise ValueError(
+                f"created_at must be canonical UTC ISO 8601 (YYYY-MM-DDTHH:MM:SSZ): {value!r}"
+            )
+        return value
+
+
+@dataclass
+class InitResult:
+    """Outcome of :func:`init_workspace`.
+
+    ``created`` is True only when a new ``project.yaml`` was written this call.
+    Paths are workspace-root-relative POSIX strings.
+    """
+
+    workspace_dir: Path
+    created: bool
+    created_paths: list[str] = field(default_factory=list)
+    existing_paths: list[str] = field(default_factory=list)
+
+
+def write_project(paths: WorkspacePaths, meta: ProjectMeta) -> None:
+    """Write ``meta`` to the canonical ``project.yaml`` deterministically.
+
+    Serialization happens first, then the content is written to a temp file in the
+    same directory and ``os.replace`` publishes it atomically. A crash or error
+    after serialization cannot leave ``project.yaml`` truncated or empty.
+    """
+    content = dump_yaml(meta.model_dump()).encode("utf-8")
+    fd, tmp = tempfile.mkstemp(
+        dir=str(paths.workspace_dir), prefix=".project_", suffix=".tmp"
+    )
+    try:
+        os.write(fd, content)
+    except BaseException:
+        os.close(fd)
+        os.unlink(tmp)
+        raise
+    os.close(fd)
+    try:
+        os.replace(tmp, str(paths.project_file))
+    except BaseException:
+        os.unlink(tmp)
+        raise
+
+
+def read_project(paths: WorkspacePaths) -> ProjectMeta:
+    """Read and validate ``project.yaml`` into a :class:`ProjectMeta`."""
+    data = load_yaml(paths.project_file.read_text(encoding="utf-8"))
+    return ProjectMeta.model_validate(data)
+
+
+def init_workspace(
+    root: Path | str,
+    *,
+    project_id: str,
+    key: str,
+    name: str,
+    now: str | None = None,
+) -> InitResult:
+    """Create the ``.taskpilot/`` tree under ``root`` without overwriting canonical files.
+
+    Missing directories (``.taskpilot/``, ``items/``, ``comments/``) and a missing
+    ``project.yaml`` are created. Existing canonical files are left untouched, so
+    re-running init is safe and preserves project identity.
+    """
+    paths = WorkspacePaths.for_root(root)
+    created: list[str] = []
+    existing: list[str] = []
+
+    for directory in (paths.workspace_dir, paths.items_dir, paths.comments_dir):
+        rel = paths.relative_posix(directory)
+        if directory.is_dir():
+            existing.append(rel)
+        else:
+            directory.mkdir(parents=True, exist_ok=True)
+            created.append(rel)
+
+    project_rel = paths.relative_posix(paths.project_file)
+    project_created = False
+    if paths.project_file.exists():
+        existing.append(project_rel)
+    else:
+        meta = ProjectMeta(
+            id=project_id,
+            key=key,
+            name=name,
+            created_at=now or utc_now_iso(),
+        )
+        write_project(paths, meta)
+        created.append(project_rel)
+        project_created = True
+
+    return InitResult(
+        workspace_dir=paths.workspace_dir,
+        created=project_created,
+        created_paths=created,
+        existing_paths=existing,
+    )

package/src/taskpilot/core/timestamps.py

@@ -0,0 +1,54 @@
+"""UTC timestamp helpers for canonical TaskPilot data.
+
+Canonical timestamps are UTC ISO 8601 with seconds and a ``Z`` suffix, e.g.
+``2026-06-24T10:00:00Z`` (see ``docs/specs/0002``). Comment filenames use the
+same instant with ``:`` replaced by ``-`` so they are filesystem-safe and sort
+chronologically.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+__all__ = [
+    "utc_now_iso",
+    "is_canonical_iso",
+    "iso_to_filename_stamp",
+    "filename_stamp_to_iso",
+]
+
+_ISO_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def utc_now_iso() -> str:
+    """Return the current UTC time as ``YYYY-MM-DDTHH:MM:SSZ`` (seconds precision)."""
+    return datetime.now(timezone.utc).strftime(_ISO_FORMAT)
+
+
+def is_canonical_iso(value: str) -> bool:
+    """True when ``value`` is a canonical UTC ISO 8601 timestamp (``...Z``, seconds)."""
+    try:
+        datetime.strptime(value, _ISO_FORMAT)
+    except (ValueError, TypeError):
+        return False
+    return True
+
+
+def iso_to_filename_stamp(iso: str) -> str:
+    """Convert a canonical ISO timestamp to a filesystem-safe stamp.
+
+    ``2026-06-24T10:00:00Z`` -> ``2026-06-24T10-00-00Z``.
+    """
+    datetime.strptime(iso, _ISO_FORMAT)  # validate shape
+    return iso.replace(":", "-")
+
+
+def filename_stamp_to_iso(stamp: str) -> str:
+    """Inverse of :func:`iso_to_filename_stamp`.
+
+    ``2026-06-24T10-00-00Z`` -> ``2026-06-24T10:00:00Z``.
+    """
+    date_part, _, time_part = stamp.partition("T")
+    iso = f"{date_part}T{time_part.replace('-', ':')}"
+    datetime.strptime(iso, _ISO_FORMAT)  # validate shape
+    return iso