kanbaroo-cli 0.2.2__py3-none-any.whl

kanbaroo_cli/commands/tag.py

@@ -0,0 +1,252 @@
+"""
+Implementation of ``kb tag``.
+
+Tags are workspace-scoped and do not participate in optimistic
+concurrency, so rename and delete do not require ``If-Match``. The
+commands mirror the REST surface in ``kanbaroo_api.routers.tags``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from kanbaroo_cli.client import ApiError
+from kanbaroo_cli.context import build_client, require_config
+from kanbaroo_cli.rendering import (
+    exit_on_api_error,
+    print_json,
+    print_table,
+    stdout_console,
+)
+from kanbaroo_cli.resolvers import require_effective_workspace, resolve_workspace
+from kanbaroo_cli.similar import fetch_similar_entities, print_similar_entities
+
+app = typer.Typer(
+    name="tag",
+    help="Manage workspace-scoped tags.",
+    no_args_is_help=True,
+)
+
+
+def _swatch_markup(color: str | None) -> str:
+    """
+    Build a Rich-markup color swatch for the ``color`` column.
+
+    Renders a two-space background-coloured block followed by the hex
+    text so the listing shows both the swatch and the raw value. Tags
+    with no colour get a plain dash so the column never collapses to
+    an empty cell.
+    """
+    if not color:
+        return "-"
+    return f"[on {color}]  [/]  {color}"
+
+
+def _tag_row(item: dict[str, Any]) -> list[str]:
+    """
+    Format a single tag record into a :func:`print_table` row.
+
+    Soft-deleted rows dim the ``name`` cell so they are obviously
+    distinct from live tags when ``--include-deleted`` is active.
+    """
+    name = str(item["name"])
+    is_deleted = bool(item["deleted_at"])
+    name_cell = f"[dim]{name}[/dim]" if is_deleted else name
+    return [
+        name_cell,
+        _swatch_markup(item["color"]),
+        str(item["id"]),
+        "yes" if is_deleted else "no",
+    ]
+
+
+@app.command("list")
+def list_tags(
+    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 tags in the listing.",
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    """
+    List every tag in a workspace.
+
+    Soft-deleted tags are hidden by default. When any exist a short
+    hint points at ``--include-deleted`` so the CLI does not silently
+    omit them.
+    """
+    config = require_config()
+    workspace_ref = require_effective_workspace(workspace, config)
+    with build_client(config) as client:
+        try:
+            ws = resolve_workspace(client, workspace_ref)
+            # Always request the full set so we can count soft-deleted
+            # tags without a second round-trip. Tag volume per
+            # workspace is small (single-page), so the cost is nil.
+            response = client.get(
+                f"/workspaces/{ws['id']}/tags",
+                params={"include_deleted": True},
+            )
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        items = response.json()["items"]
+
+    deleted_items = [item for item in items if item["deleted_at"]]
+    displayed = (
+        items if include_deleted else [item for item in items if not item["deleted_at"]]
+    )
+
+    if as_json:
+        print_json(displayed)
+        return
+    rows = [_tag_row(item) for item in displayed]
+    print_table(
+        columns=["name", "color", "id", "deleted"],
+        rows=rows,
+        title=f"tags in {ws['key']}",
+    )
+    if not include_deleted and deleted_items:
+        count = len(deleted_items)
+        plural = "" if count == 1 else "s"
+        stdout_console.print(
+            f"[dim]Note: {count} soft-deleted tag{plural} not shown. "
+            "Use --include-deleted to see them.[/dim]"
+        )
+
+
+@app.command("create")
+def create_tag(
+    name: str = typer.Argument(..., help="Tag name."),
+    workspace: str | None = typer.Option(
+        None,
+        "--workspace",
+        help=(
+            "Workspace key or UUID. Falls back to $KANBAROO_WORKSPACE "
+            "and default_workspace from config."
+        ),
+    ),
+    color: str | None = typer.Option(
+        None,
+        "--color",
+        help="Optional hex color (e.g. #cc3333).",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Skip the duplicate-name prompt and create the tag regardless.",
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    """
+    Create a workspace-scoped tag.
+
+    Mirrors ``kb story create``: a normalised-name check runs first
+    so visually similar tags (``UI`` vs ``ui``) trigger an interactive
+    confirmation. ``--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, Any] = {"name": name}
+    if color is not None:
+        payload["color"] = color
+    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="tags",
+                field_name="name",
+                value=name,
+            )
+            if similar and not as_json and not force:
+                print_similar_entities(similar, label_key="name", entity="tag")
+                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']}/tags",
+                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
+    stdout_console.print(f"created tag [bold]{body['name']}[/bold] (id {body['id']})")
+
+
+@app.command("rename")
+def rename_tag(
+    tag_id: str = typer.Argument(..., help="Tag UUID."),
+    new_name: str = typer.Argument(..., help="New tag name."),
+    color: str | None = typer.Option(
+        None,
+        "--color",
+        help="Optionally recolor the tag at the same time.",
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    """
+    Rename and optionally recolor a tag.
+    """
+    config = require_config()
+    payload: dict[str, Any] = {"name": new_name}
+    if color is not None:
+        payload["color"] = color
+    with build_client(config) as client:
+        try:
+            response = client.patch(f"/tags/{tag_id}", json=payload)
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        body = response.json()
+
+    if as_json:
+        print_json(body)
+        return
+    stdout_console.print(f"renamed tag {tag_id} to [bold]{body['name']}[/bold]")
+
+
+@app.command("delete")
+def delete_tag(
+    tag_id: str = typer.Argument(..., help="Tag UUID."),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        help="Skip the confirmation prompt.",
+    ),
+) -> None:
+    """
+    Soft-delete a tag. Detaches the tag from every story that carried it.
+    """
+    if not yes:
+        confirmed = typer.confirm(f"Soft-delete tag {tag_id}?")
+        if not confirmed:
+            stdout_console.print("aborted.")
+            raise typer.Exit(code=0)
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            client.delete(f"/tags/{tag_id}")
+        except ApiError as exc:
+            exit_on_api_error(exc)
+
+    stdout_console.print(f"soft-deleted tag [bold]{tag_id}[/bold].")

kanbaroo_cli/commands/token.py

@@ -0,0 +1,150 @@
+"""
+Implementation of ``kb token``.
+
+Wraps the ``/tokens`` REST surface. The create endpoint returns the
+plaintext token exactly once; we surface it prominently and warn the
+user to save it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+
+from kanbaroo_cli.client import ApiError
+from kanbaroo_cli.context import build_client, require_config
+from kanbaroo_cli.rendering import (
+    exit_on_api_error,
+    print_json,
+    print_table,
+    stdout_console,
+)
+
+app = typer.Typer(
+    name="token",
+    help="Manage Kanbaroo API tokens.",
+    no_args_is_help=True,
+)
+
+
+@app.command("list")
+def list_tokens(
+    include_revoked: bool = typer.Option(
+        False,
+        "--include-revoked",
+        help="Include revoked tokens in the listing.",
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    """
+    List every API token. Plaintext is never returned; only the hash
+    prefix is surfaced so operators can identify tokens without seeing
+    secrets.
+    """
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            params: dict[str, Any] = {}
+            if include_revoked:
+                params["include_revoked"] = True
+            response = client.get("/tokens", params=params or None)
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        items = response.json()
+
+    if as_json:
+        print_json(items)
+        return
+    rows = [
+        [
+            str(item["id"]),
+            str(item["name"]),
+            f"{item['actor_type']}/{item['actor_id']}",
+            str(item["created_at"]),
+            "yes" if item["revoked_at"] else "no",
+        ]
+        for item in items
+    ]
+    print_table(
+        columns=["id", "name", "actor", "created_at", "revoked"],
+        rows=rows,
+        title="api tokens",
+    )
+
+
+@app.command("create")
+def create_token(
+    name: str = typer.Option(..., "--name", help="Human-readable token label."),
+    actor_type: str = typer.Option(
+        ...,
+        "--actor-type",
+        help="Actor type (human|claude|system).",
+    ),
+    actor_id: str = typer.Option(
+        ...,
+        "--actor-id",
+        help="Actor id (free-form label, e.g. 'outer-claude').",
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Emit JSON output."),
+) -> None:
+    """
+    Issue a new API token. The plaintext is returned exactly once;
+    save it before leaving this command.
+    """
+    config = require_config()
+    payload: dict[str, Any] = {
+        "name": name,
+        "actor_type": actor_type,
+        "actor_id": actor_id,
+    }
+    with build_client(config) as client:
+        try:
+            response = client.post("/tokens", json=payload)
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        body = response.json()
+
+    if as_json:
+        print_json(body)
+        return
+    stdout_console.print(
+        "[bold yellow]Save this token now. It will not be shown again.[/bold yellow]"
+    )
+    print_table(
+        columns=["field", "value"],
+        rows=[
+            ["plaintext", body["plaintext"]],
+            ["id", body["id"]],
+            ["name", body["name"]],
+            ["actor_type", body["actor_type"]],
+            ["actor_id", body["actor_id"]],
+        ],
+        title=f"created token {body['name']}",
+    )
+
+
+@app.command("revoke")
+def revoke_token(
+    token_id: str = typer.Argument(..., help="Token UUID."),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        help="Skip the confirmation prompt.",
+    ),
+) -> None:
+    """
+    Revoke a token. Idempotent against already-revoked rows.
+    """
+    if not yes:
+        confirmed = typer.confirm(f"Revoke token {token_id}?")
+        if not confirmed:
+            stdout_console.print("aborted.")
+            raise typer.Exit(code=0)
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            client.delete(f"/tokens/{token_id}")
+        except ApiError as exc:
+            exit_on_api_error(exc)
+    stdout_console.print(f"revoked token [bold]{token_id}[/bold].")

kanbaroo_cli/commands/workspace.py

@@ -0,0 +1,263 @@
+"""
+Implementation of ``kb workspace``.
+
+Wraps the workspace REST surface. ``show`` takes either a UUID or a
+short key (``KAN``) and falls back to a list scan when the first lookup
+returns 404, so the user can address workspaces the same way they do
+in the rest of the CLI.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from kanbaroo_cli.client import ApiError, ApiRequestError
+from kanbaroo_cli.config import write_default_workspace
+from kanbaroo_cli.context import build_client, require_config
+from kanbaroo_cli.rendering import (
+    exit_on_api_error,
+    print_json,
+    print_table,
+    stdout_console,
+)
+from kanbaroo_cli.resolvers import (
+    WORKSPACE_ENV_VAR,
+    WorkspaceSource,
+    effective_workspace,
+    resolve_workspace,
+)
+
+app = typer.Typer(
+    name="workspace",
+    help="Create, list, and inspect workspaces.",
+    no_args_is_help=True,
+)
+
+
+@app.command("list")
+def list_workspaces(
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit machine-readable JSON instead of a Rich table.",
+    ),
+    include_deleted: bool = typer.Option(
+        False,
+        "--include-deleted",
+        help="Include soft-deleted workspaces in the listing.",
+    ),
+) -> None:
+    """
+    List every workspace. Walks the paginated endpoint to collect the
+    entire set in one command.
+    """
+    config = require_config()
+    items: list[dict[str, object]] = []
+    cursor: str | None = None
+    with build_client(config) as client:
+        try:
+            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("/workspaces", 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
+
+    rows = [
+        [
+            str(item["key"]),
+            str(item["name"]),
+            str(item["id"]),
+            str(item["next_issue_num"]),
+            "yes" if item["deleted_at"] else "no",
+        ]
+        for item in items
+    ]
+    print_table(
+        columns=["key", "name", "id", "next_issue", "deleted"],
+        rows=rows,
+        title="workspaces",
+    )
+
+
+@app.command("create")
+def create_workspace(
+    key: str = typer.Option(..., "--key", help="Short prefix, e.g. KAN."),
+    name: str = typer.Option(..., "--name", help="Human-readable workspace name."),
+    description: str | None = typer.Option(
+        None,
+        "--description",
+        help="Optional markdown description.",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the created workspace as JSON instead of a Rich panel.",
+    ),
+) -> None:
+    """
+    Create a new workspace.
+    """
+    config = require_config()
+    payload: dict[str, object] = {"key": key, "name": name}
+    if description is not None:
+        payload["description"] = description
+    with build_client(config) as client:
+        try:
+            response = client.post("/workspaces", json=payload)
+        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=[
+            ["id", body["id"]],
+            ["key", body["key"]],
+            ["name", body["name"]],
+            ["description", body["description"] or ""],
+        ],
+        title=f"created workspace {body['key']}",
+    )
+
+
+@app.command("show")
+def show_workspace(
+    key_or_id: str = typer.Argument(..., help="Workspace key (KAN) or UUID."),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit the workspace body as JSON instead of a Rich table.",
+    ),
+) -> None:
+    """
+    Show a single workspace by its short key or UUID.
+    """
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            body = resolve_workspace(client, key_or_id)
+        except ApiRequestError as 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=[
+            ["id", body["id"]],
+            ["key", body["key"]],
+            ["name", body["name"]],
+            ["description", body["description"] or ""],
+            ["next_issue_num", str(body["next_issue_num"])],
+            ["version", str(body["version"])],
+            ["created_at", body["created_at"]],
+            ["updated_at", body["updated_at"]],
+            ["deleted_at", body["deleted_at"] or ""],
+        ],
+        title=f"workspace {body['key']}",
+    )
+
+
+@app.command("use")
+def use_workspace(
+    key: str = typer.Argument(..., help="Workspace key to set as the default."),
+) -> None:
+    """
+    Set the CLI's default workspace.
+
+    Validates the key against the live server, then writes
+    ``default_workspace`` into ``config.toml`` so subsequent commands
+    may omit ``--workspace``. The ``--workspace`` flag and
+    ``$KANBAROO_WORKSPACE`` still take precedence when set.
+    """
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            body = resolve_workspace(client, key)
+        except ApiRequestError as exc:
+            exit_on_api_error(exc)
+        except ApiError as exc:
+            exit_on_api_error(exc)
+
+    stored_key = str(body["key"])
+    write_default_workspace(config.config_path, stored_key)
+    stdout_console.print(
+        f"Default workspace set to [bold]{stored_key}[/bold]. "
+        "Commands will now default to this workspace unless "
+        f"[bold]--workspace[/bold] or [bold]${WORKSPACE_ENV_VAR}[/bold] is set."
+    )
+
+
+@app.command("delete")
+def delete_workspace(
+    key_or_id: str = typer.Argument(..., help="Workspace key (KAN) or UUID."),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        help="Skip the confirmation prompt.",
+    ),
+) -> None:
+    """
+    Soft-delete a workspace. Prompts for confirmation unless ``--yes``.
+    """
+    config = require_config()
+    with build_client(config) as client:
+        try:
+            workspace = resolve_workspace(client, key_or_id)
+        except ApiRequestError as exc:
+            exit_on_api_error(exc)
+        except ApiError as exc:
+            exit_on_api_error(exc)
+        if not yes:
+            confirmed = typer.confirm(
+                f"Soft-delete workspace {workspace['key']} ({workspace['name']!r})?"
+            )
+            if not confirmed:
+                stdout_console.print("aborted.")
+                raise typer.Exit(code=0)
+        try:
+            client.delete_with_etag(f"/workspaces/{workspace['id']}")
+        except ApiError as exc:
+            exit_on_api_error(exc)
+
+    stdout_console.print(f"soft-deleted [bold]{workspace['key']}[/bold].")
+
+
+@app.command("current")
+def current_workspace() -> None:
+    """
+    Show the effective default workspace and the source supplying it.
+
+    Applies the same resolution order as every command that accepts
+    ``--workspace`` (env > config). Reports ``unset`` when no source
+    supplies a value.
+    """
+    config = require_config()
+    value, source = effective_workspace(None, config)
+    if source == WorkspaceSource.UNSET:
+        stdout_console.print(
+            "[yellow]No default workspace configured.[/yellow] "
+            f"Set [bold]${WORKSPACE_ENV_VAR}[/bold] or run "
+            "[bold]kb workspace use KEY[/bold]."
+        )
+        return
+    stdout_console.print(f"[bold]{value}[/bold] (source: [cyan]{source}[/cyan])")