rlsbl 0.5.1 → 0.6.0

package/README.md

@@ -62,7 +62,7 @@ rlsbl release major --dry-run --registry npm
 
 The version is synced across all detected project files (`package.json`, `pyproject.toml`, `VERSION`) regardless of which registry is primary. Go projects use a plain `VERSION` file as the version source.
 
-If `scripts/pre-release.sh` exists, it runs before any changes are made. A non-zero exit aborts the release. If `scripts/post-release.sh` exists, it runs after the release completes (non-fatal). See [Release flow](#release-flow) for details.
+If `.rlsbl/hooks/pre-release.sh` exists, it runs before any changes are made. A non-zero exit aborts the release. If `.rlsbl/hooks/post-release.sh` exists, it runs after the release completes (non-fatal). See [Release flow](#release-flow) for details.
 
 ### status
 
@@ -120,14 +120,14 @@ When you run `release`, the following happens in order:
 3. Reads the current version from the primary project file
 4. Computes the new version and confirms the git tag does not already exist
 5. Validates that `CHANGELOG.md` contains a `## <new-version>` section
-6. Runs `scripts/pre-release.sh` if present (non-zero exit aborts)
+6. Runs `.rlsbl/hooks/pre-release.sh` if present (non-zero exit aborts)
 7. Writes the new version to the primary project file
 8. Syncs the new version to all other detected project files
 9. Commits the version bump (uses `safegit` if available, otherwise `git`)
 10. Pushes the branch to `origin`
 11. Creates a GitHub Release tagged `v<new-version>` with the changelog entry as notes
 12. The GitHub Release triggers `publish.yml`, which publishes to the registry
-13. Runs `scripts/post-release.sh` if present (non-fatal -- the release is already complete). The `RLSBL_VERSION` env var is set to the released version. Useful for local install (`go install ./cmd/myapp/`), deploy, or notifications.
+13. Runs `.rlsbl/hooks/post-release.sh` if present (non-fatal -- the release is already complete). The `RLSBL_VERSION` env var is set to the released version. Useful for local install (`go install ./cmd/myapp/`), deploy, or notifications.
 14. Spawns a background process that watches CI via `gh run watch`. When CI finishes, it prints the result to stderr (so AI agents can read it) and sends a desktop notification (`notify-send` on Linux, `osascript` on macOS). On CI failure, it also prints the GitHub Actions run URL. This happens automatically -- no configuration needed.
 
 ## What scaffold creates
@@ -141,19 +141,17 @@ When you run `release`, the following happens in order:
 | `.gitignore` | Shared | Standard ignores for the ecosystem |
 | `CLAUDE.md` | Shared | AI assistant instructions |
 | `.claude/settings.json` | Shared | Claude Code settings |
-| `scripts/check-prs.sh` | Shared | PR review helper |
-| `scripts/pre-release.sh` | Shared | Pre-release hook (runs before each release) |
-| `scripts/post-release.sh` | Shared | Post-release hook (runs after each release, non-fatal) |
-| `scripts/record-gif.sh` | Shared | Terminal recording helper |
-| `scripts/pre-push-hook.sh` | Shared | Pre-push changelog enforcement |
+| `.rlsbl/hooks/pre-release.sh` | Shared | User-customizable pre-release validation |
+| `.rlsbl/hooks/post-release.sh` | Shared | User-customizable post-release actions |
+| `.git/hooks/pre-push` | Shared | One-liner that calls `rlsbl pre-push-check` |
 
-All `.sh` files in `scripts/` are made executable automatically. The pre-push hook is installed into `.git/hooks/pre-push` during scaffold.
+Hook files are made executable automatically. The `check-prs`, `record-gif`, and `pre-push-check` functionality is provided as built-in subcommands (`rlsbl check-prs`, `rlsbl record-gif`, `rlsbl pre-push-check`) rather than scaffolded scripts.
 
 The scaffolded `.gitignore` includes a `*.local-only` pattern. Create a `.local-only/` directory or rename files with a `.local-only` suffix to keep them out of version control -- useful for local-only assets, experiments, and keeping the working tree clean for tools that check `git status`.
 
 ## Pre-push hook
 
-The scaffolded `scripts/pre-push-hook.sh` is installed as a git pre-push hook during `scaffold`. It prevents pushing when `CHANGELOG.md` lacks an entry for the current version.
+The `rlsbl pre-push-check` subcommand enforces changelog coverage. During `scaffold`, a one-liner git hook is installed at `.git/hooks/pre-push` that calls this subcommand. It prevents pushing when `CHANGELOG.md` lacks an entry for the current version.
 
 How it works:
 
@@ -165,7 +163,7 @@ How it works:
 To reinstall manually:
 
 ```
-cp scripts/pre-push-hook.sh .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+echo '#!/bin/sh' > .git/hooks/pre-push && echo 'exec rlsbl pre-push-check "$@"' >> .git/hooks/pre-push && chmod +x .git/hooks/pre-push
 ```
 
 ## First publish
@@ -185,7 +183,7 @@ After configuration, all subsequent releases are handled by CI when `rlsbl relea
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `RLSBL_PUSH_TIMEOUT` | `120` | Timeout in seconds for `git push` operations. Increase if your pre-push hooks (e.g. test suites) take longer than 2 minutes. |
-| `RLSBL_VERSION` | -- | Set automatically when running `scripts/post-release.sh`. Contains the just-released version string. |
+| `RLSBL_VERSION` | -- | Set automatically when running `.rlsbl/hooks/post-release.sh`. Contains the just-released version string. |
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rlsbl",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Release orchestration and project scaffolding for npm and PyPI",
   "license": "MIT",
   "bin": {

package/rlsbl/__init__.py

@@ -3,14 +3,44 @@
 import os
 import sys
 
-try:
-    from importlib.metadata import version as _get_version
-    __version__ = _get_version("rlsbl")
-except Exception:
-    __version__ = "unknown"
+
+def _detect_version():
+    """Detect package version, preferring pyproject.toml over installed metadata.
+
+    Order: pyproject.toml in the source tree (accurate during editable installs)
+    -> importlib.metadata (works for regular installs) -> "unknown".
+    """
+    # Try reading version from pyproject.toml next to the package source
+    try:
+        pyproject_path = os.path.realpath(
+            os.path.join(os.path.dirname(__file__), "..", "pyproject.toml")
+        )
+        if os.path.isfile(pyproject_path):
+            try:
+                import tomllib
+            except ModuleNotFoundError:
+                import tomli as tomllib  # type: ignore[no-redef]
+            with open(pyproject_path, "rb") as f:
+                data = tomllib.load(f)
+            return data["project"]["version"]
+    except Exception:
+        pass
+
+    # Fall back to installed dist-info metadata
+    try:
+        from importlib.metadata import version as _get_version
+        return _get_version("rlsbl")
+    except Exception:
+        pass
+
+    return "unknown"
+
+
+__version__ = _detect_version()
 
 REGISTRIES = ("npm", "pypi", "go")
-COMMANDS = ("release", "status", "scaffold", "check", "config", "undo", "discover")
+COMMANDS = ("release", "status", "scaffold", "check", "config", "undo", "discover", "watch",
+            "check-prs", "pre-push-check", "record-gif")
 COMMAND_ALIASES = {"init": "scaffold"}
 
 HELP = f"""\
@@ -24,6 +54,10 @@ Usage:
   rlsbl config                                              Show project configuration
   rlsbl undo [--yes]                                        Revert the last release
   rlsbl discover [--mine]                                   List rlsbl ecosystem projects
+  rlsbl watch [<commit-sha>]                                Watch CI runs for a commit
+  rlsbl check-prs                                          List open PRs (informational)
+  rlsbl pre-push-check                                     Verify CHANGELOG entry for current version
+  rlsbl record-gif                                         Record a demo GIF with vhs
 
 Options:
   --registry <npm|pypi|go>  Target a specific registry (auto-detected if omitted)
@@ -89,6 +123,10 @@ def _get_command_module(command):
         "config": "config",
         "undo": "undo",
         "discover": "discover",
+        "watch": "watch",
+        "check-prs": "check_prs",
+        "pre-push-check": "pre_push_check",
+        "record-gif": "record_gif",
     }
     module_name = module_map.get(command)
     if not module_name:
@@ -145,14 +183,17 @@ def main():
             sys.exit(1)
 
         if command == "check":
-            # check: if registry given, check that one; otherwise check all
+            # check: if registry given, check that one; otherwise check npm and pypi.
+            # Go is excluded from the default set because Go modules use repository
+            # paths (e.g. github.com/user/repo), not a flat claimable namespace, so
+            # "available" would be misleading.  Pass --registry go explicitly to check.
             if registry:
                 handler.run_cmd(registry, args, flags)
             else:
-                all_registries = ["npm", "pypi", "go"]
-                for i, r in enumerate(all_registries):
+                default_registries = ["npm", "pypi"]
+                for i, r in enumerate(default_registries):
                     handler.run_cmd(r, args, flags)
-                    if i < len(all_registries) - 1:
+                    if i < len(default_registries) - 1:
                         print("")
         elif command == "scaffold":
             if registry:
@@ -182,6 +223,12 @@ def main():
         elif command == "discover":
             # discover: global query, no registry needed
             handler.run_cmd(registry, args, flags)
+        elif command == "watch":
+            # watch: monitors CI runs, no registry needed
+            handler.run_cmd(registry, args, flags)
+        elif command in ("check-prs", "pre-push-check", "record-gif"):
+            # Standalone commands, no registry needed
+            handler.run_cmd(registry, args, flags)
         else:
             # release, status: use explicit registry or auto-detect primary
             if not registry:

package/rlsbl/commands/check.py

@@ -168,35 +168,44 @@ def _check_name_pypi(name):
 def check_go_availability(name):
     """Check if a Go module path exists on pkg.go.dev.
 
-    Returns {"status": "available"|"taken"|"error", "message"?: str}.
+    Returns {"status": "not_found"|"exists"|"error", "message"?: str, "note"?: str}.
+
+    Go modules use repository paths (e.g. github.com/user/repo), not a flat
+    claimable namespace, so we report "not found" / "exists" rather than the
+    "available" / "taken" language used for npm and PyPI.
     """
     url = f"https://pkg.go.dev/{name}"
     try:
         req = urllib.request.Request(url, method="GET")
         with urllib.request.urlopen(req, timeout=5) as resp:
             if resp.status == 200:
-                return {"status": "taken"}
+                return {"status": "exists"}
             return {"status": "error", "message": f"Unexpected status {resp.status}"}
     except urllib.error.HTTPError as e:
         if e.code == 404:
-            return {"status": "available"}
+            return {
+                "status": "not_found",
+                "note": "Go modules use repository paths, not a central registry.",
+            }
         return {"status": "error", "message": f"Unexpected status {e.code}"}
     except Exception as e:
         return {"status": "error", "message": str(e) or "Network error"}
 
 
 def _check_name_go(name):
-    """Check Go module path availability on pkg.go.dev."""
+    """Check Go module path on pkg.go.dev."""
     print(f'Checking pkg.go.dev for "{name}"...')
 
     result = check_go_availability(name)
     if result["status"] == "error":
         print(f"Error checking pkg.go.dev: {result['message']}", file=sys.stderr)
         sys.exit(1)
-    if result["status"] == "available":
-        print(f'"{name}" is available on pkg.go.dev.')
+    if result["status"] == "not_found":
+        print(f'"{name}" not found on pkg.go.dev.')
     else:
-        print(f'"{name}" already exists on pkg.go.dev.')
+        print(f'"{name}" exists on pkg.go.dev.')
+    if result.get("note"):
+        print(f"  Note: {result['note']}")
 
 
 def run_cmd(registry, args, flags):

package/rlsbl/commands/check_prs.py

@@ -0,0 +1,26 @@
+"""Check-prs command: list open PRs for awareness."""
+
+import shutil
+import subprocess
+import sys
+
+
+def run_cmd(registry, args, flags):
+    """List open pull requests in the current repository.
+
+    Exits silently if gh CLI is not available. Always exits 0 (informational only).
+    """
+    if not shutil.which("gh"):
+        sys.exit(0)
+
+    try:
+        result = subprocess.run(
+            ["gh", "pr", "list", "--state", "open", "--limit", "20"],
+            capture_output=True, text=True, timeout=15,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            print(result.stdout.strip())
+    except Exception:
+        pass
+
+    sys.exit(0)

package/rlsbl/commands/config.py

@@ -40,9 +40,9 @@ def run_cmd(registry, args, flags):
         print(f"  {wf}: {'yes' if os.path.exists(path) else 'no'}")
 
     print("\nHooks:")
-    pre_release = os.path.join("scripts", "pre-release.sh")
+    pre_release = os.path.join(".rlsbl", "hooks", "pre-release.sh")
     print(f"  pre-release.sh: {'yes' if os.path.exists(pre_release) else 'no'}")
-    post_release = os.path.join("scripts", "post-release.sh")
+    post_release = os.path.join(".rlsbl", "hooks", "post-release.sh")
     print(f"  post-release.sh: {'yes' if os.path.exists(post_release) else 'no'}")
     pre_push = os.path.join(".git", "hooks", "pre-push")
     print(f"  pre-push hook: {'installed' if os.path.exists(pre_push) else 'not installed'}")

package/rlsbl/commands/discover.py

@@ -133,6 +133,8 @@ def run_cmd(registry, args, flags):
         repos = _fetch_all_repos(token)
     except urllib.error.HTTPError as e:
         print(f"Error: GitHub API returned {e.code}: {e.reason}", file=sys.stderr)
+        if e.code == 403:
+            print("Hint: run 'gh auth login' to increase API rate limits (60/hr unauthenticated → 5000/hr).", file=sys.stderr)
         sys.exit(1)
     except urllib.error.URLError as e:
         print(f"Error: could not reach GitHub API: {e.reason}", file=sys.stderr)

package/rlsbl/commands/init_cmd.py

@@ -4,8 +4,6 @@ import hashlib
 import json
 import os
 import re
-import shutil
-import stat
 import sys
 
 from ..config import should_tag
@@ -25,9 +23,6 @@ MERGEABLE = {".gitignore"}
 UPDATABLE = {
     ".github/workflows/ci.yml",
     ".github/workflows/publish.yml",
-    "scripts/check-prs.sh",
-    "scripts/post-release.sh",
-    "scripts/pre-push-hook.sh",
 }
 
 def file_hash(path):
@@ -177,13 +172,19 @@ def process_mappings(template_dir, mappings, vars_dict, force, update=False,
                 existing_lines = {
                     line.strip() for line in existing.split("\n") if line.strip()
                 }
+                # Normalize by stripping trailing slashes so e.g.
+                # "*.egg-info/" matches "*.egg-info" and vice versa.
+                existing_normalized = {
+                    line.rstrip("/") for line in existing_lines
+                }
                 new_lines = [
                     line.strip() for line in content.split("\n") if line.strip()
                 ]
                 # Only merge non-comment entries that are missing from the existing file
                 missing = [
                     line for line in new_lines
-                    if line not in existing_lines and not line.startswith("#")
+                    if line.rstrip("/") not in existing_normalized
+                    and not line.startswith("#")
                 ]
                 if missing:
                     with open(target, "a", encoding="utf-8") as f:
@@ -228,20 +229,21 @@ def _finalize_scaffold(existing_hashes, all_hash_dicts, created, skipped, warnin
         flags = {}
     if registries is None:
         registries = [registry] if registry else []
-    # Make all shell scripts in scripts/ executable
-    scripts_dir = os.path.join(".", "scripts")
-    if os.path.isdir(scripts_dir):
-        for entry in os.listdir(scripts_dir):
+    # Make all shell scripts in .rlsbl/hooks/ executable
+    hooks_dir = os.path.join(".", ".rlsbl", "hooks")
+    if os.path.isdir(hooks_dir):
+        for entry in os.listdir(hooks_dir):
             if entry.endswith(".sh"):
-                os.chmod(os.path.join(scripts_dir, entry), 0o755)
+                os.chmod(os.path.join(hooks_dir, entry), 0o755)
 
-    # Auto-install pre-push hook if not already present
-    hook_source = os.path.join("scripts", "pre-push-hook.sh")
+    # Auto-install pre-push hook as a one-liner that delegates to the subcommand
     hook_target = os.path.join(".git", "hooks", "pre-push")
-    if os.path.exists(hook_source) and os.path.isdir(".git"):
+    if os.path.isdir(".git"):
         if not os.path.exists(hook_target):
+            hook_content = "#!/usr/bin/env bash\nexec rlsbl pre-push-check \"$@\"\n"
             os.makedirs(os.path.join(".git", "hooks"), exist_ok=True)
-            shutil.copy2(hook_source, hook_target)
+            with open(hook_target, "w", encoding="utf-8") as f:
+                f.write(hook_content)
             os.chmod(hook_target, 0o755)
             print("Installed pre-push hook (.git/hooks/pre-push)")
 

package/rlsbl/commands/pre_push_check.py

@@ -0,0 +1,77 @@
+"""Pre-push-check command: verify CHANGELOG.md has an entry for the current version."""
+
+import json
+import os
+import re
+import sys
+
+
+def _detect_version():
+    """Detect project type and read the current version.
+
+    Returns (version_string, project_type) or (None, None) if undetectable.
+    """
+    if os.path.exists("go.mod"):
+        # Go projects store version in a VERSION file
+        version_path = "VERSION"
+        if os.path.exists(version_path):
+            with open(version_path, "r", encoding="utf-8") as f:
+                version = f.read().strip()
+            if version:
+                return version, "go"
+        return None, None
+
+    if os.path.exists("package.json"):
+        try:
+            with open("package.json", "r", encoding="utf-8") as f:
+                data = json.load(f)
+            version = data.get("version", "")
+            if version:
+                return version, "npm"
+        except Exception:
+            pass
+        return None, None
+
+    if os.path.exists("pyproject.toml"):
+        try:
+            try:
+                import tomllib
+            except ModuleNotFoundError:
+                import tomli as tomllib  # type: ignore[no-redef]
+            with open("pyproject.toml", "rb") as f:
+                data = tomllib.load(f)
+            version = data.get("project", {}).get("version", "")
+            if version:
+                return version, "pypi"
+        except Exception:
+            pass
+        return None, None
+
+    return None, None
+
+
+def run_cmd(registry, args, flags):
+    """Check that CHANGELOG.md has an entry for the current project version.
+
+    Exits 1 if no changelog entry is found; exits 0 silently on success.
+    """
+    version, _project_type = _detect_version()
+    if not version:
+        # Cannot detect version -- nothing to check
+        sys.exit(0)
+
+    if not os.path.exists("CHANGELOG.md"):
+        # No changelog file -- nothing to check
+        sys.exit(0)
+
+    with open("CHANGELOG.md", "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Look for a heading like "## <version>"
+    pattern = re.compile(r"^## " + re.escape(version) + r"\s*$", re.MULTILINE)
+    if pattern.search(content):
+        sys.exit(0)
+
+    print(f"Error: CHANGELOG.md has no entry for version {version}.", file=sys.stderr)
+    print(f"Add a '## {version}' section before pushing.", file=sys.stderr)
+    sys.exit(1)

package/rlsbl/commands/record_gif.py

@@ -0,0 +1,86 @@
+"""Record-gif command: record a demo GIF using vhs."""
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+from .. import detect_registries
+from ..registries import REGISTRIES
+
+
+def _get_bin_command():
+    """Auto-detect the project's binary command name via registry template vars."""
+    regs = detect_registries()
+    if not regs:
+        return None
+    # Use the first detected registry
+    registry_module = REGISTRIES.get(regs[0])
+    if not registry_module:
+        return None
+    try:
+        tvars = registry_module.get_template_vars(".")
+        return tvars.get("binCommand") or None
+    except Exception:
+        return None
+
+
+def run_cmd(registry, args, flags):
+    """Record a demo GIF of '<binCommand> --help' using vhs.
+
+    Requires vhs (https://github.com/charmbracelet/vhs) to be installed.
+    Output is saved to assets/demo.gif.
+    """
+    if not shutil.which("vhs"):
+        print("Error: vhs is required.", file=sys.stderr)
+        print("Install: go install github.com/charmbracelet/vhs@latest", file=sys.stderr)
+        sys.exit(1)
+
+    bin_command = _get_bin_command()
+    if not bin_command:
+        print("Error: could not detect project binary command.", file=sys.stderr)
+        print("Ensure package.json, pyproject.toml, or go.mod exists with a CLI entry point.", file=sys.stderr)
+        sys.exit(1)
+
+    assets_dir = "assets"
+    os.makedirs(assets_dir, exist_ok=True)
+
+    # Create a temporary VHS tape file in the project directory
+    tape_content = (
+        'Set FontFamily "monospace"\n'
+        "Set FontSize 24\n"
+        "Set Width 1200\n"
+        "Set Height 600\n"
+        "Set TypingSpeed 50ms\n"
+        f'Type "{bin_command} --help"\n'
+        "Enter\n"
+        "Sleep 3s\n"
+    )
+
+    tape_fd, tape_path = tempfile.mkstemp(suffix=".tape", dir=".")
+    try:
+        with os.fdopen(tape_fd, "w") as f:
+            f.write(tape_content)
+
+        output_path = os.path.join(assets_dir, "demo.gif")
+        print("Recording demo...")
+
+        subprocess.run(
+            ["vhs", tape_path, "-o", output_path],
+            check=True, timeout=120,
+        )
+
+        print(f"Done. GIF saved to {output_path}")
+    except subprocess.CalledProcessError:
+        print("Error: vhs recording failed.", file=sys.stderr)
+        sys.exit(1)
+    except subprocess.TimeoutExpired:
+        print("Error: vhs recording timed out after 120s.", file=sys.stderr)
+        sys.exit(1)
+    finally:
+        # Clean up the temp tape file
+        try:
+            os.unlink(tape_path)
+        except OSError:
+            pass

package/rlsbl/commands/release.py

@@ -18,7 +18,6 @@ from ..utils import (
     is_clean_tree,
     push_if_needed,
     run,
-    spawn_ci_watcher,
 )
 
 VALID_BUMP_TYPES = ("patch", "minor", "major")
@@ -113,7 +112,7 @@ def run_cmd(registry, args, flags):
         )
 
     # Run pre-release hook if present
-    pre_release_script = os.path.join(".", "scripts", "pre-release.sh")
+    pre_release_script = os.path.join(".", ".rlsbl", "hooks", "pre-release.sh")
     if os.path.exists(pre_release_script):
         log("Running pre-release hook...")
         try:
@@ -256,7 +255,7 @@ def run_cmd(registry, args, flags):
         ensure_github_topic(quiet=quiet)
 
     # Run post-release hook if present (non-fatal: release is already complete)
-    post_release_script = os.path.join(".", "scripts", "post-release.sh")
+    post_release_script = os.path.join(".", ".rlsbl", "hooks", "post-release.sh")
     if os.path.exists(post_release_script):
         log("Running post-release hook...")
         try:
@@ -266,11 +265,10 @@ def run_cmd(registry, args, flags):
         except Exception as e:
             print(f"Warning: post-release hook failed: {e}", file=sys.stderr)
 
-    # Watch CI in the background and notify on completion
+    # Hint: how to watch CI for this release
     try:
         commit_sha = run("git", ["rev-parse", "HEAD"])
-        spawn_ci_watcher(commit_sha, tag)
-        log("Watching CI in background (will notify when done)")
+        log(f"Watch CI: rlsbl watch {commit_sha}")
     except Exception:
         pass
 

package/rlsbl/commands/watch.py

@@ -0,0 +1,115 @@
+"""Watch command: monitor CI runs for a commit and report results."""
+
+import json
+import shutil
+import subprocess
+import sys
+import time
+
+from ..utils import run
+
+
+def _notify(title, body):
+    """Send a desktop notification. Non-fatal if unavailable."""
+    try:
+        if sys.platform == "darwin":
+            subprocess.run(
+                ["osascript", "-e",
+                 f'display notification "{body}" with title "{title}"'],
+                timeout=5, capture_output=True,
+            )
+        elif shutil.which("notify-send"):
+            subprocess.run(
+                ["notify-send", "-u", "normal", title, body],
+                timeout=5, capture_output=True,
+            )
+    except Exception:
+        pass
+
+
+def run_cmd(registry, args, flags):
+    """Watch all CI runs for a commit until they complete.
+
+    Usage: rlsbl watch [<commit-sha>]
+    Defaults to HEAD if no commit SHA is provided.
+    """
+    # Get commit SHA
+    if args:
+        commit_sha = args[0]
+    else:
+        try:
+            commit_sha = run("git", ["rev-parse", "HEAD"])
+        except Exception:
+            print("Error: not a git repository and no commit SHA provided.", file=sys.stderr)
+            sys.exit(1)
+
+    # Get repo info for display and URLs
+    try:
+        repo_info = run("gh", ["repo", "view", "--json", "nameWithOwner,name"])
+        info = json.loads(repo_info)
+        repo_slug = info.get("nameWithOwner", "")
+        repo_name = info.get("name", "")
+    except Exception:
+        print("Error: could not get repo info. Is gh installed and authenticated?", file=sys.stderr)
+        sys.exit(1)
+
+    # Try to find a tag for this commit for nicer display
+    try:
+        tag = run("git", ["describe", "--tags", "--exact-match", commit_sha])
+    except Exception:
+        tag = commit_sha[:12]
+
+    label = f"{repo_name} {tag}" if repo_name else tag
+
+    # Poll until at least one run appears (retry up to 30s)
+    runs = []
+    for _ in range(15):
+        try:
+            raw = run("gh", ["run", "list", "--commit", commit_sha,
+                             "--json", "databaseId,name,status"])
+            parsed = json.loads(raw)
+            if parsed:
+                runs = parsed
+                break
+        except Exception:
+            pass
+        time.sleep(2)
+
+    if not runs:
+        print(f"rlsbl: {label}: no CI runs found after 30s", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"rlsbl: {label}: found {len(runs)} CI run(s), watching...", file=sys.stderr)
+
+    # Watch each run sequentially, collecting results
+    any_failed = False
+    for ci_run in runs:
+        run_id = str(ci_run["databaseId"])
+        workflow_name = ci_run.get("name", f"run {run_id}")
+
+        try:
+            # gh run watch blocks until the run completes;
+            # --exit-status makes it exit 1 on failure; check=True raises
+            # CalledProcessError so we can distinguish pass from fail
+            subprocess.run(
+                ["gh", "run", "watch", run_id, "--exit-status"],
+                capture_output=True, text=True, timeout=3600, check=True,
+            )
+            print(f"rlsbl: {label}: {workflow_name} passed", file=sys.stderr)
+        except subprocess.CalledProcessError:
+            any_failed = True
+            print(f"rlsbl: {label}: {workflow_name} FAILED", file=sys.stderr)
+            if repo_slug:
+                print(f"rlsbl: https://github.com/{repo_slug}/actions/runs/{run_id}",
+                      file=sys.stderr)
+        except subprocess.TimeoutExpired:
+            any_failed = True
+            print(f"rlsbl: {label}: {workflow_name} timed out after 1h", file=sys.stderr)
+
+    # Desktop notification for overall result
+    if any_failed:
+        _notify(f"{label}: CI FAILED", "One or more workflows failed")
+    else:
+        _notify(f"{label}: CI passed", "All workflows passed")
+
+    sys.exit(1 if any_failed else 0)

package/rlsbl/registries/go.py

@@ -86,6 +86,7 @@ def get_template_vars(dir_path):
         "author": author,
         "repoName": repo_name,
         "binCommand": short_name,
+        "publishSetup": "GoReleaser handles binary publishing via GitHub Actions (no secrets needed)",
     }
 
 
@@ -106,12 +107,9 @@ def get_shared_template_mappings():
         {"template": "gitignore.tpl", "target": ".gitignore"},
         {"template": "LICENSE.tpl", "target": "LICENSE"},
         {"template": "CLAUDE.md.tpl", "target": "CLAUDE.md"},
-        {"template": "check-prs.sh.tpl", "target": "scripts/check-prs.sh"},
         {"template": "claude-settings.json.tpl", "target": ".claude/settings.json"},
-        {"template": "record-gif.sh.tpl", "target": "scripts/record-gif.sh"},
-        {"template": "pre-release.sh.tpl", "target": "scripts/pre-release.sh"},
-        {"template": "post-release.sh.tpl", "target": "scripts/post-release.sh"},
-        {"template": "pre-push-hook.sh.tpl", "target": "scripts/pre-push-hook.sh"},
+        {"template": "hooks/pre-release.sh.tpl", "target": ".rlsbl/hooks/pre-release.sh"},
+        {"template": "hooks/post-release.sh.tpl", "target": ".rlsbl/hooks/post-release.sh"},
     ]
 
 

package/rlsbl/registries/npm.py

@@ -84,6 +84,7 @@ def get_template_vars(dir_path):
         "binCommand": bin_command,
         "author": pkg.get("author", ""),
         "repoName": repo_name,
+        "publishSetup": "Requires NPM_TOKEN secret on GitHub (Settings > Secrets > Actions)",
     }
 
 
@@ -102,11 +103,8 @@ def get_shared_template_mappings():
         {"template": "gitignore.tpl", "target": ".gitignore"},
         {"template": "LICENSE.tpl", "target": "LICENSE"},
         {"template": "CLAUDE.md.tpl", "target": "CLAUDE.md"},
-        {"template": "check-prs.sh.tpl", "target": "scripts/check-prs.sh"},
-        {"template": "record-gif.sh.tpl", "target": "scripts/record-gif.sh"},
-        {"template": "pre-release.sh.tpl", "target": "scripts/pre-release.sh"},
-        {"template": "post-release.sh.tpl", "target": "scripts/post-release.sh"},
-        {"template": "pre-push-hook.sh.tpl", "target": "scripts/pre-push-hook.sh"},
+        {"template": "hooks/pre-release.sh.tpl", "target": ".rlsbl/hooks/pre-release.sh"},
+        {"template": "hooks/post-release.sh.tpl", "target": ".rlsbl/hooks/post-release.sh"},
         {"template": "claude-settings.json.tpl", "target": ".claude/settings.json"},
     ]
 

package/rlsbl/registries/pypi.py

@@ -136,6 +136,7 @@ def get_template_vars(dir_path):
         "author": author,
         "repoName": repo_name,
         "importName": import_name,
+        "publishSetup": "Configure Trusted Publishing on pypi.org for automated PyPI releases",
     }
 
 
@@ -154,11 +155,8 @@ def get_shared_template_mappings():
         {"template": "gitignore.tpl", "target": ".gitignore"},
         {"template": "LICENSE.tpl", "target": "LICENSE"},
         {"template": "CLAUDE.md.tpl", "target": "CLAUDE.md"},
-        {"template": "check-prs.sh.tpl", "target": "scripts/check-prs.sh"},
-        {"template": "record-gif.sh.tpl", "target": "scripts/record-gif.sh"},
-        {"template": "pre-release.sh.tpl", "target": "scripts/pre-release.sh"},
-        {"template": "post-release.sh.tpl", "target": "scripts/post-release.sh"},
-        {"template": "pre-push-hook.sh.tpl", "target": "scripts/pre-push-hook.sh"},
+        {"template": "hooks/pre-release.sh.tpl", "target": ".rlsbl/hooks/pre-release.sh"},
+        {"template": "hooks/post-release.sh.tpl", "target": ".rlsbl/hooks/post-release.sh"},
         {"template": "claude-settings.json.tpl", "target": ".claude/settings.json"},
     ]
 

package/rlsbl/utils.py

@@ -108,112 +108,6 @@ def find_commit_tool():
     return "git"
 
 
-def spawn_ci_watcher(commit_sha, tag):
-    """Spawn a detached background process that watches CI and prints results to stderr.
-
-    The spawned process inherits the parent's stderr so output appears in the
-    same terminal/stream -- important for AI agents that read stderr.
-    Desktop notifications are sent as a secondary channel when available.
-    """
-    repo_slug = ""
-    try:
-        repo_slug = run("gh", ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"])
-    except Exception:
-        pass
-
-    repo_name = ""
-    try:
-        repo_name = run("gh", ["repo", "view", "--json", "name", "-q", ".name"])
-    except Exception:
-        pass
-
-    label = f"{repo_name} {tag}" if repo_name else tag
-
-    # Build the notification snippet based on what's available on this platform
-    notify_snippet = _notify_snippet()
-
-    script = f"""
-import subprocess, sys, time
-
-commit_sha = {commit_sha!r}
-label = {label!r}
-repo_slug = {repo_slug!r}
-
-# Find the CI run by commit SHA (retry up to 30s)
-run_id = None
-for _ in range(15):
-    try:
-        r = subprocess.run(
-            ["gh", "run", "list", "--commit", commit_sha, "--limit", "1",
-             "--json", "databaseId", "-q", ".[0].databaseId"],
-            capture_output=True, text=True, timeout=10)
-        if r.returncode == 0 and r.stdout.strip():
-            run_id = r.stdout.strip()
-            break
-    except Exception:
-        pass
-    time.sleep(2)
-
-if not run_id:
-    sys.exit(0)
-
-# Watch the run until it completes
-result = subprocess.run(
-    ["gh", "run", "watch", run_id, "--exit-status"],
-    capture_output=True, text=True, timeout=3600)
-
-ok = result.returncode == 0
-
-# Extract last non-empty line as summary for desktop notification
-summary = ""
-for line in reversed(result.stdout.strip().splitlines()):
-    if line.strip():
-        summary = line.strip()
-        break
-
-# Print result to stderr so AI agents and terminal users can see it
-if ok:
-    print(f"rlsbl: {{label}}: CI passed", file=sys.stderr)
-else:
-    print(f"rlsbl: {{label}}: CI FAILED", file=sys.stderr)
-    if repo_slug and run_id:
-        print(f"rlsbl: https://github.com/{{repo_slug}}/actions/runs/{{run_id}}", file=sys.stderr)
-
-# Desktop notification (optional, non-fatal)
-title = f"{{label}}: CI passed" if ok else f"{{label}}: CI FAILED"
-try:
-{notify_snippet}
-except Exception:
-    pass
-"""
-    subprocess.Popen(
-        [sys.executable, "-c", script],
-        start_new_session=True,
-        stdin=subprocess.DEVNULL,
-    )
-
-
-def _notify_snippet():
-    """Return an indented Python code snippet for sending a desktop notification.
-
-    Returns a pass statement if no notification tool is available.
-    The snippet is intended to be embedded inside a try/except block.
-    """
-    indent = "    "
-    if sys.platform == "darwin":
-        return (
-            f'{indent}subprocess.run(["osascript", "-e",\n'
-            f'{indent}    f\'display notification "{{summary}}" with title "{{title}}"\'],\n'
-            f'{indent}    timeout=5)'
-        )
-    if shutil.which("notify-send"):
-        return (
-            f'{indent}urgency = "normal" if ok else "critical"\n'
-            f'{indent}subprocess.run(["notify-send", "-u", urgency, title, summary], timeout=5)'
-        )
-    return f"{indent}pass"
-
-
 def bump_version(version, bump_type):
     """Bump a semver version string by the given type (patch, minor, major).
 

package/templates/go/ci.yml.tpl

@@ -13,8 +13,8 @@ jobs:
       matrix:
         go-version: ["1.22", "1.23", "1.24"]
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
         with:
           go-version: ${{ matrix.go-version }}
       - run: go test ./...

package/templates/go/publish.yml.tpl

@@ -11,15 +11,15 @@ jobs:
   goreleaser:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - uses: actions/setup-go@v5
+      - uses: actions/setup-go@v6
         with:
           go-version-file: go.mod
-      - uses: goreleaser/goreleaser-action@v6
+      - uses: goreleaser/goreleaser-action@v7
         with:
-          version: latest
+          version: "~> v2"
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/templates/merged/publish.yml.tpl

@@ -12,8 +12,8 @@ jobs:
   npm:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           registry-url: https://registry.npmjs.org
@@ -24,7 +24,7 @@ jobs:
   pypi:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: astral-sh/setup-uv@v7
       - run: uv build
       - uses: pypa/gh-action-pypi-publish@release/v1

package/templates/npm/ci.yml.tpl

@@ -13,8 +13,8 @@ jobs:
       matrix:
         node-version: [18, 20, 22]
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: ${{ matrix.node-version }}
       - run: node -e "require('./package.json')"

package/templates/npm/publish.yml.tpl

@@ -12,8 +12,8 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
           registry-url: https://registry.npmjs.org

package/templates/pypi/ci.yml.tpl

@@ -13,7 +13,7 @@ jobs:
       matrix:
         python-version: ["3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: astral-sh/setup-uv@v7
       - run: uv python install ${{ matrix.python-version }}
       - run: uv sync

package/templates/pypi/publish.yml.tpl

@@ -12,7 +12,7 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: astral-sh/setup-uv@v7
       - run: uv build
       - uses: pypa/gh-action-pypi-publish@release/v1

package/templates/shared/CLAUDE.md.tpl

@@ -8,7 +8,7 @@ This project uses [rlsbl](https://github.com/smm-h/rlsbl) for release orchestrat
 - Run `rlsbl release [patch|minor|major]` to bump version and create a GitHub Release
 - CI handles publishing automatically via the publish workflow
 - Never publish manually — always use `rlsbl release`
-- Requires `NPM_TOKEN` secret on GitHub (for npm projects)
+- {{publishSetup}}
 - Use `rlsbl release --dry-run` to preview a release without making changes
 
 ## Conventions

package/templates/shared/claude-settings.json.tpl

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./scripts/check-prs.sh"
+            "command": "rlsbl check-prs"
           }
         ]
       }

package/templates/shared/check-prs.sh.tpl

@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-# List open PRs for awareness at session start.
-# Safe to run in hooks -- always exits 0.
-cd "$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
-count=$(gh pr list --state open --json number --jq length 2>/dev/null) || exit 0
-if [ "$count" -gt 0 ]; then
-  echo "Open PRs: $count"
-  gh pr list --state open
-fi
-exit 0

package/templates/shared/pre-push-hook.sh.tpl

@@ -1,44 +0,0 @@
-#!/usr/bin/env bash
-# Pre-push hook: verify CHANGELOG.md has an entry for the current version.
-# Install: cp scripts/pre-push-hook.sh .git/hooks/pre-push && chmod +x .git/hooks/pre-push
-
-set -euo pipefail
-
-# Detect project type and extract version
-if [ -f package.json ]; then
-  VERSION=$(node -e "console.log(require('./package.json').version)" 2>/dev/null) || exit 0
-elif [ -f pyproject.toml ]; then
-  VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)".*/\1/') || exit 0
-elif [ -f VERSION ]; then
-  VERSION=$(tr -d '[:space:]' < VERSION) || exit 0
-else
-  exit 0
-fi
-
-if [ -z "$VERSION" ]; then
-  exit 0
-fi
-
-# Check CHANGELOG.md has an entry for this version
-if [ ! -f CHANGELOG.md ]; then
-  echo "Warning: CHANGELOG.md not found."
-  exit 0
-fi
-
-if ! grep -q "^## $VERSION" CHANGELOG.md; then
-  echo "Error: CHANGELOG.md has no entry for version $VERSION."
-  echo "Add a '## $VERSION' section before pushing."
-  exit 1
-fi
-
-# Check scaffolding freshness
-if [ -f .rlsbl/version ]; then
-  SCAFFOLD_VER=$(cat .rlsbl/version | tr -d '[:space:]')
-  if command -v rlsbl &>/dev/null; then
-    CURRENT_VER=$(rlsbl --version 2>/dev/null | tr -d '[:space:]')
-    if [ -n "$CURRENT_VER" ] && [ "$SCAFFOLD_VER" != "$CURRENT_VER" ]; then
-      echo "Warning: scaffolding was generated by rlsbl $SCAFFOLD_VER but you have $CURRENT_VER installed."
-      echo "Run 'rlsbl scaffold --update' to update scaffolding."
-    fi
-  fi
-fi

package/templates/shared/record-gif.sh.tpl

@@ -1,34 +0,0 @@
-#!/usr/bin/env bash
-# Record a demo GIF for README. Requires: vhs (https://github.com/charmbracelet/vhs).
-# Usage: ./scripts/record-gif.sh [duration_seconds]
-set -euo pipefail
-
-DURATION="${1:-10}"
-ASSETS_DIR="assets"
-
-mkdir -p "$ASSETS_DIR"
-
-if ! command -v vhs &>/dev/null; then
-  echo "Error: vhs is required."
-  echo "Install: go install github.com/charmbracelet/vhs@latest"
-  exit 1
-fi
-
-TAPE=$(mktemp /tmp/record-XXXX.tape)
-cat > "$TAPE" <<EOF
-Set FontFamily "monospace"
-Set FontSize 24
-Set Width 1200
-Set Height 600
-Set TypingSpeed 50ms
-Type "{{binCommand}} --help"
-Enter
-Sleep 3s
-EOF
-
-echo "Recording demo..."
-vhs "$TAPE" -o "$ASSETS_DIR/demo.gif"
-rm -f "$TAPE"
-
-echo "Done. GIF saved to $ASSETS_DIR/demo.gif"
-echo "Edit this script to customize the recording."