kohakutui 0.1.0__tar.gz

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

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff black
+      - run: ruff check src/ tests/ scripts/
+      - run: black --check src/ tests/ scripts/
+
+  rust:
+    name: Rust (fmt, clippy, stage tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo clippy --all-targets --features python -- -D warnings
+      # Without the python feature the test binary links nothing of Python
+      - run: cargo test --no-default-features
+      - name: One crossterm in the dependency graph
+        run: |
+          n=$(cargo tree -e normal -i crossterm --depth 0 2>/dev/null | grep -c '^crossterm' || true)
+          test "$n" -le 1 || { cargo tree -d; exit 1; }
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: astral-sh/setup-uv@v6
+      - name: Build the wheel
+        shell: bash
+        run: |
+          uv venv
+          uv pip install maturin
+          uv run --no-project maturin build --release --out dist
+      - name: Install the built wheel
+        shell: bash
+        run: |
+          WHEEL=$(ls dist/*.whl)
+          uv pip install "${WHEEL}[dev]"
+      - name: Tests
+        run: uv run --no-project pytest tests/ -q --tb=short

kohakutui-0.1.0/.github/workflows/nightly.yml

@@ -0,0 +1,60 @@
+name: Nightly
+
+on:
+  schedule:
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+    inputs:
+      force_rebuild:
+        description: Build even if this commit already has nightly artifacts
+        type: boolean
+        default: false
+
+# Like KohakuVault and KohakuTerrarium: nightly only decides; release.yml owns every build and
+# upload, so there is one matrix and one PyPI trusted publisher.
+concurrency:
+  group: nightly-dispatch
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  actions: write
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+      - name: Require green CI, skip a commit already published
+        id: gate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          FORCE: ${{ inputs.force_rebuild || false }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          sha=$(git rev-parse HEAD)
+          result=$(gh run list --workflow ci.yml --commit "$sha" --event push --limit 1 --json conclusion --jq '.[0].conclusion // "missing"')
+          if [ "$result" != success ]; then
+            echo "::error::CI for $sha is $result; nightly not dispatched"
+            exit 1
+          fi
+          previous=$(gh release list --limit 100 --json tagName --jq '[.[] | select(.tagName | startswith("nightly-"))][0].tagName // ""')
+          if [ -n "$previous" ] && [ "$FORCE" != true ]; then
+            body=$(gh release view "$previous" --json body --jq .body)
+            if printf '%s' "$body" | grep -Fq "Source commit: $sha"; then
+              echo "Commit $sha already published" >> "$GITHUB_STEP_SUMMARY"
+              exit 0
+            fi
+          fi
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+      - name: Dispatch the release builder (nightly channel)
+        if: steps.gate.outputs.sha != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SOURCE_SHA: ${{ steps.gate.outputs.sha }}
+        run: |
+          gh workflow run release.yml --ref main -f ref="$SOURCE_SHA" -f channel=nightly
+          echo "Dispatched nightly for $SOURCE_SHA." >> "$GITHUB_STEP_SUMMARY"

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

@@ -0,0 +1,220 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: Exact commit or ref to build
+        default: main
+        type: string
+      channel:
+        description: Build only, or publish a nightly (never a stable manual release)
+        default: build
+        type: choice
+        options: [build, nightly]
+
+concurrency:
+  group: release-${{ inputs.channel || github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  actions: read
+
+defaults:
+  run:
+    shell: bash
+
+# The only workflow that uploads kohakutui, so PyPI needs one trusted publisher: this file
+# (release.yml), environment `pypi`. Nightly runs come here too, dispatched by nightly.yml.
+jobs:
+  meta:
+    name: Resolve the version
+    if: github.event_name != 'release' || startsWith(github.event.release.tag_name, 'v')
+    runs-on: ubuntu-latest
+    outputs:
+      sha: ${{ steps.source.outputs.sha }}
+      cargo_version: ${{ steps.version.outputs.cargo_version }}
+      python_version: ${{ steps.version.outputs.python_version }}
+      tag: ${{ steps.version.outputs.tag }}
+      nightly: ${{ steps.version.outputs.nightly }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Resolve the source; a nightly needs green CI on it
+        id: source
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CHANNEL: ${{ inputs.channel }}
+        run: |
+          sha=$(git rev-parse HEAD)
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          if [ "$CHANNEL" = nightly ]; then
+            result=$(gh run list --workflow ci.yml --commit "$sha" --event push --limit 1 --json conclusion --jq '.[0].conclusion // "missing"')
+            test "$result" = success || { echo "::error::CI for $sha is $result"; exit 1; }
+          fi
+      - name: One version for every platform
+        id: version
+        env:
+          CHANNEL: ${{ inputs.channel }}
+        run: |
+          args=()
+          if [ "$CHANNEL" = nightly ]; then args+=(--nightly); fi
+          python scripts/release_version.py "${args[@]}" --github-output "$GITHUB_OUTPUT"
+      # A tag that disagrees with Cargo.toml is a mis-cut release: stop before anything is built
+      - name: The tag matches Cargo.toml
+        if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'release'
+        env:
+          TAG: ${{ github.event.release.tag_name || github.ref_name }}
+          EXPECTED: ${{ steps.version.outputs.tag }}
+        run: |
+          test "$TAG" = "$EXPECTED" || { echo "::error::tag $TAG != Cargo.toml $EXPECTED"; exit 1; }
+
+  # abi3: one wheel per platform serves every CPython from 3.10 on
+  build-wheels:
+    name: Wheel for ${{ matrix.target }}
+    needs: meta
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, target: x86_64-unknown-linux-gnu, manylinux: '2_28', native: true }
+          - { os: ubuntu-24.04-arm, target: aarch64-unknown-linux-gnu, manylinux: '2_28', native: true }
+          - { os: windows-latest, target: x86_64-pc-windows-msvc, manylinux: '', native: true }
+          - { os: macos-latest, target: aarch64-apple-darwin, manylinux: '', native: true }
+          # Intel macs: cross-built on the arm runner (GitHub retired its Intel macOS images)
+          - { os: macos-latest, target: x86_64-apple-darwin, manylinux: '', native: false }
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.meta.outputs.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Stamp the version
+        env:
+          ARTIFACT_VERSION: ${{ needs.meta.outputs.cargo_version }}
+        run: python scripts/release_version.py --stamp "$ARTIFACT_VERSION"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux || 'auto' }}
+          args: --release --out dist
+      - name: Smoke-test the wheel in a clean venv
+        if: matrix.native
+        env:
+          EXPECTED_VERSION: ${{ needs.meta.outputs.python_version }}
+        run: |
+          python -m venv .venv-wheel
+          if [ "${RUNNER_OS}" = "Windows" ]; then . .venv-wheel/Scripts/activate; else . .venv-wheel/bin/activate; fi
+          pip install dist/*.whl
+          # away from src/, so the import is the installed wheel
+          cd dist
+          python -c "import importlib.metadata as m, os; assert m.version('kohakutui') == os.environ['EXPECTED_VERSION']"
+          python -c "import kohakutui; print(kohakutui.version(), kohakutui.PROTOCOL)"
+          # a whole demo turn on the emulated terminal: the engine, not just the import
+          python -c "
+          from kohakutui import App
+          from kohakutui.demo.agent import agent
+          app = App(backend='test', size=(90, 30), interrupt='event')
+          agent(speed=0.0, interactive=False, app=app)
+          assert any(l.startswith('● Done.') for l in app.history()), app.history()
+          print('demo ok')
+          "
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.target }}
+          path: dist/*.whl
+          if-no-files-found: error
+          retention-days: 7
+
+  build-sdist:
+    name: Build the sdist
+    needs: meta
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.meta.outputs.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Stamp the version
+        env:
+          ARTIFACT_VERSION: ${{ needs.meta.outputs.cargo_version }}
+        run: python scripts/release_version.py --stamp "$ARTIFACT_VERSION"
+      - name: Build
+        run: |
+          pip install maturin twine
+          maturin sdist --out dist
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [meta, build-wheels, build-sdist]
+    runs-on: ubuntu-latest
+    if: needs.meta.outputs.nightly == 'true' || startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'release' && startsWith(github.event.release.tag_name, 'v'))
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kohakutui
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - name: List artifacts
+        run: ls -lh dist/
+
+      - name: Nightly notes and checksums
+        if: needs.meta.outputs.nightly == 'true'
+        env:
+          SOURCE_SHA: ${{ needs.meta.outputs.sha }}
+          ARTIFACT_VERSION: ${{ needs.meta.outputs.python_version }}
+        run: |
+          printf 'Automatic nightly build (not a stable release).\n\nVersion: %s\n\nSource commit: %s\n' "$ARTIFACT_VERSION" "$SOURCE_SHA" > nightly-notes.md
+          sha256sum dist/* > dist/SHA256SUMS.txt
+      - name: Nightly as a dated prerelease
+        if: needs.meta.outputs.nightly == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.meta.outputs.tag }}
+          target_commitish: ${{ needs.meta.outputs.sha }}
+          name: Nightly ${{ needs.meta.outputs.python_version }}
+          prerelease: true
+          make_latest: false
+          body_path: nightly-notes.md
+          files: dist/*
+      - name: Keep the checksum file off PyPI
+        if: needs.meta.outputs.nightly == 'true'
+        run: rm dist/SHA256SUMS.txt
+
+      - name: Upload to the GitHub release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          fail_on_unmatched_files: false
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verbose: true

kohakutui-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Local working notes
+/plans/
+.claude/
+temp/
+
+# Rust
+/target/
+*.pdb
+
+# Built extension (maturin develop / editable installs)
+*.so
+*.pyd
+*.dylib
+
+# Python
+__pycache__/
+*.py[codz]
+*$py.class
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+.venv/
+.venv-*/
+venv/
+
+# Tests and tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.snap.new
+*.pending-snap
+
+# Editors
+.vscode/
+.idea/

kohakutui-0.1.0/CLAUDE.md

@@ -0,0 +1,106 @@
+# KohakuTUI
+
+A terminal UI engine in Rust, driven from Python through a retained node-tree protocol. Python
+describes what is on screen; Rust owns the terminal, the frame loop and every keystroke.
+
+The architecture is `plans/design.md` (local, gitignored, like all of `plans/`). Section references
+such as "design §5" in code and READMEs point into it. Read §1–§5 before changing anything in
+`proto/` or `model/`.
+
+## Project layout
+
+```text
+src/kohakutui-rust/   engine crate; lib.rs holds the `_rs` pymodule (feature `python`)
+src/kohakutui/        Python SDK over kohakutui._rs
+tests/                static/, e2e/, integration/, unit/ (Python); Rust tests in <module>/tests.rs
+docs/                 public docs (protocol, sdk), added as they are written
+plans/                local design and working plans (gitignored)
+```
+
+## Development setup
+
+- `uv venv`, then `uv pip install -e ".[dev]"`. maturin builds the extension into the venv;
+  rerun after any Rust change.
+- **Never use `sys.path.insert` hacks** in examples or tests; import `kohakutui.*` from the
+  installed package.
+
+## Rust rules
+
+1. **Every module is a directory whose only entry point is `mod.rs`**: submodule declarations,
+   the module's public types and re-exports. Logic goes in sibling files. Never `name.rs` beside
+   `name/` (`tests/static/test_layout.py` enforces this).
+2. Unit tests live in `<module>/tests.rs` (`#[cfg(test)] mod tests;` in `mod.rs`).
+3. pyo3 code lives in `<module>/python.rs` behind `#[cfg(feature = "python")]`, exposes
+   `register(m)`, and is registered from `lib.rs`. Pure Rust never imports pyo3, so
+   `cargo test --no-default-features` links no Python.
+4. pyclasses are underscore-prefixed (`_Session`) and wrapped by a public Python class.
+5. Errors: one `thiserror` enum per module, with `From<Error> for PyErr` in its `python.rs`.
+   The engine never panics on input from Python or the wire; a bad op becomes `Event::Error`.
+6. `//!` docs at the top of every file say what the module is for. `pub(crate)` unless the
+   item is part of the crate API.
+7. `cargo fmt` (max width 100) and `cargo clippy --all-targets -- -D warnings`, with and without
+   `--features python`.
+8. Code adapted from Codex (Apache-2.0) or ratatui (MIT) keeps its license header.
+
+## Python rules
+
+### Style
+- Target Python 3.10+ (abi3 wheel). Modern hints: `list`, `dict`, `X | None`.
+- Prefer `match`/`case` over deep `if`/`elif`.
+- No `print()` in library code. CLI entry points (`__main__.py`) may print.
+- black (default width) and `ruff check` over `src/` and `tests/`.
+
+### Imports
+1. No imports inside functions (except an optional dependency, such as `tqdm`).
+   `tests/static/test_layout.py` enforces this.
+2. Groups: built-in, third-party, `kohakutui`.
+3. Within a group: `import` before `from`, shorter dotted paths first, then a–z.
+
+### Files
+- One responsibility per module. Every package folder has a `README.md` with a file table.
+- File size is capped by AST statements (imports and docstrings excluded): over 500 warns,
+  over 1000 fails (`tests/static/test_file_sizes.py`).
+
+## Comments and docstrings
+
+Comment, code and docstring all say **what**. *How* and *why* live in `docs/` and `plans/`.
+
+1. No memo, note or editorial comments.
+2. A comment says what the code itself cannot say clearly.
+3. A docstring says what the class or function is *for*, so a reader can place it.
+4. Soft limits: inline comment blocks ≤ 2 lines, docstrings ≤ 14 lines.
+5. Doc comments (`//!`, `///`, docstrings) say what a file, type or function is for. An inline
+   comment (1–2 lines) heads a logic block only when the code cannot say what it does (a tricky
+   API, a non-obvious algorithm step).
+6. Separate logic blocks inside a function with one blank line.
+7. Formatting is the formatter's: rustfmt for Rust, black for Python (black already wraps long
+   expressions in parentheses).
+
+## Tests
+
+The engine is a pipeline of stages (proto → model → text → widgets/view → term, then the SDK on
+top). **A test proves one stage on the level below it and nothing further.** `tests/README.md`
+has the stage table.
+
+- Write tiers **e2e first, then integration, then unit**: the journey fixes what must work, the
+  lower tiers pin the parts.
+- `static/`: layout and contract guards (module layout, imports, file sizes, the `_rs.pyi` stub).
+- Behavior asserts, not shape asserts; real collaborators, not mocks. The only seam is the
+  terminal: `_Session(backend="test")`.
+- A check that cannot fail on a broken stage is not a check.
+
+## Post-implementation
+
+1. Check the rules above, especially in-function imports and the `mod.rs` layout.
+2. `black src/ tests/`, `ruff check src/ tests/`, `cargo fmt`, both clippy runs.
+3. `pytest tests/ -q` and `cargo test --no-default-features`.
+4. New behaviour has tests at the right stage and tier.
+5. Logically separate commits (conventional style: `feat(model): ...`). **Do not commit unless
+   asked.**
+
+## Audit loop (multi-step work: required)
+
+Implement → write tests that pin the behaviour (negative cases first) → run every suite and lint
+→ audit the diff for clear bugs, integrity bugs (broken invariants, races, stale caches) and
+behaviour bugs (wrong default, swallowed error) → if the audit finds a bug the tests missed,
+first make a test fail on it, then fix → repeat until the audit is clean and everything is green.