@astra-kit/rp 0.0.0-stage → 0.10.0

package/types/constants/terminal-ui.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Layout, ANSI and key contracts of the dependency-free terminal UI.
+ *
+ * @module constants/terminal-ui
+ */
+/** Widest box drawn, so lines stay readable on large terminals. */
+export declare const MAX_BOX_WIDTH = 84;
+/** Width assumed when stdout does not report its columns. */
+export declare const FALLBACK_TERMINAL_WIDTH = 80;
+/** Columns kept free at the right of the terminal when sizing a box. */
+export declare const TERMINAL_RIGHT_MARGIN = 2;
+/** Horizontal padding inside a box, per side. */
+export declare const BOX_PADDING = 1;
+/** Width of the label column of status rows. */
+export declare const ROW_LABEL_WIDTH = 16;
+/** Spinner animation frames. */
+export declare const SPINNER_FRAMES: readonly string[];
+/** Delay between spinner frames. */
+export declare const SPINNER_INTERVAL_MS = 80;
+/** Exit code conventionally used after Ctrl+C. */
+export declare const INTERRUPTED_EXIT_CODE = 130;
+/** Splits styled text into ANSI escape sequences and single code points. */
+export declare const ANSI_TOKEN_PATTERN: RegExp;
+/** First character of every ANSI escape sequence. */
+export declare const ANSI_ESCAPE = "\u001B";
+/** ANSI control sequences used by boxes, spinners and prompts. */
+export declare const ANSI_SEQUENCE: Readonly<{
+    reset: "\u001B[0m";
+    hideCursor: "\u001B[?25l";
+    showCursor: "\u001B[?25h";
+    clearLine: "\r\u001B[2K";
+    clearBelow: "\u001B[0J";
+}>;
+/** Border color of each box tone. */
+export declare const BOX_TONE: Readonly<{
+    neutral: "gray";
+    info: "cyan";
+    success: "green";
+    warning: "yellow";
+    danger: "red";
+    accent: "magenta";
+}>;
+/** Nerd Font glyphs (Font Awesome and Octicons sets) used as status icons. */
+export declare const ICON_GLYPH: Readonly<{
+    success: "";
+    failure: "";
+    warning: "";
+    info: "";
+    pending: "";
+    arrow: "";
+    bullet: "";
+    star: "";
+    rocket: "";
+}>;
+/** Label/value rows (`renderRow`): the value starts after a gap of two or more spaces. */
+export declare const VALUE_COLUMN_PATTERN: RegExp;
+/** Leading marker (icon, arrow, bullet or `1.`, never a word) followed by a space, used as hanging indent. */
+export declare const HANGING_MARKER_PATTERN: RegExp;
+/** Options that can be picked with a single digit key (1-9). */
+export declare const MAX_NUMBERED_OPTIONS = 9;
+/** A single digit key that picks a numbered option. */
+export declare const NUMBER_KEY_PATTERN: RegExp;
+/** Seconds in a minute, used to format durations. */
+export declare const SECONDS_PER_MINUTE = 60;
+/** Milliseconds in a second, used to format durations. */
+export declare const MILLISECONDS_PER_SECOND = 1000;
+/** Key names (`readline` keypress events) handled by the select prompt. */
+export declare const PROMPT_KEY: Readonly<{
+    interrupt: "c";
+    previous: readonly string[];
+    next: readonly string[];
+    confirm: readonly string[];
+}>;

package/types/constants/version-files.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Markers of `versionFiles`: lines and blocks whose version `create-version`
+ * rewrites in the release commit, besides `package.json`.
+ *
+ * @module constants/version-files
+ */
+/**
+ * Comment marking a single line whose version is rewritten. The release-please marker is also
+ * accepted, so a project moving from release-please keeps its files untouched.
+ */
+export declare const VERSION_LINE_MARKERS: readonly string[];
+/** Comments opening a block whose every version is rewritten, paired by index with {@link VERSION_BLOCK_END_MARKERS}. */
+export declare const VERSION_BLOCK_START_MARKERS: readonly string[];
+/** Comments closing a version block, paired by index with {@link VERSION_BLOCK_START_MARKERS}. */
+export declare const VERSION_BLOCK_END_MARKERS: readonly string[];
+/**
+ * Ways a file can pair its version block markers wrongly. Any of them stops the rewrite, since
+ * guessing where a block ends could rewrite versions outside the intended section.
+ *
+ * - `unterminated`: a start marker without its end marker before the end of the file.
+ * - `unopened`: an end marker outside any block.
+ * - `nested`: a start marker inside a block that is still open.
+ * - `mismatched`: an end marker of the other tool (`x-release-please-end` closing `astra-rp-start-version`, or the reverse).
+ */
+export declare const VERSION_BLOCK_PROBLEM: Readonly<{
+    unterminated: "unterminated";
+    unopened: "unopened";
+    nested: "nested";
+    mismatched: "mismatched";
+}>;
+/**
+ * A semantic version inside a marked line (`1.2.3`, `1.2.3-beta.1`, `1.2.3+build`), not glued to
+ * other version-like digits (`10.0.0.1`, `1.2.3.4`). A period that ends a sentence (`is 1.2.3.`)
+ * is not part of the version and is kept. Global: every version of a marked line is rewritten.
+ */
+export declare const MARKED_VERSION_PATTERN: RegExp;
+/**
+ * Splits a versioned file into lines right after each terminator (`\r\n`, `\n` or a lone `\r`),
+ * so every line keeps its own terminator and joining the lines gives back the original content.
+ */
+export declare const LINE_TERMINATOR_BOUNDARY_PATTERN: RegExp;
+/**
+ * Files the release owns: the bumped `package.json` and the CHANGELOG whose `[Unreleased]` it closes.
+ * `versionFiles` cannot list either: rewriting them would undo the bump or the closed section.
+ */
+export declare const RELEASE_COMMIT_BUILT_IN_FILES: readonly string[];
+/**
+ * Git pathspec magic that matches a configured path literally, so names starting with `:` or
+ * holding `*`/`?` are never read as pathspec syntax.
+ */
+export declare const GIT_LITERAL_PATHSPEC_PREFIX = ":(literal)";

package/types/constants/versions.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Release version rules shared by `create-version` and the Vercel build gate.
+ *
+ * @module constants/versions
+ */
+/** Semver release types, from the smallest to the largest change. */
+export declare const RELEASE_TYPE: Readonly<{
+    patch: "patch";
+    minor: "minor";
+    major: "major";
+}>;
+/**
+ * Suggested release type before `1.0.0` with `preMajorShift`: one level down, the `0.x` convention
+ * where a minor carries breaking changes and a patch carries features (release-please's
+ * `bump-minor-pre-major` plus `bump-patch-for-minor-pre-major`).
+ */
+export declare const PRE_MAJOR_SHIFTED_RELEASE_TYPE: Readonly<{
+    patch: "patch";
+    minor: "patch";
+    major: "minor";
+}>;
+/** Major version of the `0.x` line, where `preMajorShift` applies. */
+export declare const PRE_MAJOR_VERSION = 0;
+/**
+ * Version of a package that was never released (the release-please placeholder): the commit that
+ * sets it is not a release, and its first release keeps the unshifted suggestion (a feature gives
+ * `0.1.0`, not `0.0.1`).
+ */
+export declare const UNRELEASED_PLACEHOLDER_VERSION = "0.0.0";
+/** Release types in the order they are offered: patch, minor, major. */
+export declare const RELEASE_TYPE_ORDER: readonly ("major" | "minor" | "patch")[];
+/** Stable `X.Y.Z` release version: no prerelease, build metadata, prefix or leading zeros. */
+export declare const RELEASE_VERSION_PATTERN: RegExp;
+/** Any semver version, capturing its `X.Y.Z` core and optional prerelease. */
+export declare const SEMVER_PATTERN: RegExp;
+/** Prefix of the annotated Git tags that mark each release (`v0.93.0`). */
+export declare const RELEASE_TAG_PREFIX = "v";
+/** `git log --grep` pattern of release commit subjects (`0.93.0`). */
+export declare const RELEASE_COMMIT_SUBJECT_GREP: string;
+/** Conventional commit header: `type(scope)!: subject`. */
+export declare const CONVENTIONAL_HEADER_PATTERN: RegExp;
+/** Footer that marks a breaking change in a conventional commit body. */
+export declare const BREAKING_CHANGE_FOOTER_PATTERN: RegExp;
+/** Conventional commit type that ships user-visible features. */
+export declare const FEATURE_COMMIT_TYPE = "feat";
+/** Imperative verbs used by legacy, non-conventional feature subjects. */
+export declare const LEGACY_FEATURE_SUBJECT_PATTERN: RegExp;

package/types/create-version/artifact.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Locates and verifies the package archive prepared for a release, so
+ * `publish: "npm"` publishes exactly the artifact the project verified
+ * instead of repacking the working tree.
+ *
+ * Patterns are relative to the repository root, use `/` separators and
+ * replace `{version}` and `{name}` (the tarball base name `npm pack` uses, so
+ * `@scope/pkg` becomes `scope-pkg`). Inside a single path segment, `*` matches
+ * anything and `{sha256}` matches a SHA-256 digest that must equal the
+ * archive checksum (for example `releases/{version}-{sha256}/{name}-{version}.tgz`).
+ * `{sha256}` may repeat, in one segment or several: every occurrence must
+ * declare the same digest.
+ *
+ * Projects pack with `npm pack --ignore-scripts`, which is reproducible: the same
+ * checkout always yields the same bytes. So the archive is verified by comparing
+ * its SHA-512 integrity with the one `npm pack --dry-run` reports for the release
+ * checkout, and the manifest must not rely on rewrites only pnpm applies when packing.
+ * The archive is moved out of the package root during that dry run, so npm never
+ * counts it as part of the package it describes.
+ *
+ * @module create-version/artifact
+ */
+export type PreparedArtifact = {
+    path: string;
+    expectedSha256: string | null;
+};
+export type PackageManifest = Record<string, unknown>;
+/**
+ * Replaces the `{version}` and `{name}` placeholders of an artifact pattern; `{sha256}` stays.
+ * `{name}` becomes the tarball base name, so scoped packages never add a path separator.
+ *
+ * @param {string} pattern - Configured pattern.
+ * @param {{ version: string, packageName: string }} release - Version and npm package name.
+ * @returns {string} Pattern with placeholders replaced.
+ */
+export declare function expandArtifactPattern(pattern: string, { version, packageName }: {
+    version: string;
+    packageName: string;
+}): string;
+/**
+ * Finds the newest file that matches an artifact pattern.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @param {string} pattern - Configured pattern with `{version}` and optional `{name}`, `*` and `{sha256}`.
+ * @param {{ version: string, packageName: string }} release - Version and npm package name.
+ * @returns {PreparedArtifact | null} Path relative to the root with `/` separators and the digest its path declares, or `null`.
+ *   Paths whose segments declare different digests never match.
+ */
+export declare function findPreparedArtifact(repositoryRoot: string, pattern: string, release: {
+    version: string;
+    packageName: string;
+}): PreparedArtifact | null;
+/**
+ * Checks that an artifact path can be passed to `npm publish` on a shell command line.
+ *
+ * @param {string} artifactPath - Relative path found by {@link findPreparedArtifact}.
+ * @returns {boolean} Whether the path only uses safe characters.
+ */
+export declare function isSafeArtifactPath(artifactPath: string): boolean;
+/**
+ * Computes the SHA-256 of a file.
+ *
+ * @param {string} filePath - Absolute path.
+ * @returns {string} Lowercase hexadecimal digest.
+ */
+export declare function computeSha256(filePath: string): string;
+/**
+ * Computes the npm integrity of a file: the same `sha512-<base64>` string that
+ * `npm pack --json` reports for the archive it writes.
+ *
+ * @param {string} filePath - Absolute path.
+ * @returns {string} Subresource-integrity string.
+ */
+export declare function computeNpmIntegrity(filePath: string): string;
+/**
+ * Lists what a manifest needs from `pnpm pack` and npm would publish as it is: `workspace:`,
+ * `catalog:` or `jsr:` specifiers in published dependency maps, and `publishConfig` keys pnpm hoists onto the
+ * manifest (such as `exports`, `main` or `bin`; npm only reads `publishConfig` as configuration).
+ * Every other `publishConfig` key is npm configuration and is accepted.
+ *
+ * @param {PackageManifest} manifest - `package.json` of the release checkout.
+ * @returns {string[]} Problems in Spanish; empty when npm packs the package as pnpm would.
+ */
+export declare function findPnpmPackRewrites(manifest: PackageManifest): string[];
+/**
+ * Runs an operation with the prepared archive moved out of the package root, and always puts it
+ * back afterwards, also when the operation fails.
+ *
+ * `npm pack --dry-run` describes every file npm would pack now. When the package has no `files`
+ * allowlist and neither `.npmignore` nor `.gitignore` excludes the archive directory, the archive
+ * written by `prepare` (for example `releases/pkg-1.0.0.tgz`) would be packed into the package it
+ * is compared with, changing the integrity and rejecting a valid artifact. Hiding it reproduces the
+ * package root `prepare` packed: a directory left empty is ignored by npm, as it was then.
+ *
+ * @template T
+ * @param {string} repositoryRoot - Package root.
+ * @param {string} artifactPath - Archive relative to the root, found by {@link findPreparedArtifact}.
+ * @param {() => Promise<T>} operation - Runs while the archive is outside the package root.
+ * @param {string} [parentDirectory] - Where the holding directory is created; defaults to the OS temp directory.
+ * @returns {Promise<T>} The operation result.
+ */
+export declare function withArtifactOutsidePackageRoot<T>(repositoryRoot: string, artifactPath: string, operation: () => Promise<T>, parentDirectory?: string): Promise<T>;
+/**
+ * Verifies a prepared archive before publishing it: the SHA-256 its path declares (when the
+ * pattern uses `{sha256}`) and the SHA-512 integrity `npm pack --dry-run` reports for the release
+ * checkout, so the archive is byte for byte what npm packs from that commit.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @param {PreparedArtifact} artifact - Archive found by {@link findPreparedArtifact}.
+ * @param {string} expectedIntegrity - `integrity` of `npm pack --dry-run --json --ignore-scripts`.
+ * @returns {string[]} Problems in Spanish; empty when the archive can be published.
+ */
+export declare function verifyPreparedArtifact(repositoryRoot: string, artifact: PreparedArtifact, expectedIntegrity: string): string[];

package/types/create-version/changelog-draft-workspace.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Isolated workspace where the changelog drafting agents run: a temporary directory outside the
+ * repository with a snapshot of the files Git tracks at `HEAD` and the release context (diff and
+ * log of the release range, plus the working tree changelog) that astra-rp reads for them. The
+ * agents never see the checkout, its `.git` directory nor its untracked files, and need no Git
+ * command of their own.
+ *
+ * @module create-version/changelog-draft-workspace
+ */
+export type ChangelogDraftWorkspaceRequest = {
+    repositoryRoot: string;
+    lastReleaseSha: string | null;
+    changelogPath: string;
+};
+export type ChangelogDraftWorkspace = {
+    directory: string;
+    remove: () => void;
+};
+/**
+ * @typedef {{ repositoryRoot: string, lastReleaseSha: string | null, changelogPath: string }} ChangelogDraftWorkspaceRequest
+ * @typedef {{ directory: string, remove: () => void }} ChangelogDraftWorkspace
+ */
+/**
+ * Creates the workspace: `repository/` with the tracked files at `HEAD`, and `release-context/`
+ * with the diff of the release range (without the changelog the agents are drafting), its
+ * `git log --stat` and the working tree changelog they will update, when it is a regular file.
+ * Without a previous release, the range is the whole history.
+ *
+ * @param {ChangelogDraftWorkspaceRequest} request - Repository, last release and changelog path.
+ * @returns {Promise<ChangelogDraftWorkspace>} Workspace directory and how to remove it.
+ * @throws {Error} When Git fails or the changelog cannot be copied; the partial workspace is removed and the original error is the `cause`.
+ */
+export declare function createChangelogDraftWorkspace({ repositoryRoot, lastReleaseSha, changelogPath }: ChangelogDraftWorkspaceRequest): Promise<ChangelogDraftWorkspace>;

package/types/create-version/changelog-draft.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Drafts the `[Unreleased]` entries of a changelog with an agent CLI when a new release would stop
+ * because they are missing. The agents are tried in the configured order (Claude Code, then Codex
+ * by default): each one reads an isolated, read-only copy of the repository with the release diff
+ * and log, outside the checkout, and answers the entries as Markdown,
+ * which astra-rp checks before writing them. The first valid answer wins; when every agent fails,
+ * the caller reports why and the release stops as it does without drafting.
+ *
+ * @module create-version/changelog-draft
+ */
+export type ChangelogDraftProvider = "claude" | "codex";
+export type AgentInvocation = {
+    command: string;
+    shell: boolean;
+};
+export type AgentAnswer = {
+    answer: string;
+    reason: null;
+} | {
+    answer: null;
+    reason: string;
+};
+export type ParsedChangelogDraft = {
+    entries: string;
+    reason: null;
+} | {
+    entries: null;
+    reason: string;
+};
+export type ChangelogDraftFailure = {
+    provider: ChangelogDraftProvider;
+    reason: string;
+};
+export type ChangelogDraftResult = {
+    provider: ChangelogDraftProvider;
+    entries: string;
+    failures: ChangelogDraftFailure[];
+} | {
+    provider: null;
+    entries: null;
+    failures: ChangelogDraftFailure[];
+};
+export type ChangelogDraftRequest = {
+    packageName: string;
+    changelogPath: string;
+    lastReleaseSha: string | null;
+    commits: readonly {
+        sha?: string;
+        subject: string;
+    }[];
+};
+export type ChangelogDraftOptions = {
+    providers: readonly ChangelogDraftProvider[];
+    repositoryRoot: string;
+    request: ChangelogDraftRequest;
+    timeoutMs?: number;
+    onAttempt?: (provider: ChangelogDraftProvider) => void;
+    onFailure?: (failure: ChangelogDraftFailure) => void;
+};
+/**
+ * @typedef {"claude" | "codex"} ChangelogDraftProvider
+ * @typedef {{ command: string, shell: boolean }} AgentInvocation
+ * @typedef {{ answer: string, reason: null } | { answer: null, reason: string }} AgentAnswer
+ * @typedef {{ entries: string, reason: null } | { entries: null, reason: string }} ParsedChangelogDraft
+ * @typedef {{ provider: ChangelogDraftProvider, reason: string }} ChangelogDraftFailure
+ * @typedef {{ provider: ChangelogDraftProvider, entries: string, failures: ChangelogDraftFailure[] }
+ *   | { provider: null, entries: null, failures: ChangelogDraftFailure[] }} ChangelogDraftResult
+ * @typedef {{
+ *   packageName: string,
+ *   changelogPath: string,
+ *   lastReleaseSha: string | null,
+ *   commits: readonly { sha?: string, subject: string }[],
+ * }} ChangelogDraftRequest
+ * @typedef {{
+ *   providers: readonly ChangelogDraftProvider[],
+ *   repositoryRoot: string,
+ *   request: ChangelogDraftRequest,
+ *   timeoutMs?: number,
+ *   onAttempt?: (provider: ChangelogDraftProvider) => void,
+ *   onFailure?: (failure: ChangelogDraftFailure) => void,
+ * }} ChangelogDraftOptions
+ */
+/**
+ * Writes the prompt the agent receives: what to draft, the files of the isolated workspace it runs
+ * in (snapshot and release context) and the exact answer format astra-rp accepts. The project rules
+ * about the changelog win over these guidelines.
+ *
+ * @param {ChangelogDraftRequest} request - Package, changelog and commits of the release.
+ * @returns {string} Prompt in Spanish.
+ */
+export declare function buildChangelogDraftPrompt({ packageName, changelogPath, lastReleaseSha, commits }: ChangelogDraftRequest): string;
+/**
+ * Checks an agent answer before it reaches the terminal or the changelog: an answer with control
+ * characters (see {@link CONTROL_CHARACTER_PATTERN}) is rejected, an optional Markdown fence is
+ * removed, and the rest must be Keep a Changelog sections and nothing else, with the structure
+ * {@link findSectionStructureProblem} requires.
+ *
+ * @param {string} answer - Text the agent answered.
+ * @returns {ParsedChangelogDraft} Entries to write, or why the answer cannot be used.
+ */
+export declare function parseChangelogDraft(answer: string): ParsedChangelogDraft;
+/**
+ * Tries each agent CLI in order until one answers entries {@link parseChangelogDraft} accepts. The
+ * agents run in one isolated workspace (see {@link createChangelogDraftWorkspace}), removed at the
+ * end. An agent that is not installed, has no quota left, fails, takes longer than the limit or
+ * answers in another format counts as a failure, and the next one is tried; when the workspace
+ * cannot be created, every agent fails with that reason.
+ *
+ * @param {ChangelogDraftOptions} options - Agents in order, repository, release and progress callbacks.
+ * @returns {Promise<ChangelogDraftResult>} Entries and the agent that wrote them, or every failure.
+ */
+export declare function draftChangelogEntries({ providers, repositoryRoot, request, timeoutMs, onAttempt, onFailure }: ChangelogDraftOptions): Promise<ChangelogDraftResult>;
+/**
+ * Names an agent CLI for the terminal.
+ *
+ * @param {ChangelogDraftProvider} provider - Agent CLI.
+ * @returns {string} Label such as `Claude Code`.
+ */
+export declare function describeChangelogDraftProvider(provider: ChangelogDraftProvider): string;
+/**
+ * Finds how to start an agent CLI. Elsewhere `PATH` lookup happens on spawn; Windows needs `where`
+ * because npm installs CLIs as `.cmd` shims, which only a shell runs.
+ *
+ * @param {string} executable - Executable name.
+ * @returns {Promise<AgentInvocation | null>} Invocation, or `null` when the executable is not on `PATH`.
+ */
+export declare function resolveAgentInvocation(executable: string): Promise<AgentInvocation | null>;

package/types/create-version/changelog.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Verifies manually maintained changelogs and closes their `[Unreleased]` section in the release
+ * commit: the entries are written by hand (or drafted with `changelogDraft`), the version heading
+ * and its date by the release.
+ *
+ * @module create-version/changelog
+ */
+export type ChangelogUpdateState = {
+    updated: boolean;
+    reason: string | null;
+};
+export type PreservedReleaseFile = {
+    filePath: string;
+    originalBytes: Buffer;
+};
+export type ChangelogContext = {
+    repositoryRoot: string;
+    reader: import("./process.js").GitReader;
+    commands: import("../package-manager.js").ProjectCommands;
+};
+export type UnreleasedEntriesState = {
+    exists: boolean;
+    entryCount: number;
+};
+/**
+ * @typedef {{ updated: boolean, reason: string | null }} ChangelogUpdateState
+ * @typedef {{ filePath: string, originalBytes: Buffer }} PreservedReleaseFile
+ * @typedef {{ repositoryRoot: string, reader: import("./process.js").GitReader, commands: import("../package-manager.js").ProjectCommands }} ChangelogContext
+ * @typedef {{ exists: boolean, entryCount: number }} UnreleasedEntriesState
+ */
+/**
+ * Compares a changelog with its last release using Git's normalized blob hashes. Local edits,
+ * staged edits and committed edits all count; an initial release requires an existing file.
+ *
+ * @param {import("./process.js").GitReader} reader - Read-only Git adapter.
+ * @param {string} repositoryRoot - Repository root.
+ * @param {string} filePath - Changelog path relative to the repository root.
+ * @param {string | null} releaseRevision - Last release commit, or `null` for an initial release.
+ * @returns {Promise<ChangelogUpdateState>} Whether the file was updated, or why publication must stop.
+ */
+export declare function readChangelogUpdateState(reader: import("./process.js").GitReader, repositoryRoot: string, filePath: string, releaseRevision: string | null): Promise<ChangelogUpdateState>;
+/**
+ * Explains why a changelog cannot be closed in the release commit: it has no `## [Unreleased]`
+ * block, or that block has no entry (`- ` line) to release.
+ *
+ * @param {UnreleasedEntriesState} unreleased - `[Unreleased]` block of the changelog.
+ * @param {string} filePath - Changelog path relative to the repository root.
+ * @returns {string | null} Reason in Spanish, or `null` when the block has entries.
+ */
+export declare function describeMissingUnreleasedEntries(unreleased: UnreleasedEntriesState, filePath: string): string | null;
+/**
+ * Tells whether `[Unreleased]` holds nothing an agent draft would discard: only blank lines and
+ * `### <change type>` headings. Comments, release instructions or template text written there by
+ * the user (maybe not committed yet) keep the block from being drafted.
+ *
+ * @param {import("../changelog.js").UnreleasedState} unreleased - `[Unreleased]` block of the changelog.
+ * @returns {boolean} Whether drafted entries can replace the block body.
+ */
+export declare function hasOnlyEmptySections(unreleased: import("../changelog.js").UnreleasedState): boolean;
+/**
+ * Writes drafted entries as the body of `[Unreleased]`, replacing what the block held (an empty
+ * block, or empty section headings; see {@link hasOnlyEmptySections}). Creates the block, or the
+ * document, when missing, keeps the released history and uses the line breaks of a CRLF changelog.
+ *
+ * @param {string} changelog - Existing contents, or an empty string for a new file.
+ * @param {string} entries - `### Section` headings and `- ` entries, without the `## [Unreleased]` heading.
+ * @returns {string} Changelog whose `[Unreleased]` block holds `entries`.
+ */
+export declare function fillUnreleasedEntries(changelog: string, entries: string): string;
+/**
+ * Says how to fix a changelog the release cannot close, without touching the version.
+ *
+ * @param {string} filePath - Changelog path relative to the repository root.
+ * @param {string} createVersionCommand - Project command that runs `create-version`.
+ * @returns {string} Actionable hint in Spanish.
+ */
+export declare function describeUnreleasedEntriesHint(filePath: string, createVersionCommand: string): string;
+/**
+ * Requires a manual changelog update and captures its bytes, so the release can tell whether a
+ * later step changed them before closing `[Unreleased]`.
+ *
+ * @param {ChangelogContext} context - Release context.
+ * @param {string} filePath - Changelog path relative to the repository root.
+ * @param {string | null} releaseRevision - Last release commit, or `null` for an initial release.
+ * @returns {Promise<PreservedReleaseFile>} Changelog and its bytes before the release steps.
+ * @throws {ReleaseStepError} When the changelog is missing, unchanged or cannot be read.
+ */
+export declare function verifyChangelogUpdate(context: ChangelogContext, filePath: string, releaseRevision: string | null): Promise<PreservedReleaseFile>;
+/**
+ * Requires entries in the `[Unreleased]` block of a verified changelog, which the release commit closes.
+ *
+ * @param {ChangelogContext} context - Release context.
+ * @param {PreservedReleaseFile} changelog - Changelog captured by {@link verifyChangelogUpdate}.
+ * @returns {string} Changelog text, decoded as strict UTF-8.
+ * @throws {ReleaseStepError} When the changelog is not valid UTF-8, or `[Unreleased]` is missing or has no entries.
+ */
+export declare function assertUnreleasedEntries(context: ChangelogContext, changelog: PreservedReleaseFile): string;
+/**
+ * Stops when a check or hook changed a changelog after the release captured it: closing
+ * `[Unreleased]` over those bytes would ship content the release never verified.
+ *
+ * @param {ChangelogContext} context - Release context.
+ * @param {readonly PreservedReleaseFile[]} files - Files captured before running release steps.
+ * @returns {void}
+ * @throws {ReleaseStepError} When a file changed, disappeared or cannot be read.
+ */
+export declare function assertPreservedFilesUnchanged(context: ChangelogContext, files: readonly PreservedReleaseFile[]): void;
+/**
+ * Formats a date as the `YYYY-MM-DD` day Keep a Changelog gives a version: the day in `timeZone`
+ * when the project configures `releaseTimeZone`, so a release prepared on a CI runner in UTC keeps
+ * the team's day, or the machine's local day otherwise.
+ *
+ * @param {Date} [date] - Moment to format; the current time by default.
+ * @param {string | null} [timeZone] - IANA time zone already validated by the configuration, or `null` for the local day.
+ * @returns {string} Release day in `YYYY-MM-DD` format.
+ */
+export declare function formatReleaseDate(date?: Date, timeZone?: string | null): string;
+/**
+ * Closes the `[Unreleased]` section: its heading becomes `## [version] - releaseDate`, keeping its
+ * body, and a new empty `## [Unreleased]` goes on top. Every other byte is kept, including the
+ * line breaks of a CRLF changelog and section names outside Keep a Changelog.
+ *
+ * @param {string} changelog - Changelog contents.
+ * @param {string} version - Version being released.
+ * @param {string} releaseDate - Release day in `YYYY-MM-DD` format.
+ * @returns {string} Changelog with the section closed.
+ * @throws {Error} When the changelog has no `[Unreleased]` heading or that block has no entries.
+ */
+export declare function closeUnreleasedSection(changelog: string, version: string, releaseDate: string): string;
+/**
+ * Prepares the release-commit update of a verified changelog: checks that no step changed it since
+ * it was captured and closes its `[Unreleased]` section for `version`.
+ *
+ * @param {ChangelogContext} context - Release context.
+ * @param {PreservedReleaseFile} changelog - Changelog captured by {@link verifyChangelogUpdate}.
+ * @param {string} version - Version being released.
+ * @param {string} releaseDate - Release day in `YYYY-MM-DD` format.
+ * @returns {import("./run.js").ReleaseFileUpdate} File to write, with its bytes before the release.
+ * @throws {ReleaseStepError} When a step changed the changelog, it is not valid UTF-8 or `[Unreleased]` cannot be closed.
+ */
+export declare function prepareChangelogClosing(context: ChangelogContext, changelog: PreservedReleaseFile, version: string, releaseDate: string): import("./run.js").ReleaseFileUpdate;

package/types/create-version/ci-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Validates repository-owned CI release settings.
+ * @module create-version/ci-config
+ */
+export type CiReleaseConfig = {
+    workflow: string;
+    secrets?: string[];
+    variables?: string[];
+    deployment?: "vercel" | null;
+};
+export type ResolvedCiReleaseConfig = {
+    workflow: string;
+    secrets: string[];
+    variables: string[];
+    deployment: "vercel" | null;
+};
+/**
+ * @typedef {{ workflow: string, secrets?: string[], variables?: string[], deployment?: "vercel" | null }} CiReleaseConfig
+ * @typedef {{ workflow: string, secrets: string[], variables: string[], deployment: "vercel" | null }} ResolvedCiReleaseConfig
+ */
+/**
+ * Builds the root-relative path of a workflow file.
+ * @param {string} workflow - Validated workflow filename.
+ * @returns {string} Path under {@link CI_WORKFLOW_DIRECTORY}.
+ */
+export declare function ciWorkflowPath(workflow: string): string;
+/**
+ * Resolves a workflow basename and explicit environment bindings.
+ * @param {unknown} raw - Repository-owned configuration, or null to disable CI releases.
+ * @returns {ResolvedCiReleaseConfig | null} Validated configuration.
+ * @throws {Error} When the workflow path or environment names are invalid.
+ */
+export declare function resolveCiReleaseConfig(raw: unknown): ResolvedCiReleaseConfig | null;