rlsbl 0.5.0 → 0.5.2

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/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.
 
 ### status
 
@@ -127,6 +127,8 @@ When you run `release`, the following happens in order:
 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.
+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,11 +143,14 @@ When you run `release`, the following happens in order:
 | `.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 |
 
 All `.sh` files in `scripts/` are made executable automatically. The pre-push hook is installed into `.git/hooks/pre-push` during scaffold.
 
+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.
@@ -180,6 +185,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. |
 
 ## Requirements
 

package/package.json

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

package/rlsbl/__init__.py

@@ -3,11 +3,40 @@
 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")
@@ -145,14 +174,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:

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/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

@@ -177,13 +177,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:

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)",
     }
 
 

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)",
     }
 
 

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",
     }
 
 

package/rlsbl/utils.py

@@ -109,27 +109,42 @@ def find_commit_tool():
 
 
 def spawn_ci_watcher(commit_sha, tag):
-    """Spawn a detached background process that watches CI and sends a desktop notification."""
+    """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
 
-    notify_cmd = _notify_command()
-    if not notify_cmd:
-        return
-
     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",
+            ["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():
@@ -142,43 +157,61 @@ for _ in range(15):
 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
 
-ok = result.returncode == 0
-title = "{label}: CI passed" if ok else "{label}: CI FAILED"
-{notify_cmd}
+# 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,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
     )
 
 
-def _notify_command():
-    """Return a Python code snippet for sending a desktop notification, or None."""
+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 (
-            'subprocess.run(["osascript", "-e",'
-            ' f\'display notification "{summary}" with title "{title}"\'],'
-            ' timeout=5)'
+            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 (
-            'urgency = "normal" if ok else "critical"\n'
-            'subprocess.run(["notify-send", "-u", urgency, title, summary], timeout=5)'
+            f'{indent}urgency = "normal" if ok else "critical"\n'
+            f'{indent}subprocess.run(["notify-send", "-u", urgency, title, summary], timeout=5)'
         )
-    return None
+    return f"{indent}pass"
 
 
 def bump_version(version, bump_type):

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/record-gif.sh.tpl

@@ -14,7 +14,7 @@ if ! command -v vhs &>/dev/null; then
   exit 1
 fi
 
-TAPE=$(mktemp /tmp/record-XXXX.tape)
+TAPE=$(mktemp)
 cat > "$TAPE" <<EOF
 Set FontFamily "monospace"
 Set FontSize 24