@astra-kit/rp 0.0.0-stage → 0.10.0

package/src/build-gate.js

@@ -0,0 +1,157 @@
+/**
+ * Decides whether Vercel builds a commit (`vercel.json` → `ignoreCommand`).
+ *
+ * Only a stable `X.Y.Z` version that is the next patch, minor or major of the
+ * previous commit's version ships, the same rule `create-version` applies. An
+ * unchanged, lower or skipped version (`1.0.0` → `3.0.0`) and any prerelease
+ * or build-metadata version skip the build. When the previous version cannot
+ * be read there is nothing to compare, so a stable version builds.
+ *
+ * A release delegated to CI is skipped only on the commit that changes
+ * `.astra-rp/release.json` against its first parent, the same commit scoping the
+ * generated `.astra-rp/vercel-ignore-build.mjs` applies (that template stays
+ * dependency-free, so it inlines the check). Later commits keep the metadata
+ * untouched and fall through to the version rule. Without a readable parent
+ * (shallow clone or first commit) the release commit is recognized by its own
+ * `Astra-Rp-Execution: ci` trailer, which later commits never carry, so the
+ * deployment still waits for the release workflow.
+ *
+ * @module build-gate
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { CURRENT_REVISION, GIT_DIFF_CHANGED_STATUS, PACKAGE_MANIFEST_FILE, PREVIOUS_REVISION } from "./constants/build-gate.js";
+import { isStableReleaseVersion, listAllowedVersionsAfter } from "./versions.js";
+import { CI_RELEASE_METADATA_FILE, RELEASE_EXECUTION, RELEASE_EXECUTION_TRAILER } from "./constants/ci-release.js";
+
+/**
+ * @typedef {{ shouldBuild: boolean, reason: string }} BuildDecision
+ */
+
+/**
+ * Decides whether a commit is built.
+ *
+ * @param {string | null} previousVersion - Version of the previous commit, or `null` when unreadable.
+ * @param {string | null} currentVersion - Version of the commit being deployed, or `null` when unreadable.
+ * @returns {BuildDecision} Decision and a log line.
+ */
+export function decideBuild(previousVersion, currentVersion) {
+  if (currentVersion === null) {
+    return { shouldBuild: false, reason: "Current package version could not be read. Skipping build." };
+  }
+
+  if (!isStableReleaseVersion(currentVersion)) {
+    return { shouldBuild: false, reason: `Version ${currentVersion} is not a stable X.Y.Z release. Skipping build.` };
+  }
+
+  const allowedVersions = previousVersion === null ? null : listAllowedVersionsAfter(previousVersion);
+
+  if (allowedVersions === null) {
+    return { shouldBuild: true, reason: `Previous package version could not be compared. Building stable ${currentVersion}.` };
+  }
+
+  if (currentVersion === previousVersion) {
+    return { shouldBuild: false, reason: "Version did not change. Skipping build." };
+  }
+
+  if (!allowedVersions.includes(currentVersion)) {
+    return {
+      shouldBuild: false,
+      reason: `Version ${previousVersion} -> ${currentVersion} is not the next patch, minor or major (${allowedVersions.join(", ")}). Skipping build.`,
+    };
+  }
+
+  return { shouldBuild: true, reason: `Version changed: ${previousVersion} -> ${currentVersion}. Building.` };
+}
+
+/**
+ * Reads the `version` field of a `package.json` text.
+ *
+ * @param {() => string} readManifest - Returns the manifest contents.
+ * @returns {string | null} Version, or `null` when unreadable.
+ */
+function readVersion(readManifest) {
+  try {
+    const version = JSON.parse(readManifest()).version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Tells whether the deployed commit carries exactly one `Astra-Rp-Execution: ci`
+ * trailer, the commit-local mark `create-version` writes in a release delegated
+ * to CI. A Git failure counts as "no trailer".
+ *
+ * @param {string} repositoryRoot - Checkout whose `HEAD` is being deployed.
+ * @returns {boolean} Whether `HEAD` declares a CI release execution.
+ */
+function hasCiReleaseTrailer(repositoryRoot) {
+  const trailers = spawnSync("git", ["log", "-1", `--format=%(trailers:key=${RELEASE_EXECUTION_TRAILER},valueonly=true)`, CURRENT_REVISION], {
+    cwd: repositoryRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    windowsHide: true,
+  });
+  if (trailers.status !== 0) return false;
+  const recordedValues = [...new Set(trailers.stdout.split("\n").map((value) => value.trim()).filter(Boolean))];
+  return recordedValues.length === 1 && recordedValues[0] === RELEASE_EXECUTION.ci;
+}
+
+/**
+ * Tells whether the deployed commit is the one that wrote the CI release
+ * metadata. With a readable first parent it compares the metadata against it;
+ * without one (first commit or shallow clone) it relies on the release commit's
+ * own `Astra-Rp-Execution: ci` trailer, so the CI gate holds in shallow checkouts.
+ *
+ * @param {string} repositoryRoot - Checkout whose `HEAD` is being deployed.
+ * @returns {boolean} Whether `HEAD` is the CI release commit.
+ */
+function isReleaseMetadataCommit(repositoryRoot) {
+  const parentLookup = spawnSync("git", ["rev-parse", "--verify", "--quiet", `${PREVIOUS_REVISION}^{commit}`], {
+    cwd: repositoryRoot,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  if (parentLookup.status !== 0) return hasCiReleaseTrailer(repositoryRoot);
+  const metadataDiff = spawnSync("git", ["diff", "--quiet", PREVIOUS_REVISION, CURRENT_REVISION, "--", CI_RELEASE_METADATA_FILE], {
+    cwd: repositoryRoot,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  return metadataDiff.status === GIT_DIFF_CHANGED_STATUS;
+}
+
+/**
+ * Reads the previous and the current `package.json` versions of a Git
+ * checkout and decides whether it is built.
+ *
+ * @param {string} repositoryRoot - Checkout whose `HEAD` is being deployed.
+ * @returns {BuildDecision} Decision and a log line.
+ */
+export function decideBuildForCheckout(repositoryRoot) {
+  const previousVersion = readVersion(() =>
+    execFileSync("git", ["show", `${PREVIOUS_REVISION}:${PACKAGE_MANIFEST_FILE}`], {
+      cwd: repositoryRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+  );
+  const currentVersion = readVersion(() => readFileSync(path.join(repositoryRoot, PACKAGE_MANIFEST_FILE), "utf8"));
+  const metadataPath = path.join(repositoryRoot, CI_RELEASE_METADATA_FILE);
+  if (existsSync(metadataPath)) {
+    try {
+      const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+      const isDelegatedRelease = metadata.version === currentVersion && metadata.execution === RELEASE_EXECUTION.ci;
+      if (isDelegatedRelease && isReleaseMetadataCommit(repositoryRoot)) return { shouldBuild: false, reason: `Release ${currentVersion} is delegated to CI. Production deployment waits for its checks. Skipping build.` };
+    } catch {
+      return { shouldBuild: false, reason: "CI release metadata could not be read. Skipping build." };
+    }
+  }
+
+  return decideBuild(previousVersion, currentVersion);
+}

package/src/changelog-blocks.js

@@ -0,0 +1,53 @@
+/**
+ * Internal helpers that split `CHANGELOG.md` into release blocks and rewrite the `[Unreleased]`
+ * block. Shared by the public `@astra-kit/rp/changelog` module and by `create-version`; not part of the
+ * package's public API (no `exports` entry and no reexport from `@astra-kit/rp`).
+ *
+ * @module changelog-blocks
+ */
+
+import { CHANGELOG_TITLE, RELEASE_HEADING_PATTERN, UNRELEASED_HEADING, UNRELEASED_LINE_PATTERN } from "./constants/changelog.js";
+
+/**
+ * @typedef {{ label: string, heading: string, start: number, bodyStart: number, end: number }} ChangelogBlock
+ */
+
+/**
+ * Splits the changelog into release blocks in document order.
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @returns {ChangelogBlock[]} Blocks.
+ */
+export function listBlocks(changelog) {
+  const headings = [...changelog.matchAll(RELEASE_HEADING_PATTERN)];
+  return headings.map((match, index) => {
+    const start = match.index ?? 0;
+    return {
+      label: match[1],
+      heading: match[0],
+      start,
+      bodyStart: start + match[0].length,
+      end: headings[index + 1]?.index ?? changelog.length,
+    };
+  });
+}
+
+/**
+ * Replaces the `[Unreleased]` block with `body`, or inserts the block above the newest release.
+ *
+ * @param {string} changelog - Existing contents, or an empty string for a new file.
+ * @param {string} body - New block body, already using `lineBreak`.
+ * @param {string} lineBreak - Line break written around the body.
+ * @returns {string} Changelog with the new `[Unreleased]` block.
+ */
+export function replaceUnreleasedBody(changelog, body, lineBreak) {
+  const replacement = `${UNRELEASED_HEADING}${lineBreak}${lineBreak}${body}${lineBreak}${lineBreak}`;
+  const blocks = listBlocks(changelog);
+  const unreleased = blocks.find((block) => UNRELEASED_LINE_PATTERN.test(block.heading));
+  if (unreleased) {
+    return `${changelog.slice(0, unreleased.start)}${replacement}${changelog.slice(unreleased.end)}`;
+  }
+  const insertion = blocks[0]?.start ?? changelog.length;
+  const prefix = changelog.slice(0, insertion).trimEnd() || CHANGELOG_TITLE;
+  return `${prefix}${lineBreak}${lineBreak}${replacement}${changelog.slice(insertion)}`;
+}

package/src/changelog.js

@@ -0,0 +1,108 @@
+/**
+ * Generates CHANGELOG.md entries from commits and releases `[Unreleased]`.
+ *
+ * A release lists the hash and original subject of every commit since the
+ * previous version, then moves the block under `## [X.Y.Z] - YYYY-MM-DD`.
+ * Published history, including legacy unbracketed headings, is preserved.
+ *
+ * `astra-rp create-version` does not generate entries from commits: it requires entries under
+ * `[Unreleased]`, written by hand or, with `changelogDraft`, drafted by an agent CLI, and in the
+ * release commit only renames that heading to `## [X.Y.Z] - YYYY-MM-DD` and adds an empty
+ * `[Unreleased]` on top, keeping any section names.
+ *
+ * @module changelog
+ */
+
+import { listBlocks, replaceUnreleasedBody } from "./changelog-blocks.js";
+import {
+  CHANGE_TYPES,
+  ENTRY_LINE_PATTERN,
+  LEADING_WHITESPACE_PATTERN,
+  LINE_BREAK_PATTERN,
+  SECTION_HEADING_PATTERN,
+  COMMIT_SHORT_SHA_LENGTH,
+  LF_LINE_BREAK,
+  UNRELEASED_HEADING,
+  UNRELEASED_LINE_PATTERN,
+} from "./constants/changelog.js";
+
+/**
+ * Replaces `[Unreleased]` with the exact commit list for the next version.
+ * Creates the block or document when missing and preserves released history.
+ *
+ * @param {string} changelog - Existing contents, or an empty string for a new file.
+ * @param {{ sha: string, subject: string }[]} commits - Commits since the previous release, newest first.
+ * @returns {string} Changelog with one hash and original subject per commit.
+ * @throws {Error} When there are no commits to release.
+ */
+export function fillUnreleasedFromCommits(changelog, commits) {
+  if (commits.length === 0) throw new Error("create-version: no commits available to generate CHANGELOG.md");
+  const body = commits.map((commit) => `- ${commit.sha.slice(0, COMMIT_SHORT_SHA_LENGTH)} ${commit.subject}`).join(LF_LINE_BREAK);
+  return replaceUnreleasedBody(changelog, body, LF_LINE_BREAK);
+}
+
+/**
+ * @typedef {import("./changelog-blocks.js").ChangelogBlock} ChangelogBlock
+ * @typedef {{ exists: boolean, entryCount: number, unknownSections: string[], body: string }} UnreleasedState
+ */
+
+/**
+ * Counts the change entries of a block body.
+ *
+ * @param {string} body - Block text below its heading.
+ * @returns {number} Number of `- ` lines.
+ */
+function countEntries(body) {
+  return body.split(LINE_BREAK_PATTERN).filter((line) => ENTRY_LINE_PATTERN.test(line)).length;
+}
+
+/**
+ * Describes the `## [Unreleased]` block.
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @returns {UnreleasedState} Unreleased state.
+ */
+export function readUnreleased(changelog) {
+  const block = listBlocks(changelog).find((candidate) => UNRELEASED_LINE_PATTERN.test(candidate.heading));
+  if (!block) return { exists: false, entryCount: 0, unknownSections: [], body: "" };
+  const body = changelog.slice(block.bodyStart, block.end);
+  const unknownSections = [...body.matchAll(SECTION_HEADING_PATTERN)]
+    .map((match) => match[1])
+    .filter((name) => !CHANGE_TYPES.includes(name));
+  return { exists: true, entryCount: countEntries(body), unknownSections, body: body.trim() };
+}
+
+/**
+ * Returns the newest released block (the first one that is not `[Unreleased]`).
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @returns {{ version: string, entryCount: number } | null} Latest release entry.
+ */
+export function readLatestRelease(changelog) {
+  const block = listBlocks(changelog).find((candidate) => !UNRELEASED_LINE_PATTERN.test(candidate.heading));
+  return block ? { version: block.label, entryCount: countEntries(changelog.slice(block.bodyStart, block.end)) } : null;
+}
+
+/**
+ * Moves the `[Unreleased]` changes under a new version heading and leaves an empty `[Unreleased]` block.
+ *
+ * @param {string} changelog - CHANGELOG.md contents.
+ * @param {string} version - Version being released.
+ * @param {string} releaseDate - Date in `YYYY-MM-DD` format.
+ * @returns {string} Released changelog.
+ * @throws {Error} When `[Unreleased]` is missing, empty or uses an unknown section.
+ */
+export function releaseUnreleased(changelog, version, releaseDate) {
+  const unreleased = readUnreleased(changelog);
+  if (!unreleased.exists) throw new Error(`create-version: CHANGELOG.md needs a "${UNRELEASED_HEADING}" block`);
+  if (unreleased.unknownSections.length > 0) {
+    throw new Error(
+      `create-version: CHANGELOG.md [Unreleased] uses unknown sections (${unreleased.unknownSections.join(", ")}); use ${CHANGE_TYPES.join(", ")}`
+    );
+  }
+  if (unreleased.entryCount === 0) throw new Error("create-version: CHANGELOG.md [Unreleased] has no changes to release");
+  const block = listBlocks(changelog).find((candidate) => UNRELEASED_LINE_PATTERN.test(candidate.heading));
+  if (!block) throw new Error(`create-version: CHANGELOG.md needs a "${UNRELEASED_HEADING}" block`);
+  const released = `${UNRELEASED_HEADING}\n\n## [${version}] - ${releaseDate}\n\n${unreleased.body}\n\n`;
+  return `${changelog.slice(0, block.start)}${released}${changelog.slice(block.end).replace(LEADING_WHITESPACE_PATTERN, "")}`;
+}

package/src/constants/build-gate.js

@@ -0,0 +1,30 @@
+/**
+ * Contract between the `astra-rp ignore-build` command and the Vercel
+ * `ignoreCommand` wrapper that reads its output.
+ *
+ * @module constants/build-gate
+ */
+
+/** Decision printed as the last output line of `astra-rp ignore-build`. */
+export const BUILD_DECISION = Object.freeze({
+  build: "BUILD",
+  skip: "SKIP",
+});
+
+/** Git revision whose `package.json` holds the previous version. */
+export const PREVIOUS_REVISION = "HEAD^";
+
+/** Git revision being deployed. */
+export const CURRENT_REVISION = "HEAD";
+
+/** `git diff --quiet` status reporting that the compared path changed between both revisions. */
+export const GIT_DIFF_CHANGED_STATUS = 1;
+
+/** Manifest that holds the version. */
+export const PACKAGE_MANIFEST_FILE = "package.json";
+
+/** Exit code of `astra-rp ignore-build` when a decision was printed. */
+export const DECISION_EXIT_CODE = 0;
+
+/** Exit code of `astra-rp ignore-build` when it could not decide; wrappers must skip the build. */
+export const GATE_FAILURE_EXIT_CODE = 2;

package/src/constants/changelog-draft.js

@@ -0,0 +1,180 @@
+/**
+ * Contract of the `[Unreleased]` entries `create-version` drafts with an agent CLI (Claude Code or
+ * Codex) when `changelogDraft` is configured and the release would stop for a missing changelog.
+ *
+ * @module constants/changelog-draft
+ */
+
+/** Configuration field that turns on the drafting and orders the agent CLIs it tries. */
+export const CHANGELOG_DRAFT_FIELD = "changelogDraft";
+
+/** Agent CLIs that can draft the entries. */
+export const CHANGELOG_DRAFT_PROVIDER = Object.freeze({ claude: "claude", codex: "codex" });
+
+/** Order tried with `changelogDraft: true`: Claude Code first, Codex when Claude Code fails or has no quota left. */
+export const DEFAULT_CHANGELOG_DRAFT_PROVIDERS = Object.freeze([CHANGELOG_DRAFT_PROVIDER.claude, CHANGELOG_DRAFT_PROVIDER.codex]);
+
+/** Names printed for each agent CLI. */
+export const CHANGELOG_DRAFT_PROVIDER_LABELS = Object.freeze({ [CHANGELOG_DRAFT_PROVIDER.claude]: "Claude Code", [CHANGELOG_DRAFT_PROVIDER.codex]: "Codex" });
+
+/** Executable of each agent CLI, resolved from `PATH`. */
+export const CHANGELOG_DRAFT_EXECUTABLES = Object.freeze({ [CHANGELOG_DRAFT_PROVIDER.claude]: "claude", [CHANGELOG_DRAFT_PROVIDER.codex]: "codex" });
+
+/**
+ * Prefix of the isolated workspace the agents run in: a temporary directory outside the repository,
+ * removed when the drafting ends.
+ */
+export const CHANGELOG_DRAFT_DIRECTORY_PREFIX = "astra-rp-changelog-draft-";
+
+/**
+ * Directory of the workspace with the files Git tracks at `HEAD` (from `git checkout-index`): no `.git`,
+ * no untracked or ignored files, so local credentials such as an untracked `.env` or `.npmrc` stay
+ * out of the agents' reach.
+ */
+export const CHANGELOG_DRAFT_SNAPSHOT_DIRECTORY = "repository";
+
+/** Directory of the workspace with the release context astra-rp writes for the agents. */
+export const CHANGELOG_DRAFT_CONTEXT_DIRECTORY = "release-context";
+
+/** Release context file with the diff of the release range, without the changelog itself. */
+export const CHANGELOG_DRAFT_DIFF_FILE = "changes.diff";
+
+/** Release context file with the `git log --stat` of the release range. */
+export const CHANGELOG_DRAFT_LOG_FILE = "commits.log";
+
+/** `rmSync` retries when removing the workspace, while Windows releases the files of a stopped agent. */
+export const WORKSPACE_REMOVAL_RETRIES = Object.freeze({ maxRetries: 10, retryDelay: 100 });
+
+/**
+ * Settings file, at the workspace root, that Claude Code loads with `--settings`: its file tools
+ * refuse reads outside the working directory in every permission mode, even when the user's own
+ * settings allow them.
+ */
+export const CLAUDE_DRAFT_SETTINGS_FILE = "claude-settings.json";
+
+/** Contents of {@link CLAUDE_DRAFT_SETTINGS_FILE}. */
+export const CLAUDE_DRAFT_SETTINGS = Object.freeze({ permissions: Object.freeze({ blockReadsOutsideWorkingDirectories: true }) });
+
+/**
+ * Claude Code in print mode, inside the isolated workspace, with only its file tools (`Read`,
+ * `Grep`, `Glob`): no Bash, so no command can write files, and `--strict-mcp-config` without
+ * `--mcp-config` loads no MCP server. Reads inside the working directory need no approval; reads
+ * outside it need one, which `dontAsk` denies instead of asking (Claude Code documentation,
+ * "Configure permissions"), and {@link CLAUDE_DRAFT_SETTINGS_FILE} also refuses them.
+ * `--restricted` (Claude Code v2.1.248 or later) loads only managed settings and `--settings`, not
+ * the user's or the project's, so an inherited `permissions.additionalDirectories` cannot widen the
+ * reads, and confines the file tools to the working directories (Claude Code documentation, "CLI
+ * reference", https://code.claude.com/docs/en/cli-reference). `--no-session-persistence` keeps the
+ * run, with its prompt and the repository excerpts it read, off the disk and not resumable, as
+ * `--ephemeral` does for Codex. Every argument is fixed, so a Windows `.cmd` shim receives no
+ * variable path on its command line. The answer comes back as JSON.
+ */
+export const CLAUDE_DRAFT_ARGUMENTS = Object.freeze([
+  "-p",
+  "--restricted",
+  "--no-session-persistence",
+  "--output-format",
+  "json",
+  "--permission-mode",
+  "dontAsk",
+  "--tools",
+  "Read,Grep,Glob",
+  "--strict-mcp-config",
+  "--settings",
+  CLAUDE_DRAFT_SETTINGS_FILE,
+]);
+
+/** `--output-format json` result that reports a successful answer. */
+export const CLAUDE_SUCCESS_SUBTYPE = "success";
+
+/** File, at the workspace root, where Codex writes its last message (relative to its working directory). */
+export const CODEX_LAST_MESSAGE_FILE = "last-message.md";
+
+/**
+ * Codex in non-interactive mode inside the isolated workspace (its working directory, which is not
+ * a Git repository), sandboxed read-only, without saving the session. Its last message goes to
+ * {@link CODEX_LAST_MESSAGE_FILE} and the prompt comes from stdin (`-`). Every argument is fixed,
+ * so a Windows `.cmd` shim receives no variable path on its command line.
+ *
+ * Residual risk: Codex 0.162 documents no option that limits reads to one directory or turns off
+ * its shell tool, and `read-only` blocks writes but not reads. The workspace keeps the repository's
+ * untracked credentials away, yet Codex could still read other files of the host.
+ */
+export const CODEX_DRAFT_ARGUMENTS = Object.freeze([
+  "exec",
+  "--sandbox",
+  "read-only",
+  "--skip-git-repo-check",
+  "--ephemeral",
+  "--color",
+  "never",
+  "--output-last-message",
+  CODEX_LAST_MESSAGE_FILE,
+  "-",
+]);
+
+/** Time an agent CLI has to explore the repository and answer before the next one is tried. */
+export const CHANGELOG_DRAFT_TIMEOUT_MS = 600_000;
+
+/** Characters of an agent failure shown to the user. */
+export const CHANGELOG_DRAFT_MAX_FAILURE_CHARACTERS = 300;
+
+/** Markdown code fence an agent may wrap its answer in. */
+export const MARKDOWN_FENCE_PATTERN = /^```[^\n]*\n([\s\S]*?)\n```$/u;
+
+/**
+ * A C0 or C1 control character other than a line break or a tab, such as the ESC that starts a
+ * terminal escape sequence (OSC, CSI): an agent answer holding one is rejected before it is shown
+ * or written.
+ */
+// oxlint-disable-next-line no-control-regex -- matching control characters is the purpose of this pattern.
+export const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/u;
+
+/** Every character {@link CONTROL_CHARACTER_PATTERN} matches, to remove them from agent text shown in the terminal. */
+export const CONTROL_CHARACTERS_PATTERN = new RegExp(CONTROL_CHARACTER_PATTERN.source, "gu");
+
+/**
+ * A line a draft may hold: blank, a `### Section` heading or a complete `- ` entry. Each change is a
+ * single `- ` line, so an indented continuation of an entry is rejected.
+ */
+export const CHANGELOG_DRAFT_LINE_PATTERN = /^(?:\s*|### +\S.*|\s*- +\S.*)$/u;
+
+/** An indented line that is not an entry: an entry split across several lines, which a draft must not hold. */
+export const CHANGELOG_DRAFT_CONTINUATION_LINE_PATTERN = /^\s+\S/u;
+
+/** A level-2 heading such as `## [Unreleased]` or `## [1.2.0] - 2026-01-01`, which the draft must not contain. */
+export const RELEASE_LEVEL_HEADING_PATTERN = /^##(?!#)/mu;
+
+/** A single `### Section` line of a draft, capturing the section name. */
+export const CHANGELOG_DRAFT_SECTION_PATTERN = /^### +(.+?)\s*$/u;
+
+/** A blank line of a draft. */
+export const BLANK_LINE_PATTERN = /^\s*$/u;
+
+/** Windows command that resolves an executable on `PATH`, including the `.cmd` shims npm installs. */
+export const WINDOWS_EXECUTABLE_LOOKUP_COMMAND = "where";
+
+/** Files Windows can run; `where` also lists the extensionless shell script next to an npm `.cmd` shim. */
+export const WINDOWS_RUNNABLE_FILE_PATTERN = /\.(?:exe|com|cmd|bat)$/iu;
+
+/** Windows scripts that only a shell can run, such as the `claude.cmd` shim npm installs. */
+export const WINDOWS_SHELL_SCRIPT_PATTERN = /\.(?:cmd|bat)$/iu;
+
+/**
+ * Characters `cmd.exe` would interpret inside a double-quoted argument: `"` ends the quotes, `%`
+ * and `!` (with delayed expansion) expand variables, and `^&|<>` are its operators. The shim path
+ * and every agent argument on a Windows shell command line are checked against it.
+ */
+export const UNSAFE_SHELL_ARGUMENT_PATTERN = /["%!^&|<>]/u;
+
+/**
+ * Temporary Git index (`GIT_INDEX_FILE`), inside the workspace, that checks out the snapshot
+ * without touching the repository index; removed once the snapshot is written.
+ */
+export const CHANGELOG_DRAFT_INDEX_FILE = "snapshot.index";
+
+/**
+ * Release context file with the working tree changelog the agents will update, so they see it
+ * even when it is untracked or only changed locally.
+ */
+export const CHANGELOG_DRAFT_CURRENT_CHANGELOG_FILE = "CHANGELOG.md";

package/src/constants/changelog.js

@@ -0,0 +1,74 @@
+/**
+ * Keep a Changelog contract used to read and release `CHANGELOG.md`.
+ *
+ * @module constants/changelog
+ */
+
+/** Changelog file released together with `package.json`. */
+export const CHANGELOG_FILE = "CHANGELOG.md";
+
+/** Blocking release condition that exits with failure until the manual changelog is updated and its `[Unreleased]` block has entries. */
+export const CHANGELOG_UPDATE_REQUIRED_CODE = "changelog-update-required";
+
+/** Default title when creating a changelog document. */
+export const CHANGELOG_TITLE = "# Changelog";
+
+/** Length of commit hashes displayed in changelog entries. */
+export const COMMIT_SHORT_SHA_LENGTH = 7;
+
+/** Heading of the block that collects changes not yet released. */
+export const UNRELEASED_HEADING = "## [Unreleased]";
+
+/** Change types allowed as `###` sections, in Keep a Changelog order. */
+export const CHANGE_TYPES = Object.freeze(["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]);
+
+/** Any release-level heading: `## [Unreleased]`, `## [0.7.0] - 2026-09-26` or `## 0.6.0 - 2026-09-23`. */
+export const RELEASE_HEADING_PATTERN = /^## +\[?([^\]\s]+)\]?[^\n]*$/gmu;
+
+/** Unreleased heading, case-insensitive, as its own line. */
+export const UNRELEASED_LINE_PATTERN = /^## +\[Unreleased\][ \t]*$/imu;
+
+/** A change entry line. */
+export const ENTRY_LINE_PATTERN = /^\s*- +\S/mu;
+
+/** A change-type section heading inside a release block. */
+export const SECTION_HEADING_PATTERN = /^### +(.+?)\s*$/gmu;
+
+/** Leading whitespace left before the next block after moving `[Unreleased]`. */
+export const LEADING_WHITESPACE_PATTERN = /^\s+/u;
+
+/** Line break in a changelog written on any platform. */
+export const LINE_BREAK_PATTERN = /\r?\n/u;
+
+/** Line break of a changelog written on Windows, kept when closing `[Unreleased]`. */
+export const CRLF_LINE_BREAK = "\r\n";
+
+/** Line break of a changelog written on any other platform. */
+export const LF_LINE_BREAK = "\n";
+
+/** Separator between the year, month and day of a release date (`YYYY-MM-DD`). */
+export const RELEASE_DATE_SEPARATOR = "-";
+
+/** Digits of the month and the day of a release date. */
+export const RELEASE_DATE_PART_LENGTH = 2;
+
+/** Padding of a one-digit month or day in a release date. */
+export const RELEASE_DATE_PAD = "0";
+
+/**
+ * Locale whose `Intl.DateTimeFormat` parts are Gregorian with Latin digits, to read the year, month
+ * and day of a release in its configured time zone.
+ */
+export const RELEASE_DATE_LOCALE = "en-US";
+
+/** `Intl.DateTimeFormat` fields of a `YYYY-MM-DD` release date. */
+export const RELEASE_DATE_FORMAT_OPTIONS = Object.freeze({ year: "numeric", month: "2-digit", day: "2-digit" });
+
+/** `Intl.DateTimeFormat` part types of a release date, in `YYYY-MM-DD` order. */
+export const RELEASE_DATE_PART_ORDER = Object.freeze(["year", "month", "day"]);
+
+/** Configuration field naming the IANA time zone that dates the closed `[Unreleased]` section. */
+export const RELEASE_TIME_ZONE_FIELD = "releaseTimeZone";
+
+/** IANA time zone suggested by the messages about `releaseTimeZone`. */
+export const RELEASE_TIME_ZONE_EXAMPLE = "America/Argentina/Buenos_Aires";