@oorabona/release-it-preset 0.8.1 → 0.9.0

package/README.md

@@ -16,6 +16,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 +42,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 +339,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 +391,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/package.json

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