@alexey_platkovsky/taskpilot 0.1.0-beta.1

package/src/taskpilot/services/item_service.py

@@ -0,0 +1,264 @@
+"""Item domain service: create, read, update, list (task F002-T2, requirement F002-R2).
+
+Stateless operations over canonical ``items/<id>.yaml`` files. IDs are allocated
+as ``<PROJECT_KEY>-<n>`` where ``n`` is one past the highest existing numeric
+suffix (gaps from deleted items are not reused). Model construction validates
+enums/timestamps, so invalid input is rejected before any file is written
+(F002-R8); richer pre-write validation is consolidated in F002-T8.
+
+Hierarchy rules for ``parent_id`` (F002-T3) and links (F002-T4/T5) are layered on
+in their own tasks; this service owns plain field create/read/update/list.
+"""
+
+from __future__ import annotations
+
+from pydantic import ValidationError
+
+from taskpilot.core.item_io import ItemParseError, parse_item_file, write_item
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.models import Item
+from taskpilot.core.timestamps import utc_now_iso
+from taskpilot.services.errors import NotFound, ValidationFailed
+from taskpilot.services.hierarchy import validate_can_parent_children, validate_parent
+from taskpilot.services.operation_validation import build_validated_item
+from taskpilot.services.project_service import read_project
+
+__all__ = [
+    "create_item",
+    "read_item",
+    "update_item",
+    "delete_item",
+    "list_items",
+    "list_invalid_item_stubs",
+    "next_id",
+]
+
+
+def _numeric_suffix(item_id: str, key: str) -> int | None:
+    """Return the numeric suffix of ``item_id`` for project ``key``, else ``None``."""
+    prefix = f"{key}-"
+    if not item_id.startswith(prefix):
+        return None
+    rest = item_id[len(prefix) :]
+    return int(rest) if rest.isdigit() else None
+
+
+def next_id(paths: WorkspacePaths, key: str) -> str:
+    """Allocate the next item id for project ``key`` as ``<key>-<max+1>``.
+
+    Scans existing ``items/*.yaml`` filenames for the highest numeric suffix.
+    Gaps left by deleted items are not reused (see ``tasks.md`` notes).
+    """
+    highest = 0
+    if paths.items_dir.is_dir():
+        for file in paths.items_dir.glob("*.yaml"):
+            suffix = _numeric_suffix(file.stem, key)
+            if suffix is not None and suffix > highest:
+                highest = suffix
+    return f"{key}-{highest + 1}"
+
+
+def create_item(
+    paths: WorkspacePaths,
+    *,
+    title: str,
+    type: str,
+    priority: str = "normal",
+    status: str = "backlog",
+    description: str | None = None,
+    parent_id: str | None = None,
+    tags: list[str] | None = None,
+    created_by: str | None = None,
+    now: str | None = None,
+) -> Item:
+    """Create a new item with an allocated id and return it (F002-R2).
+
+    Requires an initialized project (its key prefixes the id). ``created_at`` and
+    ``updated_at`` are set to ``now`` (current UTC by default). Raises
+    :class:`NotFound` when no project exists and :class:`ValidationFailed` for
+    invalid field values — no file is written in the latter case.
+    """
+    project = read_project(paths)  # raises NotFound when absent
+    timestamp = now or utc_now_iso()
+    item_id = next_id(paths, project.key)
+    item = build_validated_item(
+        {
+            "id": item_id,
+            "title": title,
+            "type": type,
+            "priority": priority,
+            "status": status,
+            "created_at": timestamp,
+            "updated_at": timestamp,
+            "description": description,
+            "parent_id": parent_id,
+            "tags": tags,
+            "created_by": created_by,
+        }
+    )
+    validate_parent(
+        paths, child_id=item.id, child_type=item.type, parent_id=item.parent_id
+    )
+    write_item(paths, item)
+    return item
+
+
+def read_item(paths: WorkspacePaths, item_id: str) -> Item:
+    """Read an item by id (F002-R2).
+
+    Raises :class:`NotFound` when the file is absent and :class:`ValidationFailed`
+    when it exists but cannot be parsed/validated.
+    """
+    target = paths.item_file(item_id)
+    if not target.is_file():
+        raise NotFound(f"No item found with id {item_id!r}")
+    try:
+        return parse_item_file(target)
+    except (ItemParseError, ValidationError, UnicodeDecodeError, OSError) as exc:
+        raise ValidationFailed(f"Invalid item file for {item_id!r}: {exc}") from exc
+
+
+def update_item(
+    paths: WorkspacePaths,
+    item_id: str,
+    *,
+    now: str | None = None,
+    **fields: object,
+) -> Item:
+    """Update ``item_id``'s fields and refresh ``updated_at`` (F002-R2).
+
+    Reads the current item, applies ``fields``, re-validates, and persists.
+    ``id`` and ``created_at`` cannot be changed. Raises :class:`NotFound` when the
+    item is absent and :class:`ValidationFailed` for invalid values (the file is
+    left unchanged in that case).
+    """
+    current = read_item(paths, item_id)
+
+    if not fields:
+        # No-op update: do not rewrite the file or bump updated_at (avoids a
+        # spurious Git diff on an empty change).
+        return current
+
+    for immutable in ("id", "created_at"):
+        if immutable in fields:
+            raise ValidationFailed(f"Field {immutable!r} cannot be updated")
+
+    data = current.model_dump()
+    data.update(fields)
+    data["updated_at"] = now or utc_now_iso()
+    updated = build_validated_item(data)
+
+    validate_parent(
+        paths, child_id=updated.id, child_type=updated.type, parent_id=updated.parent_id
+    )
+    if updated.type != current.type:
+        validate_can_parent_children(
+            paths, parent_id=updated.id, parent_type=updated.type
+        )
+    _validate_links(paths, updated)
+    write_item(paths, updated)
+    return updated
+
+
+def list_invalid_item_stubs(
+    paths: WorkspacePaths,
+    *,
+    project: str | None = None,
+) -> list[tuple[str, str, str]]:
+    """Return (item_id, relative_path, error_message) for unparseable item files.
+
+    Scans the same ``items/*.yaml`` glob used by :func:`list_items` but collects
+    files that raise a parse or validation error instead of silently skipping them.
+    The caller is responsible for surfacing these as invalid-item representations
+    (e.g. API findings) to honor the product invariant that invalid files remain
+    visible and actionable.
+    """
+    result: list[tuple[str, str, str]] = []
+    if not paths.items_dir.is_dir():
+        return result
+    for file in paths.items_dir.glob("*.yaml"):
+        if not file.is_file():
+            continue
+        if project is not None and not file.stem.startswith(f"{project}-"):
+            continue
+        try:
+            parse_item_file(file)
+        except (ItemParseError, ValidationError, UnicodeDecodeError, OSError) as exc:
+            rel = paths.relative_posix(file)
+            result.append((file.stem, rel, str(exc)))
+    return result
+
+
+def _validate_links(paths: WorkspacePaths, item: Item) -> None:
+    """Reject self-links or links to unknown items on the canonical write path.
+
+    ``add_link``/``remove_link`` validate before delegating here, but ``links``
+    can also reach :func:`update_item` directly, so the shared write path must
+    enforce the same rules (F002-R4/R8) — no dangling or self links may persist.
+    """
+    if item.links is None:
+        return
+    for link_type in ("blocks", "relates_to"):
+        for target in getattr(item.links, link_type):
+            if target == item.id:
+                raise ValidationFailed(f"Item {item.id!r} cannot link to itself")
+            if not paths.item_file(target).is_file():
+                raise ValidationFailed(
+                    f"links.{link_type} references unknown item {target!r}"
+                )
+
+
+def delete_item(paths: WorkspacePaths, item_id: str, *, now: str | None = None) -> Item:
+    """Soft-delete an item by setting ``status: deleted`` (F002-R7).
+
+    The file is preserved on disk and stays findable by direct lookup; default
+    listings exclude it. Idempotent: deleting an already-deleted item returns it
+    unchanged without rewriting the file. Raises :class:`NotFound` when absent.
+    """
+    current = read_item(paths, item_id)  # raises NotFound when absent
+    if current.status == "deleted":
+        return current  # idempotent: no rewrite, updated_at preserved
+    return update_item(paths, item_id, now=now, status="deleted")
+
+
+def _numeric_id_key(item: Item) -> tuple[int, str]:
+    _, _, suffix = item.id.rpartition("-")
+    return (int(suffix), item.id) if suffix.isdigit() else (-1, item.id)
+
+
+def list_items(
+    paths: WorkspacePaths,
+    *,
+    project: str | None = None,
+    status: str | None = None,
+    type: str | None = None,
+    include_deleted: bool = False,
+) -> list[Item]:
+    """List items, filtered and sorted by numeric id (F002-R2).
+
+    Filters: ``project`` (item-id key prefix), ``status``, ``type``. ``deleted``
+    items are excluded unless ``include_deleted`` is true. Structurally invalid
+    files are skipped here; surfacing them is the validation layer's job (F001-T7).
+    """
+    items: list[Item] = []
+    if paths.items_dir.is_dir():
+        for file in paths.items_dir.glob("*.yaml"):
+            if not file.is_file():
+                continue
+            try:
+                items.append(parse_item_file(file))
+            except (ItemParseError, ValidationError, UnicodeDecodeError, OSError):
+                continue
+
+    if project is not None:
+        prefix = f"{project}-"
+        items = [i for i in items if i.id.startswith(prefix)]
+    if status is not None:
+        items = [i for i in items if i.status == status]
+    if type is not None:
+        items = [i for i in items if i.type == type]
+    if not include_deleted:
+        items = [i for i in items if i.status != "deleted"]
+
+    items.sort(key=_numeric_id_key)
+    return items

package/src/taskpilot/services/link_service.py

@@ -0,0 +1,97 @@
+"""Link domain service: add, remove, query (task F002-T4, requirement F002-R4).
+
+Non-parent graph links (``blocks``, ``relates_to``) are stored as a map on the
+*source* item. Adding or removing a link rewrites only the source file (the
+target is never touched); reverse relationships are derived elsewhere (F002-T5),
+never stored. Link targets must reference an existing item.
+"""
+
+from __future__ import annotations
+
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.models import Item
+from taskpilot.services import item_service
+from taskpilot.services.errors import ValidationFailed
+
+__all__ = ["LINK_TYPES", "add_link", "remove_link", "query_links"]
+
+#: Link types supported through Alpha.
+LINK_TYPES = ("blocks", "relates_to")
+
+
+def _require_link_type(link_type: str) -> None:
+    if link_type not in LINK_TYPES:
+        raise ValidationFailed(
+            f"Unknown link type {link_type!r}; expected one of {list(LINK_TYPES)}"
+        )
+
+
+def _links_as_dict(item: Item) -> dict[str, list[str]]:
+    if item.links is None:
+        return {"blocks": [], "relates_to": []}
+    return {
+        "blocks": list(item.links.blocks),
+        "relates_to": list(item.links.relates_to),
+    }
+
+
+def add_link(
+    paths: WorkspacePaths,
+    source_id: str,
+    link_type: str,
+    target_id: str,
+    *,
+    now: str | None = None,
+) -> Item:
+    """Add ``link_type`` from ``source_id`` to ``target_id`` (F002-R4).
+
+    Validates the link type, rejects self-links, and requires the target to
+    exist. Idempotent: adding an existing link rewrites nothing. Raises
+    :class:`NotFound` when the source is missing and :class:`ValidationFailed`
+    for an unknown link type, self-link, or unknown target.
+    """
+    _require_link_type(link_type)
+    source = item_service.read_item(paths, source_id)  # NotFound propagates
+    if source_id == target_id:
+        raise ValidationFailed(f"Item {source_id!r} cannot link to itself")
+    if not paths.item_file(target_id).is_file():
+        raise ValidationFailed(f"Link target references unknown item {target_id!r}")
+
+    links = _links_as_dict(source)
+    if target_id in links[link_type]:
+        return source  # idempotent: already linked
+    links[link_type].append(target_id)
+    return item_service.update_item(paths, source_id, now=now, links=links)
+
+
+def remove_link(
+    paths: WorkspacePaths,
+    source_id: str,
+    link_type: str,
+    target_id: str,
+    *,
+    now: str | None = None,
+) -> Item:
+    """Remove ``link_type`` from ``source_id`` to ``target_id`` (F002-R4).
+
+    Idempotent: removing an absent link rewrites nothing and returns the source
+    unchanged. Raises :class:`NotFound` when the source is missing and
+    :class:`ValidationFailed` for an unknown link type.
+    """
+    _require_link_type(link_type)
+    source = item_service.read_item(paths, source_id)  # NotFound propagates
+
+    links = _links_as_dict(source)
+    if target_id not in links[link_type]:
+        return source  # idempotent: nothing to remove
+    links[link_type] = [t for t in links[link_type] if t != target_id]
+    return item_service.update_item(paths, source_id, now=now, links=links)
+
+
+def query_links(paths: WorkspacePaths, item_id: str) -> dict[str, list[str]]:
+    """Return ``item_id``'s stored (forward) links as ``{type: [target_ids]}`` (F002-R4).
+
+    Reverse links (``blocked_by``, ``related_to``) are derived separately (F002-T5).
+    Raises :class:`NotFound` when the item is missing.
+    """
+    return _links_as_dict(item_service.read_item(paths, item_id))

package/src/taskpilot/services/operation_validation.py

@@ -0,0 +1,52 @@
+"""Centralized pre-write operation validation (task F002-T8, requirement F002-R8).
+
+Services validate operation input here *before* touching the filesystem, so an
+invalid operation is rejected with a descriptive error and never leaves a partial
+or invalid file on disk. This is the single place that turns low-level pydantic
+``ValidationError`` detail into human-readable, field-level messages for the
+domain layer; adapters render the resulting :class:`ValidationFailed` message.
+
+Cross-file rules (reference existence, hierarchy, link targets) live in their own
+modules (validation layer, :mod:`hierarchy`, :mod:`link_service`); this module
+owns single-item field/shape validation that must pass before a write.
+"""
+
+from __future__ import annotations
+
+from pydantic import ValidationError
+
+from taskpilot.core.models import Item
+from taskpilot.services.errors import ValidationFailed
+
+__all__ = ["describe_validation_error", "build_validated_item"]
+
+
+def _describe_error(err: dict) -> str:
+    """Render one pydantic error as a human-readable field-level message."""
+    field = ".".join(str(p) for p in err["loc"])
+    etype = err["type"]
+    if etype == "missing":
+        return f"Missing required field: {field}"
+    if etype == "enum":
+        expected = err.get("ctx", {}).get("expected", "")
+        return f"Invalid value for {field}: expected one of {expected}"
+    return f"{field}: {err['msg']}"
+
+
+def describe_validation_error(exc: ValidationError) -> str:
+    """Join all field-level problems in ``exc`` into one descriptive message."""
+    return "; ".join(_describe_error(err) for err in exc.errors())
+
+
+def build_validated_item(data: dict) -> Item:
+    """Validate item ``data`` into an :class:`Item`, or raise :class:`ValidationFailed`.
+
+    The raised error carries a descriptive, field-level message so callers never
+    need to write a file just to discover the input was invalid (F002-R8).
+    """
+    try:
+        return Item.model_validate(data)
+    except ValidationError as exc:
+        raise ValidationFailed(
+            f"Invalid item: {describe_validation_error(exc)}"
+        ) from exc

package/src/taskpilot/services/project_service.py

@@ -0,0 +1,111 @@
+"""Project domain service: create, read, list (task F002-T1, requirement F002-R1).
+
+Orchestrates the F001 storage primitives in :mod:`taskpilot.core.project`.
+Business rules owned here:
+
+- creating a project over an already-initialized workspace is a conflict;
+- the project ``id`` is derived from the display name when not supplied;
+- ``read``/``list`` translate "missing or invalid" into domain errors rather
+  than leaking storage exceptions.
+
+One repository holds exactly one TaskPilot project (see ``docs/architecture.md``),
+so :func:`list_projects` returns the single registered project or an empty list.
+"""
+
+from __future__ import annotations
+
+import re
+
+import yaml
+from pydantic import ValidationError
+
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.project import (
+    ProjectMeta,
+    init_workspace,
+    read_project as _read_project_file,
+)
+from taskpilot.services.errors import ConflictError, NotFound, ValidationFailed
+
+__all__ = ["create_project", "read_project", "list_projects", "slugify"]
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(value: str) -> str:
+    """Derive a filesystem/identity-safe slug from ``value``.
+
+    Lowercases, replaces runs of non-alphanumeric characters with a single ``-``,
+    and trims leading/trailing dashes. ``"Voice Pilot"`` -> ``"voice-pilot"``.
+    """
+    return _SLUG_RE.sub("-", value.lower()).strip("-")
+
+
+def create_project(
+    paths: WorkspacePaths,
+    *,
+    key: str,
+    name: str,
+    project_id: str | None = None,
+    now: str | None = None,
+) -> ProjectMeta:
+    """Create a new project and return its model (F002-R1).
+
+    Writes ``project.yaml`` with the given ``key`` and ``name``. ``project_id``
+    defaults to a slug of ``name``. Raises :class:`ValidationFailed` for empty
+    identity fields and :class:`ConflictError` when a project already exists.
+    """
+    if not key or not key.strip():
+        raise ValidationFailed("Project key must not be empty")
+    if not name or not name.strip():
+        raise ValidationFailed("Project name must not be empty")
+
+    if paths.project_file.exists():
+        raise ConflictError(
+            f"A project already exists at {paths.relative_posix(paths.project_file)}"
+        )
+
+    resolved_id = project_id if project_id else slugify(name)
+    if not resolved_id:
+        raise ValidationFailed(
+            f"Cannot derive a project id from name {name!r}; supply project_id"
+        )
+
+    result = init_workspace(
+        paths.root, project_id=resolved_id, key=key, name=name, now=now
+    )
+    if not result.created:
+        # Lost a race: another writer initialized the project between our check and init.
+        raise ConflictError(
+            f"A project already exists at {paths.relative_posix(paths.project_file)}"
+        )
+    return read_project(paths)
+
+
+def read_project(paths: WorkspacePaths) -> ProjectMeta:
+    """Read project metadata (F002-R1).
+
+    Raises :class:`NotFound` when ``project.yaml`` is absent and
+    :class:`ValidationFailed` when it exists but is unreadable/invalid.
+    """
+    if not paths.project_file.exists():
+        raise NotFound(
+            f"No project found at {paths.relative_posix(paths.project_file)}"
+        )
+    try:
+        return _read_project_file(paths)
+    except (ValidationError, yaml.YAMLError, UnicodeDecodeError, OSError) as exc:
+        raise ValidationFailed(
+            f"Invalid project file {paths.relative_posix(paths.project_file)}: {exc}"
+        ) from exc
+
+
+def list_projects(paths: WorkspacePaths) -> list[ProjectMeta]:
+    """List registered projects (F002-R1).
+
+    Returns the single registered project, or an empty list when the workspace
+    has no project. (One repository holds one project.)
+    """
+    if not paths.project_file.exists():
+        return []
+    return [read_project(paths)]