kanbaroo-cli 0.2.2__py3-none-any.whl

kanbaroo_cli/config.py

@@ -0,0 +1,233 @@
+"""
+Config loader for the Kanbaroo CLI.
+
+Every command that talks to the server needs three things: an
+``api_url``, a ``token``, and (for ``kb backup``) a ``database_url``.
+All three are written to ``$KANBAROO_CONFIG_DIR/config.toml`` by
+``kb init``. This module provides a single :func:`load_config` entry
+point that reads that file, applies environment-variable overrides,
+and surfaces a dataclass the command handlers can consume without
+re-parsing TOML every time.
+
+If the config file is missing the loader raises
+:class:`ConfigNotFoundError`, which the CLI translates into a clean
+Rich-rendered message pointing the user at ``kb init``. We deliberately
+do not fall back to a partial config: if ``config.toml`` does not exist
+the user has not finished setup and we should say so loudly.
+"""
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+class ConfigError(Exception):
+    """
+    Base class for CLI configuration failures.
+    """
+
+
+class ConfigNotFoundError(ConfigError):
+    """
+    Raised when the expected ``config.toml`` does not exist.
+
+    The CLI translates this into a 1-exit with a Rich-rendered hint
+    pointing the user at ``kb init``.
+    """
+
+    def __init__(self, path: Path) -> None:
+        super().__init__(f"Kanbaroo config not found at {path}")
+        self.path = path
+
+
+class ConfigMalformedError(ConfigError):
+    """
+    Raised when ``config.toml`` is present but missing a required key or
+    contains a value of the wrong type.
+    """
+
+
+@dataclass(frozen=True)
+class CliConfig:
+    """
+    In-memory representation of the CLI's on-disk configuration.
+
+    ``database_url`` is needed by ``kb backup`` to locate the raw
+    SQLite file for a local snapshot; every other command only needs
+    ``api_url`` and ``token``. The field is typed ``str | None`` so the
+    API-only loader can skip the database-url validation and still
+    return a usable config (the HTTP-probe path in ``kb server start
+    --wait`` does not care where the database lives). Commands that
+    actually need the URL route through :func:`load_config`, which keeps
+    it mandatory.
+
+    ``default_workspace`` is the optional workspace key most
+    mutating/listing commands fall back to when neither ``--workspace``
+    nor ``$KANBAROO_WORKSPACE`` is set. It is written by
+    ``kb workspace use`` and may be absent in older configs.
+    """
+
+    api_url: str
+    token: str
+    database_url: str | None
+    config_path: Path
+    default_workspace: str | None = None
+
+
+def default_config_dir() -> Path:
+    """
+    Resolve the config directory from ``$KANBAROO_CONFIG_DIR`` or fall
+    back to ``$HOME/.kanbaroo``.
+
+    Mirrors the helper inside ``kb init`` so both commands share the
+    same resolution logic without leaking the init module's internals.
+    """
+    override = os.environ.get("KANBAROO_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return Path.home() / ".kanbaroo"
+
+
+def default_config_path() -> Path:
+    """
+    Resolve the canonical ``config.toml`` path.
+    """
+    return default_config_dir() / "config.toml"
+
+
+def load_config(
+    path: Path | None = None,
+    *,
+    require_database_url: bool = True,
+) -> CliConfig:
+    """
+    Read ``config.toml`` and return a :class:`CliConfig`.
+
+    ``$KANBAROO_API_URL``, ``$KANBAROO_TOKEN``, and
+    ``$KANBAROO_DATABASE_URL`` each override the matching TOML field
+    when set; this lets the test suite and CI pipelines drive the CLI
+    without touching a user's config.
+
+    ``api_url`` and ``token`` are always required.
+    ``require_database_url`` defaults to ``True``; pass ``False`` via
+    :func:`load_config_api_only` for commands that only hit the HTTP
+    API and never open the database directly (e.g.
+    ``kb server start --wait``).
+
+    TODO: broader CLI split needed between API-client commands (that
+    speak HTTP) and direct-DB-client commands (``kb backup``) so the
+    required-field set is implicit from the command rather than
+    manually wired per call site. Track alongside the API-client vs
+    direct-DB-client modes note in TODO.md.
+
+    Raises :class:`ConfigNotFoundError` when the file is absent and
+    :class:`ConfigMalformedError` when it is present but incomplete.
+    """
+    resolved_path = path or default_config_path()
+    if not resolved_path.exists():
+        raise ConfigNotFoundError(resolved_path)
+
+    with resolved_path.open("rb") as fh:
+        raw = tomllib.load(fh)
+
+    api_url = os.environ.get("KANBAROO_API_URL") or raw.get("api_url")
+    token = os.environ.get("KANBAROO_TOKEN") or raw.get("token")
+    database_url_raw = os.environ.get("KANBAROO_DATABASE_URL") or raw.get(
+        "database_url"
+    )
+    default_workspace_raw = raw.get("default_workspace")
+
+    missing: list[str] = []
+    if not isinstance(api_url, str) or not api_url:
+        missing.append("api_url")
+    if not isinstance(token, str) or not token:
+        missing.append("token")
+    if require_database_url and (
+        not isinstance(database_url_raw, str) or not database_url_raw
+    ):
+        missing.append("database_url")
+    if missing:
+        raise ConfigMalformedError(
+            f"config.toml at {resolved_path} is missing: {', '.join(missing)}"
+        )
+    if default_workspace_raw is not None and (
+        not isinstance(default_workspace_raw, str) or not default_workspace_raw
+    ):
+        raise ConfigMalformedError(
+            f"config.toml at {resolved_path} has an invalid default_workspace"
+        )
+
+    assert isinstance(api_url, str)
+    assert isinstance(token, str)
+    database_url: str | None = (
+        database_url_raw
+        if isinstance(database_url_raw, str) and database_url_raw
+        else None
+    )
+    default_workspace: str | None = (
+        default_workspace_raw if isinstance(default_workspace_raw, str) else None
+    )
+    return CliConfig(
+        api_url=api_url,
+        token=token,
+        database_url=database_url,
+        config_path=resolved_path,
+        default_workspace=default_workspace,
+    )
+
+
+def load_config_api_only(path: Path | None = None) -> CliConfig:
+    """
+    Like :func:`load_config` but does not require ``database_url``.
+
+    Used by commands that only need to talk to the running HTTP API
+    and never read the local database. ``database_url`` may be absent
+    from ``config.toml`` entirely; in that case the returned
+    ``CliConfig.database_url`` is ``None``.
+    """
+    return load_config(path, require_database_url=False)
+
+
+def _escape_toml(value: str) -> str:
+    """
+    Escape a string value for a TOML basic string literal.
+    """
+    return value.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def _render_config_toml(values: dict[str, Any]) -> str:
+    """
+    Render a minimal ``config.toml`` from a mapping of string scalars.
+
+    ``None`` values are omitted. Key order is preserved so rewrites do
+    not reshuffle the file unnecessarily.
+    """
+    lines: list[str] = []
+    for key, value in values.items():
+        if value is None:
+            continue
+        if not isinstance(value, str):
+            raise TypeError(f"config value for {key!r} must be str, got {type(value)}")
+        lines.append(f'{key} = "{_escape_toml(value)}"')
+    return "\n".join(lines) + "\n"
+
+
+def write_default_workspace(path: Path, workspace_key: str | None) -> None:
+    """
+    Rewrite ``config.toml`` at ``path`` to set ``default_workspace`` to
+    ``workspace_key`` (or remove it when ``None``).
+
+    Preserves every other key present in the file. Used by
+    ``kb workspace use``.
+    """
+    if not path.exists():
+        raise ConfigNotFoundError(path)
+    with path.open("rb") as fh:
+        raw = tomllib.load(fh)
+    if workspace_key is None:
+        raw.pop("default_workspace", None)
+    else:
+        raw["default_workspace"] = workspace_key
+    path.write_text(_render_config_toml(raw), encoding="utf-8")

kanbaroo_cli/context.py

@@ -0,0 +1,104 @@
+"""
+Per-command context helpers.
+
+Most command handlers load the CLI config and spin up an
+:class:`~kanbaroo_cli.client.ApiClient` in the same pattern. Centralising
+that pattern here keeps each command handler thin and makes it trivial
+to test: injecting a custom :class:`httpx.MockTransport` only happens in
+one place.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import typer
+from rich.console import Console
+
+from kanbaroo_cli.client import ApiClient
+from kanbaroo_cli.config import (
+    CliConfig,
+    ConfigMalformedError,
+    ConfigNotFoundError,
+    load_config,
+    load_config_api_only,
+)
+
+ClientFactory = Callable[[CliConfig], ApiClient]
+
+_stderr_console = Console(stderr=True)
+
+
+def require_config() -> CliConfig:
+    """
+    Load the CLI config or exit with a friendly error message.
+
+    Keeps every command from re-implementing the same error-render
+    plumbing.
+    """
+    try:
+        return load_config()
+    except ConfigNotFoundError as exc:
+        _stderr_console.print(
+            f"[red]Error:[/red] no Kanbaroo config at {exc.path}.\n"
+            "Run [bold]kb init[/bold] to create one."
+        )
+        raise typer.Exit(code=1) from exc
+    except ConfigMalformedError as exc:
+        _stderr_console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+
+def require_config_api_only() -> CliConfig:
+    """
+    Like :func:`require_config` but does not demand ``database_url``.
+
+    For commands that only hit the HTTP API (e.g.
+    ``kb server start --wait``). The returned
+    :class:`CliConfig.database_url` may be ``None``; the caller must
+    not dereference it.
+    """
+    try:
+        return load_config_api_only()
+    except ConfigNotFoundError as exc:
+        _stderr_console.print(
+            f"[red]Error:[/red] no Kanbaroo config at {exc.path}.\n"
+            "Run [bold]kb init[/bold] to create one."
+        )
+        raise typer.Exit(code=1) from exc
+    except ConfigMalformedError as exc:
+        _stderr_console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+
+def _default_client_factory(config: CliConfig) -> ApiClient:
+    """
+    Default implementation of :data:`_client_factory`: spin up a real
+    HTTP-backed client against the user's configured API URL.
+    """
+    return ApiClient(base_url=config.api_url, token=config.token)
+
+
+_client_factory: ClientFactory = _default_client_factory
+
+
+def build_client(config: CliConfig) -> ApiClient:
+    """
+    Build an :class:`ApiClient` wired to the loaded config.
+
+    Tests override this through :func:`set_client_factory` so they can
+    hand back a client pre-bound to an :class:`httpx.MockTransport`.
+    """
+    return _client_factory(config)
+
+
+def set_client_factory(factory: ClientFactory | None) -> None:
+    """
+    Override the client factory for the duration of a test.
+
+    Passing ``None`` restores the default (real-HTTP) factory. The
+    indirection is deliberate: patching the factory keeps the call
+    sites in the command handlers identical to the production path.
+    """
+    global _client_factory
+    _client_factory = factory or _default_client_factory

kanbaroo_cli/rendering.py

@@ -0,0 +1,83 @@
+"""
+Shared rendering helpers for CLI commands.
+
+Every list/show command supports ``--json`` for scripting and defaults
+to a Rich-rendered table. Keeping the two rendering paths in one place
+means individual commands only choose *what* to display, not *how*.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from kanbaroo_cli.client import ApiError, ApiRequestError
+
+stdout_console = Console()
+stderr_console = Console(stderr=True)
+
+
+def print_json(payload: Any) -> None:
+    """
+    Emit ``payload`` as compact JSON on stdout.
+
+    Uses :func:`json.dumps` directly (rather than Rich's
+    ``print_json``) so the output is deterministic and pipe-friendly.
+    """
+    stdout_console.print_json(_json.dumps(payload))
+
+
+def print_table(
+    *,
+    columns: list[str],
+    rows: list[list[str]],
+    title: str | None = None,
+) -> None:
+    """
+    Render a Rich table with the given columns and rows on stdout.
+
+    Empty ``rows`` renders the header with a single "(none)" cell so
+    the user never sees a blank box.
+    """
+    table = Table(title=title, show_lines=False)
+    for col in columns:
+        table.add_column(col)
+    if not rows:
+        table.add_row(*["(none)"] + [""] * (len(columns) - 1))
+    else:
+        for row in rows:
+            table.add_row(*row)
+    stdout_console.print(table)
+
+
+def render_api_error(exc: ApiError) -> None:
+    """
+    Print a friendly error message for an API failure on stderr.
+
+    Wraps both transport errors (server unreachable) and HTTP errors
+    (canonical envelope) so command handlers can call this once and
+    raise :class:`typer.Exit` immediately after.
+    """
+    if isinstance(exc, ApiRequestError):
+        stderr_console.print(
+            f"[red]Error ({exc.status_code} {exc.code}):[/red] {exc.message}"
+        )
+        if exc.details:
+            stderr_console.print(f"[dim]details:[/dim] {exc.details}")
+    else:
+        stderr_console.print(f"[red]Error:[/red] {exc}")
+
+
+def exit_on_api_error(exc: ApiError) -> None:
+    """
+    Render the error and raise :class:`typer.Exit` with code 1.
+
+    Used by every command handler so the exit-code contract is
+    identical across the CLI surface.
+    """
+    render_api_error(exc)
+    raise typer.Exit(code=1) from exc

kanbaroo_cli/resolvers.py

@@ -0,0 +1,185 @@
+"""
+ID-resolution helpers shared by commands.
+
+Stories and epics are addressed in the CLI by their ``{KEY}-{N}`` human
+identifiers (``KAN-123``); workspaces are addressed by their short key
+(``KAN``) or by UUID. The REST API serves by-key lookups for every
+entity directly so the CLI never has to walk the workspace list.
+
+Most commands that accept ``--workspace`` also support a default: when
+the flag is omitted, :func:`resolve_effective_workspace` falls back to
+``$KANBAROO_WORKSPACE`` and then to ``default_workspace`` from
+``config.toml`` before surfacing a friendly error.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import typer
+
+from kanbaroo_cli.client import ApiClient, ApiRequestError
+from kanbaroo_cli.config import CliConfig
+from kanbaroo_cli.rendering import stderr_console
+
+
+def _looks_like_human_id(candidate: str) -> bool:
+    """
+    Return True if ``candidate`` is shaped like ``{KEY}-{N}``.
+    """
+    if "-" not in candidate:
+        return False
+    head, tail = candidate.rsplit("-", 1)
+    return bool(head) and tail.isdigit()
+
+
+def resolve_workspace(client: ApiClient, key_or_id: str) -> dict[str, Any]:
+    """
+    Resolve a workspace by short key or UUID and return its full body.
+
+    Workspace keys do not contain dashes (the conventional ``KAN``/
+    ``DATA`` shape) whereas UUIDs do. Route any dashless reference
+    straight to ``GET /workspaces/by-key/{key}``. Otherwise try the
+    direct UUID endpoint first and fall back to the by-key endpoint for
+    the rare hyphenated-key case. A 404 from the final lookup surfaces
+    as :class:`ApiRequestError` with ``code="not_found"``.
+    """
+    if "-" not in key_or_id:
+        response = client.get(f"/workspaces/by-key/{key_or_id}")
+        body: dict[str, Any] = response.json()
+        return body
+
+    try:
+        response = client.get(f"/workspaces/{key_or_id}")
+    except ApiRequestError as exc:
+        if exc.code != "not_found":
+            raise
+    else:
+        direct: dict[str, Any] = response.json()
+        return direct
+
+    response = client.get(f"/workspaces/by-key/{key_or_id}")
+    fallback: dict[str, Any] = response.json()
+    return fallback
+
+
+WORKSPACE_ENV_VAR = "KANBAROO_WORKSPACE"
+
+
+class WorkspaceSource:
+    """
+    Labels for where an effective workspace came from.
+
+    Consumed by ``kb workspace current`` to tell the user which source
+    supplied the value.
+    """
+
+    FLAG = "flag"
+    ENV = "env"
+    CONFIG = "config"
+    UNSET = "unset"
+
+
+def effective_workspace(
+    workspace_arg: str | None,
+    config: CliConfig,
+) -> tuple[str | None, str]:
+    """
+    Resolve the effective ``--workspace`` value and its source.
+
+    Order, highest to lowest precedence:
+
+    1. ``workspace_arg`` (the explicit ``--workspace`` flag),
+    2. ``$KANBAROO_WORKSPACE`` environment variable,
+    3. ``default_workspace`` in ``config.toml``.
+
+    Returns ``(value, source)`` where ``value`` is ``None`` only when
+    none of the three supplied a non-empty string. Callers that need a
+    guaranteed value should use :func:`require_effective_workspace`.
+    """
+    if workspace_arg:
+        return workspace_arg, WorkspaceSource.FLAG
+    env_value = os.environ.get(WORKSPACE_ENV_VAR)
+    if env_value:
+        return env_value, WorkspaceSource.ENV
+    if config.default_workspace:
+        return config.default_workspace, WorkspaceSource.CONFIG
+    return None, WorkspaceSource.UNSET
+
+
+def require_effective_workspace(
+    workspace_arg: str | None,
+    config: CliConfig,
+) -> str:
+    """
+    Resolve the effective workspace, exiting with a friendly Rich
+    error when none of the three sources supplies one.
+
+    Keeps every command handler's call site to a single line while
+    still yielding the same ``exit 1`` / stderr-hint UX across the CLI.
+    """
+    value, _ = effective_workspace(workspace_arg, config)
+    if value is None:
+        stderr_console.print(
+            "[red]Error:[/red] no workspace specified. "
+            "Pass [bold]--workspace KEY[/bold], "
+            f"set [bold]${WORKSPACE_ENV_VAR}[/bold], or run "
+            "[bold]kb workspace use KEY[/bold]."
+        )
+        raise typer.Exit(code=1)
+    return value
+
+
+def resolve_story(client: ApiClient, ref: str) -> dict[str, Any]:
+    """
+    Resolve a story by ``{KEY}-{N}`` human id or by UUID.
+
+    Uses ``GET /stories/by-key/{ref}`` when ``ref`` matches the
+    human-id pattern, otherwise treats ``ref`` as a UUID and calls
+    ``GET /stories/{ref}``.
+    """
+    if _looks_like_human_id(ref):
+        response = client.get(f"/stories/by-key/{ref}")
+    else:
+        response = client.get(f"/stories/{ref}")
+    body: dict[str, Any] = response.json()
+    return body
+
+
+def resolve_epic(client: ApiClient, ref: str) -> dict[str, Any]:
+    """
+    Resolve an epic by ``{KEY}-{N}`` human id or by UUID.
+
+    Uses ``GET /epics/by-key/{ref}`` when ``ref`` matches the human-id
+    pattern, otherwise treats ``ref`` as a UUID and calls
+    ``GET /epics/{ref}``.
+    """
+    if _looks_like_human_id(ref):
+        response = client.get(f"/epics/by-key/{ref}")
+    else:
+        response = client.get(f"/epics/{ref}")
+    body: dict[str, Any] = response.json()
+    return body
+
+
+def try_resolve_other(
+    client: ApiClient,
+    ref: str,
+    *,
+    other: str,
+) -> dict[str, Any] | None:
+    """
+    Attempt to resolve ``ref`` as the other entity kind and return it.
+
+    ``other`` is either ``"story"`` or ``"epic"``. Used by ``kb story
+    show`` and ``kb epic show`` to turn a 404 into a helpful "this
+    looks like the other kind of entity" hint. Returns ``None`` when
+    the other lookup also misses so callers fall back to the plain
+    not-found message.
+    """
+    resolver = resolve_story if other == "story" else resolve_epic
+    try:
+        return resolver(client, ref)
+    except ApiRequestError:
+        return None

kanbaroo_cli/similar.py

@@ -0,0 +1,67 @@
+"""
+Shared helpers for the duplicate-title check used by ``kb story``,
+``kb epic``, and ``kb tag`` ``create`` commands.
+
+The wired flow is the same for every entity type: query the
+``similar`` endpoint with the proposed title (or name), and either
+prompt the user to abort, skip the prompt under ``--force``, or fold
+the matches into a ``warnings`` field for ``--json`` output. The
+shape of the entity differs (stories and epics carry ``human_id``;
+tags carry ``name``), so callers pick the label key they want
+displayed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kanbaroo_cli.client import ApiClient
+from kanbaroo_cli.rendering import stdout_console
+
+
+def fetch_similar_entities(
+    client: ApiClient,
+    *,
+    workspace_id: str,
+    resource: str,
+    field_name: str,
+    value: str,
+) -> list[dict[str, Any]]:
+    """
+    Call ``GET /workspaces/{id}/{resource}/similar?{field_name}=...``
+    and return the ``items`` list.
+
+    ``resource`` is the URL segment (``stories``, ``epics``,
+    ``tags``); ``field_name`` is the query-string key the endpoint
+    expects (``title`` for stories and epics, ``name`` for tags).
+    """
+    response = client.get(
+        f"/workspaces/{workspace_id}/{resource}/similar",
+        params={field_name: value},
+    )
+    body: dict[str, Any] = response.json()
+    items = body.get("items") or []
+    return [item for item in items if isinstance(item, dict)]
+
+
+def print_similar_entities(
+    items: list[dict[str, Any]],
+    *,
+    label_key: str,
+    entity: str,
+) -> None:
+    """
+    Render a short list of similar entities to stdout for the
+    interactive prompt.
+
+    ``label_key`` is the field rendered in the second column
+    (``human_id`` for stories and epics, ``name`` for tags). The
+    table is intentionally small; we want the user to see the
+    overlap, not browse a result set.
+    """
+    plural = entity if items and len(items) == 1 else f"{entity}s"
+    stdout_console.print(f"[yellow]Found {len(items)} similar {plural}:[/yellow]")
+    for item in items:
+        label = str(item.get(label_key, "?"))
+        title = str(item.get("title") or item.get("name") or "")
+        stdout_console.print(f"  - {label}  {title}")

kanbaroo_cli-0.2.2.dist-info/METADATA

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: kanbaroo-cli
+Version: 0.2.2
+Summary: Kanbaroo command-line interface
+Author: Adam Reese
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: kanbaroo-core
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# kanbaroo-cli
+
+Typer-based command-line interface for [Kanbaroo](https://github.com/areese801/kanbaroo), a kanban-style issue tracker. Provides the `kanbaroo` and `kb` console scripts for working with workspaces, epics, stories, comments, tags, linkages, tokens, audit trails, export, and backups from the shell.
+
+```bash
+pip install kanbaroo-cli
+kb init        # mint your first token
+kb --help
+```
+
+Full docs: [github.com/areese801/kanbaroo](https://github.com/areese801/kanbaroo).
+
+License: MIT.