@alexey_platkovsky/taskpilot 0.1.0-beta.1

package/src/taskpilot/cli/commands/init.py

@@ -0,0 +1,116 @@
+"""``taskpilot init <path>`` — workspace creation + registration (task F003-T2, F003-R1).
+
+Creates the repository-local ``.taskpilot/`` structure and ``project.yaml`` via
+the F002 project service, then adds/enables the project in the local system
+registry (spec ``0002`` "Project Initialization"). Identity is derived from the
+target folder name and overridable with ``--id`` / ``--key`` / ``--name``.
+
+``init`` is idempotent: re-running it on an already-initialized workspace does
+not overwrite canonical identity (the service refuses that) but still re-enables
+the project in the registry and reports it as already initialized.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import typer
+
+from taskpilot.services import registry
+from taskpilot.cli.context import get_state
+from taskpilot.cli.errors import service_errors
+from taskpilot.cli.output import print_json, print_line
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.services import project_service
+from taskpilot.services.errors import ConflictError, ValidationFailed
+
+__all__ = ["register", "derive_key"]
+
+_TOKEN_RE = re.compile(r"[A-Za-z0-9]+")
+
+
+def derive_key(name: str) -> str:
+    """Derive a default project key (item-id prefix) from a display ``name``.
+
+    Multi-word names use the uppercased first letter of each token
+    (``"Voice Pilot"`` / ``"voice-pilot"`` -> ``"VP"``); a single token is
+    uppercased whole (``"voicepilot"`` -> ``"VOICEPILOT"``). Returns ``""`` when
+    ``name`` has no alphanumeric characters, so the caller can prompt for ``--key``.
+    """
+    tokens = _TOKEN_RE.findall(name)
+    if not tokens:
+        return ""
+    if len(tokens) == 1:
+        return tokens[0].upper()
+    return "".join(token[0] for token in tokens).upper()
+
+
+def init_command(
+    ctx: typer.Context,
+    path: str = typer.Argument(
+        ".", help="Repository root to initialize (only this folder is inspected)."
+    ),
+    key: str = typer.Option(
+        None,
+        "--key",
+        help="Project key used as the item-ID prefix. Derived from the folder name if omitted.",
+    ),
+    name: str = typer.Option(
+        None, "--name", help="Project display name. Defaults to the folder name."
+    ),
+    project_id: str = typer.Option(
+        None, "--id", help="Project id. Derived from the name if omitted."
+    ),
+) -> None:
+    """Initialize a TaskPilot workspace and register the project."""
+    state = get_state(ctx)
+    target = Path(path).resolve()
+    resolved_name = name or target.name
+    resolved_key = key or derive_key(resolved_name)
+    paths = WorkspacePaths.for_root(target)
+
+    with service_errors():
+        if not resolved_key:
+            raise ValidationFailed(
+                f"Cannot derive a project key from {resolved_name!r}; pass --key"
+            )
+        try:
+            meta = project_service.create_project(
+                paths, key=resolved_key, name=resolved_name, project_id=project_id
+            )
+            created = True
+        except ConflictError:
+            # Already initialized: keep canonical identity, just re-enable in the registry.
+            meta = project_service.read_project(paths)
+            created = False
+
+        entry = registry.register_project(
+            registry.default_registry_dir(),
+            id=meta.id,
+            key=meta.key,
+            name=meta.name,
+            path=str(target),
+        )
+
+    if state.json:
+        print_json(
+            {
+                "created": created,
+                "workspace": paths.relative_posix(paths.workspace_dir),
+                "project": meta.model_dump(),
+                "registered": entry.model_dump(),
+            }
+        )
+        return
+
+    if created:
+        print_line(f"Initialized TaskPilot workspace at {target / '.taskpilot'}")
+    else:
+        print_line(f"Workspace already initialized at {target / '.taskpilot'}")
+    print_line(f"Registered project {meta.key} ({meta.name}).")
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the ``init`` command to ``app``."""
+    app.command("init")(init_command)

package/src/taskpilot/cli/commands/item.py

@@ -0,0 +1,305 @@
+"""``taskpilot item`` commands — list/show/create/update (task F003-T4, requirement F003-R4).
+
+Thin adapters over the F002 item service. Enum-like fields (``type``, ``status``,
+``priority``) are passed through as strings and validated by the service, which
+is the single source of truth for domain rules — invalid values surface as a
+``ValidationFailed`` mapped to exit code 1, before any file is written (F003-R4).
+JSON output dumps the item model in canonical field order for determinism
+(F003-R8).
+"""
+
+from __future__ import annotations
+
+import getpass
+from typing import Any, Optional
+
+import typer
+
+from taskpilot.cli.context import get_state
+from taskpilot.cli.errors import service_errors
+from taskpilot.cli.output import print_json, print_line, render_key_values, render_table
+from taskpilot.cli.workspace import find_workspace
+from taskpilot.core.models import Item
+from taskpilot.services import comment_service, item_service, link_service
+
+
+def _default_author() -> str:
+    """Best-effort local author identity for comments when ``--author`` is omitted."""
+    try:
+        return getpass.getuser()
+    except Exception:  # pragma: no cover - getuser is environment-dependent
+        return "unknown"
+
+
+__all__ = ["register"]
+
+_HUMAN_SKIP = frozenset({"schema_version"})
+
+item_app = typer.Typer(
+    name="item",
+    help="List, show, create, and update items.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _emit_item(
+    ctx: typer.Context, item: Item, *, human_prefix: str | None = None
+) -> None:
+    """Render a single item as JSON or a human key/value block (or a one-liner)."""
+    if get_state(ctx).json:
+        print_json(item.model_dump())
+        return
+    if human_prefix is not None:
+        print_line(f"{human_prefix} {item.id}")
+        return
+    pairs = [
+        (name, str(value))
+        for name, value in item.model_dump().items()
+        if value is not None and name not in _HUMAN_SKIP
+    ]
+    print_line(render_key_values(pairs))
+
+
+@item_app.command("list")
+def item_list(
+    ctx: typer.Context,
+    status: Optional[str] = typer.Option(None, "--status", help="Filter by status."),
+    type: Optional[str] = typer.Option(None, "--type", help="Filter by item type."),
+    project: Optional[str] = typer.Option(
+        None, "--project", help="Filter by project key (id prefix)."
+    ),
+    include_deleted: bool = typer.Option(
+        False, "--include-deleted", help="Include soft-deleted items."
+    ),
+) -> None:
+    """List items in the current workspace."""
+    with service_errors():
+        paths = find_workspace()
+        items = item_service.list_items(
+            paths,
+            project=project,
+            status=status,
+            type=type,
+            include_deleted=include_deleted,
+        )
+
+    if get_state(ctx).json:
+        print_json([item.model_dump() for item in items])
+        return
+
+    if not items:
+        print_line("No items found.")
+        return
+    rows = [[i.id, i.type, i.status, i.priority, i.title] for i in items]
+    print_line(render_table(["ID", "TYPE", "STATUS", "PRIORITY", "TITLE"], rows))
+
+
+@item_app.command("show")
+def item_show(
+    ctx: typer.Context,
+    item_id: str = typer.Argument(..., help="Item id, e.g. VP-1."),
+) -> None:
+    """Show a single item by id."""
+    with service_errors():
+        paths = find_workspace()
+        item = item_service.read_item(paths, item_id)
+    _emit_item(ctx, item)
+
+
+@item_app.command("create")
+def item_create(
+    ctx: typer.Context,
+    title: str = typer.Option(..., "--title", help="Item title (required)."),
+    type: str = typer.Option(
+        ..., "--type", help="Item type: epic|feature|task|bug (required)."
+    ),
+    priority: str = typer.Option(
+        "normal", "--priority", help="Priority: low|normal|high."
+    ),
+    status: str = typer.Option("backlog", "--status", help="Initial status."),
+    description: Optional[str] = typer.Option(
+        None, "--description", help="Item description."
+    ),
+    parent: Optional[str] = typer.Option(None, "--parent", help="Parent item id."),
+    tag: Optional[list[str]] = typer.Option(None, "--tag", help="Tag (repeatable)."),
+    created_by: Optional[str] = typer.Option(
+        None, "--created-by", help="Author identity."
+    ),
+) -> None:
+    """Create a new item and print its id."""
+    with service_errors():
+        paths = find_workspace()
+        item = item_service.create_item(
+            paths,
+            title=title,
+            type=type,
+            priority=priority,
+            status=status,
+            description=description,
+            parent_id=parent,
+            tags=tag or None,
+            created_by=created_by,
+        )
+    _emit_item(ctx, item, human_prefix="Created")
+
+
+@item_app.command("update")
+def item_update(
+    ctx: typer.Context,
+    item_id: str = typer.Argument(..., help="Item id to update."),
+    title: Optional[str] = typer.Option(None, "--title", help="New title."),
+    type: Optional[str] = typer.Option(None, "--type", help="New type."),
+    priority: Optional[str] = typer.Option(None, "--priority", help="New priority."),
+    status: Optional[str] = typer.Option(None, "--status", help="New status."),
+    description: Optional[str] = typer.Option(
+        None, "--description", help="New description."
+    ),
+    parent: Optional[str] = typer.Option(None, "--parent", help="New parent item id."),
+    tag: Optional[list[str]] = typer.Option(
+        None, "--tag", help="Replace tags (repeatable)."
+    ),
+) -> None:
+    """Update fields on an existing item.
+
+    Only the options you pass are changed; ``--parent`` and ``--tag`` set new
+    values (they do not merge). Every update refreshes ``updated_at``.
+    """
+    fields: dict[str, Any] = {}
+    if title is not None:
+        fields["title"] = title
+    if type is not None:
+        fields["type"] = type
+    if priority is not None:
+        fields["priority"] = priority
+    if status is not None:
+        fields["status"] = status
+    if description is not None:
+        fields["description"] = description
+    if parent is not None:
+        fields["parent_id"] = parent
+    if tag is not None:
+        fields["tags"] = tag
+
+    with service_errors():
+        paths = find_workspace()
+        item = item_service.update_item(paths, item_id, **fields)
+    _emit_item(ctx, item, human_prefix="Updated")
+
+
+def _emit_relationship(ctx: typer.Context, item: Item, message: str) -> None:
+    """Render a relationship change: the updated source item (JSON) or a confirmation."""
+    if get_state(ctx).json:
+        print_json(item.model_dump())
+        return
+    print_line(message)
+
+
+@item_app.command("parent")
+def item_parent(
+    ctx: typer.Context,
+    child_id: str = typer.Argument(..., help="Child item id."),
+    parent_id: str = typer.Argument(..., help="Parent item id."),
+) -> None:
+    """Set ``child_id``'s parent to ``parent_id`` (hierarchy rules apply)."""
+    with service_errors():
+        paths = find_workspace()
+        item = item_service.update_item(paths, child_id, parent_id=parent_id)
+    _emit_relationship(ctx, item, f"{child_id} parent set to {parent_id}.")
+
+
+@item_app.command("unparent")
+def item_unparent(
+    ctx: typer.Context,
+    child_id: str = typer.Argument(..., help="Child item id."),
+) -> None:
+    """Clear ``child_id``'s parent."""
+    with service_errors():
+        paths = find_workspace()
+        item = item_service.update_item(paths, child_id, parent_id=None)
+    _emit_relationship(ctx, item, f"{child_id} parent cleared.")
+
+
+@item_app.command("blocks")
+def item_blocks(
+    ctx: typer.Context,
+    source_id: str = typer.Argument(..., help="Item that blocks."),
+    target_id: str = typer.Argument(..., help="Item that is blocked."),
+) -> None:
+    """Record that ``source_id`` blocks ``target_id`` (idempotent)."""
+    with service_errors():
+        paths = find_workspace()
+        item = link_service.add_link(paths, source_id, "blocks", target_id)
+    _emit_relationship(ctx, item, f"{source_id} now blocks {target_id}.")
+
+
+@item_app.command("unblocks")
+def item_unblocks(
+    ctx: typer.Context,
+    source_id: str = typer.Argument(..., help="Item that blocks."),
+    target_id: str = typer.Argument(..., help="Item that is blocked."),
+) -> None:
+    """Remove a ``blocks`` link from ``source_id`` to ``target_id`` (idempotent)."""
+    with service_errors():
+        paths = find_workspace()
+        item = link_service.remove_link(paths, source_id, "blocks", target_id)
+    _emit_relationship(ctx, item, f"{source_id} no longer blocks {target_id}.")
+
+
+@item_app.command("relates")
+def item_relates(
+    ctx: typer.Context,
+    source_id: str = typer.Argument(..., help="Source item."),
+    target_id: str = typer.Argument(..., help="Related item."),
+) -> None:
+    """Record that ``source_id`` relates to ``target_id`` (idempotent)."""
+    with service_errors():
+        paths = find_workspace()
+        item = link_service.add_link(paths, source_id, "relates_to", target_id)
+    _emit_relationship(ctx, item, f"{source_id} now relates to {target_id}.")
+
+
+@item_app.command("unrelates")
+def item_unrelates(
+    ctx: typer.Context,
+    source_id: str = typer.Argument(..., help="Source item."),
+    target_id: str = typer.Argument(..., help="Related item."),
+) -> None:
+    """Remove a ``relates_to`` link from ``source_id`` to ``target_id`` (idempotent)."""
+    with service_errors():
+        paths = find_workspace()
+        item = link_service.remove_link(paths, source_id, "relates_to", target_id)
+    _emit_relationship(ctx, item, f"{source_id} no longer relates to {target_id}.")
+
+
+@item_app.command("comment")
+def item_comment(
+    ctx: typer.Context,
+    item_id: str = typer.Argument(..., help="Item id to comment on."),
+    text: str = typer.Argument(..., help="Comment body."),
+    author: Optional[str] = typer.Option(
+        None, "--author", help="Comment author (defaults to the local user)."
+    ),
+) -> None:
+    """Add a comment to an item and print the comment filename."""
+    with service_errors():
+        paths = find_workspace()
+        written = comment_service.add_comment(
+            paths, item_id, body=text, created_by=author or _default_author()
+        )
+
+    if get_state(ctx).json:
+        print_json(
+            {
+                "item_id": item_id,
+                "filename": written.name,
+                "path": paths.relative_posix(written),
+            }
+        )
+        return
+    print_line(written.name)
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the ``item`` command group to ``app``."""
+    app.add_typer(item_app)

package/src/taskpilot/cli/commands/project.py

@@ -0,0 +1,50 @@
+"""``taskpilot project list`` — list registered projects (task F003-T3, requirement F003-R3).
+
+Lists entries from the local system registry (spec ``0002``: "``project list``
+shows all registry entries, including disabled entries ... sorts by project
+name"), not the single in-repo project. Output is deterministic (entries sorted
+by name then id, canonical field order) so repeated ``--json`` calls are
+byte-identical (F003-R8).
+"""
+
+from __future__ import annotations
+
+import typer
+
+from taskpilot.services import registry
+from taskpilot.cli.context import get_state
+from taskpilot.cli.output import print_json, print_line, render_table
+
+__all__ = ["register"]
+
+project_app = typer.Typer(
+    name="project",
+    help="Inspect registered TaskPilot projects.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@project_app.command("list")
+def project_list(ctx: typer.Context) -> None:
+    """List projects registered on this machine."""
+    state = get_state(ctx)
+    entries = registry.list_projects(registry.default_registry_dir())
+
+    if state.json:
+        print_json([entry.model_dump() for entry in entries])
+        return
+
+    if not entries:
+        print_line(
+            "No registered projects. Run `taskpilot init .` in a project repository."
+        )
+        return
+
+    rows = [[e.id, e.key, e.name, "yes" if e.active else "no", e.path] for e in entries]
+    print_line(render_table(["ID", "KEY", "NAME", "ACTIVE", "PATH"], rows))
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the ``project`` command group to ``app``."""
+    app.add_typer(project_app)

package/src/taskpilot/cli/commands/serve.py

@@ -0,0 +1,78 @@
+"""``taskpilot serve`` — start the local REST API server (task F005-T6, requirement F005-R6).
+
+Resolves the TaskPilot workspace and registry, then runs the FastAPI application
+via uvicorn. The server binds to ``127.0.0.1`` on port ``7152`` by default,
+matching the Vite dev proxy target in ``web/vite.config.ts``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import typer
+import uvicorn
+
+from taskpilot.cli.exit_codes import EXIT_USER_ERROR
+from taskpilot.cli.workspace import find_workspace
+from taskpilot.core.layout import WorkspacePaths
+from taskpilot.services.errors import NotFound
+from taskpilot.services.registry import default_registry_dir
+
+#: Import-string for uvicorn's app factory. Passing a string (not an imported symbol)
+#: keeps the CLI adapter from importing the server adapter directly (TP-4).
+_APP_FACTORY = "taskpilot.server.app:create_app_from_env"
+_REGISTRY_DIR_ENV = "TASKPILOT_REGISTRY_DIR"
+
+__all__ = ["register"]
+
+
+def _validate_workspace(ws: WorkspacePaths) -> bool:
+    """Return True only when both the workspace dir and project.yaml exist."""
+    return ws.exists() and ws.project_file.is_file()
+
+
+def serve_command(
+    host: str = typer.Option("127.0.0.1", "--host", help="Host interface to bind."),
+    port: int = typer.Option(7152, "--port", help="Port to listen on."),
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help="Workspace root path (default: auto-detect from cwd).",
+    ),
+) -> None:
+    """Start the local REST API server."""
+    if workspace is not None:
+        ws = WorkspacePaths.for_root(Path(workspace))
+        if not _validate_workspace(ws):
+            typer.echo(
+                f"Error: no initialized TaskPilot workspace at {ws.root} "
+                f"(missing .taskpilot/ or project.yaml)",
+                err=True,
+            )
+            raise typer.Exit(EXIT_USER_ERROR)
+    else:
+        try:
+            ws = find_workspace()
+        except NotFound as exc:
+            typer.echo(f"Error: {exc}", err=True)
+            raise typer.Exit(EXIT_USER_ERROR) from exc
+
+    if not _validate_workspace(ws):
+        typer.echo(
+            f"Error: workspace at {ws.root} is missing project.yaml",
+            err=True,
+        )
+        raise typer.Exit(EXIT_USER_ERROR)
+
+    registry_dir = default_registry_dir()
+    os.environ[_REGISTRY_DIR_ENV] = str(registry_dir)
+
+    typer.echo(f"TaskPilot API server starting on http://{host}:{port}")
+    typer.echo(f"OpenAPI docs at http://{host}:{port}/docs")
+    uvicorn.run(_APP_FACTORY, factory=True, host=host, port=port)
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the ``serve`` command to ``app``."""
+    app.command("serve")(serve_command)

package/src/taskpilot/cli/commands/validate.py

@@ -0,0 +1,61 @@
+"""``taskpilot validate`` — workspace validation (task F003-T7, requirement F003-R7).
+
+Runs the F001 validator over the current workspace and reports findings. Exit
+code follows the report: ``0`` when there are no error-severity findings,
+``1`` otherwise (warnings alone do not fail). Output channels follow the CLI
+contract: human findings go to stderr (so a clean run leaves stderr empty,
+scenario F003-S7); the structured ``--json`` report goes to stdout.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from taskpilot.cli.context import get_state
+from taskpilot.cli.errors import service_errors
+from taskpilot.cli.exit_codes import EXIT_OK, EXIT_SYSTEM_ERROR, EXIT_USER_ERROR
+from taskpilot.cli.output import print_json, print_line
+from taskpilot.cli.workspace import find_workspace
+from taskpilot.core.validation import Finding, ValidationReport, validate_workspace
+
+__all__ = ["register"]
+
+
+def _format_finding(finding: Finding) -> str:
+    """Render a finding as ``<severity>: <path>[:<field>]: <message>``."""
+    location = finding.path
+    if finding.field:
+        location = f"{location}:{finding.field}"
+    return f"{finding.severity.value}: {location}: {finding.message}"
+
+
+def validate_command(ctx: typer.Context) -> None:
+    """Validate the current workspace and exit non-zero when errors are found."""
+    state = get_state(ctx)
+    with service_errors():
+        paths = find_workspace()
+        try:
+            report: ValidationReport = validate_workspace(paths)
+        except OSError as exc:
+            typer.echo(f"Error: {exc}", err=True)
+            raise typer.Exit(EXIT_SYSTEM_ERROR) from exc
+
+    if state.json:
+        print_json(report.to_dict())
+    else:
+        for finding in report.findings:
+            typer.echo(_format_finding(finding), err=True)
+        if report.ok:
+            print_line("Workspace is valid.")
+        else:
+            typer.echo(
+                f"Found {report.error_count} error(s), {report.warning_count} warning(s).",
+                err=True,
+            )
+
+    raise typer.Exit(EXIT_OK if report.ok else EXIT_USER_ERROR)
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the ``validate`` command to ``app``."""
+    app.command("validate")(validate_command)

package/src/taskpilot/cli/context.py

@@ -0,0 +1,36 @@
+"""Per-invocation CLI state carried through Typer's context (task F003-T1).
+
+The root callback stores a :class:`CLIState` on ``ctx.obj`` so every subcommand
+can read global options — currently the ``--json`` switch — without re-declaring
+them. Subcommands fetch it with :func:`get_state`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import typer
+
+__all__ = ["CLIState", "get_state"]
+
+
+@dataclass
+class CLIState:
+    """Global options resolved once by the root callback.
+
+    ``json`` selects machine-readable output (F003-R8); ``False`` means
+    human-readable output.
+    """
+
+    json: bool = False
+
+
+def get_state(ctx: typer.Context) -> CLIState:
+    """Return the :class:`CLIState` for this invocation, creating a default if absent.
+
+    A default is created when a command is exercised without the root callback
+    (e.g. some test harnesses), so subcommands never see ``None``.
+    """
+    if not isinstance(ctx.obj, CLIState):
+        ctx.obj = CLIState()
+    return ctx.obj