kanbaroo 0.2.2__py3-none-any.whl

kanbaroo/__init__.py

@@ -0,0 +1,18 @@
+"""
+Kanbaroo: a kanban-style issue tracker.
+
+This is the top-level meta-package. Install the optional ``all`` extra
+for everything::
+
+    pip install kanbaroo[all]
+
+Or install individual sub-packages directly::
+
+    pip install kanbaroo-core
+    pip install kanbaroo-api
+    pip install kanbaroo-tui
+    pip install kanbaroo-cli
+    pip install kanbaroo-mcp
+"""
+
+__version__ = "0.2.2"

kanbaroo-0.2.2.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: kanbaroo
+Version: 0.2.2
+Summary: A kanban-style issue tracker with TUI, REST + WebSocket API, CLI, and MCP server. Meta-package.
+Project-URL: Repository, https://github.com/areese801/kanbaroo
+Project-URL: Issues, https://github.com/areese801/kanbaroo/issues
+Author: Adam Reese
+License: MIT
+License-File: LICENSE
+Keywords: issue-tracker,kanban,mcp,tui
+Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: kanbaroo-api[web]; extra == 'all'
+Requires-Dist: kanbaroo-cli; extra == 'all'
+Requires-Dist: kanbaroo-core; extra == 'all'
+Requires-Dist: kanbaroo-mcp; extra == 'all'
+Requires-Dist: kanbaroo-tui; extra == 'all'
+Description-Content-Type: text/markdown
+
+# Kanbaroo
+
+A kanban-style issue tracker with a TUI, REST + WebSocket API, CLI, and MCP server. Designed to be useful standalone, and to integrate with [trusty-cage](https://pypi.org/project/trusty-cage/) for AI-driven workflows.
+
+**Status:** Phase 2 complete. Single-user, terminal + web + AI.
+
+## What it does
+
+Kanbaroo exposes the same data through five surfaces:
+
+- **TUI** (Textual) for terminal-centric humans: workspace list, kanban board, story detail, fuzzy search, audit feed.
+- **Web UI** (React SPA, served by the API at `/ui`): workspace list, kanban board with drag-to-transition, story detail, comments, tags, live WebSocket updates, keyboard shortcuts.
+- **CLI** (Typer + Rich): scriptable access to every resource, JSON output for pipelines.
+- **REST + WebSocket API** (FastAPI): the source of truth. WebSocket feeds live change events; REST is always authoritative.
+- **MCP server**: lets AI agents (outer Claude in particular) read and write the board through the Model Context Protocol.
+
+The data model is intentionally Jira-shaped but simpler. Workspaces contain optional Epics which contain Stories. Stories carry comments, tags, typed linkages, priority, and a standard kanban lifecycle. Every mutation is attributed to a `human`, `claude`, or `system` actor and recorded in an immutable audit log.
+
+## Architecture
+
+```mermaid
+flowchart TB
+    subgraph clients["Clients"]
+        TUI["TUI<br/>(Textual)"]
+        CLI["CLI<br/>(Typer + Rich)"]
+        MCP["MCP Server<br/>(mcp SDK)"]
+        WEB["Web UI<br/>(React SPA)"]
+    end
+
+    subgraph server["Kanbaroo Server"]
+        REST["FastAPI<br/>REST endpoints"]
+        WS["WebSocket<br/>event stream"]
+        CORE["kanbaroo-core<br/>(business logic)"]
+    end
+
+    subgraph storage["Storage"]
+        DB[("SQLite (local)<br/>Postgres (cloud)")]
+    end
+
+    subgraph external["External Consumers"]
+        DUCK["DuckDB / Snowflake<br/>(read-only)"]
+        GHA["GitHub Actions<br/>(read-only scripts)"]
+    end
+
+    TUI -->|HTTP + WS| REST
+    TUI -->|HTTP + WS| WS
+    CLI -->|HTTP| REST
+    MCP -->|HTTP| REST
+    WEB -->|HTTP + WS| REST
+
+    REST --> CORE
+    WS --> CORE
+    CORE --> DB
+
+    DB -.->|direct read| DUCK
+    DB -.->|direct read| GHA
+
+    style DUCK stroke-dasharray: 5 5
+    style GHA stroke-dasharray: 5 5
+```
+
+## Installation
+
+Requires Python 3.12 or newer.
+
+```bash
+# Everything (server + TUI + CLI + MCP)
+pip install 'kanbaroo[all]'
+
+# Or pick and choose:
+pip install kanbaroo-api          # Just the server (no web UI)
+pip install 'kanbaroo-api[web]'   # Server + bundled web UI at /ui
+pip install kanbaroo-cli          # CLI only (pulls in core)
+pip install kanbaroo-tui          # TUI only
+pip install kanbaroo-mcp          # MCP server only
+```
+
+Contributors working from a checkout should use the [uv](https://docs.astral.sh/uv/) workspace instead:
+
+```bash
+uv sync --all-packages --dev
+```
+
+## Quickstart
+
+For a human walking up cold, all the way from install to a running board:
+
+```bash
+# 1. Install
+pip install 'kanbaroo[all]'
+
+# 2. Initialise config dir, apply migrations, mint your first token
+kb init
+
+# 3. Start the server (docker compose under the hood)
+kb server start
+
+# 4. Create your first workspace
+kb workspace create --key KAN --name "My Work"
+
+# 5. File a story
+kb story create --workspace KAN --title "First task"
+
+# 6. In another terminal, open the TUI on the board
+kanbaroo-tui
+```
+
+Press `?` on any TUI screen for the keybinding cheatsheet. Press `/` from the workspace list or board for fuzzy search. `a` opens the global audit feed.
+
+## Configuration
+
+Kanbaroo reads settings from `$KANBAROO_CONFIG_DIR/config.toml` (default `~/.kanbaroo/config.toml`), which `kb init` creates for you. Environment variables override the TOML values when set.
+
+| Variable | Consumed by | Default / note |
+|----------|-------------|----------------|
+| `KANBAROO_DATABASE_URL` | core, api, `kb init`, `kb backup` | Required for the API to start. Docker supplies `sqlite:////data/kanbaroo.db` inside the container. |
+| `KANBAROO_API_URL` | cli, tui, mcp | Overrides `api_url` in `config.toml`. Example: `http://localhost:8080`. |
+| `KANBAROO_TOKEN` | cli, tui | Bearer token for API auth. Overrides `token` in `config.toml`. |
+| `KANBAROO_MCP_TOKEN` | mcp | MCP-specific token; falls back to `KANBAROO_TOKEN`. |
+| `KANBAROO_CONFIG_DIR` | cli, tui, mcp, `kb init` | Override for the config directory. Default: `~/.kanbaroo`. |
+| `KANBAROO_WORKSPACE` | cli | Default workspace key so you can omit `--workspace` on every command. Example: `KAN`. |
+| `KANBAROO_API_HOST` | api server | Uvicorn bind host. Default: `0.0.0.0`. |
+| `KANBAROO_API_PORT` | api server | Uvicorn bind port. Default: `8080`. |
+| `KANBAROO_COMPOSE_FILE` | `kb server` | Path to a non-default `docker-compose.yml` (useful for CI). |
+| `KANBAROO_MCP_LOG_LEVEL` | mcp | `INFO` by default; `DEBUG` for verbose MCP logs. |
+
+## Web UI
+
+The `kanbaroo-web` package ships a Vite + React SPA that `kanbaroo-api` serves at `/ui`. Once the API is running, visit `http://localhost:8080/ui` in a browser.
+
+### First-boot inside the container
+
+`kb server start` runs `docker compose up -d`; the API runs inside the `kanbaroo-api` container with its SQLite DB on a named volume. The volume is blank on first boot, so migrations and the initial token have to happen inside the container:
+
+```bash
+# Bring the stack up
+kb server start
+
+# Apply migrations
+docker compose exec -e KANBAROO_DATABASE_URL="sqlite:////data/kanbaroo.db" \
+  kanbaroo-api \
+  uv run --no-dev alembic -c /app/packages/kanbaroo-core/alembic.ini upgrade head
+
+# Mint the first token (print it once; save it)
+docker compose exec -e KANBAROO_DATABASE_URL="sqlite:////data/kanbaroo.db" \
+  kanbaroo-api \
+  uv run --no-dev kb init
+```
+
+Copy the `kbr_` token that `kb init` prints and paste it into the `/ui` login form. The token is stored in browser `localStorage` under `kanbaroo.token`; press "Log out" to clear it.
+
+You can also mint additional tokens later with `kb token create --actor-type human --actor-id you --name "web"` (inside the container, same `docker compose exec` wrapper).
+
+Shipped in v0.2.0:
+
+- Workspace list with inline create.
+- Kanban board with drag-to-transition, illegal-move rejection, optimistic updates.
+- Story detail: markdown description, metadata, comments (with one-level replies), tags, audit trail.
+- Live updates via the existing `/api/v1/events` WebSocket.
+- Story creation modal (`n` on the board).
+- In-board search (`/` on the board; matches on human id prefix and title substring).
+- Keyboard shortcuts: `n` new story, `/` search, `e` edit story, `?` shortcut help, `Escape` close modal / clear search / exit edit mode.
+
+The release wheel auto-includes the built bundle, so `pipx install --include-deps 'kanbaroo[all]'` picks up the UI. Node 20+ is only required at build time for maintainers publishing a new release.
+
+### Developing the web UI
+
+```bash
+make web-build   # Build the SPA into packages/kanbaroo-web/src/kanbaroo_web/dist/
+make web-dev     # Vite dev server on :5173, proxies /api and /api/v1/events to :8080
+make web-test    # vitest, single-shot
+```
+
+## MCP setup
+
+Let an AI agent drive Kanbaroo through the Model Context Protocol. The MCP server is a thin translator between the MCP tool protocol and the Kanbaroo REST API; every mutation routes through the API and is attributed to the MCP token's actor.
+
+First create a dedicated `claude`-typed token so AI mutations are audited correctly:
+
+```bash
+kb token create --actor-type claude --actor-id outer-claude --name "claude"
+```
+
+Copy the plaintext that `kb token create` prints into `KANBAROO_MCP_TOKEN` in your shell, then add this to Claude's `mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "kanbaroo": {
+      "command": "kanbaroo-mcp",
+      "args": ["--api-url", "http://localhost:8080", "--token-env", "KANBAROO_MCP_TOKEN"]
+    }
+  }
+}
+```
+
+See [`docs/mcp-setup.md`](docs/mcp-setup.md) for the full walkthrough, the smoke test, and the tool reference.
+
+## Docs
+
+- [`docs/spec.md`](docs/spec.md): authoritative design intent. Start here if you want the why.
+- [`docs/api-reference.md`](docs/api-reference.md): generated REST API reference.
+- [`docs/mcp-setup.md`](docs/mcp-setup.md): MCP setup guide for AI agents.
+- [`docs/future-skill-draft.md`](docs/future-skill-draft.md): draft workflow skill for AI agents using Kanbaroo via MCP.
+- [`CLAUDE.md`](CLAUDE.md): guidance for Claude Code when working in this repo.
+- [`CHANGELOG.md`](CHANGELOG.md): release notes.
+
+## Development
+
+This is a uv workspace monorepo with six packages in `packages/` (`kanbaroo-core`, `-api`, `-cli`, `-tui`, `-mcp`, `-web`) and a top-level meta-package with an `[all]` extra. Before committing anything:
+
+```bash
+uv run ruff format .
+uv run ruff check --fix .
+uv run mypy packages/
+uv run pytest
+```
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

kanbaroo-0.2.2.dist-info/RECORD

@@ -0,0 +1,5 @@
+kanbaroo/__init__.py,sha256=GYiopcWFA3mOYg5KviA1ufxRYa0sA4-ZSYzq6z5i08w,385
+kanbaroo-0.2.2.dist-info/METADATA,sha256=LoUpYtJG16ZJcFLUwp6MOXMR9VUXbep0O45SWbrq4EU,9568
+kanbaroo-0.2.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+kanbaroo-0.2.2.dist-info/licenses/LICENSE,sha256=D1Bibmq70Wc-4YvvSql38PWwyJP4gtAXrkNUfqjgRAk,1067
+kanbaroo-0.2.2.dist-info/RECORD,,

kanbaroo-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kanbaroo-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Reese
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.