@exadev/build-identity 2.0.0 → 2.1.0

package/README.md

@@ -23,6 +23,8 @@ const identity = resolveBuildIdentity(process.cwd(), 'exadev/build-identity');
 // { kind: 'commit', version: 'a1b2c3d', url: 'https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6...', date: '2026-09-08T09:12:03+01:00', commit: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2' }
 ```
 
+The same thing is available as a command, for build and deploy steps that cannot import anything -- see [`build-identity` (CLI)](#build-identity-cli).
+
 ## `resolveBuildIdentity(repoRoot, repoSlug, options?)`
 
 ```ts
@@ -116,10 +118,99 @@ const predictedVersion = await predictNextVersion(process.cwd(), releaseRules, a
 const identity = resolvePredictedIdentity(build, predictedVersion);
 ```
 
+## `build-identity` (CLI)
+
+The same three functions, wired together, as a command. It exists for build and deploy steps that are a shell invocation rather than a JavaScript config file, so nothing in them can `import` this package at all -- `wrangler deploy --var RELEASE_VERSION:...` being the case it was built for. A step that *is* a JavaScript config file (`next.config.ts`, `vite.config.ts`) should import the functions directly instead; see [Framework-agnosticism](#framework-agnosticism) below.
+
+```sh
+pnpm add -D @exadev/build-identity
+pnpm exec build-identity --repo exadev/build-identity
+```
+
+```
+Usage: build-identity [options]
+
+Options:
+  -V, --version                output the version number
+  --repo <owner/repo>          GitHub slug used to build the release and commit URLs
+  --root <directory>           git working tree to inspect (default: the current working directory)
+  --tag-name <template>        tag name marking a release, with {version} standing in for the version (default: v{version})
+  --predict                    also predict the version this commit's next release would be
+  --release-rules <json>       commit-analyzer release rules for --predict, as a JSON array
+  --release-rules-file <path>  file holding the same JSON array as --release-rules
+  --format <format>            output format: json or env (default: "json")
+  --prefix <prefix>            prepended to each variable name in --format env (default: "BUILD_")
+  --verbose                    send commit-analyzer's own per-commit narration to stderr
+  -h, --help                   display help for command
+```
+
+`--repo` is the only required flag, and the command's whole output is a single `DisplayIdentity` on stdout:
+
+```sh
+$ build-identity --repo exadev/build-identity
+{
+  "kind": "commit",
+  "version": "a1b2c3d",
+  "url": "https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
+  "date": "2026-09-08T09:12:03+01:00",
+  "commit": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+}
+```
+
+Those are exactly the five fields `DisplayIdentity` declares, under exactly its own names -- there is no CLI-specific shape and no consumer-specific naming. In particular there is no separate `predicted` boolean: `kind` is already `"predicted"` in precisely that case, and a second field asserting the same fact would just be one more thing that could disagree with the first.
+
+### Prediction
+
+`--predict` adds the `predictNextVersion` step, turning an unreleased build's short commit hash into the version that commit would release as. It is opt-in rather than automatic because it costs something real: it needs `@semantic-release/commit-analyzer` (this package's optional peer dependency) to be installed, and it reads every commit since the last tag.
+
+Release rules are yours, not this package's -- your repo's commit-type-to-release-level convention is real configuration, and nothing here invents a default for it. Pass them inline, or from a file when quoting a full rule set through YAML and a shell gets unreadable:
+
+```sh
+build-identity --repo exadev/build-identity --predict \
+  --release-rules '[{"breaking":true,"release":"major"},{"type":"feat","release":"minor"},{"type":"fix","release":"patch"}]'
+
+build-identity --repo exadev/build-identity --predict --release-rules-file release-rules.json
+```
+
+A confirmed release still wins outright: on a commit an actual release tag points at, `--predict` changes nothing at all.
+
+### `--format env`
+
+```sh
+$ build-identity --repo exadev/build-identity --format env --prefix RELEASE_
+RELEASE_KIND=commit
+RELEASE_VERSION=a1b2c3d
+RELEASE_URL=https://github.com/exadev/build-identity/commit/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
+RELEASE_DATE=2026-09-08T09:12:03+01:00
+RELEASE_COMMIT=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
+```
+
+The variable names are the same generic field names, upper-cased, behind a prefix of your choosing. This format is deliberately additional surface rather than "emit JSON and document a `jq` one-liner": appending to `$GITHUB_ENV` is the realistic use for both of the cases that motivated this CLI, and the one-liner alternative would put a `jq` dependency and a quoting-sensitive shell expression into every consumer's workflow to produce output this package can simply print. A value containing a line break is refused outright rather than emitted, since it would silently swallow or inject `$GITHUB_ENV` entries.
+
+```yaml
+- name: Resolve the build's identity
+  run: pnpm exec build-identity --repo my-org/my-repo --predict --release-rules-file release-rules.json --format env --prefix RELEASE_ >> "$GITHUB_ENV"
+
+- name: Deploy
+  run: wrangler deploy --var RELEASE_VERSION:$RELEASE_VERSION --var RELEASE_COMMIT:$RELEASE_COMMIT
+```
+
+Where a repo's own variable names differ from the generic ones, map them in that repo's own workflow rather than expecting this package to know them -- `--prefix` covers most of it, and `jq` covers the rest:
+
+```sh
+echo "MY_OWN_VERSION_NAME=$(build-identity --repo my-org/my-repo | jq -r .version)" >> "$GITHUB_ENV"
+```
+
+`--verbose` routes commit-analyzer's own per-commit narration to **stderr**, never stdout, so it is always safe to pipe or capture stdout while debugging why a prediction came out as it did.
+
+The CLI is the one part of this package with a runtime dependency (`commander`, itself dependency-free). It is bundled into `dist/cli.js` alone: importing the library never loads it. It stays on `commander@14` deliberately, rather than the newest major: `commander@15` raises its own floor to Node 22.12, which would contradict this package's declared `engines` of Node 20 and upwards. Raise it alongside that floor, not before it.
+
 ## Framework-agnosticism
 
 This package does pure Node.js filesystem and git access only -- no bundler, framework, or UI assumptions. Wiring its result into a running app is a build-time concern for whichever bundler that app already uses, done in that bundler's own config file, not in this package.
 
+**A config file that is itself JavaScript does not need the CLI** -- it can import the functions directly, which is both simpler and better typed than shelling out and parsing JSON back. Reach for `build-identity` (above) only where there is genuinely nothing to import from: a `wrangler deploy --var ...` line, a `docker build --build-arg ...` line, a plain `sh` deploy script.
+
 ### Next.js
 
 ```ts

package/dist/cli.js

@@ -0,0 +1,379 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { format } from "node:util";
+import { Command, InvalidArgumentError, Option } from "commander";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region package.json
+var version = "2.1.0";
+//#endregion
+//#region src/format-identity.ts
+const OUTPUT_FORMATS = ["json", "env"];
+function isOutputFormat(value) {
+	return value === "json" || value === "env";
+}
+/** Every field of `DisplayIdentity`, in the order it is declared there. The `env` format derives its variable names by upper-casing these directly, so there is no second name mapping that could drift out of step with the type itself. */
+const IDENTITY_FIELDS = [
+	"kind",
+	"version",
+	"url",
+	"date",
+	"commit"
+];
+/** A prefix is glued straight onto an already-upper-case field name, so it only has to keep the result a legal shell/GitHub Actions variable name. An empty prefix is legitimate (bare `KIND=`, `VERSION=`, ...) for a caller that genuinely wants the unprefixed names. */
+const ENV_PREFIX_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$|^$/;
+function isEnvPrefix(value) {
+	return ENV_PREFIX_PATTERN.test(value);
+}
+/**
+* Renders a resolved identity for stdout, in whichever of the two formats the caller asked for.
+*
+* `json` emits the `DisplayIdentity` object verbatim -- the same five field names the library's own type declares, with no CLI-invented additions. In particular there is no separate `predicted` boolean: `kind` is already `'predicted'` in exactly that case, and a second field asserting the same fact would be one more thing every writer has to keep in step.
+*
+* `env` emits one `PREFIX_FIELD=value` line per field, upper-cased, ready to append straight to `$GITHUB_ENV` (or `eval`/`source` in a plain shell). Each repo maps these generic names onto whatever it calls them itself; this package never emits a consumer-specific name.
+*/
+function formatIdentity(identity, options) {
+	if (options.format === "json") return JSON.stringify(identity, null, 2);
+	if (!isEnvPrefix(options.prefix)) throw new Error(`--prefix must be empty or a legal variable-name prefix ([A-Za-z_][A-Za-z0-9_]*), got: ${JSON.stringify(options.prefix)}`);
+	return IDENTITY_FIELDS.map((field) => {
+		const value = identity[field];
+		if (/[\r\n]/.test(value)) throw new Error(`${field} contains a line break, which cannot be represented as a KEY=VALUE line: ${JSON.stringify(value)}`);
+		return `${options.prefix}${field.toUpperCase()}=${value}`;
+	}).join("\n");
+}
+//#endregion
+//#region src/load-commit-analyzer.ts
+const COMMIT_ANALYZER_SPECIFIER = "@semantic-release/commit-analyzer";
+function hasAnalyzeCommits(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("analyzeCommits" in value)) return false;
+	return typeof value.analyzeCommits === "function";
+}
+/**
+* Loads `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- the tested, correct way to obtain the `AnalyzeCommits` implementation `predictNextVersion` (`./predict-next-version`) needs. Split out from `predictNextVersion` itself so that function stays a pure, easily-fakeable function of its own arguments; this is the one place in the package that actually touches the untyped module.
+*
+* `@semantic-release/commit-analyzer` is an optional peer dependency (see this package's own `package.json`): not required to use `resolveBuildIdentity`/`resolvePredictedIdentity`, only to call this function. Throws a clear error, rather than a bare "Cannot find module", when it isn't installed or doesn't export `analyzeCommits` -- a version bump of the real package removing or renaming that export fails loudly here, not silently.
+*/
+async function loadCommitAnalyzer() {
+	let commitAnalyzerModule;
+	try {
+		commitAnalyzerModule = await import(COMMIT_ANALYZER_SPECIFIER);
+	} catch (error) {
+		throw new Error("@semantic-release/commit-analyzer is not installed -- it is an optional peer dependency of @exadev/build-identity, required only for loadCommitAnalyzer/predictNextVersion.", { cause: error });
+	}
+	if (!hasAnalyzeCommits(commitAnalyzerModule)) throw new Error("@semantic-release/commit-analyzer has no analyzeCommits export.");
+	return commitAnalyzerModule.analyzeCommits;
+}
+//#endregion
+//#region src/package-version.ts
+/** Turns a version into the tag name expected to mark its release -- the shared default (and shared option shape) both `resolveBuildIdentity` and `predictNextVersion` accept, so a repo that tags differently only has to say so once per call site, not maintain two independent conventions. */
+function defaultTagName(version) {
+	return `v${version}`;
+}
+function isPackageJsonWithVersion(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("version" in value)) return false;
+	return typeof value.version === "string" && value.version.length > 0;
+}
+/** The single semantic-release-managed version, read from `package.json` at `repoRoot`'s root -- shared by `resolveBuildIdentity` (what this build's version is, if released) and `predictNextVersion` (the version to diff commits since). Throws rather than defaulting, matching this package's own "no sensible placeholder identity" stance. */
+function readPackageVersion(repoRoot) {
+	const packageJsonPath = join(repoRoot, "package.json");
+	const raw = readFileSync(packageJsonPath, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!isPackageJsonWithVersion(parsed)) throw new Error(`${packageJsonPath} must contain a non-empty string "version" field`);
+	return parsed.version;
+}
+//#endregion
+//#region src/predict-next-version.ts
+const GIT_FORMAT = "%x00%H%x00%B";
+const FIELD_SEP = "\0";
+/**
+* Pure parsing of `git log --format=%x00%H%x00%B` output -- split out so it's testable against a raw string fixture with no real git process. NUL is git's own pretty-format escape for a real NUL byte, the one byte git guarantees can never appear inside a commit hash or message (git refuses to store one), making it the only delimiter genuinely safe against arbitrary commit content. Each record is `<hash><NUL><message>`, with a leading NUL on the whole format string, so splitting the entire raw output on NUL and dropping the resulting leading empty token leaves an exact (hash, message) pairing for every commit. Git appends its own trailing newline per record (tformat behaviour); trim() absorbs it the same way it absorbs genuine trailing blank lines in a real commit body.
+*/
+function parseGitLogOutput(raw) {
+	const tokens = raw.split(FIELD_SEP);
+	tokens.shift();
+	const commits = [];
+	for (let index = 0; index < tokens.length; index += 2) commits.push({
+		hash: tokens[index] ?? "",
+		message: (tokens[index + 1] ?? "").trim()
+	});
+	return commits;
+}
+function readCommitsSince(repoRoot, sinceTag) {
+	return parseGitLogOutput(execFileSync("git", [
+		"log",
+		`${sinceTag}..HEAD`,
+		`--format=${GIT_FORMAT}`
+	], {
+		cwd: repoRoot,
+		encoding: "utf-8"
+	}));
+}
+function isReleaseLevel(value) {
+	return value === "major" || value === "minor" || value === "patch";
+}
+/** A trivial major.minor.patch increment -- every version this package works with is a plain X.Y.Z, never a prerelease or build-metadata identifier (see `resolveBuildIdentity`'s own tag convention), so there is no broader semver grammar here worth delegating to a library for. */
+function bumpVersion(version, releaseType) {
+	const [major = 0, minor = 0, patch = 0] = version.split(".").map(Number);
+	if (releaseType === "major") return `${String(major + 1)}.0.0`;
+	if (releaseType === "minor") return `${String(major)}.${String(minor + 1)}.0`;
+	return `${String(major)}.${String(minor)}.${String(patch + 1)}`;
+}
+const NOOP_LOGGER = {
+	log: () => void 0,
+	error: () => void 0
+};
+/**
+* Predicts the version this repo's next release would be, from commits since the last tagged release -- WITHOUT running semantic-release's own top-level orchestrator. That orchestrator's core (not any plugin) verifies push access to the remote as part of resolving branches before analysis ever runs: genuinely slow, and needing credentials a prediction has no real reason to hold. This calls `analyzeCommits` directly instead -- no network, no registry lookups -- exactly the same hook `@semantic-release/commit-analyzer` exports, supplied by the caller (see `AnalyzeCommits`'s own doc comment for why this package never imports that module itself).
+*
+* Returns `undefined` when there is genuinely no predicted release -- no commits since the last tag, or none of them are release-worthy under `releaseRules` -- the same "nothing to report" case `resolvePredictedIdentity` already treats as valid, not an error. Throws for a genuine setup problem instead of defaulting: `repoRoot` isn't a git repository, or `package.json` has no usable version.
+*
+* @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root, same as `resolveBuildIdentity`).
+* @param releaseRules The commit-analyzer release rules this repo's own commit convention defines.
+* @param analyzeCommits `@semantic-release/commit-analyzer`'s own `analyzeCommits` export -- `loadCommitAnalyzer` (`./load-commit-analyzer`) is the tested way to obtain one.
+*/
+async function predictNextVersion(repoRoot, releaseRules, analyzeCommits, options = {}) {
+	const lastVersion = readPackageVersion(repoRoot);
+	const tagName = (options.tagName ?? defaultTagName)(lastVersion);
+	const logger = options.logger ?? NOOP_LOGGER;
+	const commits = readCommitsSince(repoRoot, tagName);
+	if (commits.length === 0) return;
+	const releaseType = await analyzeCommits({ releaseRules: releaseRules.map((rule) => ({ ...rule })) }, {
+		commits,
+		logger,
+		cwd: repoRoot
+	});
+	if (!isReleaseLevel(releaseType)) return;
+	return bumpVersion(lastVersion, releaseType);
+}
+//#endregion
+//#region src/parse-release-rules.ts
+function isUnknownArray(value) {
+	return Array.isArray(value);
+}
+function isReleaseValue(value) {
+	return value === false || isReleaseLevel(value);
+}
+function isReleaseRule(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("release" in value) || !isReleaseValue(value.release)) return false;
+	if ("breaking" in value) return value.breaking === true;
+	if (!("type" in value)) return false;
+	return typeof value.type === "string" && value.type.length > 0;
+}
+/**
+* Validates a JSON array of `@semantic-release/commit-analyzer` release rules supplied on the command line, into the `ReleaseRule[]` `predictNextVersion` takes.
+*
+* The library deliberately hardcodes no rules of its own -- a repo's commit-type-to-release-level convention is real, repo-specific configuration -- so the CLI cannot either, and this is the only route by which it learns them. Every failure names `source` (the flag or file path the JSON came from) so a malformed rule set is traceable back to whichever of the two supplied it.
+*/
+function parseReleaseRules(raw, source) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw new Error(`${source} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+	if (!isUnknownArray(parsed)) throw new Error(`${source} must be a JSON array of commit-analyzer release rules, e.g. [{"breaking":true,"release":"major"},{"type":"feat","release":"minor"}]`);
+	const rules = [];
+	for (const [index, entry] of parsed.entries()) {
+		if (!isReleaseRule(entry)) throw new Error(`${source}: entry ${String(index)} must be {"type":<string>,"release":"major"|"minor"|"patch"|false} or {"breaking":true,"release":"major"|"minor"|"patch"|false}, got: ${JSON.stringify(entry)}`);
+		rules.push(entry);
+	}
+	return rules;
+}
+//#endregion
+//#region src/git.ts
+function runGit(repoRoot, args) {
+	return execFileSync("git", args, {
+		cwd: repoRoot,
+		encoding: "utf8"
+	}).trim();
+}
+/**
+* Reads HEAD's full hash, short hash, and author date from the given git working tree. Author date, not committer date: a rebase-merged commit keeps its original author date but gets a fresh committer date at rebase time, and every consumer of this identity treats the date as "when this commit was authored", not "when it was last rewritten onto its current position". Throws whatever `git` itself throws (e.g. `repoRoot` is not a git repository, or has no commits) -- there is no sensible default identity for a build that isn't sitting in real git history.
+*/
+function getHeadCommit(repoRoot) {
+	return {
+		fullSha: runGit(repoRoot, ["rev-parse", "HEAD"]),
+		shortSha: runGit(repoRoot, [
+			"rev-parse",
+			"--short",
+			"HEAD"
+		]),
+		date: runGit(repoRoot, [
+			"log",
+			"-1",
+			"--format=%aI",
+			"HEAD"
+		])
+	};
+}
+/**
+* True only if `tagName` both exists and points at the exact commit HEAD is on right now. Uses `git tag --list <tag> --points-at HEAD`, which returns `tagName` itself when both hold and nothing otherwise -- there is no separate "tag exists but points elsewhere" case to confuse this with.
+*/
+function tagPointsAtHead(repoRoot, tagName) {
+	return runGit(repoRoot, [
+		"tag",
+		"--list",
+		tagName,
+		"--points-at",
+		"HEAD"
+	]).split("\n").map((line) => line.trim()).includes(tagName);
+}
+//#endregion
+//#region src/resolve-build-identity.ts
+const REPO_SLUG_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+function assertRepoSlug(repoSlug) {
+	if (!REPO_SLUG_PATTERN.test(repoSlug)) throw new Error(`repoSlug must be a GitHub "owner/repo" slug, got: ${JSON.stringify(repoSlug)}`);
+}
+/**
+* Resolves what the current build actually is: a real, already-tagged release, or a build made from a commit that hasn't been released yet.
+*
+* This is the one property the whole package exists to guarantee: `kind: 'release'` is returned if and only if a tag named `tagName(version)` (default `v${version}`) provably points at the exact commit HEAD is on right now, checked live against git -- never inferred from `package.json` alone, a CI environment variable, or any other proxy that could be true before the tag actually exists. A caller can render `url` as a link the moment it gets a result back, in either case, without first checking whether that link is real.
+*
+* @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root).
+* @param repoSlug The GitHub `owner/repo` slug used to build both release and commit URLs.
+*/
+function resolveBuildIdentity(repoRoot, repoSlug, options = {}) {
+	assertRepoSlug(repoSlug);
+	const version = readPackageVersion(repoRoot);
+	const tagName = (options.tagName ?? defaultTagName)(version);
+	const head = getHeadCommit(repoRoot);
+	if (tagPointsAtHead(repoRoot, tagName)) return {
+		kind: "release",
+		version,
+		url: `https://github.com/${repoSlug}/releases/tag/${tagName}`,
+		date: head.date,
+		commit: head.fullSha
+	};
+	return {
+		kind: "commit",
+		version: head.shortSha,
+		url: `https://github.com/${repoSlug}/commit/${head.fullSha}`,
+		date: head.date,
+		commit: head.fullSha
+	};
+}
+//#endregion
+//#region src/resolve-predicted-identity.ts
+/**
+* Upgrades an unreleased build's displayed version to a predicted one (e.g. the version `predictNextVersion` computes the next release will be), without ever upgrading its URL.
+*
+* A confirmed release always wins outright: if `build.kind === 'release'`, this returns `build` completely unchanged, prediction or not -- a real, already-tagged release can never be second-guessed by a prediction. Otherwise, when `predictedVersion` is a real, non-empty string, the result is `kind: 'predicted'` with `version` set to that predicted label -- `url`/`date`/`commit` are copied verbatim from `build`, still describing the real commit, never a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged (still a valid `DisplayIdentity`, since every `BuildIdentity` kind is also a `DisplayIdentity` kind).
+*
+* This function does no git or filesystem access of its own: predicting the next version is entirely the caller's job, typically `predictNextVersion` (`./predict-next-version`). It exists to keep that prediction, and the guarantee `resolveBuildIdentity` makes about `url`, cleanly separate.
+*/
+function resolvePredictedIdentity(build, predictedVersion) {
+	if (build.kind === "release") return build;
+	const trimmedPrediction = predictedVersion?.trim();
+	if (trimmedPrediction === void 0 || trimmedPrediction.length === 0) return build;
+	return {
+		kind: "predicted",
+		version: trimmedPrediction,
+		url: build.url,
+		date: build.date,
+		commit: build.commit
+	};
+}
+//#endregion
+//#region src/cli-program.ts
+const VERSION_PLACEHOLDER = "{version}";
+const DEFAULT_TAG_TEMPLATE = `v${VERSION_PLACEHOLDER}`;
+const DEFAULT_ENV_PREFIX = "BUILD_";
+/** `predictNextVersion` narrates through a caller-supplied logger and explicitly warns against routing it to stdout, which carries the machine-readable result. `--verbose` sends it to stderr instead, so a CI step can see why a prediction came out the way it did without contaminating what the next step parses. */
+const STDERR_LOGGER = {
+	log: (...args) => {
+		writeStderr(args);
+	},
+	error: (...args) => {
+		writeStderr(args);
+	}
+};
+function writeStderr(args) {
+	process.stderr.write(`${format(...args)}\n`);
+}
+/**
+* A `{version}` template rather than a function, since a command line cannot carry one: `resolveBuildIdentity` and `predictNextVersion` are both given the same resulting function, keeping "which tag marks a release" one convention across the two calls exactly as the library's own docs advise.
+*/
+function parseTagTemplate(template) {
+	if (!template.includes(VERSION_PLACEHOLDER)) throw new InvalidArgumentError(`--tag-name must contain the ${VERSION_PLACEHOLDER} placeholder, got: ${JSON.stringify(template)}`);
+	return (version) => template.replaceAll(VERSION_PLACEHOLDER, version);
+}
+function parseFormat(value) {
+	if (!isOutputFormat(value)) throw new InvalidArgumentError(`--format must be one of: ${OUTPUT_FORMATS.join(", ")}`);
+	return value;
+}
+function parsePrefix(value) {
+	if (!isEnvPrefix(value)) throw new InvalidArgumentError(`--prefix must be empty or a legal variable-name prefix ([A-Za-z_][A-Za-z0-9_]*), got: ${JSON.stringify(value)}`);
+	return value;
+}
+function parseInlineReleaseRules(value) {
+	try {
+		return parseReleaseRules(value, "--release-rules");
+	} catch (cause) {
+		throw new InvalidArgumentError(cause instanceof Error ? cause.message : String(cause));
+	}
+}
+function readReleaseRulesFile(path) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (cause) {
+		throw new Error(`--release-rules-file ${path} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+	return parseReleaseRules(raw, `--release-rules-file ${path}`);
+}
+/**
+* The whole CLI as a function of its already-parsed flags: resolves the identity and returns the exact text the command prints, so the wiring between the library's three functions is testable without a subprocess and without capturing stdout.
+*
+* Prediction is gated behind `--predict` rather than inferred: it needs `@semantic-release/commit-analyzer`, an optional peer dependency of this package, and reads the whole commit range since the last tag. Both are real costs a caller that only wants `resolveBuildIdentity`'s answer should not silently pay.
+*/
+async function runBuildIdentity(flags) {
+	if (flags.releaseRules !== void 0 && flags.releaseRulesFile !== void 0) throw new Error("--release-rules and --release-rules-file are alternatives; pass one, not both");
+	const rules = flags.releaseRules ?? (flags.releaseRulesFile === void 0 ? void 0 : readReleaseRulesFile(flags.releaseRulesFile));
+	if (flags.predict === true && rules === void 0) throw new Error("--predict needs this repo's own commit-type release rules: pass --release-rules or --release-rules-file");
+	if (flags.predict !== true && rules !== void 0) throw new Error("--release-rules/--release-rules-file only take effect with --predict, which was not passed");
+	const build = resolveBuildIdentity(flags.root, flags.repo, { tagName: flags.tagName });
+	let predictedVersion;
+	if (rules !== void 0) {
+		const options = {
+			tagName: flags.tagName,
+			...flags.verbose === true ? { logger: STDERR_LOGGER } : {}
+		};
+		predictedVersion = await predictNextVersion(flags.root, rules, await loadCommitAnalyzer(), options);
+	}
+	return formatIdentity(resolvePredictedIdentity(build, predictedVersion), {
+		format: flags.format,
+		prefix: flags.prefix
+	});
+}
+/**
+* Builds the commander program without parsing argv or exiting the process, so the command tree stays testable in isolation. There is no subcommand: the package does exactly one thing, and a subcommand naming it again would be pure ceremony.
+*/
+function createProgram() {
+	const program = new Command("build-identity");
+	program.description("Resolve a build's true identity -- a real, already-tagged release, or the commit it was built from -- from live git state, with an optional predicted-version display layer.");
+	program.version(version);
+	program.requiredOption("--repo <owner/repo>", "GitHub slug used to build the release and commit URLs, e.g. exadev/build-identity");
+	program.addOption(new Option("--root <directory>", "git working tree to inspect; must contain package.json at its root").default(process.cwd(), "the current working directory"));
+	program.addOption(new Option("--tag-name <template>", `tag name marking a release, with ${VERSION_PLACEHOLDER} standing in for the version`).argParser(parseTagTemplate).default(defaultTagName, DEFAULT_TAG_TEMPLATE));
+	program.option("--predict", "also predict the version this commit's next release would be, and show that instead of a bare commit hash when there is no release tag on HEAD");
+	program.option("--release-rules <json>", "commit-analyzer release rules for --predict, as a JSON array", parseInlineReleaseRules);
+	program.option("--release-rules-file <path>", "file holding the same JSON array as --release-rules, for a rule set too awkward to quote inline");
+	program.option("--format <format>", `output format: ${OUTPUT_FORMATS.join(" or ")}`, parseFormat, "json");
+	program.option("--prefix <prefix>", "prepended to each variable name in --format env", parsePrefix, DEFAULT_ENV_PREFIX);
+	program.option("--verbose", "send commit-analyzer's own per-commit narration to stderr");
+	program.action(async (flags) => {
+		process.stdout.write(`${await runBuildIdentity(flags)}\n`);
+	});
+	return program;
+}
+//#endregion
+//#region src/cli.ts
+createProgram().parseAsync(process.argv).catch((cause) => {
+	process.stderr.write(`build-identity: ${cause instanceof Error ? cause.stack ?? cause.message : String(cause)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exadev/build-identity",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Resolve a build's true identity (a real release tag, or the commit it was built from) from git state, with an optional predicted-version display layer",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "bin": {
+    "build-identity": "./dist/cli.js"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -33,7 +36,8 @@
     "version",
     "git",
     "release",
-    "commit"
+    "commit",
+    "cli"
   ],
   "repository": {
     "type": "git",
@@ -80,5 +84,8 @@
     "prepublishOnly": "pnpm run lint && pnpm run typecheck && pnpm run test && tsdown && publint && attw --pack",
     "prepare": "husky",
     "release": "semantic-release"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
   }
 }