@astra-kit/rp 0.0.0-stage → 0.10.0

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

@@ -0,0 +1,21 @@
+/**
+ * JSON helpers shared by the release modes: plain-object checks and manifest reads.
+ *
+ * @module create-version/json
+ */
+/**
+ * Tells whether a value is a plain JSON object.
+ *
+ * @param {unknown} value - Any value.
+ * @returns {value is Record<string, unknown>} Whether it is a non-array object.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Reads and parses a JSON manifest from the working tree; read and parse errors propagate as they are.
+ *
+ * @param {string} directory - Directory the manifest path is relative to.
+ * @param {string} [manifestPath] - Manifest path; the `package.json` of the directory by default.
+ * @returns {any} Parsed manifest.
+ * @throws {Error} When the file cannot be read or is not valid JSON.
+ */
+export declare function readJsonManifest(directory: string, manifestPath?: string): any;

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

@@ -0,0 +1,21 @@
+/**
+ * Parses native registry JSONC manifests while preserving character offsets for version-only edits.
+ *
+ * @module create-version/jsonc
+ */
+/**
+ * Replaces comments and trailing commas with whitespace, without touching string values or offsets.
+ *
+ * @param {string} content - JSON or JSONC text.
+ * @returns {string} JSON text with the same length and line breaks.
+ * @throws {Error} When a block comment is unterminated.
+ */
+export declare function normalizeJsonc(content: string): string;
+/**
+ * Reads a native JSONC manifest as JSON, preserving comments in the caller's source text.
+ *
+ * @param {string} content - JSONC manifest text.
+ * @returns {Record<string, unknown>} Parsed manifest.
+ * @throws {Error} When the manifest is not an object or is malformed.
+ */
+export declare function parseJsoncManifest(content: string): Record<string, unknown>;

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

@@ -0,0 +1,52 @@
+/**
+ * Reads and versions native JSR manifests, then publishes with the official JSR or Deno client.
+ *
+ * @module create-version/jsr
+ */
+/**
+ * Finds the native JSR manifest inside a package and reads only its publication metadata.
+ *
+ * @param {string} packageRoot - Package directory.
+ * @param {string | null} configFile - Explicit package-relative path, or auto-detection.
+ * @returns {{ filePath: string, originalBytes: Buffer, text: string, manifest: Record<string, unknown>, packageName: string }} Native manifest.
+ * @throws {Error} When the file is absent, linked outside the package, malformed or unscoped.
+ */
+export declare function readJsrManifest(packageRoot: string, configFile?: string | null): {
+    filePath: string;
+    originalBytes: Buffer;
+    text: string;
+    manifest: Record<string, unknown>;
+    packageName: string;
+};
+/**
+ * Prepares a native manifest version edit for the same transaction as package.json; never writes it.
+ *
+ * @param {{ repositoryRoot: string, reader: import("./process.js").GitReader, commands: import("../package-manager.js").ProjectCommands, config?: { versionFiles: string[] } }} context - Release context.
+ * @param {string} packageRoot - Package checkout directory.
+ * @param {import("./registry-config.js").ResolvedPublicationOptions} options - Native publication options.
+ * @param {string} version - New stable version.
+ * @returns {Promise<import("./run.js").ReleaseFileUpdate[]>} Transactional native manifest update.
+ * @throws {ReleaseStepError} When the manifest is dirty, untracked or lacks a usable top-level version.
+ */
+export declare function prepareJsrVersionUpdates(context: {
+    repositoryRoot: string;
+    reader: import("./process.js").GitReader;
+    commands: import("../package-manager.js").ProjectCommands;
+    config?: {
+        versionFiles: string[];
+    };
+}, packageRoot: string, options: import("./registry-config.js").ResolvedPublicationOptions, version: string): Promise<import("./run.js").ReleaseFileUpdate[]>;
+/**
+ * Publishes with a pinned official client and a selected config; the token is never printed by astra-rp.
+ *
+ * @param {string} packageRoot - Release checkout.
+ * @param {{ registryUrl: string, options: import("./registry-config.js").ResolvedPublicationOptions }} registry - Selected native registry.
+ * @param {string | null} token - Personal token, or `null` for browser/OIDC authentication.
+ * @param {ReturnType<typeof readJsrManifest>} [native] - Native manifest of the package, when the caller already read it.
+ * @returns {Promise<number>} Official client exit code.
+ * @throws {Error} When a shell operand or token cannot be passed safely.
+ */
+export declare function publishToJsr(packageRoot: string, registry: {
+    registryUrl: string;
+    options: import("./registry-config.js").ResolvedPublicationOptions;
+}, token: string | null, native?: ReturnType<typeof readJsrManifest>): Promise<number>;

package/types/create-version/local-changes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Local changes of `astra-rp create-version --ignore-local-changes`: the
+ * uncommitted changes (staged, unstaged and untracked) are set aside in a
+ * `git stash` entry while the release runs, so checks, preparation and
+ * publication only see the release commit, and are restored at the end.
+ *
+ * The restore is exact or nothing: staged changes go back to the index only,
+ * unstaged changes to the working tree only and untracked files stay
+ * untracked. Every layer is checked before anything is written; when one does
+ * not apply cleanly on top of the release, nothing is touched and the stash
+ * entry is kept.
+ *
+ * @module create-version/local-changes
+ */
+export type GitReader = import("./process.js").GitReader;
+export type SetAsideChanges = {
+    sha: string;
+    keptPaths: string[];
+};
+export type LocalChangesRestore = {
+    restored: true;
+} | {
+    restored: false;
+    reason: string;
+};
+/**
+ * Sets the uncommitted changes aside in a new stash entry.
+ *
+ * @param {GitReader} reader - Git reader of the repository root.
+ * @param {{ keepChangelog?: boolean, keptPaths?: readonly string[], createVersionCommand?: string }} options - Files
+ *   that stay in the working tree because a new release commits them (`keepChangelog` keeps the root
+ *   `CHANGELOG.md`; a monorepo passes every released package's `keptPaths`), and how the project
+ *   runs create-version (for the hints).
+ * @returns {Promise<SetAsideChanges>} Stash entry holding the changes.
+ * @throws {ReleaseStepError} When Git cannot create the stash entry; nothing was changed then.
+ */
+export declare function setAsideLocalChanges(reader: GitReader, { keepChangelog, keptPaths: configuredKeptPaths, createVersionCommand }: {
+    keepChangelog?: boolean;
+    keptPaths?: readonly string[];
+    createVersionCommand?: string;
+}): Promise<SetAsideChanges>;
+/**
+ * Restores the changes set aside by {@link setAsideLocalChanges} exactly as they were: staged
+ * changes staged, unstaged changes unstaged and untracked files untracked. Nothing is written
+ * unless every layer applies cleanly; the stash entry is dropped only after a full restore.
+ *
+ * @param {GitReader} reader - Git reader of the repository root.
+ * @param {string} repositoryRoot - Repository root.
+ * @param {SetAsideChanges} setAside - Stash entry returned by {@link setAsideLocalChanges}.
+ * @returns {Promise<LocalChangesRestore>} Whether the changes are back, and why not otherwise.
+ */
+export declare function restoreLocalChanges(reader: GitReader, repositoryRoot: string, setAside: SetAsideChanges): Promise<LocalChangesRestore>;

package/types/create-version/npm-auth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure explanations of the npm credential check of `astra-rp create-version`:
+ * the blocker the planner shows before anything is touched, and the error of a
+ * failed `npm publish`, whose output cannot be parsed because npm inherits the
+ * terminal (2FA). They name where `NPM_TOKEN` came from, never the token.
+ *
+ * @module create-version/npm-auth
+ */
+export type NpmAuthCheck = import("./npm.js").NpmAuthCheck;
+export type ProjectCommands = import("../package-manager.js").ProjectCommands;
+export type NpmAuthProblem = {
+    title: string;
+    details: string[];
+};
+/**
+ * @typedef {import("./npm.js").NpmAuthCheck} NpmAuthCheck
+ * @typedef {import("../package-manager.js").ProjectCommands} ProjectCommands
+ * @typedef {{ title: string, details: string[] }} NpmAuthProblem
+ */
+/**
+ * Names the source of the token for messages.
+ *
+ * @param {NpmAuthCheck} npmAuth - Check result.
+ * @returns {string} Source label, or a generic name when it is unknown.
+ */
+export declare function describeNpmTokenSource(npmAuth: NpmAuthCheck): string;
+/**
+ * Explains an npm credential check that must stop the release before anything is touched.
+ *
+ * @param {NpmAuthCheck} npmAuth - Result of `checkNpmPublishAccess`.
+ * @param {ProjectCommands} [commands] - Project commands quoted by the fix (pnpm when omitted).
+ * @returns {NpmAuthProblem | null} Blocker, or `null` when the check passed or could not decide (`unknown`).
+ */
+export declare function describeNpmAuthProblem(npmAuth: NpmAuthCheck, commands?: ProjectCommands): NpmAuthProblem | null;
+/**
+ * Warns about a first publication that cannot be told apart from a hidden package: `npm view` and
+ * `npm owner ls` answered E404, which is what a registry answers both for a new package and for a
+ * private package the token has no access to.
+ *
+ * @param {NpmAuthCheck} npmAuth - Result of `checkNpmPublishAccess`, confirmed against `npm view`.
+ * @returns {string | null} Warning, or `null` when the check is not a first publication.
+ */
+export declare function describeNpmFirstPublicationWarning(npmAuth: NpmAuthCheck): string | null;
+/**
+ * Explains a failed `npm publish` from the credential check re-run after it: an invalid token, a
+ * user without permission on the package or, when the user can publish, the generic failure, which
+ * still names a read-only or granular token without write permission as a possible cause.
+ *
+ * @param {NpmAuthCheck} npmAuth - Result of `checkNpmPublishAccess` after the failure.
+ * @param {{ exitCode: number, version: string }} publication - npm exit code and version being published.
+ * @param {ProjectCommands} [commands] - Project commands quoted by the hint (pnpm when omitted).
+ * @returns {{ message: string, hint: string }} Spanish message and next action for `ReleaseStepError`.
+ */
+export declare function describeNpmPublishFailure(npmAuth: NpmAuthCheck, { exitCode, version }: {
+    exitCode: number;
+    version: string;
+}, commands?: ProjectCommands): {
+    message: string;
+    hint: string;
+};

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

@@ -0,0 +1,331 @@
+/**
+ * npm adapter of `astra-rp create-version`: resolves the registry a package is
+ * published to (`publishConfig`, else npm's own config), resolves `NPM_TOKEN`
+ * with a single ordered lookup (environment, repository `.env`, shared
+ * `~/.config/astra-rp/.env`), checks that the token can publish the package
+ * (`npm whoami` + `npm owner ls`), lists the versions published there
+ * (authenticated with `NPM_TOKEN` when available), reads the integrity npm
+ * would pack from the release checkout, and publishes the working tree or a
+ * prepared archive with `NPM_TOKEN` bound to the publish registry.
+ *
+ * @module create-version/npm
+ */
+import { runCaptured } from "./process.js";
+export type NpmLookup = {
+    status: string;
+    publishedVersions: string[];
+    latestVersion?: string | null;
+    reason: string | null;
+    registryLabel?: string;
+    tag?: string | null;
+};
+export type NpmPackDescription = {
+    name: unknown;
+    version: unknown;
+    integrity: string;
+};
+export type NpmPackResult = {
+    pack: NpmPackDescription | null;
+    problem: string | null;
+};
+export type NpmTokenResolution = {
+    token: string | null;
+    source: string | null;
+};
+export type NpmTokenLookup = {
+    environment?: NodeJS.ProcessEnv;
+    homeDirectory?: string;
+    tokenVariable?: string;
+    pinScope?: boolean;
+};
+export type NpmAuthCheck = {
+    status: string;
+    user: string | null;
+    source: string | null;
+    registryUrl: string;
+    packageName: string;
+    owners: string[];
+    firstPublication: boolean;
+    reason: string | null;
+    tokenVariable?: string;
+    registryLabel?: string;
+};
+/**
+ * @typedef {{ status: string, publishedVersions: string[], latestVersion?: string | null, reason: string | null, registryLabel?: string, tag?: string | null }} NpmLookup
+ *   `latestVersion` is the version the `latest` dist-tag points at, which may be a prerelease.
+ * @typedef {{ name: unknown, version: unknown, integrity: string }} NpmPackDescription
+ *   What `npm pack --dry-run --json` reports for the release checkout: package name, version and `sha512-<base64>` integrity.
+ * @typedef {{ pack: NpmPackDescription | null, problem: string | null }} NpmPackResult
+ * @typedef {{ token: string | null, source: string | null }} NpmTokenResolution
+ *   `NPM_TOKEN` and the `NPM_TOKEN_SOURCE` it came from; both `null` when no source defines it.
+ * @typedef {{ environment?: NodeJS.ProcessEnv, homeDirectory?: string, tokenVariable?: string, pinScope?: boolean }} NpmTokenLookup
+ *   Environment and home directory {@link resolveNpmToken} reads; the current process and `os.homedir()` by default.
+ * @typedef {{
+ *   status: string,
+ *   user: string | null,
+ *   source: string | null,
+ *   registryUrl: string,
+ *   packageName: string,
+ *   owners: string[],
+ *   firstPublication: boolean,
+ *   reason: string | null,
+ *   tokenVariable?: string,
+ *   registryLabel?: string,
+ * }} NpmAuthCheck
+ *   Result of {@link checkNpmPublishAccess}: one of `NPM_AUTH_STATUS`, the user the token
+ *   authenticates as, where the token came from (never the token itself), the owners npm reports
+ *   and why the check did not pass.
+ */
+/**
+ * Runs npm with captured output. On Windows npm only resolves through the shell, so every argument
+ * is double-quoted there; callers pass validated names, registries and temporary paths only.
+ *
+ * @param {string[]} npmArguments - Arguments that follow `npm`.
+ * @param {string} repositoryRoot - Working directory, whose `.npmrc` npm reads.
+ * @param {NodeJS.ProcessEnv} [environment] - Environment of npm; the current process by default.
+ * @returns {ReturnType<typeof runCaptured>} Exit status and output.
+ * @throws {Error} When an argument could break out of its quotes on the Windows shell.
+ */
+export declare function runNpmCaptured(npmArguments: string[], repositoryRoot: string, environment?: NodeJS.ProcessEnv): ReturnType<typeof runCaptured>;
+/**
+ * Builds the `npm view` arguments that list the published versions and dist-tags of a package on a registry.
+ * `npm view` ignores the manifest `publishConfig`, so the registry is always passed explicitly.
+ *
+ * @param {string} packageName - npm package name, already checked with `NPM_PACKAGE_NAME_PATTERN`.
+ * @param {string} registryUrl - Registry resolved by {@link resolvePublishRegistry}.
+ * @param {string | null} [userConfigPath] - Temporary npm config from {@link withNpmAuthConfig} that
+ *   authenticates the query; `null` queries with npm's usual config.
+ * @param {boolean} [pinScope] - Whether to override inherited scope routing with this operation's registry.
+ * @returns {string[]} Arguments that follow `npm`.
+ * @throws {Error} When the registry is not a valid http(s) URL or has characters unsafe on the Windows shell.
+ */
+export declare function buildNpmViewArguments(packageName: string, registryUrl: string, userConfigPath?: string | null, pinScope?: boolean): string[];
+/**
+ * Builds the `npm whoami` arguments that ask a registry which user the temporary config authenticates as.
+ *
+ * @param {string} registryUrl - Registry the package is published to.
+ * @param {string} userConfigPath - Temporary npm config from {@link withNpmAuthConfig}.
+ * @param {string | null} [packageName] - Package whose scope must use this registry.
+ * @returns {string[]} Arguments that follow `npm`.
+ * @throws {Error} When the registry is invalid or unsafe on the Windows shell.
+ */
+export declare function buildNpmWhoamiArguments(registryUrl: string, userConfigPath: string, packageName?: string | null): string[];
+/**
+ * Builds the `npm owner ls` arguments that list the owners of a package on a registry.
+ *
+ * @param {string} packageName - npm package name, already checked with `NPM_PACKAGE_NAME_PATTERN`.
+ * @param {string} registryUrl - Registry the package is published to.
+ * @param {string} userConfigPath - Temporary npm config from {@link withNpmAuthConfig}.
+ * @returns {string[]} Arguments that follow `npm`.
+ * @throws {Error} When the registry is invalid or unsafe on the Windows shell.
+ */
+export declare function buildNpmOwnerListArguments(packageName: string, registryUrl: string, userConfigPath: string, pinScope?: boolean): string[];
+/**
+ * Resolves `NPM_TOKEN` with the single lookup shared by the diagnosis, `npm view` and the
+ * publication: the `NPM_TOKEN` environment variable, else the repository `.env` (ignored by Git),
+ * else the file shared by every project, `~/.config/astra-rp/.env`. The token is only returned:
+ * it is never written to disk nor loaded into `process.env`.
+ *
+ * @param {string} repositoryRoot - Repository root holding the optional `.env`.
+ * @param {NpmTokenLookup} [lookup] - Environment and home directory to read.
+ * @returns {NpmTokenResolution} Token and its source.
+ * @throws {Error} When a `.env` that has to be read exists but cannot be read.
+ */
+export declare function resolveNpmToken(repositoryRoot: string, { environment, homeDirectory, tokenVariable }?: NpmTokenLookup): NpmTokenResolution;
+/**
+ * Builds the environment of an npm command that authenticates with the temporary config: the
+ * publish environment ({@link buildNpmPublishEnvironment}) without inherited npm credential
+ * variables, plus `NPM_TOKEN`, which npm expands from `${NPM_TOKEN}` in that config. Only the child
+ * process receives the token, and it is the only credential npm can use.
+ *
+ * @param {string} token - Token from {@link resolveNpmToken}.
+ * @param {NodeJS.ProcessEnv} [environment] - Environment to copy; the current process by default.
+ * @returns {NodeJS.ProcessEnv} Environment for npm.
+ */
+export declare function buildNpmTokenEnvironment(token: string, environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Parses the output of `npm owner ls`: one `<user> <<email>>` line per owner.
+ *
+ * @param {string} output - Standard output of npm.
+ * @returns {string[]} npm user names.
+ */
+export declare function parseNpmOwnerList(output: string): string[];
+/**
+ * Builds the result of a lookup that could not list the published versions.
+ *
+ * @param {string | null} reason - Why the lookup failed.
+ * @returns {NpmLookup} Failed lookup without versions.
+ */
+export declare function failedLookup(reason: string | null): NpmLookup;
+/**
+ * Checks, before anything is touched, the credential `npm publish` will use: resolves the token
+ * ({@link resolveNpmToken}), asks the registry who it authenticates as (`npm whoami`) and whether
+ * that user owns the package (`npm owner ls`). A package the registry does not show (E404) passes as
+ * `firstPublication`; registries also hide private packages from users without access, so the
+ * snapshot confirms it against the versions `npm view` lists (see `state.js`). Both commands use the same temporary config and registry as
+ * `npm publish`. A passing check proves that the token authenticates as an owner, not that it can
+ * write: a read-only or granular token without write permission passes too, and npm offers no
+ * side-effect-free way to tell before publishing.
+ *
+ * @param {string} packageName - npm package name.
+ * @param {string} repositoryRoot - Repository root, where npm reads its project config.
+ * @param {string} registryUrl - Registry from {@link resolvePublishRegistry}.
+ * A project `.npmrc` with credentials for the registry blocks as `projectCredentials` without
+ * querying it, because npm would authenticate with them instead of `NPM_TOKEN`; an unreadable
+ * `.env` or `.npmrc` leaves the check `unknown` with the file it could not read.
+ *
+ * @param {NpmTokenLookup} [lookup] - Token lookup of {@link resolveNpmToken}.
+ * @returns {Promise<NpmAuthCheck>} Check result; never rejects.
+ */
+export declare function checkNpmPublishAccess(packageName: string, repositoryRoot: string, registryUrl: string, lookup?: NpmTokenLookup): Promise<NpmAuthCheck>;
+/**
+ * Lists the versions of a package published on a registry. With `NPM_TOKEN` ({@link resolveNpmToken})
+ * the query authenticates through the same temporary config the publication uses, so a private
+ * package can be diagnosed; without it the registry is queried with npm's usual config.
+ *
+ * @param {string} packageName - npm package name.
+ * @param {string} repositoryRoot - Directory whose `.npmrc` npm reads.
+ * @param {string} [registryUrl] - Registry the package is published to, from {@link resolvePublishRegistry};
+ *   defaults to npm's default registry.
+ * @returns {Promise<NpmLookup>} Published versions; a never-published package has none. An unreadable
+ *   `.env` fails the lookup with the file it could not read instead of rejecting.
+ */
+export declare function lookupPublishedVersions(packageName: string, repositoryRoot: string, registryUrl?: string, { tokenVariable, tag, pinScope }?: {
+    pinScope?: boolean | undefined;
+    tag?: string | undefined;
+    tokenVariable?: string | undefined;
+}): Promise<NpmLookup>;
+/**
+ * Parses the output of `npm pack --dry-run --json`: an array with one package and its `integrity`.
+ *
+ * @param {string} output - Standard output of npm.
+ * @returns {NpmPackResult} Package name, version and integrity, or why the output is unusable.
+ */
+export declare function parseNpmPackDryRunOutput(output: string): NpmPackResult;
+/**
+ * Asks npm for the integrity of the archive it would pack from the release checkout, without
+ * writing anything nor running lifecycle scripts. The command line is constant, so it is safe
+ * on the Windows shell.
+ *
+ * @param {string} repositoryRoot - Package root, as `prepare` left it.
+ * @returns {Promise<NpmPackResult>} npm description, or why npm failed or its output is unusable.
+ */
+export declare function readNpmPackIntegrity(repositoryRoot: string): Promise<NpmPackResult>;
+/**
+ * Returns the registry `npm publish` sends the package to: `publishConfig["@scope:registry"]` for a
+ * scoped package that declares it, else `publishConfig.registry`, else the registry npm's own config
+ * resolves (project `.npmrc`, environment, global config; see {@link readNpmConfigRegistry}).
+ *
+ * @param {Record<string, unknown>} manifest - `package.json` being published.
+ * @param {string} repositoryRoot - Package root, where npm reads its project config.
+ * @returns {Promise<string>} Registry URL, already checked to be a plain http(s) URL.
+ * @throws {Error} When the resolved registry is not a plain http(s) URL or npm cannot report its config.
+ */
+export declare function resolvePublishRegistry(manifest: Record<string, unknown>, repositoryRoot: string): Promise<string>;
+/**
+ * Describes where a published release can be seen: its npmjs.com page when the registry is the
+ * public npm registry, else the registry URL with the package and version.
+ *
+ * @param {{ registryUrl: string, packageName: string, version: string }} release - Published release.
+ * @returns {string} Summary text.
+ */
+export declare function describePublishedRelease({ registryUrl, packageName, version }: {
+    registryUrl: string;
+    packageName: string;
+    version: string;
+}): string;
+/**
+ * Builds the npm config line that binds `${NPM_TOKEN}` to a registry, in the form npm matches
+ * credentials with: `//<host>[:port]<path>/:_authToken=${NPM_TOKEN}` (no protocol, trailing `/`).
+ *
+ * @param {string} registryUrl - Registry `npm publish` uses.
+ * @returns {string} Config line ending with a newline; the token itself is never written.
+ * @throws {Error} When the registry is not a plain http(s) URL (credentials, query and fragment are rejected).
+ */
+export declare function buildNpmAuthConfigLine(registryUrl: string): string;
+/**
+ * Finds a credential for the registry in the project `.npmrc` (repository root). npm prefers the
+ * project config over the temporary `--userconfig` that binds `NPM_TOKEN`, so such a credential
+ * would authenticate every command instead of the token. Only keys are read, never values.
+ *
+ * @param {string} repositoryRoot - Repository root holding the optional `.npmrc`.
+ * @param {string} registryUrl - Registry the package is published to.
+ * @returns {string | null} First credential key for the registry, or `null` when there is none.
+ * @throws {Error} When the `.npmrc` exists but cannot be read, or the registry is not a plain http(s) URL.
+ */
+export declare function findProjectNpmCredentialKey(repositoryRoot: string, registryUrl: string): string | null;
+/**
+ * Runs an operation with a temporary npm user config outside the repository
+ * that only references `${NPM_TOKEN}` for the publish registry: npm expands it
+ * from the environment, so the token never reaches the disk or a command line,
+ * and no repository needs an `.npmrc` (which pnpm refuses to expand and warns
+ * about). The config is always removed afterwards.
+ *
+ * @template T
+ * @param {string} authConfigLine - Line built by {@link buildNpmAuthConfigLine}; an empty line
+ *   gives npm a user config without credentials, which only replaces `~/.npmrc`.
+ * @param {(userConfigPath: string) => Promise<T>} operation - Receives the path for `npm --userconfig`.
+ * @param {string} [parentDirectory] - Where the temporary directory is created; defaults to the OS temp directory.
+ * @returns {Promise<T>} The operation result.
+ */
+export declare function withNpmAuthConfig<T>(authConfigLine: string, operation: (userConfigPath: string) => Promise<T>, parentDirectory?: string): Promise<T>;
+/**
+ * Builds the `npm publish` arguments, without the user config. A prepared
+ * archive is prefixed with `./` because npm parses a bare relative operand
+ * such as `releases/1.9.0-abc/pkg-1.9.0.tgz` as a package spec instead of a file.
+ *
+ * @param {string | null} [artifactPath] - Archive relative to the root, already checked with `isSafeArtifactPath`; `null` publishes the working tree.
+ * @param {string | null} [registryUrl] - Registry from {@link resolvePublishRegistry} passed as `--registry`, so npm
+ *   publishes where it was resolved even from a checkout without the project `.npmrc`; `null` leaves it to npm's config.
+ * @param {{ access?: "public" | "restricted" | null, tag?: string | null, provenance?: boolean, packageName?: string | null }} [options] - Publication flags; `null` omits a registry-owned setting.
+ * @returns {string[]} Arguments that follow `npm`.
+ * @throws {Error} When the registry is not a valid http(s) URL or has characters unsafe on the Windows shell.
+ */
+export declare function buildNpmPublishArguments(artifactPath?: string | null, registryUrl?: string | null, { access, tag, provenance, packageName }?: {
+    access?: "public" | "restricted" | null;
+    tag?: string | null;
+    provenance?: boolean;
+    packageName?: string | null;
+}): string[];
+/**
+ * Builds the environment of `npm publish` without the inherited package
+ * manager user agent. npm reads `npm_config_user_agent` as its `user-agent`
+ * config, so under `pnpm create-version` its lifecycle scripts would report
+ * pnpm and `astra-rp guard-publish` would block its own npm publication.
+ * Without it npm reports its own user agent (`npm/…`). npm reads its config
+ * variables in any case (`NPM_CONFIG_USER_AGENT` too), so every casing is dropped.
+ *
+ * @param {NodeJS.ProcessEnv} [environment] - Environment to copy; the current process by default.
+ * @returns {NodeJS.ProcessEnv} Copy without `npm_config_user_agent` in any casing.
+ */
+export declare function buildNpmPublishEnvironment(environment?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Publishes the working tree, or a prepared archive, to npm. `NPM_TOKEN` comes
+ * from {@link resolveNpmToken} and only reaches npm through the child
+ * environment and a temporary user config. npm inherits the terminal, so its
+ * interactive browser or one-time-password (2FA) confirmation works; that is
+ * also why its output cannot be parsed, and a failure is explained afterwards
+ * with {@link checkNpmPublishAccess}.
+ *
+ * @param {string} repositoryRoot - Repository root, where `NPM_TOKEN` is looked up; also the package root unless `packageRoot` is given.
+ * @param {{ authConfigLine: string, artifactPath?: string | null, packageRoot?: string, registryUrl?: string | null, tokenVariable?: string, authentication?: "token" | "oidc", access?: "public" | "restricted" | null, tag?: string | null, packageName?: string | null }} publication - Registry credential
+ *   line from {@link buildNpmAuthConfigLine}, the archive relative to the package root (already checked with
+ *   `isSafeArtifactPath`; without it the working tree is published), the directory of a workspace package and the
+ *   registry to pass explicitly (see {@link buildNpmPublishArguments}).
+ * @returns {Promise<{ exitCode: number, missingToken: boolean }>} npm exit code, or a missing-token result without running npm.
+ * @throws {Error} When the temporary config path could break out of its shell quotes.
+ */
+export declare function publishToNpm(repositoryRoot: string, { authConfigLine, artifactPath, packageRoot, registryUrl, tokenVariable, authentication, access, tag, packageName }: {
+    authConfigLine: string;
+    artifactPath?: string | null;
+    packageRoot?: string;
+    registryUrl?: string | null;
+    tokenVariable?: string;
+    authentication?: "token" | "oidc";
+    access?: "public" | "restricted" | null;
+    tag?: string | null;
+    packageName?: string | null;
+}): Promise<{
+    exitCode: number;
+    missingToken: boolean;
+}>;