kanbaroo-cli 0.2.2__py3-none-any.whl

kanbaroo_cli/commands/epic.py

@@ -0,0 +1,323 @@
+"""
+Implementation of ``kb epic``.
+
+Wraps ``/workspaces/{id}/epics`` and the epic id-addressed endpoints.
+``show``, ``close``, and ``reopen`` all accept a ``{KEY}-{N}`` handle
+and translate via ``GET /epics/by-key/{human_id}`` (added this cage)
+so the user never has to type a UUID.
+"""
+
+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,
+    stderr_console,
+    stdout_console,
+)
+from kanbaroo_cli.resolvers import (
+    require_effective_workspace,
+    resolve_epic,
+    resolve_workspace,
+    try_resolve_other,
+)
+from kanbaroo_cli.similar import fetch_similar_entities, print_similar_entities
+
+app = typer.Typer(
+    name="epic",
+    help="Create, list, and transition epics.",
+    no_args_is_help=True,
+)
+
+
+def _epic_rows(items: list[dict[str, object]]) -> list[list[str]]:
+    """
+    Format a list of epic bodies into table rows.
+    """
+    return [
+        [
+            str(item["human_id"]),
+            str(item["title"]),
+            str(item["state"]),
+            "yes" if item["deleted_at"] else "no",
+        ]
+        for item in items
+    ]
+
+
+@app.command("list")
+def list_epics(
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help=(
+            "Workspace key or UUID. Falls back to $KANBAROO_WORKSPACE "
+            "and default_workspace from config."
+        ),
+    ),
+    include_deleted: bool = typer.Option(
+        False,
+        "--include-deleted",
+        help="Include soft-deleted epics in the listing.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit machine-readable JSON instead of a Rich table.",
+    ),
+) -> None:
+    """
+    List every epic in a workspace.
+    """
+    config = require_config()
+    workspace_ref = require_effective_workspace(workspace, config)
+    items: list[dict[str, object]] = []
+    with build_client(config) as client:
+        try:
+            ws = resolve_workspace(client, workspace_ref)
+            cursor: str | None = None
+            while True:
+                params: dict[str, object] = {"limit": 200}
+                if include_deleted:
+                    params["include_deleted"] = True
+                if cursor is not None:
+                    params["cursor"] = cursor
+                response = client.get(
+                    f"/workspaces/{ws['id']}/epics",
+                    params=params,
+                )
+                body = response.json()
+                items.extend(body["items"])
+                cursor = body.get("next_cursor")
+                if cursor is None:
+                    break
+        except ApiError as exc:
+            exit_on_api_error(exc)
+
+    if as_json:
+        print_json(items)
+        return
+    print_table(
+        columns=["human_id", "title", "state", "deleted"],
+        rows=_epic_rows(items),
+        title=f"epics in {ws['key']}",
+    )
+
+
+@app.command("create")
+def create_epic(
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help=(
+            "Workspace key or UUID. Falls back to $KANBAROO_WORKSPACE "
+            "and default_workspace from config."
+        ),
+    ),
+    title: str = typer.Option(..., "--title", help="Epic title."),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="Optional markdown description.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Skip the duplicate-title prompt and create the epic regardless.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the created epic as JSON instead of a Rich table.",
+    ),
+) -> None:
+    """
+    Create a new epic in ``workspace``.
+
+    Mirrors ``kb story create``: a normalised-title check runs against
+    the workspace before posting and warns the user about likely
+    duplicates. ``--force`` skips the prompt; ``--json`` never prompts
+    but folds the matches into a ``warnings`` field.
+    """
+    config = require_config()
+    workspace_ref = require_effective_workspace(workspace, config)
+    payload: dict[str, object] = {"title": title}
+    if description is not None:
+        payload["description"] = description
+    similar: list[dict[str, Any]] = []
+    with build_client(config) as client:
+        try:
+            ws = resolve_workspace(client, workspace_ref)
+            similar = fetch_similar_entities(
+                client,
+                workspace_id=str(ws["id"]),
+                resource="epics",
+                field_name="title",
+                value=title,
+            )
+            if similar and not as_json and not force:
+                print_similar_entities(similar, label_key="human_id", entity="epic")
+                confirmed = typer.confirm("Create anyway?", default=False)
+                if not confirmed:
+                    stdout_console.print("aborted: existing entity has a similar name")
+                    raise typer.Exit(code=1)
+            response = client.post(
+                f"/workspaces/{ws['id']}/epics",
+                json=payload,
+            )
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        body = response.json()
+
+    if as_json:
+        if similar:
+            body = {**body, "warnings": {"similar": [s["id"] for s in similar]}}
+        print_json(body)
+        return
+    print_table(
+        columns=["field", "value"],
+        rows=[
+            ["human_id", body["human_id"]],
+            ["title", body["title"]],
+            ["state", body["state"]],
+            ["id", body["id"]],
+        ],
+        title=f"created epic {body['human_id']}",
+    )
+
+
+@app.command("show")
+def show_epic(
+    ref: str = typer.Argument(..., help="Epic handle (e.g. KAN-4) or UUID."),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the epic body as JSON instead of a Rich table.",
+    ),
+) -> None:
+    """
+    Show a single epic by its human id or UUID.
+
+    A 404 from the epic lookup falls through to a story lookup with
+    the same ref; if that hits, the user gets a hint to run
+    ``kb story show`` instead of a bare "not found" message.
+    """
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            body = resolve_epic(client, ref)
+        except ApiRequestError as exc:
+            if exc.status_code == 404:
+                _suggest_alternative(client, ref, missing="epic", alternative="story")
+                raise typer.Exit(code=1) from exc
+            exit_on_api_error(exc)
+        except ApiError as exc:
+            exit_on_api_error(exc)
+
+    if as_json:
+        print_json(body)
+        return
+    print_table(
+        columns=["field", "value"],
+        rows=[
+            ["human_id", body["human_id"]],
+            ["title", body["title"]],
+            ["state", body["state"]],
+            ["description", body["description"] or ""],
+            ["id", body["id"]],
+            ["version", str(body["version"])],
+            ["created_at", body["created_at"]],
+            ["updated_at", body["updated_at"]],
+            ["deleted_at", body["deleted_at"] or ""],
+        ],
+        title=f"epic {body['human_id']}",
+    )
+
+
+def _transition(ref: str, action: str, *, as_json: bool) -> None:
+    """
+    Shared implementation of ``close`` and ``reopen``.
+
+    Both endpoints require ``If-Match``; we fetch the epic first to
+    learn its current version and then POST to the action path.
+    """
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            epic = resolve_epic(client, ref)
+            response = client.post_with_etag(
+                f"/epics/{epic['id']}",
+                f"/epics/{epic['id']}/{action}",
+            )
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        body = response.json()
+
+    if as_json:
+        print_json(body)
+        return
+    print_table(
+        columns=["field", "value"],
+        rows=[
+            ["human_id", body["human_id"]],
+            ["title", body["title"]],
+            ["state", body["state"]],
+            ["version", str(body["version"])],
+        ],
+        title=f"{action}d epic {body['human_id']}",
+    )
+
+
+@app.command("close")
+def close_epic(
+    ref: str = typer.Argument(..., help="Epic handle (e.g. KAN-4) or UUID."),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    """
+    Close an epic.
+    """
+    _transition(ref, "close", as_json=as_json)
+
+
+@app.command("reopen")
+def reopen_epic(
+    ref: str = typer.Argument(..., help="Epic handle (e.g. KAN-4) or UUID."),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    """
+    Reopen a closed epic.
+    """
+    _transition(ref, "reopen", as_json=as_json)
+
+
+def _suggest_alternative(
+    client: ApiClient,
+    ref: str,
+    *,
+    missing: str,
+    alternative: str,
+) -> None:
+    """
+    Print a Rich error explaining that ``ref`` is the other entity type.
+
+    Mirrors the helper in ``kanbaroo_cli.commands.story`` so both
+    ``show`` commands offer the same "this looks like a story / epic"
+    hint when the user picks the wrong one.
+    """
+    stderr_console.print(
+        f"[red]Error (404 not_found):[/red] {missing} {ref!r} not found."
+    )
+    other = try_resolve_other(client, ref, other=alternative)
+    if other is None:
+        return
+    handle = other.get("human_id", ref)
+    stderr_console.print(
+        f"{handle} is a {alternative} - try `kb {alternative} show {handle}`."
+    )

kanbaroo_cli/commands/export.py

@@ -0,0 +1,81 @@
+"""
+Implementation of ``kb export``.
+
+Hits ``GET /api/v1/workspaces/{id}/export`` which is cage K's
+responsibility. The CLI-side implementation here is correct in its
+own right: resolve the workspace, stream the response body to
+``<output>/<workspace_key>-<timestamp>.tar.gz``, and surface clear
+errors when the endpoint is not yet available.
+
+Until the export endpoint lands the server returns 404 (or another
+canonical error envelope) and ``kb export`` prints a friendly
+``export endpoint not available yet`` message instead of a traceback.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from pathlib import Path
+
+import httpx
+import typer
+
+from kanbaroo_cli.client import ApiError, ApiRequestError, ApiTransportError
+from kanbaroo_cli.context import build_client, require_config
+from kanbaroo_cli.rendering import (
+    exit_on_api_error,
+    stderr_console,
+    stdout_console,
+)
+from kanbaroo_cli.resolvers import require_effective_workspace, resolve_workspace
+
+
+def export_command(
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help=(
+            "Workspace key or UUID. Falls back to $KANBAROO_WORKSPACE "
+            "and default_workspace from config."
+        ),
+    ),
+    output: Path = typer.Option(
+        ...,
+        "--output",
+        help="Directory to write the exported archive into.",
+    ),
+) -> None:
+    """
+    Download a workspace export archive into ``output``.
+    """
+    config = require_config()
+    workspace_ref = require_effective_workspace(workspace, config)
+    output.mkdir(parents=True, exist_ok=True)
+    with build_client(config) as client:
+        try:
+            ws = resolve_workspace(client, workspace_ref)
+        except ApiError as exc:
+            exit_on_api_error(exc)
+
+        timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
+        dest = output / f"{ws['key']}-{timestamp}.tar.gz"
+        try:
+            response = client.get(f"/workspaces/{ws['id']}/export")
+        except ApiRequestError as exc:
+            if exc.status_code == 404:
+                stderr_console.print(
+                    "[red]Error:[/red] export endpoint not available yet. "
+                    "This server does not expose /workspaces/{id}/export; "
+                    "the feature arrives in a later milestone."
+                )
+                raise typer.Exit(code=1) from exc
+            exit_on_api_error(exc)
+        except ApiTransportError as exc:
+            exit_on_api_error(exc)
+        except httpx.HTTPError as exc:
+            stderr_console.print(f"[red]Error:[/red] {exc}")
+            raise typer.Exit(code=1) from exc
+
+        dest.write_bytes(response.content)
+
+    stdout_console.print(f"wrote [bold]{dest}[/bold].")

kanbaroo_cli/commands/init.py

@@ -0,0 +1,160 @@
+"""
+Implementation of ``kb init``.
+
+Creates ``$KANBAROO_CONFIG_DIR`` (defaulting to ``~/.kanbaroo``), runs
+Alembic migrations to stand up the SQLite database, issues the first
+personal API token, writes ``config.toml``, and prints the plaintext
+token exactly once.
+
+The command is idempotent-adjacent: running it twice against an existing
+config.toml is an error unless ``--force`` is passed. ``--force`` issues
+a fresh token and rewrites the config but never revokes existing tokens
+in the database; the user is free to revoke old tokens later via
+``kb token`` (milestone 10).
+"""
+
+import os
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from sqlalchemy.orm import Session, sessionmaker
+
+from kanbaroo_core import ActorType
+from kanbaroo_core.auth import create_token
+from kanbaroo_core.db import engine_for_url
+from kanbaroo_core.migrations import upgrade_to_head
+
+console = Console()
+
+
+def _default_config_dir() -> Path:
+    """
+    Resolve the config directory from ``KANBAROO_CONFIG_DIR`` or fall
+    back to ``$HOME/.kanbaroo``.
+    """
+    override = os.environ.get("KANBAROO_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return Path.home() / ".kanbaroo"
+
+
+def _default_database_url(config_dir: Path) -> str:
+    """
+    Resolve the database URL from ``KANBAROO_DATABASE_URL`` or fall
+    back to a SQLite file inside ``config_dir``.
+    """
+    override = os.environ.get("KANBAROO_DATABASE_URL")
+    if override:
+        return override
+    return f"sqlite:///{config_dir / 'kanbaroo.db'}"
+
+
+def _default_actor_id() -> str:
+    """
+    Default the initial token's actor id to the OS user, or
+    ``"human"`` if ``$USER`` is not set (e.g. minimal containers).
+    """
+    return os.environ.get("USER") or "human"
+
+
+def _render_config_toml(*, database_url: str, api_url: str, token: str) -> str:
+    """
+    Render the on-disk ``config.toml`` contents.
+
+    Kept deliberately hand-crafted rather than pulling in a TOML writer:
+    the file has three scalar keys and the escaping surface is tiny
+    (double-quoted strings, backslash-escape internal quotes).
+    """
+
+    def _escape(value: str) -> str:
+        return value.replace("\\", "\\\\").replace('"', '\\"')
+
+    return (
+        f'database_url = "{_escape(database_url)}"\n'
+        f'api_url = "{_escape(api_url)}"\n'
+        f'token = "{_escape(token)}"\n'
+    )
+
+
+def init(
+    actor_id: str = typer.Option(
+        None,
+        "--actor-id",
+        help="Label stamped on mutations from this token. Defaults to $USER.",
+    ),
+    name: str = typer.Option(
+        "personal",
+        "--name",
+        help="Human-readable token name (shown in token lists).",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite an existing config.toml and issue a new token.",
+    ),
+) -> None:
+    """
+    Initialise Kanbaroo's local config, database, and first API token.
+    """
+    config_dir = _default_config_dir()
+    database_url = _default_database_url(config_dir)
+    resolved_actor_id = actor_id or _default_actor_id()
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_path = config_dir / "config.toml"
+
+    if config_path.exists() and not force:
+        console.print(
+            f"[red]Error:[/red] {config_path} already exists. "
+            "Re-run with [bold]--force[/bold] to overwrite the config "
+            "and issue a new token."
+        )
+        raise typer.Exit(code=1)
+
+    upgrade_to_head(database_url)
+
+    engine = engine_for_url(database_url)
+    factory = sessionmaker(bind=engine, expire_on_commit=False)
+    session: Session = factory()
+    try:
+        _, plaintext = create_token(
+            session,
+            actor_type=ActorType.HUMAN,
+            actor_id=resolved_actor_id,
+            name=name,
+        )
+        session.commit()
+    finally:
+        session.close()
+        engine.dispose()
+
+    api_url = "http://localhost:8080"
+    config_path.write_text(
+        _render_config_toml(
+            database_url=database_url,
+            api_url=api_url,
+            token=plaintext,
+        ),
+        encoding="utf-8",
+    )
+
+    warning = (
+        "[bold yellow]Save this token now. "
+        "It will not be shown again.[/bold yellow]\n\n"
+    )
+    body = (
+        f"[bold]Token:[/bold]        [green]{plaintext}[/green]\n"
+        f"[bold]Config path:[/bold]  {config_path}\n"
+        f"[bold]Database URL:[/bold] {database_url}\n"
+        f"[bold]Actor:[/bold]        human / {resolved_actor_id}\n"
+        f"[bold]Token name:[/bold]   {name}"
+    )
+    console.print(
+        Panel.fit(
+            warning + body,
+            title="Kanbaroo initialized",
+            border_style="green",
+        )
+    )

kanbaroo_cli/commands/server.py

@@ -0,0 +1,133 @@
+"""
+Implementation of ``kb server``.
+
+Thin wrappers around ``docker compose up -d`` and ``docker compose
+down``. ``--wait`` on ``start`` polls ``/api/v1/workspaces`` until the
+server responds or 30 seconds elapse.
+
+We shell out via :func:`subprocess.run` rather than importing a
+docker-compose Python binding because the binding surface is messy and
+users already have ``docker compose`` on PATH as the supported entry
+point per ``docker-compose.yml`` at the project root. When
+``$KANBAROO_COMPOSE_FILE`` is set we pass ``-f`` so the caller can
+target a non-default file (useful for CI).
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from typing import Any
+
+import httpx
+import typer
+
+from kanbaroo_cli.client import API_PREFIX
+from kanbaroo_cli.context import require_config_api_only
+from kanbaroo_cli.rendering import stderr_console, stdout_console
+
+app = typer.Typer(
+    name="server",
+    help="Start or stop the Kanbaroo API server via docker compose.",
+    no_args_is_help=True,
+)
+
+_READY_TIMEOUT_SECONDS = 30.0
+_READY_POLL_SECONDS = 0.5
+
+
+def _compose_command(subcommand: list[str]) -> list[str]:
+    """
+    Build the ``docker compose`` command line, injecting
+    ``-f $KANBAROO_COMPOSE_FILE`` when the override is set.
+    """
+    argv: list[str] = ["docker", "compose"]
+    compose_file = os.environ.get("KANBAROO_COMPOSE_FILE")
+    if compose_file:
+        argv.extend(["-f", compose_file])
+    argv.extend(subcommand)
+    return argv
+
+
+def _run_compose(subcommand: list[str]) -> None:
+    """
+    Invoke docker compose with the given subcommand and check the
+    result. Any non-zero exit propagates to the user.
+    """
+    subprocess.run(_compose_command(subcommand), check=True)
+
+
+def _poll_until_ready(
+    *,
+    base_url: str,
+    token: str,
+    timeout_seconds: float = _READY_TIMEOUT_SECONDS,
+) -> bool:
+    """
+    Poll ``GET {base_url}{API_PREFIX}/workspaces`` until it responds
+    with a 2xx or ``timeout_seconds`` elapses.
+
+    Returns ``True`` on success, ``False`` on timeout.
+    """
+    deadline = time.monotonic() + timeout_seconds
+    headers: dict[str, Any] = {"Authorization": f"Bearer {token}"}
+    url = f"{base_url.rstrip('/')}{API_PREFIX}/workspaces"
+    with httpx.Client(timeout=2.0) as probe:
+        while time.monotonic() < deadline:
+            try:
+                response = probe.get(url, headers=headers)
+                if 200 <= response.status_code < 300:
+                    return True
+            except httpx.HTTPError:
+                pass
+            time.sleep(_READY_POLL_SECONDS)
+    return False
+
+
+@app.command("start")
+def start_server(
+    wait: bool = typer.Option(
+        False,
+        "--wait",
+        help="Poll the API until it responds or 30 seconds elapse.",
+    ),
+) -> None:
+    """
+    Start the server (``docker compose up -d``).
+    """
+    try:
+        _run_compose(["up", "-d"])
+    except subprocess.CalledProcessError as exc:
+        stderr_console.print(
+            f"[red]Error:[/red] docker compose up failed (exit {exc.returncode})."
+        )
+        raise typer.Exit(code=exc.returncode) from exc
+
+    if wait:
+        config = require_config_api_only()
+        if not _poll_until_ready(
+            base_url=config.api_url,
+            token=config.token,
+        ):
+            stderr_console.print(
+                "[red]Error:[/red] server did not respond within 30 seconds."
+            )
+            raise typer.Exit(code=1)
+
+    stdout_console.print("server started.")
+
+
+@app.command("stop")
+def stop_server() -> None:
+    """
+    Stop the server (``docker compose down``).
+    """
+    try:
+        _run_compose(["down"])
+    except subprocess.CalledProcessError as exc:
+        stderr_console.print(
+            f"[red]Error:[/red] docker compose down failed (exit {exc.returncode})."
+        )
+        raise typer.Exit(code=exc.returncode) from exc
+    stdout_console.print("server stopped.")