changelog-machine 2.0.0 → 2.1.0

package/README.md

@@ -26,6 +26,7 @@ npx changelog-machine --bump           # Update package metadata and release cha
 | --- | --- |
 | `--full` | Rebuild the entire changelog |
 | `--bump` | Infer and apply a version bump |
+| `--bump-command <command>` | Override the metadata update command; requires `--bump` and `{version}` |
 | `--dry-run` | Preview without writing |
 | `--output <path>` | Set the changelog destination |
 | `--repo-url <url>` | Override repository links with an HTTPS URL |
@@ -110,15 +111,30 @@ The highest-impact commit since the latest release wins:
 | `fix:` or `perf:` | Patch |
 | Other types | None |
 
-- Updates `package.json`, an existing npm lockfile (versions 1–3), and the changelog with `## v<next-version>`. No Git tag is needed to prepare that section; the CLI does not create one.
-- Leaves dependency versions unchanged.
+- Calculates the exact next version, then runs `npm version <next-version> --no-git-tag-version --ignore-scripts` by default. npm owns `package.json` and its lockfiles; changelog-machine does not parse or restrict lockfile formats. npm must be available on `PATH` unless a custom command is supplied.
+- Writes the release changelog with `## v<next-version>` only after the command succeeds and `package.json` contains the planned version. No Git tag is needed to prepare that section.
+- The default command disables lifecycle scripts and Git commit/tag creation.
 - Requires the latest tag to match the package version; repeated bumps fail.
 - Without tags, analyzes all commits against the current package version.
-- Prerelease promotion, Yarn/pnpm lockfiles, and workspaces are unsupported.
+- Prerelease promotion and workspace version orchestration are unsupported. Non-npm metadata and lockfiles can be maintained by a custom command.
 - `--bump --full` rebuilds historical sections too. Without `--full`, older sections remain unchanged. `--output` also works with bumps; `--dry-run` previews without writing. No release-worthy commits means no file changes.
 - After a successful bump, commit and create the matching version tag before another incremental update or bump.
 
-Files are staged first and replaced atomically per file—not as a multi-file transaction.
+### Custom package managers
+
+```sh
+changelog-machine --bump \
+  --bump-command='bun pm version {version} --no-git-tag-version --ignore-scripts'
+```
+
+Use `{version}` for the exact calculated version, not a relative bump such as `patch`. Every occurrence is replaced. Commands run in the repository directory through the system shell, with output sent to stderr. Shell syntax and executable availability depend on your platform.
+
+`--bump-command` is **trusted, arbitrary shell input**. You are responsible for making it update `package.json` and the relevant lockfiles without commits, tags, pushes, publishing, or lifecycle side effects. npm does not maintain Bun, pnpm, or Yarn lockfiles; use a command or wrapper script appropriate to your package manager. The tool verifies the resulting package version, but cannot verify arbitrary lockfile contents or prevent custom-command side effects.
+
+`--dry-run` prints the planned command to stderr and changelog to stdout without executing the command. No release-worthy commits means no command execution.
+
+Changelog destinations are validated and temporary files staged before executing the command. Command failures or version mismatches leave the existing changelog untouched. Metadata changes made by a command are **not rolled back**; inspect repository changes before retrying. A failure while replacing the staged changelog can also leave metadata updated without the changelog; updates are not a multi-file transaction.
+
 
 ## API
 
@@ -142,7 +158,7 @@ const contributors = await resolveContributors(
 const enriched = renderMarkdown(releases, { repositoryUrl, contributors });
 ```
 
-Also exports `parseCommit`, `recommendedBump`, `planVersion`, and TypeScript types.
+Also exports `parseCommit`, `recommendedBump`, `planVersion`, and TypeScript types. `planVersion` is read-only: it calculates `current`, `next`, and `bump`; its `files` array is now empty because metadata updates are delegated to a command.
 Pass a boundary tag to `getReleases(cwd, tag)` for incremental history.
 The API does not write files. Explicit GitLab profiles can be supplied to the renderer.
 

package/lib/cli/files.d.ts

@@ -2,4 +2,4 @@ export type FilePlan = {
     path: string;
     content: string;
 };
-export declare function apply(files: FilePlan[]): Promise<void>;
+export declare function apply(files: FilePlan[], beforeReplace?: () => Promise<void>): Promise<void>;

package/lib/cli/files.js

@@ -14,7 +14,7 @@ async function fileMode(path) {
         return undefined;
     }
 }
-export async function apply(files) {
+export async function apply(files, beforeReplace) {
     const staged = [];
     try {
         for (const file of files) {
@@ -24,6 +24,8 @@ export async function apply(files) {
             staged.push({ path: file.path, temporary });
             await writeFile(temporary, file.content, { flag: 'wx', mode });
         }
+        // Validate and stage changelog destinations before running a mutating command.
+        await beforeReplace?.();
         for (const file of staged)
             await rename(file.temporary, file.path);
     }

package/lib/cli/index.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { parseChangelog } from '../changelog/update.js';
 import { getLatestReleaseTag, getReleases } from '../git/history.js';
+import { defaultBumpCommand, formatBumpCommand, runBumpCommand, } from '../version/command.js';
 import { apply } from './files.js';
 import { parseFlags, showInformation } from './options.js';
 import { changelogPath, planBump, planChangelog } from './plans.js';
@@ -15,34 +16,57 @@ async function readChangelog(path) {
         throw error;
     }
 }
-export async function run(args = process.argv.slice(2)) {
-    const flags = parseFlags(args);
-    if (await showInformation(flags))
-        return;
-    const cwd = process.cwd();
+async function readExistingChangelog(flags, cwd) {
     const existing = flags.full
         ? undefined
         : await readChangelog(changelogPath(flags, cwd));
+    // Only regenerate history newer than the latest documented release.
     const boundary = existing === undefined ? undefined : parseChangelog(existing).boundaryTag;
-    const bumpTag = flags.bump ? await getLatestReleaseTag(cwd) : undefined;
-    const bump = flags.bump
-        ? await planBump(await getReleases(cwd, bumpTag), cwd, bumpTag)
-        : undefined;
-    if (flags.bump && !bump?.next)
-        return;
-    let releases = await withProgress('Reading Git releases', () => getReleases(cwd, boundary));
+    return { existing, boundary };
+}
+async function prepareBump(flags, cwd) {
+    if (!flags.bump)
+        return undefined;
+    const tag = await getLatestReleaseTag(cwd);
+    return planBump(await getReleases(cwd, tag), cwd, tag);
+}
+function promoteUnreleased(releases, next, boundary) {
+    if (!next)
+        return releases;
+    // Incremental history may expose the previous tag only through Unreleased.
     const latestTag = releases.find((release) => release.tag !== 'Unreleased')?.tag ??
         releases.find((release) => release.tag === 'Unreleased')?.previousTag ??
         boundary;
-    if (bump?.next) {
-        releases = releases.map((release) => release.tag === 'Unreleased'
-            ? { ...release, tag: `v${bump.next}`, previousTag: latestTag }
-            : release);
-    }
-    const files = [
+    return releases.map((release) => release.tag === 'Unreleased'
+        ? { ...release, tag: `v${next}`, previousTag: latestTag }
+        : release);
+}
+async function prepareFiles(flags, cwd, existing, boundary, bump) {
+    const releases = await withProgress('Reading Git releases', () => getReleases(cwd, boundary));
+    return [
         ...(bump?.files ?? []),
-        ...(await planChangelog(releases, flags, cwd, existing)),
+        ...(await planChangelog(promoteUnreleased(releases, bump?.next, boundary), flags, cwd, existing)),
     ];
-    if (!flags['dry-run'])
-        await apply(files);
+}
+async function applyOrPreview(files, flags, cwd, next) {
+    if (flags['dry-run']) {
+        if (next) {
+            console.error(`Would run: ${formatBumpCommand(flags['bump-command'] ?? defaultBumpCommand, next)}`);
+        }
+        return;
+    }
+    // Stage the changelog first; update metadata before replacing it.
+    await apply(files, next ? () => runBumpCommand(next, cwd, flags['bump-command']) : undefined);
+}
+export async function run(args = process.argv.slice(2)) {
+    const flags = parseFlags(args);
+    if (await showInformation(flags))
+        return;
+    const cwd = process.cwd();
+    const { existing, boundary } = await readExistingChangelog(flags, cwd);
+    const bump = await prepareBump(flags, cwd);
+    if (flags.bump && !bump?.next)
+        return;
+    const files = await prepareFiles(flags, cwd, existing, boundary, bump);
+    await applyOrPreview(files, flags, cwd, bump?.next);
 }

package/lib/cli/options.d.ts

@@ -2,6 +2,7 @@ export type Flags = ReturnType<typeof parseFlags>;
 export declare function parseFlags(args: string[]): {
     full?: boolean | undefined;
     bump?: boolean | undefined;
+    'bump-command'?: string | undefined;
     'dry-run'?: boolean | undefined;
     output?: string | undefined;
     'repo-url'?: string | undefined;

package/lib/cli/options.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { parseArgs } from 'node:util';
+import { validateBumpCommand } from '../version/command.js';
 const help = `Usage: changelog-machine [options]
 
 Updates missing releases and refreshes Unreleased in CHANGELOG.md by default.
@@ -7,6 +8,7 @@ Creates a complete changelog when the file does not exist.
 
   --full                      Replace the entire CHANGELOG.md from Git history
   --bump                      Infer version; update package metadata and changelog
+  --bump-command <command>    Trusted shell command containing {version} (requires --bump)
   --dry-run                   Preview without writing any files
   --output <path>              Changelog destination (default: CHANGELOG.md)
   --repo-url <url>             Repository URL for links
@@ -18,11 +20,12 @@ Creates a complete changelog when the file does not exist.
 Requires Node 24+ and Git. Never fetches, commits, tags, pushes or publishes.
 `;
 export function parseFlags(args) {
-    return parseArgs({
+    const flags = parseArgs({
         args,
         options: {
             full: { type: 'boolean' },
             bump: { type: 'boolean' },
+            'bump-command': { type: 'string' },
             'dry-run': { type: 'boolean' },
             output: { type: 'string' },
             'repo-url': { type: 'string' },
@@ -33,6 +36,12 @@ export function parseFlags(args) {
         },
         allowPositionals: false,
     }).values;
+    if (flags['bump-command'] !== undefined) {
+        if (!flags.bump)
+            throw new Error('--bump-command requires --bump');
+        validateBumpCommand(flags['bump-command']);
+    }
+    return flags;
 }
 export async function showInformation(flags) {
     if (flags.help) {

package/lib/version/command.d.ts

@@ -0,0 +1,5 @@
+export declare const defaultBumpCommand = "npm version {version} --no-git-tag-version --ignore-scripts";
+export declare function validateBumpCommand(command: string): void;
+export declare function formatBumpCommand(command: string, version: string): string;
+/** Custom commands are explicitly trusted shell input, never read from Git. */
+export declare function runBumpCommand(version: string, cwd: string, command?: string): Promise<void>;

package/lib/version/command.js

@@ -0,0 +1,52 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseObject } from './json.js';
+export const defaultBumpCommand = 'npm version {version} --no-git-tag-version --ignore-scripts';
+export function validateBumpCommand(command) {
+    if (!command.trim() || !command.includes('{version}')) {
+        throw new Error('--bump-command must contain the {version} placeholder');
+    }
+}
+export function formatBumpCommand(command, version) {
+    validateBumpCommand(command);
+    if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(version)) {
+        throw new Error('Bump command requires a stable semver version');
+    }
+    return command.replaceAll('{version}', version);
+}
+/** Custom commands are explicitly trusted shell input, never read from Git. */
+export async function runBumpCommand(version, cwd, command) {
+    const formatted = formatBumpCommand(command ?? defaultBumpCommand, version);
+    console.error(`Running bump command: ${formatted}`);
+    await new Promise((resolveCommand, reject) => {
+        // Avoid shell interpretation for the built-in command.
+        const child = command === undefined
+            ? spawn('npm', ['version', version, '--no-git-tag-version', '--ignore-scripts'], {
+                cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: process.platform === 'win32',
+            })
+            : spawn(formatted, {
+                cwd,
+                shell: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        // Keep stdout reserved for changelog previews.
+        child.stdout?.pipe(process.stderr, { end: false });
+        child.stderr?.pipe(process.stderr, { end: false });
+        child.on('error', (error) => {
+            reject(new Error(`Could not start bump command: ${error.message}. Check repository files before retrying.`, { cause: error }));
+        });
+        child.on('close', (code, signal) => {
+            if (code === 0)
+                resolveCommand();
+            else
+                reject(new Error(`Bump command failed (${signal ?? `exit ${code}`}). Repository files may have changed; inspect them before retrying.`));
+        });
+    });
+    const manifest = parseObject(await readFile(resolve(cwd, 'package.json'), 'utf8'), resolve(cwd, 'package.json'));
+    if (manifest.version !== version) {
+        throw new Error(`Bump command did not set package.json version to ${version} (found ${String(manifest.version)}). Repository files may have changed; inspect them before retrying.`);
+    }
+}

package/lib/version/plan.js

@@ -1,8 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { recommendedBump } from '../commits/parse.js';
-import { formatJson, parseObject } from './json.js';
-import { readLockfiles, updateLockfile } from './lockfiles.js';
+import { parseObject } from './json.js';
 const stableVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 const tagPrefixPattern = /^v/;
 function readCurrentVersion(manifest) {
@@ -37,15 +36,6 @@ export async function planVersion(commits, latestTag, cwd = process.cwd()) {
     if (!bump)
         return { current, files: [] };
     const next = bumpVersion(current, bump);
-    const lockfiles = await readLockfiles(cwd);
-    const files = lockfiles.map(({ path, content }) => ({
-        path,
-        content: updateLockfile(path, content, next),
-    }));
-    manifest.version = next;
-    files.unshift({
-        path: packagePath,
-        content: formatJson(manifest, packageText),
-    });
-    return { current, next, bump, files };
+    // Metadata and lockfiles are owned by the configured package-manager command.
+    return { current, next, bump, files: [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changelog-machine",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Minimal, dependency-free conventional changelog and version generator",
   "type": "module",
   "main": "./lib/index.js",
@@ -49,4 +49,4 @@
     "@types/node": "^24.0.0",
     "typescript": "^7.0.2"
   }
-}
+}

package/lib/version/lockfiles.d.ts

@@ -1,3 +0,0 @@
-import type { VersionPlan } from './plan.js';
-export declare function readLockfiles(cwd: string): Promise<VersionPlan['files']>;
-export declare function updateLockfile(path: string, content: string, next: string): string;

package/lib/version/lockfiles.js

@@ -1,44 +0,0 @@
-import { resolve } from 'node:path';
-import { formatJson, isObject, parseObject, readOptionalFile } from './json.js';
-export async function readLockfiles(cwd) {
-    const lockNames = [
-        'package-lock.json',
-        'npm-shrinkwrap.json',
-        'pnpm-lock.yaml',
-        'yarn.lock',
-    ];
-    const lockTexts = await Promise.all(lockNames.map((name) => readOptionalFile(resolve(cwd, name))));
-    if (lockTexts[0] !== undefined && lockTexts[1] !== undefined) {
-        throw new Error('Both package-lock.json and npm-shrinkwrap.json exist. Remove the unused lockfile to resolve ambiguity before bumping.');
-    }
-    const unsupported = lockNames.filter((_, index) => index >= 2 && lockTexts[index] !== undefined);
-    if (unsupported.length) {
-        throw new Error(`Unsupported lockfile: ${unsupported.join(', ')}. Update it with its package manager instead; only npm lockfiles are supported.`);
-    }
-    const files = [];
-    for (let index = 0; index < 2; index++) {
-        const content = lockTexts[index];
-        if (content !== undefined)
-            files.push({ path: resolve(cwd, lockNames[index]), content });
-    }
-    return files;
-}
-export function updateLockfile(path, content, next) {
-    const lockfile = parseObject(content, path);
-    if (![1, 2, 3].includes(lockfile.lockfileVersion)) {
-        throw new Error(`Unsupported lockfileVersion in ${path}; expected npm lockfile version 1, 2, or 3.`);
-    }
-    if (typeof lockfile.version !== 'string') {
-        throw new Error(`Malformed ${path}: missing root version. Regenerate the lockfile with npm.`);
-    }
-    if (lockfile.packages !== undefined || lockfile.lockfileVersion !== 1) {
-        if (!isObject(lockfile.packages) ||
-            !isObject(lockfile.packages['']) ||
-            typeof lockfile.packages[''].version !== 'string') {
-            throw new Error(`Malformed ${path}: missing packages[''].version. Regenerate the lockfile with npm.`);
-        }
-        lockfile.packages[''].version = next;
-    }
-    lockfile.version = next;
-    return formatJson(lockfile, content);
-}