@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/scripts/lib/fault-workspace.mjs

@@ -0,0 +1,210 @@
+/**
+ * What `verify-traps.mjs` and `verify-faults.mjs` share: a throwaway copy of a
+ * package to apply a fault to, and the one way a fault is written down.
+ *
+ * Both scripts prove that a check bites by breaking the code it guards and
+ * watching the check fail. Neither may ever touch the working tree while it
+ * does: an interrupted run would leave a fault in the source, and a fault left
+ * in the source is a bug somebody commits. So the fault goes into a copy under
+ * the system temp directory, and the copy is deleted afterwards.
+ */
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, isAbsolute, join, relative, resolve } from "node:path"
+
+/** A fault that cannot be applied: its target moved, or it is written wrongly. */
+export class FaultError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "FaultError"
+  }
+}
+
+/**
+ * One textual edit of a fault: `search` becomes `replace` in `file`, a path
+ * relative to the package the fault is applied to.
+ *
+ * @typedef {object} Edit
+ * @property {string} file
+ * @property {string} search
+ * @property {string} replace
+ * @property {boolean} [all] Replace every occurrence. By default `search` must
+ *   occur exactly once.
+ */
+
+/** How many times `search` occurs in `text`, without overlap. */
+function occurrences(text, search) {
+  let count = 0
+  for (
+    let at = text.indexOf(search);
+    at !== -1;
+    at = text.indexOf(search, at + search.length)
+  ) {
+    count++
+  }
+  return count
+}
+
+/**
+ * Applies edits under `root`.
+ *
+ * Each `search` must occur exactly once (unless the edit says `all`), so a
+ * fault that no longer finds its target, or finds it twice, fails loudly
+ * instead of silently doing nothing: a fault that changes nothing would make
+ * every check look as if it bit.
+ *
+ * @param {string} root The directory the edits' `file` paths are relative to.
+ * @param {Edit[]} edits
+ * @param {string} label The fault's name, for messages.
+ */
+export function applyEdits(root, edits, label) {
+  if (!Array.isArray(edits) || edits.length === 0) {
+    throw new FaultError(`${label}: the fault has no edits`)
+  }
+  for (const edit of edits) {
+    const { file, search, replace } = edit
+    if (
+      typeof file !== "string" ||
+      typeof search !== "string" ||
+      typeof replace !== "string"
+    ) {
+      throw new FaultError(
+        `${label}: an edit needs string "file", "search" and "replace" fields`
+      )
+    }
+    if (search === "" || search === replace) {
+      throw new FaultError(
+        `${label}: an edit of ${file} must search for something and replace it with something else`
+      )
+    }
+    const path = resolve(root, file)
+    const rel = relative(root, path)
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      throw new FaultError(`${label}: ${file} is outside the package`)
+    }
+    if (!existsSync(path)) {
+      throw new FaultError(`${label}: ${file} does not exist`)
+    }
+    const text = readFileSync(path, "utf8")
+    const count = occurrences(text, search)
+    const shown = JSON.stringify(
+      search.length > 70 ? `${search.slice(0, 70)}...` : search
+    )
+    if (count === 0) {
+      throw new FaultError(
+        `${label}: ${file} no longer contains ${shown}. The source moved on; update the fault.`
+      )
+    }
+    if (count > 1 && edit.all !== true) {
+      throw new FaultError(
+        `${label}: ${file} contains ${shown} ${count} times; make the search longer so it names one place`
+      )
+    }
+    writeFileSync(path, text.split(search).join(replace))
+  }
+}
+
+/** Directories and files a copy leaves out: built or installed, never read. */
+const SKIPPED = new Set(["node_modules", "dist", ".vitest", "coverage"])
+
+/**
+ * What a tool writes into a `node_modules` it runs next to: Vite's cache
+ * (`.vite`, where vitest keeps its results), the bundled config it loads
+ * (`.vite-temp`), and the like. They are not linked into a copy's installs,
+ * so the tool creates them in the copy.
+ */
+const TOOL_STATE = /^\.(?:vite|vitest|cache)/
+
+/**
+ * A `node_modules` in `target` that holds everything the installs at `source`
+ * hold, entry by entry, except what a tool writes there. Linking the whole
+ * directory would let vitest write its cache and its bundled config into the
+ * repository's installs, up to eight runs at once, from a script that promises
+ * to leave the working tree alone.
+ *
+ * @param {string} source The installs to mirror.
+ * @param {string} target Where the mirror goes; created here.
+ * @param {(target: string, path: string) => void} link Makes (and records)
+ *   one symlink, so `cleanup` can unlink it before anything is deleted.
+ */
+function linkInstalls(source, target, link) {
+  const real = realpathSync(source)
+  mkdirSync(target)
+  for (const name of readdirSync(real)) {
+    if (!TOOL_STATE.test(name)) link(join(real, name), join(target, name))
+  }
+}
+
+/**
+ * A copy of `packageDir` (relative to `repoRoot`, such as `packages/core`)
+ * in a fresh temporary directory laid out like the repository: the package at
+ * the same relative path and the root's `tsconfig.base.json` above it, so the
+ * package's `extends` still resolves. Its `node_modules` (and the root's) is
+ * linked entry by entry, not copied, so imports resolve exactly as in the
+ * repository while whatever a tool writes beside them (vitest's cache) lands
+ * in the copy.
+ *
+ * @returns {{ root: string, dir: string, cleanup: () => void }} `dir` is the
+ * copy of the package; call `cleanup` when done.
+ */
+export function createWorkspaceCopy({ repoRoot, packageDir }) {
+  // The real path: a temporary directory can sit behind a symlink
+  // (/var -> /private/var on macOS), and tools name files by their real paths.
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "ic-reactor-fault-")))
+  const links = []
+  const link = (target, path) => {
+    symlinkSync(target, path, "dir")
+    links.push(path)
+  }
+  try {
+    const base = join(repoRoot, "tsconfig.base.json")
+    if (existsSync(base)) cpSync(base, join(root, "tsconfig.base.json"))
+    const dir = join(root, packageDir)
+    cpSync(join(repoRoot, packageDir), dir, {
+      recursive: true,
+      filter: (source) =>
+        !SKIPPED.has(basename(source)) && !source.endsWith(".tsbuildinfo"),
+    })
+    const modules = join(repoRoot, packageDir, "node_modules")
+    if (existsSync(modules)) {
+      linkInstalls(modules, join(dir, "node_modules"), link)
+    }
+    const rootModules = join(repoRoot, "node_modules")
+    if (existsSync(rootModules)) {
+      linkInstalls(rootModules, join(root, "node_modules"), link)
+    }
+    return {
+      root,
+      dir,
+      cleanup() {
+        // Unlink the links first: whatever happens after, a recursive delete
+        // must never reach through one into the repository's installs.
+        for (const path of links) {
+          try {
+            if (lstatSync(path).isSymbolicLink()) unlinkSync(path)
+          } catch {
+            // Already gone.
+          }
+        }
+        rmSync(root, { recursive: true, force: true })
+      },
+    }
+  } catch (error) {
+    for (const path of links) unlinkSync(path)
+    rmSync(root, { recursive: true, force: true })
+    throw error
+  }
+}

package/scripts/lib/io.mjs

@@ -0,0 +1,29 @@
+/**
+ * What `verify-peer-floors.js` and `verify-typescript-floor.js` share to set
+ * up a scratch project and run tools in it.
+ */
+import { spawnSync } from "node:child_process"
+import { readFileSync, writeFileSync } from "node:fs"
+
+/** The JSON file at `path`, parsed. */
+export function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"))
+}
+
+/** `value` as JSON indented by two spaces, ending with a newline. */
+export function writeJson(path, value) {
+  writeFileSync(path, JSON.stringify(value, null, 2) + "\n")
+}
+
+/**
+ * Runs `command` in `cwd` with the output shown, and says whether it exited 0.
+ * `HUSKY=0` keeps an install in a scratch project from setting up git hooks.
+ */
+export function run(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+    env: { ...process.env, HUSKY: "0" },
+  })
+  return result.status === 0
+}

package/scripts/lib/io.test.mjs

@@ -0,0 +1,38 @@
+/**
+ * Tests of the helpers the two floor scripts share.
+ *
+ * Run by `pnpm test:scripts`.
+ */
+import assert from "node:assert/strict"
+import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { after, describe, it } from "node:test"
+import { readJson, run, writeJson } from "./io.mjs"
+
+const dir = mkdtempSync(join(tmpdir(), "scripts-io-test-"))
+after(() => rmSync(dir, { recursive: true, force: true }))
+
+describe("readJson and writeJson", () => {
+  it("write two-space JSON with a final newline, and read it back", () => {
+    const file = join(dir, "package.json")
+    writeJson(file, { name: "x", private: true })
+    assert.equal(
+      readFileSync(file, "utf8"),
+      '{\n  "name": "x",\n  "private": true\n}\n'
+    )
+    assert.deepEqual(readJson(file), { name: "x", private: true })
+  })
+})
+
+describe("run", () => {
+  it("says whether the command exited 0, run in cwd with HUSKY=0", () => {
+    const where = JSON.stringify(realpathSync(dir))
+    const check = (code) =>
+      `const { realpathSync } = require("node:fs")
+      if (realpathSync(process.cwd()) !== ${where} || process.env.HUSKY !== "0") process.exit(3)
+      process.exit(${code})`
+    assert.equal(run(process.execPath, ["-e", check(0)], dir), true)
+    assert.equal(run(process.execPath, ["-e", check(1)], dir), false)
+  })
+})

package/scripts/lib/markdown-fences.mjs

@@ -0,0 +1,56 @@
+/**
+ * Fenced code blocks in Markdown (and MDX), by the one rule the scripts share:
+ * `check-snippets.mjs` takes the code out of them, and `check-ai-context.js`
+ * skips them when it reads headings. Following CommonMark, a fence closes on a
+ * line of the same character, at least as long, with no info string, so a
+ * ```ts inside a ````markdown block is content, not a fence. Fences may be
+ * indented, as they are in lists and MDX components.
+ */
+
+/**
+ * The fence `line` opens, or null: its indentation, its marker (``` or ~~~,
+ * three or more), its language in lower case, and the rest of its info string
+ * split at whitespace.
+ *
+ * @returns {{ indent: number, marker: string, lang: string, info: string[] } | null}
+ */
+export function fenceOpening(line) {
+  // `.*` would stop at the `\r` that ends a CRLF line and match nothing, so
+  // the rest of the line is `[^\n]*`.
+  const match = /^(\s*)(`{3,}|~{3,})\s*([^\s`]*)([^\n]*)$/.exec(line)
+  if (match === null) return null
+  return {
+    indent: match[1].length,
+    marker: match[2],
+    lang: match[3].toLowerCase(),
+    info: match[4].trim().split(/\s+/).filter(Boolean),
+  }
+}
+
+/** Whether `line` closes the block that `marker` opened. */
+export function closesFence(line, marker) {
+  const close = /^\s*(`{3,}|~{3,})\s*$/.exec(line)
+  return (
+    close !== null &&
+    close[1][0] === marker[0] &&
+    close[1].length >= marker.length
+  )
+}
+
+/**
+ * A reader of a text's lines in order, which says for each whether it belongs
+ * to a fenced code block: a fence line, or a line of code inside one.
+ *
+ * @returns {(line: string) => boolean}
+ */
+export function fencedLines() {
+  let marker = null
+  return (line) => {
+    if (marker === null) {
+      marker = fenceOpening(line)?.marker ?? null
+      return marker !== null
+    }
+    if (closesFence(line, marker)) marker = null
+    return true
+  }
+}

package/scripts/lib/markdown-fences.test.mjs

@@ -0,0 +1,84 @@
+/**
+ * Tests of the fence rule `check-snippets.mjs` and `check-ai-context.js` share.
+ *
+ * Run by `pnpm test:scripts`.
+ */
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import { closesFence, fenceOpening, fencedLines } from "./markdown-fences.mjs"
+
+/** Which lines of `text` the reader puts in a block, by 1-based number. */
+const fenced = (text) => {
+  const read = fencedLines()
+  return text.split("\n").flatMap((line, i) => (read(line) ? [i + 1] : []))
+}
+
+describe("fenceOpening", () => {
+  it("reads the indent, the marker, the language and the rest of the info", () => {
+    assert.deepEqual(fenceOpening("  ```TSX title=x.tsx skip"), {
+      indent: 2,
+      marker: "```",
+      lang: "tsx",
+      info: ["title=x.tsx", "skip"],
+    })
+    assert.deepEqual(fenceOpening("~~~~"), {
+      indent: 0,
+      marker: "~~~~",
+      lang: "",
+      info: [],
+    })
+  })
+
+  it("is null for a line that opens no fence", () => {
+    for (const line of ["``", "text ```ts", "~~", ""]) {
+      assert.equal(fenceOpening(line), null, line)
+    }
+  })
+})
+
+describe("closesFence", () => {
+  it("closes on the same character, at least as long, with no info string", () => {
+    assert.equal(closesFence("```", "```"), true)
+    assert.equal(closesFence("  `````  ", "```"), true)
+    assert.equal(closesFence("```ts", "```"), false)
+    assert.equal(closesFence("```", "````"), false)
+    assert.equal(closesFence("~~~", "```"), false)
+  })
+})
+
+describe("fencedLines", () => {
+  it("puts the fence lines and the code between them in the block", () => {
+    assert.deepEqual(fenced("# A\n```ts\n# not a heading\n```\n# B"), [2, 3, 4])
+  })
+
+  it("does not end a block on a line with an info string", () => {
+    // `check-ai-context.js` read its headings by a rule of its own, under
+    // which this ```ts ended the block and `## In code` was a heading.
+    assert.deepEqual(
+      fenced("```\n```ts\n## In code\n```\n# After"),
+      [1, 2, 3, 4]
+    )
+  })
+
+  it("does not end a block on a shorter or another fence", () => {
+    assert.deepEqual(fenced("````md\n```\n~~~~\n````\nafter"), [1, 2, 3, 4])
+  })
+
+  it("runs a block that is never closed to the end", () => {
+    assert.deepEqual(fenced("text\n```\ncode\n# code"), [2, 3, 4])
+  })
+
+  it("reads the lines of a file with CRLF line endings", () => {
+    assert.deepEqual(
+      fenced("```ts\r\n## In code\r\n```\r\n## After\r"),
+      [1, 2, 3]
+    )
+  })
+
+  it("reads an indented fence, as in a list or an MDX component", () => {
+    assert.deepEqual(
+      fenced("1. Step\n   ```sh\n   pnpm i\n   ```\n2. Next"),
+      [2, 3, 4]
+    )
+  })
+})

package/scripts/lib/package-exports.mjs

@@ -0,0 +1,54 @@
+/**
+ * A package's public entry points, read from its manifest's `exports` the one
+ * way `check-exports.mjs`, `verify-package-artifacts.mjs` and
+ * `verify-typescript-floor.js` share, and the commands its `bin` installs.
+ */
+
+/**
+ * A manifest's `exports` as a map of subpath to target. The sugar forms (a
+ * string, an array, or conditions with no subpath keys) are the root subpath;
+ * a manifest without `exports` has none, and is read through `types`.
+ */
+export function exportsMapOf(manifest) {
+  const { exports } = manifest
+  if (exports === undefined || exports === null) return undefined
+  if (
+    typeof exports === "string" ||
+    Array.isArray(exports) ||
+    !Object.keys(exports).some((key) => key.startsWith("."))
+  ) {
+    return { ".": exports }
+  }
+  return exports
+}
+
+/**
+ * The subpaths a consumer can import: each of the `exports` map but
+ * `./package.json` and one mapped to `null`, which blocks it. A manifest
+ * without `exports` has its root alone.
+ */
+export function publicSubpaths(manifest) {
+  const map = exportsMapOf(manifest)
+  if (map === undefined) return ["."]
+  return Object.entries(map)
+    .filter(
+      ([subpath, target]) => subpath !== "./package.json" && target !== null
+    )
+    .map(([subpath]) => subpath)
+}
+
+/** The specifier that imports `subpath` of the package `name`. */
+export function specifierOf(name, subpath) {
+  return subpath === "." ? name : `${name}/${subpath.replace(/^\.\//, "")}`
+}
+
+/**
+ * The commands a manifest's `bin` installs. A string `bin` installs one,
+ * named after the package without its scope, as npm names it.
+ */
+export function commandsOf(manifest) {
+  const { bin, name = "" } = manifest
+  if (typeof bin === "string") return [name.replace(/^@[^/]+\//, "")]
+  if (bin === null || typeof bin !== "object") return []
+  return Object.keys(bin)
+}

package/scripts/lib/package-exports.test.mjs

@@ -0,0 +1,66 @@
+/**
+ * Tests of the reading of a package's `exports` that `check-exports.mjs`,
+ * `verify-package-artifacts.mjs` and `verify-typescript-floor.js` share.
+ *
+ * Run by `pnpm test:scripts`.
+ */
+import assert from "node:assert/strict"
+import { describe, it } from "node:test"
+import {
+  exportsMapOf,
+  publicSubpaths,
+  specifierOf,
+} from "./package-exports.mjs"
+
+describe("exportsMapOf", () => {
+  it("takes the sugar forms as the root subpath", () => {
+    assert.deepEqual(exportsMapOf({ exports: "./index.js" }), {
+      ".": "./index.js",
+    })
+    assert.deepEqual(
+      exportsMapOf({ exports: { import: "./a.js", default: "./b.js" } }),
+      { ".": { import: "./a.js", default: "./b.js" } }
+    )
+    assert.deepEqual(
+      exportsMapOf({ exports: { ".": "./a.js", "./b": null } }),
+      {
+        ".": "./a.js",
+        "./b": null,
+      }
+    )
+    assert.equal(exportsMapOf({}), undefined)
+  })
+})
+
+describe("publicSubpaths", () => {
+  it("lists the subpaths of the map but ./package.json and a blocked one", () => {
+    assert.deepEqual(
+      publicSubpaths({
+        exports: {
+          ".": "./index.js",
+          "./testing": "./testing.js",
+          "./internal": null,
+          "./package.json": "./package.json",
+        },
+      }),
+      [".", "./testing"]
+    )
+  })
+
+  it("is the root alone for a sugar form or no exports", () => {
+    assert.deepEqual(publicSubpaths({ exports: "./index.js" }), ["."])
+    assert.deepEqual(publicSubpaths({ exports: ["./a.js", "./b.js"] }), ["."])
+    assert.deepEqual(publicSubpaths({ exports: { import: "./a.js" } }), ["."])
+    assert.deepEqual(publicSubpaths({ main: "./index.js" }), ["."])
+  })
+})
+
+describe("specifierOf", () => {
+  it("is the name for the root and the name with the subpath otherwise", () => {
+    assert.equal(specifierOf("@ic-reactor/core", "."), "@ic-reactor/core")
+    assert.equal(
+      specifierOf("@ic-reactor/core", "./testing"),
+      "@ic-reactor/core/testing"
+    )
+  })
+})

package/scripts/lib/release-pr-steps.mjs

@@ -0,0 +1,47 @@
+/**
+ * What `release.js` prints once it has made the release commit: the rest of a
+ * release, which goes through a pull request. A release reaches npm only
+ * through `release.yml`, from a tag on that pull request's merge commit, so
+ * the script itself never pushes, tags or publishes (#969).
+ */
+
+import { LANE_PACKAGES, releaseFor } from "../release-tag.mjs"
+
+/** The lane's packages as prose: "core, react, vite-plugin and mcp". */
+const LANE_IN_WORDS = `${LANE_PACKAGES.slice(0, -1).join(", ")} and ${LANE_PACKAGES.at(-1)}`
+
+/** A new pull request against `main`, the 4.x line and the default branch. */
+const COMPARE_WITH_MAIN = "https://github.com/B3Pay/ic-reactor/compare/main..."
+
+/**
+ * The steps left after the release commit of `version`, as lines to print.
+ *
+ * @param {string} version  the version the release commit sets, such as `4.0.0`
+ * @returns {string}
+ */
+export function releasePrSteps(version) {
+  const { distTag } = releaseFor(version)
+  const branch = `release/v${version}`
+  const tag = `v${version}`
+  // GitHub's merge commit names the branch it merged: "Merge pull request #N
+  // from B3Pay/release/v<version>". A version's dots must match only dots.
+  const mergedFrom = `from B3Pay/${branch.replaceAll(".", "\\.")}$`
+  return [
+    `Nothing is pushed, tagged or published. Release ${tag} through a pull request:`,
+    "",
+    `  1. Move the entries under "## Unreleased" in CHANGELOG.md into a new`,
+    `     "## ${LANE_PACKAGES.join(", ")} ${version}" section below it, and commit that.`,
+    `  2. Push the commits as ${branch}, and open its pull request into main:`,
+    `       git push origin HEAD:refs/heads/${branch}`,
+    `       ${COMPARE_WITH_MAIN}${branch}?expand=1`,
+    `  3. Once it is merged, find its merge commit, then tag that commit and push`,
+    `     that one tag (if the log prints nothing, take the commit from the pull`,
+    `     request's page):`,
+    `       git fetch origin main`,
+    `       git log origin/main --first-parent --merges -1 --format='%H %s' --grep='${mergedFrom}'`,
+    `       git tag -a ${tag} -m "ic-reactor ${version}" <merge-commit>`,
+    `       git push origin ${tag}`,
+    `     release.yml checks the tag, waits for approval on npm-publish, and`,
+    `     publishes ${LANE_IN_WORDS} under the ${distTag} dist-tag.`,
+  ].join("\n")
+}

package/scripts/release-tag.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * What a release of this line publishes, from its version or its tag.
+ *
+ * `main` releases the packages of `LANE_PACKAGES` (`@ic-reactor/core`,
+ * `@ic-reactor/react`, `@ic-reactor/vite-plugin` and `@ic-reactor/mcp`) in
+ * lockstep, at 4.x only: the 3.x line has its own lane on the `v3` branch. A
+ * stable version goes to npm's `latest` dist-tag and becomes the repository's
+ * latest GitHub Release; a prerelease goes to `beta` and never to `latest`.
+ * Anything else is refused, so a 3.x or 5.x tag pushed here publishes nothing.
+ *
+ * `.github/workflows/release.yml` runs this as a command on the tag, and
+ * `scripts/release.js` imports it, so the two cannot disagree about a version.
+ *
+ * Usage: node scripts/release-tag.mjs v4.0.0
+ * Prints `version=`, `dist_tag=`, `prerelease=` and `make_latest=` lines (the
+ * `$GITHUB_OUTPUT` format), or exits 1 with the reason on stderr.
+ */
+import { realpathSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+
+/** The only major this line releases. */
+export const RELEASE_MAJOR = 4
+
+/**
+ * The packages of the lane, as directories under `packages/`, in the order
+ * `release.yml` publishes them: core first, since react and mcp depend on it,
+ * and mcp, the newest, last, so that a first publish of it that fails leaves
+ * the other three released. `scripts/release.js` bumps them, and `release.yml`
+ * checks, packs and publishes them. Its publish job checks nothing out, so the
+ * workflow names them itself, and `scripts/release-workflow.test.mjs` holds
+ * each of its lists to this one.
+ */
+export const LANE_PACKAGES = Object.freeze([
+  "core",
+  "react",
+  "vite-plugin",
+  "mcp",
+])
+
+// No build metadata: npm drops `+build` from the version it publishes, so the
+// tag, the manifests and the registry would disagree.
+const VERSION =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?$/
+
+/**
+ * @param {string} versionOrTag `4.0.0`, `v4.0.0-beta.2`, ...
+ * @returns {{ version: string, prerelease: boolean, distTag: "latest" | "beta", makeLatest: boolean }}
+ * @throws {Error} for anything that is not a 4.x semver version
+ */
+export function releaseFor(versionOrTag) {
+  const version = String(versionOrTag ?? "").replace(/^v/, "")
+  const match = VERSION.exec(version)
+  if (!match) {
+    throw new Error(
+      `${versionOrTag} is not a release version (MAJOR.MINOR.PATCH, with an optional -prerelease and no +build).`
+    )
+  }
+  if (Number(match[1]) !== RELEASE_MAJOR) {
+    throw new Error(
+      `${versionOrTag} is not a ${RELEASE_MAJOR}.x version. This lane releases ${RELEASE_MAJOR}.x only; 3.x security releases are tagged from the v3 branch with its own workflows.`
+    )
+  }
+  const prerelease = match[4] !== undefined
+  return {
+    version,
+    prerelease,
+    distTag: prerelease ? "beta" : "latest",
+    makeLatest: !prerelease,
+  }
+}
+
+function isMain() {
+  try {
+    return (
+      realpathSync(process.argv[1]) ===
+      realpathSync(fileURLToPath(import.meta.url))
+    )
+  } catch {
+    return false
+  }
+}
+
+if (isMain()) {
+  try {
+    const release = releaseFor(process.argv[2])
+    console.log(`version=${release.version}`)
+    console.log(`dist_tag=${release.distTag}`)
+    console.log(`prerelease=${release.prerelease}`)
+    console.log(`make_latest=${release.makeLatest}`)
+  } catch (error) {
+    console.error(`::error::${error.message}`)
+    process.exit(1)
+  }
+}