@alexey_platkovsky/taskpilot 0.1.0-beta.1

package/src/taskpilot/cli/errors.py

@@ -0,0 +1,53 @@
+"""Translate domain errors into CLI stderr output and exit codes (task F003-T1).
+
+Domain services raise :class:`~taskpilot.services.errors.ServiceError` subtypes.
+The CLI adapter turns those into an actionable stderr message and the
+deterministic exit code from :mod:`taskpilot.cli.exit_codes`:
+
+- :class:`ValidationFailed`, :class:`NotFound`, :class:`ConflictError` are
+  caller-correctable -> exit ``1`` (user error);
+- any other :class:`ServiceError` is treated as an unexpected internal failure
+  -> exit ``2`` (system error).
+
+JSON-mode error envelopes are intentionally out of scope for Alpha (see
+``requirements.md`` "Out of Scope"); errors are plain text on stderr in every
+mode so the message is never swallowed.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator
+
+import typer
+
+from taskpilot.cli import exit_codes
+from taskpilot.services.errors import (
+    ConflictError,
+    NotFound,
+    ServiceError,
+    ValidationFailed,
+)
+
+__all__ = ["service_errors"]
+
+#: Service errors the caller can correct -> user error exit code.
+_USER_ERRORS = (ValidationFailed, NotFound, ConflictError)
+
+
+@contextmanager
+def service_errors() -> Iterator[None]:
+    """Run a command body, converting service errors to stderr + ``typer.Exit``.
+
+    Wrap the service calls of a command in this context manager. Known
+    caller-correctable errors exit ``1``; any other :class:`ServiceError` exits
+    ``2``. Non-``ServiceError`` exceptions propagate unchanged.
+    """
+    try:
+        yield
+    except _USER_ERRORS as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(exit_codes.EXIT_USER_ERROR) from exc
+    except ServiceError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(exit_codes.EXIT_SYSTEM_ERROR) from exc

package/src/taskpilot/cli/exit_codes.py

@@ -0,0 +1,20 @@
+"""Deterministic CLI exit codes (feature F003).
+
+The CLI contract (``docs/features/F003_cli-interface/requirements.md``) fixes
+three exit codes so scripts and AI agents can branch on them reliably:
+
+- ``0`` success;
+- ``1`` user error (bad input, not found, conflict — the caller can fix it);
+- ``2`` system error (an unexpected failure the caller cannot fix).
+"""
+
+from __future__ import annotations
+
+__all__ = ["EXIT_OK", "EXIT_USER_ERROR", "EXIT_SYSTEM_ERROR"]
+
+#: Command completed successfully.
+EXIT_OK = 0
+#: Caller-correctable error: invalid input, missing item/project, conflict.
+EXIT_USER_ERROR = 1
+#: Unexpected failure the caller cannot correct (I/O, internal error).
+EXIT_SYSTEM_ERROR = 2

package/src/taskpilot/cli/output.py

@@ -0,0 +1,77 @@
+"""Output formatting for the TaskPilot CLI (task F003-T1, requirement F003-R8).
+
+Two output modes share one rendering seam so every command stays consistent:
+
+- **JSON mode** (``--json``): :func:`dumps_json` serializes plain data to
+  deterministic JSON on stdout. Determinism (F003-R8) comes from preserving the
+  data's own key order — domain models are dumped in canonical field order, so
+  re-running a read command with no state change yields byte-identical bytes. We
+  never ``sort_keys``: canonical order is declared field order, not alphabetical.
+- **Human mode** (default): helpers render tables, key/value blocks, and
+  one-line confirmations to stdout.
+
+Errors always go to stderr (see :mod:`taskpilot.cli.errors`); these helpers
+write only success output to stdout.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, TextIO
+
+__all__ = [
+    "dumps_json",
+    "print_json",
+    "print_line",
+    "render_table",
+    "render_key_values",
+]
+
+
+def dumps_json(data: Any) -> str:
+    """Serialize ``data`` to deterministic, human-readable JSON.
+
+    Key order is taken from ``data`` as given (no ``sort_keys``) so that callers
+    controlling field order — e.g. Pydantic ``model_dump`` in canonical order —
+    get stable output. Uses 2-space indentation and keeps non-ASCII characters
+    verbatim. No trailing newline is added; :func:`print_json` adds one.
+    """
+    return json.dumps(data, indent=2, ensure_ascii=False)
+
+
+def print_json(data: Any, *, stream: TextIO | None = None) -> None:
+    """Write ``data`` as JSON plus a trailing newline to stdout (or ``stream``)."""
+    print(dumps_json(data), file=stream or sys.stdout)
+
+
+def print_line(text: str, *, stream: TextIO | None = None) -> None:
+    """Write a single human-readable line to stdout (or ``stream``)."""
+    print(text, file=stream or sys.stdout)
+
+
+def render_table(headers: list[str], rows: list[list[str]]) -> str:
+    """Render a fixed-width text table with left-aligned, space-padded columns.
+
+    Returns the header row, a dashed rule, and one line per row. With no rows the
+    header and rule are still returned so the column shape is visible.
+    """
+    columns = [headers] + rows
+    widths = [max(len(str(row[i])) for row in columns) for i in range(len(headers))]
+
+    def _format(cells: list[str]) -> str:
+        return "  ".join(
+            str(cell).ljust(widths[i]) for i, cell in enumerate(cells)
+        ).rstrip()
+
+    lines = [_format(headers), "  ".join("-" * w for w in widths).rstrip()]
+    lines.extend(_format(row) for row in rows)
+    return "\n".join(lines)
+
+
+def render_key_values(pairs: list[tuple[str, str]]) -> str:
+    """Render ``(key, value)`` pairs as right-padded ``key: value`` lines."""
+    if not pairs:
+        return ""
+    width = max(len(key) for key, _ in pairs)
+    return "\n".join(f"{key.ljust(width)}  {value}" for key, value in pairs)

package/src/taskpilot/cli/workspace.py

@@ -0,0 +1,33 @@
+"""Locate the TaskPilot workspace for repo-scoped commands (task F003-T4).
+
+Commands like ``item`` and ``validate`` operate on "the current project". They
+resolve it by walking up from the current directory to the nearest ancestor that
+contains a ``.taskpilot/`` directory — the conventional repo-root discovery used
+by Git-like tools. ``init`` does not use this (it inspects only the given path).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from taskpilot.core.layout import WORKSPACE_DIRNAME, WorkspacePaths
+from taskpilot.services.errors import NotFound
+
+__all__ = ["find_workspace"]
+
+
+def find_workspace(start: Path | None = None) -> WorkspacePaths:
+    """Return the workspace for the repo containing ``start`` (default: cwd).
+
+    Walks ``start`` and its parents for a ``.taskpilot/`` directory. Raises
+    :class:`~taskpilot.services.errors.NotFound` (mapped to exit code 1) when no
+    workspace is found, with a hint to run ``taskpilot init``.
+    """
+    current = (start or Path.cwd()).resolve()
+    for directory in (current, *current.parents):
+        if (directory / WORKSPACE_DIRNAME).is_dir():
+            return WorkspacePaths.for_root(directory)
+    raise NotFound(
+        f"No TaskPilot workspace found in {current} or any parent directory; "
+        "run `taskpilot init .` in the project root"
+    )

package/src/taskpilot/core/__init__.py

@@ -0,0 +1,5 @@
+"""TaskPilot core domain layer.
+
+Business rules live here. CLI and REST adapters call into this layer directly;
+filesystem and index/cache details must not leak into the domain model.
+"""

package/src/taskpilot/core/comments.py

@@ -0,0 +1,238 @@
+"""Comment model and Markdown-with-frontmatter parsing (task F001-T5).
+
+Comments are append-only Markdown files with a YAML frontmatter block::
+
+    ---
+    schema_version: 1
+    created_at: 2026-06-23T10:00:00Z
+    created_by: Aleksei
+    ---
+
+    Investigated current parser behavior.
+
+They live under ``.taskpilot/comments/<ITEM_ID>/``; the folder name is the owning
+item ID, so frontmatter does not duplicate it. The filename timestamp is the
+comment identity and should match ``created_at``. Comment writing and timestamp
+collision handling are F001-T6.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, StringConstraints, field_validator
+from typing_extensions import Annotated
+
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.timestamps import (
+    filename_stamp_to_iso,
+    is_canonical_iso,
+    iso_to_filename_stamp,
+    utc_now_iso,
+)
+from taskpilot.core.yaml_io import dump_yaml, load_yaml
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "Comment",
+    "CommentParseError",
+    "parse_comment_text",
+    "parse_comment_file",
+    "list_comments",
+    "dump_comment",
+    "write_comment",
+    "add_comment",
+    "comment_filename_timestamp",
+]
+
+#: Current canonical schema version for comment frontmatter.
+SCHEMA_VERSION = 1
+
+_FRONTMATTER_RE = re.compile(r"\A---\n(?P<fm>.*?)\n---\n?(?P<body>.*)\Z", re.DOTALL)
+
+NonEmptyStr = Annotated[str, StringConstraints(min_length=1)]
+
+
+class CommentParseError(Exception):
+    """Raised when a comment file lacks valid YAML frontmatter or a mapping body."""
+
+    def __init__(self, message: str, *, path: Path | None = None):
+        self.path = path
+        super().__init__(f"{path}: {message}" if path is not None else message)
+
+
+class Comment(BaseModel):
+    """A single append-only comment parsed from a Markdown file."""
+
+    model_config = ConfigDict(extra="allow")
+
+    schema_version: int = SCHEMA_VERSION
+    created_at: str
+    created_by: NonEmptyStr
+    body: 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
+
+
+def parse_comment_text(text: str, *, path: Path | None = None) -> Comment:
+    """Parse comment Markdown ``text`` into a :class:`Comment`.
+
+    Raises :class:`CommentParseError` for missing/invalid frontmatter and pydantic
+    ``ValidationError`` for schema problems.
+
+    Line endings are normalized to ``\\n`` first, so CRLF files (e.g. produced on
+    Windows or by ``core.autocrlf``) parse identically to LF files.
+    """
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    match = _FRONTMATTER_RE.match(text)
+    if match is None:
+        raise CommentParseError("missing or malformed YAML frontmatter", path=path)
+    try:
+        data = load_yaml(match.group("fm"))
+    except yaml.YAMLError as exc:
+        raise CommentParseError(f"invalid YAML frontmatter: {exc}", path=path) from exc
+    if not isinstance(data, dict):
+        raise CommentParseError("frontmatter is not a mapping", path=path)
+    return Comment.model_validate({**data, "body": match.group("body").strip("\n")})
+
+
+def parse_comment_file(path: Path) -> Comment:
+    """Read and parse the comment file at ``path``.
+
+    Note: the filename timestamp is the comment's identity and should match
+    ``created_at`` (see ``docs/specs/0002``). For well-formed files they do match;
+    the parser does not *enforce* the match (a mismatch is accepted), leaving
+    detection to a future comment-validation layer. No F001 task currently owns
+    that check.
+    """
+    return parse_comment_text(path.read_text(encoding="utf-8"), path=path)
+
+
+def _comment_sort_key(filename: str) -> tuple[str, int]:
+    """Chronological sort key ``(timestamp, collision_suffix)`` for a comment filename.
+
+    A base file like ``2026-06-23T10-00-00Z.md`` sorts before its same-second
+    collision ``2026-06-23T10-00-00Z-2.md``; raw lexical order would invert them.
+    """
+    stem = filename[:-3] if filename.endswith(".md") else filename
+    marker = stem.find("Z")
+    if marker == -1:
+        return (stem, 0)
+    stamp = stem[: marker + 1]
+    rest = stem[marker + 1 :]
+    suffix = int(rest.lstrip("-")) if rest.startswith("-") and rest[1:].isdigit() else 0
+    return (stamp, suffix)
+
+
+def comment_filename_timestamp(filename: str) -> str | None:
+    """Return the canonical ISO timestamp encoded in a comment filename, or ``None``.
+
+    Strips the ``.md`` suffix and any ``-N`` collision suffix, then converts the
+    ``YYYY-MM-DDTHH-MM-SSZ`` stamp to ``YYYY-MM-DDTHH:MM:SSZ``. Returns ``None``
+    when the filename does not encode a valid timestamp stamp.
+    """
+    stem = filename[:-3] if filename.endswith(".md") else filename
+    marker = stem.find("Z")
+    if marker == -1:
+        return None
+    try:
+        return filename_stamp_to_iso(stem[: marker + 1])
+    except ValueError:
+        return None
+
+
+def list_comments(paths: WorkspacePaths, item_id: str) -> list[Comment]:
+    """Return ``item_id``'s comments parsed and ordered chronologically.
+
+    Returns an empty list when the item has no comment directory. This is a
+    strict accessor: it raises :class:`CommentParseError` (or pydantic
+    ``ValidationError``) on the first malformed comment file rather than skipping
+    it. Fault-tolerant loading that surfaces invalid files as findings is a
+    validation-layer concern (F001-T7); callers needing tolerance should validate
+    first.
+    """
+    directory = paths.item_comments_dir(item_id)
+    if not directory.is_dir():
+        return []
+    files = sorted(
+        (p for p in directory.iterdir() if p.is_file() and p.suffix == ".md"),
+        key=lambda p: _comment_sort_key(p.name),
+    )
+    return [parse_comment_file(p) for p in files]
+
+
+def dump_comment(comment: Comment) -> str:
+    """Serialize ``comment`` to Markdown-with-frontmatter, round-tripping the parser.
+
+    Frontmatter is emitted as ``schema_version``, ``created_at``, ``created_by``,
+    then preserved unknown fields in sorted key order, followed by the body.
+    """
+    raw = comment.model_dump()
+    frontmatter: dict = {
+        "schema_version": raw["schema_version"],
+        "created_at": raw["created_at"],
+        "created_by": raw["created_by"],
+    }
+    for key in sorted(k for k in raw if k not in Comment.model_fields):
+        frontmatter[key] = raw[key]
+
+    text = f"---\n{dump_yaml(frontmatter)}---\n"
+    if comment.body:
+        text += f"\n{comment.body}\n"
+    return text
+
+
+def write_comment(paths: WorkspacePaths, item_id: str, comment: Comment) -> Path:
+    """Write ``comment`` under ``item_id``, returning the chosen path.
+
+    The filename is derived from ``comment.created_at``; same-second collisions
+    receive ``-2``, ``-3``, ... suffixes (F001-R5). Creates the comment directory
+    if missing.
+
+    Slot acquisition uses ``open(..., "x")`` (O_EXCL) so the check-and-create is
+    atomic: two concurrent writers in the same second cannot both claim the same
+    filename.
+    """
+    directory = paths.item_comments_dir(item_id)
+    directory.mkdir(parents=True, exist_ok=True)
+
+    content = dump_comment(comment)
+    base = iso_to_filename_stamp(comment.created_at)
+    target = directory / f"{base}.md"
+    suffix = 2
+    while True:
+        try:
+            with open(target, "x", encoding="utf-8") as f:
+                f.write(content)
+            return target
+        except FileExistsError:
+            if suffix > 10_000:
+                raise RuntimeError(f"Too many comment collisions for {base}")
+            target = directory / f"{base}-{suffix}.md"
+            suffix += 1
+
+
+def add_comment(
+    paths: WorkspacePaths,
+    item_id: str,
+    *,
+    body: str,
+    created_by: str,
+    now: str | None = None,
+) -> Path:
+    """Create and write a new comment for ``item_id``; returns the written path.
+
+    ``now`` defaults to the current UTC time and becomes both the frontmatter
+    ``created_at`` and the filename timestamp.
+    """
+    comment = Comment(created_at=now or utc_now_iso(), created_by=created_by, body=body)
+    return write_comment(paths, item_id, comment)

package/src/taskpilot/core/item_io.py

@@ -0,0 +1,123 @@
+"""Reading and writing canonical item YAML files.
+
+F001-T3 implements strict parsing into the :class:`~taskpilot.core.models.Item`
+model. YAML syntax problems and non-mapping documents raise :class:`ItemParseError`
+with the offending path; schema problems raise pydantic ``ValidationError``.
+Both are surfaced as actionable findings by the validation/loader layers
+(F001-T7/T8) rather than crashing a project load.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+import yaml
+
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.core.models import Item
+from taskpilot.core.yaml_io import dump_yaml, load_yaml
+
+__all__ = [
+    "ItemParseError",
+    "parse_item_text",
+    "parse_item_file",
+    "dump_item",
+    "write_item",
+]
+
+
+class ItemParseError(Exception):
+    """Raised when item YAML cannot be read as a mapping document.
+
+    Distinct from pydantic ``ValidationError`` (schema/field problems): this
+    covers YAML syntax errors and documents whose top level is not a mapping.
+    """
+
+    def __init__(self, message: str, *, path: Path | None = None):
+        self.path = path
+        super().__init__(f"{path}: {message}" if path is not None else message)
+
+
+def parse_item_text(text: str, *, path: Path | None = None) -> Item:
+    """Parse item YAML ``text`` into an :class:`Item`.
+
+    Raises :class:`ItemParseError` for YAML syntax errors or a non-mapping
+    document, and pydantic ``ValidationError`` for schema/field problems.
+    """
+    try:
+        data = load_yaml(text)
+    except yaml.YAMLError as exc:
+        raise ItemParseError(f"invalid YAML: {exc}", path=path) from exc
+    if not isinstance(data, dict):
+        raise ItemParseError(
+            f"expected a YAML mapping, got {type(data).__name__}", path=path
+        )
+    return Item.model_validate(data)
+
+
+def parse_item_file(path: Path) -> Item:
+    """Read and parse the item file at ``path``."""
+    text = path.read_text(encoding="utf-8")
+    return parse_item_text(text, path=path)
+
+
+def dump_item(item: Item) -> str:
+    """Serialize ``item`` to canonical YAML text.
+
+    Known fields are emitted in canonical declaration order; absent optionals
+    (``None``) and empty link lists are omitted; preserved unknown fields are
+    written after known fields in sorted key order. The result is byte-stable on
+    re-serialization (F001-R3).
+    """
+    raw = item.model_dump()
+
+    ordered: dict = {}
+    for name in Item.model_fields:
+        if name not in raw:
+            continue
+        value = raw[name]
+        if value is None:
+            continue  # absent optional field is omitted
+        if name == "links":
+            non_empty = {k: v for k, v in value.items() if v}
+            if non_empty:
+                ordered[name] = non_empty
+            continue
+        ordered[name] = value
+
+    # Preserve unknown fields verbatim (including explicit nulls), after known
+    # fields, in sorted key order.
+    for key in sorted(k for k in raw if k not in Item.model_fields):
+        ordered[key] = raw[key]
+
+    return dump_yaml(ordered)
+
+
+def write_item(paths: WorkspacePaths, item: Item) -> Path:
+    """Write ``item`` to its canonical ``items/<id>.yaml`` path.
+
+    Creates the ``items/`` directory if missing, serializes the item first, then
+    publishes via a temp-file + ``os.replace`` so the target file is never left
+    truncated by a partial write.
+    """
+    target = paths.item_file(item.id)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    content = dump_item(item).encode("utf-8")
+    fd, tmp = tempfile.mkstemp(
+        dir=str(target.parent), prefix=f".{item.id}_", suffix=".tmp"
+    )
+    try:
+        os.write(fd, content)
+    except BaseException:
+        os.close(fd)
+        os.unlink(tmp)
+        raise
+    os.close(fd)
+    try:
+        os.replace(tmp, str(target))
+    except BaseException:
+        os.unlink(tmp)
+        raise
+    return target