caland 0.5.0__tar.gz

caland-0.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Something isn't working
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `caland`
+        2. ...
+  - type: input
+    id: version
+    attributes:
+      label: Caland version
+      placeholder: "0.1.0  (uvx caland --version, or `uv tool list`)"
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+  - type: input
+    id: os
+    attributes:
+      label: OS / terminal
+      placeholder: "macOS 15 · iTerm2"
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output
+      description: >
+        The TUI takes over the screen, so capture stderr with
+        `caland 2>err.log` and paste `err.log` here.
+      render: text

caland-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/kostavo-oss/caland/security/advisories/new
+    about: Please report security issues privately, not as a public issue.

caland-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+<!-- Thanks for contributing to Caland! -->
+
+## What & why
+
+<!-- What does this change, and why? Link any related issue (#123). -->
+
+## Checklist
+
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check .` and `uv run ruff format .` are clean
+- [ ] `uv run ty check` passes
+- [ ] New behaviour has a test
+- [ ] Business logic stays out of `interface/`; the SDK stays in `infrastructure/`

caland-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,74 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: lint + types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync
+      - name: Lint (ruff)
+        run: uv run ruff check .
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+      - name: Type check (ty)
+        run: uv run ty check
+
+  test:
+    name: test (py${{ matrix.python-version }} · ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python-version: "3.14"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Tests (pytest)
+        run: uv run --python ${{ matrix.python-version }} pytest
+
+  docs:
+    name: docs (strict build + screenshots)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      # mkdocs lives in the `docs` dependency group, which a plain sync skips
+      - run: uv sync --group docs
+      - name: Build the docs site (strict — broken links/nav fail)
+        run: uv run --group docs mkdocs build --strict
+      - name: Screenshot pipeline still runs
+        run: uv run --group docs python docs/redesign/capture.py
+
+  build:
+    name: build (wheel + sdist)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - name: Smoke-test the built wheel on 3.11
+        run: |
+          uv venv /tmp/smoke -p 3.11
+          uv pip install --python /tmp/smoke/bin/python dist/*.whl
+          /tmp/smoke/bin/python -c "import caland.app; print('import OK')"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*

caland-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# allow the GITHUB_TOKEN to deploy to Pages, and serialise deploys
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build site
+    runs-on: ubuntu-latest
+    env:
+      NO_MKDOCS_2_WARNING: "1" # we pin mkdocs < 2; suppress the advisory banner
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Build (mkdocs)
+        run: uv run --group docs mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: deploy to Pages
+    needs: build
+    if: github.event_name != 'pull_request' # build-only on PRs; deploy from main
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

caland-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,95 @@
+name: release
+
+# Version-driven releases — the package version is the single source of truth.
+# To cut a release:
+#   1. uv version --bump {patch|minor|major}   # edits pyproject.toml + uv.lock
+#   2. move the CHANGELOG "[Unreleased]" notes under a "## [x.y.z]" heading
+#   3. open a PR and merge to main
+# On that merge this workflow checks whether the version is already released; if
+# not, it builds the wheel + sdist, publishes to PyPI, and creates the matching
+# `vX.Y.Z` git tag + GitHub release (notes pulled from the CHANGELOG). A push that
+# doesn't change the version is a no-op.
+#
+# One-time setup — configure a PyPI Trusted Publisher (no API token needed) for
+#   repo: kostavo-oss/caland · workflow: release.yml · environment: pypi
+# at https://pypi.org/manage/account/publishing/
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  check:
+    name: detect version bump
+    runs-on: ubuntu-latest
+    outputs:
+      should_release: ${{ steps.decide.outputs.should_release }}
+      version: ${{ steps.read.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # need the tags to tell whether this version shipped
+      - id: read
+        name: Read the project version
+        run: |
+          v=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+          echo "Project version: $v"
+      - id: decide
+        name: Already released?
+        run: |
+          version="${{ steps.read.outputs.version }}"
+          released=false
+          if git rev-parse "v$version" >/dev/null 2>&1; then
+            echo "git tag v$version already exists"; released=true
+          fi
+          code=$(curl -fsS -o /dev/null -w "%{http_code}" \
+            "https://pypi.org/pypi/caland/$version/json" || echo 000)
+          if [ "$code" = "200" ]; then
+            echo "caland $version is already on PyPI"; released=true
+          fi
+          if [ "$released" = "true" ]; then
+            echo "Nothing to release for $version."
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Will release $version."
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+          fi
+
+  release:
+    name: publish v${{ needs.check.outputs.version }}
+    needs: check
+    if: needs.check.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write # create the tag + GitHub release
+      id-token: write # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/
+      - name: Release notes from CHANGELOG
+        run: |
+          version="${{ needs.check.outputs.version }}"
+          awk -v v="$version" '
+            index($0, "## [" v "]") == 1 { f=1; next }
+            f && index($0, "## [") == 1 { exit }
+            f { print }
+          ' CHANGELOG.md > notes.md || true
+      - name: Create the tag + GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${{ needs.check.outputs.version }}"
+          args=(--title "v$version" --target "$GITHUB_SHA")
+          if [ -s notes.md ]; then args+=(--notes-file notes.md); else args+=(--generate-notes); fi
+          gh release create "v$version" dist/* "${args[@]}"

caland-0.5.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.pyc
+.textual/
+dist/
+build/
+*.egg-info/
+.DS_Store
+docs/redesign/*.svg.png
+
+# generated reference renders (regenerate with docs/redesign/capture.py)
+docs/redesign/*.svg
+
+# mkdocs build output
+site/

caland-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+# `uvx pre-commit install` once, and ruff runs on every commit.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20 # the ruff uv.lock has, so a commit is checked as ci checks it
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

caland-0.5.0/.zed/settings.json

@@ -0,0 +1,36 @@
+{
+  "languages": {
+    "Python": {
+      "language_servers": ["ty", "ruff"],
+      "format_on_save": "on",
+      "code_actions_on_format": {
+        "source.organizeImports.ruff": true
+      },
+      "formatter": {
+        "language_server": { "name": "ruff" }
+      }
+    }
+  },
+  "lsp": {
+    "ruff": {
+      "binary": {
+        "path": ".venv/bin/ruff",
+        "arguments": ["server"]
+      }
+    },
+    "ty": {
+      "binary": {
+        "path": ".venv/bin/ty",
+        "arguments": ["server"]
+      }
+    }
+  },
+  "terminal": {
+    "detect_venv": {
+      "on": {
+        "directories": [".venv"],
+        "activate_script": "default"
+      }
+    }
+  }
+}