@oorabona/release-it-preset 0.8.1 → 0.10.1

package/README.md

@@ -4,6 +4,7 @@ Shared [release-it](https://github.com/release-it/release-it) configuration and
 
 [![codecov](https://codecov.io/github/oorabona/release-it-preset/graph/badge.svg?token=6RMN34Z7TX)](https://codecov.io/github/oorabona/release-it-preset)
 [![CI](https://github.com/oorabona/release-it-preset/actions/workflows/ci.yml/badge.svg)](https://github.com/oorabona/release-it-preset/actions/workflows/ci.yml)
+[![Audit](https://github.com/oorabona/release-it-preset/actions/workflows/audit.yml/badge.svg)](https://github.com/oorabona/release-it-preset/actions/workflows/audit.yml)
 [![NPM Version](https://img.shields.io/npm/v/release-it-preset.svg)](https://npmjs.org/package/@oorabona/release-it-preset)
 [![NPM Downloads](https://img.shields.io/npm/dm/release-it-preset.svg)](https://npmjs.org/package/@oorabona/release-it-preset)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
@@ -16,6 +17,11 @@ Shared [release-it](https://github.com/release-it/release-it) configuration and
 - [Quick Start](#quick-start)
 - [Available Configurations](#available-configurations)
 - [CLI Usage](#cli-usage)
+  - [Zero-Config Mode (Auto-Detection)](#zero-config-mode-auto-detection)
+  - [Preset Selection Mode](#preset-selection-mode)
+  - [Passthrough Mode (Custom Config Override)](#passthrough-mode-custom-config-override)
+  - [Monorepo Support](#monorepo-support)
+  - [Utility Commands](#utility-commands)
 - [Scripts](#scripts)
 - [Environment Variables](#environment-variables)
 - [Configuration Override](#configuration-override)
@@ -37,6 +43,9 @@ Shared [release-it](https://github.com/release-it/release-it) configuration and
 - 🔄 Republish and retry mechanisms for failed releases
 - ⚡ Hotfix release support
 - 🎯 Environment variable configuration
+- 🔍 **NEW v0.9.0:** Zero-config auto-detection mode
+- 🏢 **NEW v0.9.0:** Monorepo support with parent directory config references
+- ⚙️ **NEW v0.9.0:** Passthrough mode for custom config files
 
 ## Installation
 
@@ -331,9 +340,42 @@ Features:
 
 ## CLI Usage
 
-The package provides a `release-it-preset` CLI with two types of commands:
+The package provides a `release-it-preset` CLI with four operating modes:
 
-### Release Commands
+1. **Zero-Config Mode** (auto-detection) - No arguments needed
+2. **Preset Selection Mode** - Specify which preset to use
+3. **Passthrough Mode** - Direct config file override
+4. **Utility Mode** - Helper commands
+
+### Zero-Config Mode (Auto-Detection)
+
+**NEW in v0.9.0** - The CLI can automatically detect which preset to use from your `.release-it.json`:
+
+```bash
+# Just run release-it-preset with no arguments
+pnpm release-it-preset
+
+# 🔍 Auto-detected preset: default
+# ✅ Config validated: preset "default"
+# 📝 Using: /path/to/.release-it.json
+```
+
+**How it works:**
+1. CLI reads your `.release-it.json`
+2. Extracts the preset name from the `extends` field
+3. Runs that preset automatically
+
+**Requirements:**
+- `.release-it.json` must exist
+- Must have `extends` field like `"@oorabona/release-it-preset/config/default"`
+
+**Benefits:**
+- ✅ Shortest command possible
+- ✅ Config file is source of truth
+- ✅ No need to remember preset names
+- ✅ Follows industry standards (ESLint, TypeScript, Prettier)
+
+### Preset Selection Mode
 
 Run release-it with specific configurations:
 
@@ -350,6 +392,92 @@ pnpm release-it-preset manual-changelog
 
 All additional arguments are passed through to release-it.
 
+### Passthrough Mode (Custom Config Override)
+
+**NEW in v0.9.0** - Use a custom config file and bypass preset validation:
+
+```bash
+# Use custom config file
+pnpm release-it-preset --config .release-it-manual.json
+
+# 🔀 Passthrough mode: using config .release-it-manual.json
+#    Bypassing preset validation - direct release-it invocation
+```
+
+**Use cases:**
+- **Switching presets occasionally** - Have multiple config files for different scenarios
+- **Monorepo workflows** - Reference shared configs from parent directories
+- **Advanced customization** - Full control over release-it configuration
+
+**Example workflow:**
+
+```json
+// .release-it.json (default - 95% of time)
+{
+  "extends": "@oorabona/release-it-preset/config/default",
+  "git": { "requireBranch": "develop" }
+}
+
+// .release-it-manual.json (rare - 5% of time)
+{
+  "extends": "@oorabona/release-it-preset/config/manual-changelog",
+  "git": { "requireBranch": "develop" }
+}
+```
+
+```bash
+# Normal release
+pnpm release-it-preset                              # Auto-detects default
+
+# Manual changelog release (rare)
+pnpm release-it-preset --config .release-it-manual.json
+```
+
+**Benefits:**
+- ✅ No need to edit `.release-it.json` to switch presets
+- ✅ Config files are explicit and version-controlled
+- ✅ Works with monorepo parent directory references
+
+### Monorepo Support
+
+**NEW in v0.9.0** - Parent directory config references are now supported:
+
+```bash
+# Monorepo structure
+/my-monorepo/
+├── .release-it-base.json        # Shared configuration
+├── packages/
+│   ├── core/
+│   │   └── .release-it.json     # extends: ../../.release-it-base.json
+│   └── utils/
+│       └── .release-it.json     # extends: ../../.release-it-base.json
+```
+
+```json
+// packages/core/.release-it.json
+{
+  "extends": [
+    "../../.release-it-base.json",                    // ✅ Parent reference allowed!
+    "@oorabona/release-it-preset/config/default"
+  ]
+}
+```
+
+**Security validation:**
+- ✅ Parent directory references (`../`) supported (up to 5 levels)
+- ✅ Config file extension whitelist (`.json`, `.js`, `.cjs`, `.mjs`, `.yaml`, `.yml`, `.toml`)
+- ✅ File existence validation
+- ❌ Absolute paths blocked (use relative paths)
+- ❌ Excessive traversal blocked (max `../../../../../../`)
+
+**Why this is safe:**
+- Config files are trusted code (developer controls the repository)
+- Industry standard pattern (TypeScript, ESLint, Prettier all allow `../`)
+- Multiple validation layers prevent abuse
+- No privilege escalation in CLI tool context
+
+See [examples/monorepo-workflow.md](examples/monorepo-workflow.md) for complete monorepo guide.
+
 ### Utility Commands
 
 Helper commands for project setup and maintenance:

package/bin/cli.js

@@ -27,7 +27,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import { validateConfigName, validateUtilityCommand, sanitizeArgs } from './validators.js';
+import { validateConfigName, validateUtilityCommand, sanitizeArgs, validateConfigPath } from './validators.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -54,7 +54,14 @@ const UTILITY_COMMANDS = {
 
 function showHelp() {
   console.log(`
-Usage: release-it-preset <command> [...args]
+Usage: release-it-preset [command] [...args]
+       release-it-preset --config <file> [...args]
+
+CLI Modes:
+  1. Auto-detection (no command)      - Reads preset from .release-it.json
+  2. Preset selection                  - Specify preset command
+  3. Passthrough (--config)            - Direct config file, bypass validation
+  4. Utility commands                  - Helper scripts
 
 Release Commands:
   default          Full release with changelog, git, GitHub, and npm
@@ -73,19 +80,28 @@ Utility Commands:
   check-pr               Evaluate PR hygiene (branch diff, changelog status, conventions)
   retry-publish-preflight  Run retry publish safety checks without executing release
 
+Passthrough Mode:
+  --config <file>  Use custom config file, bypass preset validation
+
 Examples:
+  # Zero-config (auto-detect from .release-it.json)
+  release-it-preset
+
   # Release commands
   release-it-preset default --dry-run
   release-it-preset hotfix --verbose
   release-it-preset changelog-only --ci
 
+  # Passthrough mode (custom config)
+  release-it-preset --config .release-it-manual.json
+
+  # Monorepo (parent config reference)
+  release-it-preset --config ../../.release-it-base.json
+
   # Utility commands
   release-it-preset init
   release-it-preset update
   release-it-preset validate
-  release-it-preset check
-  release-it-preset check-pr
-  release-it-preset retry-publish-preflight
 
 For release-it options, see: https://github.com/release-it/release-it
 For environment variables, see: https://github.com/oorabona/release-it-preset#environment-variables
@@ -138,7 +154,7 @@ function handleReleaseCommand(configName, args) {
       }
 
       // Validate extends matches CLI preset
-      const extendsMatch = userConfig.extends.match(/@oorabona\/release-it-preset\/config\/(\w+)/);
+      const extendsMatch = userConfig.extends.match(/@oorabona\/release-it-preset\/config\/([\w-]+)/);
       const extendsPreset = extendsMatch?.[1];
 
       if (extendsPreset && extendsPreset !== configName) {
@@ -237,10 +253,53 @@ function handleUtilityCommand(commandName, args) {
   });
 }
 
+function passthroughToReleaseIt(args) {
+  // Extract --config value
+  const configIndex = args.indexOf('--config');
+  if (configIndex === -1 || configIndex === args.length - 1) {
+    console.error('❌ --config requires a file path argument\n');
+    console.error('Usage: release-it-preset --config <file>');
+    process.exit(1);
+  }
+
+  const configPath = args[configIndex + 1];
+
+  // Security validation
+  try {
+    validateConfigPath(configPath);
+    sanitizeArgs(args);
+
+    console.log(`🔀 Passthrough mode: using config ${configPath}`);
+    console.log(`   Bypassing preset validation - direct release-it invocation\n`);
+  } catch (error) {
+    console.error(`❌ Configuration validation failed: ${error.message}`);
+    process.exit(1);
+  }
+
+  // Delegate to release-it
+  const releaseItCommand = 'release-it';
+  const child = spawn(releaseItCommand, args, {
+    stdio: 'inherit',
+    shell: false, // Security: prevent command injection
+  });
+
+  child.on('error', (error) => {
+    console.error(`❌ Failed to start release-it: ${error.message}`);
+    console.error(`\nMake sure release-it is installed:`);
+    console.error(`  pnpm add -D release-it`);
+    process.exit(1);
+  });
+
+  child.on('close', (code) => {
+    process.exit(code ?? 0);
+  });
+}
+
 function main() {
   const args = process.argv.slice(2);
 
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  // Handle --help
+  if (args.includes('--help') || args.includes('-h')) {
     showHelp();
     process.exit(0);
   }
@@ -248,13 +307,66 @@ function main() {
   const command = args[0];
   const commandArgs = args.slice(1);
 
-  // Check if it's a release config
+  // Check for conflicting arguments (preset command + --config)
+  if (args.includes('--config') && RELEASE_CONFIGS[command]) {
+    console.error('❌ Conflicting arguments detected!\n');
+    console.error('   You specified both a preset command and --config flag.');
+    console.error('');
+    console.error('   Either:');
+    console.error(`     1. Use preset: release-it-preset ${command}`);
+    console.error(`     2. Use config: release-it-preset --config <file>`);
+    console.error('');
+    console.error('   Do not mix both approaches.');
+    process.exit(1);
+  }
+
+  // MODE 1: Passthrough - Direct release-it with custom config
+  if (args.includes('--config')) {
+    passthroughToReleaseIt(args);
+    return;
+  }
+
+  // MODE 2: Auto-detection - No arguments, read preset from .release-it.json
+  if (args.length === 0) {
+    const userConfigPath = join(process.cwd(), '.release-it.json');
+
+    if (!existsSync(userConfigPath)) {
+      console.error('❌ No command specified and no .release-it.json found\n');
+      console.error('Either:');
+      console.error('  1. Run: release-it-preset init');
+      console.error('  2. Run: release-it-preset <command>\n');
+      showHelp();
+      process.exit(1);
+    }
+
+    try {
+      const config = JSON.parse(readFileSync(userConfigPath, 'utf8'));
+      const extendsMatch = config.extends?.match(/@oorabona\/release-it-preset\/config\/([\w-]+)/);
+
+      if (!extendsMatch) {
+        console.error('❌ .release-it.json does not extend a known preset\n');
+        console.error('Expected extends field like:');
+        console.error('  "@oorabona/release-it-preset/config/default"\n');
+        process.exit(1);
+      }
+
+      const preset = extendsMatch[1];
+      console.log(`🔍 Auto-detected preset: ${preset}`);
+      handleReleaseCommand(preset, []);
+      return;
+    } catch (error) {
+      console.error(`❌ Error reading .release-it.json: ${error.message}`);
+      process.exit(1);
+    }
+  }
+
+  // MODE 3: Preset command (existing logic)
   if (RELEASE_CONFIGS[command]) {
     handleReleaseCommand(command, commandArgs);
     return;
   }
 
-  // Check if it's a utility command
+  // MODE 4: Utility command (existing logic)
   if (UTILITY_COMMANDS[command]) {
     handleUtilityCommand(command, commandArgs);
     return;
@@ -264,6 +376,7 @@ function main() {
   console.error(`❌ Unknown command: ${command}`);
   console.error(`\nAvailable release configs: ${Object.keys(RELEASE_CONFIGS).join(', ')}`);
   console.error(`Available utility commands: ${Object.keys(UTILITY_COMMANDS).join(', ')}`);
+  console.error(`\nFor direct config file usage: release-it-preset --config <file>`);
   console.error(`\nRun 'release-it-preset --help' for more information.`);
   process.exit(1);
 }

package/bin/validators.js

@@ -10,6 +10,9 @@
  * - Fail securely
  */
 
+import { existsSync, statSync } from 'node:fs';
+import { extname, isAbsolute, resolve } from 'node:path';
+
 /**
  * Validates that a config name is in the allowed list
  *
@@ -96,26 +99,75 @@ export function sanitizeArgs(args) {
 }
 
 /**
- * Validates that a path does not contain directory traversal attempts
+ * Validates config file paths with monorepo support
+ *
+ * Security approach: Defense in depth with multiple validation layers
+ * - Whitelist allowed file extensions
+ * - Limit parent directory traversal depth (monorepo support)
+ * - Reject absolute paths from CLI
+ * - Validate file existence
+ *
+ * Why we allow ".." (parent directory references):
+ * - Standard pattern in monorepos (TypeScript, ESLint, Prettier all allow it)
+ * - Developer controls the environment (config files are trusted code boundary)
+ * - No privilege escalation possible in CLI tool context
+ * - Multiple validation layers prevent abuse
  *
- * @param {string} path - The path to validate
- * @throws {Error} If path contains traversal patterns
- * @returns {string} The validated path
+ * @param {string} configPath - The config file path to validate (relative or absolute)
+ * @throws {Error} If validation fails (invalid extension, too deep, missing file, etc.)
+ * @returns {string} Absolute path to validated config file
  */
-export function validatePath(path) {
-  // Check for directory traversal patterns
-  if (path.includes('..')) {
+export function validateConfigPath(configPath) {
+  // 1. Whitelist config file extensions (defense in depth)
+  const allowedExtensions = ['.json', '.js', '.cjs', '.mjs', '.yaml', '.yml', '.toml'];
+  const ext = extname(configPath).toLowerCase();
+
+  if (!allowedExtensions.includes(ext)) {
+    throw new Error(
+      `Invalid config file extension: "${ext}"\n` +
+      `Allowed: ${allowedExtensions.join(', ')}\n` +
+      `This restriction prevents reading non-config files.`
+    );
+  }
+
+  // 2. Limit parent directory traversal depth (max 5 levels for monorepo support)
+  const upwardLevels = (configPath.match(/\.\.\//g) || []).length;
+  if (upwardLevels > 5) {
+    throw new Error(
+      `Too many parent directory references: ${upwardLevels}\n` +
+      `Maximum allowed: 5 levels (../../../../../../)\n` +
+      `This prevents accidental access to system directories.`
+    );
+  }
+
+  // 3. Reject absolute paths from CLI (could reference system files)
+  if (isAbsolute(configPath)) {
+    throw new Error(
+      `Absolute paths not allowed: "${configPath}"\n` +
+      `Use relative paths from your project directory.\n` +
+      `For monorepos, use parent references like ../../config.json`
+    );
+  }
+
+  // 4. Resolve to absolute path and validate file exists
+  const resolved = resolve(process.cwd(), configPath);
+
+  if (!existsSync(resolved)) {
     throw new Error(
-      `Path contains directory traversal pattern (..) which is not allowed: "${path}"`
+      `Config file not found: "${configPath}"\n` +
+      `Resolved to: ${resolved}\n` +
+      `Check that the file exists and the path is correct.`
     );
   }
 
-  // Check for absolute paths (we expect relative paths)
-  if (path.startsWith('/') || /^[a-zA-Z]:/.test(path)) {
+  // 5. Validate it's a file (not a directory or symlink to avoid confusion)
+  const stats = statSync(resolved);
+  if (!stats.isFile()) {
     throw new Error(
-      `Absolute paths are not allowed: "${path}"`
+      `Config path must be a file, not a directory: "${configPath}"\n` +
+      `Resolved to: ${resolved}`
     );
   }
 
-  return path;
+  return resolved;
 }

package/config/constants.js

@@ -13,8 +13,8 @@
  * Git configuration defaults
  */
 export const GIT_DEFAULTS = {
-  COMMIT_MESSAGE: 'release: bump v${version}',
-  HOTFIX_COMMIT_MESSAGE: 'hotfix: bump v${version}',
+  COMMIT_MESSAGE: 'chore(release): v${version}',
+  HOTFIX_COMMIT_MESSAGE: 'chore(hotfix): v${version}',
   TAG_NAME: 'v${version}',
   REQUIRE_BRANCH: 'main',
   REMOTE: 'origin',
@@ -22,7 +22,9 @@ export const GIT_DEFAULTS = {
 
 /**
  * Default git changelog command
- * Filters out commits matching release/hotfix/ci patterns
+ * Filters out commits matching release/hotfix/ci patterns, in both
+ * legacy form (`release: bump ...`) and Conventional Commits form
+ * (`chore(release): ...`, `chore(hotfix): ...`).
  */
 export const DEFAULT_CHANGELOG_COMMAND = [
   'git log',
@@ -36,6 +38,9 @@ export const DEFAULT_CHANGELOG_COMMAND = [
   '--grep="^Hotfix"',
   '--grep="^ci"',
   '--grep="^CI"',
+  '--grep="^chore(release)"',
+  '--grep="^chore(hotfix)"',
+  '--grep="^chore(ci)"',
   '--invert-grep',
 ].join(' ');
 

package/dist/scripts/check-config.js

@@ -15,6 +15,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { getGitHubRepoUrl } from './lib/git-utils.js';
+import { runScript } from './lib/run-script.js';
 export function safeExec(command, deps) {
     try {
         return deps.execSync(command, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
@@ -256,7 +257,7 @@ export function displayNpmStatus(deps, npmUsername) {
  */
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    async function main() {
+    void runScript({ error: console.error, exit: process.exit }, async () => {
         console.log('🔍 Checking release configuration and project status...');
         const deps = {
             execSync,
@@ -276,10 +277,6 @@ if (import.meta.url === `file://${process.argv[1]}`) {
         console.log('\n✨ Check complete!');
         console.log('\nTo validate release readiness, run:');
         console.log('  pnpm release-it-preset validate\n');
-    }
-    main().catch((error) => {
-        console.error('❌ Check failed:', error);
-        process.exit(1);
     });
 }
 /* c8 ignore end */

package/dist/scripts/check-pr-status.js

@@ -13,6 +13,7 @@
 import { execSync } from 'node:child_process';
 import { appendFileSync } from 'node:fs';
 import { STRICT_CONVENTIONAL_COMMIT_REGEX } from './lib/commit-parser.js';
+import { runScript } from './lib/run-script.js';
 const SKIP_CHANGELOG_REGEX = /\[skip-changelog]/i;
 export function safeExec(command, deps) {
     try {
@@ -155,10 +156,12 @@ export function renderSummary(result, deps) {
 }
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    const deps = createDefaultDeps();
-    const args = parseArgs(process.argv.slice(2));
-    const result = runPrCheck(args, deps);
-    writeOutputs(result, deps);
-    renderSummary(result, deps);
+    void runScript({ error: console.error, exit: process.exit }, () => {
+        const deps = createDefaultDeps();
+        const args = parseArgs(process.argv.slice(2));
+        const result = runPrCheck(args, deps);
+        writeOutputs(result, deps);
+        renderSummary(result, deps);
+    });
 }
 /* c8 ignore end */

package/dist/scripts/extract-changelog.js

@@ -18,6 +18,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { validateAndNormalizeSemver } from './lib/semver-utils.js';
 import { escapeRegExp } from './lib/string-utils.js';
+import { runScript } from './lib/run-script.js';
 export function extractChangelog(version, deps) {
     // Validate semver format
     const normalizedVersion = validateAndNormalizeSemver(version);
@@ -45,22 +46,19 @@ export function extractChangelog(version, deps) {
  */
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    const version = process.argv[2];
-    if (!version) {
-        console.error('Usage: tsx scripts/extract-changelog.ts <version>');
-        process.exit(1);
-    }
-    try {
+    void runScript({ error: console.error, exit: process.exit }, () => {
+        const version = process.argv[2];
+        if (!version) {
+            console.error('Usage: tsx scripts/extract-changelog.ts <version>');
+            process.exit(1);
+            return;
+        }
         const result = extractChangelog(version, {
             readFileSync,
             getEnv: (key) => process.env[key],
             getCwd: () => process.cwd(),
         });
         console.log(result);
-    }
-    catch (error) {
-        console.error(`❌ ${error instanceof Error ? error.message : error}`);
-        process.exit(1);
-    }
+    });
 }
 /* c8 ignore end */

package/dist/scripts/init-project.js

@@ -15,6 +15,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { createInterface } from 'node:readline';
+import { runScript } from './lib/run-script.js';
 const CHANGELOG_TEMPLATE = `# Changelog
 
 All notable changes to this project will be documented in this file.
@@ -163,29 +164,28 @@ export async function initProject(options, deps) {
  */
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    async function realPrompt(question) {
-        const rl = createInterface({
-            input: process.stdin,
-            output: process.stdout,
-        });
-        return new Promise((resolve) => {
-            rl.question(`${question} (y/N): `, (answer) => {
-                rl.close();
-                resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+    void runScript({ error: console.error, exit: process.exit }, async () => {
+        async function realPrompt(question) {
+            const rl = createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            return new Promise((resolve) => {
+                rl.question(`${question} (y/N): `, (answer) => {
+                    rl.close();
+                    resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+                });
             });
+        }
+        const options = parseArgs();
+        await initProject(options, {
+            existsSync,
+            readFileSync,
+            writeFileSync,
+            prompt: realPrompt,
+            log: console.log,
+            warn: console.warn,
         });
-    }
-    const options = parseArgs();
-    initProject(options, {
-        existsSync,
-        readFileSync,
-        writeFileSync,
-        prompt: realPrompt,
-        log: console.log,
-        warn: console.warn,
-    }).catch((error) => {
-        console.error('❌ Initialization failed:', error);
-        process.exit(1);
     });
 }
 /* c8 ignore end */

package/dist/scripts/lib/errors.js

@@ -0,0 +1,45 @@
+/**
+ * Typed error hierarchy for script-level failures.
+ *
+ * Each subclass maps to a specific CLI exit code so that callers and
+ * the `runScript()` wrapper can surface the right exit code without
+ * inspecting raw strings.
+ *
+ * Usage:
+ *   throw new ValidationError('CHANGELOG.md not found')
+ *   // → exits with code 2
+ *
+ *   throw new GitError('git tag not found')
+ *   // → exits with code 1
+ */
+/**
+ * Base class for all script-level errors that map to a CLI exit code.
+ * Throw a subclass to signal a specific failure mode; uncaught throws
+ * fall through to exit code 1 via runScript().
+ */
+export class ScriptError extends Error {
+    exitCode;
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = this.constructor.name;
+        this.exitCode = options?.exitCode ?? 1;
+    }
+}
+/** Pre-flight or input-validation failure (e.g. missing CHANGELOG, wrong branch, dirty tree). Exit 2. */
+export class ValidationError extends ScriptError {
+    constructor(message, options) {
+        super(message, { exitCode: 2, cause: options?.cause });
+    }
+}
+/** Git operation failure (tag not found, command non-zero, parse error on git output). Exit 1. */
+export class GitError extends ScriptError {
+    constructor(message, options) {
+        super(message, { exitCode: 1, cause: options?.cause });
+    }
+}
+/** Changelog parse/write failure (malformed file, missing [Unreleased], etc.). Exit 1. */
+export class ChangelogError extends ScriptError {
+    constructor(message, options) {
+        super(message, { exitCode: 1, cause: options?.cause });
+    }
+}

package/dist/scripts/lib/run-script.js

@@ -0,0 +1,28 @@
+import { ScriptError } from './errors.js';
+/**
+ * Wraps a script's main function with consistent error handling and
+ * exit-code mapping. ScriptError subclasses exit with their specific
+ * exitCode; any other thrown value exits 1 with a generic message.
+ *
+ * The function may be sync or async. Returns a promise that resolves
+ * before exit() is called for the failure path; on success the promise
+ * simply resolves (exit() is not invoked — caller can let process end
+ * naturally with code 0).
+ */
+export async function runScript(deps, fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        if (err instanceof ScriptError) {
+            deps.error(`❌ ${err.message}`);
+            deps.exit(err.exitCode);
+        }
+        if (err instanceof Error) {
+            deps.error(`❌ Unexpected error: ${err.message}`);
+            deps.exit(1);
+        }
+        deps.error(`❌ Unknown error: ${String(err)}`);
+        deps.exit(1);
+    }
+}

package/dist/scripts/populate-unreleased-changelog.js

@@ -21,6 +21,7 @@ import { execSync } from 'node:child_process';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { getGitHubRepoUrl } from './lib/git-utils.js';
 import { CONVENTIONAL_COMMIT_REGEX } from './lib/commit-parser.js';
+import { runScript } from './lib/run-script.js';
 /**
  * Extract all conventional commit patterns from a commit body
  */
@@ -98,7 +99,14 @@ export function parseCommitsWithMultiplePrefixes(gitOutput, repoUrl) {
                 const firstLine = body.split('\n')[0].trim();
                 if (firstLine) {
                     const lowerFirstLine = firstLine.toLowerCase();
-                    const ignoredPatterns = [/^release\b/, /^hotfix\b/, /^ci\b/];
+                    const ignoredPatterns = [
+                        /^release\b/,
+                        /^hotfix\b/,
+                        /^ci\b/,
+                        /^chore\(release\)/i,
+                        /^chore\(hotfix\)/i,
+                        /^chore\(ci\)/i,
+                    ];
                     const shouldSkip = ignoredPatterns.some((pattern) => pattern.test(lowerFirstLine));
                     if (shouldSkip) {
                         continue;
@@ -223,20 +231,14 @@ export function populateChangelog(deps) {
  */
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    try {
-        populateChangelog({
-            execSync,
-            readFileSync,
-            writeFileSync,
-            getEnv: (key) => process.env[key],
-            log: console.log,
-            warn: console.warn,
-            error: console.error,
-        });
-    }
-    catch (error) {
-        console.error('❌ Failed to populate [Unreleased] section:', error);
-        process.exit(1);
-    }
+    void runScript({ error: console.error, exit: process.exit }, () => populateChangelog({
+        execSync,
+        readFileSync,
+        writeFileSync,
+        getEnv: (key) => process.env[key],
+        log: console.log,
+        warn: console.warn,
+        error: console.error,
+    }));
 }
 /* c8 ignore end */

package/dist/scripts/republish-changelog.js

@@ -24,6 +24,7 @@ import { execSync } from 'node:child_process';
 import { getGitHubRepoUrl } from './lib/git-utils.js';
 import { escapeRegExp } from './lib/string-utils.js';
 import { validateAndNormalizeSemver } from './lib/semver-utils.js';
+import { runScript } from './lib/run-script.js';
 export function updateReferenceLinks(changelog, versionLabels, linkTarget, unreleasedLine) {
     const lines = changelog.split(/\r?\n/);
     const updatedLines = [];
@@ -162,26 +163,19 @@ export function republishChangelog(version, deps) {
  */
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    async function main() {
-        try {
-            const pkg = await import(join(process.cwd(), 'package.json'), { with: { type: 'json' } });
-            const version = pkg.default.version;
-            republishChangelog(version, {
-                execSync,
-                readFileSync,
-                writeFileSync,
-                getEnv: (key) => process.env[key],
-                getCwd: () => process.cwd(),
-                getDate: () => new Date().toISOString().split('T')[0],
-                log: console.log,
-                warn: console.warn,
-            });
-        }
-        catch (error) {
-            console.error(`❌ ${error instanceof Error ? error.message : error}`);
-            process.exit(1);
-        }
-    }
-    main();
+    void runScript({ error: console.error, exit: process.exit }, async () => {
+        const pkg = await import(join(process.cwd(), 'package.json'), { with: { type: 'json' } });
+        const version = pkg.default.version;
+        republishChangelog(version, {
+            execSync,
+            readFileSync,
+            writeFileSync,
+            getEnv: (key) => process.env[key],
+            getCwd: () => process.cwd(),
+            getDate: () => new Date().toISOString().split('T')[0],
+            log: console.log,
+            warn: console.warn,
+        });
+    });
 }
 /* c8 ignore end */

package/dist/scripts/retry-publish.js

@@ -17,6 +17,7 @@
  */
 import { execSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
+import { runScript } from './lib/run-script.js';
 export function retryPublish(deps) {
     deps.log('🔄 Starting retry publish process...');
     const currentBranch = deps.execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
@@ -82,17 +83,13 @@ export function retryPublish(deps) {
  */
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    try {
+    void runScript({ error: console.error, exit: process.exit }, () => {
         retryPublish({
             execSync,
             readFileSync,
             log: console.log,
             warn: console.warn,
         });
-    }
-    catch (error) {
-        console.error(`❌ Pre-flight checks failed: ${error instanceof Error ? error.message : error}`);
-        process.exit(1);
-    }
+    });
 }
 /* c8 ignore end */

package/dist/scripts/validate-release.js

@@ -18,6 +18,8 @@
  */
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
+import { ValidationError } from './lib/errors.js';
+import { runScript } from './lib/run-script.js';
 export function parseArgs(argv) {
     return {
         allowDirty: argv.includes('--allow-dirty'),
@@ -248,7 +250,7 @@ export function validateRelease(deps, options) {
  */
 /* c8 ignore start */
 if (import.meta.url === `file://${process.argv[1]}`) {
-    async function main() {
+    void runScript({ error: console.error, exit: process.exit }, async () => {
         const options = parseArgs(process.argv.slice(2));
         console.log('🔍 Validating release readiness...\n');
         const deps = {
@@ -273,16 +275,10 @@ if (import.meta.url === `file://${process.argv[1]}`) {
         console.log();
         if (allPassed) {
             console.log('✨ All validations passed! Ready to release.');
-            process.exit(0);
         }
         else {
-            console.log('❌ Some validations failed. Please fix the issues above before releasing.');
-            process.exit(1);
+            throw new ValidationError('Some validations failed. Please fix the issues above before releasing.');
         }
-    }
-    main().catch((error) => {
-        console.error('❌ Validation failed:', error);
-        process.exit(1);
     });
 }
 /* c8 ignore end */

package/dist/types/lib/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Typed error hierarchy for script-level failures.
+ *
+ * Each subclass maps to a specific CLI exit code so that callers and
+ * the `runScript()` wrapper can surface the right exit code without
+ * inspecting raw strings.
+ *
+ * Usage:
+ *   throw new ValidationError('CHANGELOG.md not found')
+ *   // → exits with code 2
+ *
+ *   throw new GitError('git tag not found')
+ *   // → exits with code 1
+ */
+/**
+ * Base class for all script-level errors that map to a CLI exit code.
+ * Throw a subclass to signal a specific failure mode; uncaught throws
+ * fall through to exit code 1 via runScript().
+ */
+export declare class ScriptError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, options?: {
+        exitCode?: number;
+        cause?: unknown;
+    });
+}
+/** Pre-flight or input-validation failure (e.g. missing CHANGELOG, wrong branch, dirty tree). Exit 2. */
+export declare class ValidationError extends ScriptError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Git operation failure (tag not found, command non-zero, parse error on git output). Exit 1. */
+export declare class GitError extends ScriptError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Changelog parse/write failure (malformed file, missing [Unreleased], etc.). Exit 1. */
+export declare class ChangelogError extends ScriptError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/types/lib/run-script.d.ts

@@ -0,0 +1,15 @@
+export interface RunScriptDeps {
+    error: (msg: string) => void;
+    exit: (code: number) => never;
+}
+/**
+ * Wraps a script's main function with consistent error handling and
+ * exit-code mapping. ScriptError subclasses exit with their specific
+ * exitCode; any other thrown value exits 1 with a generic message.
+ *
+ * The function may be sync or async. Returns a promise that resolves
+ * before exit() is called for the failure path; on success the promise
+ * simply resolves (exit() is not invoked — caller can let process end
+ * naturally with code 0).
+ */
+export declare function runScript(deps: RunScriptDeps, fn: () => void | Promise<void>): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oorabona/release-it-preset",
-  "version": "0.8.1",
+  "version": "0.10.1",
   "description": "Shared release-it configuration and scripts for the organisation",
   "type": "module",
   "keywords": [
@@ -69,23 +69,25 @@
     "test:unit": "vitest run tests/unit/*.test.ts",
     "test:unit:watch": "vitest tests/unit/*.test.ts",
     "test:unit:coverage": "vitest run tests/unit/*.test.ts --coverage",
+    "test:e2e": "vitest run tests/e2e/*.test.ts --testTimeout=30000",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
     "prepublishOnly": "pnpm build && echo 'Running prepublish checks...' && test -f README.md && test -f LICENSE"
   },
   "peerDependencies": {
-    "release-it": "^19.0.0"
+    "release-it": "^20.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.2.5",
-    "@types/node": "^24.6.2",
-    "@vitest/coverage-v8": "^3.2.4",
-    "nano-staged": "^0.8.0",
-    "rimraf": "^6.0.1",
-    "tsx": "^4.20.6",
-    "typescript": "^5.7.3",
-    "vitest": "^3.2.4"
+    "@biomejs/biome": "^2.4.13",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "nano-staged": "^1.0.2",
+    "release-it": "^20.0.1",
+    "rimraf": "^6.1.3",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=18.0.0"