rlsbl 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smm-h
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# rlsbl
+
+Release orchestration and project scaffolding CLI for npm and PyPI.
+
+## Install
+
+From npm:
+
+```
+npm i -g rlsbl
+```
+
+From PyPI (requires Node.js 18+):
+
+```
+uv tool install rlsbl
+```
+
+## Quick start
+
+```
+rlsbl scaffold
+rlsbl release minor
+```
+
+## Commands
+
+All commands work at the top level -- registries are auto-detected from project files (`package.json`, `pyproject.toml`). Use the registry-specific form (`rlsbl <registry> <command>`) only when you need to target a single registry.
+
+### scaffold [--force] [--update]
+
+Scaffolds CI/CD infrastructure and release tooling for all detected registries.
+
+```
+rlsbl scaffold
+rlsbl npm scaffold          # target npm only
+rlsbl pypi scaffold --force # overwrite existing files
+```
+
+Context-aware behavior when files already exist (without `--force`):
+
+| File | Behavior |
+|---|---|
+| `CLAUDE.md` | Appends rlsbl sections if the marker is not present |
+| `.gitignore` | Merges missing entries from the template |
+| `.github/workflows/ci.yml` | Preserves existing file, prints a note to review manually |
+| All others | Skipped |
+
+### release [patch|minor|major] [--dry-run] [--quiet]
+
+Bumps version, commits, pushes, and creates a GitHub Release. Defaults to `patch`.
+
+```
+rlsbl release minor
+rlsbl npm release major --dry-run
+```
+
+The version is synced across all detected project files (`package.json`, `pyproject.toml`) regardless of which registry is primary.
+
+If `scripts/pre-release.sh` exists, it runs before any changes are made. A non-zero exit aborts the release.
+
+### status
+
+Shows project status: package name, version (per registry), git branch, last tag, working tree state, changelog coverage, and CI workflow presence.
+
+```
+rlsbl status
+rlsbl pypi status
+```
+
+### check-name \<name\>
+
+Checks name availability on both npm and PyPI, and warns about confusingly similar names.
+
+```
+rlsbl check-name my-cool-lib
+rlsbl npm check-name my-cool-lib   # npm only
+```
+
+npm checks variant spellings (hyphens, underscores, dots, no separator). PyPI normalizes per PEP 503 and checks common alternatives.
+
+Global flags: `--help`, `--version`.
+
+## Release flow
+
+When you run `release`, the following happens in order:
+
+1. Verifies `gh` CLI is installed and authenticated
+2. Checks that the git working tree is clean
+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)
+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
+
+## What scaffold creates
+
+| File | Source | Purpose |
+|---|---|---|
+| `.github/workflows/ci.yml` | Registry-specific | CI workflow (lint, test) |
+| `.github/workflows/publish.yml` | Registry-specific | Publish on GitHub Release (OIDC) |
+| `CHANGELOG.md` | Shared | Version changelog |
+| `LICENSE` | Shared | MIT license (author and year filled in) |
+| `.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/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.
+
+## 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.
+
+How it works:
+
+1. Detects project type (`package.json` or `pyproject.toml`)
+2. Extracts the current version
+3. Checks that `CHANGELOG.md` contains a heading `## <version>`
+4. Blocks the push with an error if the entry is missing
+
+To reinstall manually:
+
+```
+cp scripts/pre-push-hook.sh .git/hooks/pre-push && chmod +x .git/hooks/pre-push
+```
+
+## First publish
+
+The first version must be published manually before CI can take over:
+
+| Registry | Manual first publish | Then configure |
+|---|---|---|
+| npm | Add an `NPM_TOKEN` secret to your GitHub repo (Settings > Secrets > Actions), then push a release | CI handles subsequent publishes |
+| PyPI | Run `uv publish` | Set up [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) on pypi.org |
+
+After configuration, all subsequent releases are handled by CI when `rlsbl release` creates a GitHub Release.
+
+## Requirements
+
+- Node 18+
+- [GitHub CLI](https://cli.github.com) (`gh`), installed and authenticated
+- git
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync, spawnSync } = require("child_process");
+
+try {
+  execFileSync("python3", ["--version"], { stdio: "pipe" });
+} catch {
+  console.error("rlsbl requires Python 3.11+. Install from https://python.org/");
+  process.exit(1);
+}
+
+const result = spawnSync("python3", ["-m", "rlsbl", ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/package.json

@@ -1,11 +1,30 @@
 {
   "name": "rlsbl",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Release orchestration and project scaffolding for npm and PyPI",
   "license": "MIT",
-  "author": "smm-h",
+  "bin": {
+    "rlsbl": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "rlsbl/",
+    "templates/"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/smm-h/rlsbl.git"
-  }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "release",
+    "npm",
+    "pypi",
+    "publish",
+    "cli",
+    "scaffold"
+  ],
+  "author": "smm-h"
 }

package/rlsbl/__init__.py

@@ -1 +1,174 @@
-"""rlsbl: releasable."""
+"""rlsbl: Release orchestration and project scaffolding for npm and PyPI."""
+
+import os
+import sys
+
+try:
+    from importlib.metadata import version as _get_version
+    __version__ = _get_version("rlsbl")
+except Exception:
+    __version__ = "unknown"
+
+REGISTRIES = ("npm", "pypi")
+COMMANDS = ("release", "status", "scaffold", "check-name")
+COMMAND_ALIASES = {"init": "scaffold"}
+
+HELP = f"""\
+rlsbl v{__version__} -- Release orchestration and project scaffolding for npm and PyPI
+
+Usage:
+  rlsbl release [patch|minor|major] [--dry-run] [--quiet]  Orchestrate a release
+  rlsbl status                                             Show project status
+  rlsbl scaffold [--force] [--update]                       Scaffold release infrastructure
+  rlsbl check-name <name>                                  Check name availability
+
+  Registry-specific (when you need to target one):
+  rlsbl <registry> <command> [args...]
+
+Registries: {', '.join(REGISTRIES)}"""
+
+
+def detect_registries():
+    """Detect all registries that have a project file in the current directory.
+
+    Returns a list, e.g. ["npm"], ["pypi"], or ["npm", "pypi"].
+    """
+    found = []
+    if os.path.exists("package.json"):
+        found.append("npm")
+    if os.path.exists("pyproject.toml"):
+        found.append("pypi")
+    return found
+
+
+def parse_args(argv):
+    """Parse sys.argv into positional args and flags."""
+    raw = argv[1:]
+    positional = []
+    flags = {}
+
+    for arg in raw:
+        if arg.startswith("--"):
+            flags[arg[2:]] = True
+        elif arg.startswith("-") and len(arg) == 2:
+            flags[arg[1:]] = True
+        else:
+            positional.append(arg)
+
+    return positional, flags
+
+
+def _get_command_module(command):
+    """Import and return the command module for the given command name."""
+    # Map CLI command names to Python module names
+    module_map = {
+        "release": "release",
+        "status": "status",
+        "scaffold": "init_cmd",
+        "check-name": "check_name",
+    }
+    module_name = module_map.get(command)
+    if not module_name:
+        return None
+
+    # Import the command module
+    from importlib import import_module
+    return import_module(f".commands.{module_name}", package="rlsbl")
+
+
+def main():
+    positional, flags = parse_args(sys.argv)
+
+    # Top-level flags
+    if flags.get("help") or flags.get("h"):
+        print(HELP)
+        sys.exit(0)
+
+    if flags.get("version") or flags.get("v"):
+        print(__version__)
+        sys.exit(0)
+
+    first = positional[0] if positional else None
+
+    # Resolve command aliases (e.g. "init" -> "scaffold")
+    if first in COMMAND_ALIASES:
+        first = COMMAND_ALIASES[first]
+
+    if not first:
+        print("Error: missing command.\n", file=sys.stderr)
+        print(HELP, file=sys.stderr)
+        sys.exit(1)
+
+    registry = None
+    command = None
+    args = []
+
+    if first in COMMANDS:
+        # Top-level: rlsbl <command> ... -- auto-detect registry
+        command = first
+        args = positional[1:]
+    elif first in REGISTRIES:
+        # Registry-prefixed: rlsbl <registry> <command> ...
+        registry = first
+        command = positional[1] if len(positional) > 1 else None
+        if command and command in COMMAND_ALIASES:
+            command = COMMAND_ALIASES[command]
+
+        if not command:
+            print(f'Error: missing command for registry "{registry}".\n', file=sys.stderr)
+            print(HELP, file=sys.stderr)
+            sys.exit(1)
+
+        if command not in COMMANDS:
+            print(
+                f'Error: unknown command "{command}". Valid commands: {", ".join(COMMANDS)}\n',
+                file=sys.stderr,
+            )
+            print(HELP, file=sys.stderr)
+            sys.exit(1)
+
+        args = positional[2:]
+    else:
+        print(f'Error: unknown command or registry "{first}".\n', file=sys.stderr)
+        print(HELP, file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        handler = _get_command_module(command)
+        if handler is None:
+            print(f'Error: command "{command}" is not yet implemented.', file=sys.stderr)
+            sys.exit(1)
+
+        if registry:
+            # Explicit registry -- single invocation
+            handler.run_cmd(registry, args, flags)
+        elif command == "check-name":
+            # Top-level check-name: check ALL registries
+            regs = ["npm", "pypi"]
+            for i, r in enumerate(regs):
+                handler.run_cmd(r, args, flags)
+                if i < len(regs) - 1:
+                    print("")
+        elif command == "scaffold":
+            # Top-level scaffold: scaffold for each detected registry
+            regs = detect_registries()
+            if not regs:
+                print("Error: no package.json or pyproject.toml found.", file=sys.stderr)
+                sys.exit(1)
+            if len(regs) > 1:
+                # Multi-registry: only scaffold for the primary registry
+                # (CI/publish workflows conflict when both registries target the same paths)
+                print(f"Multiple registries detected: {', '.join(regs)}")
+                print(f"Scaffolding for primary registry: {regs[0]}")
+                print("For dual-registry projects, manually configure workflows with both jobs.")
+            handler.run_cmd(regs[0], args, flags)
+        else:
+            # Top-level release/status: use primary detected registry
+            regs = detect_registries()
+            if not regs:
+                print("Error: no package.json or pyproject.toml found.", file=sys.stderr)
+                sys.exit(1)
+            handler.run_cmd(regs[0], args, flags)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)

package/rlsbl/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as python -m rlsbl."""
+from . import main
+
+main()

package/rlsbl/commands/check_name.py

@@ -0,0 +1,184 @@
+"""Check-name command: check package name availability on npm or PyPI."""
+
+import re
+import subprocess
+import sys
+import urllib.request
+import urllib.error
+
+
+def normalize_npm(name):
+    """Normalize an npm package name for similarity comparison.
+
+    Strips hyphens, underscores, dots, and lowercases.
+    """
+    return re.sub(r"[-_.]", "", name.lower())
+
+
+def normalize_pypi(name):
+    """Normalize a PyPI package name per PEP 503.
+
+    Lowercases and replaces runs of [-_.] with a single hyphen.
+    """
+    return re.sub(r"[-_.]+", "-", name.lower())
+
+
+def check_npm_availability(name):
+    """Check if an npm package name is available.
+
+    Returns {"status": "available"|"taken"|"error", "message"?: str}.
+    Distinguishes 404 (truly available) from network/other errors.
+    """
+    try:
+        subprocess.run(
+            ["npm", "view", name, "name"],
+            capture_output=True, text=True, check=True,
+        )
+        return {"status": "taken"}
+    except subprocess.CalledProcessError as e:
+        stderr = e.stderr or ""
+        if "E404" in stderr or "404" in stderr:
+            return {"status": "available"}
+        return {"status": "error", "message": stderr.strip() or "Unknown error checking npm"}
+    except FileNotFoundError:
+        return {"status": "error", "message": "npm CLI not found"}
+
+
+def get_npm_variants(name):
+    """Generate common npm name variants for similarity checking."""
+    variants = set()
+    lower = name.lower()
+    variants.add(lower)
+    variants.add(lower.replace("_", "-"))
+    variants.add(lower.replace("-", "_"))
+    variants.add(re.sub(r"[-_]", "", lower))
+    variants.add(re.sub(r"[-_]", ".", lower))
+
+    # Remove the original name itself from the set
+    variants.discard(name)
+
+    return list(variants)
+
+
+def check_pypi_availability(name):
+    """Check if a PyPI package name is available.
+
+    Returns {"status": "available"|"taken"|"error", "message"?: str}.
+    Distinguishes 404 (truly available) from network/other errors.
+    """
+    url = f"https://pypi.org/pypi/{name}/json"
+    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": "error", "message": f"Unexpected status {resp.status}"}
+    except urllib.error.HTTPError as e:
+        if e.code == 404:
+            return {"status": "available"}
+        return {"status": "error", "message": f"Unexpected status {e.code}"}
+    except Exception as e:
+        return {"status": "error", "message": str(e) or "Network error"}
+
+
+def get_pypi_variants(name):
+    """Generate common PyPI name variants for similarity checking."""
+    normalized = normalize_pypi(name)
+    lower = name.lower()
+    variants = set()
+    variants.add(normalized)
+    variants.add(re.sub(r"[-_.]+", "_", lower))
+    variants.add(re.sub(r"[-_.]+", "-", lower))
+    variants.add(re.sub(r"[-_.]+", "", lower))
+
+    # Remove the original name itself
+    variants.discard(name)
+
+    return list(variants)
+
+
+def _check_name_npm(name):
+    """Check npm availability and report similar names."""
+    print(f'Checking npm for "{name}"...')
+
+    result = check_npm_availability(name)
+    if result["status"] == "error":
+        print(f"Error checking npm: {result['message']}", file=sys.stderr)
+        sys.exit(1)
+    available = result["status"] == "available"
+    if available:
+        print(f'"{name}" is available on npm.')
+    else:
+        print(f'"{name}" is taken on npm.')
+
+    # Check variants for similarity; skip variants that error
+    variants = get_npm_variants(name)
+    similar = []
+    for variant in variants:
+        var_result = check_npm_availability(variant)
+        if var_result["status"] == "taken":
+            similar.append(variant)
+
+    if similar:
+        print("\nSimilar names already taken:")
+        for s in similar:
+            print(f"  {s}")
+        if available:
+            print(
+                "\nYour name is available but has similar existing packages. "
+                "Consider if this could cause confusion."
+            )
+
+
+def _check_name_pypi(name):
+    """Check PyPI availability and report similar names."""
+    print(f'Checking PyPI for "{name}"...')
+
+    result = check_pypi_availability(name)
+    if result["status"] == "error":
+        print(f"Error checking PyPI: {result['message']}", file=sys.stderr)
+        sys.exit(1)
+    available = result["status"] == "available"
+    if available:
+        print(f'"{name}" is available on PyPI.')
+    else:
+        print(f'"{name}" is taken on PyPI.')
+
+    # Check variants for similarity (PEP 503 normalization); skip variants that error
+    variants = get_pypi_variants(name)
+    similar = []
+    for variant in variants:
+        if variant == name:
+            continue
+        var_result = check_pypi_availability(variant)
+        if var_result["status"] == "taken":
+            similar.append(variant)
+
+    if similar:
+        print("\nSimilar names already taken:")
+        for s in similar:
+            print(f"  {s}")
+        if available:
+            print(
+                "\nYour name is available but has similar existing packages. "
+                "Consider if this could cause confusion."
+            )
+
+
+def run_cmd(registry, args, flags):
+    """Check-name command handler.
+
+    Checks package name availability on npm or PyPI, and warns about similar names.
+    """
+    name = args[0] if args else None
+    if not name:
+        print(
+            "Error: missing package name. Usage: rlsbl check-name <name>",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if registry == "npm":
+        _check_name_npm(name)
+    else:
+        _check_name_pypi(name)