@oorabona/release-it-preset 0.7.0 → 0.8.0

package/README.md

@@ -562,56 +562,153 @@ GIT_REQUIRE_CLEAN="true" \
 pnpm release
 ```
 
-## Configuration Override
+## Configuration Modes
 
-You can override any configuration in your project's `.release-it.json`:
+The preset supports three configuration modes to suit different workflows:
+
+### Mode 1: CLI Only (No Config File)
+
+**When to use:** Simple projects with minimal customization needs
+
+Don't create `.release-it.json`. Just run the CLI:
+
+```bash
+pnpm release-it-preset hotfix
+```
+
+All configuration comes from the preset and environment variables.
+
+**Pros:**
+- ✅ Zero config files
+- ✅ Consistent behavior across projects
+- ✅ Easy to understand
+
+---
+
+### Mode 2: CLI + User Overrides (Recommended)
+
+**When to use:** Customize specific options while using CLI presets
+
+Create `.release-it.json` **WITHOUT the `extends` field**:
 
 ```json
 {
-  "extends": "@oorabona/release-it-preset/config/default",
   "git": {
-    "requireBranch": "develop",
+    "requireBranch": "master",
     "commitMessage": "chore: release v${version}"
   },
-  "github": {
-    "releaseName": "Release ${version}"
+  "npm": {
+    "publish": true
   }
 }
 ```
 
-### CLI Behavior with User Configuration
+Run with CLI preset:
 
-**Important:** The CLI now intelligently detects and respects your `.release-it.json` file:
+```bash
+pnpm release-it-preset hotfix
+```
 
-- **With `.release-it.json` present:**
-  - The CLI runs `release-it` without `--config` flag
-  - release-it naturally merges your config with the preset via the `extends` field
-  - **Your settings have priority** over preset defaults
-  - Perfect for customizing tag names, commit messages, branch requirements, etc.
+**How it works:**
+- CLI selects the preset (`hotfix` in this example)
+- release-it merges your overrides on top of the preset
+- **Your values take precedence** over preset defaults
 
-- **Without `.release-it.json`:**
-  - The CLI runs `release-it --config <preset-path>`
-  - Uses preset configuration directly
-  - Works exactly as before
+**Pros:**
+- ✅ **Recommended approach** for most use cases
+- ✅ CLI controls preset selection
+- ✅ Declarative overrides in config file
+- ✅ No `extends` maintenance needed
 
-**Example of customizing the default preset:**
+**Example use case:** You want to use the `hotfix` preset but require releases from `master` instead of `main`:
 
 ```json
 {
-  "extends": "@oorabona/release-it-preset/config/default",
   "git": {
-    "tagName": "release-${version}",
-    "requireBranch": "develop"
+    "requireBranch": "master"
   }
 }
 ```
 
-Then run:
 ```bash
-pnpm release-it-preset default
+pnpm release-it-preset hotfix  # Uses hotfix preset + your branch override
+```
+
+---
+
+### Mode 3: File with Extends (Advanced)
+
+**When to use:** Lock a specific preset regardless of CLI command
+
+Create `.release-it.json` **WITH the `extends` field**:
+
+```json
+{
+  "extends": "@oorabona/release-it-preset/config/hotfix",
+  "git": {
+    "commitMessage": "custom: ${version}"
+  }
+}
+```
+
+Run matching CLI command:
+
+```bash
+pnpm release-it-preset hotfix  # Must match the extends!
+```
+
+**How it works:**
+- The `extends` field locks the preset
+- CLI command **must match** the preset in `extends`
+- Mismatch triggers an error
+
+**Pros:**
+- ✅ Prevents accidental use of wrong presets
+- ✅ Explicit preset declaration in config
+
+**Cons:**
+- ⚠️ Less flexible (preset locked in file)
+- ⚠️ Requires updating `extends` to switch presets
+
+---
+
+### Configuration Error Handling
+
+If your `.release-it.json` has an `extends` field that doesn't match the CLI command, you'll get a clear error:
+
+```bash
+# Your config extends "default", but you run:
+pnpm release-it-preset hotfix
+
+# ❌ Configuration mismatch error!
+#    CLI preset:               hotfix
+#    .release-it.json extends: default
+#
+# Either:
+#   1. Remove the "extends" field from .release-it.json (recommended)
+#      → Your overrides will merge with the CLI preset automatically
+#
+#   2. Run: release-it-preset default
+#      → Use the preset specified in your config file
+#
+#   3. Update .release-it.json extends to: "@oorabona/release-it-preset/config/hotfix"
+#      → Match your config file to the CLI command
 ```
 
-The CLI will use your customized settings instead of the preset defaults!
+This prevents silent misconfigurations where the wrong preset runs unexpectedly.
+
+---
+
+### Which Mode Should I Use?
+
+| Scenario | Recommended Mode |
+|----------|------------------|
+| Minimal config, trust defaults | **Mode 1** (CLI only) |
+| Customize branch/commit messages | **Mode 2** (CLI + overrides) |
+| Lock preset for safety | **Mode 3** (File with extends) |
+| Monorepo with different presets per package | **Mode 2** (CLI + overrides) |
+
+**Most users should use Mode 2** for the best balance of flexibility and clarity.
 
 ## Borrowing Scripts & Workflows
 

package/bin/cli.js

@@ -24,7 +24,7 @@
  */
 
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { validateConfigName, validateUtilityCommand, sanitizeArgs } from './validators.js';
@@ -110,25 +110,63 @@ function handleReleaseCommand(configName, args) {
 
   const releaseItCommand = 'release-it';
   let fullArgs;
-  let strategyMessage;
 
   if (hasUserConfig) {
-    // User has .release-it.json - let release-it handle the merge naturally
-    // The user config should have "extends": "@oorabona/release-it-preset/config/<preset>"
+    // Read and validate user config
+    try {
+      const userConfigContent = readFileSync(userConfigPath, 'utf8');
+      const userConfig = JSON.parse(userConfigContent);
+
+      const expectedExtends = `@oorabona/release-it-preset/config/${configName}`;
+
+      if (userConfig.extends) {
+        // If extends exists, it MUST match the CLI preset
+        const extendsMatch = userConfig.extends.match(/@oorabona\/release-it-preset\/config\/(\w+)/);
+        const extendsPreset = extendsMatch?.[1];
+
+        if (extendsPreset && extendsPreset !== configName) {
+          console.error(`\n❌ Configuration mismatch error!`);
+          console.error(`   CLI preset:               ${configName}`);
+          console.error(`   .release-it.json extends: ${extendsPreset}`);
+          console.error(``);
+          console.error(`Either:`);
+          console.error(`  1. Remove the "extends" field from .release-it.json (recommended)`);
+          console.error(`     → Your overrides will merge with the CLI preset automatically`);
+          console.error(``);
+          console.error(`  2. Run: release-it-preset ${extendsPreset}`);
+          console.error(`     → Use the preset specified in your config file`);
+          console.error(``);
+          console.error(`  3. Update .release-it.json extends to: "${expectedExtends}"`);
+          console.error(`     → Match your config file to the CLI command\n`);
+          process.exit(1);
+        }
+
+        console.log(`✅ Config file extends matches CLI preset: ${configName}`);
+        console.log(`📝 Using: ${userConfigPath}\n`);
+      } else {
+        // No extends = natural merge (Mode 3 - Hybrid)
+        console.log(`📝 Merging CLI preset "${configName}" with user config overrides`);
+        console.log(`   Config file: ${userConfigPath}`);
+        console.log(`   User overrides will take precedence\n`);
+      }
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        console.error(`❌ Failed to parse .release-it.json: ${error.message}`);
+      } else {
+        console.error(`❌ Error reading .release-it.json: ${error.message}`);
+      }
+      process.exit(1);
+    }
+
+    // Let release-it handle the merge naturally
     fullArgs = [...args];
-    strategyMessage = `📝 Using user config: ${userConfigPath}\n   (should extend preset: ${configName})`;
-    console.log(strategyMessage);
-    console.log(`ℹ️  Ensure your .release-it.json contains: "extends": "@oorabona/release-it-preset/config/${configName}"`);
   } else {
     // No user config - use preset directly
+    console.log(`📝 Using preset config directly: ${configPath}`);
+    console.log(`   Tip: Create .release-it.json (without "extends") to add overrides\n`);
     fullArgs = ['--config', configPath, ...args];
-    strategyMessage = `📝 Using preset config directly: ${configPath}`;
-    console.log(strategyMessage);
-    console.log(`ℹ️  Tip: Create .release-it.json with "extends" to customize the preset`);
   }
 
-  console.log(`💡 Command: ${releaseItCommand} ${fullArgs.join(' ')}\n`);
-
   const child = spawn(releaseItCommand, fullArgs, {
     stdio: 'inherit',
     shell: false, // Security: disable shell to prevent command injection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oorabona/release-it-preset",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Shared release-it configuration and scripts for the organisation",
   "type": "module",
   "keywords": [