kanbaroo-cli 0.2.2__py3-none-any.whl

kanbaroo_cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+Kanbaroo CLI: Typer-based command-line interface (kanbaroo, kb).
+"""
+
+__version__ = "0.2.2"

kanbaroo_cli/app.py

@@ -0,0 +1,114 @@
+"""
+Kanbaroo CLI entry point.
+
+Exposes the root Typer app and mounts every sub-app defined in
+``kanbaroo_cli.commands``. The root callback is a no-op so Typer
+always treats registered entries as subcommands; this mirrors the
+pattern established when only ``kb init`` existed and keeps the help
+output consistent as new commands arrive.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+import typer
+
+from kanbaroo_cli.commands import audit as audit_command
+from kanbaroo_cli.commands import backup as backup_command
+from kanbaroo_cli.commands import epic as epic_command
+from kanbaroo_cli.commands import export as export_command
+from kanbaroo_cli.commands import init as init_command
+from kanbaroo_cli.commands import server as server_command
+from kanbaroo_cli.commands import story as story_command
+from kanbaroo_cli.commands import tag as tag_command
+from kanbaroo_cli.commands import token as token_command
+from kanbaroo_cli.commands import workspace as workspace_command
+from kanbaroo_cli.rendering import stdout_console
+
+app = typer.Typer(
+    name="kanbaroo",
+    help="Kanbaroo: a kanban-style issue tracker for terminals and AI agents.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _installed_version() -> str:
+    """
+    Return the installed ``kanbaroo-cli`` version, or ``"unknown"`` when
+    the package is not installed (e.g. running directly from source
+    without an editable install).
+    """
+    try:
+        return _pkg_version("kanbaroo-cli")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _version_callback(value: bool) -> None:
+    """
+    Eager Typer option callback for ``--version``. Prints the installed
+    version and exits cleanly before any subcommand runs.
+    """
+    if value:
+        stdout_console.print(_installed_version())
+        raise typer.Exit(code=0)
+
+
+@app.callback()
+def _root(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        help="Print the installed kanbaroo-cli version and exit.",
+        is_eager=True,
+        callback=_version_callback,
+    ),
+) -> None:
+    """
+    Root callback. Exists only so Typer treats registered commands as
+    subcommands; it also wires the ``--version`` option.
+    """
+
+
+@app.command(
+    name="version",
+    help="Print the installed kanbaroo-cli version.",
+)
+def version_command() -> None:
+    """
+    Print the installed kanbaroo-cli version. Mirrors ``kb --version``.
+    """
+    stdout_console.print(_installed_version())
+
+
+app.command(
+    name="init",
+    help="Initialise the Kanbaroo config directory, database, and first token.",
+)(init_command.init)
+
+app.command(
+    name="audit",
+    help="Show the audit history for a story or epic.",
+)(audit_command.audit_command)
+
+app.command(
+    name="export",
+    help="Download an export archive for a workspace.",
+)(export_command.export_command)
+
+app.command(
+    name="backup",
+    help="Copy the configured SQLite database file to a timestamped path.",
+)(backup_command.backup_command)
+
+app.add_typer(workspace_command.app, name="workspace")
+app.add_typer(story_command.app, name="story")
+app.add_typer(epic_command.app, name="epic")
+app.add_typer(tag_command.app, name="tag")
+app.add_typer(token_command.app, name="token")
+app.add_typer(server_command.app, name="server")
+
+
+if __name__ == "__main__":
+    app()

kanbaroo_cli/client.py

@@ -0,0 +1,304 @@
+"""
+Thin HTTP client wrapper for the Kanbaroo CLI.
+
+Every command that hits the server goes through :class:`ApiClient` so
+that authentication, base URLs, error-envelope handling, and ETag /
+``If-Match`` plumbing live in exactly one place. The wrapper is
+intentionally not a general-purpose HTTP abstraction: its job is to
+turn the server's documented REST surface into Python calls that raise
+typed exceptions on failure.
+
+The client is built on top of :class:`httpx.Client` and accepts an
+optional ``transport`` argument so tests can swap in
+:class:`httpx.MockTransport` without monkey-patching. This is the same
+pattern the FastAPI ``TestClient`` uses internally.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+API_PREFIX = "/api/v1"
+
+
+class ApiError(Exception):
+    """
+    Base class for every error surfaced from the CLI HTTP client.
+
+    Commands translate this into a Rich-rendered message and a
+    non-zero exit code; no command handler should ever let a raw
+    :class:`httpx.HTTPError` escape.
+    """
+
+
+class ApiRequestError(ApiError):
+    """
+    Raised when the server returns a non-2xx response.
+
+    ``code`` and ``message`` come from the canonical error envelope
+    defined in ``docs/spec.md`` section 4.1. ``details`` is the
+    per-error dict the server chose to attach (or ``None``).
+    """
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.details = details
+
+
+class ApiTransportError(ApiError):
+    """
+    Raised when the HTTP round-trip itself fails (DNS, refused
+    connection, timeout). Distinct from :class:`ApiRequestError`
+    because the user's remediation is different: start the server,
+    check the network, fix the URL.
+    """
+
+
+def _extract_error(response: httpx.Response) -> ApiRequestError:
+    """
+    Parse the canonical error envelope out of a non-2xx response.
+
+    Falls back to a best-effort message if the server returned a
+    body that is not valid JSON or does not match the envelope shape;
+    the CLI still surfaces a non-zero exit with a human-readable
+    message in that case.
+    """
+    code = "unknown"
+    message = response.text or f"HTTP {response.status_code}"
+    details: dict[str, Any] | None = None
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict) and "error" in body and isinstance(body["error"], dict):
+        error = body["error"]
+        code = str(error.get("code", code))
+        message = str(error.get("message", message))
+        raw_details = error.get("details")
+        if isinstance(raw_details, dict):
+            details = raw_details
+    return ApiRequestError(
+        status_code=response.status_code,
+        code=code,
+        message=message,
+        details=details,
+    )
+
+
+class ApiClient:
+    """
+    Authenticated HTTP wrapper around the Kanbaroo REST API.
+
+    The wrapper handles four things the command handlers would
+    otherwise duplicate:
+
+    * Base URL composition: every call takes a path (``/workspaces``)
+      and the client prepends ``{base_url}{API_PREFIX}``.
+    * Auth: ``Authorization: Bearer <token>`` on every request.
+    * Error envelope translation: non-2xx responses become
+      :class:`ApiRequestError` instances.
+    * ETag / If-Match round trips: :meth:`patch_with_etag` and
+      :meth:`delete_with_etag` take an entity path and do the GET to
+      read the ETag before issuing the mutation.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """
+        Build a new client.
+
+        ``transport`` is injected so tests can drive the CLI with an
+        :class:`httpx.MockTransport` without touching the network.
+        """
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=f"{self._base_url}{API_PREFIX}",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+            transport=transport,
+            timeout=timeout,
+        )
+
+    def __enter__(self) -> ApiClient:
+        """
+        Support ``with ApiClient(...) as client`` in command handlers.
+        """
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """
+        Close the underlying ``httpx.Client`` on context exit.
+        """
+        self.close()
+
+    def close(self) -> None:
+        """
+        Close the underlying ``httpx.Client``.
+        """
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """
+        Issue an HTTP request and return the raw response.
+
+        Low-level escape hatch: most callers should use the typed
+        wrappers (:meth:`get`, :meth:`post`, ...). Non-2xx responses
+        still raise :class:`ApiRequestError` so callers never have to
+        inspect ``response.status_code`` themselves.
+        """
+        try:
+            response = self._client.request(
+                method=method,
+                url=path,
+                params=params,
+                json=json,
+                headers=headers,
+            )
+        except httpx.TransportError as exc:
+            raise ApiTransportError(f"could not reach {self._base_url}: {exc}") from exc
+        if response.status_code >= 400:
+            raise _extract_error(response)
+        return response
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """
+        Issue a GET request.
+        """
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """
+        Issue a POST request.
+        """
+        return self.request("POST", path, params=params, json=json, headers=headers)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """
+        Issue a PATCH request. Callers that need automatic ETag
+        round-tripping should use :meth:`patch_with_etag`.
+        """
+        return self.request("PATCH", path, json=json, headers=headers)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """
+        Issue a DELETE request. Callers that need automatic ETag
+        round-tripping should use :meth:`delete_with_etag`.
+        """
+        return self.request("DELETE", path, headers=headers)
+
+    def patch_with_etag(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+    ) -> httpx.Response:
+        """
+        PATCH ``path`` after fetching its current ETag via GET.
+
+        Convenience for the common CLI flow: fetch, mutate, send back.
+        If the server returns a 412 the caller gets the raw
+        :class:`ApiRequestError` so it can render a friendly
+        "version conflict" message.
+        """
+        etag = self._fetch_etag(path)
+        return self.patch(path, json=json, headers={"If-Match": etag})
+
+    def delete_with_etag(self, path: str) -> httpx.Response:
+        """
+        DELETE ``path`` after fetching its current ETag via GET.
+        """
+        etag = self._fetch_etag(path)
+        return self.delete(path, headers={"If-Match": etag})
+
+    def post_with_etag(
+        self,
+        entity_path: str,
+        action_path: str,
+        *,
+        json: Any | None = None,
+    ) -> httpx.Response:
+        """
+        POST to ``action_path`` after fetching the ETag of
+        ``entity_path``.
+
+        Used for the ``/epics/{id}/close`` and ``/stories/{id}/transition``
+        endpoints, which require ``If-Match`` but do not share a URL
+        with their parent entity.
+        """
+        etag = self._fetch_etag(entity_path)
+        return self.post(action_path, json=json, headers={"If-Match": etag})
+
+    def _fetch_etag(self, path: str) -> str:
+        """
+        GET ``path`` and return the ``ETag`` header value.
+
+        Raises :class:`ApiError` if the response did not include an
+        ETag header, which signals that the caller mixed up a
+        non-versioned resource (tags, linkages) with the versioned
+        helper.
+        """
+        response = self.get(path)
+        etag = response.headers.get("etag")
+        if etag is None:
+            raise ApiError(
+                f"response for {path} did not include an ETag header; "
+                "this resource does not support optimistic concurrency"
+            )
+        return str(etag)

kanbaroo_cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""
+Kanbaroo CLI command groups.
+
+Each module in this package implements one command or command group and
+is registered onto the root Typer app in :mod:`kanbaroo_cli.app`.
+"""

kanbaroo_cli/commands/audit.py

@@ -0,0 +1,123 @@
+"""
+Implementation of ``kb audit``.
+
+Calls the ``/audit/entity/{entity_type}/{id}`` endpoint per spec
+section 4.2. That endpoint is not yet implemented on the server as of
+this cage (the GET-audit router belongs to a later cage); when the
+server returns 404 the CLI prints a clear message rather than a
+traceback, so the contract is stable for callers even while the
+backend catches up.
+
+``kb audit`` accepts a human id (``KAN-123``) or a UUID. For human
+ids we try ``/stories/by-key`` first and fall back to
+``/epics/by-key``; that lets the same command serve either kind of
+entity without the user having to specify the type.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from kanbaroo_cli.client import ApiClient, ApiError, ApiRequestError
+from kanbaroo_cli.context import build_client, require_config
+from kanbaroo_cli.rendering import (
+    exit_on_api_error,
+    print_json,
+    print_table,
+)
+
+
+def _resolve_entity(client: ApiClient, ref: str) -> tuple[str, str, str]:
+    """
+    Resolve ``ref`` to a ``(entity_type, entity_id, human_id_or_ref)``
+    triple.
+
+    For a human id (``KAN-N``) this hits ``by-key`` on both stories
+    and epics; for a UUID it tries story-by-id then epic-by-id.
+    Raises :class:`ApiRequestError` with ``not_found`` when neither
+    lookup succeeds, so the CLI's error path is uniform.
+    """
+    if "-" in ref and ref.rsplit("-", 1)[-1].isdigit():
+        try:
+            body = client.get(f"/stories/by-key/{ref}").json()
+            return "story", str(body["id"]), str(body["human_id"])
+        except ApiRequestError as exc:
+            if exc.code != "not_found":
+                raise
+        try:
+            body = client.get(f"/epics/by-key/{ref}").json()
+            return "epic", str(body["id"]), str(body["human_id"])
+        except ApiRequestError as exc:
+            if exc.code != "not_found":
+                raise
+    else:
+        try:
+            body = client.get(f"/stories/{ref}").json()
+            return "story", str(body["id"]), str(body["human_id"])
+        except ApiRequestError as exc:
+            if exc.code != "not_found":
+                raise
+        try:
+            body = client.get(f"/epics/{ref}").json()
+            return "epic", str(body["id"]), str(body["human_id"])
+        except ApiRequestError as exc:
+            if exc.code != "not_found":
+                raise
+    raise ApiRequestError(
+        status_code=404,
+        code="not_found",
+        message=f"no story or epic matches {ref!r}",
+        details={"ref": ref},
+    )
+
+
+def audit_command(
+    ref: str = typer.Argument(
+        ...,
+        help="Story or epic handle (KAN-123) or UUID.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit JSON output instead of a Rich table.",
+    ),
+) -> None:
+    """
+    Show the audit history for a single story or epic.
+    """
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            entity_type, entity_id, human_id = _resolve_entity(client, ref)
+            response = client.get(f"/audit/entity/{entity_type}/{entity_id}")
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        payload: Any = response.json()
+
+    items: list[dict[str, Any]]
+    if isinstance(payload, dict) and "items" in payload:
+        items = list(payload["items"])
+    elif isinstance(payload, list):
+        items = list(payload)
+    else:
+        items = []
+
+    if as_json:
+        print_json(items)
+        return
+    rows = [
+        [
+            str(item.get("occurred_at", "")),
+            str(item.get("action", "")),
+            f"{item.get('actor_type', '')}/{item.get('actor_id', '')}",
+            str(item.get("id", "")),
+        ]
+        for item in items
+    ]
+    print_table(
+        columns=["occurred_at", "action", "actor", "event_id"],
+        rows=rows,
+        title=f"audit trail for {human_id}",
+    )

kanbaroo_cli/commands/backup.py

@@ -0,0 +1,78 @@
+"""
+Implementation of ``kb backup``.
+
+Local-only command: reads the configured SQLite file path from the
+CLI config (or ``$KANBAROO_DATABASE_URL``) and copies it to a
+timestamped path under ``--output`` (default ``~/.kanbaroo/backups``).
+Does not touch the running server: snapshotting a SQLite file while
+the writer is live is safe as long as readers see a consistent page
+view, and using the filesystem here lets the command work even when
+the server is offline.
+
+Any database URL that is not SQLite (i.e. Postgres in a later phase)
+causes the command to print a warning and exit with code 0. The
+contract is "SQLite only for now"; we do not want to silently imply a
+Postgres backup is happening.
+"""
+
+from __future__ import annotations
+
+import shutil
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+
+from kanbaroo_cli.config import default_config_dir
+from kanbaroo_cli.context import require_config
+from kanbaroo_cli.rendering import stderr_console, stdout_console
+
+SQLITE_PREFIXES: tuple[str, ...] = ("sqlite:///", "sqlite+pysqlite:///")
+
+
+def _sqlite_path_from_url(url: str) -> Path | None:
+    """
+    Return the file path embedded in a ``sqlite://`` URL, or ``None``
+    if the URL does not point at a SQLite file.
+
+    ``sqlite:///:memory:`` and other non-file forms return ``None``.
+    """
+    for prefix in SQLITE_PREFIXES:
+        if url.startswith(prefix):
+            raw = url[len(prefix) :]
+            if not raw or raw == ":memory:":
+                return None
+            return Path(raw)
+    return None
+
+
+def backup_command(
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        help="Directory to write the backup into. Default: ~/.kanbaroo/backups.",
+    ),
+) -> None:
+    """
+    Copy the configured SQLite database file to a timestamped path.
+    """
+    config = require_config()
+    assert config.database_url is not None  # require_config() guarantees this
+    src = _sqlite_path_from_url(config.database_url)
+    if src is None:
+        stderr_console.print(
+            "[yellow]Warning:[/yellow] database_url is not a SQLite file URL; "
+            "kb backup only supports SQLite in v1. Skipping."
+        )
+        raise typer.Exit(code=0)
+
+    if not src.exists():
+        stderr_console.print(f"[red]Error:[/red] database file {src} does not exist.")
+        raise typer.Exit(code=1)
+
+    dest_dir = output if output is not None else default_config_dir() / "backups"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
+    dest = dest_dir / f"kanbaroo-{timestamp}.db"
+    shutil.copy2(src, dest)
+    stdout_console.print(f"wrote [bold]{dest}[/bold].")