pgntui 0.3.0__tar.gz → 0.3.2__tar.gz

{pgntui-0.3.0 → pgntui-0.3.2}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project are documented in this file.
 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).
 
+## [0.3.2] — 2026-06-04
+
+### Fixed
+- Recording writer errors during `_handle_frame` now surface in the status bar instead of being silently swallowed.
+- `pgntui --example` targeting an existing file path now prints a clean error instead of a `NotADirectoryError` traceback.
+
+## [0.3.1] — 2026-06-04
+
+### Fixed
+- Recording reader now parses timestamps as UTC. Replay frame deltas were unaffected, but CSV export and debug log absolute timestamps were off by the local UTC offset.
+
+### Changed
+- `test_iter_frames_honors_pause_with_sliding_resume` now polls instead of hard-sleeping; faster suite, less flake attractor.
+
 ## [0.3.0] — 2026-06-04
 
 Bedtime audit fix wave: concurrency, decoding, packaging, recording, platform paths,
@@ -87,6 +101,8 @@ validation, and CI gating. Captures audits A/B/C/D from `docs/audits/2026-06-04-
 
 Initial published release.
 
+[0.3.2]: https://github.com/phobicdotno/pgntui/releases/tag/v0.3.2
+[0.3.1]: https://github.com/phobicdotno/pgntui/releases/tag/v0.3.1
 [0.3.0]: https://github.com/phobicdotno/pgntui/releases/tag/v0.3.0
 [0.2.2]: https://github.com/phobicdotno/pgntui/releases/tag/v0.2.2
 [0.2.0]: https://github.com/phobicdotno/pgntui/releases/tag/v0.2.0

{pgntui-0.3.0 → pgntui-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgntui
-Version: 0.3.0
+Version: 0.3.2
 Summary: Cross-platform TUI for NMEA 2000 with canboat decoding and pluggable drivers
 Project-URL: Homepage, https://github.com/phobicdotno/pgntui
 Project-URL: Source, https://github.com/phobicdotno/pgntui

pgntui-0.3.2/docs/audits/2026-06-04-round2-audit.md

@@ -0,0 +1,71 @@
+# Round 2 Audit (2026-06-04, post fix-wave, pre 0.3.0)
+Branch: main @ 010e7de
+
+## Verification Results
+
+All 23 Round 1 findings verified PASS at HEAD.
+
+| Finding | Status | Evidence |
+|---|---|---|
+| A-1 | PASS | `app.py:346-351` iterates workers, calls `cancel()` on frame_loop group before `exit()` |
+| A-2 | PASS | `_writer_lock` guards `_handle_frame` snapshot (185-187) and `_stop_recording` swap (312-314) |
+| A-3 | PASS | `actisense.py:122` checks `self._stop.is_set()` at top of `while True` |
+| A-4 | PASS | `replay.py:73,79,97,109` — stop event respected in sleep and yield points |
+| A-5 | PASS | `__main__.py:255-260` — writer backstop in finally |
+| B-1 | PASS | `canboat.py:126-142` applies offset + resolution |
+| B-2 | PASS | `canboat.py:66,92` constructs and routes via `FastPacketReassembler` |
+| B-4 | PASS | `router.py:44` — None != 2 correctly skips |
+| B-6 | PASS | Writer/reader column order match; Frame priority+destination roundtrip |
+| B-7 | PASS | `containers/loader.py:45-63` rejects overlap |
+| B-8 | PASS | `themes/loader.py:54-61` validates gradient stops |
+| C-1 | PASS | `config.py:10` uses platformdirs |
+| C-2 | PASS | `signals/base.py:114-117,129-132` coerces thresholds to float |
+| C-3 | PASS | `pgntui.spec:9-12` includes examples/ + copy_metadata |
+| C-4 | PASS | `writer.py:23` uses `newline=""` |
+| C-5 | PASS | `config.py:46-47` catches TOMLDecodeError |
+| C-6 | PASS | `pyproject.toml:28` — `textual>=8.0` |
+| C-7 | PASS | `app.py:113` — typed `_view_pairs`; no property |
+| D-I1 | PASS | release.yml — test:10 / binaries:30 timeouts |
+| D-I2 | PASS | pypi + binaries declare `needs: test` |
+| D-I3 | PASS | pyproject.toml has [project.urls] |
+| D-I4 | PASS | README expanded to 174 lines |
+| D-I5 | PASS | packaging/README.md exists with runbook |
+
+## New Findings
+
+### NF-1: Reader parses UTC timestamps as local time
+- **File:** `src/pgntui/recording/reader.py:17`
+- **Severity:** P2 (replay speed correct via frame deltas; absolute timestamps off by UTC offset)
+- **What's wrong:** Writer formats with `tz=UTC`. Reader calls `datetime.strptime(...).timestamp()` on naive datetime, which Python interprets as local time. In UTC+2 every replayed timestamp is 7200s low. CSV export and debug log timestamps are wrong by the local UTC offset.
+- **Fix:** `datetime.strptime(parts[0], "%Y-%m-%d-%H:%M:%S.%f").replace(tzinfo=UTC).timestamp()` — one line.
+
+### NF-2: Hard 1.5s sleep in pause test
+- **File:** `tests/test_replay_mode.py:95`
+- **Severity:** Low (CI flake attractor; no prod impact)
+- **What's wrong:** `time.sleep(1.5)` to assert no frames during pause. Accumulates suite time and is fragile under scheduler jitter.
+- **Fix:** Replace with polling loop — exit early on `len(emitted) > 1` (fast-fail) capped at a budget.
+
+## Cross-fix Interaction Notes
+
+- **F3 + F4 (Offset + fast-packet):** Clean. `_decode_fields` applies offset on fully assembled payload. No fast-packet PGN in bundled DB has non-zero Offset, but code path is correct regardless.
+- **F5 + F2 in actisense.py:** Clean. `_stop` event in `__init__` + read_frames; `parse_frame` returns Frame with priority/destination.
+- **F6 + F2 in app.py:** Both present. Welcome text + worker cancel + _writer_lock + atomic swap all in HEAD.
+- **F6 + F2 in __main__.py:** Both present. platformdirs config path + TOMLDecodeError catch + SIGINT writer backstop all in HEAD.
+- **Writer/reader columns:** `[ts, priority, pgn, src, dst, len, *hex]` — exact alignment.
+- **Fast-packet duplicate frame 0 (same seq_id):** Second overwrites buffer with fresh state — N2K retransmit handled.
+- **Fast-packet malformed length=0xFF:** Buffer expires via `_expire_stale(5.0s)`. No garbage decode path.
+- **FastPacketReassembler thread safety:** Owned by CanboatDecoder, called only from single frame_loop worker. No concurrent access.
+
+## Test Suite
+
+- 156 tests passing
+- Real threads in: test_writer_race, test_app_worker_cancel_on_exit, test_replay_mode — all use event-sync or generous-timeout polling except NF-2's flat sleep
+- No network, no FS writes outside tmp_path
+- No global state mutation; test_fastpacket patches time.monotonic in local context manager
+- mypy --strict: clean
+- ruff: clean
+- No TODO/FIXME/HACK/XXX in src/
+
+## Verdict
+
+**Clean to ship 0.3.0.** All Round 1 findings fixed. NF-1 and NF-2 are minor: reader UTC offset doesn't break replay (frame deltas are correct) and the test sleep is a flake attractor not a prod bug. Fix in 0.3.1.

pgntui-0.3.2/docs/audits/2026-06-04-round3-audit.md

@@ -0,0 +1,79 @@
+# Round 3 Audit (post 0.3.1)
+Branch: main @ 71d5f78
+
+## NF-1 + NF-2 Verification
+
+- **NF-1 (reader UTC):** PASS — `recording/reader.py:20` does `.replace(tzinfo=UTC).timestamp()` correctly.
+- **NF-1 test:** PASS — `test_recording_roundtrip.py:52-55` asserts `abs(restored.timestamp - written.timestamp) < 1e-3`.
+- **NF-2 (polling pause):** PASS — `test_replay_mode.py` budget loop polls with 50ms quantum, fast-fails on leak. Sliding margin 20× test threshold.
+
+## Sweep A — Errors
+
+| Severity | File:line | Issue |
+|---|---|---|
+| OK | reader.py:27 | `except (ValueError, IndexError)` — line parser, returns None |
+| OK | fastpacket.py:158,167 | Skips bad PGN/length entries in pgns.json |
+| OK | containers/themes/signals/config loaders | All raise typed exceptions |
+| OK | __main__.py:139 | importlib.metadata fallback |
+| OK | __main__.py:157 | driver.open exception → stderr + None (correct for optional hardware) |
+| OK | app.py:175 | Frame loop safety net logs to UI |
+| **SILENT** | **app.py:190** | **`except Exception: pass` on writer.write() — silent drop on disk full or closed file** |
+| OK | app.py:273 | Pre-mount _set_status guard |
+| OK | app.py:339,349 / __main__.py:250,259 | Defensive teardown finals |
+
+### NF-3 (P3): app.py:190 silent write error
+- **What's wrong:** Recording writer.write() error silently swallowed. On full disk or closed file the recording silently stops while UI shows "REC -> filename".
+- **Fix:** One-liner — `self.call_from_thread(self._set_status, f"rec error: {e}")` in the except block.
+
+## Sweep B — Resources
+
+- All file handles via `with` blocks or explicit close in finally/close()
+- `_writer_lock`, `_stop` Events properly initialized, no deadlock risk
+- No subprocess, signal handlers, or fork calls
+- `CSVSignalLogger` not currently wired into PgntuiApp (standalone) — no live handle leak
+
+## Sweep C — Public API
+
+- `__init__.py` exports only `__version__`. Minimal.
+- entry-points correct: `actisense-ngt1 → NGT1Driver`, `file-replay → FileReplayDriver`. Both verified to exist + implement Driver Protocol.
+- Minor: `__main__.py` imports `_default_workspace` (leading-underscore) from config. Convention violation, not functional bug.
+
+## Sweep D — CLI UX
+
+- `--help` documents `--workspace`, `--enable-write`, `--check`, `--example`, `replay` ✓
+- `pgntui replay` (no file) → argparse usage error ✓
+- `pgntui --example /path/to/file` → `iterdir()` raises `NotADirectoryError` traceback
+- `pgntui --workspace /no/such/dir` → silent default config + welcome (reasonable)
+- `pgntui replay --help` → argparse subparser help ✓
+
+### NF-4 (P3): __main__.py:59 --example handles file path poorly
+- **What's wrong:** `--example` targeting an existing file (not dir) raises `NotADirectoryError` instead of clean message.
+- **Fix:** One-liner — `if workspace.is_file(): print("error: workspace path is a file"); return 1` before iterdir.
+
+## Sweep E — Wheel hygiene
+
+Verified via pyproject.toml static analysis (build not run):
+- All force-include entries map to real files
+- `decode/fastpacket.py` covered by packages=[src/pgntui] auto-discovery ✓
+- `examples/__pycache__/` exists on disk (cosmetic; hatchling excludes by default)
+- entry_points.txt derived correctly
+- [project.urls] complete ✓
+
+## Sweep F — Docs accuracy
+
+- README.md: install, quickstart, workspace, themes, hotkeys, status — all match code ✓
+- packaging/README.md: runbook executable; example version `0.2.2` is a template (cosmetic)
+- CHANGELOG.md: 0.3.1 + 0.3.0 entries match commits ✓
+- release-notes-v0.3.0.md: test count 95→156 accurate ✓
+
+## Verdict
+
+| Round | New P0/P1 | New P2 | New P3 |
+|---|---|---|---|
+| 1 | 5 | 13 | 12 |
+| 2 | 0 | 1 (NF-1) | 1 (NF-2) |
+| 3 | 0 | 0 | 2 (NF-3, NF-4) |
+
+**Severity distribution this round: P0=0 P1=0 P2=0 P3=2.**
+
+**Recommendation: STOP.** NF-3 and NF-4 are both edge-case P3s with trivial one-liner fixes. The codebase is clean to leave at 0.3.1, or alternatively ship 0.3.2 with both P3 fixes bundled (~10 min of work). After that, expected diminishing returns from further audit rounds.

{pgntui-0.3.0 → pgntui-0.3.2}/packaging/homebrew/pgntui.rb

@@ -3,7 +3,7 @@
 class Pgntui < Formula
   desc "Cross-platform TUI for NMEA 2000 with canboat decoding"
   homepage "https://github.com/phobicdotno/pgntui"
-  url "https://files.pythonhosted.org/packages/source/p/pgntui/pgntui-0.3.0.tar.gz"
+  url "https://files.pythonhosted.org/packages/source/p/pgntui/pgntui-0.3.2.tar.gz"
   sha256 "REPLACE_ON_RELEASE"
   license "MIT"
 

{pgntui-0.3.0 → pgntui-0.3.2}/packaging/winget/phobic.pgntui.yaml

@@ -1,6 +1,6 @@
 # Stub manifest for microsoft/winget-pkgs PR
 PackageIdentifier: phobic.pgntui
-PackageVersion: 0.3.0
+PackageVersion: 0.3.2
 PackageLocale: en-US
 Publisher: phobic
 PackageName: pgntui
@@ -15,7 +15,7 @@ Tags: [nmea, marine, tui, terminal]
 Installers:
   - Architecture: x64
     InstallerType: portable
-    InstallerUrl: https://github.com/phobicdotno/pgntui/releases/download/v0.3.0/pgntui-windows-x86_64.exe
+    InstallerUrl: https://github.com/phobicdotno/pgntui/releases/download/v0.3.2/pgntui-windows-x86_64.exe
     InstallerSha256: REPLACE_ON_RELEASE
 ManifestType: singleton
 ManifestVersion: 1.6.0

{pgntui-0.3.0 → pgntui-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pgntui"
-version = "0.3.0"
+version = "0.3.2"
 description = "Cross-platform TUI for NMEA 2000 with canboat decoding and pluggable drivers"
 readme = "README.md"
 requires-python = ">=3.11"

{pgntui-0.3.0 → pgntui-0.3.2}/src/pgntui/__init__.py

@@ -1,3 +1,3 @@
 """pgntui — NMEA 2000 TUI."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{pgntui-0.3.0 → pgntui-0.3.2}/src/pgntui/__main__.py

@@ -56,6 +56,13 @@ def scaffold_example(workspace: Path) -> int:
     Refuses to clobber an existing directory — the user must point at a fresh
     path or delete the old one.
     """
+    if workspace.is_file():
+        print(
+            f"workspace path {workspace} is a file, not a directory. "
+            "Pass --workspace <other> or delete the file.",
+            file=sys.stderr,
+        )
+        return 2
     if workspace.exists() and any(workspace.iterdir()):
         print(
             f"workspace exists at {workspace}, refusing to overwrite. "

{pgntui-0.3.0 → pgntui-0.3.2}/src/pgntui/app.py

@@ -187,8 +187,8 @@ class PgntuiApp(App[None]):
         if writer is not None:
             try:
                 writer.write(frame)
-            except Exception:  # pragma: no cover — defensive
-                pass
+            except Exception as e:  # pragma: no cover — defensive
+                self.call_from_thread(self._set_status, f"rec error: {e}")
         decoded = self._decoder.decode(frame)
         if decoded is None:
             return

{pgntui-0.3.0 → pgntui-0.3.2}/src/pgntui/recording/reader.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterator
-from datetime import datetime
+from datetime import UTC, datetime
 from pathlib import Path
 
 from pgntui.drivers.base import Frame
@@ -14,7 +14,10 @@ def parse_line(line: str) -> Frame | None:
     if len(parts) < 7:
         return None
     try:
-        ts = datetime.strptime(parts[0], "%Y-%m-%d-%H:%M:%S.%f").timestamp()
+        # Writer emits UTC timestamps via datetime.utcfromtimestamp; parse
+        # them back as UTC so .timestamp() returns the original epoch value
+        # rather than shifting by the local UTC offset.
+        ts = datetime.strptime(parts[0], "%Y-%m-%d-%H:%M:%S.%f").replace(tzinfo=UTC).timestamp()
         priority = int(parts[1])
         pgn = int(parts[2])
         src = int(parts[3])

{pgntui-0.3.0 → pgntui-0.3.2}/tests/test_app_record_toggle.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
 
 import pytest
 
@@ -94,3 +95,57 @@ async def test_record_writer_receives_frames(tmp_path: Path) -> None:
             assert writer.frame_count >= 0
         app.action_toggle_record()
         await pilot.pause()
+
+
+class _RaisingWriter:
+    """Stand-in writer whose write() always blows up."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.opened = False
+        self.closed = False
+
+    def open(self) -> None:
+        self.opened = True
+
+    def close(self) -> None:
+        self.closed = True
+
+    def write(self, _frame: Frame) -> None:
+        raise OSError("disk full")
+
+
+@pytest.mark.asyncio
+async def test_record_write_error_surfaces_to_status(tmp_path: Path) -> None:
+    """When the writer's write() raises, the status bar shows 'rec error'."""
+    import asyncio
+
+    app = PgntuiApp(
+        theme=load_builtin("dark"),
+        containers=[],
+        decoder=CanboatDecoder.load_bundled(),
+        router=SignalRouter(),
+        record_dir=tmp_path / "rec",
+    )
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        # Inject a raising writer directly so we don't depend on the real
+        # ActisenseLogWriter for failure simulation.
+        bad_writer: Any = _RaisingWriter(tmp_path / "rec" / "fake.pgnlog")
+        with app._writer_lock:
+            app._writer = bad_writer
+            app._writer_path = bad_writer.path
+        frame = Frame(timestamp=1.0, source_addr=23, pgn=127488, data=b"\x00" * 8)
+        # _handle_frame runs on the worker thread in production. Use
+        # asyncio.to_thread so `call_from_thread` runs from a non-event-loop
+        # thread and can marshal the status update back without deadlocking.
+        await asyncio.to_thread(app._handle_frame, frame)
+        await pilot.pause()
+        # Status bar should reflect the recording error rather than silently
+        # carrying on as if writes were succeeding.
+        from textual.widgets import Static
+
+        status = app.query_one("#status-bar", Static)
+        rendered = str(status.render())
+        assert "rec error" in rendered
+        assert "disk full" in rendered

{pgntui-0.3.0 → pgntui-0.3.2}/tests/test_example_workspace.py

@@ -65,3 +65,13 @@ def test_example_works_with_brand_new_workspace_dir(tmp_path: Path) -> None:
     ws.mkdir()  # empty dir is OK
     rc = main(["--workspace", str(ws), "--example"])
     assert rc == 0
+
+
+def test_example_refuses_file_path(tmp_path: Path, capsys) -> None:  # type: ignore[no-untyped-def]
+    """Pointing --example at an existing file (not dir) errors cleanly."""
+    tmp_file = tmp_path / "notadir.txt"
+    tmp_file.write_text("oops")
+    rc = main(["--workspace", str(tmp_file), "--example"])
+    assert rc == 2
+    captured = capsys.readouterr()
+    assert "is a file" in captured.err

{pgntui-0.3.0 → pgntui-0.3.2}/tests/test_recording_roundtrip.py

@@ -49,14 +49,10 @@ def test_write_read_roundtrip_preserves_all_fields(tmp_path: Path) -> None:
         assert restored.data == written.data
         assert restored.priority == written.priority
         assert restored.destination == written.destination
-        # NOTE: timestamp roundtrip has a pre-existing timezone mismatch
-        # (writer formats as UTC, reader parses naively as local time). That's
-        # out of scope for the B-6/C-4 fix and is left for a separate audit.
-        # We still assert sub-second precision is preserved (ms via the writer's
-        # "%Y-%m-%d-%H:%M:%S.%f"[:-3] truncation), modulo whole-second TZ offsets.
-        sub_second_written = written.timestamp - int(written.timestamp)
-        sub_second_restored = restored.timestamp - int(restored.timestamp)
-        assert abs(sub_second_restored - sub_second_written) < 1e-3
+        # Reader now parses as UTC (NF-1), so the absolute timestamp survives
+        # the roundtrip modulo the writer's millisecond truncation
+        # ("%Y-%m-%d-%H:%M:%S.%f"[:-3] drops microsecond precision).
+        assert abs(restored.timestamp - written.timestamp) < 1e-3
 
 
 def test_writer_uses_lf_only(tmp_path: Path) -> None:

{pgntui-0.3.0 → pgntui-0.3.2}/tests/test_replay_mode.py

@@ -88,12 +88,15 @@ def test_iter_frames_honors_pause_with_sliding_resume(tmp_path: Path) -> None:
 
     # Pause immediately; the inter-frame sleep before frame 2 is in progress.
     # Frames 2 (+500ms) and 3 (+1000ms) would normally land within the next
-    # ~1000ms. Sleep through a longer 1.5s window — well past when both
-    # frames would have emitted under nominal timing — and confirm neither
-    # arrives. The wider window absorbs CI runner jitter and scheduler stalls.
+    # ~1000ms. Poll across a 1.5s budget and fail-fast the moment a frame
+    # leaks through — keeps the suite snappy while still absorbing CI jitter.
     s.toggle_pause()
-    time.sleep(1.5)
-    assert len(emitted) == 1, f"no frames should be emitted while paused; got {len(emitted)}"
+    budget_end = time.monotonic() + 1.5
+    while time.monotonic() < budget_end:
+        if len(emitted) > 1:
+            break  # leak detected, will assert below
+        time.sleep(0.05)
+    assert len(emitted) == 1, f"pause leaked: emitted={len(emitted)}"
 
     # Resume — frame 2 should arrive after the leftover inter-frame delay
     # (sliding semantics), not instantly (which would mean catching up the

{pgntui-0.3.0 → pgntui-0.3.2}/tests/test_smoke.py

@@ -2,7 +2,7 @@ from pgntui import __version__
 
 
 def test_version() -> None:
-    assert __version__ == "0.3.0"
+    assert __version__ == "0.3.2"
 
 
 def test_main_returns_zero() -> None: