rlsbl 0.4.2 → 0.5.1

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
 
@@ -84,6 +84,31 @@ rlsbl check my-cool-lib --registry npm   # npm only
 
 npm checks variant spellings (hyphens, underscores, dots, no separator). PyPI normalizes per PEP 503 and checks common alternatives.
 
+### discover [--mine]
+
+Lists all projects in the rlsbl ecosystem by querying GitHub for repositories with the `rlsbl` topic.
+
+```
+rlsbl discover
+rlsbl discover --mine              # only your repos
+```
+
+Uses GitHub token if available (higher rate limit). Works unauthenticated for public repos.
+
+### Ecosystem tagging
+
+By default, `scaffold` and `release` add an `"rlsbl"` keyword to `package.json` and/or `pyproject.toml`, and set the `rlsbl` topic on the GitHub repository. This makes projects discoverable via `rlsbl discover`.
+
+To disable tagging:
+
+| Method | Scope |
+|---|---|
+| `--no-tag` flag | Single invocation |
+| `{"tag": false}` in `.rlsbl/config.json` | This project |
+| `{"tag": false}` in `~/.rlsbl/config.json` | All your projects |
+
+Precedence: CLI flag > project config > user config > default (enabled).
+
 Global flags: `--help`, `--version`.
 
 ## Release flow
@@ -102,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
 
@@ -116,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.
@@ -155,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.4.2",
+  "version": "0.5.1",
   "description": "Release orchestration and project scaffolding for npm and PyPI",
   "license": "MIT",
   "bin": {
@@ -24,7 +24,8 @@
     "pypi",
     "publish",
     "cli",
-    "scaffold"
+    "scaffold",
+    "rlsbl"
   ],
   "author": "smm-h"
 }

package/rlsbl/__init__.py

@@ -10,7 +10,7 @@ except Exception:
     __version__ = "unknown"
 
 REGISTRIES = ("npm", "pypi", "go")
-COMMANDS = ("release", "status", "scaffold", "check", "config", "undo")
+COMMANDS = ("release", "status", "scaffold", "check", "config", "undo", "discover")
 COMMAND_ALIASES = {"init": "scaffold"}
 
 HELP = f"""\
@@ -23,9 +23,11 @@ Usage:
   rlsbl check <name>                                        Check name availability
   rlsbl config                                              Show project configuration
   rlsbl undo [--yes]                                        Revert the last release
+  rlsbl discover [--mine]                                   List rlsbl ecosystem projects
 
 Options:
   --registry <npm|pypi|go>  Target a specific registry (auto-detected if omitted)
+  --no-tag               Disable ecosystem tagging for this invocation
   --help, -h             Show this help
   --version, -v          Show version"""
 
@@ -86,6 +88,7 @@ def _get_command_module(command):
         "check": "check",
         "config": "config",
         "undo": "undo",
+        "discover": "discover",
     }
     module_name = module_map.get(command)
     if not module_name:
@@ -176,6 +179,9 @@ def main():
                     sys.exit(1)
                 registry = regs[0]
             handler.run_cmd(registry, args, flags)
+        elif command == "discover":
+            # discover: global query, 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

@@ -1,6 +1,7 @@
 """Config command: show resolved project configuration."""
 
 import os
+from ..config import PROJECT_CONFIG, USER_CONFIG, read_json_config, should_tag
 from ..registries import REGISTRIES
 
 
@@ -41,9 +42,26 @@ def run_cmd(registry, args, flags):
     print("\nHooks:")
     pre_release = os.path.join("scripts", "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")
+    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'}")
 
+    print("\nEcosystem tagging:")
+    enabled = should_tag(flags)
+    # Determine why it's enabled/disabled
+    project_cfg = read_json_config(PROJECT_CONFIG)
+    user_cfg = read_json_config(USER_CONFIG)
+    if flags.get("no-tag"):
+        source = "CLI flag"
+    elif "tag" in project_cfg:
+        source = f"project config ({PROJECT_CONFIG})"
+    elif "tag" in user_cfg:
+        source = f"user config ({USER_CONFIG})"
+    else:
+        source = "default"
+    print(f"  Status: {'enabled' if enabled else 'disabled'} ({source})")
+
     print("\nFiles:")
     for f in ["CHANGELOG.md", "LICENSE", ".gitignore", "CLAUDE.md"]:
         print(f"  {f}: {'yes' if os.path.exists(f) else 'no'}")

package/rlsbl/commands/discover.py

@@ -0,0 +1,194 @@
+"""Discover command: list projects in the rlsbl ecosystem."""
+
+import json
+import os
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+
+SEARCH_URL = "https://api.github.com/search/repositories?q=topic:rlsbl&sort=updated&per_page=100"
+MAX_RESULTS = 1000
+
+
+def _get_github_token():
+    """Get a GitHub token from GITHUB_TOKEN env or `gh auth token`."""
+    token = os.environ.get("GITHUB_TOKEN")
+    if token:
+        return token
+    try:
+        result = subprocess.run(
+            ["gh", "auth", "token"],
+            capture_output=True, text=True, check=True, timeout=10,
+        )
+        return result.stdout.strip() or None
+    except Exception:
+        return None
+
+
+def _make_request(url, token):
+    """Make a GET request to the GitHub API, return parsed JSON and response headers."""
+    req = urllib.request.Request(url, method="GET")
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("User-Agent", "rlsbl-cli")
+    if token:
+        req.add_header("Authorization", f"token {token}")
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        data = json.loads(resp.read().decode("utf-8"))
+        headers = dict(resp.headers)
+        return data, headers
+
+
+def _parse_next_link(headers):
+    """Extract the 'next' URL from the Link header, or None."""
+    link = headers.get("Link") or headers.get("link")
+    if not link:
+        return None
+    for part in link.split(","):
+        if 'rel="next"' in part:
+            # Extract URL between < and >
+            start = part.index("<") + 1
+            end = part.index(">")
+            return part[start:end]
+    return None
+
+
+def _relative_time(iso_timestamp):
+    """Convert an ISO 8601 timestamp to a relative time string like '2d ago'."""
+    from datetime import datetime, timezone
+
+    if not iso_timestamp:
+        return ""
+
+    # Parse ISO timestamp (GitHub uses Z suffix)
+    ts = iso_timestamp.replace("Z", "+00:00")
+    dt = datetime.fromisoformat(ts)
+    now = datetime.now(timezone.utc)
+    delta = now - dt
+
+    seconds = int(delta.total_seconds())
+    if seconds < 60:
+        return "just now"
+    minutes = seconds // 60
+    if minutes < 60:
+        return f"{minutes}m ago"
+    hours = minutes // 60
+    if hours < 24:
+        return f"{hours}h ago"
+    days = hours // 24
+    if days < 7:
+        return f"{days}d ago"
+    weeks = days // 7
+    if weeks < 5:
+        return f"{weeks}w ago"
+    months = days // 30
+    if months < 12:
+        return f"{months}mo ago"
+    years = days // 365
+    return f"{years}y ago"
+
+
+def _get_authenticated_user(token):
+    """Get the authenticated user's login name."""
+    if not token:
+        return None
+    try:
+        req = urllib.request.Request("https://api.github.com/user", method="GET")
+        req.add_header("Accept", "application/vnd.github+json")
+        req.add_header("User-Agent", "rlsbl-cli")
+        req.add_header("Authorization", f"token {token}")
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            return data.get("login")
+    except Exception:
+        return None
+
+
+def _fetch_all_repos(token):
+    """Fetch all repos with the rlsbl topic, handling pagination."""
+    repos = []
+    url = SEARCH_URL
+
+    while url and len(repos) < MAX_RESULTS:
+        data, headers = _make_request(url, token)
+        items = data.get("items", [])
+        repos.extend(items)
+        url = _parse_next_link(headers)
+
+    return repos
+
+
+def run_cmd(registry, args, flags):
+    """Discover command: list projects in the rlsbl ecosystem."""
+    token = _get_github_token()
+    mine_only = flags.get("mine", False)
+
+    if mine_only and not token:
+        print("Error: --mine requires authentication (set GITHUB_TOKEN or install gh CLI).", file=sys.stderr)
+        sys.exit(1)
+
+    # Fetch repos
+    try:
+        repos = _fetch_all_repos(token)
+    except urllib.error.HTTPError as e:
+        print(f"Error: GitHub API returned {e.code}: {e.reason}", 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)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Filter to --mine if requested
+    if mine_only:
+        username = _get_authenticated_user(token)
+        if not username:
+            print("Error: could not determine authenticated user.", file=sys.stderr)
+            sys.exit(1)
+        repos = [r for r in repos if r.get("owner", {}).get("login") == username]
+
+    if not repos:
+        if mine_only:
+            print("No rlsbl-tagged repositories found for your account.")
+        else:
+            print("No rlsbl-tagged repositories found.")
+        return
+
+    # Build table rows
+    rows = []
+    for repo in repos:
+        full_name = repo.get("full_name", "")
+        description = repo.get("description") or ""
+        updated = _relative_time(repo.get("updated_at", ""))
+        rows.append((full_name, description, updated))
+
+    # Calculate column widths
+    name_width = max(len(r[0]) for r in rows)
+    desc_width = max(len(r[1]) for r in rows)
+    time_width = max(len(r[2]) for r in rows)
+
+    # Cap description width to keep output readable
+    max_desc = 40
+    if desc_width > max_desc:
+        desc_width = max_desc
+
+    # Ensure minimum widths match headers
+    name_width = max(name_width, len("owner/repo"))
+    desc_width = max(desc_width, len("description"))
+    time_width = max(time_width, len("updated"))
+
+    # Print header
+    print(f"\nrlsbl ecosystem ({len(repos)} projects)\n")
+    header = f"  {'owner/repo':<{name_width}}  {'description':<{desc_width}}  {'updated':<{time_width}}"
+    print(header)
+    separator_len = name_width + desc_width + time_width + 6
+    print(f"  {'─' * separator_len}")
+
+    # Print rows
+    for full_name, description, updated in rows:
+        # Truncate long descriptions
+        if len(description) > max_desc:
+            description = description[:max_desc - 1] + "…"
+        print(f"  {full_name:<{name_width}}  {description:<{desc_width}}  {updated}")

package/rlsbl/commands/init_cmd.py

@@ -8,7 +8,9 @@ import shutil
 import stat
 import sys
 
+from ..config import should_tag
 from ..registries import REGISTRIES
+from ..tagging import ensure_tags
 
 HASHES_FILE = os.path.join(".rlsbl", "hashes.json")
 
@@ -24,6 +26,7 @@ UPDATABLE = {
     ".github/workflows/ci.yml",
     ".github/workflows/publish.yml",
     "scripts/check-prs.sh",
+    "scripts/post-release.sh",
     "scripts/pre-push-hook.sh",
 }
 
@@ -214,11 +217,17 @@ def process_mappings(template_dir, mappings, vars_dict, force, update=False,
 
 
 def _finalize_scaffold(existing_hashes, all_hash_dicts, created, skipped, warnings,
-                       registry=None):
-    """Shared post-processing for scaffold: chmod, hooks, version marker, hashes, summary.
+                       registry=None, flags=None, registries=None):
+    """Shared post-processing for scaffold: chmod, hooks, version marker, hashes, tagging, summary.
 
     all_hash_dicts is a list of dicts to merge into existing_hashes.
+    flags is the CLI flags dict (used for tagging check).
+    registries is a list of registry names (used for tagging).
     """
+    if flags is None:
+        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):
@@ -252,6 +261,10 @@ def _finalize_scaffold(existing_hashes, all_hash_dicts, created, skipped, warnin
     existing_hashes.update(all_new_hashes)
     save_hashes(existing_hashes)
 
+    # Ecosystem tagging
+    if should_tag(flags):
+        ensure_tags(registries)
+
     # Print summary
     if created:
         print("Created:")
@@ -335,6 +348,7 @@ def run_cmd(registry, args, flags):
     _finalize_scaffold(
         existing_hashes, [reg_hashes, shared_hashes],
         created, skipped, warnings, registry=registry,
+        flags=flags, registries=[registry],
     )
 
 
@@ -402,6 +416,7 @@ def run_cmd_multi(registries_list, args, flags):
     _finalize_scaffold(
         existing_hashes, [ci_hashes, merged_hashes, shared_hashes],
         created, skipped, warnings,
+        flags=flags, registries=registries_list,
     )
 
     # Show combined next steps for dual-registry

package/rlsbl/commands/release.py

@@ -4,7 +4,9 @@ import os
 import sys
 import time
 
+from ..config import should_tag
 from ..registries import REGISTRIES
+from ..tagging import ensure_github_topic, ensure_npm_keyword, ensure_pypi_keyword
 from ..utils import (
     bump_version,
     check_gh_auth,
@@ -16,6 +18,7 @@ from ..utils import (
     is_clean_tree,
     push_if_needed,
     run,
+    spawn_ci_watcher,
 )
 
 VALID_BUMP_TYPES = ("patch", "minor", "major")
@@ -191,8 +194,26 @@ def run_cmd(registry, args, flags):
                     other_reg.write_version(".", new_version)
                     log(f"Synced version to {other_file}")
 
-    # Commit version file changes (skip if version didn't change, e.g. first release)
-    if files_to_commit and new_version != current_version:
+    # Ecosystem tagging: add keyword to manifests if enabled (after confirmation)
+    if should_tag(flags):
+        try:
+            if REGISTRIES["npm"].check_project_exists("."):
+                if ensure_npm_keyword(".", quiet=quiet):
+                    if "package.json" not in files_to_commit:
+                        files_to_commit.append("package.json")
+        except Exception:
+            pass
+        try:
+            if REGISTRIES["pypi"].check_project_exists("."):
+                if ensure_pypi_keyword(".", quiet=quiet):
+                    if "pyproject.toml" not in files_to_commit:
+                        files_to_commit.append("pyproject.toml")
+        except Exception:
+            pass
+
+    # Commit if anything was actually modified (version bump or tagging)
+    needs_commit = new_version != current_version or not is_clean_tree()
+    if files_to_commit and needs_commit:
         commit_tool = find_commit_tool()
         if commit_tool == "safegit":
             run(commit_tool, ["commit", "-m", tag, "--", *files_to_commit])
@@ -200,8 +221,8 @@ def run_cmd(registry, args, flags):
             run("git", ["add", *files_to_commit])
             run("git", ["commit", "-m", tag])
         log(f"Committed: {tag}")
-    else:
-        log("No version bump to commit")
+    elif not needs_commit:
+        log("No changes to commit")
 
     # Create local git tag
     run("git", ["tag", tag])
@@ -230,4 +251,27 @@ def run_cmd(registry, args, flags):
             if os.path.exists(tmp):
                 os.unlink(tmp)
 
+    # Ecosystem tagging: add GitHub topic after release is created
+    if should_tag(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")
+    if os.path.exists(post_release_script):
+        log("Running post-release hook...")
+        try:
+            env = os.environ.copy()
+            env["RLSBL_VERSION"] = new_version
+            run("bash", [post_release_script], env=env)
+        except Exception as e:
+            print(f"Warning: post-release hook failed: {e}", file=sys.stderr)
+
+    # Watch CI in the background and notify on completion
+    try:
+        commit_sha = run("git", ["rev-parse", "HEAD"])
+        spawn_ci_watcher(commit_sha, tag)
+        log("Watching CI in background (will notify when done)")
+    except Exception:
+        pass
+
     log(f"\nRelease {new_version} complete!")

package/rlsbl/config.py

@@ -0,0 +1,54 @@
+"""Config reading for the tag feature (ecosystem discoverability).
+
+Precedence (highest to lowest):
+  1. CLI flag (--no-tag)
+  2. Project-level: .rlsbl/config.json
+  3. User-level: ~/.rlsbl/config.json
+  4. Default: True (tagging enabled)
+"""
+
+import json
+import os
+
+
+PROJECT_CONFIG = os.path.join(".rlsbl", "config.json")
+USER_CONFIG = os.path.expanduser("~/.rlsbl/config.json")
+
+
+def read_json_config(path):
+    """Safely read a JSON file, returning {} on missing or malformed."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def should_tag(flags):
+    """Returns True if tagging is enabled, checking flag > project > user > default."""
+    # CLI flag takes highest precedence
+    if flags.get("no-tag"):
+        return False
+
+    # Project-level config
+    project = read_json_config(PROJECT_CONFIG)
+    if "tag" in project:
+        return bool(project["tag"])
+
+    # User-level config
+    user = read_json_config(USER_CONFIG)
+    if "tag" in user:
+        return bool(user["tag"])
+
+    # Default: tagging enabled
+    return True
+
+
+def write_project_config(key, value):
+    """Write or update a key in .rlsbl/config.json (creates dir if needed)."""
+    os.makedirs(os.path.dirname(PROJECT_CONFIG), exist_ok=True)
+    existing = read_json_config(PROJECT_CONFIG)
+    existing[key] = value
+    with open(PROJECT_CONFIG, "w", encoding="utf-8") as f:
+        json.dump(existing, f, indent=2)
+        f.write("\n")

package/rlsbl/registries/go.py

@@ -110,6 +110,7 @@ def get_shared_template_mappings():
         {"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"},
     ]
 

package/rlsbl/registries/npm.py

@@ -105,6 +105,7 @@ def get_shared_template_mappings():
         {"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": "claude-settings.json.tpl", "target": ".claude/settings.json"},
     ]

package/rlsbl/registries/pypi.py

@@ -157,6 +157,7 @@ def get_shared_template_mappings():
         {"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": "claude-settings.json.tpl", "target": ".claude/settings.json"},
     ]

package/rlsbl/tagging.py

@@ -0,0 +1,202 @@
+"""Tagging module: inject "rlsbl" keywords into manifests and GitHub topics."""
+
+import json
+import os
+import re
+import subprocess
+import tomllib
+import urllib.request
+import urllib.error
+
+from .utils import run
+
+
+def ensure_npm_keyword(dir_path=".", quiet=False):
+    """Add "rlsbl" to the keywords array in package.json if not already present."""
+    pkg_path = os.path.join(dir_path, "package.json")
+    with open(pkg_path, "r", encoding="utf-8") as f:
+        raw = f.read()
+
+    # Detect indent: look for the first indented line
+    indent_match = re.search(r'^( +|\t+)"', raw, re.MULTILINE)
+    indent = indent_match.group(1) if indent_match else "  "
+
+    pkg = json.loads(raw)
+    keywords = pkg.get("keywords", [])
+
+    if "rlsbl" in keywords:
+        return False
+
+    keywords.append("rlsbl")
+    pkg["keywords"] = keywords
+
+    # Preserve trailing newline if present
+    trailing_newline = "\n" if raw.endswith("\n") else ""
+    output = json.dumps(pkg, indent=indent) + trailing_newline
+
+    # Atomic write: write to temp file, then rename
+    tmp_path = pkg_path + ".tmp"
+    with open(tmp_path, "w", encoding="utf-8") as f:
+        f.write(output)
+    os.replace(tmp_path, pkg_path)
+
+    if not quiet:
+        print('Tagged package.json with "rlsbl" keyword')
+    return True
+
+
+def ensure_pypi_keyword(dir_path=".", quiet=False):
+    """Add "rlsbl" to the keywords array in pyproject.toml if not already present."""
+    toml_path = os.path.join(dir_path, "pyproject.toml")
+    with open(toml_path, "rb") as f:
+        data = tomllib.load(f)
+
+    # Check if already tagged
+    existing = data.get("project", {}).get("keywords", [])
+    if "rlsbl" in existing:
+        return False
+
+    # Read as text for regex-based editing
+    with open(toml_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Find [project] section boundaries
+    project_match = re.search(r"^\[project\]\s*$", content, re.MULTILINE)
+    if not project_match:
+        raise ValueError("No [project] section found in pyproject.toml")
+
+    section_start = project_match.end()
+    next_section = re.search(r"^\[", content[section_start:], re.MULTILINE)
+    section_end = section_start + next_section.start() if next_section else len(content)
+    section = content[section_start:section_end]
+
+    # Case 1: keywords field already exists -- add "rlsbl" to the array
+    # Use DOTALL to handle multi-line arrays (e.g. keywords = [\n  "foo",\n])
+    keywords_match = re.search(r'^(keywords\s*=\s*\[)(.*?)\]', section, re.MULTILINE | re.DOTALL)
+    if keywords_match:
+        prefix = keywords_match.group(1)
+        array_content = keywords_match.group(2)
+        # Detect if multi-line (contains newline between brackets)
+        if "\n" in array_content:
+            # Multi-line: insert before the closing bracket on its own line
+            # Find the indent used for existing items
+            item_indent_match = re.search(r'\n( +)"', array_content)
+            item_indent = item_indent_match.group(1) if item_indent_match else "    "
+            new_array_content = array_content.rstrip() + f',\n{item_indent}"rlsbl"\n'
+        else:
+            # Single-line
+            if array_content.strip():
+                new_array_content = array_content.rstrip() + ', "rlsbl"'
+            else:
+                new_array_content = '"rlsbl"'
+        new_field = prefix + new_array_content + "]"
+        updated_section = section[:keywords_match.start()] + new_field + section[keywords_match.end():]
+    else:
+        # Case 2: keywords field missing -- insert after the version line
+        version_match = re.search(r'^version\s*=\s*"[^"]*"\s*$', section, re.MULTILINE)
+        if version_match:
+            insert_pos = version_match.end()
+        else:
+            # Fallback: insert at the beginning of the section
+            insert_pos = 0
+        updated_section = (
+            section[:insert_pos] + '\nkeywords = ["rlsbl"]' + section[insert_pos:]
+        )
+
+    updated = content[:section_start] + updated_section + content[section_end:]
+
+    # Atomic write: write to temp file, then rename
+    tmp_path = toml_path + ".tmp"
+    with open(tmp_path, "w", encoding="utf-8") as f:
+        f.write(updated)
+    os.replace(tmp_path, toml_path)
+
+    if not quiet:
+        print('Tagged pyproject.toml with "rlsbl" keyword')
+    return True
+
+
+def ensure_github_topic(quiet=False):
+    """Add "rlsbl" topic to the GitHub repository if not already present."""
+    # Try to get a GitHub token (env var first, then gh CLI)
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        try:
+            token = run("gh", ["auth", "token"])
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    if not token:
+        if not quiet:
+            print("No GitHub token available. Run 'gh auth login' or set GITHUB_TOKEN.")
+        return False
+
+    # Detect repo name
+    repo_name = None
+    try:
+        repo_name = run("gh", ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"])
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    if not repo_name:
+        # Fallback: parse from git remote
+        try:
+            remote_url = run("git", ["remote", "get-url", "origin"])
+            match = re.search(r"github\.com[/:]([^/]+/[^/.]+)", remote_url)
+            if match:
+                repo_name = match.group(1).removesuffix(".git")
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            pass
+
+    if not repo_name:
+        if not quiet:
+            print("Warning: could not detect GitHub repository name.")
+        return False
+
+    owner, repo = repo_name.split("/", 1)
+    api_url = f"https://api.github.com/repos/{owner}/{repo}/topics"
+    headers = {
+        "Authorization": f"token {token}",
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "rlsbl-cli",
+    }
+
+    # GET existing topics
+    try:
+        req = urllib.request.Request(api_url, headers=headers)
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, OSError, json.JSONDecodeError) as e:
+        if not quiet:
+            print(f"Warning: failed to fetch GitHub topics: {e}")
+        return False
+
+    topics = data.get("names", [])
+    if "rlsbl" in topics:
+        return False
+
+    # PUT with merged topics list
+    topics.append("rlsbl")
+    payload = json.dumps({"names": topics}).encode("utf-8")
+    try:
+        req = urllib.request.Request(api_url, data=payload, headers=headers, method="PUT")
+        req.add_header("Content-Type", "application/json")
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            resp.read()  # consume response
+    except (urllib.error.URLError, OSError) as e:
+        if not quiet:
+            print(f"Warning: failed to set GitHub topics: {e}")
+        return False
+
+    if not quiet:
+        print('Added "rlsbl" topic to GitHub repository')
+    return True
+
+
+def ensure_tags(registries, dir_path=".", quiet=False):
+    """Tag manifests and GitHub repo based on detected registries."""
+    if "npm" in registries:
+        ensure_npm_keyword(dir_path, quiet=quiet)
+    if "pypi" in registries:
+        ensure_pypi_keyword(dir_path, quiet=quiet)
+    ensure_github_topic(quiet=quiet)

package/rlsbl/utils.py

@@ -7,10 +7,10 @@ import subprocess
 import sys
 
 
-def run(cmd, args=None, timeout=120):
+def run(cmd, args=None, timeout=120, env=None):
     """Run a command with args, return trimmed stdout. Raise on failure."""
     full_cmd = [cmd] + (args or [])
-    result = subprocess.run(full_cmd, capture_output=True, text=True, check=True, timeout=timeout)
+    result = subprocess.run(full_cmd, capture_output=True, text=True, check=True, timeout=timeout, env=env)
     return result.stdout.strip()
 
 
@@ -108,6 +108,112 @@ 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/gitignore.tpl

@@ -11,3 +11,4 @@ dist/
 .*-cache.json
 .env
 .env.local
+*.local-only

package/templates/shared/post-release.sh.tpl

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Post-release hook. Runs after a successful release (non-fatal).
+# Environment: RLSBL_VERSION is set to the released version.
+# Customize this for your project (e.g., local install, deploy, notify).
+
+set -euo pipefail
+
+echo "Post-release: v$RLSBL_VERSION"