@astra-kit/rp 0.0.0-stage → 0.10.0

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

@@ -0,0 +1,369 @@
+/**
+ * Pure release planning of `astra-rp create-version`.
+ *
+ * Receives the snapshot gathered by `state.js` and the project capabilities,
+ * and decides without touching Git, npm or databases what is still missing
+ * to ship a release from `main`:
+ *
+ * - a new release: sync `main`, verify the manual changelog and its `[Unreleased]` entries, apply migrations, run the
+ *   checks, bump (commit `X.Y.Z` + tag `vX.Y.Z`), prepare, push and publish;
+ * - the resume of a release commit that never reached `origin` or the registry,
+ *   including the publication of a tagged release from a detached `HEAD`;
+ * - nothing, when every commit is already released;
+ * - blockers that explain what to fix first (feature branch, uncommitted
+ *   files, foreign commits on `main`, unreachable registry, invalid changelog,
+ *   npm credentials that cannot publish, a last release missing from npm).
+ *
+ * @module create-version/plan
+ */
+export type ReleaseCommit = {
+    sha?: string;
+    subject: string;
+    body?: string;
+};
+export type FeatureBranchSnapshot = {
+    name: string;
+    headSha: string;
+    hasUpstream: boolean;
+    unpushedCount: number;
+    aheadOfMainCount: number;
+};
+export type PullRequestSnapshot = {
+    number: number;
+    url: string;
+    title?: string;
+    state: string;
+    isDraft: boolean;
+    headRefOid: string;
+};
+export type NpmLookup = import("./npm.js").NpmLookup;
+export type NpmAuthCheck = import("./npm.js").NpmAuthCheck;
+export type MigrationCheck = import("./config.js").MigrationCheck;
+export type LastReleaseSnapshot = {
+    sha: string;
+    version: string | null;
+    subject?: string | null;
+    tagged?: boolean;
+};
+export type ReleaseState = {
+    currentBranch: string | null;
+    workingTreeChanges: string[];
+    branch?: FeatureBranchSnapshot | null;
+    pullRequest?: PullRequestSnapshot | null;
+    githubError?: string | null;
+    main: {
+        aheadCommits: ReleaseCommit[];
+        behindCount: number;
+    };
+    headVersion: string | null;
+    headSubject: string | null;
+    headSha?: string | null;
+    headReleaseTag?: string | null;
+    remoteReleaseTagSha?: string | null;
+    headOnRemoteMain?: boolean;
+    releasedVersion?: string | null;
+    lastRelease?: LastReleaseSnapshot | null;
+    unreleasedCommits: ReleaseCommit[];
+    npm: NpmLookup | null;
+    npmAuth?: NpmAuthCheck | null;
+    migrations: MigrationCheck | null;
+    changelog: {
+        exists: boolean;
+        entryCount: number;
+        unknownSections: string[];
+        updated: boolean;
+        reason: string | null;
+    };
+};
+export type ProjectCommands = import("../package-manager.js").ProjectCommands;
+export type ReleaseCapabilities = {
+    checks: boolean;
+    checksMissing?: boolean;
+    prepare: boolean;
+    publish: boolean;
+    publishTitle: string;
+    commands?: ProjectCommands;
+};
+export type ReleasePlanStep = {
+    id: string;
+    title: string;
+    detail?: string;
+};
+export type ReleaseBlocker = {
+    code?: "changelog-update-required";
+    title: string;
+    details: string[];
+};
+export type ReleasePlan = {
+    mode: string;
+    steps: ReleasePlanStep[];
+    blockers: ReleaseBlocker[];
+    warnings: string[];
+    pendingVersion: string | null;
+};
+export type ReleaseOptions = {
+    bump: "patch" | "minor" | "major" | null;
+    setVersion: string | null;
+    dryRun: boolean;
+    skipUnpublished: boolean;
+    ignoreLocalChanges: boolean;
+    acceptSuggested: boolean;
+    help: boolean;
+    execution?: "local" | "ci" | null;
+    setupCi?: boolean;
+    ciRelease?: string | null;
+    retryCi?: string | null;
+};
+export type UnpublishedRelease = {
+    version: string;
+    latestPublished: string | null;
+    resumable: boolean;
+    registryLabel?: string;
+};
+export type PlanOptions = {
+    skipUnpublished?: boolean;
+    ignoreLocalChanges?: boolean;
+    ciWorkerFiles?: readonly string[];
+};
+/**
+ * @typedef {{ sha?: string, subject: string, body?: string }} ReleaseCommit
+ * @typedef {{ name: string, headSha: string, hasUpstream: boolean, unpushedCount: number, aheadOfMainCount: number }} FeatureBranchSnapshot
+ * @typedef {{ number: number, url: string, title?: string, state: string, isDraft: boolean, headRefOid: string }} PullRequestSnapshot
+ * @typedef {import("./npm.js").NpmLookup} NpmLookup
+ * @typedef {import("./npm.js").NpmAuthCheck} NpmAuthCheck
+ * @typedef {import("./config.js").MigrationCheck} MigrationCheck
+ * @typedef {{ sha: string, version: string | null, subject?: string | null, tagged?: boolean }} LastReleaseSnapshot
+ *   Newest commit of `origin/main` that changed `version`; `tagged` when `vX.Y.Z` points at it.
+ * @typedef {{
+ *   currentBranch: string | null,
+ *   workingTreeChanges: string[],
+ *   branch?: FeatureBranchSnapshot | null,
+ *   pullRequest?: PullRequestSnapshot | null,
+ *   githubError?: string | null,
+ *   main: { aheadCommits: ReleaseCommit[], behindCount: number },
+ *   headVersion: string | null,
+ *   headSubject: string | null,
+ *   headSha?: string | null,
+ *   headReleaseTag?: string | null,
+ *   remoteReleaseTagSha?: string | null,
+ *   headOnRemoteMain?: boolean,
+ *   releasedVersion?: string | null,
+ *   lastRelease?: LastReleaseSnapshot | null,
+ *   unreleasedCommits: ReleaseCommit[],
+ *   npm: NpmLookup | null,
+ *   npmAuth?: NpmAuthCheck | null,
+ *   migrations: MigrationCheck | null,
+ *   changelog: { exists: boolean, entryCount: number, unknownSections: string[], updated: boolean, reason: string | null },
+ * }} ReleaseState
+ * @typedef {import("../package-manager.js").ProjectCommands} ProjectCommands
+ * @typedef {{ checks: boolean, checksMissing?: boolean, prepare: boolean, publish: boolean, publishTitle: string, commands?: ProjectCommands }} ReleaseCapabilities
+ *   `checksMissing` means the project configures no checks, has no `ci` script and did not skip
+ *   them with `checks: false`: a new release is blocked. `commands` are the project's package
+ *   manager commands quoted by every hint (pnpm when omitted).
+ * @typedef {{ id: string, title: string, detail?: string }} ReleasePlanStep
+ * @typedef {{ code?: "changelog-update-required", title: string, details: string[] }} ReleaseBlocker
+ * @typedef {{ mode: string, steps: ReleasePlanStep[], blockers: ReleaseBlocker[], warnings: string[], pendingVersion: string | null }} ReleasePlan
+ * @typedef {{ bump: "patch" | "minor" | "major" | null, setVersion: string | null, dryRun: boolean, skipUnpublished: boolean, ignoreLocalChanges: boolean, acceptSuggested: boolean, help: boolean, execution?: "local" | "ci" | null, setupCi?: boolean, ciRelease?: string | null, retryCi?: string | null }} ReleaseOptions
+ *   `acceptSuggested` takes the release type the commits suggest instead of asking.
+ * @typedef {{ version: string, latestPublished: string | null, resumable: boolean, registryLabel?: string }} UnpublishedRelease
+ * @typedef {{ skipUnpublished?: boolean, ignoreLocalChanges?: boolean, ciWorkerFiles?: readonly string[] }} PlanOptions
+ *   `skipUnpublished` plans a new release even when the last release is missing from npm.
+ *   `ignoreLocalChanges` plans the release despite uncommitted changes, which the run sets aside.
+ *   `ciWorkerFiles` lists, only for CI preparation, the root-relative files the worker reads from the
+ *   release tag; `ignoreLocalChanges` cannot set changes to them aside.
+ */
+/** Capabilities of a project without checks, preparation or publication. */
+export declare const DEFAULT_CAPABILITIES: Readonly<{
+    checks: false;
+    checksMissing: false;
+    prepare: false;
+    publish: false;
+    publishTitle: "Publicar el release";
+    commands: Readonly<import("../package-manager.js").ProjectCommands>;
+}>;
+/** Usage printed by `create-version --help` in a pnpm project. */
+export declare const RELEASE_USAGE: string;
+/**
+ * Builds the usage printed by `create-version --help` for the project's package manager.
+ *
+ * @param {ProjectCommands} [commands] - Project commands (pnpm when omitted).
+ * @returns {string} Usage.
+ */
+export declare function buildReleaseUsage(commands?: ProjectCommands): string;
+/**
+ * Parses the command-line arguments of `create-version`.
+ *
+ * @param {string[]} argv - Arguments after the command name.
+ * @returns {ReleaseOptions} Options.
+ * @throws {Error} With a Spanish message when an argument is unknown or invalid.
+ */
+export declare function parseReleaseArguments(argv: string[]): ReleaseOptions;
+/**
+ * Describes what is still missing for a feature branch to reach `main`, so
+ * the blocker tells the user the next concrete action.
+ *
+ * @param {FeatureBranchSnapshot} branch - Branch snapshot.
+ * @param {PullRequestSnapshot | null} pullRequest - Pull request of the branch.
+ * @param {string | null} githubError - Why the pull request could not be read.
+ * @param {ProjectCommands} [commands] - Project commands quoted by the hints (pnpm when omitted).
+ * @returns {string[]} Spanish lines, most urgent first.
+ */
+export declare function describeFeatureBranchGaps(branch: FeatureBranchSnapshot, pullRequest: PullRequestSnapshot | null, githubError: string | null, commands?: ProjectCommands): string[];
+/**
+ * Tells whether the npm lookup of the diagnosis ran and failed, so the plan is blocked before it
+ * could show a publication step; shared with the monorepo mode and the run.
+ *
+ * @param {{ npm?: NpmLookup | null }} snapshot - Repository or package snapshot.
+ * @returns {boolean} `true` when npm was queried and did not answer with the published versions.
+ */
+export declare function hasFailedNpmLookup(snapshot: {
+    npm?: NpmLookup | null;
+}): boolean;
+/**
+ * Explains a failed npm lookup; shared with the monorepo mode. When the registry answered it and
+ * rejected the credential (an invalid or expired token, or a user that cannot publish), an
+ * authenticated `npm view` fails with E401/E403, so the credential blocker explains it: replacing
+ * the token is the fix, not the connection. A missing token never reached the registry, so it does
+ * not explain the lookup.
+ *
+ * @param {NpmLookup} npm - Failed lookup.
+ * @param {NpmAuthCheck | null | undefined} npmAuth - Credential check, when it ran.
+ * @param {ProjectCommands} commands - Project commands quoted by the hints.
+ * @param {{ subject?: string, defaultReason: string }} description - Text after the registry name in the
+ *   title (such as ` para <paquete>`) and the reason shown when the lookup has none.
+ * @returns {ReleaseBlocker} Credential blocker, or the generic lookup blocker.
+ */
+export declare function failedNpmLookupBlocker(npm: NpmLookup, npmAuth: NpmAuthCheck | null | undefined, commands: ProjectCommands, { subject, defaultReason }: {
+    subject?: string;
+    defaultReason: string;
+}): ReleaseBlocker;
+/**
+ * Explains that the releases only leave from `main`; shared with the monorepo mode.
+ *
+ * @param {Pick<ReleaseState, "branch" | "pullRequest" | "githubError"> & { currentBranch: string }} state - Snapshot on a feature branch.
+ * @param {ProjectCommands} commands - Project commands quoted by the hints.
+ * @returns {ReleaseBlocker} Blocker with what is still missing for the branch to reach `main`.
+ */
+export declare function featureBranchBlocker(state: Pick<ReleaseState, "branch" | "pullRequest" | "githubError"> & {
+    currentBranch: string;
+}, commands: ProjectCommands): ReleaseBlocker;
+/**
+ * Lists the uncommitted files that block the release without `--ignore-local-changes`; shared with the monorepo mode.
+ *
+ * @param {string[]} blockingChanges - `git status --porcelain` lines that block.
+ * @param {ProjectCommands} commands - Project commands quoted by the hints.
+ * @returns {ReleaseBlocker} Blocker.
+ */
+export declare function uncommittedFilesBlocker(blockingChanges: string[], commands: ProjectCommands): ReleaseBlocker;
+/**
+ * Stops a new release whose manual changelog was not updated since the last release; shared with the monorepo mode.
+ *
+ * @param {string | null} reason - Why the changelog check failed, when it says so.
+ * @param {string} changelogPath - Changelog path relative to the root.
+ * @param {ProjectCommands} commands - Project commands quoted by the hints.
+ * @returns {ReleaseBlocker} Blocker with {@link CHANGELOG_UPDATE_REQUIRED_CODE}.
+ */
+export declare function changelogUpdateRequiredBlocker(reason: string | null, changelogPath: string, commands: ProjectCommands): ReleaseBlocker;
+/**
+ * Stops a new release whose changelog has no `## [Unreleased]` block or no entry in it: the release
+ * commit closes that block as the new version. Shared with the monorepo mode.
+ *
+ * @param {{ exists: boolean, entryCount: number }} changelog - `[Unreleased]` block of the changelog.
+ * @param {string} changelogPath - Changelog path relative to the root.
+ * @param {ProjectCommands} commands - Project commands quoted by the hints.
+ * @returns {ReleaseBlocker | null} Blocker with {@link CHANGELOG_UPDATE_REQUIRED_CODE}, or `null` when `[Unreleased]` has entries.
+ */
+export declare function unreleasedEntriesRequiredBlocker(changelog: {
+    exists: boolean;
+    entryCount: number;
+}, changelogPath: string, commands: ProjectCommands): ReleaseBlocker | null;
+/**
+ * Builds the step that fast-forwards `main` before a new release; shared with the monorepo mode.
+ *
+ * @param {number} behindCount - Commits `origin/main` has and `main` lacks.
+ * @param {ProjectCommands} commands - Project commands quoted by the detail.
+ * @returns {ReleasePlanStep} Sync step.
+ */
+export declare function syncMainPlanStep(behindCount: number, commands: ProjectCommands): ReleasePlanStep;
+/**
+ * Adds the migrations step when migrations are pending, or a warning when they could not be checked;
+ * shared with the monorepo mode.
+ *
+ * @param {MigrationCheck | null | undefined} migrations - Migration state of the diagnosis.
+ * @param {ReleasePlanStep[]} steps - Steps of the plan, extended in place.
+ * @param {string[]} warnings - Warnings of the plan, extended in place.
+ * @returns {void}
+ */
+export declare function addMigrationsPlanStep(migrations: MigrationCheck | null | undefined, steps: ReleasePlanStep[], warnings: string[]): void;
+/**
+ * Classifies the npm credential check of a package the plan would publish; shared with the monorepo mode.
+ *
+ * @param {NpmAuthCheck} npmAuth - Credential check.
+ * @param {ProjectCommands} commands - Project commands quoted by the fix.
+ * @param {string} [subject] - Text after the registry name in the unverified warning (such as ` de <paquete>`).
+ * @returns {{ problem: ReleaseBlocker | null, warning: string | null }} Blocker when the credentials cannot publish,
+ *   otherwise a warning when they could not be verified or the first publication cannot be confirmed.
+ */
+export declare function classifyNpmAuth(npmAuth: NpmAuthCheck, commands: ProjectCommands, subject?: string): {
+    problem: ReleaseBlocker | null;
+    warning: string | null;
+};
+/**
+ * Lists the uncommitted changes a run with `--ignore-local-changes` sets aside: every change,
+ * except `CHANGELOG.md` in a new release, whose bump commits it.
+ *
+ * @param {ReleaseState} state - Snapshot.
+ * @param {string} mode - Planned {@link RELEASE_MODE}.
+ * @returns {string[]} `git status --porcelain` lines to set aside.
+ */
+export declare function listLocalChangesToSetAside(state: ReleaseState, mode: string): string[];
+/**
+ * Lists the paths of a `git status --porcelain` line: the path, or both the original and the new
+ * path of a rename or copy (`R  old.js -> new.js`), without the quotes Git adds to unusual names.
+ *
+ * @param {string} line - Porcelain line.
+ * @returns {string[]} Paths the line reports.
+ */
+export declare function listPorcelainPaths(line: string): string[];
+/**
+ * Tells whether a `git status --porcelain` line touches code or data the loaded configuration may
+ * import (see {@link UNSETTABLE_ASIDE_EXTENSIONS}), or a `.npmrc` the diagnosis already read to
+ * resolve the registry and credentials.
+ *
+ * @param {string} line - Porcelain line.
+ * @returns {boolean} `true` when any of its paths has one of those extensions or is a `.npmrc`.
+ */
+export declare function isCodeChange(line: string): boolean;
+/**
+ * Explains why `--ignore-local-changes` cannot set aside code or data changes (see
+ * {@link UNSETTABLE_ASIDE_EXTENSIONS}); shared with the monorepo mode.
+ *
+ * @param {string[]} codeChanges - `git status --porcelain` lines of the code or data changes.
+ * @param {ProjectCommands} commands - Project commands quoted by the hints.
+ * @returns {ReleaseBlocker} Blocker listing them.
+ */
+export declare function codeChangesToSetAsideBlocker(codeChanges: string[], commands: ProjectCommands): ReleaseBlocker;
+/**
+ * Builds the blocker for local `main` commits that are not release commits.
+ *
+ * @param {ReleaseCommit[]} commits - Foreign commits.
+ * @returns {ReleaseBlocker} Blocker.
+ */
+export declare function foreignCommitsBlocker(commits: ReleaseCommit[]): ReleaseBlocker;
+/**
+ * Stops a new release that nothing would validate before the version is touched.
+ *
+ * @param {ProjectCommands} commands - Project commands quoted by the hints.
+ * @returns {ReleaseBlocker} Blocker.
+ */
+export declare function missingChecksBlocker(commands: ProjectCommands): ReleaseBlocker;
+/**
+ * Decides what is still missing to publish a release from `main` (or, from a detached `HEAD` on
+ * a release tag, to publish that release).
+ *
+ * @param {ReleaseState} state - Snapshot gathered by `state.js`.
+ * @param {ReleaseCapabilities} [capabilities] - Steps the project configured.
+ * @param {PlanOptions} [planOptions] - Options chosen on the command line.
+ * @returns {ReleasePlan} Ordered plan.
+ */
+export declare function buildReleasePlan(state: ReleaseState, capabilities?: ReleaseCapabilities, planOptions?: PlanOptions): ReleasePlan;

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

@@ -0,0 +1,151 @@
+/**
+ * Process and Git helpers of `astra-rp create-version`: captured and inherited
+ * commands that never reject, a Git reader bound to a repository, commit
+ * listing and manifest reads at any revision.
+ *
+ * @module create-version/process
+ */
+export type CapturedResult = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export type CommandOptions = {
+    cwd?: string;
+    shell?: boolean;
+    env?: NodeJS.ProcessEnv;
+};
+export type GitReader = {
+    git: (gitArguments: string[]) => Promise<string>;
+    tryGit: (gitArguments: string[]) => Promise<string | null>;
+};
+export type CommitRecord = {
+    sha: string;
+    subject: string;
+    body: string;
+};
+/**
+ * @typedef {{ status: number, stdout: string, stderr: string }} CapturedResult
+ * @typedef {{ cwd?: string, shell?: boolean, env?: NodeJS.ProcessEnv }} CommandOptions
+ * @typedef {{ git: (gitArguments: string[]) => Promise<string>, tryGit: (gitArguments: string[]) => Promise<string | null> }} GitReader
+ * @typedef {{ sha: string, subject: string, body: string }} CommitRecord
+ */
+/** Windows resolves `pnpm.cmd` and `npm.cmd` only through a shell. */
+export declare const USES_SHELL_FOR_PACKAGE_MANAGERS: boolean;
+/**
+ * Double-quotes every argument for a Windows shell command line; callers validate them first against
+ * characters that could break out of the quotes.
+ *
+ * @param {readonly string[]} commandArguments - Validated arguments.
+ * @returns {string} Arguments quoted and joined with spaces.
+ */
+export declare function quoteShellArguments(commandArguments: readonly string[]): string;
+/**
+ * Runs a command and captures its output. Leading whitespace is kept because
+ * `git status --porcelain` encodes the file state in the first columns.
+ *
+ * @param {string} command - Executable name, or a full command line when `shell` is set.
+ * @param {string[]} commandArguments - Arguments.
+ * @param {CommandOptions} [options] - Spawn options.
+ * @returns {Promise<CapturedResult>} Result; never rejects.
+ */
+export declare function runCaptured(command: string, commandArguments: string[], options?: CommandOptions): Promise<CapturedResult>;
+export type InputCommandOptions = CommandOptions & {
+    input: string;
+    timeoutMs: number;
+};
+export type InputCommandResult = CapturedResult & {
+    timedOut: boolean;
+    spawnErrorCode: string | null;
+};
+/**
+ * Runs a command that reads `input` from stdin and captures its output, stopping it after
+ * `timeoutMs`. Used for agent CLIs that receive their prompt through stdin. Outside Windows the
+ * command runs in its own process group so a timeout also stops the processes it started; the
+ * promise still waits for its pipes to close when it ends normally, so no `unref` is needed.
+ *
+ * @param {string} command - Executable name, or a full command line when `shell` is set.
+ * @param {string[]} commandArguments - Arguments.
+ * @param {InputCommandOptions} options - Spawn options, stdin contents and time limit.
+ * @returns {Promise<InputCommandResult>} Result, whether it was stopped for taking too long and the
+ *   spawn error code (such as `ENOENT`); never rejects.
+ */
+export declare function runCapturedWithInput(command: string, commandArguments: string[], options: InputCommandOptions): Promise<InputCommandResult>;
+/**
+ * Runs a command with inherited stdio so its progress stays visible.
+ *
+ * @param {string} command - Executable name, or a full command line when `shell` is set.
+ * @param {string[]} commandArguments - Arguments.
+ * @param {CommandOptions} [options] - Spawn options.
+ * @returns {Promise<number>} Exit code; never rejects.
+ */
+export declare function runInherited(command: string, commandArguments: string[], options?: CommandOptions): Promise<number>;
+/**
+ * Streams a client that may print its own command on failure, redacting credentials across chunks.
+ *
+ * @param {string} command - Executable or trusted shell command.
+ * @param {string[]} commandArguments - Client arguments.
+ * @param {CommandOptions} options - Child environment and checkout.
+ * @param {string[]} secrets - Values to redact; never included in diagnostics.
+ * @returns {Promise<number>} Exit code with interactive stdin and safe terminal output.
+ */
+export declare function runRedactedInherited(command: string, commandArguments: string[], options: CommandOptions, secrets: string[]): Promise<number>;
+/**
+ * Runs a trusted, configured command line (for example `pnpm check`) through the shell.
+ *
+ * @param {string} commandLine - Command line written in the project configuration, never user input.
+ * @param {string} cwd - Working directory.
+ * @returns {Promise<number>} Exit code; never rejects.
+ */
+export declare function runCommandLine(commandLine: string, cwd: string): Promise<number>;
+/**
+ * Creates a Git reader bound to a repository.
+ *
+ * @param {string} repositoryRoot - Repository root.
+ * @returns {GitReader} Readers.
+ */
+export declare function createGitReader(repositoryRoot: string): GitReader;
+/**
+ * Parses `git log` records produced with {@link FIELD_SEPARATOR} and {@link RECORD_SEPARATOR}.
+ *
+ * @param {string} output - Raw `git log` output.
+ * @returns {CommitRecord[]} Commits, newest first.
+ */
+export declare function parseCommitLog(output: string): CommitRecord[];
+/**
+ * Lists the commits of a revision range, optionally only those touching some paths.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} range - Revision range such as `abc..origin/main`.
+ * @param {readonly string[]} [paths] - Paths relative to the root; every commit when empty.
+ * @returns {Promise<CommitRecord[]>} Commits, newest first.
+ */
+export declare function listCommits(reader: GitReader, range: string, paths?: readonly string[]): Promise<CommitRecord[]>;
+/**
+ * Reads a `package.json` at a revision.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `HEAD`, `v1.2.0` or `origin/main`.
+ * @param {string} [manifestPath] - Manifest path relative to the root, with `/` separators (a
+ *   workspace package's `packages/x/package.json`); the root `package.json` by default.
+ * @returns {Promise<Record<string, unknown> | null>} Parsed manifest, or `null` when missing, unreadable or not a JSON object.
+ */
+export declare function readPackageManifestAt(reader: GitReader, revision: string, manifestPath?: string): Promise<Record<string, unknown> | null>;
+/**
+ * Reads the `version` field of a `package.json` at a revision.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `HEAD` or `origin/main`.
+ * @param {string} [manifestPath] - Manifest path relative to the root; the root `package.json` by default.
+ * @returns {Promise<string | null>} Version, or `null` when unreadable.
+ */
+export declare function readPackageVersionAt(reader: GitReader, revision: string, manifestPath?: string): Promise<string | null>;
+/**
+ * Finds the newest top-level version change, including compact JSON and excluding edits to nested versions.
+ *
+ * @param {GitReader} reader - Read-only Git boundary.
+ * @param {string} revision - History to inspect.
+ * @param {string} [manifestPath] - Package manifest path.
+ * @returns {Promise<string | null>} Commit that actually changed the top-level version.
+ */
+export declare function findVersionChangeCommit(reader: GitReader, revision: string, manifestPath?: string): Promise<string | null>;

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

@@ -0,0 +1,56 @@
+/**
+ * Validates provider-specific publication options while keeping legacy npm configuration intact.
+ *
+ * @module create-version/registry-config
+ */
+export type RegistryProvider = "npm" | "github" | "gitlab" | "jsr";
+export type RegistryAuthentication = "token" | "oidc" | "browser";
+export type PublicationOptions = {
+    registryUrl?: string;
+    packageName?: string;
+    authentication?: RegistryAuthentication;
+    tokenEnv?: string;
+    access?: "public" | "restricted";
+    tag?: string;
+    configFile?: string;
+    jsrClient?: "npx" | "deno";
+};
+export type ResolvedPublicationOptions = {
+    registryUrl: string | null;
+    packageName: string | null;
+    authentication: RegistryAuthentication;
+    tokenEnv: string;
+    access: "public" | "restricted" | null;
+    tag: string | null;
+    configFile: string | null;
+    jsrClient: "npx" | "deno";
+};
+/**
+ * @typedef {"npm" | "github" | "gitlab" | "jsr"} RegistryProvider
+ * @typedef {"token" | "oidc" | "browser"} RegistryAuthentication
+ * @typedef {{ registryUrl?: string, packageName?: string, authentication?: RegistryAuthentication, tokenEnv?: string, access?: "public" | "restricted", tag?: string, configFile?: string, jsrClient?: "npx" | "deno" }} PublicationOptions
+ * @typedef {{ registryUrl: string | null, packageName: string | null, authentication: RegistryAuthentication, tokenEnv: string, access: "public" | "restricted" | null, tag: string | null, configFile: string | null, jsrClient: "npx" | "deno" }} ResolvedPublicationOptions
+ */
+/**
+ * Identifies one of the four built-in publishers.
+ *
+ * @param {unknown} value - Configured publisher or registry.
+ * @returns {value is RegistryProvider} Whether it is a provider name.
+ */
+export declare function isRegistryProvider(value: unknown): value is RegistryProvider;
+/**
+ * Tells whether a URL is a plain http(s) URL: without credentials, query nor fragment.
+ *
+ * @param {URL} url - Parsed URL.
+ * @returns {boolean} Whether a registry can be addressed by it.
+ */
+export declare function isPlainHttpUrl(url: URL): boolean;
+/**
+ * Resolves publication options for a single selected provider; arrays are deliberately unsupported.
+ *
+ * @param {unknown} value - Raw `publication` configuration.
+ * @param {RegistryProvider} [provider] - Selected publisher or monitored registry.
+ * @returns {ResolvedPublicationOptions} Validated options and provider defaults.
+ * @throws {Error} When a field is invalid or unsupported by the selected provider.
+ */
+export declare function resolvePublicationOptions(value: unknown, provider?: RegistryProvider): ResolvedPublicationOptions;

package/types/create-version/registry-http.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reads provider metadata without following registry forwarding redirects or exposing upstream bodies.
+ *
+ * @module create-version/registry-http
+ */
+/**
+ * Fetches versions directly from GitLab or JSR; a forwarding redirect means absent in this registry.
+ *
+ * @param {{ provider: import("./registry-config.js").RegistryProvider, registryUrl: string, packageName: string, label: string, tag: string | null, options?: { tokenEnv: string } }} registry - Selected registry.
+ * @param {string | null} token - Read credential, never included in returned state.
+ * @returns {Promise<import("./npm.js").NpmLookup>} Shared published-version contract.
+ */
+export declare function lookupHttpRegistry(registry: {
+    provider: import("./registry-config.js").RegistryProvider;
+    registryUrl: string;
+    packageName: string;
+    label: string;
+    tag: string | null;
+    options?: {
+        tokenEnv: string;
+    };
+}, token: string | null): Promise<import("./npm.js").NpmLookup>;