Asteroids!

.envrc

@@ -0,0 +1,4 @@
+use nix
+watch_file flake.nix flake.lock shell.nix
+watch_file nixos/pkgs/uv-python.nix
+watch_file python/pyproject.toml python/uv.lock

.github/scripts/update_manifest.py

@@ -4,11 +4,19 @@
 import argparse
 import json
 import re
+import urllib.error
+import urllib.request
 from datetime import datetime, timezone
 from pathlib import Path
 
 
 STORE_PATH_RE = re.compile(r"^/nix/store/[a-z0-9]+-[A-Za-z0-9._+=?,-]+$")
+
+# The binary caches devices resolve upgrades from. A build is only advertised
+# as available once one of these actually serves its narinfo — see set_available.
+DEV_CACHE = "https://cache.pifinder.eu/pifinder"
+RELEASE_CACHE = "https://cache.pifinder.eu/pifinder-release"
+DEFAULT_CACHES = (DEV_CACHE, RELEASE_CACHE)
 EMPTY_MANIFEST = {
     "schema": 1,
     "generated_at": None,
@@ -49,14 +57,54 @@ def valid_store_path(value: str | None) -> bool:
     return isinstance(value, str) and STORE_PATH_RE.fullmatch(value) is not None
 
 
-def set_available(entry: dict) -> dict:
-    if valid_store_path(entry.get("store_path")):
-        entry["available"] = True
-        entry.pop("reason", None)
-    else:
+def _narinfo_url(store_path: str, cache: str) -> str:
+    digest = Path(store_path).name.split("-", 1)[0]
+    return f"{cache.rstrip('/')}/{digest}.narinfo"
+
+
+def cache_serves(store_path: str, caches, timeout: int = 15) -> bool | None:
+    """Whether the closure is actually downloadable from a cache right now.
+
+    Returns True if any cache serves the narinfo (200); False only if every
+    cache answered and none had it (a real 404 everywhere); None if a cache
+    could not be reached, so presence is unknown. Publishing treats anything
+    other than True as "do not advertise", so a failed push or a down cache can
+    never advertise a build the device cannot fetch.
+    """
+    saw_404 = False
+    for cache in caches:
+        url = _narinfo_url(store_path, cache)
+        try:
+            with urllib.request.urlopen(url, timeout=timeout) as resp:
+                if resp.status == 200:
+                    return True
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                saw_404 = True
+            else:
+                return None
+        except (urllib.error.URLError, OSError, TimeoutError):
+            return None
+    return False if saw_404 else None
+
+
+def set_available(entry: dict, caches=DEFAULT_CACHES, verify: bool = True) -> dict:
+    store_path = entry.get("store_path")
+    if not valid_store_path(store_path):
         entry["store_path"] = None
         entry["available"] = False
         entry.setdefault("reason", "no build")
+        return entry
+
+    if verify:
+        present = cache_serves(store_path, caches)
+        if present is not True:
+            entry["available"] = False
+            entry["reason"] = "not in cache" if present is False else "cache unreachable"
+            return entry
+
+    entry["available"] = True
+    entry.pop("reason", None)
     return entry
 
 
@@ -79,11 +127,17 @@ def key(item: dict) -> tuple[int, int, str]:
     return sorted(entries, key=key)
 
 
+def resolve_verify(args: argparse.Namespace) -> tuple[tuple[str, ...], bool]:
+    caches = tuple(args.verify_cache) if args.verify_cache else DEFAULT_CACHES
+    return caches, not args.skip_cache_check
+
+
 def update_build(args: argparse.Namespace) -> None:
     manifest = load_manifest(args.manifest)
     channels = manifest["channels"]
     store_path = args.store_path or None
     short_sha = (args.head_sha or args.sha)[:7]
+    caches, verify = resolve_verify(args)
 
     if args.pr_number:
         number = int(args.pr_number)
@@ -100,7 +154,7 @@ def update_build(args: argparse.Namespace) -> None:
             "store_path": store_path,
             "built_at": now_iso(),
         }
-        set_available(entry)
+        set_available(entry, caches, verify)
         channels["unstable"] = replace_entry(
             channels["unstable"],
             lambda item: item.get("kind") == "pr"
@@ -120,7 +174,7 @@ def update_build(args: argparse.Namespace) -> None:
             "store_path": store_path,
             "built_at": now_iso(),
         }
-        set_available(entry)
+        set_available(entry, caches, verify)
         channels["unstable"] = replace_entry(
             channels["unstable"],
             lambda item: item.get("kind") == "trunk"
@@ -135,6 +189,7 @@ def update_build(args: argparse.Namespace) -> None:
 
 def update_release(args: argparse.Namespace) -> None:
     manifest = load_manifest(args.manifest)
+    caches, verify = resolve_verify(args)
     channel = "beta" if args.release_type == "beta" else "stable"
     entry = {
         "kind": "release",
@@ -150,7 +205,7 @@ def update_release(args: argparse.Namespace) -> None:
         "migration_sha256_url": args.migration_sha256_url or None,
         "built_at": now_iso(),
     }
-    set_available(entry)
+    set_available(entry, caches, verify)
     manifest["channels"][channel] = replace_entry(
         manifest["channels"][channel],
         lambda item: item.get("kind") == "release" and item.get("label") == args.tag,
@@ -159,6 +214,17 @@ def update_release(args: argparse.Namespace) -> None:
     save_manifest(args.manifest, manifest)
 
 
+def add_cache_args(sub: argparse.ArgumentParser) -> None:
+    # A build is advertised as available only if one of these caches actually
+    # serves its narinfo. Repeatable; defaults to the dev + release caches.
+    sub.add_argument("--verify-cache", action="append", metavar="URL")
+    sub.add_argument(
+        "--skip-cache-check",
+        action="store_true",
+        help="advertise on store-path syntax alone (tests / offline only)",
+    )
+
+
 def parser() -> argparse.ArgumentParser:
     root = argparse.ArgumentParser()
     sub = root.add_subparsers(dest="command", required=True)
@@ -176,6 +242,7 @@ def parser() -> argparse.ArgumentParser:
     build.add_argument("--head-repo")
     build.add_argument("--head-ref")
     build.add_argument("--head-sha")
+    add_cache_args(build)
     build.set_defaults(func=update_build)
 
     release = sub.add_parser("release")
@@ -190,6 +257,7 @@ def parser() -> argparse.ArgumentParser:
     release.add_argument("--migration-sha256-url")
     release.add_argument("--title")
     release.add_argument("--notes")
+    add_cache_args(release)
     release.set_defaults(func=update_release)
 
     return root

.github/workflows/nox.yml

@@ -1,4 +1,9 @@
 name: nox
+# The nixos branch manages the Python environment with uv (pyproject.toml +
+# uv.lock) instead of nox + requirements*.txt, so this runs the same checks
+# (ruff, mypy, pytest) through uv. The workflow keeps upstream's "nox" name so
+# PR check wiring stays identical across branches.
+#
 # Run on pushes to the long-lived branches and on pull requests. Restricting
 # `push` to main/release means a push to a feature branch with an open PR only
 # triggers the `pull_request` run (not also a `push` run), so a PR gets a single
@@ -18,9 +23,21 @@ jobs:
         working-directory: ./python
     steps:
       - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
         with:
-          submodules: true
-      - uses: wntrblm/nox@2024.04.15
-        with:
-          python-versions: "3.9"
-      - run: nox -s lint format type_hints smoke_tests unit_tests ui_tests
+          enable-cache: true
+      # Same ruff pin as upstream main's noxfile, so shared files keep one style.
+      - name: Lint
+        run: uvx ruff@0.4.8 check --config "builtins=['_']" .
+      - name: Format check
+        run: uvx ruff@0.4.8 format --check .
+      - name: Sync environment
+        run: uv sync --frozen
+      - name: Type check
+        run: uv run mypy PiFinder
+      - name: Smoke tests
+        run: uv run pytest -m smoke
+      - name: Unit tests
+        run: uv run pytest -m unit
+      - name: UI module tests
+        run: uv run pytest -m integration tests/test_ui_modules.py

.gitignore

@@ -155,10 +155,16 @@ case/my_printer
 .direnv/
 **/.claude/*
 !**/.claude/skills/
+.agents/
+.codex/
 .serena/
 astro_data/comets.txt
 
 # users GPS data
 test_ubx
 test_ubx/*
 python/telemetry_analysis/
+
+# nix build result symlinks
+result
+result-*

.pre-commit-config.yaml

@@ -1,15 +1,27 @@
-# See https://pre-commit.com for more information
-# See https://pre-commit.com/hooks.html for more hooks
 repos:
-  - repo: https://github.com/saltstack/mirrors-nox
-    rev: 'v2022.11.21'  # Use the sha / tag you want to point at
+  - repo: local
     hooks:
-      - id: nox
-        files: ^.*\.py$
-        args:
-          - -f
-          - python/noxfile.py
-          - -s
-          - type_hints
-          - smoke_tests
-          - --
+      - id: ruff-lint
+        name: ruff lint
+        entry: bash -c 'cd python && ruff check'
+        language: system
+        files: ^python/.*\.py$
+        pass_filenames: false
+      - id: ruff-format
+        name: ruff format check
+        entry: bash -c 'cd python && ruff format --check'
+        language: system
+        files: ^python/.*\.py$
+        pass_filenames: false
+      - id: mypy
+        name: mypy type check
+        entry: bash -c 'cd python && mypy .'
+        language: system
+        files: ^python/.*\.py$
+        pass_filenames: false
+      - id: smoke-tests
+        name: smoke tests
+        entry: bash -c 'cd python && pytest -m smoke'
+        language: system
+        files: ^python/.*\.py$
+        pass_filenames: false

CLAUDE.md

@@ -22,65 +22,46 @@ Maintainers can make `fresh` root on `main` automatically per clone (without cha
 git remote set-head origin main
 ```
 
-**Initialise the `tetra3` submodule in every new worktree.** `python/PiFinder/tetra3` is a git submodule (the `cedar-solve`/Tetra3 solver); the importable package is its inner `tetra3/tetra3/` dir, surfaced through the tracked symlink `python/tetra3`. `git worktree add` / `EnterWorktree` does **not** populate submodules, so a fresh worktree starts with an empty submodule dir and a dangling symlink. Any test that imports the solver then fails with `ModuleNotFoundError: No module named 'tetra3'` (or `cedar_detect_pb2`) — this is a missing checkout, **not** a code problem, so don't reach for `PYTHONPATH` hacks. Fix it once per worktree:
-
-```bash
-git submodule update --init python/PiFinder/tetra3
-```
-
-mypy also needs this: its config points at `python/PiFinder/tetra3/tetra3`, so `nox -s type_hints` can't run in a worktree until the submodule is initialised.
+**No tetra3 submodule on this branch.** Unlike upstream `main`, the solver
+(`cedar-solve`/Tetra3) is an ordinary uv dependency (pinned git rev in
+`python/pyproject.toml`), so worktrees need no `git submodule` step.
 
 ## Development Commands
 
-**Running Python**
-Developers may have created virtual environments in directories like ".venv" or "venv". Make sure these virtual
-environments are activated before any of the python based tools below.
-
-**Development workflow uses Nox for task automation:**
-```bash
-nox -s lint          # Code linting with Ruff (auto-fixes issues)
-nox -s format        # Code formatting with Ruff
-nox -s type_hints    # Type checking with MyPy
-nox -s smoke_tests   # Quick functionality validation
-nox -s unit_tests    # Full unit test suite
-nox -s babel         # I18n message extraction and compilation
-nox -s web_tests     # Testing the webserver, see below
-```
-
-**Direct testing with pytest:**
-```bash
-pytest -m smoke      # Smoke tests for core functionality
-pytest -m unit       # Unit tests for isolated components
-pytest -m integration # End-to-end integration tests
-```
+**This branch uses uv (pyproject.toml + uv.lock), not nox/requirements*.txt.**
+All Python tooling runs through uv from `python/`:
 
-**Development setup:**
 ```bash
 cd python/
-python3.9 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-pip install -r requirements_dev.txt
+uv sync --frozen                                  # create/refresh .venv from uv.lock
+uvx ruff@0.4.8 check --config "builtins=['_']" .  # lint (same pin as CI / upstream noxfile)
+uvx ruff@0.4.8 format .                           # format
+uv run mypy PiFinder                              # type checking
+uv run pytest -m smoke                            # smoke tests
+uv run pytest -m unit                             # unit tests
+uv run pytest -m integration tests/test_ui_modules.py  # UI module harness
 ```
-If the .venv dir already exists, you can directly source it and run the app.
 
+CI (`.github/workflows/nox.yml` — keeps the upstream "nox" check name) runs
+exactly these commands.
 
-Watch out for .venv directories containing virtual environments, that you need to activate first. 
+NixOS dev-box note: manylinux wheels (numpy etc.) need `libstdc++`; if imports
+fail with `libstdc++.so.6: cannot open shared object file`, run tests with
+`LD_LIBRARY_PATH=$(nix build --print-out-paths nixpkgs#stdenv.cc.cc.lib)/lib`.
 
 **Running the application:**
 
 First start the `cedar-detect-server` which is in `bin` (you need to use `-p 50551`, when invoking it).
-Use the correct architecture suffix for cedar-detect-server according to the platform you're running on. 
+Use the correct architecture suffix for cedar-detect-server according to the platform you're running on.
 
-Development setup has to have run and you should be in .venv virtual environment
 ```bash
 cd python/
-python -m PiFinder.main [options]
+uv run python -m PiFinder.main [options]
 ```
 Usual startup:
 
 ```bash
-python3.9 -m PiFinder.main -fh --camera debug --keyboard local -x
+uv run python -m PiFinder.main -fh --camera debug --keyboard local -x
 ```
 
 ## Reference Documentation
@@ -191,6 +172,39 @@ Tests use pytest with custom markers for different test types. The smoke tests p
 - **Linting:** Ruff with Python 3.9 target, Black-compatible formatting
 - **Type Checking:** MyPy with gradual typing adoption
 - **Code Style:** 88-character line length, double quotes, space indentation
+- **Comments:** describe what the code does now, not how it changed. No "previously / no longer / used to / moved from" — history lives in git/jj, not in comments.
 - **I18n Support:** Babel integration for multi-language UI
 
 The codebase follows modern Python practices with type hints, comprehensive testing, and automated code quality checks integrated into the development workflow.
+
+## NixOS Development
+
+**CRITICAL: Never run `nix build` or `nix eval` on Pi 4 targets.** The Pi 4 lacks sufficient resources and will hang/crash. Always build on pi5.local (GitHub Actions runner), push to Attic, then trigger the upgrade service:
+```bash
+# Build on pi5
+ssh pi5.local 'nix build --no-link --print-out-paths github:mrosseel/PiFinder/nixos#nixosConfigurations.pifinder.config.system.build.toplevel'
+# Push to Attic (so Pi can download signed paths)
+ssh pi5.local 'attic push pifinder:pifinder <store-path>'
+# Trigger upgrade on target Pi (downloads from Attic, activates, reboots)
+ssh pifinder@<target-ip> 'echo "<store-path>" > /run/pifinder/upgrade-ref && sudo systemctl start --no-block pifinder-upgrade.service'
+# Monitor progress
+ssh pifinder@<target-ip> 'cat /run/pifinder/upgrade-status'
+```
+
+**Netboot deployment (dev Pi on proxnix NFS):**
+```bash
+./deploy-image-to-nfs.sh    # Build and deploy to NFS
+```
+
+**Power control (Shelly plug via Home Assistant):**
+```bash
+~/.local/bin/pifinder-power-off.sh   # Turn off PiFinder
+~/.local/bin/pifinder-power-on.sh    # Turn on PiFinder
+```
+
+**Check Pi status:**
+```bash
+ssh pifinder@192.168.5.146           # SSH to netboot Pi
+systemctl status pifinder            # Check service status
+journalctl -u pifinder -f            # Follow service logs
+```