@oorabona/release-it-preset 0.3.0

package/bin/cli.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * CLI wrapper for release-it-preset
+ *
+ * Provides two types of commands:
+ * 1. Release commands - Run release-it with specific configurations
+ * 2. Utility commands - Helper commands for project setup and validation
+ *
+ * Usage:
+ *   release-it-preset <command> [...args]
+ *
+ * Release commands:
+ *   release-it-preset default
+ *   release-it-preset hotfix
+ *   release-it-preset changelog-only
+ *
+ * Utility commands:
+ *   release-it-preset init [--yes]
+ *   release-it-preset update
+ *   release-it-preset validate [--allow-dirty]
+ *   release-it-preset check
+ */
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const RELEASE_CONFIGS = {
+  default: 'config/default.js',
+  hotfix: 'config/hotfix.js',
+  'changelog-only': 'config/changelog-only.js',
+  'manual-changelog': 'config/manual-changelog.js',
+  'no-changelog': 'config/no-changelog.js',
+  republish: 'config/republish.js',
+  'retry-publish': 'config/retry-publish.js',
+};
+
+// Map base names (without extension) for utility scripts
+const UTILITY_COMMANDS = {
+  init: 'init-project',
+  update: 'populate-unreleased-changelog',
+  validate: 'validate-release',
+  check: 'check-config',
+};
+
+function showHelp() {
+  console.log(`
+Usage: release-it-preset <command> [...args]
+
+Release Commands:
+  default          Full release with changelog, git, GitHub, and npm
+  hotfix           Emergency hotfix with auto-changelog from commits
+  changelog-only   Update changelog only, no release
+  manual-changelog Release with manually edited changelog (skip auto-generation)
+  no-changelog     Release without changelog updates
+  republish        Republish existing version (moves git tag)
+  retry-publish    Retry failed npm/GitHub publish
+
+Utility Commands:
+  init [--yes]           Initialize project (create CHANGELOG.md, .release-it.json, etc.)
+  update                 Update [Unreleased] section from commits
+  validate [--allow-dirty]  Validate project is ready for release
+  check                  Display configuration and project status
+
+Examples:
+  # Release commands
+  release-it-preset default --dry-run
+  release-it-preset hotfix --verbose
+  release-it-preset changelog-only --ci
+
+  # Utility commands
+  release-it-preset init
+  release-it-preset update
+  release-it-preset validate
+  release-it-preset check
+
+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
+`);
+}
+
+function handleReleaseCommand(configName, args) {
+  const configPath = join(__dirname, '..', RELEASE_CONFIGS[configName]);
+
+  console.log(`🚀 Running release-it with config: ${configName}`);
+  console.log(`📝 Config file: ${configPath}`);
+
+  const releaseItCommand = 'release-it';
+  const fullArgs = ['--config', configPath, ...args];
+
+  console.log(`💡 Command: ${releaseItCommand} ${fullArgs.join(' ')}\n`);
+
+  const child = spawn(releaseItCommand, fullArgs, {
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  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 handleUtilityCommand(commandName, args) {
+  const base = UTILITY_COMMANDS[commandName];
+  const compiledPath = join(__dirname, '..', 'dist', 'scripts', `${base}.js`);
+  const sourcePath = join(__dirname, '..', 'scripts', `${base}.ts`);
+
+  console.log(`🔧 Running utility command: ${commandName}\n`);
+
+  // Prefer compiled script; fallback to tsx source if not built yet (developer convenience)
+  import('node:fs').then(fs => {
+    const useCompiled = fs.existsSync(compiledPath);
+    const runner = useCompiled ? 'node' : 'tsx';
+    const target = useCompiled ? compiledPath : sourcePath;
+    if (!useCompiled) {
+      console.log('ℹ️  Compiled script not found, falling back to tsx source execution (dev mode).');
+    }
+
+    const child = spawn(runner, [target, ...args], {
+      stdio: 'inherit',
+      shell: true,
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Failed to run command: ${error.message}`);
+      if (!useCompiled) {
+        console.error(`\nMake sure tsx is installed for source execution:`);
+        console.error(`  pnpm add -D tsx`);
+      }
+      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') {
+    showHelp();
+    process.exit(0);
+  }
+
+  const command = args[0];
+  const commandArgs = args.slice(1);
+
+  // Check if it's a release config
+  if (RELEASE_CONFIGS[command]) {
+    handleReleaseCommand(command, commandArgs);
+    return;
+  }
+
+  // Check if it's a utility command
+  if (UTILITY_COMMANDS[command]) {
+    handleUtilityCommand(command, commandArgs);
+    return;
+  }
+
+  // Unknown command
+  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(`\nRun 'release-it-preset --help' for more information.`);
+  process.exit(1);
+}
+
+main();

package/bin/run-script.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/* c8 ignore file */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function quote(value) {
+  return `"${value.replace(/["\\]/g, '\\$&')}"`;
+}
+
+function resolveTsxCommand() {
+  const localTsx = join(__dirname, '..', 'node_modules', '.bin', 'tsx');
+  if (existsSync(localTsx)) {
+    return localTsx;
+  }
+  return 'tsx';
+}
+
+function runWithNode(target, args) {
+  const result = spawnSync(process.execPath, [target, ...args], { stdio: 'inherit' });
+  if (result.error) {
+    console.error(`❌ Failed to execute ${target}: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
+}
+
+function runWithTsx(tsxCommand, sourcePath, args) {
+  const command = [`${quote(tsxCommand)} ${quote(sourcePath)}`]
+    .concat(args.map(arg => quote(arg)))
+    .join(' ');
+
+  const result = spawnSync(command, { stdio: 'inherit', shell: true });
+  if (result.error) {
+    console.error(`❌ Failed to execute tsx: ${result.error.message}`);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
+}
+
+const [scriptName, ...scriptArgs] = process.argv.slice(2);
+
+if (!scriptName) {
+  console.error('❌ Missing script name. Usage: node run-script.js <script-name> [...args]');
+  process.exit(1);
+}
+
+const compiledPath = join(__dirname, '..', 'dist', 'scripts', `${scriptName}.js`);
+const sourcePath = join(__dirname, '..', 'scripts', `${scriptName}.ts`);
+
+if (existsSync(compiledPath)) {
+  runWithNode(compiledPath, scriptArgs);
+}
+
+console.log('ℹ️  Compiled script not found, falling back to tsx execution.');
+const tsxCommand = resolveTsxCommand();
+
+if (!tsxCommand) {
+  console.error('❌ Could not locate tsx. Run "pnpm install" or "pnpm build" and retry.');
+  process.exit(1);
+}
+
+if (!existsSync(sourcePath)) {
+  console.error(`❌ Source script not found: ${sourcePath}`);
+  process.exit(1);
+}
+
+runWithTsx(tsxCommand, sourcePath, scriptArgs);

package/config/changelog-only.js

@@ -0,0 +1,41 @@
+/**
+ * Changelog-only release-it configuration
+ *
+ * This configuration only generates/updates the changelog without:
+ * - Version increment
+ * - Git operations
+ * - npm publishing
+ * - GitHub releases
+ *
+ * Useful for preparing changelogs in CI or before actual release.
+ *
+ * Usage:
+ * ```bash
+ * pnpm release-it --config node_modules/@oorabona/release-it-preset/config/changelog-only.js --ci
+ * ```
+ */
+
+import { runScriptCommand } from './helpers.js';
+
+const config = {
+  increment: false,
+  git: {
+    changelog: false,
+    commit: false,
+    tag: false,
+    push: false,
+  },
+  hooks: {
+    'before:init': [
+      runScriptCommand('populate-unreleased-changelog'),
+    ],
+  },
+  npm: {
+    publish: false,
+  },
+  github: {
+    release: false,
+  },
+};
+
+export default config;

package/config/default.js

@@ -0,0 +1,54 @@
+/**
+ * Default release-it configuration
+ *
+ * This configuration provides a complete release workflow with:
+ * - Keep a Changelog format
+ * - Git commit, tag, and push
+ * - Optional GitHub releases (set GITHUB_RELEASE=true)
+ * - Optional npm publishing with provenance (set NPM_PUBLISH=true)
+ *
+ * Usage in client project:
+ * ```json
+ * {
+ *   "release-it": {
+ *     "extends": "@oorabona/release-it-preset/config/default"
+ *   }
+ * }
+ * ```
+ */
+
+import { createReleaseNotesGenerator, runScriptCommand } from './helpers.js';
+
+const config = {
+  git: {
+    commitMessage: process.env.GIT_COMMIT_MESSAGE || 'release: bump v${version}',
+    tagName: process.env.GIT_TAG_NAME || 'v${version}',
+    requireBranch: process.env.GIT_REQUIRE_BRANCH || 'main',
+    requireUpstream: process.env.GIT_REQUIRE_UPSTREAM === 'true',
+    requireCleanWorkingDir: process.env.GIT_REQUIRE_CLEAN === 'true',
+  },
+  hooks: {
+    'before:bump': [
+      runScriptCommand('populate-unreleased-changelog'),
+    ],
+    'after:bump': [
+      runScriptCommand('republish-changelog'),
+    ],
+  },
+  github: {
+    release: process.env.GITHUB_RELEASE === 'true',
+    releaseNotes: createReleaseNotesGenerator(),
+  },
+  npm: {
+    skipChecks: process.env.NPM_SKIP_CHECKS === 'true',
+    publish: process.env.NPM_PUBLISH === 'true',
+    versionArgs: ['--allow-same-version'],
+    publishArgs: [
+      '--provenance',
+      '--access',
+      process.env.NPM_ACCESS || 'public',
+    ],
+  },
+};
+
+export default config;

package/config/helpers.js

@@ -0,0 +1,52 @@
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const RUN_SCRIPT_PATH = join(__dirname, '..', 'bin', 'run-script.js');
+
+const DOUBLE_QUOTE = /["\\]/g;
+
+function quote(value) {
+  return `"${value.replace(DOUBLE_QUOTE, '\\$&')}"`;
+}
+
+function fallbackReleaseNotes(version) {
+  return `# Release v${version}\n\nNo changelog entry available.\n`;
+}
+
+export function runScriptCommand(scriptName, extraArgs = []) {
+  const args = [scriptName, ...extraArgs].map(quote).join(' ');
+  return `node ${quote(RUN_SCRIPT_PATH)} ${args}`.trim();
+}
+
+export function createReleaseNotesGenerator() {
+  return ({ version }) => {
+    const result = spawnSync(
+      process.execPath,
+      [RUN_SCRIPT_PATH, 'extract-changelog', version],
+      {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'inherit'],
+      },
+    );
+
+    if (result.error) {
+      console.warn(`⚠️  Failed to run extract-changelog script: ${result.error.message}`);
+      return fallbackReleaseNotes(version);
+    }
+
+    if (result.status !== 0) {
+      console.warn(
+        `⚠️  extract-changelog exited with code ${
+          typeof result.status === 'number' ? result.status : 'unknown'
+        }`,
+      );
+      return fallbackReleaseNotes(version);
+    }
+
+    const output = result.stdout?.trim();
+    return output ? `${output}\n` : fallbackReleaseNotes(version);
+  };
+}

package/config/hotfix.js

@@ -0,0 +1,51 @@
+/**
+ * Hotfix release-it configuration
+ *
+ * This configuration is for emergency hotfix releases:
+ * - Forces patch version increment
+ * - Generates changelog from git log
+ * - Populates unreleased section before bump
+ * - Optionally creates GitHub release with extracted notes (set GITHUB_RELEASE=true)
+ * - Optionally publishes to npm with provenance (set NPM_PUBLISH=true)
+ *
+ * Usage:
+ * ```bash
+ * pnpm release-it --config node_modules/@oorabona/release-it-preset/config/hotfix.js
+ * ```
+ */
+
+import { createReleaseNotesGenerator, runScriptCommand } from './helpers.js';
+
+const config = {
+  increment: process.env.HOTFIX_INCREMENT || 'patch',
+  git: {
+    changelog: 'git log --pretty=format:"- %s" ${latestTag}..HEAD',
+    commitMessage: process.env.GIT_COMMIT_MESSAGE || 'hotfix: bump v${version}',
+    tagName: process.env.GIT_TAG_NAME || 'v${version}',
+    requireBranch: process.env.GIT_REQUIRE_BRANCH || 'main',
+    requireUpstream: process.env.GIT_REQUIRE_UPSTREAM === 'true',
+    requireCleanWorkingDir: process.env.GIT_REQUIRE_CLEAN === 'true',
+  },
+  hooks: {
+    'before:bump': [
+      'echo "Creating hotfix release..."',
+      runScriptCommand('populate-unreleased-changelog'),
+    ],
+  },
+  github: {
+    release: process.env.GITHUB_RELEASE === 'true',
+    releaseNotes: createReleaseNotesGenerator(),
+  },
+  npm: {
+    skipChecks: process.env.NPM_SKIP_CHECKS === 'true',
+    publish: process.env.NPM_PUBLISH === 'true',
+    versionArgs: ['--allow-same-version'],
+    publishArgs: [
+      '--provenance',
+      '--access',
+      process.env.NPM_ACCESS || 'public',
+    ],
+  },
+};
+
+export default config;

package/config/manual-changelog.js

@@ -0,0 +1,64 @@
+/**
+ * Manual changelog release-it configuration
+ *
+ * This configuration is for releases where you have manually edited
+ * the [Unreleased] section in CHANGELOG.md:
+ * - Skips automatic changelog population (no before:bump hook)
+ * - Moves your manual [Unreleased] content to the version section (after:bump)
+ * - Creates git commit, tag, and push
+ * - Optionally creates GitHub release with your manual changelog (set GITHUB_RELEASE=true)
+ * - Optionally publishes to npm with provenance (set NPM_PUBLISH=true)
+ *
+ * Typical workflow:
+ * 1. Run `pnpm release-it-preset update` to generate initial changelog
+ * 2. Manually edit CHANGELOG.md [Unreleased] section
+ * 3. Run `pnpm release-it-preset manual-changelog` to release
+ *
+ * Usage:
+ * ```bash
+ * pnpm release-it-preset manual-changelog
+ * ```
+ *
+ * Or via extends in client project:
+ * ```json
+ * {
+ *   "release-it": {
+ *     "extends": "@oorabona/release-it-preset/config/manual-changelog"
+ *   }
+ * }
+ * ```
+ */
+
+import { createReleaseNotesGenerator, runScriptCommand } from './helpers.js';
+
+const config = {
+  git: {
+    commitMessage: process.env.GIT_COMMIT_MESSAGE || 'release: bump v${version}',
+    tagName: process.env.GIT_TAG_NAME || 'v${version}',
+    requireBranch: process.env.GIT_REQUIRE_BRANCH || 'main',
+    requireUpstream: process.env.GIT_REQUIRE_UPSTREAM === 'true',
+    requireCleanWorkingDir: process.env.GIT_REQUIRE_CLEAN === 'true',
+  },
+  hooks: {
+    // No before:bump - preserve manual changelog edits
+    'after:bump': [
+      runScriptCommand('republish-changelog'),
+    ],
+  },
+  github: {
+    release: process.env.GITHUB_RELEASE === 'true',
+    releaseNotes: createReleaseNotesGenerator(),
+  },
+  npm: {
+    skipChecks: process.env.NPM_SKIP_CHECKS === 'true',
+    publish: process.env.NPM_PUBLISH === 'true',
+    versionArgs: ['--allow-same-version'],
+    publishArgs: [
+      '--provenance',
+      '--access',
+      process.env.NPM_ACCESS || 'public',
+    ],
+  },
+};
+
+export default config;

package/config/no-changelog.js

@@ -0,0 +1,40 @@
+/**
+ * No-changelog release-it configuration
+ *
+ * This configuration disables changelog generation for quick releases:
+ * - Skips changelog updates
+ * - Still performs git operations
+ * - Optionally publishes to npm (set NPM_PUBLISH=true)
+ * - Optionally creates GitHub releases (set GITHUB_RELEASE=true)
+ *
+ * Usage:
+ * ```bash
+ * pnpm release-it --config node_modules/@oorabona/release-it-preset/config/no-changelog.js
+ * ```
+ */
+
+const config = {
+  git: {
+    changelog: false,
+    commitMessage: process.env.GIT_COMMIT_MESSAGE || 'release: bump v${version}',
+    tagName: process.env.GIT_TAG_NAME || 'v${version}',
+    requireBranch: process.env.GIT_REQUIRE_BRANCH || 'main',
+    requireUpstream: process.env.GIT_REQUIRE_UPSTREAM === 'true',
+    requireCleanWorkingDir: process.env.GIT_REQUIRE_CLEAN === 'true',
+  },
+  github: {
+    release: process.env.GITHUB_RELEASE === 'true',
+  },
+  npm: {
+    skipChecks: process.env.NPM_SKIP_CHECKS === 'true',
+    publish: process.env.NPM_PUBLISH === 'true',
+    versionArgs: ['--allow-same-version'],
+    publishArgs: [
+      '--provenance',
+      '--access',
+      process.env.NPM_ACCESS || 'public',
+    ],
+  },
+};
+
+export default config;

package/config/republish.js

@@ -0,0 +1,60 @@
+/**
+ * Republish release-it configuration
+ *
+ * DANGER: This configuration republishes the current version without incrementing.
+ * It moves the existing git tag, which breaks semantic versioning immutability.
+ *
+ * Only use this in exceptional cases when you need to:
+ * - Fix a broken release
+ * - Republish with corrected artifacts
+ *
+ * Publishing steps remain opt-in:
+ * - Set GITHUB_RELEASE=true to update the GitHub release
+ * - Set NPM_PUBLISH=true to republish to npm with provenance
+ *
+ * Usage:
+ * ```bash
+ * pnpm release-it --config node_modules/@oorabona/release-it-preset/config/republish.js
+ * ```
+ */
+
+import { createReleaseNotesGenerator, runScriptCommand } from './helpers.js';
+
+const config = {
+  increment: false,
+  git: {
+    commitMessage: process.env.GIT_COMMIT_MESSAGE || 'chore: republish v${version}',
+    tagName: process.env.GIT_TAG_NAME || 'v${version}',
+    tagAnnotation: 'Release ${version} (republished)',
+    requireBranch: process.env.GIT_REQUIRE_BRANCH || 'main',
+    requireUpstream: process.env.GIT_REQUIRE_UPSTREAM === 'true',
+    requireCleanWorkingDir: process.env.GIT_REQUIRE_CLEAN === 'true',
+  },
+  hooks: {
+    'before:init': [
+      'echo "⚠️  WARNING: You are about to MOVE an existing tag!"',
+      'echo "⚠️  This breaks semantic versioning immutability!"',
+      'echo "⚠️  Only proceed if you understand the consequences."',
+    ],
+    'before:bump': [
+      runScriptCommand('republish-changelog'),
+    ],
+  },
+  npm: {
+    skipChecks: process.env.NPM_SKIP_CHECKS === 'true',
+      publish: process.env.NPM_PUBLISH === 'true',
+    versionArgs: ['--allow-same-version'],
+    publishArgs: [
+      '--provenance',
+      '--access',
+      process.env.NPM_ACCESS || 'public',
+    ],
+  },
+  github: {
+      release: process.env.GITHUB_RELEASE === 'true',
+    update: true,
+    releaseNotes: createReleaseNotesGenerator(),
+  },
+};
+
+export default config;

package/config/retry-publish.js

@@ -0,0 +1,40 @@
+/**
+ * Retry publish release-it configuration
+ *
+ * This configuration retries publishing an existing version that failed:
+ * - No version increment
+ * - No git operations
+ * - Optionally runs npm publish with provenance (set NPM_PUBLISH=true)
+ * - Optionally updates GitHub release (set GITHUB_RELEASE=true)
+ *
+ * Usage:
+ * First run the retry script to checkout the tag:
+ * ```bash
+ * node node_modules/@oorabona/release-it-preset/dist/scripts/retry-publish.js
+ * pnpm release-it --config node_modules/@oorabona/release-it-preset/config/retry-publish.js
+ * ```
+ */
+
+import { createReleaseNotesGenerator } from './helpers.js';
+
+const config = {
+  increment: false,
+  git: false,
+  npm: {
+    skipChecks: process.env.NPM_SKIP_CHECKS === 'true',
+    publish: process.env.NPM_PUBLISH === 'true',
+    versionArgs: ['--allow-same-version'],
+    publishArgs: [
+      '--provenance',
+      '--access',
+      process.env.NPM_ACCESS || 'public',
+    ],
+  },
+  github: {
+    release: process.env.GITHUB_RELEASE === 'true',
+    update: true,
+    releaseNotes: createReleaseNotesGenerator(),
+  },
+};
+
+export default config;