kanbai 0.1.0__tar.gz

kanbai-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint (ruff)
+        run: uv run ruff check kanbai tests
+
+      - name: Type check (mypy)
+        run: uv run mypy
+
+      - name: Type check (ty)
+        run: uv run ty check
+
+      - name: Tests (pytest)
+        run: uv run pytest

kanbai-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+# Publish to PyPI when a version tag is pushed, e.g. `git tag v0.1.0 && git push --tags`.
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify the tag matches the package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION="$(grep -m1 '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')"
+          echo "tag=$TAG  pyproject=$VERSION"
+          test "$TAG" = "$VERSION"
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kanbai
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kanbai-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Environment and IDE
+.venv/
+.env
+.vscode/
+.claude/
+.cursor/
+.codex/
+.mcp.json
+
+# Cache
+.mypy_cache
+.pytest_cache
+.ruff_cache
+
+# Build and Compiled
+dist/
+_build/
+*.pyc
+.DS_Store
+
+# Test Coverage
+.coverage
+htmlcov/
+coverage.xml
+
+# KanbAI
+.kanbai
+
+# Local work
+tmp/
+scratchworks/
+scratchwork.py
+.python-version
+*.local.*
+ISSUES.md

kanbai-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-23
+
+Initial release: a file-based Kanban board for Claude Code and other AI coding harnesses.
+
+### Added
+
+- **Board storage** — one Markdown card per file with YAML frontmatter, organized in
+  per-column folders under `.kanbai/`. Atomic writes; the folder is the source of truth
+  for a card's column.
+- **Sprint workflow columns** — `backlog → todo → doing → review → done`. `kanbai next`
+  reads the sprint (`todo`) and respects card order and blocking dependencies.
+- **CLI** (`kanbai`): `init`, `add`, `list`, `next`, `show`, `move`, `start`, `review`,
+  `done`, `edit`, `archive`, `rm`, `new-sprint`, and `ui`. Read commands support `--json`.
+- **`kanbai init`** — scaffolds `.kanbai/` and the Claude Code integration (`.claude/rules`
+  + skills `kanbai-next` / `kanbai-sprint` / `kanbai-status`). Idempotent and degrades
+  gracefully when integration files can't be written.
+- **Review flow** — finished cards go to `review` via `kanbai review`; the user approves
+  them to `done` with `kanbai done`.
+- **Web UI** (`kanbai ui`, FastAPI + HTMX, assets vendored for offline use):
+  - Board view; create cards; move cards by drag-and-drop (with persisted reordering) or
+    from the card detail modal.
+  - Card detail, edit, archive, and delete modals.
+  - "Plan sprint" and "New sprint" modals; text search and label filtering.
+  - Live updates via Server-Sent Events; WIP-limit and blocked-by-dependency indicators.
+  - Logo and favicon; `--reload` development mode; `--poll` for sandboxes/containers.
+- **WIP limits** — optional `[wip]` config per column; the CLI and UI warn (never block)
+  when a column is over its limit.
+- **`new-sprint`** — archives `done` cards (recording each card's origin column in
+  `archived_from`) and optionally moves the active columns back to the backlog.
+
+### Packaging
+
+- Packaged with hatchling; `kanbai` console entry point. Optional `ui` extra
+  (fastapi, uvicorn, jinja2, watchfiles, python-multipart). MIT licensed.
+
+[Unreleased]: https://github.com/rennan-cockles/kanbai/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rennan-cockles/kanbai/releases/tag/v0.1.0

kanbai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rennan Cockles
+
+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.

kanbai-0.1.0/Makefile

@@ -0,0 +1,134 @@
+.PHONY: help start install pre-commit lint-fix lint ruff mypy ty ruff-check format-check ruff-fix fmt pre-commit-sim type-check test test-unit test-ci pre-commit-run dev release-dry release release-info tag-release inspect-release publish-docs docs env-check mcp-run mcp-inspector
+.DEFAULT_GOAL := help
+# .ONESHELL:
+
+# Load .env (if present) and export its vars to all recipe subprocesses.
+# Optional so targets still work without a .env file.
+-include .env
+export
+
+# Variables
+PROJECT_NAME=KanbAI
+ENV_PREFIX=$(shell python -c "if __import__('pathlib').Path('.venv/bin/pip').exists(): print('.venv/bin/')")
+# Parallel pytest workers (pytest-xdist); use -n0 to disable (e.g. test-watch)
+PYTEST_PARALLEL ?= -n auto
+
+# Colors for output
+BOLD := \033[1m
+RED := \033[31m
+GREEN := \033[32m
+YELLOW := \033[33m
+BLUE := \033[34m
+RESET := \033[0m
+
+help: ## Show this help message
+	@echo "$(BOLD)$(PROJECT_NAME) Development Commands$(RESET)"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "$(BLUE)%-20s$(RESET) %s\n", $$1, $$2}'
+	@echo ""
+	@echo "$(YELLOW)Main Commands:$(RESET)"
+	@echo "  $(GREEN)make start$(RESET)       - Start API, wait for health, setup pre-commit, run CLI"
+	@echo "  $(GREEN)make lint$(RESET)        - Run all linting and formatting checks"
+	@echo "  $(GREEN)make test$(RESET)        - Run all tests with coverage"
+	@echo ""
+	@echo "$(YELLOW)Development Workflow:$(RESET)"
+	@echo "  1. $(GREEN)make lint-fix$(RESET) - Fix code issues before staging"
+	@echo "  2. $(GREEN)git add .$(RESET)     - Stage your changes"
+	@echo "  3. $(GREEN)git commit$(RESET)    - Commit (pre-commit hooks will run)"
+
+start: install pre-commit ## Start local environment
+
+install: ## Install project dev dependencies
+	@echo "$(YELLOW)Installing dev dependencies with Poetry...$(RESET)"
+	@poetry install --with dev --all-extras
+	@echo "$(GREEN)✓ Dev dependencies installed$(RESET)"
+
+pre-commit: ## Install and configure pre-commit hooks
+	@echo "$(YELLOW)Setting up pre-commit hooks...$(RESET)"
+	@poetry run pre-commit install
+	@echo "$(GREEN)✓ Pre-commit hooks configured$(RESET)"
+
+
+# Development and Quality Commands
+# Note: The order of lint operations matches pre-commit hooks for consistency:
+lint-fix: fmt ruff-fix ruff-check format-check type-check ## Run all linting and formatting checks
+lint: ruff-check format-check type-check ## Run all linting and formatting checks
+ruff: ruff-check format-check ## Run Ruff linting and formatting checks
+type-check: mypy ty ## Run MyPy and Ty type checks
+
+ruff-check: ## Run Ruff linting
+	@echo "$(YELLOW)Running Ruff linting...$(RESET)"
+	@poetry run ruff check .
+
+format-check: ## Check code formatting without making changes
+	@echo "$(YELLOW)Checking code formatting...$(RESET)"
+	@poetry run ruff format . --check
+
+ruff-fix: ## Run Ruff linting with auto-fix (matches pre-commit behavior)
+	@echo "$(YELLOW)Running Ruff linting with auto-fix...$(RESET)"
+	@poetry run ruff check . --fix || true
+
+fmt: ## Run code formatting
+	@echo "$(YELLOW)Running code formatting...$(RESET)"
+	@poetry run ruff format .
+
+pre-commit-sim: ## Simulate pre-commit hooks exactly (for troubleshooting)
+	@echo "$(YELLOW)Simulating pre-commit hooks...$(RESET)"
+	@poetry run ruff check . --fix --exit-non-zero-on-fix || echo "Ruff applied fixes"
+	@poetry run ruff format .
+
+mypy: ## Run MyPy type checking
+	@echo "$(YELLOW)Running MyPy type checking...$(RESET)"
+	@poetry run mypy
+
+ty: ## Run Ty type checking
+	@echo "$(YELLOW)Running Ty check...$(RESET)"
+	@poetry run ty check
+
+test: ## Run all tests with coverage (parallel via pytest-xdist)
+	@echo "$(YELLOW)Running all tests with coverage...$(RESET)"
+	@poetry run pytest $(PYTEST_PARALLEL) --cov --cov-report=term-missing:skip-covered --cov-report=html
+
+test-unit: ## Run all unit tests with coverage (parallel via pytest-xdist)
+	@echo "$(YELLOW)Running unit tests with coverage...$(RESET)"
+	@poetry run pytest $(PYTEST_PARALLEL) --cov --cov-report=term-missing:skip-covered --cov-report=html -m "unit"
+
+# Jenkins CI/CD specific test targets with XML output
+test-ci: ## Run all tests with CI-friendly output (JUnit XML + Coverage XML)
+	@echo "$(YELLOW)Running tests with CI-friendly output...$(RESET)"
+	@poetry run pytest $(PYTEST_PARALLEL) --cov --cov-report=term-missing --cov-report=html --cov-report=xml:coverage.xml --cov-fail-under=75 --junitxml=test-results.xml -m "not integration"
+
+# Security and Quality Assurance
+security-scan: ## Run security scans
+	@echo "$(YELLOW)Running security scans...$(RESET)"
+	@poetry run gitleaks dir -v .
+
+pre-commit-run: ## Run pre-commit on all files
+	@echo "$(YELLOW)Running pre-commit on all files...$(RESET)"
+	@poetry run pre-commit run --all-files
+
+# Development shortcuts
+dev: start ## Alias for start command
+
+# Release and versioning
+release-dry: ## Dry run semantic release
+	@echo "$(YELLOW)Running semantic release dry run...$(RESET)"
+	@poetry run semantic-release version --print
+
+release: ## Create a new release
+	@echo "$(YELLOW)Creating new release...$(RESET)"
+	@poetry run semantic-release version
+
+# Environment management
+env-check: ## Check environment setup
+	@echo "$(YELLOW)Checking environment setup...$(RESET)"
+	@echo "$(BLUE)Python version:$(RESET) $$(python --version 2>/dev/null || echo 'Not found')"
+	@echo "$(BLUE)Poetry version:$(RESET) $$(poetry --version 2>/dev/null || echo 'Not found')"
+	@echo "$(BLUE)Docker version:$(RESET) $$(docker --version 2>/dev/null || echo 'Not found')"
+	@echo "$(BLUE)Docker Compose version:$(RESET) $$(docker compose version 2>/dev/null || echo 'Not found')"
+	@echo "$(BLUE)Pre-commit installed:$(RESET) $$(poetry run pre-commit --version 2>/dev/null || echo 'Not found')"
+	@if [ -f .env ]; then \
+		echo "$(GREEN)✓ .env file exists$(RESET)"; \
+	else \
+		echo "$(YELLOW)⚠ .env file not found - copy from .env.example$(RESET)"; \
+	fi

kanbai-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: kanbai
+Version: 0.1.0
+Summary: A file-based Kanban board for Claude Code and other AI coding harnesses
+Author-email: Rennan Cockles <rennan.cockles@experian.com>
+License: MIT License
+        
+        Copyright (c) 2026 Rennan Cockles
+        
+        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.
+License-File: LICENSE
+Keywords: agent,ai,claude,claude-code,kanban,task-management
+Requires-Python: >=3.10
+Requires-Dist: httpx2>=2.13
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.12
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.110; extra == 'ui'
+Requires-Dist: jinja2>=3.1; extra == 'ui'
+Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'ui'
+Requires-Dist: watchfiles>=0.21; extra == 'ui'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.png" alt="KanbAI" width="650">
+</p>
+
+# KanbAI
+
+A file-based Kanban board that lives in your repo, built for **Claude Code** and other AI
+coding harnesses (and humans too). The board is plain Markdown files under `.kanbai/`,
+driven by a simple `kanbai` CLI and a local web UI. Installed and invoked as `kanbai`.
+
+<p align="center">
+  <img src="assets/webui.png" alt="KanbAI web UI" width="840">
+</p>
+
+## Why
+
+- **The board lives in your repo.** One Markdown card per task, one folder per column —
+  git-friendly, diffable, no external service, no database.
+- **Claude drives it.** `kanbai init` installs a rule + skills so Claude picks the next
+  task, implements it, and moves it across the board while you review.
+- **You stay in control.** Finished work waits in `review` for your approval, and a
+  friendly local web UI lets you watch and manage everything live.
+
+## How it works
+
+`kanbai init` creates a `.kanbai/` folder — one directory per column, one Markdown card
+per task:
+
+```
+.kanbai/
+├── config.toml
+├── backlog/
+│   └── 004-add-oauth-login.md
+├── todo/
+├── doing/
+├── review/
+├── done/
+└── archive/
+```
+
+Each card is Markdown with YAML frontmatter (managed by the CLI — don't edit by hand):
+
+```markdown
+---
+id: "004"
+title: Add OAuth login
+status: backlog
+priority: high
+order: 1
+labels: [auth, backend]
+deps: []
+---
+
+## Description
+Support "Sign in with Google".
+
+## Acceptance criteria
+- [ ] OAuth flow works end to end
+```
+
+### The sprint workflow
+
+Cards flow through five columns:
+
+| Column | Meaning |
+|--------|---------|
+| `backlog` | Everything to do eventually. New cards land here. |
+| `todo` | The current sprint — what's planned for now. |
+| `doing` | In progress. |
+| `review` | Finished, awaiting your approval. |
+| `done` | Approved and complete. |
+
+`kanbai next` only reads the **sprint** (`todo`), respecting card order and blocking
+dependencies — so the backlog stays out of the way until you plan work into the sprint.
+When work is finished it goes to `review`; **you** approve it into `done`.
+
+## Install
+
+```bash
+uv add --dev kanbai          # add to your project as a dev dependency
+# or
+pip install kanbai
+
+# for the web UI, install the extra:
+uv add --dev 'kanbai[ui]'    # or: pip install 'kanbai[ui]'
+```
+
+## Quick start
+
+```bash
+kanbai init                              # scaffold .kanbai/ + Claude integration
+kanbai add "Build the login screen" -p high   # lands in the backlog
+kanbai move 001 todo                     # plan it into the sprint
+kanbai list                              # show the board
+```
+
+Then open a Claude Code session and ask it to *"work through the KanbAI board"*.
+
+## Working with Claude Code
+
+`kanbai init` installs the integration into `.claude/`:
+
+- **`.claude/rules/kanbai.md`** — teaches Claude the board convention, loaded every session.
+- **Skills** — `kanbai-next` (work one card and stop), `kanbai-sprint` (work the whole
+  sprint), and `kanbai-status` (summarize the board).
+
+Claude then works one card at a time:
+
+1. `kanbai next --json` — pick the next actionable sprint task.
+2. `kanbai start <id>` — move it to `doing`.
+3. Implement it (reading `kanbai show <id> --json` for the details).
+4. `kanbai review <id>` — send it to `review` and **stop**.
+5. You review the work and approve it with `kanbai done <id>`.
+
+Allow the CLI without prompts by adding `Bash(kanbai *)` to your `.claude/settings.json`.
+
+Using another assistant (Cursor, Windsurf, Aider, Copilot, …)? The board is harness-agnostic
+— see [docs/other-harnesses.md](docs/other-harnesses.md).
+
+## Web UI
+
+```bash
+kanbai ui                    # serves the board and opens your browser
+kanbai ui --reload           # auto-restart on code changes (development)
+kanbai ui --poll             # for sandboxes/containers without OS file events
+```
+
+The UI (FastAPI + HTMX, assets vendored so it works offline) lets you:
+
+- View the board and **create, edit, move, archive, or delete** cards.
+- **Drag-and-drop** between columns (with persisted reordering) or move from a card's modal.
+- **Plan a sprint** (move several backlog cards to `todo` at once) and **start a new sprint**
+  (archive done cards, optionally reset the active columns).
+- **Search** cards and **filter by label**.
+- Browse and **restore** archived cards.
+- See **WIP-limit** and **blocked-by-dependency** indicators, and **live updates** as Claude
+  moves cards from the CLI (via Server-Sent Events).
+
+## Configuration
+
+`.kanbai/config.toml` is created by `init` and can be edited:
+
+```toml
+[board]
+name = "my-project"
+columns = ["backlog", "todo", "doing", "review", "done"]
+
+[defaults]
+priority = "medium"
+
+# Optional work-in-progress limits per column (the CLI and UI warn when exceeded).
+[wip]
+doing = 3
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `kanbai init` | Scaffold `.kanbai/` and install the Claude Code integration. |
+| `kanbai add "title"` | Create a card in `backlog` (use `-c todo` for the sprint). |
+| `kanbai list [column]` | Show the board, a single column, or the `archive`. |
+| `kanbai next` | Print the next actionable card in the sprint (`todo`). |
+| `kanbai show <id>` | Show full details of a card. |
+| `kanbai move <id> <column>` | Move a card to a column. |
+| `kanbai start <id>` | Move a card to `doing`. |
+| `kanbai review <id>` / `kanbai done <id>` | Send a card to `review` / approve it to `done`. |
+| `kanbai edit <id>` | Update fields of a card. |
+| `kanbai archive <id>` / `kanbai restore <id>` | Archive a card / restore it from the archive. |
+| `kanbai rm <id>` | Delete a card permanently. |
+| `kanbai new-sprint` | Archive done cards (optionally reset active columns to the backlog). |
+| `kanbai ui` | Serve the board in a local web UI (needs the `ui` extra). |
+
+Add `--json` to read-only commands for machine-readable output.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT