pyproject.toml

[project]
name = "kagan"
version = "0.17.0"
description = "AI-powered Kanban TUI for autonomous development workflows"
license = "MIT"
authors = [
  { name = "Altynbek Orumbayev", email = "altynbek.orumbayev@makerx.com.au" },
]
keywords = [
  "kanban",
  "tui",
  "terminal",
  "ai",
  "textual",
  "project-management",
  "autonomous",
]
classifiers = [
  "Development Status :: 4 - Beta",
  "Environment :: Console",
  "Intended Audience :: Developers",
  "License :: OSI Approved :: MIT License",
  "Operating System :: OS Independent",
  "Programming Language :: Python :: 3",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Topic :: Software Development",
  "Topic :: Software Development :: Libraries :: Python Modules",
  "Topic :: Terminals",
  "Topic :: Utilities",
  "Typing :: Typed",
]
requires-python = ">=3.12,<3.15"
readme = "README.md"
dependencies = [
  "agent-client-protocol>=0.8.0,<1.0.0",
  "alembic>=1.16.0",
  "click>=8.1.0",
  "cryptography>=46.0",
  # Pinned explicitly despite being a transitive dep of mcp - prevents pre-release breakage (see v0.14.1)
  "httpx>=0.27.0,<1.0.0",
  "loguru>=0.7.0",
  "mcp>=1.26.0,<2.0.0",
  "mslex>=1.3.0",
  "packaging>=24.0",
  "pathspec>=0.12.0",
  "platformdirs>=4.3.0",
  "pydantic>=2.0.0",
  "prompt-toolkit>=3.0.0",
  "qrcode>=8.2",
  "rich>=14.0.0",
  # Explicit dependency - imported directly in 11+ files, not just via sqlmodel
  "sqlalchemy>=2.0.0",
  "sqlmodel>=0.0.22",
  "textual>=7.0.0,<8.0.0",
  "tomlkit>=0.13.0",
  "uvicorn>=0.34.0",
  "websockets>=15.0",
]

[project.scripts]
kagan = "kagan.cli:cli"
kg = "kagan.cli:cli"

[project.entry-points."kagan.plugins"]
github = "kagan.core.plugins._github:GitHubImporter"

[project.urls]
Homepage = "https://kagan.sh"
Documentation = "https://docs.kagan.sh"
Repository = "https://github.com/kagan-sh/kagan"
Issues = "https://github.com/kagan-sh/kagan/issues"
Changelog = "https://github.com/kagan-sh/kagan/blob/main/CHANGELOG.md"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/kagan"]
exclude = ["src/kagan/server/_web_static/**"]

[tool.hatch.build.targets.wheel.force-include]
"src/kagan/server/_web_static" = "kagan/server/_web_static"
[dependency-groups]
dev = [
  "poethepoet>=0.40.0",
  "pre-commit>=4.5.1",
  "pytest>=9.0.2",
  "pytest-asyncio>=1.3.0",
  "ruff>=0.14.14",
  "pyrefly>=0.50.0",
  "vulture>=2.14",
  "mkdocs>=1.6.1",
  "mkdocs-material[imaging]>=9.7.0",
  "mkdocs-redirects>=1.2.2",
  "pytest-cov>=7.0.0",
  "pytest-xdist>=3.8.0",
  "python-semantic-release>=10.5.3",
  "pytest-sugar>=1.1.1",
  "playwright>=1.58.0",
  "pytest-playwright>=0.7.2",
]

[tool.ruff]
line-length = 100
target-version = "py312"
src = ["src", "tests"]
extend-exclude = ["src/kagan/core/adapters/db/migrations/versions/*.py"]

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM", "TCH", "RUF"]
ignore = [
  "RUF012", # Textual class attributes (BINDINGS, etc.) don't need ClassVar
  "RUF006", # Allow fire-and-forget asyncio.create_task (intentional pattern)
  "SIM102", # Allow nested if statements for readability
  "SIM117", # Allow nested with statements for Textual compose patterns
]

[tool.ruff.lint.mccabe]
max-complexity = 20

[tool.ruff.lint.per-file-ignores]
"tests/property/*.py" = [
  "E402",
] # Hypothesis settings must be configured before imports
"src/kagan/server/mcp/**/*.py" = [
  "TC001", "TC002", "TC003",
] # MCP framework evaluates annotations at runtime via inspect.signature(eval_str=True)
"src/kagan/server/_task_routes.py" = [
  "C901",
] # Route registration nests all handlers inside one function
"src/kagan/server/_system_routes.py" = [
  "C901",
] # Route registration nests all handlers inside one function

[tool.ruff.format]
docstring-code-format = true

[tool.pyrefly]
project_includes = ["src", "tests"]
project_excludes = ["src/kagan/core/adapters/db/migrations/versions"]
search_path = ["src", "."]
permissive-ignores = true

# Pyrefly does not fully resolve cross-module imports in large projects.
# Each suppression documented with the root cause. Re-evaluate on pyrefly updates.
[tool.pyrefly.errors]
missing-import = false          # False positives on conditional/lazy imports
missing-attribute = false        # Cannot track None-guards or SQLModel column access
missing-module-attribute = false # Cross-module re-export resolution failures
bad-argument-type = false        # Misreads 3rd-party stubs (tomlkit, acp, textual)
no-matching-overload = false     # Textual push_screen overloads too complex for Pyrefly
bad-assignment = false           # kagan.core.models.Task vs asyncio.Task name collision
missing-argument = false         # Misreads asyncio.to_thread, acp.schema constructors
bad-override = false             # ACP client session_update signature mismatch (parent type too broad)

[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
testpaths = ["tests"]
norecursedirs = [
  "references",
  "scripts",
  "docs",
  "site",
  "htmlcov",
  ".venv",
  ".git",
  ".kagan_worktrees",
]
python_files = ["test_*.py", "*_cases.py"]
markers = [
  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
  "fast: pure-logic tests with no I/O, no DB, no subprocess",
  "unit: pure logic tests with no I/O",
  "contract: protocol/schema boundary tests",
  "smoke: critical user-path and transport checks",
  "snapshot: visual regression tests",
  "property: property-based tests with hypothesis",
  "e2e: end-to-end tests requiring real agent binaries (set KAGAN_INTEGRATION_TESTS=1)",
  "windows_ci: windows compatibility tests that must run in the Windows CI job",
  "core: tests scoped to kagan-core behaviors",
  "mcp: tests scoped to kagan-mcp protocol boundary",
  "tui: tests scoped to textual UI flows and rendering",
  "plugins: tests scoped to plugin implementations",
  "integration: tests scoped to real agent binary integration",
  "mock_platform_system(name): override platform.system() for the test",
]
addopts = "-p no:anyio -x -n auto --dist=loadgroup"

[tool.coverage.run]
source = ["src/kagan"]
branch = true
parallel = true
omit = ["*/tests/*", "*/__main__.py"]

[tool.coverage.report]
exclude_lines = [
  "pragma: no cover",
  "if TYPE_CHECKING:",
  "raise NotImplementedError",
]

[tool.poe.tasks]
dev = "python -m textual run --dev src/kagan/tui/app.py"
test = "pytest tests/"
lint = "ruff check src/"
check-loc = "python scripts/check_python_loc_budget.py --max-lines 2500"
check-complexity = "ruff check src/ --select C90"
check-wire-drift = "python scripts/check_wire_drift.py"
check-guardrails = ["check-loc", "check-complexity", "check-wire-drift"]
format = "ruff format src/ tests/"
typecheck = "pyrefly check --project-excludes src/kagan/core/adapters/db/migrations/versions src/"
deadcode = "vulture"
check = ["lint", "typecheck", "deadcode", "test"]
db-migrations-check = "pytest tests/core/test_db_migrations.py -n 0 -v"
docs-dev = "mkdocs serve -f mkdocs.local.yml"
docs-build = "mkdocs build"
docs-check = "mkdocs build"

[tool.poe.tasks.db-migration-generate]
help = "Generate an Alembic revision from SQLModel metadata"
cmd = "alembic -c alembic.ini revision --autogenerate -m \"${message}\""
args = [
  { name = "message", positional = true, required = true, help = "Migration message" },
]

[tool.poe.tasks.install-local]
help = "Install kagan as a local CLI tool (replaces any existing install)"
cmd = "uv tool install --editable --force --reinstall ."

[tool.poe.tasks.dev-setup]
help = "Install local CLI, reset DB, and stop core daemon"
sequence = [{ ref = "web-build" }, { ref = "install-local" }, { cmd = "kagan reset --force" }]

[tool.poe.tasks.fix]
help = "Fix linting issues and format code"
sequence = [
  { cmd = "ruff check --fix src/ tests/" },
  { cmd = "ruff format src/ tests/" },
]

[tool.poe.tasks.release-preview]
sequence = [
  { cmd = "uv run semantic-release version --print-last-released-tag" },
  { cmd = "uv run semantic-release version --print-tag --as-prerelease" },
]
help = "Preview current and next prerelease version"

[tool.poe.tasks.release-dry-run-beta]
shell = "uv run semantic-release --noop -vv version --as-prerelease --prerelease-token beta --print-tag"
help = "Dry-run beta release (no changes made)"

[tool.poe.tasks.snapshot-update]
help = "Update TUI snapshot tests (run sequentially)"
cmd = "pytest tests/tui/snapshot/ -n 0 -v --snapshot-update"

[tool.poe.tasks.web-build]
help = "Build React web bundle and copy into the Python package for 'kagan web'"
sequence = [
  { shell = "pnpm run web:build" },
  { shell = "rm -rf src/kagan/server/_web_static/* && cp -R packages/web/dist/* src/kagan/server/_web_static/ && touch src/kagan/server/_web_static/.gitkeep" },
]

[tool.poe.tasks.dev-web]
help = "Rebuild latest web frontend and start the web server"
sequence = [
  { ref = "web-build" },
  { cmd = "uv run kg web" },
]

[tool.poe.tasks.dev-web-hot]
help = "Start backend + Vite dev server with hot reload (no bundle rebuild)"
shell = """
echo "Starting Kagan dev servers..."
echo "  Frontend: http://localhost:5173 (Vite with hot reload)"
echo "  Backend:  http://127.0.0.1:8765 (API server)"
echo ""
cd packages/web && pnpm exec concurrently \\
  --names "VITE,API" \\
  --prefix-colors "cyan,magenta" \\
  --kill-others \\
  "pnpm exec vite" \\
  "sleep 2 && cd ../.. && uv run kg web --dev --no-open"
"""

[tool.poe.tasks.web-typecheck]
help = "Run TypeScript type checking on the web package"
shell = "pnpm run web:typecheck"

[tool.poe.tasks.web-test]
help = "Run Vitest unit tests on the web package"
shell = "pnpm run web:test"

[tool.poe.tasks.web-check]
help = "Run all web package checks (typecheck + test)"
sequence = ["web-typecheck", "web-test"]

[tool.poe.tasks.vscode-typecheck]
help = "Run TypeScript type checking on the VS Code extension package"
shell = "pnpm run vscode:typecheck"

[tool.poe.tasks.vscode-test-unit]
help = "Run Vitest unit tests on the VS Code extension package"
shell = "pnpm run vscode:test:unit"

[tool.poe.tasks.vscode-test-integration]
help = "Run extension-host integration tests on the VS Code extension package"
shell = "pnpm run vscode:test:integration"

[tool.poe.tasks.vscode-test-e2e]
help = "Run WDIO smoke tests against a real VS Code instance"
shell = "pnpm run vscode:test:e2e"

[tool.poe.tasks.vscode-check]
help = "Run typecheck and fast tests on the VS Code extension package"
sequence = ["vscode-typecheck", "vscode-test-unit"]

[tool.poe.tasks.test-all]
help = "Run all tests across the monorepo (Python + web)"
sequence = ["test", "web-test", "vscode-test-unit"]

[tool.poe.tasks.check-all]
help = "Run all checks across the monorepo (Python lint/typecheck/deadcode/test + web typecheck/test)"
sequence = ["lint", "typecheck", "deadcode", "test", "web-check", "vscode-check"]

[tool.poe.tasks.eval-generate]
help = "Export resolved prompts for the eval suite"
sequence = [
  { shell = "bash evals/generate-prompts.sh" },
  { shell = "python evals/resolve_promptfoo_config.py" },
]

[tool.poe.tasks.eval]
help = "Run promptfoo prompt evaluation (requires GITHUB_TOKEN with models:read)"
sequence = [
  { ref = "eval-generate" },
  { shell = "npx promptfoo@latest eval -c evals/promptfooconfig.resolved.yaml --no-progress-bar --max-concurrency 1 --delay 6500" },
]

[tool.poe.tasks.eval-view]
help = "Open promptfoo results in the browser"
shell = "npx promptfoo@latest view"

[tool.poe.tasks.workflows-check]
help = "Validate GitHub Actions workflows using act (requires act installed)"
sequence = [
  { shell = "act --list -W .github/workflows/" },
  { shell = "act push --dryrun -W .github/workflows/ci.yml" },
  { shell = "act workflow_dispatch --dryrun -W .github/workflows/cd.yaml" },
  { shell = "act workflow_dispatch --dryrun -W .github/workflows/post-release-update-test.yaml" },
]

[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
build_command = "uv build --wheel"
commit_message = "{version}\n\n[skip ci] Automatically generated by python-semantic-release"
tag_format = "v{version}"
allow_zero_version = true

[tool.semantic_release.changelog]
template_dir = ".github/semantic-release"
exclude_commit_patterns = [
  '''chore\(vscode\): [Bb]ump to \d.+''',
  '''[Uu]pdate pnpm-lock\.yaml .+''',
]

[tool.semantic_release.branches.main]
match = "main"
prerelease_token = "beta"
prerelease = false

[tool.semantic_release.commit_parser_options]
allowed_tags = [
  "build",
  "chore",
  "ci",
  "docs",
  "feat",
  "fix",
  "perf",
  "style",
  "refactor",
  "test",
]
minor_tags = ["feat", "refactor"]
patch_tags = ["fix", "perf", "chore"]

[tool.semantic_release.publish]
dist_glob_patterns = ["dist/*"]
upload_to_vcs_release = true

[tool.semantic_release.remote.token]
env = "GITHUB_TOKEN"

[tool.vulture]
paths = ["src/"]
min_confidence = 90
ignore_names = ["output_byte_limit", "terminal_id", "params"]