magpy-lite 0.1.0__tar.gz

magpy_lite-0.1.0/.github/scripts/roll_changelog.py

@@ -0,0 +1,99 @@
+"""Move CHANGELOG.md's [Unreleased] entries under a new version heading.
+
+Usage: roll_changelog.py CHANGELOG TAG PREVIOUS_TAG DATE NOTES_OUT [TAG_ALREADY_AT_HEAD]
+       roll_changelog.py --notes CHANGELOG TAG NOTES_OUT
+
+Called by release.yml. Writes the release notes to NOTES_OUT and edits the
+changelog in place; touches neither when there is nothing to release:
+
+- [Unreleased] has entries: they become ``## [X.Y.Z] - DATE`` and an empty
+  [Unreleased] is left above them.
+- [Unreleased] is empty but the commit already shipped as another tag (a manual
+  minor/major bump after the automatic patch): a short ``## [X.Y.Z]`` entry
+  points at that release, whose entries become the notes.
+
+Keep a Changelog link references at the bottom are updated when present.
+
+With --notes, CHANGELOG has already been rolled for TAG (a re-run resuming a
+release whose changelog commit reached main): only the notes are written, the
+same ones the roll produced. Exits 1 if CHANGELOG has no section for TAG.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+HEADING = re.compile(r"^## \[(?P<name>[^\]]+)\]", re.MULTILINE)
+LINKS = re.compile(r"^\[[^\]]+\]: ", re.MULTILINE)
+
+
+def section(text: str, name: str) -> tuple[int, int, int] | None:
+    """(heading start, body start, body end) of the ``## [name]`` section."""
+    for m in HEADING.finditer(text):
+        if m.group("name") == name:
+            body = text.index("\n", m.start()) + 1
+            nxt = HEADING.search(text, body)
+            links = LINKS.search(text, body)
+            ends = [x.start() for x in (nxt, links) if x] + [len(text)]
+            return m.start(), body, min(ends)
+    return None
+
+
+def update_links(text: str, version: str, base: str) -> str:
+    """Point [Unreleased] at the new tag and add a link for the new version."""
+    m = re.search(r"^\[Unreleased\]: (?P<repo>\S+)/compare/\S+\.\.\.HEAD$", text, re.M)
+    if not m:
+        return text
+    repo, tag = m.group("repo"), f"v{version}"
+    link = f"{repo}/compare/{base}...{tag}" if base else f"{repo}/releases/tag/{tag}"
+    new = f"[Unreleased]: {repo}/compare/{tag}...HEAD\n[{version}]: {link}"
+    return text[: m.start()] + new + text[m.end() :]
+
+
+SAME_CODE = re.compile(r"^Same code as (?P<tag>v\S+), released as \S+\.")
+
+
+def rolled_notes(path: str, tag: str, notes_out: str) -> None:
+    text = Path(path).read_text()
+    rolled = section(text, tag.removeprefix("v"))
+    if rolled is None:
+        sys.exit(f"{path} has no section for {tag}")
+    notes = text[rolled[1] : rolled[2]].strip()
+    if (m := SAME_CODE.match(notes)) and (shipped := section(text, m["tag"].removeprefix("v"))):
+        notes = f"{notes}\n\n{text[shipped[1] : shipped[2]].strip()}"
+    Path(notes_out).write_text(notes + "\n")
+
+
+def main(path: str, tag: str, previous: str, date: str, notes_out: str, at_head: str = "") -> None:
+    file = Path(path)
+    text = file.read_text()
+    version = tag.removeprefix("v")
+    unreleased = section(text, "Unreleased")
+    if unreleased is None:
+        return
+    _, body_start, body_end = unreleased
+    body = text[body_start:body_end].strip()
+    base = previous
+    if body:
+        notes = body
+        rolled = f"\n## [{version}] - {date}\n\n{body}\n\n"
+    elif at_head and (shipped := section(text, at_head.removeprefix("v"))):
+        shipped_body = text[shipped[1] : shipped[2]].strip()
+        base = at_head
+        notes = f"Same code as {at_head}, released as {tag}.\n\n{shipped_body}".strip()
+        rolled = f"\n## [{version}] - {date}\n\nSame code as {at_head}, released as {tag}.\n\n"
+    else:
+        return
+
+    text = text[:body_start] + rolled + text[body_end:].lstrip("\n")
+    file.write_text(update_links(text, version, base))
+    Path(notes_out).write_text(notes + "\n")
+
+
+if __name__ == "__main__":
+    if sys.argv[1:2] == ["--notes"]:
+        rolled_notes(*sys.argv[2:])
+    else:
+        main(*sys.argv[1:])

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

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  # PR runs supersede each other. Every other run gets its own group, so each
+  # push to main finishes CI and can be released.
+  group: ci-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history + tags for hatch-vcs versioning
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Format check
+        run: uv run ruff format --check src tests
+
+      - name: Test
+        run: uv run pytest

magpy_lite-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+name: Publish
+
+# Publishes to PyPI when a GitHub Release is published, or when release.yml
+# starts it on a new tag. It only runs on a vX.Y.Z tag.
+#
+# Uses PyPI Trusted Publishing (OIDC) — no API token/secret required. Before the
+# first release, configure a Trusted Publisher on PyPI for this project:
+#   PyPI → project "magpy-lite" → Settings → Publishing → add a GitHub publisher with
+#   owner=jmcmeen, repo=magpy-lite, workflow=publish.yml, environment=pypi.
+# Also create a GitHub environment named "pypi" (Settings → Environments).
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history + tags for hatch-vcs versioning
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Require a release tag on main
+        run: |
+          # Run by hand on a branch, this would build and upload a dev version;
+          # on a tag off main, code that never went through main and its CI.
+          if [ "$GITHUB_REF_TYPE" != tag ] || ! [[ "$GITHUB_REF_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Publish only runs on a vX.Y.Z tag, not $GITHUB_REF_TYPE '$GITHUB_REF_NAME'."
+            exit 1
+          fi
+          git fetch -q origin +refs/heads/main:refs/remotes/origin/main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_REF_NAME isn't on main; only release tags from main are published."
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: |
+          # Version from the tag this run is on, not `git describe`: when two
+          # tags share a commit, describe can pick the older one.
+          export SETUPTOOLS_SCM_PRETEND_VERSION="${GITHUB_REF_NAME#v}"
+          uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/magpy-lite
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true # a retried release re-dispatches this

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

@@ -0,0 +1,234 @@
+name: Release
+
+# Cuts a release when a merge to main passes CI: the latest vX.Y.Z tag gets its
+# patch number bumped (v0.1.0 if there are no tags yet). Merges that land while
+# a release is running can share the next release (see below), so a release is
+# per merge in the usual case, not guaranteed for each one.
+# Python packages take their version from that tag via hatch-vcs; a repo whose
+# version lives in files (e.g. Cargo.toml) provides .github/scripts/
+# set_version.sh, which is run with the new version (X.Y.Z). CHANGELOG.md's
+# [Unreleased] entries move under the new version in a github-actions[bot]
+# commit on main, along with any set_version.sh edits; that commit is what gets
+# tagged, and the entries become the release notes. If main has moved on by
+# then, nothing is pushed and this merge isn't released on its own: the release
+# for the newer merge includes it (a manual minor/major run says to run again).
+#
+# For a minor or major release, run this workflow by hand on main ("Run
+# workflow", or `gh workflow run release.yml -f bump=minor`). It releases the
+# head of main with that part bumped; the next merge continues from it. If the
+# merge was already released as a patch, the commit carries both tags. It
+# refuses to run until CI has passed on that commit. If a release is already
+# running and a merge's release queues behind your run, GitHub cancels your
+# pending run in its favour -- Actions shows it as cancelled; run it again.
+#
+# Releasing runs are serialized, and GitHub keeps only the newest pending one,
+# so merges that land close together can share a release. The lock is on the
+# job, so skipped runs (failed CI, dispatch off main) never take that slot.
+# A commit that is already inside the latest release is skipped, so an old run
+# finishing late never gets a newer version than the code after it. Re-running
+# a run whose release exists only re-dispatches publish.yml (which skips files
+# already on PyPI).
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version part to bump
+        type: choice
+        options: [minor, major, patch]
+        default: minor
+
+permissions:
+  contents: write # changelog commit, tag + release
+  actions: write # dispatch publish.yml
+
+jobs:
+  release:
+    name: Tag and release
+    if: >-
+      (github.event_name == 'workflow_run'
+        && github.event.workflow_run.conclusion == 'success'
+        && github.event.workflow_run.event == 'push')
+      || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release
+      cancel-in-progress: false
+    env:
+      SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
+      BUMP: ${{ inputs.bump || 'patch' }}
+      GH_TOKEN: ${{ github.token }}
+      BOT_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+          fetch-depth: 0 # all tags
+
+      - name: Require passing CI
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          # A release commit never runs CI (bot pushes don't trigger it), so
+          # check the commit it was made on.
+          tested=$SHA
+          if git rev-parse -q --verify HEAD^ > /dev/null &&
+            [ "$(git log -1 --format=%ae HEAD)" = "$BOT_EMAIL" ] &&
+            git log -1 --format=%s HEAD | grep -q '^Update changelog for '; then
+            tested=$(git rev-parse HEAD^)
+          fi
+          passed=$(gh run list --workflow ci.yml --commit "$tested" --event push \
+            --status success --json databaseId --jq length)
+          if [ "$passed" -eq 0 ]; then
+            echo "::error::CI hasn't passed on $tested yet; wait for it, then run this again."
+            exit 1
+          fi
+
+      - name: Compute version
+        id: version
+        run: |
+          semver='^v[0-9]+\.[0-9]+\.[0-9]+$'
+          bump() {
+            IFS=. read -r major minor patch <<< "${1#v}"
+            case "$BUMP" in
+              major) echo "v$((major + 1)).0.0" ;;
+              minor) echo "v$major.$((minor + 1)).0" ;;
+              *) echo "v$major.$minor.$((patch + 1))" ;;
+            esac
+          }
+          first() { if [ "$BUMP" = major ]; then echo v1.0.0; else echo v0.1.0; fi; }
+          # This commit's releases, oldest first: tags on it, or on a release
+          # commit the bot made on top of it.
+          ours=$(git tag --points-at HEAD | grep -E "$semver" || true)
+          for t in $(git tag --contains HEAD | grep -E "$semver" || true); do
+            if [ "$(git rev-parse "$t^{commit}^")" = "$(git rev-parse HEAD)" ] &&
+              [ "$(git log -1 --format=%ae "$t")" = "$BOT_EMAIL" ] &&
+              git log -1 --format=%s "$t" | grep -q '^Update changelog for '; then
+              ours="$ours $t"
+            fi
+          done
+          ours=$(printf '%s\n' $ours | grep . | sort -uV || true)
+          newest=$(printf '%s\n' $ours | tail -1)
+          if [ "$BUMP" = patch ]; then
+            # A patch run on a released commit retries its newest release.
+            retry=$newest
+          else
+            # A minor or major run retries only its own bump: a tag of this
+            # commit that is exactly that bump of the release before it, or the
+            # first release when there is none before it. (Asking for the same
+            # bump again on the same commit counts as a retry: releasing
+            # identical code under two new minor versions is never wanted.)
+            retry=
+            merged=$(git tag --merged HEAD | grep -E "$semver" || true)
+            for t in $ours; do
+              base=$(printf '%s\n' $merged "$t" | sort -uV | grep -B1 -xF "$t" | grep -vxF "$t" || true)
+              if { [ -n "$base" ] && [ "$(bump "$base")" = "$t" ]; } ||
+                { [ -z "$base" ] && [ "$t" = "$(first)" ]; }; then
+                retry=$t
+              fi
+            done
+          fi
+          if [ -n "$retry" ]; then
+            echo "$SHA is already $retry; retrying its release and publish."
+            echo "tag=$retry" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          latest=$(git tag --list 'v*' | grep -E "$semver" | sort -V | tail -1 || true)
+          if [ -z "$latest" ]; then
+            next=$(first)
+          elif git merge-base --is-ancestor HEAD "$latest" &&
+            ! printf '%s\n' $ours | grep -qxF "$latest"; then
+            echo "$SHA is already included in $latest; nothing to do."
+            exit 0
+          else
+            next=$(bump "$latest")
+          fi
+          echo "Releasing $next ($BUMP bump; previous: ${latest:-none})"
+          {
+            echo "tag=$next"
+            echo "new=true"
+            echo "previous=$latest"
+            echo "at_head=$newest"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Roll changelog and set version
+        id: changelog
+        if: steps.version.outputs.new == 'true'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+          PREVIOUS: ${{ steps.version.outputs.previous }}
+          AT_HEAD: ${{ steps.version.outputs.at_head }}
+        run: |
+          notes="$RUNNER_TEMP/notes.md"
+          # A re-run after this changelog commit reached main but the release
+          # wasn't created: release that commit, with the notes it rolled,
+          # rather than rolling $SHA again (that push would be rejected).
+          git fetch -q origin +refs/heads/main:refs/remotes/origin/main
+          rolled=$(git log --format='%H%x09%P%x09%ae%x09%s' "$SHA..origin/main" |
+            awk -F '\t' -v sha="$SHA" -v bot="$BOT_EMAIL" -v subject="Update changelog for $TAG" \
+              '$2 == sha && $3 == bot && $4 == subject { print $1 }')
+          if [ -n "$rolled" ]; then
+            echo "Release commit for $TAG is already on main ($rolled); releasing that."
+            echo "sha=$rolled" >> "$GITHUB_OUTPUT"
+            if git show "$rolled:CHANGELOG.md" > "$RUNNER_TEMP/CHANGELOG.md" 2> /dev/null &&
+              python3 .github/scripts/roll_changelog.py --notes "$RUNNER_TEMP/CHANGELOG.md" "$TAG" "$notes"; then
+              echo "notes=$notes" >> "$GITHUB_OUTPUT"
+            fi
+            exit 0
+          fi
+          if [ -f CHANGELOG.md ]; then
+            python3 .github/scripts/roll_changelog.py CHANGELOG.md "$TAG" "$PREVIOUS" \
+              "$(date -u +%Y-%m-%d)" "$notes" "$AT_HEAD"
+          fi
+          if [ -f .github/scripts/set_version.sh ]; then
+            bash .github/scripts/set_version.sh "${TAG#v}"
+          fi
+          # Stage everything, so files the hook creates or stages are included.
+          git add -A
+          if git diff --cached --quiet; then
+            echo "Nothing under [Unreleased] and no version files; using generated notes."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "$BOT_EMAIL"
+          git commit -qm "Update changelog for $TAG"
+          # Fast-forward only: if main moved past $SHA, leave it alone.
+          if git push origin HEAD:refs/heads/main; then
+            echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+            if [ -s "$notes" ]; then
+              echo "notes=$notes" >> "$GITHUB_OUTPUT"
+            else
+              echo "Nothing under [Unreleased]; using generated notes."
+            fi
+            exit 0
+          fi
+          git fetch -q origin +refs/heads/main:refs/remotes/origin/main
+          if [ "$(git rev-parse origin/main)" = "$SHA" ]; then
+            echo "::error::Pushing the release commit for $TAG failed, and main hasn't moved."
+            exit 1
+          fi
+          # Releasing $SHA as is would leave its entries under [Unreleased]
+          # (they'd appear in the next release too) and miss the version files.
+          echo "::notice::main moved past $SHA; not releasing $TAG here. The release for the newer merge includes this one (for a manual minor/major run, run it again)."
+          echo "skip=true" >> "$GITHUB_OUTPUT"
+
+      - name: Create release
+        if: steps.version.outputs.tag != '' && steps.changelog.outputs.skip != 'true'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+          TARGET: ${{ steps.changelog.outputs.sha || env.SHA }}
+          NOTES: ${{ steps.changelog.outputs.notes }}
+        run: |
+          if ! gh release view "$TAG" > /dev/null 2>&1; then
+            if [ -n "$NOTES" ]; then notes=(--notes-file "$NOTES"); else notes=(--generate-notes); fi
+            gh release create "$TAG" --target "$TARGET" --title "$TAG" "${notes[@]}"
+          fi
+          # A release made with GITHUB_TOKEN doesn't fire publish.yml's release
+          # trigger, so start it directly on the new tag. Repos with nothing to
+          # publish have no publish.yml.
+          if [ -f .github/workflows/publish.yml ]; then
+            gh workflow run publish.yml --ref "$TAG"
+          fi

magpy_lite-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+.venv/
+.env
+
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+.DS_Store
+.claude/settings.local.json
+.claude/*.local.json

magpy_lite-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

magpy_lite-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-17
+
+### Added
+
+- Placeholder Textual app (`magpy-lite`, `python -m magpy_lite`) announcing the project.
+

magpy_lite-0.1.0/CITATION.cff

@@ -0,0 +1,12 @@
+# Citation metadata (Citation File Format 1.2.0 — https://citation-file-format.github.io).
+# `version`/`date-released` are omitted so this file never drifts from the actual release.
+cff-version: 1.2.0
+title: "magpy-lite: Terminal interface for the bioamla bioacoustics toolkit"
+message: "If you use this software, please cite it using this metadata."
+type: software
+authors:
+  - family-names: McMeen
+    given-names: John
+    email: johnmcmeen@gmail.com
+repository-code: "https://github.com/jmcmeen/magpy-lite"
+license: MIT

magpy_lite-0.1.0/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## What this is
+
+magpy-lite is a **Textual TUI front end for the `bioamla` library**, the
+terminal sibling of MagPy (the PyQt6 GUI). bioamla owns the bioacoustics
+domain; magpy-lite owns the terminal UI and the mutable state a functional
+library can't hold. If you need domain functionality, add it to bioamla.
+
+**0.1.0 is a placeholder release**: one "coming soon" screen, no bioamla
+dependency yet. Features are planned as magpy and bioamla mature; don't invent
+screens that haven't been asked for.
+
+## Workflow
+
+- **The user handles all commits.** Make changes in the working tree and stop
+  there. Do not run `git commit`, and do not offer to, unless asked. Branching
+  and pushing likewise only on request. Work happens on `dev`; `main` releases.
+- Tooling (`Makefile`, CI, release workflow, ruff config) follows the laborae
+  workspace template; `make consistency` at the workspace root checks it. Don't
+  edit `.github/workflows/release.yml` or `.github/scripts/roll_changelog.py`
+  here; change the template instead.
+
+## Commands
+
+The project uses **`uv`**; the `Makefile` wraps the common tasks:
+
+```sh
+make install   # uv sync --extra dev
+make run       # launch the TUI (magpy-lite -> magpy_lite.app:main)
+make test      # uv run pytest
+make lint      # ruff check src tests
+make fmt       # ruff format + ruff check --fix
+make check     # lint + format check + test
+```
+
+`uv run python -m magpy_lite` also launches it. Python is `>=3.10`.
+
+## Layout
+
+- `src/magpy_lite/app.py` — the `App` subclass and the `main()` entry point.
+- `src/magpy_lite/__main__.py` — `python -m` shim.
+- Tests drive the app headlessly with Textual's `App.run_test()` inside
+  `asyncio.run()`; there is no pytest-asyncio dependency. Tests must never
+  block on real terminal input.
+
+## Rules
+
+- Keep runtime dependencies minimal: `textual` now, `bioamla` once a screen
+  calls into it. Check whether a package already arrives transitively before
+  declaring it.
+- Once bioamla is wired in, keep its imports in one layer (as MagPy does with
+  `services/`) so widgets never import bioamla directly.

magpy_lite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John McMeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

magpy_lite-0.1.0/Makefile

@@ -0,0 +1,73 @@
+# Makefile for magpy-lite development tasks.
+# Dependency resolution and environment management use uv (https://docs.astral.sh/uv/).
+
+.DEFAULT_GOAL := help
+
+UV ?= uv
+SRC := src
+TESTS := tests
+
+.PHONY: help install dev sync lock upgrade shell \
+        run \
+        test test-fast cov \
+        lint fmt fmt-check check \
+        clean
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+## --- Environment & dependencies (uv) ---
+
+install: ## Create venv and install the project with dev tooling
+	$(UV) sync --extra dev
+
+dev: install ## Alias for install
+
+sync: ## Sync the environment to the lockfile (incl. dev tooling)
+	$(UV) sync --extra dev
+
+lock: ## Resolve and write uv.lock
+	$(UV) lock
+
+upgrade: ## Upgrade locked dependencies to latest allowed versions
+	$(UV) lock --upgrade
+
+shell: ## Spawn a subshell with the project venv activated
+	$(UV) run $${SHELL:-bash}
+
+## --- Running ---
+
+run: ## Launch the TUI
+	$(UV) run magpy-lite
+
+## --- Testing ---
+
+test: ## Run the full test suite
+	$(UV) run --extra dev pytest
+
+test-fast: ## Run tests, skipping slow/integration markers
+	$(UV) run --extra dev pytest -m "not slow and not integration"
+
+cov: ## Run tests with coverage report
+	$(UV) run --extra dev pytest --cov --cov-report=term-missing
+
+## --- Linting & formatting (ruff) ---
+
+lint: ## Lint with ruff
+	$(UV) run --extra dev ruff check $(SRC) $(TESTS)
+
+fmt: ## Auto-format and apply lint fixes
+	$(UV) run --extra dev ruff format $(SRC) $(TESTS)
+	$(UV) run --extra dev ruff check --fix $(SRC) $(TESTS)
+
+fmt-check: ## Check formatting without modifying files
+	$(UV) run --extra dev ruff format --check $(SRC) $(TESTS)
+
+check: lint fmt-check test ## Run lint, format check, and tests
+
+## --- Housekeeping ---
+
+clean: ## Remove caches and test/coverage build artifacts
+	rm -rf .pytest_cache .ruff_cache .coverage htmlcov dist
+	find . -name .venv -prune -o -type d -name __pycache__ -prune -exec rm -rf {} +