@astra-kit/rp 0.0.0-stage → 0.10.0

package/types/create-version/ci-publication-history.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Reads the worker's own GitHub Actions history to prove that a custom publisher already finished,
+ * so neither a retry that only needs to deploy nor a duplicate dispatch queued behind the release's
+ * concurrency group runs a non-idempotent publication again.
+ * A registry publication is proven by the registry itself; a custom `publish` function leaves no
+ * such record, and the successful release step of an earlier run or attempt is the durable one.
+ * @module create-version/ci-publication-history
+ */
+export type ActionsWorkflowRun = {
+    id: number;
+    display_title: string;
+    run_attempt: number;
+    html_url: string;
+};
+export type ActionsJob = {
+    steps?: {
+        name: string;
+        conclusion: string | null;
+    }[];
+};
+export type CompletedCiPublication = {
+    url: string;
+    attempt: number;
+};
+/**
+ * @typedef {{ id: number, display_title: string, run_attempt: number, html_url: string }} ActionsWorkflowRun
+ * @typedef {{ steps?: { name: string, conclusion: string | null }[] }} ActionsJob
+ * @typedef {{ url: string, attempt: number }} CompletedCiPublication
+ */
+/**
+ * Tells whether the worker must prove from its Actions history that the publication already
+ * finished: a custom publisher leaves no registry record, and both a retry after a failed deployment
+ * and two concurrent `--retry-ci` dispatches (queued, not cancelled, by the workflow's concurrency
+ * group) reach the worker again for the same release, with or without a deployment.
+ * @param {import("./config.js").ResolvedCreateVersionConfig} config - Project configuration.
+ * @returns {boolean} True when `publish` is a function.
+ */
+export declare function requiresCiPublicationHistory(config: import("./config.js").ResolvedCreateVersionConfig): boolean;
+/**
+ * Finds another run or attempt of this exact release whose release step succeeded, which means its
+ * custom publisher already finished. Only successful release steps count: a duplicate dispatch queued
+ * behind the release's concurrency group starts after the first run ends, so it sees that success.
+ * The current run attempt (`GITHUB_RUN_ID`/`GITHUB_RUN_ATTEMPT`) never counts.
+ * Fails closed: when the history cannot be read, the worker stops before publishing.
+ * @param {string} workflow - Configured workflow filename that dispatches the release.
+ * @param {import("./github-workflow.js").CiReleaseIdentity} release - Verified release identity.
+ * @param {NodeJS.ProcessEnv} [environment] - Worker environment providing the Actions API, repository and token.
+ * @returns {Promise<CompletedCiPublication | null>} Another successful run attempt, or null when publication never finished.
+ * @throws {ReleaseStepError} When the Actions history is unavailable or unreadable.
+ */
+export declare function findCompletedCiPublication(workflow: string, release: import("./github-workflow.js").CiReleaseIdentity, environment?: NodeJS.ProcessEnv): Promise<CompletedCiPublication | null>;

package/types/create-version/ci-release-identity-step.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Renders the dependency-free workflow step that authenticates a dispatched release before any
+ * project-controlled code (package installation, lifecycle scripts, hooks) runs with the job's
+ * publication secrets and OIDC permission.
+ * @module create-version/ci-release-identity-step
+ */
+/**
+ * Renders the identity step placed right after checkout and before any toolchain or dependency setup.
+ * Inputs reach the script only through step environment variables, never through `${{ }}` interpolation.
+ * @returns {string} Workflow YAML for one step, indented for the release job.
+ */
+export declare function renderCiReleaseIdentityStep(): string;

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

@@ -0,0 +1,148 @@
+/**
+ * Prepares automatic CI setup as rollback-capable files of the release commit.
+ * @module create-version/ci-setup
+ */
+export type ResolvedCreateVersionConfig = import("./config.js").ResolvedCreateVersionConfig;
+export type ReleaseFileUpdate = import("./run.js").ReleaseFileUpdate;
+/**
+ * @typedef {import("./config.js").ResolvedCreateVersionConfig} ResolvedCreateVersionConfig
+ * @typedef {import("./run.js").ReleaseFileUpdate} ReleaseFileUpdate
+ */
+/**
+ * Builds the worker's environment from explicit bindings and the selected registry credential.
+ * @param {ResolvedCreateVersionConfig} config - Project configuration.
+ * Every Vercel credential is listed once in `secrets` (so preflight requires it) and always in
+ * `deploymentSecrets`, even when also declared in `ci.secrets`, which keeps it out of the job-level environment.
+ * @returns {{ secrets: string[], variables: string[], githubToken: boolean, githubTokenWrite: boolean, deploymentSecrets: string[] }} Required worker bindings, step-scoped deployment credentials and package permission.
+ */
+export declare function describeCiEnvironment(config: ResolvedCreateVersionConfig): {
+    secrets: string[];
+    variables: string[];
+    githubToken: boolean;
+    githubTokenWrite: boolean;
+    deploymentSecrets: string[];
+};
+/**
+ * Reads the package manager version pinned by `packageManager`, the exact one the generated workflow installs.
+ * @param {Record<string, unknown>} manifest - Parsed project `package.json`.
+ * @returns {string | null} Pinned version such as `11.5.1`, or `null` when the field is absent or not a safe pin.
+ */
+export declare function extractPinnedPackageManagerVersion(manifest: Record<string, unknown>): string | null;
+/**
+ * Reads the major of the Node.js running setup, the runtime the generated workflow falls back to
+ * when HEAD commits no `.nvmrc`.
+ * @returns {string} Major version such as `22`.
+ */
+export declare function readRunningNodeMajor(): string;
+/**
+ * Describes the Node.js version the generated workflow asks `actions/setup-node` for: the
+ * `.nvmrc` pin when HEAD commits it as a regular file, otherwise the major of the Node.js running
+ * setup. Only HEAD counts because the worker checks out the release commit built from it: an
+ * untracked, ignored or set-aside `.nvmrc` would make `node-version-file` fail there after the tag
+ * was pushed. Reading HEAD also keeps the rendered workflow deterministic for the drift check.
+ * @param {string} repositoryRoot - Project checkout.
+ * @returns {Promise<{ pinnedFile: string | null, version: string }>} Pin file the workflow reads (or `null`) and its version without a `v` prefix.
+ * @throws {ReleaseStepError} When Git cannot list or read HEAD.
+ */
+export declare function describeCiNodeVersion(repositoryRoot: string): Promise<{
+    pinnedFile: string | null;
+    version: string;
+}>;
+export type ProjectGithubPackagesConfig = {
+    /**
+     * - A literal registry or any project credential selects GitHub Packages.
+     */
+    usesGithubPackages: boolean;
+    /**
+     * - Variable expanded by the accepted host token (`${NAME}`), or `null`.
+     */
+    tokenVariable: string | null;
+    /**
+     * - Effective top-level entries, validated by
+     * {@link assertProjectNpmConfigEntriesSupported}.
+     */
+    entries: Array<{
+        key: string;
+        value: string | true;
+    }>;
+    /**
+     * - Git tree mode of a committed `.npmrc` that is not a regular file
+     * (a symlink, `120000`, or another kind of entry), which npm still follows in the worker; `null` otherwise.
+     */
+    irregularFileMode: string | null;
+};
+export type CommittedPackageManagerFile = {
+    /**
+     * - Root-relative path of the file committed at HEAD.
+     */
+    filePath: string;
+    /**
+     * - Committed content, or `null` when the entry is not a regular file.
+     */
+    text: string | null;
+    /**
+     * - Git tree mode of an entry that is not a regular file (a symlink,
+     * `120000`, or another kind of entry), which the package manager still follows in the worker; `null` otherwise.
+     */
+    irregularFileMode: string | null;
+};
+/**
+ * Renders the release workflow and keeps the GitHub Packages description it was rendered from, so a caller
+ * can compare the workflow first and validate that setup afterwards without describing it twice.
+ * @param {string} repositoryRoot - Project checkout.
+ * @param {ResolvedCreateVersionConfig} config - Release hooks and package manager.
+ * @returns {Promise<{ content: string, assertGithubPackagesSetupSupported: () => Promise<void> }>} GitHub Actions YAML,
+ *   and the check that the generated workflow can authenticate the project's GitHub Packages setup.
+ * @throws {ReleaseStepError} When Git cannot list or read HEAD or the worker bindings are invalid.
+ */
+export declare function prepareCiReleaseWorkflow(repositoryRoot: string, config: ResolvedCreateVersionConfig): Promise<{
+    content: string;
+    assertGithubPackagesSetupSupported: () => Promise<void>;
+}>;
+/**
+ * Renders a workflow that installs the project's package manager and finishes a pinned release.
+ * @param {string} repositoryRoot - Project checkout.
+ * @param {ResolvedCreateVersionConfig} config - Release hooks and package manager.
+ * @param {{ validateGithubPackages?: boolean }} [options] - `validateGithubPackages: false` only renders,
+ *   for comparisons against a committed workflow that may be customized and authenticate on its own.
+ * @returns {Promise<string>} GitHub Actions YAML.
+ * @throws {ReleaseStepError} When Git cannot list or read HEAD or, while validating, the GitHub Packages
+ *   setup is unsupported (see {@link assertGeneratedGithubPackagesSetupSupported}).
+ */
+export declare function renderCiReleaseWorkflow(repositoryRoot: string, config: ResolvedCreateVersionConfig, { validateGithubPackages }?: {
+    validateGithubPackages?: boolean;
+}): Promise<string>;
+/**
+ * Prepares a named CI export and a new workflow without replacing existing project code.
+ * Syntax is checked with Node before anything in the project is written.
+ * @param {string} repositoryRoot - Checkout whose configuration is already loaded.
+ * @param {ResolvedCreateVersionConfig} config - Configuration selecting the default workflow.
+ * @param {boolean} [writeConfiguration] - Add a named CI export only when settings were absent.
+ * @returns {Promise<ReleaseFileUpdate[]>} Files to include atomically with the bump.
+ * @throws {ReleaseStepError} When an existing workflow would be overwritten or configuration cannot be extended.
+ */
+export declare function prepareCiSetupFiles(repositoryRoot: string, config: ResolvedCreateVersionConfig, writeConfiguration?: boolean): Promise<ReleaseFileUpdate[]>;
+/**
+ * Records the execution mode for the early Vercel build gate without importing project dependencies.
+ * @param {string} repositoryRoot - Project root.
+ * @param {string} version - Version of the release being committed.
+ * @param {"local" | "ci"} execution - Execution location chosen for this release.
+ * @returns {ReleaseFileUpdate} Version-scoped metadata included in the bump.
+ */
+export declare function prepareCiReleaseMetadata(repositoryRoot: string, version: string, execution: "local" | "ci"): ReleaseFileUpdate;
+/**
+ * Prevents concurrent editor changes from being overwritten after an interactive version prompt.
+ * @param {string} repositoryRoot - Checkout about to receive the bump.
+ * @param {ReleaseFileUpdate[]} updates - CI files captured before prompting.
+ * @returns {void}
+ * @throws {ReleaseStepError} When a captured file changed or a new workflow appeared.
+ */
+export declare function assertCiSetupFilesUnchanged(repositoryRoot: string, updates: ReleaseFileUpdate[]): void;
+/**
+ * Rejects symlinks anywhere in an owned setup path before writes can leave the checkout.
+ * @param {string} repositoryRoot - Trusted checkout root.
+ * @param {string} relativePath - Constant or validated relative file path.
+ * @returns {void}
+ * @throws {ReleaseStepError} When an existing path component is a symlink.
+ */
+export declare function assertSafeCiPath(repositoryRoot: string, relativePath: string): void;

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

@@ -0,0 +1,145 @@
+/**
+ * Selects the release location and plans the worker for an already-created release tag.
+ * @module create-version/ci
+ */
+/**
+ * Selects the execution location without ever dispatching again inside a CI runtime.
+ * @param {import("./config.js").ResolvedCreateVersionConfig} config - Project configuration.
+ * @param {import("./plan.js").ReleaseOptions} options - CLI overrides.
+ * @returns {Promise<{ execution: "local" | "ci", setup: boolean } | null>} Selection, or null when canceled.
+ */
+export declare function chooseReleaseExecution(config: import("./config.js").ResolvedCreateVersionConfig, options: import("./plan.js").ReleaseOptions): Promise<{
+    execution: "local" | "ci";
+    setup: boolean;
+} | null>;
+/**
+ * Rejects registry authentication that a non-interactive GitHub Actions worker can never complete,
+ * before the immutable release commit and tag exist (or before a retry dispatches them again).
+ * OIDC stays allowed, since only the worker can prove it, except when the runtime the generated
+ * workflow sets up provably cannot perform npm trusted publishing: the worker would reject it only
+ * after the release was pushed. The Node.js runtime is checked for every package manager. With npm,
+ * the version pinned by `packageManager` is checked too and never raised silently, because that
+ * would change the client that runs `npm ci` against the committed lockfile; an unpinned npm
+ * project and other package managers get a capable npm installed by the workflow for publication
+ * (see `requiresCiNpmOidcClient`), after `npm ci` in the unpinned npm case. The effective npm
+ * destination is resolved as well, since trusted publishing only exists on the public npm registry.
+ * A token publication named `GITHUB_TOKEN` gets the built-in Actions token injected by the generated
+ * workflow, which only GitHub Packages accepts, so its effective destination is resolved too.
+ * @param {import("./config.js").ResolvedCreateVersionConfig} config - Project configuration.
+ * @param {string} repositoryRoot - Project root whose `package.json`, `.nvmrc` and npm config pin the worker's runtime and destination.
+ * @returns {Promise<void>}
+ * @throws {ReleaseStepError} When the registry publication authorizes from a browser, uses npm OIDC with a Node.js or npm pin below the trusted publishing minimum or a registry other than the public npm one, or names `GITHUB_TOKEN` as the token of a destination other than GitHub Packages.
+ */
+export declare function assertCiCompatiblePublication(config: import("./config.js").ResolvedCreateVersionConfig, repositoryRoot: string): Promise<void>;
+/**
+ * Rejects resuming a pending release in a location different from the one it was prepared in: the
+ * Vercel build gate decides from the committed release metadata, and a CI preparation skipped the
+ * checks and migrations that a local resume (which only pushes and publishes) would never run.
+ * The Vercel metadata wins when it names this version; otherwise the release commit trailer decides.
+ * Release commits without either mark (created before they existed) are accepted as before.
+ * @param {import("./process.js").GitReader} reader - Git reader of the checkout whose HEAD is the release commit.
+ * @param {string} version - Version of the pending release.
+ * @param {"local" | "ci"} execution - Location selected for this run.
+ * @returns {Promise<void>}
+ * @throws {ReleaseStepError} When the committed mark belongs to this version and names another location, or is unreadable.
+ */
+export declare function assertResumeExecutionMatches(reader: import("./process.js").GitReader, version: string, execution: "local" | "ci"): Promise<void>;
+/**
+ * Reads the configured workflow from HEAD after checking it is a regular file inside the project.
+ * `gh workflow run --ref <tag>` only finds workflows contained in the pushed release commit, so a
+ * local file that is untracked, ignored or set aside by `--ignore-local-changes` is not enough.
+ * @param {string} repositoryRoot - Project root.
+ * @param {string} workflow - Validated workflow filename.
+ * @param {string} [missingHint] - Recovery hint shown when HEAD does not contain the workflow.
+ * @returns {Promise<string>} Workflow content committed at HEAD.
+ * @throws {ReleaseStepError} When the workflow is missing, a symlink or not committed at HEAD.
+ */
+export declare function readCommittedCiWorkflow(repositoryRoot: string, workflow: string, missingHint?: string): Promise<string>;
+/**
+ * Rejects the generated workflow when HEAD has no lockfile of the project's package manager: it
+ * installs dependencies with a frozen lockfile (`npm ci`, `pnpm install --frozen-lockfile`,
+ * `yarn install --frozen-lockfile`/`--immutable`, `bun install --frozen-lockfile`), which fails
+ * without one, so the worker would stop only after the release commit and tag were pushed.
+ * A file present on disk is not enough: the worker checks out the pushed release commit.
+ * @param {string} repositoryRoot - Project root.
+ * @param {import("../package-manager.js").PackageManagerName} packageManager - Package manager the workflow installs with.
+ * @returns {Promise<void>}
+ * @throws {ReleaseStepError} When HEAD cannot be listed or contains none of the package manager's lockfiles.
+ */
+export declare function assertCiInstallLockfileCommitted(repositoryRoot: string, packageManager: import("../package-manager.js").PackageManagerName): Promise<void>;
+/**
+ * Rejects the generated workflow when the checkout has a `.nvmrc` that HEAD does not commit as a
+ * regular file (untracked, ignored, set aside by `--ignore-local-changes`, or committed as a
+ * symlink). The workflow only follows the committed pin, so it would silently run the local
+ * Node.js major instead of the pinned runtime, and the npm OIDC check would judge that other
+ * version; stopping before the bump lets the user commit the pin or drop it deliberately.
+ * @param {string} repositoryRoot - Project root.
+ * @returns {Promise<void>}
+ * @throws {ReleaseStepError} When `.nvmrc` exists locally but not as a regular file committed at HEAD, or HEAD cannot be read.
+ */
+export declare function assertCiNodeVersionFileCommitted(repositoryRoot: string): Promise<void>;
+/**
+ * Tells whether the configured workflow committed at HEAD is exactly the one setup renders for the
+ * current configuration, so an ordinary CI release knows it installs dependencies with a frozen
+ * lockfile and follows the committed `.nvmrc` like `--setup-ci` does. A missing, non-regular or
+ * customized workflow is not the generated one; its own checks stay with the release flow. The
+ * comparison renders without the generated workflow's GitHub Packages validations, so a customized
+ * workflow that authenticates on its own is never blocked by them; they run only once the committed
+ * workflow is known to be the generated one. A workflow that only lacks the GitHub Packages authentication
+ * lines (see {@link lacksOnlyGithubPackagesAuthentication}) was generated before that authentication existed:
+ * releasing with it would fail with 401 after the tag was pushed, so it is rejected instead of treated as customized.
+ * @param {string} repositoryRoot - Project root.
+ * @param {import("./config.js").ResolvedCreateVersionConfig} config - Project configuration.
+ * @returns {Promise<boolean>} True when HEAD commits the generated workflow unchanged.
+ * @throws {ReleaseStepError} When Git cannot list or read HEAD, HEAD commits the generated workflow
+ *   with a GitHub Packages setup it cannot authenticate, or a generated workflow without that authentication.
+ */
+export declare function isCommittedCiWorkflowGenerated(repositoryRoot: string, config: import("./config.js").ResolvedCreateVersionConfig): Promise<boolean>;
+/**
+ * Rejects `--setup-ci` over an existing workflow whose committed content no longer matches what
+ * setup would generate for the current configuration (for example a new publication token binding).
+ * Regeneration is never automatic: the committed file may hold intentional manual edits, so the
+ * user decides between regenerating it and releasing with the customized workflow through `--ci`.
+ * @param {string} repositoryRoot - Project root.
+ * @param {import("./config.js").ResolvedCreateVersionConfig} config - Configuration with a validated `ci.workflow`.
+ * @returns {Promise<void>}
+ * @throws {ReleaseStepError} When the workflow is not committed at HEAD or differs from the rendered one.
+ */
+export declare function assertGeneratedCiWorkflowCurrent(repositoryRoot: string, config: import("./config.js").ResolvedCreateVersionConfig): Promise<void>;
+/**
+ * Reads an immutable release identity and proves it already exists on origin/main.
+ * @param {import("./process.js").GitReader} reader - Git reader.
+ * @param {string} tag - Stable release tag, vX.Y.Z.
+ * @param {boolean} [requireHead] - Require the checkout to be exactly this release.
+ * @returns {Promise<import("./github-workflow.js").CiReleaseIdentity>} Verified remote identity.
+ * @throws {ReleaseStepError} When the tag, commit, version or checkout differs.
+ */
+export declare function readCiReleaseIdentity(reader: import("./process.js").GitReader, tag: string, requireHead?: boolean): Promise<import("./github-workflow.js").CiReleaseIdentity>;
+/**
+ * Appends dispatch to the minimal local preparation plan.
+ * @param {import("./plan.js").ReleasePlan} plan - Existing bump/push plan.
+ * @returns {import("./plan.js").ReleasePlan} Plan whose last step only submits the worker.
+ */
+export declare function appendCiDispatch(plan: import("./plan.js").ReleasePlan): import("./plan.js").ReleasePlan;
+/**
+ * Plans checks and unfinished publication for a pinned worker; never bumps or pushes.
+ * @param {import("./state.js").ReleaseSnapshot} state - Diagnosed worker checkout.
+ * @param {import("./plan.js").ReleaseCapabilities} capabilities - Normal project hooks.
+ * A retry after the registry publication succeeded skips migrations and publication, but still
+ * re-runs the preparation when the workflow deploys afterwards: the retry starts from a fresh
+ * checkout, so files or setup produced by `prepare` would otherwise be missing from the deployment.
+ * @param {string} version - Existing release version.
+ * A custom publisher leaves no registry record, so its completion comes from the worker's Actions
+ * history (see `findCompletedCiPublication`) and is treated exactly like a confirmed registry publication.
+ * @param {boolean} [deploymentFollows] - Whether the workflow deploys (for example to Vercel) after this worker finishes.
+ * @param {boolean} [customPublicationCompleted] - Whether an earlier run or attempt already finished the custom publisher.
+ * @returns {import("./plan.js").ReleasePlan} Worker-only execution plan.
+ */
+export declare function buildCiWorkerPlan(state: import("./state.js").ReleaseSnapshot, capabilities: import("./plan.js").ReleaseCapabilities, version: string, deploymentFollows?: boolean, customPublicationCompleted?: boolean): import("./plan.js").ReleasePlan;
+/**
+ * Derives setup defaults from the application's deployment and migration configuration.
+ * @param {string} repositoryRoot - Checkout offered automatic setup.
+ * @param {import("./config.js").ResolvedCreateVersionConfig} config - Existing project hooks.
+ * @returns {import("./ci-config.js").ResolvedCiReleaseConfig} In-memory settings, committed only with a successful bump.
+ */
+export declare function defaultCiReleaseConfig(repositoryRoot: string, config: import("./config.js").ResolvedCreateVersionConfig): import("./ci-config.js").ResolvedCiReleaseConfig;

package/types/create-version/committed-tree.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Reads files from the commit at HEAD: the content a CI worker checks out from the pushed release
+ * commit, unlike the working tree, which may hold untracked, ignored or set-aside files.
+ * @module create-version/committed-tree
+ */
+export type CommittedTreeEntry = {
+    /**
+     * - Git tree mode, such as `100644` or `120000`.
+     */
+    mode: string;
+    /**
+     * - Git object type, such as `blob` or `tree`.
+     */
+    type: string;
+    /**
+     * - Object id of the entry.
+     */
+    objectId: string;
+    /**
+     * - Path relative to the repository root.
+     */
+    filePath: string;
+};
+/**
+ * Lists which of the given root-relative paths HEAD contains.
+ * @param {string} repositoryRoot - Project root.
+ * @param {string[]} filePaths - Root-relative paths to look up.
+ * @returns {Promise<CommittedTreeEntry[]>} Entries found at HEAD; absent paths are omitted.
+ * @throws {ReleaseStepError} When `git ls-tree` fails, for example without a commit at HEAD.
+ */
+export declare function listCommittedTreeEntries(repositoryRoot: string, filePaths: string[]): Promise<CommittedTreeEntry[]>;
+/**
+ * Tells whether a HEAD tree entry is a regular file, which the worker checks out as is; a symlink,
+ * submodule or directory is not.
+ * @param {CommittedTreeEntry} entry - Entry listed by {@link listCommittedTreeEntries}.
+ * @returns {boolean} True for a blob with one of {@link GIT_REGULAR_FILE_MODES}.
+ */
+export declare function isCommittedRegularFile(entry: CommittedTreeEntry): boolean;
+/**
+ * Reads the content of a regular file entry of HEAD.
+ * @param {string} repositoryRoot - Project root.
+ * @param {CommittedTreeEntry} entry - Regular file entry (see {@link isCommittedRegularFile}).
+ * @returns {Promise<string>} Committed content.
+ * @throws {ReleaseStepError} When Git cannot read the committed object.
+ */
+export declare function readCommittedFileEntry(repositoryRoot: string, entry: CommittedTreeEntry): Promise<string>;
+/**
+ * Reads a file committed at HEAD only when it is a regular file, which the worker checks out as is;
+ * a symlink, submodule or directory at that path counts as absent.
+ * @param {string} repositoryRoot - Project root.
+ * @param {string} filePath - Root-relative path.
+ * @returns {Promise<string | null>} Committed content, or `null` when HEAD has no regular file there.
+ * @throws {ReleaseStepError} When Git cannot list HEAD or read the committed object.
+ */
+export declare function readCommittedRegularFile(repositoryRoot: string, filePath: string): Promise<string | null>;

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

@@ -0,0 +1,128 @@
+/**
+ * Loads and validates `astra-rp.config.js`, the per-project part of
+ * `astra-rp create-version`: version
+ * descriptions, registry, checks, migrations, preparation and publication.
+ *
+ * The configuration never needs to import `@astra-kit/rp`: hooks receive every
+ * helper through their context, so a project can type it with
+ * `@type {import("@astra-kit/rp/create-version").CreateVersionConfig}` only.
+ *
+ * @module create-version/config
+ */
+export type GitReader = import("./process.js").GitReader;
+export type ProjectCommands = import("../package-manager.js").ProjectCommands;
+export type ReleaseType = "patch" | "minor" | "major";
+export type MigrationCheck = {
+    status: "up-to-date" | "pending" | "unknown";
+    pending: string[];
+    target: string | null;
+    reason: string | null;
+};
+export type HookContext = {
+    repositoryRoot: string;
+    version: string | null;
+    git: GitReader;
+    run: (commandLine: string) => Promise<number>;
+    print: (text?: string) => void;
+    fail: (message: string, hint: string) => never;
+    releases?: {
+        name: string;
+        version: string;
+        directory: string;
+    }[];
+};
+export type ReleaseHook = (context: HookContext) => Promise<void> | void;
+export type MigrationsAdapter = {
+    check: (context: HookContext) => Promise<MigrationCheck> | MigrationCheck;
+    apply: (context: HookContext) => Promise<void> | void;
+    targetHint?: string;
+};
+export type CreateVersionConfig = {
+    projectName?: string;
+    releaseTypeDescriptions?: Partial<Record<ReleaseType, string>>;
+    preMajorShift?: boolean;
+    registry?: import("./registry-config.js").RegistryProvider | null;
+    publication?: import("./registry-config.js").PublicationOptions;
+    publishedLabel?: string;
+    checks?: string[] | false;
+    migrations?: MigrationsAdapter | null;
+    prepare?: string[] | ReleaseHook | null;
+    publish?: import("./registry-config.js").RegistryProvider | ReleaseHook | null;
+    artifact?: string | null;
+    summary?: string[];
+    versionFiles?: string[];
+    packages?: "workspaces" | string[];
+    tagFormat?: string;
+    ci?: import("./ci-config.js").CiReleaseConfig | null;
+    releaseTimeZone?: string;
+    changelogDraft?: boolean | import("./changelog-draft.js").ChangelogDraftProvider[];
+};
+export type ResolvedCreateVersionConfig = {
+    projectName: string | null;
+    releaseTypeDescriptions: Record<ReleaseType, string>;
+    preMajorShift: boolean;
+    registry: import("./registry-config.js").RegistryProvider | null;
+    publication: import("./registry-config.js").ResolvedPublicationOptions;
+    publishedLabel: string;
+    checks: string[] | null;
+    migrations: MigrationsAdapter | null;
+    prepare: string[] | ReleaseHook | null;
+    publish: import("./registry-config.js").RegistryProvider | ReleaseHook | null;
+    artifact: string | null;
+    summary: string[];
+    versionFiles: string[];
+    packages: "workspaces" | string[] | null;
+    tagFormat: string | null;
+    ci: import("./ci-config.js").ResolvedCiReleaseConfig | null;
+    releaseTimeZone: string | null;
+    changelogDraft: import("./changelog-draft.js").ChangelogDraftProvider[];
+    commands: ProjectCommands;
+};
+export type ConfigResolutionContext = {
+    packageScripts?: Record<string, unknown>;
+    commands?: ProjectCommands;
+};
+/**
+ * Describes the release types offered after `currentVersion`. While `preMajorShift` applies (the
+ * same `0.x` rule as the suggestion), the default descriptions move one level down with the
+ * suggestion: a patch carries features and a minor breaking changes. Descriptions the project
+ * defined are kept as they are.
+ *
+ * @param {Pick<ResolvedCreateVersionConfig, "releaseTypeDescriptions" | "preMajorShift">} config - Resolved configuration.
+ * @param {string} currentVersion - Current `X.Y.Z` version.
+ * @returns {Record<ReleaseType, string>} Description of each release type.
+ */
+export declare function describeReleaseTypes({ releaseTypeDescriptions, preMajorShift }: Pick<ResolvedCreateVersionConfig, "releaseTypeDescriptions" | "preMajorShift">, currentVersion: string): Record<ReleaseType, string>;
+/**
+ * Types a configuration in editors; returns it unchanged.
+ *
+ * @param {CreateVersionConfig} config - Project configuration.
+ * @returns {CreateVersionConfig} The same configuration.
+ */
+export declare function defineCreateVersionConfig(config: CreateVersionConfig): CreateVersionConfig;
+/**
+ * Validates a raw configuration and fills its defaults.
+ *
+ * @param {unknown} rawConfig - Default export of `astra-rp.config.js`.
+ * @param {ConfigResolutionContext} [resolutionContext] - Project data the defaults depend on.
+ * @returns {ResolvedCreateVersionConfig} Configuration ready for the command.
+ * @throws {Error} When a field has an unsupported type or value.
+ */
+export declare function resolveCreateVersionConfig(rawConfig: unknown, { packageScripts, commands }?: ConfigResolutionContext): ResolvedCreateVersionConfig;
+/**
+ * Tells whether a configured path stays inside the project root: relative, without `..` segments.
+ *
+ * @param {string} filePath - Configured path.
+ * @returns {boolean} Whether it is a relative path that cannot escape the root.
+ */
+export declare function isPathInsideRoot(filePath: string): boolean;
+/**
+ * Imports `astra-rp.config.mjs` or `astra-rp.config.js` from the repository root and validates it.
+ * It is imported once per process: after syncing `main` the command stops and asks to run it
+ * again, so a new process imports the updated file and everything it imports.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {Promise<ResolvedCreateVersionConfig>} Resolved configuration.
+ * @throws {Error} When the file is missing, fails to load or is invalid.
+ */
+export declare function loadCreateVersionConfig(repositoryRoot: string): Promise<ResolvedCreateVersionConfig>;

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

@@ -0,0 +1,39 @@
+/**
+ * Errors of `astra-rp create-version`.
+ *
+ * @module create-version/errors
+ */
+/**
+ * Describes any thrown value for a Spanish message: the message of an `Error`, otherwise its text.
+ *
+ * @param {unknown} error - Thrown value.
+ * @returns {string} Message to quote.
+ */
+export declare function describeError(error: unknown): string;
+/** Failure of a release step or hook, with a Spanish explanation and the next action to take. */
+export declare class ReleaseStepError extends Error {
+    hint: string;
+    /**
+     * @param {string} message - What failed, in Spanish.
+     * @param {string} hint - What to do next, in Spanish.
+     * @param {{ cause?: unknown }} [options] - Original error, when wrapping one.
+     */
+    constructor(message: string, hint: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Reports a CI boundary failure while retaining the release identity for a safe retry.
+ * @extends ReleaseStepError
+ */
+export declare class CiReleaseError extends ReleaseStepError {
+    code: "ci-dispatch-unconfirmed" | "ci-preflight-failed" | "ci-run-lookup-failed";
+    /**
+     * @param {"ci-preflight-failed" | "ci-run-lookup-failed" | "ci-dispatch-unconfirmed"} code - Stable failure category.
+     * @param {string} message - Safe Spanish diagnostic.
+     * @param {string} hint - Recovery action preserving the existing release.
+     * @param {{ cause?: unknown }} [options] - Original dependency failure.
+     */
+    constructor(code: "ci-preflight-failed" | "ci-run-lookup-failed" | "ci-dispatch-unconfirmed", message: string, hint: string, options?: {
+        cause?: unknown;
+    });
+}

package/types/create-version/github-workflow.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Adapts GitHub CLI for credential preflight and dispatch reconciliation.
+ * @module create-version/github-workflow
+ */
+import { runCaptured } from "./process.js";
+export type CiReleaseIdentity = {
+    version: string;
+    tag: string;
+    sha: string;
+};
+export type CiDispatchResult = {
+    status: "submitted" | "existing";
+    url: string | null;
+};
+export type ActionsBindingKind = "secret" | "variable";
+export type GithubWorkflowClient = {
+    preflight: (workflow: string, secrets: string[], variables: string[]) => Promise<void>;
+    dispatch: (workflow: string, release: CiReleaseIdentity, retryCommand: string) => Promise<CiDispatchResult>;
+};
+/**
+ * @typedef {{ version: string, tag: string, sha: string }} CiReleaseIdentity
+ * @typedef {{ status: "submitted" | "existing", url: string | null }} CiDispatchResult
+ * @typedef {"secret" | "variable"} ActionsBindingKind
+ * @typedef {{
+ *   preflight: (workflow: string, secrets: string[], variables: string[]) => Promise<void>,
+ *   dispatch: (workflow: string, release: CiReleaseIdentity, retryCommand: string) => Promise<CiDispatchResult>,
+ * }} GithubWorkflowClient
+ */
+/**
+ * Builds the `run-name` the generated workflow gives a dispatched release, which identifies its runs.
+ * @param {CiReleaseIdentity} release - Dispatched release.
+ * @returns {string} Run title, such as `astra-rp release v1.2.4 <sha>`.
+ */
+export declare function formatCiReleaseRunTitle(release: CiReleaseIdentity): string;
+/**
+ * Creates a GitHub workflow adapter with an explicit subprocess boundary.
+ * @param {string} repositoryRoot - Checkout whose origin selects the repository.
+ * @param {typeof runCaptured} [capture] - Process executor, injectable by other CLI hosts.
+ * @returns {GithubWorkflowClient} Preflight and dispatch operations.
+ */
+export declare function createGithubWorkflowClient(repositoryRoot: string, capture?: typeof runCaptured): GithubWorkflowClient;

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

@@ -0,0 +1,28 @@
+/**
+ * `@astra-kit/rp/create-version`: shared release command.
+ *
+ * Projects run it as `astra-rp create-version` and describe their differences
+ * in `astra-rp.config.js` (checks, migrations,
+ * preparation, publication). The pure planner and the state reader are
+ * exported for project tests and custom tooling.
+ *
+ * @module create-version
+ */
+export type CreateVersionConfig = import("./config.js").CreateVersionConfig;
+export type CiReleaseConfig = import("./ci-config.js").CiReleaseConfig;
+/**
+ * @typedef {import("./config.js").CreateVersionConfig} CreateVersionConfig
+ * @typedef {import("./ci-config.js").CiReleaseConfig} CiReleaseConfig
+ */
+export { computeNpmIntegrity, computeSha256, expandArtifactPattern, findPnpmPackRewrites, findPreparedArtifact, isSafeArtifactPath, verifyPreparedArtifact, withArtifactOutsidePackageRoot, } from "./artifact.js";
+export { defineCreateVersionConfig, loadCreateVersionConfig, resolveCreateVersionConfig } from "./config.js";
+export { CiReleaseError, ReleaseStepError } from "./errors.js";
+export { resolveCiReleaseConfig } from "./ci-config.js";
+export { buildNpmAuthConfigLine, buildNpmOwnerListArguments, buildNpmPublishArguments, buildNpmPublishEnvironment, buildNpmTokenEnvironment, buildNpmViewArguments, buildNpmWhoamiArguments, checkNpmPublishAccess, lookupPublishedVersions, parseNpmOwnerList, parseNpmPackDryRunOutput, publishToNpm, readNpmPackIntegrity, resolveNpmToken, resolvePublishRegistry, withNpmAuthConfig, } from "./npm.js";
+export { describeNpmAuthProblem, describeNpmPublishFailure, describeNpmTokenSource } from "./npm-auth.js";
+export { DEFAULT_CAPABILITIES, RELEASE_USAGE, buildReleasePlan, describeFeatureBranchGaps, parseReleaseArguments } from "./plan.js";
+export { createGitReader, listCommits, parseCommitLog, readPackageManifestAt, readPackageVersionAt, runCaptured, runCommandLine, runInherited } from "./process.js";
+export { createHookContext, runCreateVersion } from "./run.js";
+export { collectReleaseState, findLastRelease, readChangelogState } from "./state.js";
+export { isRegistryProvider, resolvePublicationOptions } from "./registry-config.js";
+export { checkRegistryAccess, lookupRegistryVersions, resolveRegistry, selectProjectRegistry } from "./registry.js";