@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

package/lib/src/utils/treeArchive.js

@@ -0,0 +1,242 @@
+/**
+ * A folder of a site's files as one `.tar` beside a backup document, and back
+ * (#1876).
+ *
+ * The backup document is JSON built in memory, so file contents never go in
+ * it: a manager whose data is files (attachments, role and person records,
+ * footnotes, comments) writes them here instead, as `<stem>.<part>.tar`
+ * beside the document, the way DatabaseManager writes `<stem>.<name>.db`.
+ * BackupManager prunes and downloads these with the document.
+ *
+ * - __Streamed__ both ways: each file is read from disk as the archive is
+ *   written, and written to disk as it is read, so a file's size never
+ *   becomes memory.
+ * - __Bytes as stored__: nothing is decoded, so a sealed vault file stays the
+ *   sealed bytes it is on disk.
+ * - __Only files and folders__: a symbolic link or any other kind of entry is
+ *   left out of a backup, and named; one in an archive refuses the extract.
+ * - __Paths are data__: an extract refuses an entry that is absolute or
+ *   climbs out of its folder (`strict`), never writing outside `dest`.
+ * - __Encrypted under the backup key__ when one is given (#1561, #1876): the
+ *   archive is streamed through `backupCrypto.ts` as it is written, and an
+ *   extract or a listing given the key decrypts it as it reads. One that is
+ *   encrypted is never read without the key, one made under another key is
+ *   refused by its fingerprint, and given a key a plain archive is refused:
+ *   it is not the one the backup wrote.
+ */
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { create as createTar, extract as extractTar, list as listTar } from 'tar';
+import { decryptBuffer, decryptStream, encryptBuffer, encryptStream, fileIsEncrypted } from './backupCrypto.js';
+import { BACKUP_KEY_ENV } from './backupKey.js';
+/**
+ * Whether a backup's read failed because the entry it was reading was
+ * deleted meanwhile (#1563): a page, a version folder or a file removed
+ * while the backup walked past it. That entry is skipped and counted, never
+ * a failed backup — the site keeps running while it is backed up (#1213).
+ * Every other error (EACCES, EIO, …) is a real failure and still fails.
+ */
+export function vanishedDuringBackup(err) {
+    return err?.code === 'ENOENT';
+}
+/** The log's note of entries deleted while they were backed up (#1563): skipped, not a failure. */
+export function vanishedNote(vanished) {
+    return vanished.length > 0 ? `; ${vanished.length} entr${vanished.length === 1 ? 'y' : 'ies'} deleted during the backup skipped (${vanished.slice(0, 5).join(', ')})` : '';
+}
+/** Two 512-byte zero blocks: a tar with no entries. */
+const EMPTY_TAR = Buffer.alloc(1024);
+/**
+ * Write `entries` (paths relative to `root`; default: everything in it) into
+ * `target`, streamed. `exclude` leaves out a path relative to `root`, in
+ * posix form. A missing `root` writes an empty archive. Never overwrites.
+ *
+ * An entry deleted while the archive is written (#1563) — the tar stream
+ * stops at the first file it can no longer find — is not a failure: the
+ * archive is written again from a fresh listing, without it, and the entry
+ * is named in `vanished`. It is written again only while each attempt finds
+ * another entry gone, so it ends once the deleting stops; the same entry
+ * missing twice, or one still there, is a real failure.
+ */
+export async function writeTreeArchive(target, root, options = {}) {
+    if (existsSync(target))
+        throw new Error(`${path.basename(target)} already exists; a backup never overwrites one`);
+    const vanished = new Set();
+    for (;;) {
+        try {
+            const outcome = await writeTreeArchiveOnce(target, root, options);
+            return { ...outcome, vanished: [...vanished].map((p) => toPosix(path.relative(root, p))).sort() };
+        }
+        catch (err) {
+            const gone = err.path;
+            if (!vanishedDuringBackup(err) || !gone || vanished.has(gone) || existsSync(gone))
+                throw err;
+            vanished.add(gone);
+        }
+    }
+}
+async function writeTreeArchiveOnce(target, root, options) {
+    const outcome = { files: 0, bytes: 0, skipped: [] };
+    const entries = (options.entries ?? (existsSync(root) ? readdirSync(root) : []))
+        .filter((e) => existsSync(path.join(root, e)))
+        .filter((e) => !options.exclude?.(toPosix(e)))
+        .sort();
+    if (entries.length === 0) {
+        writeFileSync(target, options.backupKey ? await encryptBuffer(EMPTY_TAR, options.backupKey) : EMPTY_TAR, { mode: 0o600, flag: 'wx' });
+        return outcome;
+    }
+    try {
+        const tarOptions = {
+            cwd: root,
+            portable: true,
+            filter: (p, stat) => {
+                const relative = toPosix(path.normalize(p));
+                if (options.exclude?.(relative))
+                    return false;
+                const s = stat;
+                if (s.isDirectory())
+                    return true;
+                if (!s.isFile()) {
+                    outcome.skipped.push(relative);
+                    return false;
+                }
+                outcome.files++;
+                outcome.bytes += s.size;
+                return true;
+            }
+        };
+        if (options.backupKey) {
+            const pack = createTar(tarOptions, entries);
+            await pipeline(pack, encryptStream(options.backupKey), createWriteStream(target, { flags: 'wx', mode: 0o600 }));
+        }
+        else {
+            await createTar({ ...tarOptions, file: target, mode: 0o600 }, entries);
+        }
+    }
+    catch (err) {
+        rmSync(target, { force: true });
+        throw err;
+    }
+    return outcome;
+}
+/**
+ * Extract `archive` into `dest`, which is emptied first, streamed.
+ * `select(relative)` picks the entries to extract (default: all). Refuses —
+ * removing `dest` — an entry that is not a file or a folder, an absolute
+ * path, or one that climbs out (`..`).
+ */
+export async function extractTreeArchive(archive, dest, options = {}) {
+    if (!existsSync(archive) || !statSync(archive).isFile())
+        throw new Error(`${path.basename(archive)} is missing`);
+    const source = await openArchive(archive, options.backupKey);
+    rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dest, { recursive: true });
+    // An archive of an empty folder is only its end blocks, which a strict read refuses.
+    if (source.empty)
+        return { files: 0, bytes: 0 };
+    const refused = [];
+    let files = 0;
+    let bytes = 0;
+    try {
+        const unpackOptions = {
+            cwd: dest,
+            strict: true,
+            preservePaths: false,
+            preserveOwner: false,
+            ...(options.strip ? { strip: options.strip } : {}),
+            filter: (p, entry) => {
+                const e = entry;
+                const relative = toPosix(p).replace(/^\.\//, '');
+                if (options.select && !options.select(relative))
+                    return false;
+                if (!['File', 'OldFile', 'ContiguousFile', 'Directory'].includes(e.type)) {
+                    refused.push(`${relative} (${e.type})`);
+                    return false;
+                }
+                if (e.type !== 'Directory') {
+                    files++;
+                    bytes += e.size ?? 0;
+                }
+                return true;
+            }
+        };
+        if (source.into)
+            await source.into(extractTar(unpackOptions));
+        else
+            await extractTar({ ...unpackOptions, file: archive });
+    }
+    catch (err) {
+        rmSync(dest, { recursive: true, force: true });
+        throw new Error(`${path.basename(archive)} could not be read: ${err.message}`, { cause: err });
+    }
+    if (refused.length > 0) {
+        rmSync(dest, { recursive: true, force: true });
+        throw new Error(`${path.basename(archive)} holds entries that are not files or folders: ${refused.slice(0, 5).join(', ')}`);
+    }
+    return { files, bytes };
+}
+/** An encrypted archive this small is decrypted whole, to recognise an empty one; anything larger streams. */
+const SMALL_ENCRYPTED = 64 * 1024;
+/**
+ * How to read an archive: plain (`stream` absent, tar reads the file), or
+ * decrypted as a stream. `empty` when it holds no entry at all. Throws for an
+ * encrypted archive with no key or another key, before anything is written.
+ */
+async function openArchive(archive, backupKey) {
+    const name = path.basename(archive);
+    if (!(await fileIsEncrypted(archive))) {
+        // A backup that says its archive is encrypted never takes a plain one in its place.
+        if (backupKey)
+            throw new Error(`${name} is not encrypted, but the backup says it is: it was replaced or damaged`);
+        const empty = statSync(archive).size === EMPTY_TAR.length && (await readHead(archive, EMPTY_TAR.length)).equals(EMPTY_TAR);
+        return { empty };
+    }
+    if (!backupKey)
+        throw new Error(`${name} is encrypted under a backup key, and none was given to read it (${BACKUP_KEY_ENV} is not set, or the backup does not say the archive is encrypted)`);
+    if (statSync(archive).size <= SMALL_ENCRYPTED) {
+        let plain;
+        try {
+            plain = await decryptBuffer(await readHead(archive, SMALL_ENCRYPTED), backupKey);
+        }
+        catch (err) {
+            throw new Error(`${name} could not be read: ${err.message}`, { cause: err });
+        }
+        if (plain.length === EMPTY_TAR.length && plain.equals(EMPTY_TAR))
+            return { empty: true };
+        return { empty: false, into: (sink) => pipeline(Readable.from([plain]), sink) };
+    }
+    // The decrypting stream checks the header (a wrong key is refused) before it passes on any byte.
+    return { empty: false, into: (sink) => pipeline(createReadStream(archive), decryptStream(backupKey), sink) };
+}
+/**
+ * Every entry in an archive, plain or encrypted, read as a stream: what a
+ * caller checks before extracting. `onEntry` gets each entry's path and type.
+ */
+export async function listTreeArchive(archive, onEntry, options = {}) {
+    if (!existsSync(archive) || !statSync(archive).isFile())
+        throw new Error(`${path.basename(archive)} is missing`);
+    const source = await openArchive(archive, options.backupKey);
+    if (source.empty)
+        return;
+    const listOptions = { onReadEntry: (e) => onEntry({ path: e.path, type: e.type }) };
+    if (source.into)
+        await source.into(listTar(listOptions));
+    else
+        await listTar({ ...listOptions, file: archive });
+}
+/** The first `n` bytes of a file, read without reading the rest. */
+export async function readHead(file, n) {
+    const chunks = [];
+    let total = 0;
+    if (n <= 0)
+        return Buffer.alloc(0);
+    for await (const chunk of createReadStream(file, { start: 0, end: n - 1 })) {
+        chunks.push(chunk);
+        total += chunk.length;
+    }
+    return Buffer.concat(chunks, total);
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}

package/lib/src/utils/version.js

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+/**
+ * Version Management Script for ngdpbase
+ *
+ * Helps manage semantic versioning for the project.
+ *
+ * Usage:
+ *   node version.js                    - Show current version
+ *   node version.js patch              - Increment patch version (bug fixes)
+ *   node version.js minor              - Increment minor version (new features)
+ *   node version.js major              - Increment major version (breaking changes)
+ *   node version.js set <version>      - Set specific version
+ */
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Find project root by walking up from __dirname until we find package.json
+function findProjectRoot() {
+    let dir = __dirname;
+    while (dir !== path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    throw new Error('Could not find project root (no package.json found)');
+}
+const PROJECT_ROOT = findProjectRoot();
+const PACKAGE_JSON_PATH = path.join(PROJECT_ROOT, 'package.json');
+const PACKAGE_LOCK_PATH = path.join(PROJECT_ROOT, 'package-lock.json');
+const CHANGELOG_PATH = path.join(PROJECT_ROOT, 'CHANGELOG.md');
+const APP_CONFIG_PATH = path.join(PROJECT_ROOT, 'config/app-default-config.json');
+/**
+ * Read package.json
+ *
+ * @returns {PackageJson} Parsed package.json
+ */
+function readPackageJson() {
+    try {
+        const content = fs.readFileSync(PACKAGE_JSON_PATH, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        console.error('Error reading package.json:', error.message);
+        process.exit(1);
+    }
+}
+/**
+ * Write package.json
+ *
+ * @param {PackageJson} packageData - Package data to write
+ */
+function writePackageJson(packageData) {
+    try {
+        const content = JSON.stringify(packageData, null, 2) + '\n';
+        fs.writeFileSync(PACKAGE_JSON_PATH, content);
+    }
+    catch (error) {
+        console.error('Error writing package.json:', error.message);
+        process.exit(1);
+    }
+}
+/**
+ * Update version in app-default-config.json
+ *
+ * @param {string} newVersion - New version string
+ */
+function updateAppConfig(newVersion) {
+    try {
+        const content = fs.readFileSync(APP_CONFIG_PATH, 'utf8');
+        const config = JSON.parse(content);
+        config['ngdpbase.version'] = newVersion;
+        fs.writeFileSync(APP_CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+        console.log(`Updated app-default-config.json with version ${newVersion}`);
+    }
+    catch (error) {
+        console.warn('Warning: Could not update app-default-config.json:', error.message);
+    }
+}
+/**
+ * Update the version fields in package-lock.json.
+ *
+ * The lockfile mirrors the project version in two places — the top-level
+ * `version` and the root package entry `packages[""].version` — and npm rewrites
+ * both on the next `npm install`. Leaving them behind meant every satellite
+ * checkout showed a two-line `package-lock.json` diff after any build, which had
+ * to be inspected and discarded by hand at every release. Keeping them in
+ * lockstep here removes the drift at the source.
+ *
+ * A parse → mutate → `JSON.stringify(…, null, 2)` round-trip is byte-identical
+ * to npm's own formatting for this lockfile, so this rewrites exactly the two
+ * version lines and nothing else. Dependency resolution is untouched: only the
+ * project's own version is edited, never any package entry.
+ *
+ * Warns rather than fails — a missing or unparseable lockfile must not abort a
+ * release, matching how a missing app-default-config.json is handled.
+ *
+ * @param {string} newVersion - New version string
+ */
+function updatePackageLock(newVersion) {
+    try {
+        if (!fs.existsSync(PACKAGE_LOCK_PATH)) {
+            console.warn('Warning: package-lock.json not found, skipping');
+            return;
+        }
+        const content = fs.readFileSync(PACKAGE_LOCK_PATH, 'utf8');
+        const lock = applyVersionToLock(JSON.parse(content), newVersion);
+        fs.writeFileSync(PACKAGE_LOCK_PATH, JSON.stringify(lock, null, 2) + '\n');
+        console.log(`Updated package-lock.json with version ${newVersion}`);
+    }
+    catch (error) {
+        console.warn('Warning: Could not update package-lock.json:', error.message);
+    }
+}
+/**
+ * Set the project's own version in a parsed lockfile — the pure half of
+ * {@link updatePackageLock}, split out so the mapping is testable without
+ * touching the filesystem.
+ *
+ * Writes exactly two fields: the top-level `version` and the root package entry
+ * `packages[""].version`. Dependency entries are never touched — only npm may
+ * change those, and rewriting one here would corrupt resolution.
+ *
+ * @param {PackageLock} lock - Parsed lockfile (mutated in place and returned)
+ * @param {string} newVersion - New version string
+ * @returns {PackageLock} The same object, for convenient chaining
+ */
+export function applyVersionToLock(lock, newVersion) {
+    lock.version = newVersion;
+    // lockfileVersion 1 has no `packages` map — guard rather than assume v2/v3.
+    const rootEntry = lock.packages?.[''];
+    if (rootEntry)
+        rootEntry.version = newVersion;
+    return lock;
+}
+/**
+ * Parse a semantic version string
+ *
+ * @param {string} version - Version string (e.g., "1.2.3")
+ * @returns {VersionComponents} Parsed version components
+ * @throws {Error} If version format is invalid
+ */
+export function parseVersion(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid version format: ${version}`);
+    }
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10)
+    };
+}
+/**
+ * Whether `version` is `minimum` or later (both `x.y.z`). An add-on states the
+ * core release it needs this way (#1757: `ngdpbase.minVersion`).
+ *
+ * @throws {Error} If either version format is invalid
+ */
+export function isAtLeast(version, minimum) {
+    const v = parseVersion(version);
+    const m = parseVersion(minimum);
+    if (v.major !== m.major)
+        return v.major > m.major;
+    if (v.minor !== m.minor)
+        return v.minor > m.minor;
+    return v.patch >= m.patch;
+}
+/**
+ * Format version components into string
+ *
+ * @param {number} major - Major version
+ * @param {number} minor - Minor version
+ * @param {number} patch - Patch version
+ * @returns {string} Formatted version string
+ */
+export function formatVersion(major, minor, patch) {
+    return `${major}.${minor}.${patch}`;
+}
+/**
+ * Increment version based on type
+ *
+ * @param {string} currentVersion - Current version string
+ * @param {VersionIncrementType} type - Type of increment
+ * @returns {string} New version string
+ * @throws {Error} If increment type is invalid
+ */
+export function incrementVersion(currentVersion, type) {
+    const { major, minor, patch } = parseVersion(currentVersion);
+    switch (type) {
+        case 'patch':
+            return formatVersion(major, minor, patch + 1);
+        case 'minor':
+            return formatVersion(major, minor + 1, 0);
+        case 'major':
+            return formatVersion(major + 1, 0, 0);
+        default:
+            throw new Error(`Invalid increment type: ${String(type)}`);
+    }
+}
+/**
+ * Get current date in ISO format (YYYY-MM-DD)
+ *
+ * @returns {string} Current date
+ */
+function getCurrentDate() {
+    return new Date().toISOString().split('T')[0];
+}
+/**
+ * Update CHANGELOG.md for a new release
+ *
+ * @param {string} newVersion - New version number
+ */
+function updateChangelogForRelease(newVersion) {
+    try {
+        let changelog = fs.readFileSync(CHANGELOG_PATH, 'utf8');
+        const newHeader = `## [${newVersion}] - ${getCurrentDate()}`;
+        if (/## \[Unreleased\]/.test(changelog)) {
+            // Replace [Unreleased] heading, preserving a fresh one above the new entry
+            const replacement = `## [Unreleased]\n\n### Planned\n\n- Future enhancements\n\n${newHeader}`;
+            changelog = changelog.replace(/## \[Unreleased\]/, replacement);
+        }
+        else {
+            // No [Unreleased] section — insert new version after the header block (first ---)
+            const insertAfter = /^---\s*\n/m;
+            if (insertAfter.test(changelog)) {
+                changelog = changelog.replace(insertAfter, `---\n\n${newHeader}\n\n`);
+            }
+            else {
+                // Fallback: prepend to the first ## heading
+                changelog = changelog.replace(/^(## )/m, `${newHeader}\n\n$1`);
+            }
+        }
+        fs.writeFileSync(CHANGELOG_PATH, changelog);
+        console.log(`Updated CHANGELOG.md with version ${newVersion}`);
+    }
+    catch (error) {
+        console.warn('Warning: Could not update CHANGELOG.md:', error.message);
+    }
+}
+/**
+ * Extract the release notes for a specific version from CHANGELOG.md.
+ * Returns the content between `## [version]` and the next `## [` heading.
+ */
+function extractChangelogNotes(version) {
+    try {
+        const changelog = fs.readFileSync(CHANGELOG_PATH, 'utf8');
+        const escaped = version.replace(/\./g, '\\.');
+        const pattern = new RegExp(`## \\[${escaped}\\][^\\n]*\\n([\\s\\S]*?)(?=\\n## \\[|$)`);
+        const match = changelog.match(pattern);
+        if (match?.[1])
+            return match[1].trim();
+    }
+    catch {
+        // ignore — caller handles empty notes
+    }
+    return '';
+}
+/**
+ * Create a git tag and push it to origin.
+ */
+function createGitTag(version) {
+    const tag = `v${version}`;
+    try {
+        execSync(`git tag ${tag}`, { stdio: 'inherit' });
+        execSync(`git push origin ${tag}`, { stdio: 'inherit' });
+        console.log(`✅ Git tag ${tag} created and pushed`);
+    }
+    catch (error) {
+        console.error('Error creating git tag:', error.message);
+        process.exit(1);
+    }
+}
+/**
+ * Create a GitHub release using the `gh` CLI.
+ * Release notes are written to a temp file to avoid shell-escaping issues.
+ */
+function createGitHubRelease(version, notes) {
+    const tag = `v${version}`;
+    const tmpFile = path.join(PROJECT_ROOT, '.release-notes.tmp');
+    try {
+        fs.writeFileSync(tmpFile, notes || `Release ${tag}`);
+        execSync(`gh release create ${tag} --title "${tag}" --notes-file "${tmpFile}"`, { stdio: 'inherit' });
+        fs.unlinkSync(tmpFile);
+        console.log(`✅ GitHub release ${tag} created`);
+    }
+    catch (error) {
+        console.error('Error creating GitHub release:', error.message);
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch { /* ignore */ }
+        process.exit(1);
+    }
+}
+/**
+ * Show help message
+ */
+function showHelp() {
+    console.log(`
+ngdpbase Version Management
+
+Usage:
+  node version.js                         - Show current version and info
+  node version.js patch                   - Increment patch (bug fixes: 1.2.0 → 1.2.1)
+  node version.js minor                   - Increment minor (new features: 1.2.0 → 1.3.0)
+  node version.js major                   - Increment major (breaking changes: 1.2.0 → 2.0.0)
+  node version.js set <version>           - Set specific version (e.g., 1.2.3)
+  node version.js patch --tag-only        - Bump + create/push git tag (no GH release)
+  node version.js minor --release         - Bump + create/push tag + GitHub release
+  node version.js help                    - Show this help
+
+Semantic Versioning:
+  MAJOR.MINOR.PATCH
+  - MAJOR: Incompatible API changes
+  - MINOR: Backward-compatible functionality additions
+  - PATCH: Backward-compatible bug fixes
+`);
+}
+/**
+ * Main CLI function
+ */
+function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const doRelease = args.includes('--release');
+    const doTagOnly = args.includes('--tag-only');
+    const packageData = readPackageJson();
+    const currentVersion = packageData.version;
+    if (!command || command === 'help') {
+        if (!command) {
+            console.log(`Current version: ${currentVersion}`);
+            console.log(`Project: ${packageData.name}`);
+            console.log(`Description: ${packageData.description || 'No description'}`);
+            console.log('\nRun "node version.js help" for usage information.');
+        }
+        else {
+            showHelp();
+        }
+        return;
+    }
+    try {
+        let newVersion;
+        switch (command) {
+            case 'patch':
+            case 'minor':
+            case 'major':
+                newVersion = incrementVersion(currentVersion, command);
+                break;
+            case 'set':
+                newVersion = args[1];
+                if (!newVersion) {
+                    console.error('Error: Please specify a version to set');
+                    process.exit(1);
+                }
+                // Validate version format
+                parseVersion(newVersion);
+                break;
+            default:
+                console.error(`Error: Unknown command "${command}"`);
+                console.log('Run "node version.js help" for usage information.');
+                process.exit(1);
+        }
+        // Update package.json
+        packageData.version = newVersion;
+        writePackageJson(packageData);
+        // Update package-lock.json (its two version fields mirror package.json)
+        updatePackageLock(newVersion);
+        // Update app-default-config.json
+        updateAppConfig(newVersion);
+        // Update changelog if incrementing
+        if (['patch', 'minor', 'major'].includes(command)) {
+            updateChangelogForRelease(newVersion);
+        }
+        console.log(`Version updated: ${currentVersion} → ${newVersion}`);
+        console.log(`Type: ${command.toUpperCase()}`);
+        if (command === 'major') {
+            console.log('\n⚠️  MAJOR version bump - ensure breaking changes are documented!');
+        }
+        else if (command === 'minor') {
+            console.log('\n✨ MINOR version bump - new features added');
+        }
+        else if (command === 'patch') {
+            console.log('\n🐛 PATCH version bump - bug fixes');
+        }
+        // Tag and/or release if requested
+        if (doRelease || doTagOnly) {
+            createGitTag(newVersion);
+        }
+        if (doRelease) {
+            const notes = extractChangelogNotes(newVersion);
+            createGitHubRelease(newVersion, notes);
+        }
+    }
+    catch (error) {
+        console.error('Error:', error.message);
+        process.exit(1);
+    }
+}
+// Run main only when executed directly (ESM-safe).
+// `require.main === module` would crash under "type": "module".
+const argvPath = process.argv[1] ? path.resolve(process.argv[1]) : '';
+if (argvPath === __filename) {
+    main();
+}