Kanabie 2

Rust 2024 rewrite of the file-based Kanabie worklog. It reads existing v1 trees in place, writes canonical frontmatter, and ships two binaries:

• kanabie — CLI, including release-based self-update;
• kanabie-serve — read-only Axum API and embedded Leptos CSR dashboard.

The current version is 2.1.0. Kanabie v1 remains the compatibility oracle for unchanged surfaces. The documented v2 differences are HTML export removal, release-bundle updates in place of raw-source updates, and canonical numbered task IDs.

Build and test

Rust 1.94.0 and Trunk 0.21 are expected. Production order matters because the server embeds the completed frontend bundle:

cd crates/kanabie-web && NO_COLOR=false trunk build --release
cd ../.. && cargo build --release -p kanabie-cli -p kanabie-serve

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo check -p kanabie-web --target wasm32-unknown-unknown

The v1/v2 differential harness is an explicit compatibility and release tool, not a dependency of normal v2 development or CI. Run its ignored tests with an explicit oracle path when checking a v1-compatible surface:

KANABIE_V1=/home/alatar/projects/kanabie/kanabie.py \
  cargo test -p kanabie-cli --test differential -- --ignored --nocapture
KANABIE_V1=/home/alatar/projects/kanabie/kanabie.py KANABIE_CASE=read_json \
  cargo test -p kanabie-cli --test differential differential_matrix -- --ignored --nocapture

It writes the machine-readable result to target/differential-report.json. Set KANABIE_DIFFERENTIAL_REPORT to choose another output path. Normal workspace tests validate the committed inventory and its Rust evidence without requiring v1. The ignored live-oracle tests additionally check all 319 CLI behaviors plus 69 server/UI behaviors against v1. See COMPATIBILITY.md for the evidence model and acceptance procedure.

Cases live in crates/kanabie-cli/tests/differential/cases.toml; adding a normal case does not require changing the Rust runner:

[[cases]]
name = "list_{format}"
argv = ["list", "--format", "{format}"]
template = "seeded"
variants = [{ format = "ids" }, { format = "paths" }, { format = "json" }]

Templates provide shared fixture, cwd, environment, setup commands and normalizers. A case may add setup commands, stdin and declarative arrange actions (write, append, append-metadata, replace, rename or set-mtime). mutation = true asserts a tree change; difference is reserved for documented v2 differences. Placeholders in variants generate option grids while preserving individually selectable KANABIE_CASE names.

Future parity expansion should describe distinct observable contracts in this manifest and generate repetitive flag/format combinations with variants. The v1 pytest suite remains the semantic source, but should not be copied one-for-one into Rust constructors; an importer may emit manifest data later if the v1 tests gain stable scenario metadata.

Server

From a repository containing kanabie/:

kanabie-serve
kanabie service install --enable-now

The default bind is 127.0.0.1:8765. Non-loopback binds require allow_remote. The read-only API starts at /api/v1; see API.md.

Install and systemd user service

For a fresh install, run the one-shot installer. It resolves the latest Forgejo release, downloads the musl archive and SHA256SUMS, verifies the checksum, and installs both binaries:

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

The same installer supports offline or pinned-release installation when the archive and checksum file are already present:

./install.sh kanabie-2.0.0-x86_64-unknown-linux-musl.tar.gz
kanabie service install --root /path/to/worklog

The installer verifies the checksum, preflights both executables, atomically replaces each destination and creates the compatibility symlink kanabie_serve. A direct one-shot or archive installation leaves the existing service state unchanged and does not create or enable a missing service. Pass --enable-now explicitly to kanabie service install when that is intended.

Existing installations use the same installer engine through the CLI:

kanabie update --check
kanabie update

update checks the latest public Forgejo release, downloads the complete archive and checksum, and replaces kanabie plus the sibling kanabie-serve only after verification. It refuses to overwrite a binary inside a Git checkout unless --force is passed. --target KANABIE_PATH selects a different CLI path and --url RELEASE_API_URL selects another compatible latest-release endpoint. Before a real update it records whether kanabie-serve.service is active and restarts it after successful installation only in that case. It never enables, disables or starts an inactive service; --check and no-op updates do not touch systemd.

Install or refresh the bundled Kanabie skill in every active agent environment with:

kanabie skill install

Kanabie currently detects Claude from CLAUDE_CONFIG_DIR or an existing ~/.claude directory, and Codex from CODEX_HOME or an existing ~/.codex directory. It installs into each detected skills/kanabie directory without creating an otherwise inactive environment. Use repeatable --environment claude or --environment codex arguments to select targets explicitly; an explicit target may be created even when that environment has not been initialized yet.

An identical service install is idempotent. Kanabie records checksums in $XDG_CONFIG_HOME/kanabie/service-state.toml; a changed config or unit is not overwritten or removed unless --force is given:

kanabie service install --root /path/to/worklog --force
kanabie service uninstall --disable-now
kanabie service uninstall --disable-now --force  # remove locally modified managed files

Taskfile workflows

Task v3 can drive the common local build and release workflows:

task build
task reinstall
task release VERSION=v2.1.0
task release -- VERSION=v2.1.0

build creates the Trunk bundle before compiling the native release binaries. reinstall builds the current workspace version, installs its verified archive into ~/.local/bin, and restarts kanabie-serve.service only when it is already active.

release is the publishing workflow and must start from a clean, fully committed main. It checks that local main contains origin/main and that the target tag is unused, updates all version-bearing files when needed, runs the complete local quality/release gate plus an installer smoke test, creates a release: prepare kanabie X.Y.Z commit when it changed the version, creates the annotated vX.Y.Z tag, and pushes main followed by the tag. The Woodpecker tag pipeline publishes the Forgejo release and verifies the downloaded artifacts. A failure before the release commit restores the automatic version edits; a push failure leaves the verified local commit/tag available for a safe retry.

Release gate

Official archives target only x86_64-unknown-linux-musl. Set the version explicitly; the build has no stale fallback version:

cargo audit
systemd-analyze verify packaging/kanabie-serve.service
VERSION=2.1.0 ./scripts/build-release.sh

The archive in dist-release/ contains both binaries, the installer, README, API/migration docs, the Kanabie skill and the systemd unit. Packaging is reproducible for a fixed SOURCE_DATE_EPOCH. Tag CI uses only forgejo_release_token, then downloads the published archive and checksum and smoke-tests the downloaded server.

Unknown metadata and bodies are preserved, legacy step:/deferred: and block/inline lists are read, mixed extensions remain per-file, and mutations use a process lock plus atomic replace. See MIGRATION.md.