keepchanges 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 edram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# keepchanges
+
+Generate and maintain `CHANGELOG.md` from Conventional Commits.
+
+[中文](#中文) · [English](#english)
+
+## 中文
+
+### 功能
+
+- 根据最近的 Git tag 到 `HEAD` 之间的 Conventional Commits 生成变更记录
+- 首次发布时读取完整 Git 历史
+- 将新版本插入 `CHANGELOG.md` 的已有内容之前
+- 为 npm 项目同步更新 `package.json` 中的 `version`
+- 为提交、对比页面、作者和共同作者生成 GitHub 信息
+- 可选择自动提交、创建 tag、推送并发布 GitHub Release
+- 没有 GitHub token 时提供预填内容的手动发布链接
+
+当前会收录 `feat`、`fix`、带 `!` 的破坏性变更，以及包含
+`BREAKING CHANGE` 或 `BREAKING-CHANGE` trailer 的提交。其他提交类型会被忽略。
+
+### 快速开始
+
+需要 Node.js 20.19.0 或更高版本。
+
+在 Git 仓库根目录运行，并传入要发布的版本号：
+
+```bash
+npx keepchanges 1.1.0
+```
+
+也可以使用带 `v` 前缀的版本号：
+
+```bash
+npx keepchanges v1.1.0
+```
+
+默认行为会写入 `CHANGELOG.md`。如果当前项目是 npm 包，还会将
+`package.json#version` 更新为 `1.1.0`，但不会自动创建 Git commit。
+
+### 命令格式
+
+```text
+npx keepchanges <version> [options]
+```
+
+#### 参数
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `<version>` | 必填 | 要生成的版本号。可以传入 `1.1.0` 或 `v1.1.0`；生成的标题和 tag 统一使用 `v1.1.0`。包含 `-` 的版本会作为预发布版本，例如 `1.1.0-beta.1`。 |
+| `--output <path>` | `CHANGELOG.md` | 指定 changelog 文件路径。相对路径以当前工作目录为基准。 |
+| `--dry` | `false` | 只预览，不写入 changelog 或版本文件。单独使用时输出完整 changelog；与 `--release` 一起使用时输出 Release notes 和手动发布链接。 |
+| `--commit` | `false` | 写入文件后创建 Git commit。只提交 changelog 和检测到的版本文件，默认提交信息为 `chore(release): v<version>`。 |
+| `--release` | `false` | 执行完整发布流程：写入文件、创建或复用 release commit、创建 annotated tag、推送 `HEAD` 和 tag，然后创建或更新仓库 Release。该参数隐含 `--commit`。 |
+| `--author <author>` | Git 默认作者 | 设置自动创建的 release commit 作者，格式必须为 `"Name <email>"`。只影响作者，不改变仓库配置的 committer；需要与 `--commit` 或 `--release` 一起使用。 |
+| `--token <token>` | 环境变量 | 仓库访问令牌，用于解析 GitHub 用户名以及创建或更新 GitHub Release。优先级为 `--token`、`GITHUB_TOKEN`、`GH_TOKEN`。 |
+
+### 常见用法
+
+指定输出文件：
+
+```bash
+npx keepchanges 1.1.0 --output docs/CHANGELOG.md
+```
+
+预览完整 changelog，不修改文件：
+
+```bash
+npx keepchanges 1.1.0 --dry
+```
+
+写入 changelog、更新版本并创建 commit：
+
+```bash
+npx keepchanges 1.1.0 --commit
+```
+
+指定 release commit 的作者：
+
+```bash
+npx keepchanges 1.1.0 --commit \
+  --author "Release Author <release@example.com>"
+```
+
+创建 GitHub Release：
+
+```bash
+GITHUB_TOKEN=github_pat_xxx npx keepchanges 1.1.0 --release
+```
+
+预览 Release，不写文件、不提交、不创建 tag、不推送且不调用发布 API：
+
+```bash
+npx keepchanges 1.1.0 --release --dry
+```
+
+### 生成和发布行为
+
+仓库地址优先读取 `package.json#repository`，不存在时读取 Git 的 `origin`。
+当前支持 GitHub。识别到仓库后，每条记录会包含 commit 链接，末尾会包含版本对比链接。
+
+默认使用 Git 提交中的作者名，并将 `Co-Authored-By` 参与者一起写入记录，bot
+账号会被忽略。提供 token 后，会通过 GitHub 尝试将邮箱解析为用户名。
+
+`--commit` 只提交 changelog 和检测到的版本文件。其他已暂存或未暂存的改动会
+保持原状。
+
+`--release` 在 tag 不存在时：
+
+1. 写入 changelog 并更新版本文件。
+2. 创建或复用 release commit。
+3. 创建 annotated tag。
+4. 将 `HEAD` 和 tag 推送到 `origin`。
+5. 创建 GitHub Release；没有 token 时输出手动发布链接。
+
+`--release` 在 tag 已存在时不会移动 tag。它会根据前一个版本到现有 tag
+重新生成 Release notes，并创建或更新 Release。只有远程存在 tag 时会先将它
+拉取到本地；只有本地存在 tag 时会推送该 tag。本地与远程 tag 指向不同 commit
+时会停止，不会强制覆盖。
+
+稳定版本会与前一个稳定 tag 对比，预发布版本会与最近的前一个 tag 对比。与
+`--release` 搭配的 `--dry` 优先级最高，不会执行任何写入或远程修改。
+
+> [!NOTE]
+> 没有 token 的普通 `--release` 仍会执行本地写入、commit、tag 和 push，
+> 然后提供手动创建 GitHub Release 的链接。如需完全无副作用的预览，请使用
+> `--release --dry`。
+
+## English
+
+### Features
+
+- Generates release notes from Conventional Commits between the latest Git tag and `HEAD`
+- Reads the complete Git history for a first release
+- Inserts a new release before existing content in `CHANGELOG.md`
+- Updates `package.json#version` for npm projects
+- Adds GitHub commit links, comparison links, authors, and co-authors
+- Can commit, tag, push, and publish a GitHub Release
+- Provides a prefilled manual release URL when no GitHub token is available
+
+The current release includes `feat`, `fix`, breaking changes marked with `!`,
+and commits with a `BREAKING CHANGE` or `BREAKING-CHANGE` trailer. Other commit
+types are ignored.
+
+### Quick start
+
+Node.js 20.19.0 or later is required.
+
+Run the CLI at the root of a Git repository and provide the version to release:
+
+```bash
+npx keepchanges 1.1.0
+```
+
+The version may also include a leading `v`:
+
+```bash
+npx keepchanges v1.1.0
+```
+
+By default, the command writes `CHANGELOG.md`. For an npm package, it also
+updates `package.json#version` to `1.1.0`, but it does not create a Git commit.
+
+### Command
+
+```text
+npx keepchanges <version> [options]
+```
+
+#### Arguments and options
+
+| Argument or option | Default | Description |
+| --- | --- | --- |
+| `<version>` | Required | Version to generate. Accepts `1.1.0` or `v1.1.0`; headings and tags use `v1.1.0`. A version containing `-`, such as `1.1.0-beta.1`, is treated as a prerelease. |
+| `--output <path>` | `CHANGELOG.md` | Sets the changelog file path. Relative paths are resolved from the current working directory. |
+| `--dry` | `false` | Previews without writing the changelog or version file. By itself it prints the complete changelog; with `--release` it prints the Release notes and manual release URL. |
+| `--commit` | `false` | Creates a Git commit after writing. It commits only the changelog and detected version file, using `chore(release): v<version>` by default. |
+| `--release` | `false` | Runs the complete release flow: writes files, creates or reuses a release commit, creates an annotated tag, pushes `HEAD` and the tag, then creates or updates the repository Release. This implies `--commit`. |
+| `--author <author>` | Git default | Sets the author of the generated release commit in `"Name <email>"` format. It does not change the configured committer and only applies with `--commit` or `--release`. |
+| `--token <token>` | Environment | Repository token used to resolve GitHub usernames and create or update a GitHub Release. Precedence is `--token`, `GITHUB_TOKEN`, then `GH_TOKEN`. |
+
+### Examples
+
+Write to a different file:
+
+```bash
+npx keepchanges 1.1.0 --output docs/CHANGELOG.md
+```
+
+Preview the complete changelog without changing files:
+
+```bash
+npx keepchanges 1.1.0 --dry
+```
+
+Write the changelog, update the version, and create a commit:
+
+```bash
+npx keepchanges 1.1.0 --commit
+```
+
+Set the release commit author:
+
+```bash
+npx keepchanges 1.1.0 --commit \
+  --author "Release Author <release@example.com>"
+```
+
+Create a GitHub Release:
+
+```bash
+GITHUB_TOKEN=github_pat_xxx npx keepchanges 1.1.0 --release
+```
+
+Preview a Release without writing, committing, tagging, pushing, or calling the
+release API:
+
+```bash
+npx keepchanges 1.1.0 --release --dry
+```
+
+### Generation and release behavior
+
+The repository URL is read from `package.json#repository`, then from the Git
+`origin`. GitHub is currently supported. When a repository is detected, each
+entry includes a commit link and the release ends with a version comparison
+link.
+
+Entries use Git author names by default and include `Co-Authored-By`
+participants. Bot accounts are omitted. With a token, the CLI asks GitHub to
+resolve email addresses to usernames.
+
+`--commit` commits only the changelog and detected version file. Other staged
+and unstaged changes remain untouched.
+
+When the tag does not exist, `--release`:
+
+1. Writes the changelog and updates the version file.
+2. Creates or reuses a release commit.
+3. Creates an annotated tag.
+4. Pushes `HEAD` and the tag to `origin`.
+5. Creates a GitHub Release, or prints a manual release URL without a token.
+
+When the tag already exists, `--release` never moves it. It regenerates Release
+notes from the previous version to the existing tag and creates or updates the
+Release. A remote-only tag is fetched, while a local-only tag is pushed. The
+command stops without force-updating when local and remote tags point to
+different commits.
+
+Stable releases compare with the previous stable tag. Prereleases compare with
+the nearest previous tag. With `--release`, `--dry` takes precedence and
+prevents all file writes and remote mutations.
+
+> [!NOTE]
+> A regular `--release` without a token still writes files, commits, tags, and
+> pushes before providing the manual GitHub Release URL. Use `--release --dry`
+> for a completely non-mutating preview.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm run typecheck
+pnpm run build
+```
+
+## License
+
+MIT

package/dist/cli.d.mts

@@ -0,0 +1,14 @@
+import ansis from "ansis";
+//#region src/run.d.ts
+interface CliEnvironment {
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  stdout?: (value: string) => void;
+  fetch?: typeof globalThis.fetch;
+  colors?: typeof ansis;
+}
+//#endregion
+//#region src/cli.d.ts
+declare function runCli(args: string[], environment: CliEnvironment): Promise<void>;
+//#endregion
+export { type CliEnvironment, runCli };

package/dist/cli.mjs

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { cac } from "cac";
+import { resolve } from "node:path";
+import ansis from "ansis";
+import { readFile, writeFile } from "node:fs/promises";
+import { normalizeFull } from "verkit";
+import { x } from "tinyexec";
+//#region package.json
+var version = "0.0.0";
+//#endregion
+//#region src/changelog.ts
+function createChangelog(version, commits, repository, comparisonFrom) {
+	const body = [
+		...renderSection(commits.filter((commit) => commit.isBreaking), "🚨 Breaking Changes", repository),
+		...renderSection(commits.filter((commit) => !commit.isBreaking && commit.type === "feat"), "🚀 Features", repository),
+		...renderSection(commits.filter((commit) => !commit.isBreaking && commit.type === "fix"), "🐞 Bug Fixes", repository),
+		...repository && comparisonFrom ? ["", `#####     [View changes on ${repository.provider.name}](${repository.provider.compareUrl(repository, comparisonFrom, `v${version}`)})`] : []
+	].join("\n").trim();
+	return {
+		body,
+		release: [
+			`## v${version}`,
+			"",
+			body,
+			""
+		].join("\n")
+	};
+}
+async function readChangelog(path) {
+	return readFile(path, "utf8").catch((error) => {
+		if (error.code === "ENOENT") return "# Changelog\n";
+		throw error;
+	});
+}
+function writeChangelog(path, changelog) {
+	return writeFile(path, changelog);
+}
+function hasRelease(changelog, version) {
+	const releaseVersion = normalizeFull(version);
+	return releaseHeadings(changelog).some((heading) => heading.version === releaseVersion);
+}
+function insertRelease(changelog, release) {
+	const releaseVersion = releaseHeadings(release)[0]?.version;
+	const headings = releaseHeadings(changelog);
+	const existingReleaseIndex = headings.findIndex((heading) => heading.version === releaseVersion);
+	if (existingReleaseIndex !== -1) {
+		const start = headings[existingReleaseIndex].index;
+		const end = headings[existingReleaseIndex + 1]?.index ?? changelog.length;
+		changelog = changelog.slice(0, start) + changelog.slice(end);
+	}
+	const firstRelease = releaseHeadings(changelog)[0];
+	if (!firstRelease) return `${changelog.trimEnd()}\n\n${release.trim()}\n`;
+	const preamble = changelog.slice(0, firstRelease.index).trimEnd();
+	const history = changelog.slice(firstRelease.index).trim();
+	return `${preamble}\n\n${release.trim()}\n\n${history}\n`;
+}
+function releaseHeadings(changelog) {
+	return [...changelog.matchAll(/^##\s+(\S+).*$/gm)].flatMap((heading) => {
+		const version = normalizeFull(heading[1]);
+		return version ? [{
+			index: heading.index,
+			version
+		}] : [];
+	});
+}
+function renderSection(commits, title, repository) {
+	const lines = commits.map((commit) => {
+		const scope = commit.scope ? `**${escapeHtml(commit.scope)}**: ` : "";
+		const reference = repository ? `[<samp>(${commit.hash.slice(0, 5)})</samp>](${repository.provider.commitUrl(repository, commit.hash)})` : "";
+		const authorNames = commit.authors.map((author) => author.login ? `@${author.login}` : `**${escapeHtml(author.name)}**`);
+		const authors = authorNames.length > 1 ? `${authorNames.slice(0, -1).join(", ")} and ${authorNames.at(-1)}` : authorNames[0] || "";
+		const details = [authors ? `by ${authors}` : "", reference].filter(Boolean).join(" ");
+		const suffix = details ? ` &nbsp;-&nbsp; ${details}` : "";
+		return `${scope}${escapeHtml(capitalize$1(commit.description))}${suffix}`;
+	}).reverse();
+	if (!lines.length) return [];
+	return [
+		"",
+		`### ${title}`,
+		"",
+		...lines.map((line) => `- ${line}`)
+	];
+}
+function capitalize$1(value) {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function escapeHtml(value) {
+	const htmlEntities = {
+		"&": "&amp;",
+		"<": "&lt;",
+		">": "&gt;",
+		"\"": "&quot;",
+		"'": "&#39;"
+	};
+	return value.replace(/[&<>"']/g, (character) => htmlEntities[character]);
+}
+//#endregion
+//#region src/git.ts
+async function git(cwd, ...args) {
+	const result = await x("git", args, { nodeOptions: { cwd } });
+	if (result.exitCode !== 0) throw new Error(result.stderr.trim() || `Git exited with status ${result.exitCode}`);
+	return result.stdout;
+}
+async function getLatestTag(cwd) {
+	return (await x("git", [
+		"describe",
+		"--tags",
+		"--abbrev=0"
+	], { nodeOptions: { cwd } })).stdout.trim();
+}
+async function getTagCommit(cwd, tag) {
+	return git(cwd, "rev-list", "-n", "1", tag).then((output) => output.trim() || void 0).catch(() => void 0);
+}
+async function getPreviousTag(cwd, tag, releaseRef) {
+	if (!tag.includes("-")) {
+		const previousStable = (await git(cwd, "tag", "--merged", releaseRef, "--sort=-version:refname")).trim().split("\n").find((candidate) => candidate !== tag && /^v?\d+\.\d+\.\d+$/.test(candidate));
+		if (previousStable) return previousStable;
+	}
+	return git(cwd, "describe", "--tags", "--abbrev=0", `${releaseRef}^`).then((output) => output.trim()).catch(() => "");
+}
+async function getRemoteTagCommit(cwd, tag) {
+	const refs = (await git(cwd, "ls-remote", "--tags", "origin", `refs/tags/${tag}`, `refs/tags/${tag}^{}`)).trim().split("\n").filter(Boolean);
+	return (refs.find((line) => line.endsWith("^{}")) || refs[0])?.split(/\s+/)[0];
+}
+async function readCommits(cwd, from, to) {
+	return parseGitLog(await git(cwd, "log", from ? `${from}..${to}` : to, "--format=%h%x00%an%x00%ae%x00%s%x00%b%x00")).map((commit) => parseCommit(commit.hash, commit.subject, commit.body, commit.author)).filter((commit) => commit !== null);
+}
+function parseGitLog(log) {
+	const fields = log.split("\0");
+	const commits = [];
+	for (let index = 0; index + 4 < fields.length; index += 5) {
+		const subject = fields[index + 3].trim();
+		if (subject) commits.push({
+			hash: fields[index].trim(),
+			subject,
+			body: fields[index + 4],
+			author: {
+				name: fields[index + 1].trim(),
+				email: fields[index + 2].trim()
+			}
+		});
+	}
+	return commits;
+}
+function parseCommit(hash, subject, body, author) {
+	const match = /^(?<type>[a-z]+)(?:\((?<scope>[^()\r\n]+)\))?(?<breaking>!)?: (?<description>.+)$/i.exec(subject);
+	if (!match?.groups) return null;
+	const authors = [author];
+	for (const coAuthor of body.matchAll(/^Co-Authored-By:\s*(.+?)\s*<([^>]+)>$/gim)) {
+		const email = coAuthor[2].trim();
+		if (!authors.some((author) => author.email === email)) authors.push({
+			name: coAuthor[1].trim(),
+			email
+		});
+	}
+	return {
+		hash,
+		authors: authors.filter((author) => !/\[bot\]|dependabot|\(bot\)/i.test(author.name)),
+		type: match.groups.type.toLowerCase(),
+		scope: match.groups.scope || "",
+		description: match.groups.description,
+		isBreaking: Boolean(match.groups.breaking) || /^BREAKING(?: |-)CHANGE:/im.test(body)
+	};
+}
+//#endregion
+//#region src/providers/github.ts
+const githubProvider = {
+	name: "GitHub",
+	parse(source) {
+		const match = /github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/.exec(source);
+		if (!match) return;
+		return {
+			provider: githubProvider,
+			path: match[1],
+			webUrl: `https://github.com/${match[1]}`
+		};
+	},
+	token(explicit, env) {
+		return explicit || env.GITHUB_TOKEN || env.GH_TOKEN;
+	},
+	commitUrl(repository, hash) {
+		return `${repository.webUrl}/commit/${hash}`;
+	},
+	compareUrl(repository, from, to) {
+		return `${repository.webUrl}/compare/${from}...${to}`;
+	},
+	manualReleaseUrl(repository, release) {
+		const url = new URL(`${repository.webUrl}/releases/new`);
+		url.search = new URLSearchParams({
+			title: release.name,
+			body: release.body,
+			tag: release.tag,
+			prerelease: String(release.prerelease)
+		}).toString();
+		return url.toString();
+	},
+	async resolveAuthors(commits, repository, token, fetch) {
+		const headers = {
+			accept: "application/vnd.github.v3+json",
+			authorization: `token ${token}`
+		};
+		const authorsByEmail = new Map(commits.flatMap((commit) => commit.authors).map((author) => [author.email, author]));
+		await Promise.all([...authorsByEmail.values()].map(async (author) => {
+			try {
+				author.login = (await (await fetch(`https://api.github.com/search/users?q=${encodeURIComponent(`${author.email} type:user in:email`)}`, { headers })).json()).items?.[0]?.login;
+				const commit = commits.find((commit) => commit.authors[0].email === author.email);
+				if (!author.login && commit) author.login = (await (await fetch(`https://api.github.com/repos/${repository.path}/commits/${commit.hash}`, { headers })).json()).author?.login;
+			} catch {}
+		}));
+		for (const commit of commits) for (const author of commit.authors) author.login = authorsByEmail.get(author.email)?.login;
+	},
+	async publishRelease(repository, release, token, fetch) {
+		const headers = {
+			accept: "application/vnd.github+json",
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		};
+		const releasesUrl = `https://api.github.com/repos/${repository.path}/releases`;
+		const existing = await fetch(`${releasesUrl}/tags/${encodeURIComponent(release.tag)}`, { headers });
+		let url = releasesUrl;
+		let method = "POST";
+		let action = "created";
+		if (existing.ok) {
+			url = `${releasesUrl}/${(await existing.json()).id}`;
+			method = "PATCH";
+			action = "updated";
+		} else if (existing.status !== 404) throw new Error(`GitHub release lookup failed (${existing.status})`);
+		const response = await fetch(url, {
+			method,
+			headers,
+			body: JSON.stringify({
+				tag_name: release.tag,
+				name: release.name,
+				body: release.body,
+				prerelease: release.prerelease
+			})
+		});
+		if (!response.ok) throw new Error(`GitHub release publishing failed (${response.status})`);
+		return {
+			url: (await response.json()).html_url,
+			action
+		};
+	}
+};
+//#endregion
+//#region src/repository.ts
+const providers$1 = [githubProvider];
+async function resolveRepository(cwd) {
+	let source = await readFile(resolve(cwd, "package.json"), "utf8").then((contents) => {
+		const repository = JSON.parse(contents).repository;
+		return typeof repository === "string" ? repository : repository?.url || "";
+	}).catch(() => "");
+	if (!source) source = (await x("git", [
+		"remote",
+		"get-url",
+		"origin"
+	], { nodeOptions: { cwd } })).stdout.trim();
+	for (const provider of providers$1) {
+		const repository = provider.parse(source);
+		if (repository) return repository;
+	}
+}
+//#endregion
+//#region src/version.ts
+const providers = [{ async update(cwd, version) {
+	const path = resolve(cwd, "package.json");
+	const contents = await readFile(path, "utf8").catch((error) => {
+		if (error.code === "ENOENT") return;
+		throw error;
+	});
+	if (contents === void 0) return;
+	const packageJson = JSON.parse(contents);
+	if (packageJson.version === version) return path;
+	packageJson.version = version;
+	const indent = /\n([ \t]+)"/.exec(contents)?.[1] ?? "  ";
+	const newline = contents.endsWith("\n") ? "\n" : "";
+	await writeFile(path, `${JSON.stringify(packageJson, null, indent)}${newline}`);
+	return path;
+} }];
+async function updateVersion(cwd, version) {
+	for (const provider of providers) {
+		const path = await provider.update(cwd, version);
+		if (path) return path;
+	}
+}
+//#endregion
+//#region src/run.ts
+const defaultAuthor = "github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>";
+async function runChangelog(options, environment) {
+	const { version: version$1 } = options;
+	const tag = `v${version$1}`;
+	const gitIdentity = options.commit || options.release ? resolveGitIdentity(options.author) : [];
+	const env = environment.env ?? process.env;
+	const stdout = environment.stdout ?? ((value) => process.stdout.write(value));
+	const colors = environment.colors ?? ansis;
+	const latestTag = await getLatestTag(environment.cwd);
+	const repository = await resolveRepository(environment.cwd);
+	const token = repository?.provider.token(options.token, env);
+	if (options.release) {
+		if (!repository) throw new Error("A supported repository is required to release");
+		if (!repository.provider.publishRelease && !repository.provider.manualReleaseUrl) throw new Error(`${repository.provider.name} does not support releases`);
+	}
+	let taggedCommit = options.release ? await getTagCommit(environment.cwd, tag) : void 0;
+	let releaseRef = taggedCommit ? tag : void 0;
+	const remoteTaggedCommit = options.release ? await getRemoteTagCommit(environment.cwd, tag) : void 0;
+	if (taggedCommit && remoteTaggedCommit && taggedCommit !== remoteTaggedCommit) throw new Error(`Tag ${tag} differs between local and origin`);
+	if (remoteTaggedCommit && !taggedCommit) if (options.dry) {
+		taggedCommit = remoteTaggedCommit;
+		releaseRef = remoteTaggedCommit;
+	} else {
+		await git(environment.cwd, "fetch", "origin", `refs/tags/${tag}:refs/tags/${tag}`);
+		taggedCommit = await getTagCommit(environment.cwd, tag);
+		releaseRef = tag;
+	}
+	const from = taggedCommit ? await getPreviousTag(environment.cwd, tag, releaseRef) : latestTag;
+	const to = releaseRef || "HEAD";
+	const comparisonFrom = from || (repository ? (await git(environment.cwd, "rev-list", "--max-parents=0", to)).trim() : "");
+	const commits = await readCommits(environment.cwd, from, to);
+	if (token && repository && !(options.release && options.dry)) await repository.provider.resolveAuthors?.(commits, repository, token, environment.fetch ?? globalThis.fetch);
+	const { body: releaseBody, release } = createChangelog(version$1, commits, repository, comparisonFrom);
+	const repositoryRelease = {
+		tag,
+		name: tag,
+		body: releaseBody,
+		prerelease: version$1.includes("-")
+	};
+	const printReleasePreview = () => {
+		stdout([
+			colors.dim(`keep${colors.bold("changes")} v${version}`),
+			`${colors.cyan(from || comparisonFrom)}${colors.dim(" -> ")}${colors.blue(tag)}${colors.dim(` (${commits.length} commits)`)}`,
+			colors.dim("--------------"),
+			"",
+			releaseBody.replaceAll("&nbsp;", ""),
+			"",
+			colors.dim("--------------"),
+			""
+		].join("\n"));
+	};
+	const printManualReleaseUrl = () => {
+		const url = repository.provider.manualReleaseUrl?.(repository, repositoryRelease);
+		if (url) stdout(`${colors.yellow("Using the following link to create it manually:")}\n${colors.yellow(url)}\n`);
+		return url;
+	};
+	const publishRepositoryRelease = async () => {
+		printReleasePreview();
+		if (!token || !repository.provider.publishRelease) {
+			if (!repository.provider.manualReleaseUrl) throw new Error("A repository token is required to release");
+			stdout(`${colors.red(`No ${repository.provider.name} token found, specify it via GITHUB_TOKEN env. Release skipped.`)}\n\n`);
+			printManualReleaseUrl();
+			return;
+		}
+		const result = await repository.provider.publishRelease(repository, repositoryRelease, token, environment.fetch ?? globalThis.fetch);
+		stdout(`${colors.green(`${capitalize(result.action)} ${repository.provider.name} release: ${result.url}`)}\n`);
+	};
+	const outputPath = resolve(environment.cwd, options.output || "CHANGELOG.md");
+	const currentChangelog = await readChangelog(outputPath);
+	const releaseExists = hasRelease(currentChangelog, version$1);
+	const changelog = insertRelease(currentChangelog, release);
+	if (options.dry) {
+		if (options.release) {
+			printReleasePreview();
+			stdout(`${colors.yellow("Dry run. Release skipped.")}\n\n`);
+			printManualReleaseUrl();
+		} else stdout(changelog);
+		return;
+	}
+	if (options.release && taggedCommit) {
+		if (!remoteTaggedCommit) await git(environment.cwd, "push", "origin", `refs/tags/${tag}`);
+		await publishRepositoryRelease();
+		return;
+	}
+	await writeChangelog(outputPath, changelog);
+	const versionPath = await updateVersion(environment.cwd, version$1);
+	if (options.commit || options.release) {
+		const releasePaths = [outputPath, versionPath].filter((path) => path !== void 0);
+		if ((await git(environment.cwd, "status", "--porcelain", "--", ...releasePaths)).trim()) {
+			await git(environment.cwd, "add", "--", ...releasePaths);
+			const versionChanges = versionPath ? await git(environment.cwd, "status", "--porcelain", "--", versionPath) : "";
+			const commitMessage = versionPath && !versionChanges.trim() ? `docs(changelog): ${releaseExists ? "update" : "add"} v${version$1} release notes` : `chore(release): v${version$1}`;
+			await git(environment.cwd, ...gitIdentity, "commit", "-m", commitMessage, ...options.author ? ["--author", options.author] : [], "--only", "--", ...releasePaths);
+		}
+	}
+	if (options.release) {
+		await git(environment.cwd, ...gitIdentity, "tag", "-a", tag, "-m", tag);
+		await git(environment.cwd, "push", "origin", "HEAD", `refs/tags/${tag}`);
+		await publishRepositoryRelease();
+	}
+}
+function capitalize(value) {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function resolveGitIdentity(author = defaultAuthor) {
+	const match = /^(.+?)\s*<([^<>]+)>$/.exec(author);
+	if (!match) throw new Error("Author must use the \"Name <email>\" format");
+	return [
+		"-c",
+		`user.name=${match[1].trim()}`,
+		"-c",
+		`user.email=${match[2].trim()}`
+	];
+}
+//#endregion
+//#region src/cli.ts
+async function runCli(args, environment) {
+	const cli = cac("changelog").version(version).option("--output <path>", "Changelog file path").option("--dry", "Print the changelog without writing it").option("--commit", "Commit the changelog").option("--release", "Publish a repository release").option("--author <author>", "Commit author in \"Name <email>\" format").option("--token <token>", "Repository token for resolving authors").help();
+	cli.command("[version]").usage("<version> [options]").action(async (versionArgument, options) => {
+		if (!versionArgument) throw new Error("A release version is required");
+		await runChangelog({
+			version: versionArgument.replace(/^v/, ""),
+			output: options.output,
+			dry: options.dry,
+			commit: options.commit,
+			release: options.release,
+			author: options.author,
+			token: options.token
+		}, environment);
+	});
+	cli.parse([
+		"node",
+		"changelog",
+		...args
+	], { run: false });
+	await cli.runMatchedCommand();
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) runCli(process.argv.slice(2), { cwd: process.cwd() }).catch((error) => {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exitCode = 1;
+});
+//#endregion
+export { runCli };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "keepchanges",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "Generate and maintain CHANGELOG.md from Conventional Commits.",
+  "author": "edram",
+  "license": "MIT",
+  "homepage": "https://github.com/edram/gitchangelog#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edram/gitchangelog.git"
+  },
+  "bugs": {
+    "url": "https://github.com/edram/gitchangelog/issues"
+  },
+  "bin": {
+    "changelog": "./dist/cli.mjs"
+  },
+  "exports": {
+    ".": "./dist/cli.mjs",
+    "./cli": "./dist/cli.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "keywords": [
+    "changelog",
+    "cli",
+    "conventional-commits",
+    "git"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "bumpp": "^11.1.0",
+    "tsdown": "^0.22.5",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "ansis": "^4.3.1",
+    "cac": "^7.0.0",
+    "tinyexec": "^1.2.4",
+    "verkit": "^0.3.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "pnpm run build && vitest run",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp"
+  }
+}