@oorabona/release-it-preset 0.7.0 → 0.8.1

package/README.md

@@ -562,56 +562,143 @@ 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 two configuration modes:
+
+### Mode 1: Direct Preset Usage (No Config File)
+
+**When to use:** Simple projects, trust preset defaults, or customize only via environment variables
+
+Don't create `.release-it.json`. Just run the CLI:
+
+```bash
+pnpm release-it-preset default
+```
+
+All configuration comes from the preset and environment variables.
+
+**Pros:**
+- ✅ Zero config files
+- ✅ Consistent behavior across projects
+- ✅ Easy to understand
+- ✅ Perfect for getting started
+
+---
+
+### Mode 2: Preset + User Overrides (Recommended)
+
+**When to use:** Customize specific options while keeping preset defaults
+
+Create `.release-it.json` **WITH 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}"
   }
 }
 ```
 
-### 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 default
+```
 
-- **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:**
+- The `extends` field loads the preset
+- release-it merges your overrides on top via c12
+- **Your values take precedence** over preset defaults
+- CLI validates that `extends` matches the command
 
-- **Without `.release-it.json`:**
-  - The CLI runs `release-it --config <preset-path>`
-  - Uses preset configuration directly
-  - Works exactly as before
+**Pros:**
+- ✅ **Recommended for customization**
+- ✅ Declarative config with explicit preset
+- ✅ Industry standard pattern (like ESLint, TypeScript)
+- ✅ Guaranteed config merging via release-it's c12
 
-**Example of customizing the default preset:**
+**Example:** Using `hotfix` preset but release from `master` instead of `main`:
 
 ```json
 {
-  "extends": "@oorabona/release-it-preset/config/default",
+  "extends": "@oorabona/release-it-preset/config/hotfix",
   "git": {
-    "tagName": "release-${version}",
-    "requireBranch": "develop"
+    "requireBranch": "master"
   }
 }
 ```
 
-Then run:
 ```bash
+pnpm release-it-preset hotfix
+```
+
+---
+
+### Configuration Validation
+
+The CLI validates your `.release-it.json` to prevent misconfigurations:
+
+#### Error 1: Missing `extends` field
+
+```bash
+# .release-it.json without extends:
+{
+  "git": { "requireBranch": "master" }
+}
+
+# Running:
 pnpm release-it-preset default
+
+# ❌ Configuration error!
+#    .release-it.json is missing the required "extends" field.
+#
+#    Without "extends", your config won't merge with the preset.
+#    This means you'll get release-it defaults instead of preset defaults.
+#
+#    Fix by adding this to .release-it.json:
+#      {
+#        "extends": "@oorabona/release-it-preset/config/default",
+#        ...your overrides
+#      }
 ```
 
-The CLI will use your customized settings instead of the preset defaults!
+**Why `extends` is required:** Without it, release-it only loads your config file and uses release-it's own defaults. The preset is never loaded, so you lose important defaults like `npm.publish: false`.
+
+#### Error 2: Preset mismatch
+
+```bash
+# .release-it.json extends "default":
+{
+  "extends": "@oorabona/release-it-preset/config/default"
+}
+
+# But you run:
+pnpm release-it-preset hotfix
+
+# ❌ Configuration mismatch error!
+#    CLI preset:               hotfix
+#    .release-it.json extends: default
+#
+#    Either:
+#      1. Run: release-it-preset default
+#      2. Update .release-it.json extends to: "@oorabona/release-it-preset/config/hotfix"
+```
+
+---
+
+### Which Mode Should I Use?
+
+| Scenario | Recommended Mode |
+|----------|------------------|
+| Quick start, minimal config | **Mode 1** (No config file) |
+| Customize branch/commit/hooks | **Mode 2** (Config with extends) |
+| Environment-only customization | **Mode 1** (Use env vars) |
+| Monorepo with per-package config | **Mode 2** (Each package has own config) |
+
+**Use Mode 1 to get started, switch to Mode 2 when you need customization.**
 
 ## 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,71 @@ 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) {
+        // ERROR: extends is required for config merging
+        console.error(`\n❌ Configuration error!`);
+        console.error(`   .release-it.json is missing the required "extends" field.`);
+        console.error(``);
+        console.error(`Without "extends", your config won't merge with the preset.`);
+        console.error(`This means you'll get release-it defaults instead of preset defaults.`);
+        console.error(``);
+        console.error(`Fix by adding this to .release-it.json:`);
+        console.error(`  {`);
+        console.error(`    "extends": "${expectedExtends}",`);
+        console.error(`    ...your overrides`);
+        console.error(`  }`);
+        console.error(``);
+        console.error(`Or remove .release-it.json to use the preset directly.\n`);
+        process.exit(1);
+      }
+
+      // Validate extends matches 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. Run: release-it-preset ${extendsPreset}`);
+        console.error(`     → Use the preset specified in your config file`);
+        console.error(``);
+        console.error(`  2. Update .release-it.json extends to: "${expectedExtends}"`);
+        console.error(`     → Match your config file to the CLI command\n`);
+        process.exit(1);
+      }
+
+      console.log(`✅ Config validated: preset "${configName}"`);
+      console.log(`📝 Using: ${userConfigPath}\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 discover .release-it.json and merge via extends
     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 with "extends" to customize\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.1",
   "description": "Shared release-it configuration and scripts for the organisation",
   "type": "module",
   "keywords": [