@releasekit/release 0.3.0-next.4 → 0.3.1

package/README.md

@@ -20,6 +20,8 @@ npm install -g @releasekit/release
 pnpm add -g @releasekit/release
 ```
 
+> **Note:** This package is ESM only and requires Node.js 20+.
+
 ## Quick Start
 
 ```bash
@@ -48,6 +50,8 @@ If no releasable changes are found after step 1, the command exits with code 0 a
 
 ## CLI Reference
 
+### `releasekit release`
+
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-c, --config <path>` | Path to config file | `releasekit.config.json` |
@@ -56,6 +60,7 @@ If no releasable changes are found after step 1, the command exits with code 0 a
 | `-p, --prerelease [id]` | Create prerelease version | — |
 | `-s, --sync` | Synchronized versioning across all packages | `false` |
 | `-t, --target <packages>` | Target specific packages (comma-separated) | all |
+| `--branch <name>` | Git branch to push to | current branch |
 | `--skip-notes` | Skip changelog generation | `false` |
 | `--skip-publish` | Skip registry publishing and git operations | `false` |
 | `--skip-git` | Skip git commit/tag/push | `false` |
@@ -66,6 +71,22 @@ If no releasable changes are found after step 1, the command exits with code 0 a
 | `-q, --quiet` | Suppress non-error output | `false` |
 | `--project-dir <path>` | Project directory | cwd |
 
+### `releasekit preview`
+
+Posts a release preview comment on a pull request showing what would be released if merged.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-c, --config <path>` | Path to config file | `releasekit.config.json` |
+| `-d, --dry-run` | Print comment markdown to stdout instead of posting | `false` |
+| `-p, --prerelease [id]` | Force prerelease preview (auto-detected by default) | — |
+| `--stable` | Force stable release preview (graduation from prerelease) | `false` |
+| `--pr <number>` | PR number (auto-detected from GitHub Actions) | — |
+| `--repo <owner/repo>` | Repository (auto-detected from `GITHUB_REPOSITORY`) | — |
+| `--project-dir <path>` | Project directory | cwd |
+
+The preview command reads PR labels to determine release behavior. See [CI Configuration](#ci-configuration) for label configuration.
+
 ## Usage Examples
 
 ### In CI (GitHub Actions)
@@ -91,10 +112,10 @@ jobs:
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
       - run: npm install -g @releasekit/release
       - run: releasekit release
 ```
@@ -144,14 +165,116 @@ if (result) {
 
 ## Configuration
 
-All configuration is shared via `releasekit.config.json`. The release command reads the `version`, `notes`, and `publish` sections as needed.
+Create a `releasekit.config.json` in your project root. Add `$schema` for editor autocompletion and validation:
+
+```json
+{
+  "$schema": "https://goosewobbler.github.io/releasekit/schema.json",
+  "version": {
+    "preset": "angular",
+    "packages": ["./"]
+  }
+}
+```
 
-See the individual package READMEs for configuration details:
+The release command reads the `version`, `notes`, and `publish` sections. See the individual package READMEs for all available options:
 
 - [@releasekit/version](../version/README.md) — versioning options
 - [@releasekit/notes](../notes/README.md) — changelog options
 - [@releasekit/publish](../publish/README.md) — publishing options
 
+### CI Configuration
+
+The `ci` section controls automation behavior:
+
+```jsonc
+{
+  "ci": {
+    // How releases are delivered
+    "releaseStrategy": "direct",       // "manual" | "direct" | "standing-pr" | "scheduled"
+
+    // What triggers a release
+    "releaseTrigger": "label",         // "commit" | "label"
+
+    // Enable/disable PR preview comments
+    "prPreview": true,
+
+    // Customise PR label names
+    "labels": {
+      "stable": "release:stable",
+      "prerelease": "release:prerelease",
+      "skip": "release:skip",
+      "major": "release:major",
+      "minor": "release:minor",
+      "patch": "release:patch"
+    }
+  }
+}
+```
+
+#### Release Trigger
+
+**`label`** (default) — A PR label (`release:patch`, `release:minor`, or `release:major`) is required to trigger a release. The label determines the bump type. PRs without a release label will not trigger a release when merged.
+
+**`commit`** — Conventional commits drive the bump type automatically. Every merge can trigger a release. Use the `release:skip` label to prevent a release, or `release:major` to override the commit-derived bump to major.
+
+Both modes support `release:stable` and `release:prerelease` as modifiers.
+
+#### Release Strategy
+
+| Strategy | Description |
+|----------|-------------|
+| `direct` | Release is triggered when a PR is merged to the main branch |
+| `manual` | Releases are triggered manually (e.g. via `workflow_dispatch`) |
+| `standing-pr` | Changes accumulate in a standing release PR *(planned)* |
+| `scheduled` | Releases are triggered on a schedule *(planned)* |
+
+### PR Preview
+
+The `releasekit preview` command posts a comment on pull requests showing what would be released. It reads PR labels from GitHub and adapts its messaging based on `releaseStrategy` and `releaseTrigger`.
+
+Add this workflow to `.github/workflows/release-preview.yml`:
+
+```yaml
+name: Release Preview
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, labeled, unlabeled]
+
+concurrency:
+  group: release-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  preview:
+    name: Release Preview
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Release preview
+        run: npx releasekit preview
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+```
+
+A template is also available at [`templates/workflows/release-preview.yml`](../../templates/workflows/release-preview.yml).
+
 ## License
 
 MIT

package/dist/chunk-EDF3BZFF.js

@@ -0,0 +1,45 @@
+import {
+  EXIT_CODES,
+  runRelease
+} from "./chunk-I5ABZWVU.js";
+
+// src/release-command.ts
+import { Command } from "commander";
+function createReleaseCommand() {
+  return new Command("release").description("Run the full release pipeline").option("-c, --config <path>", "Path to config file").option("-d, --dry-run", "Preview all steps without side effects", false).option("-b, --bump <type>", "Force bump type (patch|minor|major)").option("-p, --prerelease [identifier]", "Create prerelease version").option("-s, --sync", "Use synchronized versioning across all packages", false).option("-t, --target <packages>", "Target specific packages (comma-separated)").option("--branch <name>", "Override the git branch used for push").option("--skip-notes", "Skip changelog generation", false).option("--skip-publish", "Skip registry publishing and git operations", false).option("--skip-git", "Skip git commit/tag/push", false).option("--skip-github-release", "Skip GitHub release creation", false).option("--skip-verification", "Skip post-publish verification", false).option("-j, --json", "Output results as JSON", false).option("-v, --verbose", "Verbose logging", false).option("-q, --quiet", "Suppress non-error output", false).option("--project-dir <path>", "Project directory", process.cwd()).action(async (opts) => {
+    const options = {
+      config: opts.config,
+      dryRun: opts.dryRun,
+      bump: opts.bump,
+      prerelease: opts.prerelease,
+      sync: opts.sync,
+      target: opts.target,
+      branch: opts.branch,
+      skipNotes: opts.skipNotes,
+      skipPublish: opts.skipPublish,
+      skipGit: opts.skipGit,
+      skipGithubRelease: opts.skipGithubRelease,
+      skipVerification: opts.skipVerification,
+      json: opts.json,
+      verbose: opts.verbose,
+      quiet: opts.quiet,
+      projectDir: opts.projectDir
+    };
+    try {
+      const result = await runRelease(options);
+      if (options.json && result) {
+        console.log(JSON.stringify(result, null, 2));
+      }
+      if (!result) {
+        process.exit(0);
+      }
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+  });
+}
+
+export {
+  createReleaseCommand
+};