@capybara-hq/plugin-tools 0.0.0-stage → 0.1.0-rc.1

package/dist/release/publish-plan.d.ts

@@ -0,0 +1,68 @@
+/** A workspace package as the release sees it (`dir` is relative to the repo root, POSIX separators). */
+export interface WorkspacePackage {
+    name: string;
+    version: string;
+    dir: string;
+    private: boolean;
+    /** Lives under `plugins/`: published as its plugin tgz (`packPlugin`), not as a pnpm pack of the source tree. */
+    isPlugin: boolean;
+}
+/**
+ * One publish. `pnpm`: `pnpm pack` (rewrites `workspace:` ranges) then `npm publish <tgz>`;
+ * `plugin-tgz`: `packPlugin(dir)` then `npm publish <tgz>`.
+ */
+export interface PublishStep {
+    name: string;
+    version: string;
+    kind: "pnpm" | "plugin-tgz";
+    dir: string;
+    /** `npm publish --tag`: see `distTagFor`. */
+    tag: string;
+}
+/**
+ * The npm dist-tag a version is published under, following the image `latest` rule: a prerelease
+ * goes to `next`; a stable version below the highest stable version already on the registry (a
+ * backport) goes to `release-<major>.<minor>`, so `latest` never moves back (and npm >= 11, which
+ * refuses an untagged publish below `latest`, accepts it); anything else is `latest`. Installing
+ * `npm:@capybara-hq/plugin-x` without a version therefore never picks up an rc or a backport.
+ */
+export declare function distTagFor(version: string, published: readonly string[]): string;
+/**
+ * Library packages that must reach the registry before the ones that depend on them: kernel and testing
+ * depend on the SDK, testing depends on the kernel, plugin-tools depends on the SDK and the kernel
+ * (testing only peer-depends on it, optionally). Other non-plugin packages follow, then plugins (which
+ * only peer-depend on the SDK). Names a repository does not have are skipped.
+ */
+export declare const LIBRARY_ORDER: string[];
+/**
+ * The publish plan: every non-private package whose current version is not yet on npm, SDK first, kernel
+ * before testing, plugins last (each group by name). `published` maps a package name to the versions the
+ * registry already has (missing = never published). Skipping already-published versions makes a rerun of
+ * a half-finished release idempotent.
+ */
+export declare function planPublish(pkgs: readonly WorkspacePackage[], published: ReadonlyMap<string, readonly string[]>): PublishStep[];
+/** The versions listed in a registry packument (`GET <registry>/<name>`); anything else counts as none. */
+export declare function publishedVersionsOf(packument: unknown): string[];
+/**
+ * True while none of the packages that would be published has any version on the registry: the first
+ * release. Automatic (push-triggered) releases refuse to do it; the first publish is a manual
+ * `workflow_dispatch` once the prerequisites are confirmed (P-16).
+ */
+export declare function isFirstRelease(pkgs: readonly WorkspacePackage[], published: ReadonlyMap<string, readonly string[]>): boolean;
+/**
+ * Whether publishing `version` promotes a release candidate: `version` is stable and the highest
+ * version on the registry is a prerelease of the same major.minor.patch (0.1.0 after 0.1.0-rc.1).
+ */
+export declare function isPromotion(version: string, published: readonly string[]): boolean;
+/**
+ * The packages a release would promote from a release candidate (see {@link isPromotion}), as
+ * `name@version`. Automatic (push) releases refuse them: the promotion, like the first release, is a
+ * manual `workflow_dispatch`.
+ */
+export declare function promotions(pkgs: readonly WorkspacePackage[], published: ReadonlyMap<string, readonly string[]>): string[];
+/**
+ * Problems in a library manifest as packed for npm: a leftover `workspace:` range (pnpm pack failed to
+ * rewrite it) or the dev-only `@capybara-hq/source` export condition, which points at `src/` that is
+ * not shipped (`publishConfig.exports` replaces it).
+ */
+export declare function packedManifestIssues(pkg: Record<string, unknown>): string[];

package/dist/release/publish-plan.js

@@ -0,0 +1,117 @@
+/**
+ * Pure planning for the npm release: which workspace packages get published, in which order and how.
+ * No I/O here; `publish.ts` discovers the workspace and asks the registry. Used by core's release
+ * (`pnpm release`) and by any plugin repository (`capybara-plugin release`).
+ */
+import { compareSemver, isPrerelease, parseSemver, SEMVER_RE } from "./semver.js";
+/**
+ * The npm dist-tag a version is published under, following the image `latest` rule: a prerelease
+ * goes to `next`; a stable version below the highest stable version already on the registry (a
+ * backport) goes to `release-<major>.<minor>`, so `latest` never moves back (and npm >= 11, which
+ * refuses an untagged publish below `latest`, accepts it); anything else is `latest`. Installing
+ * `npm:@capybara-hq/plugin-x` without a version therefore never picks up an rc or a backport.
+ */
+export function distTagFor(version, published) {
+    if (isPrerelease(version))
+        return "next";
+    const below = published.some((v) => SEMVER_RE.test(v) && !isPrerelease(v) && compareSemver(version, v) < 0);
+    if (!below)
+        return "latest";
+    const [major, minor] = version.split(".");
+    return `release-${major}.${minor}`;
+}
+/**
+ * Library packages that must reach the registry before the ones that depend on them: kernel and testing
+ * depend on the SDK, testing depends on the kernel, plugin-tools depends on the SDK and the kernel
+ * (testing only peer-depends on it, optionally). Other non-plugin packages follow, then plugins (which
+ * only peer-depend on the SDK). Names a repository does not have are skipped.
+ */
+export const LIBRARY_ORDER = [
+    "@capybara-hq/plugin-sdk",
+    "@capybara-hq/kernel",
+    "@capybara-hq/testing",
+    "@capybara-hq/plugin-tools",
+];
+function rank(p) {
+    if (p.isPlugin)
+        return LIBRARY_ORDER.length + 1;
+    const i = LIBRARY_ORDER.indexOf(p.name);
+    return i < 0 ? LIBRARY_ORDER.length : i;
+}
+/**
+ * The publish plan: every non-private package whose current version is not yet on npm, SDK first, kernel
+ * before testing, plugins last (each group by name). `published` maps a package name to the versions the
+ * registry already has (missing = never published). Skipping already-published versions makes a rerun of
+ * a half-finished release idempotent.
+ */
+export function planPublish(pkgs, published) {
+    return pkgs
+        .filter((p) => !p.private && !(published.get(p.name) ?? []).includes(p.version))
+        .sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name))
+        .map((p) => ({
+        name: p.name,
+        version: p.version,
+        kind: p.isPlugin ? "plugin-tgz" : "pnpm",
+        dir: p.dir,
+        tag: distTagFor(p.version, published.get(p.name) ?? []),
+    }));
+}
+/** The versions listed in a registry packument (`GET <registry>/<name>`); anything else counts as none. */
+export function publishedVersionsOf(packument) {
+    if (typeof packument !== "object" || packument === null)
+        return [];
+    const versions = packument.versions;
+    if (typeof versions !== "object" || versions === null)
+        return [];
+    return Object.keys(versions);
+}
+/**
+ * True while none of the packages that would be published has any version on the registry: the first
+ * release. Automatic (push-triggered) releases refuse to do it; the first publish is a manual
+ * `workflow_dispatch` once the prerequisites are confirmed (P-16).
+ */
+export function isFirstRelease(pkgs, published) {
+    return pkgs.every((p) => p.private || (published.get(p.name) ?? []).length === 0);
+}
+/**
+ * Whether publishing `version` promotes a release candidate: `version` is stable and the highest
+ * version on the registry is a prerelease of the same major.minor.patch (0.1.0 after 0.1.0-rc.1).
+ */
+export function isPromotion(version, published) {
+    const v = parseSemver(version);
+    if (v === undefined || v.pre.length > 0)
+        return false;
+    const semvers = published.filter((p) => SEMVER_RE.test(p));
+    if (semvers.length === 0)
+        return false;
+    const highest = semvers.reduce((a, b) => (compareSemver(a, b) >= 0 ? a : b));
+    const h = parseSemver(highest);
+    return h !== undefined && h.pre.length > 0 && h.core.join(".") === v.core.join(".");
+}
+/**
+ * The packages a release would promote from a release candidate (see {@link isPromotion}), as
+ * `name@version`. Automatic (push) releases refuse them: the promotion, like the first release, is a
+ * manual `workflow_dispatch`.
+ */
+export function promotions(pkgs, published) {
+    return pkgs
+        .filter((p) => !p.private && isPromotion(p.version, published.get(p.name) ?? []))
+        .map((p) => `${p.name}@${p.version}`)
+        .sort();
+}
+/**
+ * Problems in a library manifest as packed for npm: a leftover `workspace:` range (pnpm pack failed to
+ * rewrite it) or the dev-only `@capybara-hq/source` export condition, which points at `src/` that is
+ * not shipped (`publishConfig.exports` replaces it).
+ */
+export function packedManifestIssues(pkg) {
+    const issues = [];
+    const text = JSON.stringify(pkg);
+    if (text.includes('"workspace:'))
+        issues.push("has a workspace: dependency range");
+    if (text.includes('"@capybara-hq/source"'))
+        issues.push('exports the "@capybara-hq/source" condition');
+    if (pkg.publishConfig !== undefined)
+        issues.push("still has publishConfig (not applied)");
+    return issues;
+}

package/dist/release/publish.d.ts

@@ -0,0 +1,91 @@
+import { integrityOf } from "../integrity.js";
+import { type WorkspacePackage } from "./publish-plan.js";
+/** Reads every workspace package.json under `root`. Plugins are the packages under `plugins/`. */
+export declare function discoverWorkspace(root: string): WorkspacePackage[];
+/**
+ * Keeps the libraries and the plugins whose directory matches one of `patterns` (see
+ * {@link RunPublishOptions.plugins}); throws on a pattern that matches no plugin.
+ */
+export declare function selectPlugins(pkgs: readonly WorkspacePackage[], patterns: readonly string[] | undefined): WorkspacePackage[];
+/** Registry to compare against; npm reads the same variable when publishing. */
+export declare function registryUrl(): string;
+/**
+ * Versions of `name` already on the registry (an anonymous read: every published package is public).
+ * 404 means never published. Any other failure stops the release rather than guessing.
+ */
+export declare function fetchPublishedVersions(name: string): Promise<string[]>;
+export { integrityOf };
+/** Runs a command; the release passes `cwd` and expects a non-zero exit to throw. */
+export type Exec = (cmd: string, args: string[], cwd: string) => Promise<void>;
+/**
+ * Guard for automatic (push) releases: the checkout must be exactly the pushed commit (`expectedHead`,
+ * i.e. GITHUB_SHA) with no uncommitted changes to any workspace package.json. What gets published is
+ * then always the committed main tree, whose versions only change when a reviewed PR (the Version
+ * Packages PR) merges; output of a `changeset version` run can never be published (C1).
+ */
+export declare function assertCommittedTree(opts?: {
+    root?: string;
+    expectedHead?: string | undefined;
+}): void;
+export interface RunPublishOptions {
+    /** Pack everything and run `npm publish --dry-run`; nothing reaches the registry. */
+    dryRun: boolean;
+    /** Pass `--provenance` (needs GitHub Actions with `id-token: write`). */
+    provenance: boolean;
+    /** Output directory for the tgz files and the plugin checksums (emptied first). */
+    out: string;
+    /** Repository root (default: the current directory). */
+    root?: string;
+    /**
+     * Refuse the first release (nothing public on the registry yet) and publish nothing: automatic
+     * releases set it so the first publish stays a manual `workflow_dispatch` (P-16).
+     */
+    refuseFirstRelease?: boolean;
+    /**
+     * Refuse, and publish nothing, when any package would be promoted from a release candidate to its
+     * stable version ({@link promotions}): automatic releases set it so the promotion stays manual.
+     */
+    refusePromotion?: boolean;
+    /** Registry lookup (tests). */
+    publishedVersions?: (name: string) => Promise<readonly string[]>;
+    /** Command runner for `pnpm pack` / `npm publish` (tests). */
+    exec?: Exec;
+    /** Plugin packer (tests); returns the tgz path. */
+    packPluginTgz?: (dir: string, outDir: string) => Promise<string>;
+    /** Reads `package/package.json` out of a packed library tgz (tests). */
+    readPackedManifest?: (tgz: string) => Record<string, unknown>;
+    /** Called after each successful publish with the running count (the CLI writes $GITHUB_OUTPUT). */
+    onPublished?: (count: number) => void;
+    /**
+     * Limits the plugins (packages under `plugins/`) the release looks at to those whose directory,
+     * relative to `root`, matches one of these patterns (`*` matches within one path segment); the
+     * other plugins are neither looked up nor published. Libraries are unaffected. A pattern that
+     * matches no plugin is an error. Unset = every plugin.
+     */
+    plugins?: readonly string[];
+    /**
+     * The repository's `marketplace.json`: each plugin pack's sha512 must equal the integrity of that
+     * version's npm entry there before it is published ({@link ReleaseIntegrityError} otherwise), so
+     * what reaches npm is byte for byte what the reviewed marketplace lists.
+     */
+    marketplace?: string;
+}
+/**
+ * A plugin pack that differs from its `marketplace.json` entry (or has none): every planned plugin
+ * is packed and checked before the first publish, so the release stops (`code`
+ * `release.integrity_mismatch`) with nothing published.
+ */
+export declare class ReleaseIntegrityError extends Error {
+    readonly code = "release.integrity_mismatch";
+    constructor(message: string);
+}
+/**
+ * Publishes every workspace package whose version is not on npm yet, in plan order. After each plugin
+ * publish it rewrites `<out>/plugins/SHA512SUMS` (hex, `sha512sum -c` format) and
+ * `<out>/plugins/integrity.json` (SRI), so a release that fails half-way still leaves the checksums of
+ * what it did publish.
+ */
+export declare function runPublish(opts: RunPublishOptions): Promise<{
+    published: string[];
+    skipped: string[];
+}>;

package/dist/release/publish.js

@@ -0,0 +1,274 @@
+import { execFileSync, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { parseMarketplaceManifest } from "@capybara-hq/plugin-sdk";
+import { integrityOf } from "../integrity.js";
+import { packPlugin } from "../pack/pack.js";
+import { isFirstRelease, packedManifestIssues, planPublish, promotions, publishedVersionsOf, } from "./publish-plan.js";
+/**
+ * The workspace groups a release looks at (one level deep, like `pnpm-workspace.yaml` `<group>/*`
+ * entries): core's layout, which a plugin repository (`plugins/*`, `tools/*`) is a subset of.
+ */
+const WORKSPACE_DIRS = ["packages", "apps", "plugins", "tools"];
+/** Workspace package directories (relative, POSIX) in the working tree. */
+function workspaceDirs(root) {
+    const dirs = [];
+    for (const group of WORKSPACE_DIRS) {
+        const base = join(root, group);
+        if (!existsSync(base))
+            continue;
+        for (const e of readdirSync(base, { withFileTypes: true })) {
+            if (e.isDirectory() && existsSync(join(base, e.name, "package.json"))) {
+                dirs.push(`${group}/${e.name}`);
+            }
+        }
+    }
+    return dirs.sort();
+}
+function toWorkspacePackage(dir, text) {
+    const pkg = JSON.parse(text);
+    if (typeof pkg.name !== "string" || typeof pkg.version !== "string") {
+        throw new Error(`${dir}/package.json needs a name and a version`);
+    }
+    return {
+        name: pkg.name,
+        version: pkg.version,
+        dir,
+        private: pkg.private === true,
+        isPlugin: dir.startsWith("plugins/"),
+    };
+}
+/** Reads every workspace package.json under `root`. Plugins are the packages under `plugins/`. */
+export function discoverWorkspace(root) {
+    return workspaceDirs(root).map((dir) => toWorkspacePackage(dir, readFileSync(join(root, dir, "package.json"), "utf8")));
+}
+/** `--plugins` patterns: `*` matches within one path segment, everything else literally. */
+function pluginPattern(pattern) {
+    const body = pattern
+        .replace(/\/+$/, "")
+        .split("*")
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join("[^/]*");
+    return new RegExp(`^${body}$`);
+}
+/**
+ * Keeps the libraries and the plugins whose directory matches one of `patterns` (see
+ * {@link RunPublishOptions.plugins}); throws on a pattern that matches no plugin.
+ */
+export function selectPlugins(pkgs, patterns) {
+    if (patterns === undefined)
+        return [...pkgs];
+    const res = patterns.map((p) => ({ p, re: pluginPattern(p) }));
+    for (const { p, re } of res) {
+        if (!pkgs.some((k) => k.isPlugin && re.test(k.dir))) {
+            throw new Error(`--plugins ${p} matches no plugin under plugins/`);
+        }
+    }
+    return pkgs.filter((k) => !k.isPlugin || res.some(({ re }) => re.test(k.dir)));
+}
+/** Registry to compare against; npm reads the same variable when publishing. */
+export function registryUrl() {
+    const r = process.env.NPM_CONFIG_REGISTRY ?? process.env.npm_config_registry;
+    return (r === undefined || r === "" ? "https://registry.npmjs.org" : r).replace(/\/+$/, "");
+}
+/**
+ * Versions of `name` already on the registry (an anonymous read: every published package is public).
+ * 404 means never published. Any other failure stops the release rather than guessing.
+ */
+export async function fetchPublishedVersions(name) {
+    const url = `${registryUrl()}/${name.replace("/", "%2f")}`;
+    const res = await fetch(url, { headers: { accept: "application/json" } });
+    if (res.status === 404)
+        return [];
+    if (!res.ok)
+        throw new Error(`registry lookup for ${name} failed: HTTP ${res.status}`);
+    return publishedVersionsOf(await res.json());
+}
+export { integrityOf };
+/** npm pack's file name: `@scope/name` + version -> `scope-name-<version>.tgz`. */
+const tgzName = (name, version) => `${name.replace(/^@/, "").replace("/", "-")}-${version}.tgz`;
+/** Runs a command with inherited stdio (its output is the publish log; it never echoes tokens). */
+const run = (cmd, args, cwd) => new Promise((res, rej) => {
+    const child = spawn(cmd, args, { cwd, stdio: "inherit", env: process.env });
+    child.on("error", rej);
+    child.on("exit", (code, signal) => code === 0
+        ? res()
+        : rej(new Error(`${cmd} ${args.join(" ")} exited with ${signal ?? `code ${code}`}`)));
+});
+/** `package/package.json` of an npm tgz, via the system tar. */
+function readTgzManifest(tgz) {
+    return JSON.parse(execFileSync("tar", ["-xzOf", tgz, "package/package.json"], { encoding: "utf8" }));
+}
+/**
+ * Guard for automatic (push) releases: the checkout must be exactly the pushed commit (`expectedHead`,
+ * i.e. GITHUB_SHA) with no uncommitted changes to any workspace package.json. What gets published is
+ * then always the committed main tree, whose versions only change when a reviewed PR (the Version
+ * Packages PR) merges; output of a `changeset version` run can never be published (C1).
+ */
+export function assertCommittedTree(opts = {}) {
+    const root = opts.root ?? process.cwd();
+    if (opts.expectedHead !== undefined && opts.expectedHead !== "") {
+        const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+        if (head !== opts.expectedHead) {
+            throw new Error(`the release checkout is at ${head}, not the pushed commit ${opts.expectedHead}: refusing to publish`);
+        }
+    }
+    const dirty = execFileSync("git", ["status", "--porcelain", "--", ...workspaceDirs(root).map((d) => `${d}/package.json`)], { cwd: root, encoding: "utf8" }).trim();
+    if (dirty !== "") {
+        throw new Error(`uncommitted package.json changes in the release checkout (publish only committed versions):\n${dirty}`);
+    }
+}
+/**
+ * A plugin pack that differs from its `marketplace.json` entry (or has none): every planned plugin
+ * is packed and checked before the first publish, so the release stops (`code`
+ * `release.integrity_mismatch`) with nothing published.
+ */
+export class ReleaseIntegrityError extends Error {
+    code = "release.integrity_mismatch";
+    constructor(message) {
+        super(`release.integrity_mismatch: ${message}`);
+        this.name = "ReleaseIntegrityError";
+    }
+}
+/** Reads and parses a marketplace manifest for the release; throws on an unreadable one. */
+function readMarketplace(file) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`cannot read the marketplace ${file}: ${e instanceof Error ? e.message : e}`);
+    }
+    const m = parseMarketplaceManifest(raw);
+    if ("errors" in m)
+        throw new Error(`the marketplace ${file} is invalid: ${m.errors.join("; ")}`);
+    return m.plugins;
+}
+/** The npm source a marketplace lists for `<pkg>@<version>`, if any. */
+function marketplaceNpm(entries, pkg, version) {
+    for (const e of entries) {
+        if ("npm" in e.source && e.source.npm.package === pkg && e.source.npm.version === version) {
+            return e.source.npm;
+        }
+    }
+    return undefined;
+}
+/**
+ * Publishes every workspace package whose version is not on npm yet, in plan order. After each plugin
+ * publish it rewrites `<out>/plugins/SHA512SUMS` (hex, `sha512sum -c` format) and
+ * `<out>/plugins/integrity.json` (SRI), so a release that fails half-way still leaves the checksums of
+ * what it did publish.
+ */
+export async function runPublish(opts) {
+    const root = opts.root ?? process.cwd();
+    const out = resolve(opts.out);
+    const lookup = opts.publishedVersions ?? fetchPublishedVersions;
+    const exec = opts.exec ?? run;
+    const packTgz = opts.packPluginTgz ?? (async (dir, o) => (await packPlugin(dir, o)).file);
+    const readManifest = opts.readPackedManifest ?? readTgzManifest;
+    const pkgs = selectPlugins(discoverWorkspace(root), opts.plugins);
+    const listed = opts.marketplace === undefined ? undefined : readMarketplace(opts.marketplace);
+    if (pkgs.length === 0) {
+        throw new Error(`no workspace package found under ${root}: the release publishes the packages in ` +
+            `${WORKSPACE_DIRS.map((d) => `${d}/*`).join(", ")} (each a directory with a package.json; ` +
+            "plugins are the ones under plugins/); pass --root <repository root>");
+    }
+    const published = new Map();
+    for (const p of pkgs)
+        if (!p.private)
+            published.set(p.name, await lookup(p.name));
+    if (opts.refuseFirstRelease === true && isFirstRelease(pkgs, published)) {
+        console.log("nothing is on the registry yet: the first release is published only by running the " +
+            "release workflow manually (workflow_dispatch)");
+        return { published: [], skipped: [] };
+    }
+    const promoting = opts.refusePromotion === true ? promotions(pkgs, published) : [];
+    if (promoting.length > 0) {
+        console.log(`refusing to promote release candidates on push (${promoting.join(", ")}): the stable ` +
+            "release after an rc is published only by running the release workflow manually " +
+            "(workflow_dispatch)");
+        return { published: [], skipped: [] };
+    }
+    const steps = planPublish(pkgs, published);
+    const planned = new Set(steps.map((s) => s.name));
+    const skipped = pkgs
+        .filter((p) => !p.private && !planned.has(p.name))
+        .map((p) => `${p.name}@${p.version}`)
+        .sort();
+    for (const s of skipped)
+        console.log(`skip    ${s} (already on the registry)`);
+    for (const s of steps)
+        console.log(`publish ${s.name}@${s.version} (${s.kind}, ${s.dir}, tag ${s.tag})`);
+    if (steps.length === 0) {
+        console.log("nothing to publish");
+        return { published: [], skipped };
+    }
+    await rm(out, { recursive: true, force: true });
+    const pluginsOut = join(out, "plugins");
+    const packagesOut = join(out, "packages");
+    await mkdir(pluginsOut, { recursive: true });
+    await mkdir(packagesOut, { recursive: true });
+    const done = [];
+    const sums = [];
+    const integrity = [];
+    // Every plugin is packed and checked against the marketplace before anything is published, so a
+    // mismatch stops the run with nothing new on the registry (dry runs check the same way).
+    const pluginFiles = new Map();
+    for (const step of steps.filter((s) => s.kind === "plugin-tgz")) {
+        const file = await packTgz(join(root, step.dir), pluginsOut);
+        if (listed !== undefined) {
+            const actual = integrityOf(new Uint8Array(await readFile(file)));
+            const entry = marketplaceNpm(listed, step.name, step.version);
+            if (entry === undefined) {
+                throw new ReleaseIntegrityError(`${step.name}@${step.version} (${step.dir}) has no npm entry in ${opts.marketplace}; its pack is ${actual} (capybara-plugin marketplace --write); nothing was published`);
+            }
+            if (entry.integrity !== actual) {
+                throw new ReleaseIntegrityError(`${step.name}@${step.version} (${step.dir}) packs ${actual} but ${opts.marketplace} lists ${entry.integrity}; nothing was published`);
+            }
+        }
+        pluginFiles.set(step.dir, file);
+    }
+    for (const step of steps) {
+        const dir = join(root, step.dir);
+        let file;
+        if (step.kind === "plugin-tgz") {
+            file = pluginFiles.get(step.dir);
+        }
+        else {
+            if (!existsSync(join(dir, "dist"))) {
+                throw new Error(`${step.dir}/dist is missing: run \`pnpm build\` before releasing`);
+            }
+            // pnpm pack rewrites `workspace:` ranges and applies publishConfig; npm publish adds provenance.
+            await exec("pnpm", ["pack", "--pack-destination", packagesOut], dir);
+            file = join(packagesOut, tgzName(step.name, step.version));
+            if (!existsSync(file))
+                throw new Error(`pnpm pack did not produce ${file}`);
+            const issues = packedManifestIssues(readManifest(file));
+            if (issues.length > 0)
+                throw new Error(`${basename(file)}: ${issues.join("; ")}`);
+        }
+        const args = ["publish", file, "--access", "public", "--tag", step.tag];
+        if (opts.provenance)
+            args.push("--provenance");
+        if (opts.dryRun)
+            args.push("--dry-run");
+        await exec("npm", args, root);
+        done.push(`${step.name}@${step.version}`);
+        opts.onPublished?.(done.length);
+        if (step.kind === "plugin-tgz") {
+            const bytes = await readFile(file);
+            sums.push(`${createHash("sha512").update(bytes).digest("hex")}  ${basename(file)}`);
+            integrity.push({
+                name: step.name,
+                version: step.version,
+                file: basename(file),
+                integrity: integrityOf(bytes),
+            });
+            await writeFile(join(pluginsOut, "SHA512SUMS"), sums.map((l) => `${l}\n`).join(""));
+            await writeFile(join(pluginsOut, "integrity.json"), `${JSON.stringify(integrity, null, 2)}\n`);
+        }
+    }
+    return { published: done, skipped };
+}

package/dist/release/semver.d.ts

@@ -0,0 +1,11 @@
+/** Plain semver helpers shared by the npm dist-tag rule and core's image `latest` rule. */
+/** A plain semver without build metadata (also a valid image tag: `+` is not allowed in tags). */
+export declare const SEMVER_RE: RegExp;
+export declare const isPrerelease: (version: string) => boolean;
+/** Parses a plain semver (`latest`, digests and other strings give undefined). */
+export declare function parseSemver(v: string): {
+    core: number[];
+    pre: string[];
+} | undefined;
+/** Semver precedence (no build metadata): negative when a < b. Both must be plain semvers. */
+export declare function compareSemver(a: string, b: string): number;

package/dist/release/semver.js

@@ -0,0 +1,44 @@
+/** Plain semver helpers shared by the npm dist-tag rule and core's image `latest` rule. */
+/** A plain semver without build metadata (also a valid image tag: `+` is not allowed in tags). */
+export const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z]+(\.[0-9A-Za-z-]+)*)?$/;
+export const isPrerelease = (version) => version.includes("-");
+/** Parses a plain semver (`latest`, digests and other strings give undefined). */
+export function parseSemver(v) {
+    if (!SEMVER_RE.test(v))
+        return undefined;
+    const [core = "", pre] = v.split(/-(.*)/s);
+    return { core: core.split(".").map(Number), pre: pre === undefined ? [] : pre.split(".") };
+}
+/** Semver precedence (no build metadata): negative when a < b. Both must be plain semvers. */
+export function compareSemver(a, b) {
+    const x = parseSemver(a);
+    const y = parseSemver(b);
+    if (x === undefined || y === undefined)
+        throw new Error(`not a semver: ${a} / ${b}`);
+    for (let i = 0; i < 3; i++) {
+        const d = (x.core[i] ?? 0) - (y.core[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    // A version without a prerelease part ranks above any prerelease of it.
+    if (x.pre.length === 0 || y.pre.length === 0)
+        return y.pre.length - x.pre.length;
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+        const p = x.pre[i];
+        const q = y.pre[i];
+        if (p === undefined)
+            return -1;
+        if (q === undefined)
+            return 1;
+        if (p === q)
+            continue;
+        const pn = /^\d+$/.test(p);
+        const qn = /^\d+$/.test(q);
+        if (pn && qn)
+            return Number(p) - Number(q);
+        if (pn !== qn)
+            return pn ? -1 : 1;
+        return p < q ? -1 : 1;
+    }
+    return 0;
+}