boost-skill-cli 1.0.239__tar.gz → 1.0.241__tar.gz

{boost_skill_cli-1.0.239 → boost_skill_cli-1.0.241}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.239
+Version: 1.0.241
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.239 → boost_skill_cli-1.0.241}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.239'
-__version_tuple__ = version_tuple = (1, 0, 239)
+__version__ = version = '1.0.241'
+__version_tuple__ = version_tuple = (1, 0, 241)
 
 __commit_id__ = commit_id = None

boost_skill_cli-1.0.241/boost_cli/core/journal.py

@@ -0,0 +1,114 @@
+"""The pulse journal: append-only feed of skill-management events.
+
+Powers `boost pulse`, `boost trending`, `boost stats`, and `boost who`.
+"""
+from __future__ import annotations
+
+import json
+from typing import List, Optional
+
+from . import paths, util
+
+ROTATE_AT = 5000
+ROTATE_KEEP = 2500
+
+
+def log(action: str, subject: str = "", **fields) -> None:
+    """Append one event line to the pulse feed, rotating when oversized.
+
+    None-valued keyword fields are dropped from the record.
+    """
+    paths.ensure_dirs()
+    event = {"ts": util.now_iso(), "user": util.user(), "action": action,
+             "subject": subject}
+    event.update({k: v for k, v in fields.items() if v is not None})
+    p = paths.pulse_path()
+    with p.open("a") as f:
+        f.write(json.dumps(event) + "\n")
+    _maybe_rotate()
+
+
+def events(n: Optional[int] = None, action: Optional[str] = None,
+           subject: Optional[str] = None) -> List[dict]:
+    """Most-recent-first list of journal events."""
+    p = paths.pulse_path()
+    if not p.exists():
+        return []
+    out = []
+    # errors="replace": one torn append must not make the whole feed
+    # unreadable — the corrupt line simply fails to parse as JSON below.
+    for line in p.read_text(encoding="utf-8", errors="replace").splitlines():
+        try:
+            e = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if action and e.get("action") != action:
+            continue
+        if subject and e.get("subject") != subject:
+            continue
+        out.append(e)
+    out.reverse()
+    return out[:n] if n else out
+
+
+def _line_count(p) -> int:
+    """Lines in `p`, closing the handle rather than leaving it to the GC.
+
+    Decodes leniently: the feed carries user-supplied text and a torn append
+    can leave a partial multi-byte sequence behind. A strict decode raises
+    UnicodeDecodeError, which is a ValueError — it would sail past the OSError
+    guard below and take down every command that logs, forever, over one bad
+    byte in an advisory feed.
+    """
+    with p.open(encoding="utf-8", errors="replace") as f:
+        return sum(1 for _ in f)
+
+
+def rotation_healthy() -> bool:
+    """True when the pulse feed is absent or at most ROTATE_AT lines long."""
+    p = paths.pulse_path()
+    if not p.exists():
+        return True
+    return _line_count(p) <= ROTATE_AT
+
+
+def _maybe_rotate() -> None:
+    """Trim the feed to ROTATE_KEEP lines once it passes ROTATE_AT.
+
+    Rotation is a read-modify-write of the whole file, and this repo's own
+    working model expects concurrent boost processes. Unserialized, two of
+    them could each read the feed, each build a snapshot, and the second
+    write would silently drop whatever the first had appended in between.
+
+    So rotation runs under a lock, and a process that cannot take it simply
+    returns: another one is already trimming, and doing it twice adds nothing.
+    Inside the lock the file is re-read — the count that got us here was taken
+    outside it and may already be stale — and anything appended between that
+    read and the swap is carried into the new file rather than dropped.
+    `log()` itself stays lock-free: O_APPEND writes of a single short record
+    do not tear, and making every command contend on a lock to protect an
+    advisory feed would be a bad trade.
+    """
+    p = paths.pulse_path()
+    try:
+        if _line_count(p) <= ROTATE_AT:
+            return
+    except OSError:
+        return
+    with util.try_lock(p.with_name(p.name + ".rotate.lock")) as locked:
+        if not locked:
+            return
+        try:
+            raw = p.read_bytes()
+            lines = raw.decode("utf-8", "replace").splitlines()
+            if len(lines) <= ROTATE_AT:
+                return                      # someone else already rotated
+            keep = lines[-ROTATE_KEEP:]
+            # Re-read past the point we stopped, so an append that landed
+            # while we were building the snapshot survives it.
+            with p.open("rb") as f:
+                f.seek(len(raw))
+                keep += f.read().decode("utf-8", "replace").splitlines()
+        except OSError:
+            return
+        util.atomic_write_text(p, "\n".join(keep) + "\n")

{boost_skill_cli-1.0.239 → boost_skill_cli-1.0.241}/boost_cli/core/util.py

@@ -10,6 +10,7 @@ import shutil
 import stat
 import sys
 import tempfile
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import List, Tuple
@@ -37,6 +38,59 @@ def rmtree(path) -> None:
         shutil.rmtree(str(path), onerror=_clear_readonly_and_retry)
 
 
+def _lock_is_stale(path: Path, stale_after: float) -> bool:
+    """True when a lock file is old enough to have been abandoned."""
+    try:
+        return (time.time() - path.stat().st_mtime) > stale_after
+    except OSError:
+        return True     # it vanished under us — treat it as free
+
+
+@contextlib.contextmanager
+def try_lock(path, stale_after: float = 300.0):
+    """Best-effort exclusive lock, yielding whether it was actually taken.
+
+    An `O_CREAT | O_EXCL` create is atomic on every filesystem boost targets,
+    and needs neither `fcntl` (missing on Windows) nor `msvcrt` (missing
+    everywhere else). Yields True to the holder and **False** to everyone
+    else — this does not wait, because its callers are jobs where "another
+    process is already doing it" is a perfectly good outcome, and blocking
+    would trade a rare lost update for a common stall.
+
+    A lock file older than `stale_after` is stolen: a process killed
+    mid-operation must not wedge the operation forever. Any error acquiring
+    it yields False rather than raising — failing to take a lock must never
+    be worse than the problem it guards.
+    """
+    path = Path(path)
+    fd = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            fd = os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            if not _lock_is_stale(path, stale_after):
+                yield False
+                return
+            with contextlib.suppress(OSError):
+                path.unlink()
+            fd = os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except OSError:
+        yield False
+        return
+    try:
+        with contextlib.suppress(OSError), os.fdopen(fd, "w") as f:
+            fd = None                      # fdopen owns it now
+            f.write(str(os.getpid()))
+        yield True
+    finally:
+        if fd is not None:
+            with contextlib.suppress(OSError):
+                os.close(fd)
+        with contextlib.suppress(OSError):
+            path.unlink()
+
+
 def atomic_write_text(path: Path, text: str, encoding: str = "utf-8") -> None:
     """Write ``text`` to ``path`` so a reader never sees a partial file.
 

{boost_skill_cli-1.0.239 → boost_skill_cli-1.0.241}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.239
+Version: 1.0.241
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

boost_skill_cli-1.0.241/docs/roadmap/items/journal-rotation-race-and-handle-leak.md

@@ -0,0 +1,37 @@
+---
+id: journal-rotation-race-and-handle-leak
+board: code
+section: internals
+status: shipped
+category: Concurrency · Bug
+complexity: M
+impact: Med
+wow: 2
+note:
+order: 31
+owner: loop/journal-rotation
+pr: 275
+title: Journal rotation has a lost-update race between concurrent processes
+---
+<code>_maybe_rotate</code> reads the whole pulse file and atomically replaces it with a truncated
+snapshot — but two concurrent boost processes (explicitly expected per this repo's parallel-loop
+model) can both read, then both write their own snapshot, and whichever writes last silently
+discards any event the other appended in between. <code>rotation_healthy()</code> also opens the
+file with a bare <code>p.open()</code> and never closes it, relying on GC instead of a
+<code>with</code> block like every other open in the module. Rotate under a lock (or an
+append-only rename scheme), and close the handle explicitly.
+Shipped with <code>util.try_lock()</code>, a portable <code>O_CREAT | O_EXCL</code> advisory
+lock that needs neither <code>fcntl</code> (absent on Windows) nor <code>msvcrt</code> (absent
+everywhere else). It <em>yields False rather than waiting</em>: a process that cannot take it
+just returns, because another one is already trimming and blocking would trade a rare lost
+update for a common stall. A lock older than five minutes is stolen, so a process killed
+mid-rotation cannot wedge the feed forever. Inside the lock the file is re-read (the count
+that got us there was taken outside it) and anything appended since is carried into the new
+file instead of dropped. <code>log()</code> stays lock-free — <code>O_APPEND</code> writes of
+one short record do not tear, and making every command contend on a lock to protect an
+advisory feed would be the wrong trade.
+Writing the test for a torn append turned up a third defect neither the card nor the code
+had noticed: a single invalid byte in the feed raised <code>UnicodeDecodeError</code>, which
+is a <code>ValueError</code> and sails straight past the <code>except OSError</code> guard —
+so one bad byte crashed <em>every command that logs</em>, permanently. Both reads decode with
+<code>errors="replace"</code> now.

{boost_skill_cli-1.0.239 → boost_skill_cli-1.0.241}/docs/roadmap.html

@@ -1014,7 +1014,7 @@ live hits," and prune removed taps on every build, not just changed ones.</p>
       </article>
 
       <article class="cap rcard" id="journal-rotation-race-and-handle-leak">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">Concurrency · Bug</span></div>
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Concurrency · Bug</span></div>
         <h3>Journal rotation has a lost-update race between concurrent processes</h3>
         <p><code>_maybe_rotate</code> reads the whole pulse file and atomically replaces it with a truncated
 snapshot — but two concurrent boost processes (explicitly expected per this repo's parallel-loop
@@ -1022,7 +1022,22 @@ model) can both read, then both write their own snapshot, and whichever writes l
 discards any event the other appended in between. <code>rotation_healthy()</code> also opens the
 file with a bare <code>p.open()</code> and never closes it, relying on GC instead of a
 <code>with</code> block like every other open in the module. Rotate under a lock (or an
-append-only rename scheme), and close the handle explicitly.</p>
+append-only rename scheme), and close the handle explicitly.
+Shipped with <code>util.try_lock()</code>, a portable <code>O_CREAT | O_EXCL</code> advisory
+lock that needs neither <code>fcntl</code> (absent on Windows) nor <code>msvcrt</code> (absent
+everywhere else). It <em>yields False rather than waiting</em>: a process that cannot take it
+just returns, because another one is already trimming and blocking would trade a rare lost
+update for a common stall. A lock older than five minutes is stolen, so a process killed
+mid-rotation cannot wedge the feed forever. Inside the lock the file is re-read (the count
+that got us there was taken outside it) and anything appended since is carried into the new
+file instead of dropped. <code>log()</code> stays lock-free — <code>O_APPEND</code> writes of
+one short record do not tear, and making every command contend on a lock to protect an
+advisory feed would be the wrong trade.
+Writing the test for a torn append turned up a third defect neither the card nor the code
+had noticed: a single invalid byte in the feed raised <code>UnicodeDecodeError</code>, which
+is a <code>ValueError</code> and sails straight past the <code>except OSError</code> guard —
+so one bad byte crashed <em>every command that logs</em>, permanently. Both reads decode with
+<code>errors="replace"</code> now.</p>
         <div class="meta">
           <span class="m">Complexity <b>M</b></span>
           <span class="m">Impact <b>Med</b></span>

{boost_skill_cli-1.0.239 → boost_skill_cli-1.0.241}/tests/unit/test_journal.py

@@ -117,6 +117,118 @@ class TestRotation:
         assert first["subject"] == "s2502"
 
 
+class TestRotationConcurrency:
+    """Rotation is a read-modify-write, and this repo expects concurrent
+    boost processes. Every assertion here is about not losing an event."""
+
+    def _lock_path(self):
+        p = paths.pulse_path()
+        return p.with_name(p.name + ".rotate.lock")
+
+    def test_a_held_lock_skips_rotation_entirely(self, sandbox):
+        # Another process is already trimming. Doing it a second time from a
+        # stale read is exactly how an event goes missing.
+        write_lines(5001)
+        paths.ensure_dirs()
+        self._lock_path().write_text("999999", encoding="utf-8")
+        journal._maybe_rotate()
+        assert len(paths.pulse_path().read_text(
+            encoding="utf-8").splitlines()) == 5001
+
+    def test_the_lock_is_released_after_rotating(self, sandbox):
+        write_lines(5001)
+        journal._maybe_rotate()
+        assert not self._lock_path().exists()
+        assert len(paths.pulse_path().read_text(
+            encoding="utf-8").splitlines()) == journal.ROTATE_KEEP
+
+    def test_an_append_during_the_snapshot_survives_it(self, sandbox,
+                                                       monkeypatch):
+        # The lost update: a concurrent log() lands after rotation has read
+        # the feed but before it swaps the trimmed file into place. The old
+        # code wrote its stale snapshot over the top and the event vanished.
+        write_lines(5001)
+        p = paths.pulse_path()
+        real_read_bytes = type(p).read_bytes
+
+        def read_then_someone_appends(self, *a, **kw):
+            # Scoped to the pulse file: this patches a method every Path in
+            # the process shares, so an unscoped version hands some unrelated
+            # read the feed's bytes and appends to the feed behind its back.
+            data = real_read_bytes(self, *a, **kw)
+            if self == p:
+                with p.open("a", encoding="utf-8") as f:
+                    f.write(json.dumps({"ts": "2026-01-01T00:00:00Z",
+                                        "user": "u", "action": "install",
+                                        "subject": "raced-in"}) + "\n")
+            return data
+
+        monkeypatch.setattr(type(p), "read_bytes", read_then_someone_appends)
+        journal._maybe_rotate()
+        subjects = [json.loads(line)["subject"] for line
+                    in p.read_text(encoding="utf-8").splitlines()]
+        assert "raced-in" in subjects
+        assert subjects[-1] == "raced-in"        # and in the right order
+
+    def test_a_second_rotation_inside_the_lock_is_a_no_op(self, sandbox,
+                                                          monkeypatch):
+        # The count that gets us into the lock is taken outside it. If another
+        # process rotated in between, the re-read must notice and leave the
+        # already-trimmed file alone rather than trim it again.
+        write_lines(5001)
+        p = paths.pulse_path()
+        real_read_bytes = type(p).read_bytes
+
+        def rotated_by_someone_else(self, *a, **kw):
+            if self == p:
+                # Exactly at the threshold, the boundary that decides it:
+                # ROTATE_AT lines is healthy, ROTATE_AT + 1 is not.
+                write_lines(journal.ROTATE_AT, action="fresh")
+            return real_read_bytes(self, *a, **kw)
+
+        monkeypatch.setattr(journal, "_line_count", lambda _p: 5001)
+        monkeypatch.setattr(type(p), "read_bytes", rotated_by_someone_else)
+        journal._maybe_rotate()
+        assert len(p.read_text(encoding="utf-8").splitlines()) == journal.ROTATE_AT
+
+    def test_undecodable_bytes_do_not_abort_rotation(self, sandbox):
+        # The feed carries user-supplied text (skill names, tap names), and a
+        # torn append can leave a partial multi-byte sequence behind. Rotation
+        # must trim the file anyway rather than raise and let it grow forever.
+        write_lines(5001)
+        p = paths.pulse_path()
+        with p.open("ab") as f:
+            f.write(b'{"ts": "2026-01-01T00:00:00Z", "user": "u", '
+                    b'"action": "install", "subject": "caf\xe9"}\n')
+        journal._maybe_rotate()
+        lines = p.read_text(encoding="utf-8").splitlines()
+        assert len(lines) == journal.ROTATE_KEEP
+        assert "caf" in lines[-1]          # kept, with the bad byte replaced
+
+    def test_rotation_healthy_closes_its_handle(self, sandbox, monkeypatch):
+        # It used to be a bare `p.open()` left to the garbage collector — the
+        # one open in the module without a `with`. Asserted by holding a
+        # reference to every handle it opens rather than by watching for a
+        # ResourceWarning: that warning is raised during finalization, where
+        # pytest reports it as unraisable instead of failing the test, so it
+        # would not have caught this.
+        write_lines(3)
+        opened = []
+        path_type = type(paths.pulse_path())
+        real_open = path_type.open
+
+        def tracking_open(self, *a, **kw):
+            handle = real_open(self, *a, **kw)
+            if self == paths.pulse_path():   # only the feed's handles are ours
+                opened.append(handle)
+            return handle
+
+        monkeypatch.setattr(path_type, "open", tracking_open)
+        assert journal.rotation_healthy() is True
+        assert opened, "expected rotation_healthy to read the feed"
+        assert all(handle.closed for handle in opened)
+
+
 class TestFallbacks:
     def test_user_falls_back_to_unknown(self, sandbox, monkeypatch):
         def no_user():

{boost_skill_cli-1.0.239 → boost_skill_cli-1.0.241}/tests/unit/test_util.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import hashlib
 import re
+import time
 from datetime import datetime, timedelta, timezone
 
 import pytest
@@ -533,6 +534,72 @@ class TestAtomicWriteText:
         assert leftovers == []
 
 
+class TestTryLock:
+    """A lock that silently fails open is worse than no lock at all, so both
+    answers are pinned: who gets True, who gets False, and what is left behind."""
+
+    def test_taken_lock_yields_true_and_cleans_up(self, tmp_path):
+        lock = tmp_path / "x.lock"
+        with util.try_lock(lock) as got:
+            assert got is True
+            assert lock.is_file()
+        assert not lock.exists()
+
+    def test_second_holder_is_refused_rather_than_queued(self, tmp_path):
+        lock = tmp_path / "x.lock"
+        with util.try_lock(lock) as first, util.try_lock(lock) as second:
+            assert first is True
+            assert second is False
+
+    def test_the_loser_does_not_delete_the_winners_lock(self, tmp_path):
+        # The nastiest failure mode: a refused caller cleaning up on its way
+        # out would hand the lock to whoever asked next, while the holder is
+        # still working.
+        lock = tmp_path / "x.lock"
+        with util.try_lock(lock):
+            with util.try_lock(lock) as second:
+                assert second is False
+            assert lock.is_file()
+
+    def test_lock_is_released_when_the_body_raises(self, tmp_path):
+        lock = tmp_path / "x.lock"
+        with pytest.raises(ValueError), util.try_lock(lock):
+            raise ValueError("boom")
+        assert not lock.exists()
+
+    def test_stale_lock_is_stolen(self, tmp_path):
+        import os as _os
+        lock = tmp_path / "x.lock"
+        lock.write_text("999999", encoding="utf-8")
+        old = time.time() - 600
+        _os.utime(lock, (old, old))
+        with util.try_lock(lock, stale_after=300.0) as got:
+            assert got is True          # the holder died; don't wedge forever
+
+    def test_fresh_lock_is_not_stolen(self, tmp_path):
+        lock = tmp_path / "x.lock"
+        lock.write_text("999999", encoding="utf-8")
+        with util.try_lock(lock, stale_after=300.0) as got:
+            assert got is False
+        assert lock.is_file()           # and it is left for its owner
+
+    def test_a_vanished_lock_reads_as_free(self, tmp_path):
+        assert util._lock_is_stale(tmp_path / "never-existed", 300.0) is True
+
+    def test_unusable_path_refuses_instead_of_raising(self, tmp_path):
+        # Failing to take a lock must never be worse than the race it guards.
+        blocker = tmp_path / "not-a-dir"
+        blocker.write_text("x", encoding="utf-8")
+        with util.try_lock(blocker / "sub" / "x.lock") as got:
+            assert got is False
+
+    def test_the_holder_records_its_pid(self, tmp_path):
+        import os as _os
+        lock = tmp_path / "x.lock"
+        with util.try_lock(lock):
+            assert lock.read_text(encoding="utf-8") == str(_os.getpid())
+
+
 class TestSafeComponent:
     """A catalog name becomes a path component, so it is attacker-controlled
     input on the way to an install path (a tap writes its own frontmatter)."""

boost_skill_cli-1.0.239/boost_cli/core/journal.py

@@ -1,69 +0,0 @@
-"""The pulse journal: append-only feed of skill-management events.
-
-Powers `boost pulse`, `boost trending`, `boost stats`, and `boost who`.
-"""
-from __future__ import annotations
-
-import json
-from typing import List, Optional
-
-from . import paths, util
-
-ROTATE_AT = 5000
-ROTATE_KEEP = 2500
-
-
-def log(action: str, subject: str = "", **fields) -> None:
-    """Append one event line to the pulse feed, rotating when oversized.
-
-    None-valued keyword fields are dropped from the record.
-    """
-    paths.ensure_dirs()
-    event = {"ts": util.now_iso(), "user": util.user(), "action": action,
-             "subject": subject}
-    event.update({k: v for k, v in fields.items() if v is not None})
-    p = paths.pulse_path()
-    with p.open("a") as f:
-        f.write(json.dumps(event) + "\n")
-    _maybe_rotate()
-
-
-def events(n: Optional[int] = None, action: Optional[str] = None,
-           subject: Optional[str] = None) -> List[dict]:
-    """Most-recent-first list of journal events."""
-    p = paths.pulse_path()
-    if not p.exists():
-        return []
-    out = []
-    for line in p.read_text(encoding="utf-8").splitlines():
-        try:
-            e = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        if action and e.get("action") != action:
-            continue
-        if subject and e.get("subject") != subject:
-            continue
-        out.append(e)
-    out.reverse()
-    return out[:n] if n else out
-
-
-def rotation_healthy() -> bool:
-    """True when the pulse feed is absent or at most ROTATE_AT lines long."""
-    p = paths.pulse_path()
-    if not p.exists():
-        return True
-    return sum(1 for _ in p.open()) <= ROTATE_AT
-
-
-def _maybe_rotate() -> None:
-    p = paths.pulse_path()
-    try:
-        lines = p.read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return
-    if len(lines) > ROTATE_AT:
-        # Atomic swap: a bare write_text here races concurrent log() appends and
-        # can truncate the feed mid-line if interrupted.
-        util.atomic_write_text(p, "\n".join(lines[-ROTATE_KEEP:]) + "\n")

boost_skill_cli-1.0.239/docs/roadmap/items/journal-rotation-race-and-handle-leak.md

@@ -1,22 +0,0 @@
----
-id: journal-rotation-race-and-handle-leak
-board: code
-section: internals
-status: planned
-category: Concurrency · Bug
-complexity: M
-impact: Med
-wow: 2
-note:
-order: 31
-owner:
-pr:
-title: Journal rotation has a lost-update race between concurrent processes
----
-<code>_maybe_rotate</code> reads the whole pulse file and atomically replaces it with a truncated
-snapshot — but two concurrent boost processes (explicitly expected per this repo's parallel-loop
-model) can both read, then both write their own snapshot, and whichever writes last silently
-discards any event the other appended in between. <code>rotation_healthy()</code> also opens the
-file with a bare <code>p.open()</code> and never closes it, relying on GC instead of a
-<code>with</code> block like every other open in the module. Rotate under a lock (or an
-append-only rename scheme), and close the handle explicitly.