guild-cli 0.26.23__tar.gz → 0.27.0__tar.gz

{guild_cli-0.26.23 → guild_cli-0.27.0}/.claude/skills/version-bump/SKILL.md

@@ -45,12 +45,17 @@ python3 .claude/skills/version-bump/scripts/bump.py show
 ## Changelog JSON Format
 
 Pass via stdin. All fields are optional — only non-empty sections are rendered.
+The only keys are `added`, `changed` and `fixed`, each a list of strings.
 
-Stdin is read until it closes, however slowly the JSON arrives. If it stays
-open with no new input for `BUMP_STDIN_IDLE_SECONDS` (default 5), the bump
-stops with an error and changes nothing, instead of hanging or dropping your
-entries. `--no-stdin` (or `BUMP_NO_STDIN=1`) skips stdin and writes the empty
-stub.
+Stdin is read until it closes. Any pause longer than `BUMP_STDIN_IDLE_SECONDS`
+(default 5), **including before the first byte**, stops the bump with an
+error; raise it for a slow producer (an LLM call, a cold `git log`).
+`--no-stdin` (or `BUMP_NO_STDIN=1`) skips stdin and writes the empty stub.
+
+Invalid JSON, an unknown key (e.g. `removed`), a value that isn't a list of
+strings, or bytes that don't decode are errors too, never a silent empty
+stub. Every check runs before any file is written, so a failed bump changes
+nothing; fix the input and run it again.
 
 ```json
 {
@@ -68,8 +73,10 @@ stub.
 - `CHANGELOG.md` — inserts a new `## [x.y.z] - YYYY-MM-DD` entry above the
   first `## [` release heading (headings inside fenced code blocks don't
   count). A leading `## [Unreleased]` section stays on top, untouched; its
-  content is never moved into the release for you. A CHANGELOG with no release
-  heading yet gets the entry after its Unreleased section, or at the end.
+  content is never moved into the release for you. A CHANGELOG with no `##`
+  heading yet gets the entry at the end, or after an Unreleased-only section.
+  One whose `##` headings aren't `## [...]` release headings (e.g. `## 1.2.3`)
+  stops the bump with an error.
 
 The script does the rest. Pick a bump type from the diff (patch for fixes,
 minor for new features, major for breaking changes), summarize the diff into

{guild_cli-0.26.23 → guild_cli-0.27.0}/.claude/skills/version-bump/scripts/bump.py

@@ -21,22 +21,28 @@ Changelog entries are passed via stdin as a JSON object:
     }
 
 If stdin is a terminal or empty, or --no-stdin (or BUMP_NO_STDIN=1) is given,
-an empty stub is inserted. Stdin is read until it closes; if it stays open
-with no new input for BUMP_STDIN_IDLE_SECONDS (default 5), the bump stops with
-an error and changes nothing, rather than hanging or dropping entries.
+an empty stub is inserted. Otherwise stdin is read until it closes. Any pause
+longer than BUMP_STDIN_IDLE_SECONDS (default 5), including before the first
+byte, stops the bump with an error; raise it for a slow producer. Stdin that
+isn't valid JSON in the shape above (an object whose keys are added / changed /
+fixed, each a list of strings) is an error too. Every check runs before any
+file is written, so a failed bump changes nothing.
 
 The new section goes above the first ``## [`` release heading, ignoring
 headings inside fenced code blocks. A leading ``## [Unreleased]`` section stays
-on top, untouched; a CHANGELOG with no release heading yet gets the section
-after its Unreleased section, or at the end.
+on top, untouched. A CHANGELOG with no ``##`` heading yet gets the section at
+the end, or after an Unreleased-only section; one whose ``##`` headings aren't
+``## [...]`` release headings (e.g. ``## 1.2.3``) is an error.
 """
 
+import argparse
 import json
 import math
 import os
+import queue
 import re
-import select
 import sys
+import threading
 from datetime import date
 from pathlib import Path
 
@@ -91,6 +97,7 @@ def write_version(path: Path, old: str, new: str) -> None:
 
 
 STDIN_IDLE_SECONDS_DEFAULT = 5.0
+SECTIONS = ("added", "changed", "fixed")
 
 
 def _env_flag(name: str) -> bool:
@@ -114,21 +121,85 @@ def _stdin_idle_seconds() -> float:
     return value
 
 
-def _read_stdin_until_eof(idle: float) -> str | None:
-    """Read stdin to EOF; None if it stays open with no new input for ``idle`` s."""
-    fd = sys.stdin.fileno()
-    chunks = []
+def _fail(message: str) -> None:
+    print(f"ERROR: {message}; nothing was changed.", file=sys.stderr)
+    sys.exit(1)
+
+
+def _stdin_encoding() -> str:
+    return getattr(sys.stdin, "encoding", None) or "utf-8"
+
+
+def _pump_stdin(out: queue.Queue) -> None:
+    """Thread body: put stdin's chunks (b"" at EOF) or the read error on ``out``.
+
+    Reads the raw fd with os.read, not the buffered sys.stdin, so a thread
+    still blocked in a read at exit can't hold the stdin buffer's lock during
+    interpreter shutdown.
+    """
+    try:
+        fd = sys.stdin.fileno()
+    except (OSError, ValueError):  # a text-only stdin, e.g. io.StringIO
+        encoding = _stdin_encoding()
+
+        def read() -> bytes:
+            return sys.stdin.read(65536).encode(encoding)
+
+    else:
+
+        def read() -> bytes:
+            return os.read(fd, 65536)
+
+    try:
+        while True:
+            chunk = read()
+            out.put(chunk)
+            if not chunk:
+                return
+    except (OSError, ValueError) as exc:
+        out.put(exc)
+
+
+def _read_stdin_until_eof(idle: float) -> bytes | None:
+    """Read stdin to EOF; None if no new input arrives within ``idle`` s."""
+    chunks: queue.Queue = queue.Queue()
+    threading.Thread(target=_pump_stdin, args=(chunks,), daemon=True).start()
+    data = []
     while True:
         try:
-            ready, _, _ = select.select([fd], [], [], idle)
-        except (OSError, ValueError):
-            return sys.stdin.read()  # select() can't poll this stdin (e.g. Windows): read as before
-        if not ready:
+            chunk = chunks.get(timeout=idle)
+        except queue.Empty:
             return None
-        chunk = os.read(fd, 65536)
+        if isinstance(chunk, Exception):
+            _fail(f"could not read stdin ({chunk})")
         if not chunk:
-            return b"".join(chunks).decode()
-        chunks.append(chunk)
+            return b"".join(data)
+        data.append(chunk)
+
+
+def _parse_entries(raw: bytes) -> dict:
+    """Decode and validate changelog JSON; an error rather than a dropped entry."""
+    try:
+        text = raw.decode(_stdin_encoding()).strip()
+    except (UnicodeDecodeError, LookupError) as exc:
+        _fail(f"could not decode stdin as {_stdin_encoding()} ({exc})")
+    if not text:
+        return {}
+    try:
+        entries = json.loads(text)
+    except json.JSONDecodeError as exc:
+        _fail(f"stdin is not valid changelog JSON ({exc})")
+    if not isinstance(entries, dict):
+        _fail('changelog JSON must be an object like {"fixed": ["..."]}')
+    unknown = sorted(set(entries) - set(SECTIONS))
+    if unknown:
+        _fail(
+            f"unknown changelog key(s) {', '.join(map(repr, unknown))}; use {', '.join(SECTIONS)}"
+        )
+    for key, items in entries.items():
+        if not isinstance(items, list) or not all(isinstance(i, str) for i in items):
+            _fail(f"changelog key {key!r} must be a list of strings")
+    return entries
 
 
 def read_changelog_entries(no_stdin: bool = False) -> dict:
@@ -138,23 +209,13 @@ def read_changelog_entries(no_stdin: bool = False) -> dict:
     idle = _stdin_idle_seconds()
     raw = _read_stdin_until_eof(idle)
     if raw is None:
-        print(
-            f"ERROR: stdin stayed open with no input for {idle:g}s and never closed; nothing "
-            "was changed. Pipe the changelog JSON (echo '{...}' | bump.py patch), or pass "
-            "--no-stdin (or set BUMP_NO_STDIN=1) for an empty stub.",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-    raw = raw.strip()
-    if not raw:
-        return {}
-    try:
-        return json.loads(raw)
-    except (json.JSONDecodeError, ValueError):
-        print(
-            "WARNING: could not parse changelog JSON from stdin, using empty stub", file=sys.stderr
+        _fail(
+            f"stdin stayed open with no input for {idle:g}s and never closed. Pipe the "
+            "changelog JSON (echo '{...}' | bump.py patch), raise BUMP_STDIN_IDLE_SECONDS "
+            "for a slow producer, or pass --no-stdin (or set BUMP_NO_STDIN=1) for an "
+            "empty stub"
         )
-        return {}
+    return _parse_entries(raw)
 
 
 def format_changelog_section(new: str, entries: dict) -> str:
@@ -167,35 +228,50 @@ def format_changelog_section(new: str, entries: dict) -> str:
     today = date.today().isoformat()
     chunks = [f"## [{new}] - {today}\n"]
 
-    for section in ("added", "changed", "fixed"):
+    for section in SECTIONS:
         items = entries.get(section, [])
         if items:
             chunks.append(f"\n### {section.capitalize()}\n\n")
             chunks.extend(f"- {item}\n" for item in items)
 
     # If no entries at all, emit empty section stubs.
-    if not any(entries.get(s) for s in ("added", "changed", "fixed")):
+    if not any(entries.get(s) for s in SECTIONS):
         chunks.append("\n### Added\n\n### Changed\n\n### Fixed\n")
 
     chunks.append("\n")  # blank line before the next existing entry
     return "".join(chunks)
 
 
+_FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
+
+
 def _section_headings(lines: list[str]) -> list[tuple[int, str]]:
-    """``## `` headings outside fenced code blocks, as (line index, line)."""
-    headings, fenced = [], False
+    """``## `` headings outside fenced code blocks, as (line index, line).
+
+    A fence opens with 3+ backticks or tildes (a backtick fence's info string
+    can't contain a backtick, so ```` ```x``` text ```` is inline code, not a
+    fence) and closes only on a line of the same character, at least as long,
+    with nothing after it.
+    """
+    headings, fence = [], None
     for i, line in enumerate(lines):
-        if line.lstrip().startswith(("```", "~~~")):
-            fenced = not fenced
-        elif not fenced and line.startswith("## "):
+        match = _FENCE.match(line.rstrip("\r\n"))
+        if fence:
+            marker, info = match.groups() if match else ("", "x")
+            if marker[:1] == fence[0] and len(marker) >= len(fence) and not info.strip():
+                fence = None
+        elif match and not (match.group(1)[0] == "`" and "`" in match.group(2)):
+            fence = match.group(1)
+        elif line.startswith("## "):
             headings.append((i, line))
     return headings
 
 
-def _insertion_index(lines: list[str]) -> int:
+def _insertion_index(lines: list[str]) -> int | None:
     """Line index for the new section: above the first ``## [`` release heading
     that isn't Unreleased, so a leading Unreleased section stays on top; after
-    an Unreleased-only section, or at the end of a file with neither."""
+    an Unreleased-only section, or at the end of a file with no ``##`` heading.
+    None for ``##`` headings this script doesn't recognise (e.g. ``## 1.2.3``)."""
     headings = _section_headings(lines)
     unreleased = re.compile(r"^## \[Unreleased\]", re.IGNORECASE)
     releases = [i for i, line in headings if line.startswith("## [") and not unreleased.match(line)]
@@ -204,46 +280,60 @@ def _insertion_index(lines: list[str]) -> int:
     after = [i for i, line in headings if unreleased.match(line)]
     if after:
         return next((i for i, _ in headings if i > after[0]), len(lines))
-    return len(lines)
+    return None if headings else len(lines)
 
 
-def update_changelog(project_root: Path, new: str, entries: dict) -> None:
-    """Insert a new changelog entry into CHANGELOG.md."""
+def plan_changelog(project_root: Path, new: str, entries: dict) -> tuple[Path, str] | None:
+    """The CHANGELOG path and its new text, without writing; None if there is none."""
     changelog = project_root / "CHANGELOG.md"
     if not changelog.exists():
-        print("No CHANGELOG.md found — skipping")
-        return
-
+        return None
     lines = changelog.read_text().splitlines(keepends=True)
     idx = _insertion_index(lines)
+    if idx is None:
+        _fail(
+            "CHANGELOG.md has ## headings but no '## [x.y.z]' release heading to insert "
+            "above (Keep a Changelog format)"
+        )
     before, after = "".join(lines[:idx]), "".join(lines[idx:])
     new_entry = format_changelog_section(new, entries)
     if not after:  # appending at the end of the file
         before = before.rstrip("\n") + "\n\n" if before.strip() else ""
         new_entry = new_entry.rstrip("\n") + "\n"
-    changelog.write_text(before + new_entry + after)
-    print(f"Updated CHANGELOG.md with [{new}]")
+    return changelog, before + new_entry + after
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="bump.py",
+        description=__doc__,
+        allow_abbrev=False,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("part", type=str.lower, choices=("major", "minor", "patch", "show"))
+    parser.add_argument(
+        "--no-stdin", action="store_true", help="don't read stdin; insert the empty stub"
+    )
+    if not argv:
+        parser.print_help()
+        sys.exit(0)
+    return parser.parse_args(argv)
 
 
 def main():
-    args = [a for a in sys.argv[1:] if a != "--no-stdin"]
-    no_stdin = len(args) < len(sys.argv) - 1 or _env_flag("BUMP_NO_STDIN")
-    if not args or args[0] in ("-h", "--help"):
-        print(__doc__.strip())
-        sys.exit(0)
-
-    part = args[0].lower()
+    args = _parse_args(sys.argv[1:])
     path = find_pyproject()
     current = read_version(path)
 
-    if part == "show":
+    if args.part == "show":
         print(current)
         sys.exit(0)
 
-    # Read changelog entries before bumping
-    entries = read_changelog_entries(no_stdin)
+    # Every check runs before any write, so a failed bump changes nothing.
+    new = bump(current, args.part)
+    entries = read_changelog_entries(args.no_stdin or _env_flag("BUMP_NO_STDIN"))
+    changelog = plan_changelog(path.parent, new, entries)
 
-    new = bump(current, part)
     write_version(path, current, new)
 
     # Also update __init__.py if it has __version__
@@ -262,8 +352,11 @@ def main():
                 )
                 print(f"Updated {init.relative_to(path.parent)}")
 
-    # Update changelog
-    update_changelog(path.parent, new, entries)
+    if changelog is None:
+        print("No CHANGELOG.md found — skipping")
+    else:
+        changelog[0].write_text(changelog[1])
+        print(f"Updated CHANGELOG.md with [{new}]")
 
     print(f"{current} -> {new}")
 

{guild_cli-0.26.23 → guild_cli-0.27.0}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.27.0] - 2026-10-30
+
+### Changed
+
+- `version-bump`: every check runs before any file is written, so a failed bump changes nothing. That covers the bump type, stdin, the changelog JSON and where the new CHANGELOG section goes. A mistyped bump type now fails at once with argparse's "invalid choice" instead of first waiting on stdin, and unknown options such as `--nostdin` or abbreviations such as `--no` are rejected.
+- `version-bump`: invalid changelog JSON, a non-object, an unknown key (e.g. `removed`), a value that isn't a list of strings, and stdin bytes that don't decode now stop the bump with an error instead of a warning plus an empty stub, so entries are never dropped silently.
+- `version-bump`: SKILL.md now says plainly that a pause longer than `BUMP_STDIN_IDLE_SECONDS`, including before the first byte, is an error, and to raise it for a slow producer.
+
+### Fixed
+
+- `version-bump`: fenced code blocks are recognised properly. A line like ```` ```bash``` one-liner ```` no longer opens a fence, a different or shorter fence marker no longer closes one, and the new section can no longer end up appended below the oldest release (regression in 0.26.23).
+- `version-bump`: a CHANGELOG whose `##` headings aren't `## [...]` release headings (e.g. `## 1.2.3`) stops the bump with an error before `pyproject.toml` is touched. 0.26.23 appended the section at the end of the file; before that, the script warned but still bumped `pyproject.toml`.
+- `version-bump`: stdin is read by a background thread with the same idle timeout instead of `select()`, so the no-hang behaviour also holds on Windows and for a text-only stdin such as `io.StringIO`, which used to crash on `fileno()`.
+
 ## [0.26.23] - 2026-10-30
 
 ### Added

{guild_cli-0.26.23 → guild_cli-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: guild-cli
-Version: 0.26.23
+Version: 0.27.0
 Summary: guildmaster — an agent and CLI that manages skills for the AgentCulture mesh.
 Project-URL: Homepage, https://github.com/agentculture/guildmaster
 Project-URL: Issues, https://github.com/agentculture/guildmaster/issues

{guild_cli-0.26.23 → guild_cli-0.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "guild-cli"
-version = "0.26.23"
+version = "0.27.0"
 description = "guildmaster — an agent and CLI that manages skills for the AgentCulture mesh."
 readme = "README.md"
 license = "Apache-2.0"

{guild_cli-0.26.23 → guild_cli-0.27.0}/tests/test_version_bump_script.py

@@ -222,3 +222,125 @@ def test_changelog_without_a_version_heading_gets_the_section_appended(tmp_path)
     assert (repo / "CHANGELOG.md").read_text() == (
         f"# Changelog\n\nAll notable changes.\n\n## [0.1.1] - {TODAY}\n\n### Fixed\n\n- Bug\n"
     )
+
+
+# ---- review follow-up: every failure changes nothing --------------------------
+
+
+def _assert_rejected(result, *needles):
+    assert result.returncode != 0
+    for needle in needles:
+        assert needle in result.stderr
+    assert "nothing was changed" in result.stderr
+
+
+@pytest.mark.parametrize(
+    "fenced",
+    [
+        "```bash``` is inline code, not a fence\n\n",
+        "```\n~~~\n## [9.9.9] - inside\n```\n\n",
+        "````\n```\n## [9.9.9] - inside\n```\n````\n\n",
+        "~~~~\n## [9.9.9] - inside\n~~~\n~~~~\n\n",
+    ],
+    ids=["inline-backticks", "tilde-in-backtick", "longer-fence", "short-close"],
+)
+def test_fences_never_hide_the_release_heading(tmp_path, fenced):
+    repo = _repo(tmp_path, changelog=f"# Changelog\n\n{fenced}## [0.1.0] - 2026-01-01\n")
+    assert _bump(repo, '{"fixed": ["Bug"]}').returncode == 0
+    text = (repo / "CHANGELOG.md").read_text()
+    assert text.index(f"## [0.1.1] - {TODAY}") < text.index("## [0.1.0]")
+    assert text.endswith("## [0.1.0] - 2026-01-01\n")
+
+
+def test_unrecognised_release_headings_stop_the_bump(tmp_path):
+    changelog = "# Changelog\n\n## 0.1.0 - 2026-01-01\n\n- old\n"
+    repo = _repo(tmp_path, changelog=changelog)
+    _assert_rejected(_bump(repo, '{"fixed": ["Bug"]}'), "## [x.y.z]")
+    assert _unchanged(repo, changelog)
+
+
+@pytest.mark.parametrize(
+    "stdin, needle",
+    [
+        ('{"fixed": ["unterminated"', "not valid changelog JSON"),
+        ('["fixed"]', "must be an object"),
+        ('{"removed": ["Old flag"]}', "unknown changelog key(s) 'removed'"),
+        ('{"fixed": "not a list"}', "must be a list of strings"),
+        ('{"fixed": [1]}', "must be a list of strings"),
+    ],
+)
+def test_bad_changelog_json_stops_the_bump(tmp_path, stdin, needle):
+    repo = _repo(tmp_path)
+    _assert_rejected(_bump(repo, stdin), needle)
+    assert _unchanged(repo)
+
+
+def test_undecodable_stdin_stops_the_bump(tmp_path):
+    repo = _repo(tmp_path)
+    result = subprocess.run(
+        [sys.executable, str(BUMP), "patch"],
+        cwd=repo,
+        input='{"fixed": ["caf\xe9"]}'.encode("latin-1"),
+        capture_output=True,
+        timeout=30,
+        env=_env(PYTHONIOENCODING="utf-8"),
+    )
+    assert result.returncode != 0
+    assert b"could not decode stdin" in result.stderr
+    assert b"Traceback" not in result.stderr
+    assert _unchanged(repo)
+
+
+def test_unknown_bump_type_fails_before_reading_stdin(tmp_path):
+    repo = _repo(tmp_path)
+    start = time.monotonic()
+    proc = subprocess.Popen(
+        [sys.executable, str(BUMP), "pach"],
+        cwd=repo,
+        stdin=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        env=_env(BUMP_STDIN_IDLE_SECONDS="60"),
+    )
+    try:
+        proc.wait(timeout=30)
+        err = proc.stderr.read()
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        raise
+    finally:
+        proc.stdin.close()
+        proc.stderr.close()
+    assert proc.returncode != 0
+    assert "invalid choice: 'pach'" in err
+    assert time.monotonic() - start < 20
+    assert _unchanged(repo)
+
+
+@pytest.mark.parametrize("bad", ["--nostdin", "--no-stdin=1", "--no_stdin", "--no"])
+def test_unknown_options_are_rejected(tmp_path, bad):
+    repo = _repo(tmp_path)
+    result = _bump(repo, "", bad)
+    assert result.returncode == 2
+    assert "bump.py: error:" in result.stderr
+    assert _unchanged(repo)
+
+
+def test_no_arguments_prints_help(tmp_path):
+    result = subprocess.run(
+        [sys.executable, str(BUMP)], cwd=_repo(tmp_path), capture_output=True, text=True, timeout=30
+    )
+    assert result.returncode == 0
+    assert "Bump the version in pyproject.toml" in result.stdout
+
+
+def test_text_only_stdin_is_read_in_process(monkeypatch):
+    # Review of culture#503: fileno() on an io.StringIO stdin used to crash.
+    import importlib.util
+    import io
+
+    spec = importlib.util.spec_from_file_location("bump_under_test", BUMP)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    monkeypatch.setattr(sys, "stdin", io.StringIO('{"fixed": ["In process"]}'))
+    assert module.read_changelog_entries() == {"fixed": ["In process"]}

{guild_cli-0.26.23 → guild_cli-0.27.0}/uv.lock

@@ -179,7 +179,7 @@ wheels = [
 
 [[package]]
 name = "guild-cli"
-version = "0.26.23"
+version = "0.27.0"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },