@releasekit/release 0.3.0 → 0.4.0

package/dist/cli.js

@@ -1 +1,59 @@
 #!/usr/bin/env node
+import {
+  createReleaseCommand
+} from "./chunk-WNKYXS62.js";
+import {
+  runPreview
+} from "./chunk-I5CGC253.js";
+import {
+  EXIT_CODES,
+  readPackageVersion
+} from "./chunk-YZHGXRG6.js";
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { Command as Command2 } from "commander";
+
+// src/preview-command.ts
+import { Command } from "commander";
+function createPreviewCommand() {
+  return new Command("preview").description("Post a release preview comment on the current pull request").option("-c, --config <path>", "Path to config file").option("--project-dir <path>", "Project directory", process.cwd()).option("--pr <number>", "PR number (auto-detected from GitHub Actions)").option("--repo <owner/repo>", "Repository (auto-detected from GITHUB_REPOSITORY)").option("-p, --prerelease [identifier]", "Force prerelease preview (auto-detected by default)").option("--stable", "Force stable release preview (graduation from prerelease)", false).option(
+    "-d, --dry-run",
+    "Print the comment to stdout without posting (GitHub context not available in dry-run mode)",
+    false
+  ).action(async (opts) => {
+    try {
+      await runPreview({
+        config: opts.config,
+        projectDir: opts.projectDir,
+        pr: opts.pr,
+        repo: opts.repo,
+        prerelease: opts.prerelease,
+        stable: opts.stable,
+        dryRun: opts.dryRun
+      });
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(EXIT_CODES.GENERAL_ERROR);
+    }
+  });
+}
+
+// src/cli.ts
+function createReleaseProgram() {
+  return new Command2().name("releasekit-release").description("Unified release pipeline: version, changelog, and publish").version(readPackageVersion(import.meta.url)).addCommand(createReleaseCommand(), { isDefault: true }).addCommand(createPreviewCommand());
+}
+var isMain = (() => {
+  try {
+    return process.argv[1] ? realpathSync(process.argv[1]) === fileURLToPath(import.meta.url) : false;
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  createReleaseProgram().parse();
+}
+export {
+  createReleaseProgram
+};

package/dist/dispatcher.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+
+declare function createDispatcherProgram(): Command;
+
+export { createDispatcherProgram };

package/dist/dispatcher.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import {
+  createReleaseCommand
+} from "./chunk-WNKYXS62.js";
+import {
+  EXIT_CODES,
+  error,
+  info,
+  readPackageVersion,
+  success
+} from "./chunk-YZHGXRG6.js";
+
+// src/dispatcher.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { createNotesCommand } from "@releasekit/notes/cli";
+import { createPublishCommand } from "@releasekit/publish/cli";
+import { createVersionCommand } from "@releasekit/version/cli";
+import { Command as Command2 } from "commander";
+
+// src/init-command.ts
+import * as fs from "fs";
+import { detectMonorepo } from "@releasekit/notes";
+import { Command } from "commander";
+function createInitCommand() {
+  return new Command("init").description("Create a default releasekit.config.json").option("-f, --force", "Overwrite existing config").action((options) => {
+    const configPath = "releasekit.config.json";
+    if (fs.existsSync(configPath) && !options.force) {
+      error(`Config file already exists at ${configPath}. Use --force to overwrite.`);
+      process.exit(EXIT_CODES.GENERAL_ERROR);
+    } else {
+      let changelogMode;
+      try {
+        const detected = detectMonorepo(process.cwd());
+        changelogMode = detected.isMonorepo ? "packages" : "root";
+        info(
+          detected.isMonorepo ? "Monorepo detected \u2014 using mode: packages" : "Single-package repo detected \u2014 using mode: root"
+        );
+      } catch {
+        changelogMode = "root";
+        info("Could not detect project type \u2014 using mode: root");
+      }
+      let packageName;
+      try {
+        const pkg = JSON.parse(fs.readFileSync("package.json", "utf-8"));
+        packageName = pkg.name;
+      } catch {
+      }
+      const isScoped = packageName?.startsWith("@") ?? false;
+      const defaultConfig = {
+        $schema: "https://goosewobbler.github.io/releasekit/schema.json",
+        notes: {
+          changelog: {
+            mode: changelogMode
+          }
+        },
+        publish: {
+          npm: {
+            enabled: true,
+            ...isScoped ? { access: "public" } : {}
+          }
+        }
+      };
+      fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2), "utf-8");
+      success(`Created ${configPath}`);
+    }
+  });
+}
+
+// src/dispatcher.ts
+function createDispatcherProgram() {
+  const program = new Command2().name("releasekit").description("Unified release pipeline: version, changelog, and publish").version(readPackageVersion(import.meta.url));
+  program.addCommand(createReleaseCommand(), { isDefault: true });
+  program.addCommand(createInitCommand());
+  program.addCommand(createVersionCommand());
+  program.addCommand(createNotesCommand());
+  program.addCommand(createPublishCommand());
+  return program;
+}
+var isMain = (() => {
+  try {
+    return process.argv[1] ? realpathSync(process.argv[1]) === fileURLToPath(import.meta.url) : false;
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  createDispatcherProgram().parse();
+}
+export {
+  createDispatcherProgram
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { PreviewOptions, runPreview } from './preview.ts';
+export { runRelease } from './release.ts';
+export { ReleaseOptions, ReleaseOutput } from './types.ts';

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  runPreview
+} from "./chunk-I5CGC253.js";
+import {
+  runRelease
+} from "./chunk-YZHGXRG6.js";
+export {
+  runPreview,
+  runRelease
+};

package/docs/ci-setup.md

@@ -0,0 +1,266 @@
+# CI Setup
+
+This guide covers common GitHub Actions patterns for automating releases with `@releasekit/release`.
+
+## Prerequisites
+
+All workflows require:
+
+- `fetch-depth: 0` on checkout — ReleaseKit reads git history to determine version bumps
+- A `GITHUB_TOKEN` with `contents: write` permission for tagging and GitHub Releases
+- Node.js 20+
+
+---
+
+## Minimal Setup (push to main)
+
+Trigger a release on every push to `main`. If there are no releasable commits, the command exits cleanly with code 0 and does nothing.
+
+```yaml
+# .github/workflows/release.yml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write   # for npm OIDC trusted publishing
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npx releasekit release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # For OIDC trusted publishing (recommended) — no NPM_TOKEN needed.
+          # For token-based publishing: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+---
+
+## Label-Based Trigger
+
+Only release when a PR is merged with a release label. Conventional commits determine the changelog entries; the label controls whether and at what level to bump.
+
+**Required labels** (customisable in config):
+
+| Label | Effect |
+|-------|--------|
+| `release:patch` | Bump patch version |
+| `release:minor` | Bump minor version |
+| `release:major` | Bump major version |
+| `release:stable` | Graduate a prerelease to stable |
+| `release:prerelease` | Create a prerelease |
+| `release:skip` | Suppress release on this PR |
+
+```yaml
+# .github/workflows/release.yml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  id-token: write
+  pull-requests: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npx releasekit release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Configure the trigger in `releasekit.config.json`:
+
+```json
+{
+  "ci": {
+    "releaseTrigger": "label",
+    "labels": {
+      "major": "release:major",
+      "minor": "release:minor",
+      "patch": "release:patch",
+      "skip": "release:skip"
+    }
+  }
+}
+```
+
+Without a `release:patch/minor/major` label on the merged PR, no release is triggered. The `labels` block shown above reflects the defaults — omit it if your repository already uses those label names.
+
+See [@releasekit/release — CI Configuration](../README.md#ci-configuration) for all `ci.*` options.
+
+---
+
+## PR Preview Comments
+
+Post a comment on every PR showing what would be released if merged. Requires `pull-requests: write`.
+
+```yaml
+# .github/workflows/release-preview.yml
+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:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - run: npm ci
+
+      - run: npx releasekit preview
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+A ready-to-use template is available at [`templates/workflows/release-preview.yml`](../../../templates/workflows/release-preview.yml).
+
+---
+
+## npm OIDC Trusted Publishing (Recommended)
+
+With OIDC, no `NPM_TOKEN` secret is required. The workflow exchanges a GitHub-issued OIDC token for a short-lived npm token at publish time.
+
+**Requirements:**
+- npm `>=9.5.0`
+- Each package must have an **Automation policy** configured at npmjs.com (Settings → Automation policies → add a GitHub Actions OIDC publisher for your repo and workflow)
+
+**Important:** `actions/setup-node` with `registry-url` writes a project `.npmrc` that injects `_authToken=${NODE_AUTH_TOKEN}`. When `NODE_AUTH_TOKEN` is unset, npm resolves this to an empty token and fails with `ENEEDAUTH` instead of falling through to the OIDC exchange. Delete the file before publishing:
+
+```yaml
+permissions:
+  contents: write
+  id-token: write    # grants the OIDC token
+
+steps:
+  - uses: actions/setup-node@v4
+    with:
+      node-version: '20'
+      registry-url: 'https://registry.npmjs.org'
+
+  - run: npx releasekit release
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      # No NPM_TOKEN needed with OIDC
+```
+
+ReleaseKit detects OIDC availability automatically (`npm-auth: auto`). To force it:
+
+```json
+{
+  "publish": {
+    "npm": { "auth": "oidc" }
+  }
+}
+```
+
+---
+
+## Prerelease Workflow
+
+```yaml
+# Manual dispatch for prereleases
+on:
+  workflow_dispatch:
+    inputs:
+      prerelease:
+        description: 'Prerelease identifier (e.g. beta, rc)'
+        required: true
+        default: 'beta'
+
+jobs:
+  prerelease:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npx releasekit release --prerelease ${{ inputs.prerelease }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+---
+
+## Monorepo Targeted Release
+
+Release only specific packages:
+
+```bash
+npx releasekit release --target @myorg/core,@myorg/cli
+```
+
+Or version all packages together:
+
+```bash
+npx releasekit release --sync
+```
+
+---
+
+## Dry Run in CI
+
+Useful for verifying pipeline setup before enabling real releases:
+
+```yaml
+- run: npx releasekit release --dry-run --json
+```
+
+`--dry-run` prints what would happen without modifying any files, creating tags, or publishing packages. `--json` emits structured output for inspection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@releasekit/release",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Unified release pipeline: version, changelog, and publish in a single command",
   "type": "module",
   "module": "./dist/index.js",
@@ -37,6 +37,7 @@
   "license": "MIT",
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -49,9 +50,9 @@
     "commander": "^14.0.3",
     "smol-toml": "^1.6.1",
     "zod": "^4.3.6",
-    "@releasekit/notes": "0.3.0",
-    "@releasekit/version": "0.3.0",
-    "@releasekit/publish": "0.3.0"
+    "@releasekit/notes": "0.4.0",
+    "@releasekit/publish": "0.4.0",
+    "@releasekit/version": "0.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
@@ -61,8 +62,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@releasekit/core": "0.0.0",
-    "@releasekit/config": "0.0.0"
+    "@releasekit/config": "0.0.0",
+    "@releasekit/core": "0.0.0"
   },
   "engines": {
     "node": ">=20"