beez-rp 0.2.0 → 0.3.0

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

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

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

@@ -44,6 +44,7 @@ export type CreateVersionConfig = {
     migrations?: MigrationsAdapter | null;
     prepare?: string[] | ReleaseHook | null;
     publish?: "npm" | ReleaseHook | null;
+    artifact?: string | null;
     summary?: string[];
 };
 export type ResolvedCreateVersionConfig = {
@@ -59,6 +60,7 @@ export type ResolvedCreateVersionConfig = {
     migrations: MigrationsAdapter | null;
     prepare: string[] | ReleaseHook | null;
     publish: "npm" | ReleaseHook | null;
+    artifact: string | null;
     summary: string[];
 };
 /**
@@ -78,6 +80,8 @@ export declare function defineCreateVersionConfig(config: CreateVersionConfig):
 export declare function resolveCreateVersionConfig(rawConfig: unknown): ResolvedCreateVersionConfig;
 /**
  * Imports `beez-rp.config.mjs` or `beez-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.

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

@@ -8,10 +8,11 @@
  *
  * @module create-version
  */
+export { computeNpmIntegrity, computeSha256, expandArtifactPattern, findPnpmPackRewrites, findPreparedArtifact, isSafeArtifactPath, verifyPreparedArtifact, withArtifactOutsidePackageRoot, } from "./artifact.js";
 export { defineCreateVersionConfig, loadCreateVersionConfig, resolveCreateVersionConfig } from "./config.js";
 export { ReleaseStepError } from "./errors.js";
-export { lookupPublishedVersions, publishToNpm } from "./npm.js";
+export { buildNpmAuthConfigLine, buildNpmPublishArguments, buildNpmPublishEnvironment, buildNpmViewArguments, lookupPublishedVersions, parseNpmPackDryRunOutput, publishToNpm, readNpmPackIntegrity, resolvePublishRegistry, withNpmAuthConfig, } from "./npm.js";
 export { DEFAULT_CAPABILITIES, RELEASE_USAGE, buildReleasePlan, describeFeatureBranchGaps, parseReleaseArguments } from "./plan.js";
-export { createGitReader, listCommits, parseCommitLog, readPackageVersionAt, runCaptured, runCommandLine, runInherited } from "./process.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";

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

@@ -1,6 +1,9 @@
 /**
- * npm adapter of `beez-rp create-version`: lists the published versions of a
- * package and publishes the working tree with the token referenced by `.npmrc`.
+ * npm adapter of `beez-rp create-version`: resolves the registry a package is
+ * published to (`publishConfig`, else npm's own config), 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
  */
@@ -9,25 +12,147 @@ export type NpmLookup = {
     publishedVersions: string[];
     reason: string | null;
 };
+export type NpmPackDescription = {
+    name: unknown;
+    version: unknown;
+    integrity: string;
+};
+export type NpmPackResult = {
+    pack: NpmPackDescription | null;
+    problem: string | null;
+};
+/**
+ * Builds the `npm view` arguments that list the published versions 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.
+ * @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): string[];
 /**
- * @typedef {{ status: string, publishedVersions: string[], reason: string | null }} NpmLookup
+ * Loads `NPM_TOKEN` from the ignored `.env` when the environment does not define it.
+ *
+ * @param {string} repositoryRoot - Repository root holding the optional `.env`.
+ * @returns {boolean} Whether `NPM_TOKEN` is available in the environment.
  */
+export declare function loadNpmToken(repositoryRoot: string): boolean;
 /**
- * Lists the versions of a package published on npm.
+ * Lists the versions of a package published on a registry. With `NPM_TOKEN` (environment or `.env`)
+ * 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.
  */
-export declare function lookupPublishedVersions(packageName: string, repositoryRoot: string): Promise<NpmLookup>;
+export declare function lookupPublishedVersions(packageName: string, repositoryRoot: string, registryUrl?: string): 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;
+/**
+ * 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.
+ * @returns {string[]} Arguments that follow `npm`.
+ */
+export declare function buildNpmPublishArguments(artifactPath?: 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 `beez-rp guard-publish` would block beez-rp's 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 to npm. `NPM_TOKEN` comes from the environment or
- * the ignored `.env`, and only reaches npm through the environment and `.npmrc`.
+ * Publishes the working tree, or a prepared archive, to npm. `NPM_TOKEN` comes
+ * from the environment or the ignored `.env` and only reaches npm through the
+ * environment and a temporary user config. npm inherits the terminal, so its
+ * interactive browser or one-time-password (2FA) confirmation works.
  *
  * @param {string} repositoryRoot - Package root.
+ * @param {{ authConfigLine: string, artifactPath?: string | null }} publication - Registry credential line from
+ *   {@link buildNpmAuthConfigLine}, and the archive relative to the root (already checked with `isSafeArtifactPath`);
+ *   without `artifactPath` the working tree is published.
  * @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): Promise<{
+export declare function publishToNpm(repositoryRoot: string, { authConfigLine, artifactPath }: {
+    authConfigLine: string;
+    artifactPath?: string | null;
+}): Promise<{
     exitCode: number;
     missingToken: boolean;
 }>;

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

@@ -13,6 +13,7 @@ export type CapturedResult = {
 export type CommandOptions = {
     cwd?: string;
     shell?: boolean;
+    env?: NodeJS.ProcessEnv;
 };
 export type GitReader = {
     git: (gitArguments: string[]) => Promise<string>;
@@ -25,7 +26,7 @@ export type CommitRecord = {
 };
 /**
  * @typedef {{ status: number, stdout: string, stderr: string }} CapturedResult
- * @typedef {{ cwd?: string, shell?: boolean }} CommandOptions
+ * @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
  */
@@ -80,6 +81,14 @@ export declare function parseCommitLog(output: string): CommitRecord[];
  * @returns {Promise<CommitRecord[]>} Commits, newest first.
  */
 export declare function listCommits(reader: GitReader, range: string): Promise<CommitRecord[]>;
+/**
+ * Reads `package.json` at a revision.
+ *
+ * @param {GitReader} reader - Git reader.
+ * @param {string} revision - Revision such as `HEAD`, `v1.2.0` or `origin/main`.
+ * @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): Promise<Record<string, unknown> | null>;
 /**
  * Reads the `version` field of `package.json` at a revision.
  *

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

@@ -29,6 +29,8 @@ export type ReleaseContext = {
     pushed: boolean;
     published: boolean;
     commitCount: number | null;
+    packageName: string;
+    registryUrl: string | null;
 };
 /**
  * Creates the context passed to project hooks.

package/types/guard-publish.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `prepublishOnly` guard of the Beez packages: they are published with npm by
+ * `pnpm create-version`, which verifies the tarball against
+ * `npm pack --dry-run`, so a `pnpm publish` (or yarn/bun) is blocked.
+ *
+ * The guard only blocks package managers it recognizes. Without a user agent,
+ * or with an unknown one, the publisher cannot be determined and it allows the
+ * publication. It can be bypassed on purpose with `--ignore-scripts`.
+ *
+ * @module guard-publish
+ */
+export type PublishGuardDecision = {
+    allowed: boolean;
+    packageManager: string | null;
+    message: string | null;
+    exitCode: number;
+};
+/**
+ * @typedef {{ allowed: boolean, packageManager: string | null, message: string | null, exitCode: number }} PublishGuardDecision
+ */
+/**
+ * Finds the blocked package manager that runs the publication.
+ *
+ * @param {string | undefined} userAgent - Value of `npm_config_user_agent`.
+ * @returns {string | null} Blocked package manager name, or `null` for npm, unknown or missing user agents.
+ */
+export declare function findBlockedPublishPackageManager(userAgent: string | undefined): string | null;
+/**
+ * Builds the explanation printed when a publication is blocked.
+ *
+ * @param {string} packageManager - Blocked package manager name.
+ * @returns {string} Message in Spanish with what to run instead.
+ */
+export declare function buildBlockedPublishMessage(packageManager: string): string;
+/**
+ * Decides whether the publication may continue.
+ *
+ * @param {string | undefined} userAgent - Value of `npm_config_user_agent`.
+ * @returns {PublishGuardDecision} Decision, message to print on stderr and exit code.
+ */
+export declare function decidePublishGuard(userAgent: string | undefined): PublishGuardDecision;
+/**
+ * Decides with the user agent of an environment (the current process by default).
+ *
+ * @param {NodeJS.ProcessEnv} [environment] - Environment of the lifecycle script.
+ * @returns {PublishGuardDecision} Decision for its `npm_config_user_agent`.
+ */
+export declare function decidePublishGuardForEnvironment(environment?: NodeJS.ProcessEnv): PublishGuardDecision;

package/types/index.d.ts

@@ -4,6 +4,7 @@
  * - `beez-rp/versions`: stable `X.Y.Z` rules; only the next patch, minor or major is allowed.
  * - `beez-rp/build-gate`: Vercel `ignoreCommand` decision built on those rules.
  * - `beez-rp/changelog` and `beez-rp/changelog-ai`: Keep a Changelog release and Codex fill-in.
+ * - `beez-rp/guard-publish`: `prepublishOnly` guard that blocks pnpm, yarn and bun publications.
  * - `beez-rp/terminal-ui`: boxes, spinners and prompts for release commands.
  * - `beez-rp/testing`: shared version bump fixtures for consumer test suites.
  * - `beez-rp/constants`: every constant above, grouped by domain.
@@ -13,6 +14,7 @@
 export * from "./build-gate.js";
 export * from "./changelog.js";
 export * from "./changelog-ai.js";
+export * from "./guard-publish.js";
 export * from "./versions.js";
 export { ICON, countTerminalRows, formatDuration, getPromptWaitMs, measureActiveMs, paint, print, renderBanner, renderBox, renderRow, renderStepHeader, resolveBoxWidth, resolveNumberKey, select, startSpinner, visibleWidth, wrapStyledLine, } from "./terminal-ui.js";
 export * from "./constants/index.js";