rlsbl 0.38.2 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +106 -51
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,10 +1,12 @@
1
+ <!-- Auto-generated by selfdoc from docs/_README.md — do not edit -->
2
+
1
3
  <p align="center">
2
4
  <img src="logo.svg" alt="rlsbl" width="336" height="105">
3
5
  </p>
4
6
 
5
7
  # rlsbl
6
8
 
7
- Release orchestration and project scaffolding CLI for npm, PyPI, and Go. Pure Python, one dependency (tomlkit).
9
+ Release orchestration and project scaffolding for npm, PyPI, and Go
8
10
 
9
11
  ## Install
10
12
 
@@ -25,7 +27,9 @@ npm i -g rlsbl
25
27
  ```
26
28
  rlsbl scaffold # set up CI/CD, hooks, changelog
27
29
  # ... develop, commit ...
28
- rlsbl release minor # bump, tag, push, create GitHub Release
30
+ rlsbl release-init # scaffold .rlsbl/releases/unreleased.toml
31
+ # ... edit bump type, targets ...
32
+ rlsbl release # bump, tag, push, create GitHub Release
29
33
  rlsbl watch <sha> # monitor CI for that release
30
34
  ```
31
35
 
@@ -34,51 +38,72 @@ rlsbl watch <sha> # monitor CI for that release
34
38
  All commands auto-detect registries from project files (`package.json`, `pyproject.toml`, `go.mod`). Use `--target <npm|pypi|go>` to target a specific one.
35
39
 
36
40
  | Command | Description |
37
- |---------|-------------|
38
- | `release [patch\|minor\|major]` | Bump version, commit, tag, push, create GitHub Release |
39
- | `scaffold [--force] [--update]` | Scaffold CI/CD, hooks, and release infrastructure |
40
- | `status` | Show version, branch, last tag, changelog coverage, CI presence |
41
- | `check <name>` | Check name availability on npm/PyPI/GitHub (parallel variant queries) |
42
- | `config [show\|init\|migrate\|status]` | Manage project configuration and schema migrations |
43
- | `undo [--yes]` | Revert the last release (tag, commit, GitHub Release) |
44
- | `discover [--mine]` | List rlsbl ecosystem projects via GitHub topic search |
45
- | `watch [<sha>]` | Monitor CI runs for a commit (parallel polling), print workflow audit summary, notify on completion |
46
- | `unreleased [--json]` | List commits since last tag, report changelog coverage |
47
- | `prs` | List open pull requests for the current repo |
48
- | `targets` | List available release targets with detection status |
49
- | `record-gif` | Record a demo GIF with vhs |
50
- | `pre-push-check` | Verify CHANGELOG entry exists for the current version |
51
-
52
- Global flags: `--help`, `--version`, `--target <npm|pypi|go>`, `--no-tag`.
41
+ | --- | --- |
42
+ | `release` | Bump the project version, validate the changelog, commit, tag, push, and create a GitHub Release. Supports patch, minor, and major bumps with dry-run preview and non-interactive mode for CI. |
43
+ | `status` | Display the current project version, branch, last release tag, unreleased commit count, and changelog coverage. Outputs plain text by default or structured JSON with the --json flag. |
44
+ | `scaffold` | Generate or update CI/CD workflows, git hooks, changelog, and license files for the detected release target. Use --update for three-way merge preserving customizations, or --force to overwrite all files. |
45
+ | `check` | Query npm, PyPI, or other registries to check whether one or more package names are available. Accepts multiple names as positional arguments and respects a configurable delay between checks. |
46
+ | `edit-release` | Sync the GitHub Release notes for a given version with the corresponding CHANGELOG.md entry. Defaults to the current version if none is specified. Use --dry-run to preview changes without updating GitHub. |
47
+ | `undo` | Revert the most recent release by deleting the GitHub Release, removing the git tag from local and remote, and reverting the version bump commit. Requires a manual git push afterward to finalize. |
48
+ | `yank` | Mark a past release as deprecated (soft yank) or delete it (hard yank). Soft yank marks the GitHub Release as pre-release and prepends a deprecation notice. Hard yank deletes the release entirely while preserving the git tag. |
49
+ | `discover` | Search GitHub for repositories tagged with the rlsbl topic and list them. Use --mine to filter results to only your own repositories. Requires the gh CLI to be authenticated. |
50
+ | `watch` | Poll GitHub Actions CI workflow runs for a specific commit SHA and report pass or fail status. Defaults to HEAD if no SHA is provided. Useful after rlsbl release to monitor the publish pipeline. |
51
+ | `pre-push-check` | Verify that CHANGELOG.md contains an entry matching the current project version. Designed to run as a git pre-push hook to prevent pushing releases without documented changes. |
52
+ | `prs` | List all open pull requests for the current repository using the GitHub CLI. Shows PR number, title, author, and branch for a quick overview of pending work. |
53
+ | `unreleased` | List commits between the latest release tag and HEAD, and check whether each has a corresponding changelog entry. Outputs a coverage report in plain text or JSON to help prepare the next release. |
54
+ | `targets` | List all release targets detected in the current project directory, showing which ecosystems (npm, PyPI, Go, Cargo, etc.) are active based on manifest files found. |
55
+ | `record-gif` | Record an animated GIF demo of rlsbl commands using the vhs terminal recorder. Configurable width, height, font size, and duration for consistent, reproducible demo recordings. |
56
+ | `migrate` | Run pending configuration migrations to update .rlsbl config files to the latest schema. Use --dry-run to preview changes without applying, or --status to see which migrations are pending. |
57
+ | `doctor` | Run diagnostic checks on the project release state, including version consistency, tag alignment, changelog coverage, and config validity. Use --fix to auto-repair issues where possible. |
58
+ | `deploy` | Run the configured deployment pipeline for the project. Supports named deploy targets, dry-run preview of what would be deployed, and a --force flag to override branch restrictions. |
59
+ | `commit` | Commit one or more files with an Autogenerated trailer, marking the commit as machine-generated so it is automatically exempted from changelog coverage checks. |
60
+ | **changelog** | Structured changelog management using JSONL entries. Add, validate, and generate CHANGELOG.md from per-commit changelog entries stored in unreleased.jsonl for precise, auditable release notes. |
61
+ | `changelog add` | Append a structured changelog entry to the project's unreleased.jsonl file. Each entry includes a human-readable description, an entry type (feature, fix, or breaking), and optional commit hashes linking it to specific changes. The file is auto-committed unless --no-commit is passed. Use --no-user-facing to mark internal changes that should not appear in the published changelog. |
62
+ | `changelog validate` | Parse and validate all entries in the project's unreleased.jsonl file. Checks each entry for schema conformance, verifies that required fields like description and type are present and well-formed, ensures entry types are one of the allowed values (feature, fix, breaking), and validates referential integrity of any attached commit hashes against the git history. |
63
+ | `changelog generate` | Compile all validated JSONL changelog entries into a formatted CHANGELOG.md file. Groups entries by type (features, fixes, breaking changes) under the appropriate version heading, preserving existing changelog content for previous releases. Use --dry-run to preview the generated Markdown output without writing to disk, which is useful for reviewing before committing. |
64
+ | **monorepo** | Manage monorepo workspaces with multiple independently-versioned projects. Initialize workspaces, add or remove projects, sync CI workflows, check name availability, and analyze dependency graphs. Provides 10 monorepo subcommands and supports all 14 release targets in a single workspace.toml. |
65
+ | `monorepo init` | Create a new monorepo workspace by generating the .rlsbl-monorepo directory and an empty workspace.toml configuration file at the current directory. This must be run at the repository root before adding individual projects with the add subcommand. Each workspace tracks multiple independently-versioned projects that share a single git repository. |
66
+ | `monorepo add` | Register a project directory in the monorepo workspace.toml configuration. The path argument specifies the project's location relative to the repo root. Optionally set a display name, target registry for publishing, glob patterns for change detection, a subtree remote URL for split publishing, inter-project dependencies, and a library flag to mark shared code packages. |
67
+ | `monorepo remove` | Unregister a project from the monorepo workspace.toml by its path. This removes the project entry from the workspace configuration file but does not delete any files, directories, or git history on disk. The project's code remains intact and can be re-added later with the add subcommand if needed. |
68
+ | `monorepo list` | Display all projects registered in the monorepo workspace.toml file. For each project, shows the project name, relative path from the repo root, target registry for publishing, and any configured options such as watch patterns, subtree remotes, inter-project dependencies, and whether the project is marked as a library. |
69
+ | `monorepo sync` | Copy and merge CI workflow files from each project's individual scaffold into the shared .github/workflows directory at the repository root. This ensures that every project in the workspace has its publish and test pipelines properly configured as GitHub Actions workflows, even when projects use different target registries or have custom workflow steps. |
70
+ | `monorepo status` | Show the current version, last release tag, and number of unreleased commits for every project in the monorepo workspace. Provides a quick overview of which projects have pending changes and are ready for their next release. Projects with zero unreleased commits are shown as up-to-date. |
71
+ | `monorepo check-names` | Check package name availability on a target registry for all projects in the monorepo workspace. Queries the registry API for each project name and reports whether it is available or already taken. Supports optional prefix and suffix arguments to test naming conventions like scoped packages, with a configurable delay between registry queries to avoid rate limiting. |
72
+ | `monorepo release-order` | Compute and display the topological release order for all projects in the monorepo workspace based on their declared depends-on relationships. Projects with no dependencies are listed first, followed by projects that depend on them, ensuring each project is released only after its dependencies. Detects and reports circular dependency errors. |
73
+ | `monorepo outdated` | Scan all projects in the monorepo workspace for intra-workspace dependencies that reference older versions than what is currently available in the workspace. Lists each outdated dependency with the referenced version and the latest available version, helping identify which downstream projects need a version bump after upstream releases. |
74
+ | `monorepo lint` | Detect unregistered projects and stale workspace entries in your monorepo. Scans first-level directories for recognized project manifests across all 14 supported targets (npm, PyPI, Go, Cargo, etc.) and compares against workspace.toml. Reports unregistered projects on disk and registered entries pointing to missing directories. Exits non-zero if issues are found, suitable for CI gating. |
75
+ | **dev** | Developer utilities for locally working with rlsbl projects, including editable installs that mirror the project's release target (pypi -> uv tool install -e, npm -> npm link, go -> go install). |
76
+ | `dev install` | Install the project locally for development using the detected target's editable install command. --global (default) installs system-wide across 8 supported targets (pypi, npm, go, cargo, zig, swift, deno, hex), while --venv installs into the project's local environment instead. In monorepo mode, pair with --all, --include, or --exclude. Use --uninstall to reverse a previous install. |
77
+
78
+ Global flags: `--help`, `--version`, `--dry-run`, `--yes`, `--quiet`.
53
79
 
54
80
  ## Release flow
55
81
 
56
- When you run `rlsbl release [patch|minor|major]`:
57
-
58
- 1. Verifies `gh` CLI is installed and authenticated
59
- 2. Checks working tree is clean
60
- 3. Fetches origin and verifies local branch is not behind remote (use `--skip-remote-check` for offline releases)
61
- 4. Reads the current version from the primary project file
62
- 5. Computes the new version; confirms the tag does not already exist
63
- 6. Validates `CHANGELOG.md` contains a `## <new-version>` section
64
- 7. Runs `.rlsbl/hooks/pre-release.sh` if present (non-zero exit aborts; receives `RLSBL_VERSION`)
65
- 8. Acquires advisory lockfile (`.rlsbl/lock`) to prevent concurrent operations
66
- 9. Writes the new version to all detected project files and `.rlsbl/version`
67
- 10. Adds `rlsbl` keyword to manifests if ecosystem tagging is enabled
68
- 11. Verifies no unexpected files were modified (race condition guard)
69
- 12. Commits the version bump (uses `safegit` if available)
70
- 13. Tags and pushes to `origin`
71
- 14. Creates a GitHub Release with the changelog entry as notes
72
- 15. Adds `rlsbl` topic to the GitHub repo (if tagging enabled)
73
- 16. Runs secondary release targets (e.g., docs via selfdoc); use `--include`/`--exclude` to control
74
- 17. Runs `.rlsbl/hooks/post-release.sh` if present (non-fatal; receives `RLSBL_VERSION`)
75
- 18. Prints `Watch CI: rlsbl watch <sha>`
76
-
77
- Use `--dry-run` to preview without changes. Use `--yes` for non-interactive mode (CI, AI agents). Use `--skip-remote-check` for offline releases.
78
-
79
- **Multi-target releases:** Secondary targets (e.g., docs) run automatically during release. Control which targets run with `--include <target>` and `--exclude <target>` (comma-separated). Configure defaults in `.rlsbl/config.json` via the `release_targets` list. Use `rlsbl targets` to see all available targets.
80
-
81
- **Documentation:** Use [selfdoc](https://github.com/smm-h/selfdoc) for documentation generation. rlsbl auto-triggers selfdoc during releases when `selfdoc.json` is detected.
82
+ When you run `rlsbl release`:
83
+
84
+ 1. Reads `.rlsbl/releases/unreleased.toml` for bump type (patch/minor/major) and target selection
85
+ 2. Verifies `gh` CLI is installed and authenticated
86
+ 3. Checks working tree is clean (use `--allow-dirty` to override)
87
+ 4. Fetches origin and verifies local branch is not behind remote
88
+ 5. Reads the current version from the primary project file
89
+ 6. Computes the new version; confirms the tag does not already exist
90
+ 7. Validates JSONL changelog via the check system
91
+ 8. Runs `.rlsbl/hooks/pre-checks.sh` if present (user-owned, non-zero aborts)
92
+ 9. Runs built-in tests and lint
93
+ 10. Runs `.rlsbl/hooks/pre-release.sh` if present (scaffold-managed, non-zero aborts)
94
+ 11. Acquires advisory lockfile (`.rlsbl/lock`) to prevent concurrent operations
95
+ 12. Writes the new version to all detected project files and `.rlsbl/version`
96
+ 13. Commits the version bump (uses `safegit` if available)
97
+ 14. Tags and pushes to `origin`
98
+ 15. Finalizes JSONL changelog (renames `unreleased.jsonl`, generates CHANGELOG.md)
99
+ 16. Creates a GitHub Release with the changelog entry as notes
100
+ 17. Runs secondary release targets (e.g., docs via selfdoc)
101
+ 18. Runs `.rlsbl/hooks/post-release.sh` if present (non-fatal)
102
+ 19. Prints `Watch CI: rlsbl watch <sha>`
103
+
104
+ Use `--dry-run` to preview without changes. Use `--yes` for non-interactive mode (CI, AI agents).
105
+
106
+ Create the release file with `rlsbl release-init`, which auto-detects project targets and scaffolds the TOML file.
82
107
 
83
108
  First release: if the current version has never been tagged, `release` publishes it as-is (bump type is ignored).
84
109
 
@@ -104,6 +129,7 @@ Created files are committed automatically by default.
104
129
  | `.gitignore` | Standard ignores for the ecosystem |
105
130
  | `CLAUDE.md` | AI assistant instructions |
106
131
  | `.claude/settings.json` | Claude Code settings |
132
+ | `.rlsbl/hooks/pre-checks.sh` | User-customizable pre-checks validation |
107
133
  | `.rlsbl/hooks/pre-release.sh` | User-customizable pre-release validation |
108
134
  | `.rlsbl/hooks/post-release.sh` | User-customizable post-release actions |
109
135
  | `.git/hooks/pre-push` | One-liner: `exec rlsbl pre-push-check "$@"` |
@@ -122,19 +148,35 @@ See [docs/ci-customization.md](docs/ci-customization.md) for an example.
122
148
 
123
149
  **Runs config migrations** when `.rlsbl/config-schema.json` exists.
124
150
 
151
+ ## Check system
152
+
153
+ 28 project checks organized by tag:
154
+
155
+ | Tag | Checks | Description |
156
+ |-----|--------|-------------|
157
+ | `project` | 5 | Version, name, license, description consistency; lockfile presence |
158
+ | `release` | 4 | Local/remote tag, GitHub Release, branch sync |
159
+ | `changelog` | 8 | Hash resolution, range, coverage, orphans, schema, batch limits, entry |
160
+ | `workspace` | 5 | CI router, CI sync, targets, unregistered, stale entries |
161
+ | `quality` | 1 | Library lint |
162
+ | (untagged) | 5 | Layer violations, dependency validation (unused/undeclared/stale) |
163
+
164
+ ```
165
+ rlsbl check --all # run all 28 checks
166
+ rlsbl check --tag changelog # run checks by tag
167
+ rlsbl check --name lock # run a single check
168
+ ```
169
+
125
170
  ## Config management
126
171
 
127
172
  Schema-driven configuration migration system for projects that ship user-facing config files.
128
173
 
129
174
  ```
130
- rlsbl config init # scaffold config migration infrastructure
131
- rlsbl config migrate # run pending migrations
132
- rlsbl config status # show migration status
133
- rlsbl config show # show resolved project configuration
175
+ rlsbl migrate # run pending migrations
176
+ rlsbl migrate --status # show migration status
177
+ rlsbl migrate --dry-run # preview changes
134
178
  ```
135
179
 
136
- `config init` creates `.rlsbl/config-schema.json` and a `defaults/` directory. Migrations support deep merge, flat merge, and list-by-key merge strategies with versioned schema tracking and atomic writes.
137
-
138
180
  ### Library API
139
181
 
140
182
  ```python
@@ -187,6 +229,19 @@ To disable:
187
229
  | `{"tag": false}` in `.rlsbl/config.json` | This project |
188
230
  | `{"tag": false}` in `~/.rlsbl/config.json` | All projects |
189
231
 
232
+ ## Monorepo
233
+
234
+ Manage multi-package workspaces with `rlsbl monorepo`:
235
+
236
+ - `monorepo init` / `monorepo add` / `monorepo remove` -- workspace management
237
+ - `monorepo sync` -- synchronize CI workflows
238
+ - `monorepo graph` -- export dependency graph (JSON, DOT, text)
239
+ - `monorepo snapshot` -- committed JSON artifact of workspace state
240
+ - `monorepo impact` -- change analysis across the dependency graph
241
+ - `monorepo release` -- batch release in topological order
242
+
243
+ Supports architectural layer rules via `[layers]` in `workspace.toml` for enforcing dependency direction.
244
+
190
245
  ## Environment variables
191
246
 
192
247
  | Variable | Default | Description |
@@ -200,7 +255,7 @@ To disable:
200
255
  | Registry | Setup | Then |
201
256
  |----------|-------|------|
202
257
  | npm | Add `NPM_TOKEN` secret to GitHub repo (Settings > Secrets > Actions) | CI publishes on GitHub Release |
203
- | PyPI | Run `uv publish` once, then set up [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) | CI publishes via OIDC |
258
+ | PyPI | Set up [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no tokens needed) | CI publishes via OIDC |
204
259
  | Go | Push tag -- Go modules are published by the tag itself | `pkg.go.dev` indexes automatically |
205
260
 
206
261
  ## Requirements
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rlsbl",
3
- "version": "0.38.2",
3
+ "version": "0.40.0",
4
4
  "description": "Release orchestration and project scaffolding for npm, PyPI, and Go",
5
5
  "license": "MIT",
6
6
  "bin": {