@releasekit/publish 0.3.1 → 0.4.1

package/README.md

@@ -1,6 +1,10 @@
 # @releasekit/publish
 
-Publish packages to npm and crates.io with git tagging and GitHub releases.
+[![@releasekit/publish](https://img.shields.io/badge/@releasekit-publish-9feaf9?labelColor=1a1a1a&style=plastic)](https://www.npmjs.com/package/@releasekit/publish)
+[![Version](https://img.shields.io/npm/v/@releasekit/publish?color=28a745&labelColor=1a1a1a)](https://www.npmjs.com/package/@releasekit/publish)
+[![Downloads](https://img.shields.io/npm/dw/@releasekit/publish?color=6f42c1&labelColor=1a1a1a)](https://www.npmjs.com/package/@releasekit/publish)
+
+**Publish packages to npm and crates.io with git tagging and GitHub releases.**
 
 ## Features
 
@@ -50,6 +54,8 @@ The publish pipeline runs in order:
 8. **Git Push** - Push commits and tags to remote
 9. **GitHub Release** - Create GitHub releases
 
+The pipeline is **fail-fast**: the first package publish failure throws immediately. Git push and GitHub release are skipped, so the version commit and tag remain local until the issue is fixed and the release is retried.
+
 ## CLI Reference
 
 | Flag | Description | Default |
@@ -59,7 +65,7 @@ The publish pipeline runs in order:
 | `--registry <type>` | Registry to publish to: `npm`, `cargo`, `all` | `all` |
 | `--npm-auth <method>` | NPM auth method: `oidc`, `token`, `auto` | `auto` |
 | `--dry-run` | Simulate all operations | `false` |
-| `--skip-git` | Skip git commit/tag/push | `false` |
+| `--skip-git` | Skip git commit/tag/push (also skips GitHub release — no tag to release against) | `false` |
 | `--skip-publish` | Skip registry publishing | `false` |
 | `--skip-github-release` | Skip GitHub Release creation | `false` |
 | `--skip-verification` | Skip post-publish verification | `false` |
@@ -126,7 +132,7 @@ Configure via `releasekit.config.json`:
     "githubRelease": {
       "enabled": true,
       "draft": true,
-      "generateNotes": true
+      "body": "auto"
     },
     "verify": {
       "npm": {
@@ -144,6 +150,11 @@ Configure via `releasekit.config.json`:
 
 See [@releasekit/config](../config/README.md) for full configuration options.
 
+## Documentation
+
+**Guides**
+- [GitHub Releases](./docs/github-releases.md) — release body options, LLM prose, draft workflow
+
 ## License
 
 MIT

package/dist/{chunk-GIMIZS5B.js → chunk-ZMMZ7S6G.js}

@@ -223,14 +223,14 @@ var GitHubReleaseConfigSchema = z.object({
   perPackage: z.boolean().default(true),
   prerelease: z.union([z.literal("auto"), z.boolean()]).default("auto"),
   /**
-   * Controls how release notes are sourced for GitHub releases.
-   * - 'auto': Use RELEASE_NOTES.md if it exists, then per-package changelog
-   *   data from the version output, then GitHub's auto-generated notes.
-   * - 'github': Always use GitHub's auto-generated notes.
-   * - 'none': No notes body.
-   * - Any other string: Treated as a file path to read notes from.
+   * Controls the source for the GitHub release body.
+   * - 'auto': Use release notes if enabled, else changelog, else GitHub auto-generated.
+   * - 'releaseNotes': Use LLM-generated release notes (requires notes.releaseNotes.enabled: true).
+   * - 'changelog': Use formatted changelog entries.
+   * - 'generated': Use GitHub's auto-generated notes.
+   * - 'none': No body.
    */
-  releaseNotes: z.union([z.literal("auto"), z.literal("github"), z.literal("none"), z.string()]).default("auto")
+  body: z.enum(["auto", "releaseNotes", "changelog", "generated", "none"]).default("auto")
 });
 var VerifyRegistryConfigSchema = z.object({
   enabled: z.boolean().default(true),
@@ -274,7 +274,7 @@ var PublishConfigSchema = z.object({
     draft: true,
     perPackage: true,
     prerelease: "auto",
-    releaseNotes: "auto"
+    body: "auto"
   }),
   verify: VerifyConfigSchema.default({
     npm: {
@@ -295,10 +295,10 @@ var TemplateConfigSchema = z.object({
   path: z.string().optional(),
   engine: z.enum(["handlebars", "liquid", "ejs"]).optional()
 });
-var OutputConfigSchema = z.object({
-  format: z.enum(["markdown", "github-release", "json"]),
+var LocationModeSchema = z.enum(["root", "packages", "both"]);
+var ChangelogConfigSchema = z.object({
+  mode: LocationModeSchema.optional(),
   file: z.string().optional(),
-  options: z.record(z.string(), z.unknown()).optional(),
   templates: TemplateConfigSchema.optional()
 });
 var LLMOptionsSchema = z.object({
@@ -358,17 +358,20 @@ var LLMConfigSchema = z.object({
   scopes: ScopeConfigSchema.optional(),
   prompts: LLMPromptsConfigSchema.optional()
 });
+var ReleaseNotesConfigSchema = z.object({
+  mode: LocationModeSchema.optional(),
+  file: z.string().optional(),
+  templates: TemplateConfigSchema.optional(),
+  llm: LLMConfigSchema.optional()
+});
 var NotesInputConfigSchema = z.object({
   source: z.string().optional(),
   file: z.string().optional()
 });
 var NotesConfigSchema = z.object({
-  input: NotesInputConfigSchema.optional(),
-  output: z.array(OutputConfigSchema).default([{ format: "markdown", file: "CHANGELOG.md" }]),
-  monorepo: MonorepoConfigSchema.optional(),
-  templates: TemplateConfigSchema.optional(),
-  llm: LLMConfigSchema.optional(),
-  updateStrategy: z.enum(["prepend", "regenerate"]).default("prepend")
+  changelog: z.union([z.literal(false), ChangelogConfigSchema]).optional(),
+  releaseNotes: z.union([z.literal(false), ReleaseNotesConfigSchema]).optional(),
+  updateStrategy: z.enum(["prepend", "regenerate"]).optional()
 });
 var CILabelsConfigSchema = z.object({
   stable: z.string().default("release:stable"),
@@ -544,7 +547,7 @@ function getDefaultConfig() {
       draft: true,
       perPackage: true,
       prerelease: "auto",
-      releaseNotes: "auto"
+      body: "auto"
     },
     verify: {
       npm: {
@@ -594,7 +597,7 @@ function toPublishConfig(config) {
       draft: config.githubRelease?.draft ?? defaults.githubRelease.draft,
       perPackage: config.githubRelease?.perPackage ?? defaults.githubRelease.perPackage,
       prerelease: config.githubRelease?.prerelease ?? defaults.githubRelease.prerelease,
-      releaseNotes: config.githubRelease?.releaseNotes ?? defaults.githubRelease.releaseNotes
+      body: config.githubRelease?.body ?? defaults.githubRelease.body
     },
     verify: {
       npm: {
@@ -977,11 +980,15 @@ async function runCargoPublishStage(ctx) {
       if (!dryRun) {
         success(`Published ${crate.name}@${crate.version} to crates.io`);
       }
+      ctx.output.cargo.push(result);
     } catch (error) {
       result.reason = error instanceof Error ? error.message : String(error);
-      warn(`Failed to publish ${crate.name}: ${result.reason}`);
+      ctx.output.cargo.push(result);
+      throw createPublishError(
+        "CARGO_PUBLISH_ERROR" /* CARGO_PUBLISH_ERROR */,
+        `${crate.name}@${crate.version}: ${result.reason}`
+      );
     }
-    ctx.output.cargo.push(result);
   }
 }
 function findCrates(updates, _cwd) {
@@ -1237,21 +1244,34 @@ async function runGitPushStage(ctx) {
 }
 
 // src/stages/github-release.ts
-import * as fs7 from "fs";
-function resolveNotes(notesSetting, tag, changelogs, pipelineNotes) {
-  if (notesSetting === "none") {
+function resolveNotes(bodySource, tag, changelogs, releaseNotesEnabled, pipelineNotes) {
+  if (bodySource === "none") {
     return { useGithubNotes: false };
   }
-  if (notesSetting === "github") {
+  if (bodySource === "generated") {
     return { useGithubNotes: true };
   }
-  if (notesSetting !== "auto") {
-    const body = readFileIfExists(notesSetting);
-    if (body) return { body, useGithubNotes: false };
-    debug(`Notes file not found: ${notesSetting}, falling back to GitHub auto-notes`);
+  if (bodySource === "releaseNotes") {
+    if (!releaseNotesEnabled) {
+      warn("releaseNotes is not enabled in notes config but body is set to releaseNotes");
+      return { useGithubNotes: true };
+    }
+    if (pipelineNotes) {
+      const body = findNotesForTag(tag, pipelineNotes);
+      if (body) return { body, useGithubNotes: false };
+    }
+    warn("No release notes found in pipeline output, falling back to GitHub auto-notes");
+    return { useGithubNotes: true };
+  }
+  if (bodySource === "changelog") {
+    const packageBody2 = formatChangelogForTag(tag, changelogs);
+    if (packageBody2) {
+      return { body: packageBody2, useGithubNotes: false };
+    }
+    warn("No changelog found for tag, falling back to GitHub auto-notes");
     return { useGithubNotes: true };
   }
-  if (pipelineNotes) {
+  if (releaseNotesEnabled && pipelineNotes) {
     const body = findNotesForTag(tag, pipelineNotes);
     if (body) return { body, useGithubNotes: false };
   }
@@ -1264,6 +1284,15 @@ function resolveNotes(notesSetting, tag, changelogs, pipelineNotes) {
 function isVersionOnlyTag(tag) {
   return /^v?\d+\.\d+\.\d+/.test(tag);
 }
+function getTitleFromTag(tag) {
+  const atIndex = tag.lastIndexOf("@");
+  if (atIndex === -1) {
+    return tag;
+  }
+  const packageName = tag.slice(0, atIndex);
+  const version = tag.slice(atIndex + 1);
+  return `${packageName} @ ${version}`;
+}
 function findNotesForTag(tag, notes) {
   for (const [packageName, body] of Object.entries(notes)) {
     if (tag.startsWith(`${packageName}@`) && body.trim()) {
@@ -1274,14 +1303,6 @@ function findNotesForTag(tag, notes) {
   if (entries.length === 1 && isVersionOnlyTag(tag)) return entries[0];
   return void 0;
 }
-function readFileIfExists(filePath) {
-  try {
-    const content = fs7.readFileSync(filePath, "utf-8").trim();
-    return content || void 0;
-  } catch {
-    return void 0;
-  }
-}
 function formatChangelogForTag(tag, changelogs) {
   if (changelogs.length === 0) return void 0;
   const changelog = changelogs.find((c) => tag.startsWith(`${c.packageName}@`));
@@ -1322,16 +1343,19 @@ async function runGithubReleaseStage(ctx) {
       success: false
     };
     const ghArgs = ["release", "create", tag];
+    ghArgs.push("--title", getTitleFromTag(tag));
     if (config.githubRelease.draft) {
       ghArgs.push("--draft");
     }
     if (isPreRel) {
       ghArgs.push("--prerelease");
     }
+    const releaseNotesEnabled = !!(ctx.releaseNotes && Object.keys(ctx.releaseNotes).length > 0);
     const { body, useGithubNotes } = resolveNotes(
-      config.githubRelease.releaseNotes,
+      config.githubRelease.body,
       tag,
       ctx.input.changelogs,
+      releaseNotesEnabled,
       ctx.releaseNotes
     );
     if (body) {
@@ -1360,22 +1384,22 @@ async function runGithubReleaseStage(ctx) {
 }
 
 // src/stages/npm-publish.ts
-import * as fs9 from "fs";
+import * as fs8 from "fs";
 import * as path8 from "path";
 
 // src/utils/npm-env.ts
-import * as fs8 from "fs";
+import * as fs7 from "fs";
 import * as os2 from "os";
 import * as path7 from "path";
 function writeTempNpmrc(contents) {
-  const dir = fs8.mkdtempSync(path7.join(os2.tmpdir(), "releasekit-npmrc-"));
+  const dir = fs7.mkdtempSync(path7.join(os2.tmpdir(), "releasekit-npmrc-"));
   const npmrcPath = path7.join(dir, ".npmrc");
-  fs8.writeFileSync(npmrcPath, contents, "utf-8");
+  fs7.writeFileSync(npmrcPath, contents, "utf-8");
   return {
     npmrcPath,
     cleanup: () => {
       try {
-        fs8.rmSync(dir, { recursive: true, force: true });
+        fs7.rmSync(dir, { recursive: true, force: true });
       } catch {
       }
     }
@@ -1395,9 +1419,6 @@ function createNpmSubprocessIsolation(options) {
     }
   })();
   const lines = [`registry=${registryUrl}`];
-  if (authMethod === "oidc") {
-    lines.push("always-auth=false");
-  }
   if (authMethod === "token" && token) {
     lines.push(`//${registryHost}/:_authToken=${token}`);
   }
@@ -1413,10 +1434,7 @@ function createNpmSubprocessIsolation(options) {
       npm_config_userconfig: npmrcPath,
       // Auth-specific hardening
       ...isOidc ? {
-        // Prevent setup-node's always-auth from forcing token lookups
-        NPM_CONFIG_ALWAYS_AUTH: "false",
-        npm_config_always_auth: "false",
-        // Explicitly prevent token-based publishing from being selected implicitly
+        // Prevent any ambient token from overriding OIDC trusted publishing
         NODE_AUTH_TOKEN: void 0,
         NPM_TOKEN: void 0
       } : {
@@ -1456,7 +1474,7 @@ async function runNpmPublishStage(ctx) {
       };
       const pkgJsonPath = path8.resolve(cwd, update.filePath);
       try {
-        const pkgContent = fs9.readFileSync(pkgJsonPath, "utf-8");
+        const pkgContent = fs8.readFileSync(pkgJsonPath, "utf-8");
         const pkgJson = JSON.parse(pkgContent);
         if (pkgJson.private) {
           result.skipped = true;
@@ -1514,11 +1532,15 @@ async function runNpmPublishStage(ctx) {
         if (!dryRun) {
           success(`Published ${update.packageName}@${update.newVersion} to npm`);
         }
+        ctx.output.npm.push(result);
       } catch (error) {
         result.reason = error instanceof Error ? error.message : String(error);
-        warn(`Failed to publish ${update.packageName}: ${result.reason}`);
+        ctx.output.npm.push(result);
+        throw createPublishError(
+          "NPM_PUBLISH_ERROR" /* NPM_PUBLISH_ERROR */,
+          `${update.packageName}@${update.newVersion}: ${result.reason}`
+        );
       }
-      ctx.output.npm.push(result);
     }
   } finally {
     npmIsolation.cleanup();
@@ -1526,7 +1548,7 @@ async function runNpmPublishStage(ctx) {
 }
 
 // src/stages/prepare.ts
-import * as fs10 from "fs";
+import * as fs9 from "fs";
 import * as path9 from "path";
 async function runPrepareStage(ctx) {
   const { input, config, cliOptions, cwd } = ctx;
@@ -1536,7 +1558,7 @@ async function runPrepareStage(ctx) {
       for (const file of config.npm.copyFiles) {
         const src = path9.resolve(cwd, file);
         const dest = path9.join(pkgDir, file);
-        if (!fs10.existsSync(src)) {
+        if (!fs9.existsSync(src)) {
           debug(`Source file not found, skipping copy: ${src}`);
           continue;
         }
@@ -1549,7 +1571,7 @@ async function runPrepareStage(ctx) {
           continue;
         }
         try {
-          fs10.copyFileSync(src, dest);
+          fs9.copyFileSync(src, dest);
           debug(`Copied ${file} \u2192 ${pkgDir}`);
         } catch (error) {
           throw createPublishError(
@@ -1564,7 +1586,7 @@ async function runPrepareStage(ctx) {
     for (const update of input.updates) {
       const pkgDir = path9.dirname(path9.resolve(cwd, update.filePath));
       const cargoPath = path9.join(pkgDir, "Cargo.toml");
-      if (!fs10.existsSync(cargoPath)) {
+      if (!fs9.existsSync(cargoPath)) {
         continue;
       }
       if (cliOptions.dryRun) {
@@ -1713,7 +1735,8 @@ async function runPipeline(input, config, options) {
       npm: [],
       cargo: [],
       verification: [],
-      githubReleases: []
+      githubReleases: [],
+      publishSucceeded: false
     }
   };
   try {
@@ -1731,14 +1754,15 @@ async function runPipeline(input, config, options) {
       if (options.registry === "all" || options.registry === "cargo") {
         await runCargoPublishStage(ctx);
       }
+      ctx.output.publishSucceeded = ctx.output.npm.every((r) => r.success) && ctx.output.cargo.every((r) => r.success);
     }
     if (!options.skipVerification && !options.skipPublish) {
       await runVerifyStage(ctx);
     }
-    if (!options.skipGit) {
+    if (!options.skipGit && (options.skipPublish || ctx.output.publishSucceeded)) {
       await runGitPushStage(ctx);
     }
-    if (!options.skipGithubRelease) {
+    if (!options.skipGithubRelease && ctx.output.git.pushed) {
       await runGithubReleaseStage(ctx);
     }
   } catch (error) {
@@ -1750,7 +1774,7 @@ async function runPipeline(input, config, options) {
 }
 
 // src/stages/input.ts
-import * as fs11 from "fs";
+import * as fs10 from "fs";
 import { z as z3 } from "zod";
 var VersionChangelogEntrySchema = z3.object({
   type: z3.string(),
@@ -1783,7 +1807,7 @@ async function parseInput(inputPath) {
   let raw;
   if (inputPath) {
     try {
-      raw = fs11.readFileSync(inputPath, "utf-8");
+      raw = fs10.readFileSync(inputPath, "utf-8");
     } catch {
       throw createPublishError("INPUT_PARSE_ERROR" /* INPUT_PARSE_ERROR */, `Could not read file: ${inputPath}`);
     }

package/dist/cli.js

@@ -9,7 +9,7 @@ import {
   runPipeline,
   setJsonMode,
   setLogLevel
-} from "./chunk-GIMIZS5B.js";
+} from "./chunk-ZMMZ7S6G.js";
 
 // src/cli.ts
 import { realpathSync } from "fs";

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   parseInput,
   runPipeline,
   updateCargoVersion
-} from "./chunk-GIMIZS5B.js";
+} from "./chunk-ZMMZ7S6G.js";
 export {
   BasePublishError,
   PipelineError,

package/docs/github-releases.md

@@ -0,0 +1,177 @@
+# GitHub Releases
+
+`@releasekit/publish` creates a GitHub Release for each published package. This guide covers configuration options and how to use LLM-generated prose as the release body.
+
+## Enabling GitHub Releases
+
+GitHub Releases are enabled by default. Requires `GITHUB_TOKEN` with `contents: write` permission.
+
+```json
+{
+  "publish": {
+    "githubRelease": {
+      "enabled": true
+    }
+  }
+}
+```
+
+To disable:
+
+```json
+{
+  "publish": {
+    "githubRelease": { "enabled": false }
+  }
+}
+```
+
+---
+
+## Release Body (`body`)
+
+Controls what appears in the GitHub Release description.
+
+| Value | Behaviour |
+|-------|-----------|
+| `"auto"` (default) | Use LLM release notes if available, otherwise changelog entries, otherwise GitHub auto-generated notes |
+| `"releaseNotes"` | Use LLM-generated prose release notes (requires `notes.releaseNotes.llm.tasks.releaseNotes: true`) |
+| `"changelog"` | Use the formatted changelog entries for this version |
+| `"generated"` | GitHub's auto-generated release notes (from merged PRs and commits) |
+| `"none"` | No release body |
+
+```json
+{
+  "publish": {
+    "githubRelease": {
+      "body": "releaseNotes"
+    }
+  }
+}
+```
+
+---
+
+## Using LLM-Generated Release Notes
+
+To populate the GitHub Release body with LLM-written prose:
+
+**1. Enable the `releaseNotes` LLM task in notes config:**
+
+```json
+{
+  "notes": {
+    "releaseNotes": {
+      "llm": {
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "tasks": { "releaseNotes": true }
+      }
+    }
+  },
+  "publish": {
+    "githubRelease": {
+      "body": "releaseNotes"
+    }
+  }
+}
+```
+
+The notes step runs first, the LLM generates prose release notes, and the publish step forwards them to the GitHub Release API.
+
+If `body` is `"auto"` (default), LLM release notes are used automatically when available — no extra config needed.
+
+**2. Optionally write release notes to a file** as well:
+
+```json
+{
+  "notes": {
+    "releaseNotes": {
+      "mode": "root",
+      "llm": {
+        "provider": "anthropic",
+        "model": "claude-haiku-4-5",
+        "tasks": { "releaseNotes": true }
+      }
+    }
+  }
+}
+```
+
+When `mode` is set, a `RELEASE_NOTES.md` file is written in addition to the GitHub Release being populated.
+
+---
+
+## Draft Releases
+
+Releases are created as drafts by default, giving you a chance to review before publishing.
+
+```json
+{
+  "publish": {
+    "githubRelease": {
+      "draft": true
+    }
+  }
+}
+```
+
+Set `"draft": false` to publish releases immediately.
+
+---
+
+## Prerelease Marking
+
+```json
+{
+  "publish": {
+    "githubRelease": {
+      "prerelease": "auto"
+    }
+  }
+}
+```
+
+| Value | Behaviour |
+|-------|-----------|
+| `"auto"` (default) | Marked as prerelease when the version contains a prerelease identifier (e.g. `1.0.0-beta.1`) |
+| `true` | Always marked as prerelease |
+| `false` | Never marked as prerelease |
+
+---
+
+## Per-Package Releases
+
+In a monorepo, a separate GitHub Release is created for each published package by default.
+
+```json
+{
+  "publish": {
+    "githubRelease": {
+      "perPackage": true
+    }
+  }
+}
+```
+
+Set `"perPackage": false` to create a single release for the entire repo.
+
+---
+
+## Full Configuration Reference
+
+```json
+{
+  "publish": {
+    "githubRelease": {
+      "enabled": true,
+      "draft": true,
+      "prerelease": "auto",
+      "perPackage": true,
+      "body": "auto"
+    }
+  }
+}
+```
+
+See the [@releasekit/publish README](../README.md) for all options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@releasekit/publish",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Publish packages to npm and crates.io with git tagging and GitHub releases",
   "type": "module",
   "module": "./dist/index.js",
@@ -41,6 +41,7 @@
   "license": "MIT",
   "files": [
     "dist",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -62,8 +63,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@releasekit/config": "0.0.0",
-    "@releasekit/core": "0.0.0"
+    "@releasekit/core": "0.0.0",
+    "@releasekit/config": "0.0.0"
   },
   "engines": {
     "node": ">=20"