rlsbl 0.5.2 → 0.7.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 `record-gif` and `pre-push-check` functionality is provided as built-in subcommands (`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.2",
+  "version": "0.7.0",
   "description": "Release orchestration and project scaffolding for npm and PyPI",
   "license": "MIT",
   "bin": {

package/rlsbl/__init__.py

@@ -39,7 +39,8 @@ def _detect_version():
 __version__ = _detect_version()
 
 REGISTRIES = ("npm", "pypi", "go")
-COMMANDS = ("release", "status", "scaffold", "check", "config", "undo", "discover")
+COMMANDS = ("release", "status", "scaffold", "check", "config", "undo", "discover", "watch",
+            "pre-push-check", "record-gif")
 COMMAND_ALIASES = {"init": "scaffold"}
 
 HELP = f"""\
@@ -53,6 +54,9 @@ 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 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)
@@ -118,6 +122,9 @@ def _get_command_module(command):
         "config": "config",
         "undo": "undo",
         "discover": "discover",
+        "watch": "watch",
+        "pre-push-check": "pre_push_check",
+        "record-gif": "record_gif",
     }
     module_name = module_map.get(command)
     if not module_name:
@@ -214,6 +221,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 ("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/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/init_cmd.py

@@ -4,9 +4,10 @@ import hashlib
 import json
 import os
 import re
-import shutil
-import stat
 import sys
+from io import StringIO
+
+from ruamel.yaml import YAML
 
 from ..config import should_tag
 from ..registries import REGISTRIES
@@ -21,13 +22,19 @@ APPEND_MARKER = "rlsbl"
 # Files where missing entries from the template are merged into the existing file
 MERGEABLE = {".gitignore"}
 
-# Files that are safe to overwrite during --update (managed files users typically don't customize)
-UPDATABLE = {
-    ".github/workflows/ci.yml",
-    ".github/workflows/publish.yml",
-    "scripts/check-prs.sh",
-    "scripts/post-release.sh",
-    "scripts/pre-push-hook.sh",
+# JSON files where template keys are deep-merged into existing user content
+JSON_MERGEABLE = {".claude/settings.json"}
+
+# YAML workflow files with job-level merge: template jobs overwrite same-key user jobs,
+# user-added jobs are preserved. Top-level keys (name, on, permissions) come from template.
+YAML_MERGEABLE = {".github/workflows/ci.yml", ".github/workflows/publish.yml"}
+
+# Files owned by the user after initial scaffold -- never overwrite or merge
+USER_OWNED = {
+    "CHANGELOG.md",
+    "LICENSE",
+    ".rlsbl/hooks/pre-release.sh",
+    ".rlsbl/hooks/post-release.sh",
 }
 
 def file_hash(path):
@@ -89,6 +96,100 @@ def process_template(template_content, vars_dict):
     return content, unreplaced
 
 
+def _deep_merge(base, override):
+    """Deep-merge two JSON-like structures. User values (base) take precedence.
+
+    - Dicts: recursively merge; keys only in override are added, base keys kept.
+    - Lists: union by value; base items first, then new override items (deduplicated).
+    - Scalars: base wins.
+    """
+    if isinstance(base, dict) and isinstance(override, dict):
+        merged = {}
+        for key in base:
+            if key in override:
+                merged[key] = _deep_merge(base[key], override[key])
+            else:
+                merged[key] = base[key]
+        for key in override:
+            if key not in base:
+                merged[key] = override[key]
+        return merged
+    if isinstance(base, list) and isinstance(override, list):
+        # Deduplicate by value: keep base order, append new items from override
+        seen = set()
+        for item in base:
+            # Use JSON serialization for unhashable items (dicts, lists)
+            try:
+                seen.add(item)
+            except TypeError:
+                seen.add(json.dumps(item, sort_keys=True))
+        result = list(base)
+        for item in override:
+            if isinstance(item, (dict, list)):
+                key = json.dumps(item, sort_keys=True)
+            else:
+                key = item
+            if key not in seen:
+                seen.add(key)
+                result.append(item)
+        return result
+    # Scalars: base (user) wins
+    return base
+
+
+def _yaml_merge_workflow(existing_text, template_text):
+    """Merge a YAML workflow at the job level.
+
+    Template wins for top-level keys (name, on, permissions, etc.).
+    For the 'jobs' key: template jobs overwrite same-key user jobs,
+    user-added jobs not in the template are preserved at the end.
+
+    Returns (merged_text, error_msg). error_msg is None on success.
+    """
+    yaml = YAML(typ="rt")
+    yaml.preserve_quotes = True
+    try:
+        existing = yaml.load(existing_text)
+    except Exception as e:
+        return None, f"failed to parse existing YAML: {e}"
+    try:
+        template = yaml.load(template_text)
+    except Exception as e:
+        return None, f"failed to parse template YAML: {e}"
+
+    if not isinstance(existing, dict) or not isinstance(template, dict):
+        return None, "YAML root is not a mapping"
+
+    # Start with template as the base (template wins for top-level keys)
+    merged = type(template)()
+    for key in template:
+        merged[key] = template[key]
+
+    # Merge jobs: template jobs first (overwriting user jobs with same key),
+    # then append user-only jobs
+    template_jobs = template.get("jobs") or {}
+    existing_jobs = existing.get("jobs") or {}
+
+    merged_jobs = type(template_jobs)() if template_jobs else type(existing_jobs)()
+    # Template jobs in template order
+    for job_key in template_jobs:
+        merged_jobs[job_key] = template_jobs[job_key]
+    # User-added jobs not in template, preserved at the end
+    for job_key in existing_jobs:
+        if job_key not in template_jobs:
+            merged_jobs[job_key] = existing_jobs[job_key]
+    merged["jobs"] = merged_jobs
+
+    # Preserve any user top-level keys not in the template (rare, but safe)
+    for key in existing:
+        if key not in merged:
+            merged[key] = existing[key]
+
+    buf = StringIO()
+    yaml.dump(merged, buf)
+    return buf.getvalue(), None
+
+
 def process_mappings(template_dir, mappings, vars_dict, force, update=False,
                      existing_hashes=None):
     """Process a list of template mappings: read each template, apply vars, write target files.
@@ -96,9 +197,8 @@ def process_mappings(template_dir, mappings, vars_dict, force, update=False,
     Skips existing files unless force is True, with special handling:
     - APPENDABLE files: append template sections if the marker is not already present
     - MERGEABLE files: merge missing entries from the template into the existing file
-    - UPDATABLE files (with --update): overwrite only if the file hasn't been customized
-      (detected via SHA-256 hash comparison against stored hashes)
-
+    - JSON_MERGEABLE files: deep-merge template JSON into existing (user values preserved)
+    - YAML_MERGEABLE files: job-level merge for CI workflows (template jobs win, user jobs preserved)
     Returns (created, skipped, warnings, new_hashes).
     """
     if existing_hashes is None:
@@ -121,29 +221,88 @@ def process_mappings(template_dir, mappings, vars_dict, force, update=False,
         if os.path.exists(target) and not force:
             basename = os.path.basename(target)
 
-            # In --update mode, overwrite managed files only if not customized
-            if update and target in UPDATABLE:
-                current_hash = file_hash(target)
-                stored_hash = existing_hashes.get(target)
-                if stored_hash and current_hash == stored_hash:
-                    # File matches stored hash -- not customized, safe to overwrite
-                    with open(template_path, "r", encoding="utf-8") as f:
-                        raw = f.read()
-                    content, unreplaced = process_template(raw, vars_dict)
-                    target_dir = os.path.dirname(target)
-                    if target_dir and target_dir != ".":
-                        os.makedirs(target_dir, exist_ok=True)
-                    with open(target, "w", encoding="utf-8") as f:
-                        f.write(content)
-                    new_hashes[target] = file_hash(target)
-                    created.append(target + " (updated)")
-                    if unreplaced:
-                        warnings.append(f"{target}: unreplaced vars: {', '.join(unreplaced)}")
+            # User-owned files are never touched after initial scaffold,
+            # except LICENSE gets its copyright year updated on --update.
+            if target in USER_OWNED:
+                if update and target == "LICENSE":
+                    from datetime import datetime
+                    current_year = str(datetime.now().year)
+                    with open(target, "r", encoding="utf-8") as f:
+                        content = f.read()
+                    # Match "Copyright (c) YYYY" or "Copyright (c) YYYY-YYYY"
+                    updated = re.sub(
+                        r"(Copyright\s+\(c\)\s+\d{4})-(\d{4})",
+                        lambda m: (
+                            m.group(0) if m.group(2) == current_year
+                            else f"{m.group(1)}-{current_year}"
+                        ),
+                        content,
+                    )
+                    if updated == content:
+                        # No range found or range already current -- try single year
+                        updated = re.sub(
+                            r"(Copyright\s+\(c\)\s+)(\d{4})(?![-\d])",
+                            lambda m: (
+                                m.group(0) if m.group(2) == current_year
+                                else f"{m.group(1)}{m.group(2)}-{current_year}"
+                            ),
+                            content,
+                        )
+                    if updated != content:
+                        with open(target, "w", encoding="utf-8") as f:
+                            f.write(updated)
+                        created.append("LICENSE (year updated)")
+                    else:
+                        skipped.append(target)
                 else:
-                    # File was customized or no stored hash -- skip conservatively
-                    # Seed the hash so future --update can detect changes
-                    new_hashes[target] = current_hash
-                    skipped.append(f"{target} (customized, use --force to overwrite)")
+                    skipped.append(target)
+                continue
+
+            if target in JSON_MERGEABLE:
+                with open(target, "r", encoding="utf-8") as f:
+                    existing_text = f.read()
+                with open(template_path, "r", encoding="utf-8") as f:
+                    raw = f.read()
+                content, unreplaced = process_template(raw, vars_dict)
+                try:
+                    existing_data = json.loads(existing_text)
+                    template_data = json.loads(content)
+                except json.JSONDecodeError as e:
+                    warnings.append(f"{target}: JSON parse error during merge: {e}")
+                    skipped.append(target)
+                    continue
+                merged = _deep_merge(existing_data, template_data)
+                target_dir = os.path.dirname(target)
+                if target_dir and target_dir != ".":
+                    os.makedirs(target_dir, exist_ok=True)
+                with open(target, "w", encoding="utf-8") as f:
+                    f.write(json.dumps(merged, indent=2))
+                    f.write("\n")
+                created.append(target + " (merged)")
+                if unreplaced:
+                    warnings.append(f"{target}: unreplaced vars: {', '.join(unreplaced)}")
+                continue
+
+            if target in YAML_MERGEABLE:
+                with open(target, "r", encoding="utf-8") as f:
+                    existing_text = f.read()
+                with open(template_path, "r", encoding="utf-8") as f:
+                    raw = f.read()
+                content, unreplaced = process_template(raw, vars_dict)
+                merged_text, err = _yaml_merge_workflow(existing_text, content)
+                if err:
+                    warnings.append(f"{target}: YAML merge skipped: {err}")
+                    skipped.append(target)
+                    continue
+                target_dir = os.path.dirname(target)
+                if target_dir and target_dir != ".":
+                    os.makedirs(target_dir, exist_ok=True)
+                with open(target, "w", encoding="utf-8") as f:
+                    f.write(merged_text)
+                new_hashes[target] = file_hash(target)
+                created.append(target + " (merged)")
+                if unreplaced:
+                    warnings.append(f"{target}: unreplaced vars: {', '.join(unreplaced)}")
                 continue
 
             if basename in APPENDABLE:
@@ -234,20 +393,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

@@ -107,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

@@ -103,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

@@ -155,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/shared/claude-settings.json.tpl

@@ -1,15 +1,3 @@
 {
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "./scripts/check-prs.sh"
-          }
-        ]
-      }
-    ]
-  }
+  "hooks": {}
 }

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)
-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."