kanabie

Plikowy kanban + worklog jako CLI. Jeden plik Pythona, wyłącznie stdlib, bez zależności. Zarządza hierarchią epic / scope / task w katalogu kanabie/ wewnątrz dowolnego repo git — metadane są źródłem prawdy, a nazwy plików są z nich regenerowane.

Wymagania

• Python 3.11+
• git (do task commit, cross-repo cache)
• brak zależności zewnętrznych

Instalacja

Jednolinijkowy installer (bez klonowania repo)

curl -fsSL https://git.chaos-it.pl/b.zablocki/kanabie/raw/branch/main/install-remote.sh | bash

Pobiera kanabie + kanabie_serve do ~/.local/bin i skill agenta do ~/.claude/skills/kanabie/. Konfigurowalne zmiennymi: BINDIR, KANABIE_REF (branch/tag), BASE_URL, NO_SKILL=1.

Z klona repo

git clone https://git.chaos-it.pl/b.zablocki/kanabie.git
cd kanabie
./install.sh

install.sh kopiuje do ~/.local/bin/:

• kanabie — CLI
• kanabie_serve — dashboardy HTML operujące na kanonicznych ID
• skill agenta do ~/.claude/skills/kanabie/ (jeśli katalog skills/ istnieje)

Upewnij się, że ~/.local/bin jest w PATH. Inny cel instalacji: ./install.sh /custom/path/kanabie.

Sprawdzenie:

kanabie --version
kanabie --help

Aktualizacja

Samoaktualizacja w miejscu — pobiera najnowszy kanabie.py (+ kanabie_serve) z remote, bez klonowania:

kanabie update --check     # tylko sprawdź, czy jest nowsza wersja
kanabie update             # nadpisz zainstalowany plik (atomowo, +x zachowany)

Opcje: --url <raw-base> lub $KANABIE_UPDATE_URL (inny host/branch — np. .../raw/branch/<ref>), --target <ścieżka> (inny plik do podmiany), --force (wymuś nadpisanie mimo że plik leży w klonie git — domyślnie update odmawia w dev-checkoutach i odsyła do git pull).

Szybki start

cd <dowolne-repo-git>
kanabie init                              # tworzy kanabie/ w repo
kanabie epic new foundation               # epic
kanabie scope new 01-setup                # scope w epicu 01
kanabie task new 01-01-bootstrap          # task (planned)
kanabie task assign 01-01-bootstrap       # nadaje numer, planned → open
kanabie task status 01-01-bootstrap closed
kanabie list                              # przegląd

Komendy operujące na encjach zwracają domyślnie kanoniczne ID. Gdy naprawdę potrzebujesz pliku, dodaj --as-path. Do treści preferuj czasowniki read / append / write — argumentem jest ref (nigdy ścieżka), więc działają bez pytań o dostęp per plik także cross-repo, a zapisy poprawnie podbijają modified.

Konfiguracja

Rozszerzenie nowych plików

Zmienna KANABIE_EXT ustawia rozszerzenie dla nowych plików (istniejące zachowują swoje):

KANABIE_EXT=.md kanabie task new 01-01-foo   # .md
KANABIE_EXT=.adoc kanabie epic new bar        # .adoc
# domyślnie: brak rozszerzenia

Repozytoria cross-repo

Rejestracja innych repo (do linkowania, coverage, gate cross-repo):

kanabie setup repo:<nazwa>                          # rejestruje bieżący katalog
kanabie setup repo:upstream --path vendor/upstream  # inna lokalna ścieżka
kanabie setup repo:upstream --url https://.../x.git # remote przez sparse cache

Pliki konfiguracyjne (TOML):

• Globalny (XDG, fallback): ~/.config/kanabie/repos.toml
• Per-repo (pełny override globalnego dla tego repo): <repo>/kanabie/.config/repos.toml

Ścieżki względne w configu per-repo rozwiązują się względem korzenia repo (przenośne dla vendored clones):

[repos]
upstream = "vendor/upstream"                       # względna do korzenia repo
external = "/abs/path/to/other"                    # absolutna
remote   = { url = "https://git.example/x.git" }   # tylko sparse cache (kanabie remote refresh)

Per-repo config w całości zastępuje globalny dla danego repo — bez mergowania, żeby utrzymać izolację namespace'ów między projektami.

Cache cross-repo (gdy producent jest duży / na innej maszynie)

kanabie remote refresh <nazwa>[,<nazwa>...] # sparse clone tylko kanabie/ → ~/.cache/kanabie/<nazwa>/
kanabie remote list                # co w cache + świeżość

Najczęstsze komendy

kanabie list [--epic N[,N] --scope S[,S] --status V[,V] --role R[,R] --since --as-path|--format paths|ids|compact|json]
kanabie show <id> [--reverse|--as-path] # kanoniczne ID; --as-path → ścieżka
kanabie read <ref> [--body|--json] # treść taska (też remote:id)
kanabie append <id> [TEKST|-]      # dopisz do worklogu (tylko lokalnie)
kanabie write <id> [TEKST|-]       # zastąp body (tylko lokalnie; frontmatter nietykalny)
kanabie find <fragment>            # szukaj po slugu
kanabie report [--format adoc|md|html] [--output FILE]
kanabie coverage (--role <r>[,<r>...]|--all-roles) [--validate --gaps --remote <r>[,<r>...]]
kanabie sync [--dry-run]           # realign nazw/mtime z metadanych
kanabie check                      # audyt spójności drzewa
kanabie_serve --export index --output status.html

Pełny opis modelu danych, gate/coverage i workflowów: zobacz CLAUDE.md.

Testy

python3 -m pytest tests/test_kanabie.py
python3 -m pytest tests/test_kanabie.py -k <wzorzec>