@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/scripts/test-examples-published.mjs

@@ -0,0 +1,1585 @@
+#!/usr/bin/env node
+/**
+ * Runs every example against the @ic-reactor/* packages published on npm, the
+ * way someone who copies the example out of this repository gets them, and the
+ * way StackBlitz installs it.
+ *
+ * The examples job of CI runs the examples inside the workspace, where
+ * `linkWorkspacePackages` links each @ic-reactor/* range to packages/*. That
+ * proves the examples against the code on the branch, not against the release:
+ * an example that uses a name the published release lacks stays green there.
+ * This script tests against one dist-tag per run (see `resolveRun`): `beta`
+ * for a prerelease and `latest` for a stable release, of the `--wait-for`
+ * version or else of the branch's own. A run without `--wait-for` whose
+ * examples all wait on the branch's own, unpublished version (a release pull
+ * request, or its merge before the tag: `awaitsRelease`) runs only the checks
+ * that need no registry (`staticFindings`) and defers to the release's run.
+ * For each example, it:
+ *
+ *   1. copies its git-tracked files to a directory outside the repository,
+ *      and refuses to run if a parent of that directory holds a node_modules
+ *      or a package.json (Node, Vite and vitest resolve a bare import by
+ *      walking up into a parent's node_modules, so an undeclared import would
+ *      be found there);
+ *   2. refuses a `workspace:`, `file:`, `link:` or `portal:` range, which no
+ *      standalone install resolves, and a tracked `.npmrc` (it could point the
+ *      @ic-reactor scope at another registry, for this install and on
+ *      StackBlitz); requires the `typecheck`, `test` and `build` scripts; and
+ *      checks each @ic-reactor/* range is satisfied by the version the run's
+ *      dist-tag names (asking npm, so its own semver decides);
+ *   3. installs from registry.npmjs.org with npm (no workspace, no links, no
+ *      lockfile of ours), the default registry and the @ic-reactor and
+ *      @meantjs scopes all pinned to it on the command line, over any
+ *      `.npmrc`, with an environment that holds nothing of the repository: no
+ *      `npm_*` or `pnpm_*` variable a `pnpm run` set, and no PATH entry
+ *      inside the repository;
+ *   4. checks every installed @ic-reactor/* package is a real directory, not
+ *      a symlink, at exactly that version, and that npm's lockfile
+ *      records it as the registry's own tarball, with the integrity the
+ *      registry publishes for that version (the proof the bytes are the
+ *      published ones);
+ *   5. runs the example's `typecheck`, `test` and `build` scripts, as the
+ *      examples job does (a Next example gets the same `next-env.d.ts` shim
+ *      `typecheck-examples.js` writes);
+ *   6. runs the `startCommand` of its `.stackblitzrc`, the command StackBlitz
+ *      runs after its install, under a model of what StackBlitz's WebContainer
+ *      lacks (WEBCONTAINER_MODEL: no global `Iterator`, and an
+ *      AsyncLocalStorage that keeps no store past the synchronous part of
+ *      `run()`): `npm run dev [-- <args>]` is started, its first page fetched
+ *      with every same-origin script on it and every app module those import
+ *      (a TanStack Start example's from its router and route tree as well:
+ *      `startEntrySeeds`), and the server stopped (a Next example with
+ *      `NEXT_TEST_WASM=1`, so Next
+ *      loads the WebAssembly bindings a WebContainer loads); any other command
+ *      must exit 0, a script step 5 already ran on plain Node included.
+ *
+ * Every example's tests run without a replica (each is a `createTestClient()`
+ * over an in-memory one), so nothing here starts a network. The vite-wallet
+ * example needs icp-cli's local network to run the wallet itself, which is why
+ * its `.stackblitzrc` runs its tests instead of its dev server. next-ssr's
+ * runs its tests too: Next 16 renders no page in a WebContainer (see
+ * WEBCONTAINER_MODEL).
+ *
+ * Usage: node scripts/test-examples-published.mjs [--keep] [--tmp <dir>]
+ *          [--wait-for <version>] [<example> ...]
+ *   --keep                 leave the copies on disk and print where they are
+ *   --tmp <dir>            make the copies under <dir> (default: the OS tmpdir)
+ *   --wait-for <version>   wait (up to 10 minutes) until the dist-tag the
+ *                          release of <version> publishes under (`beta` for a
+ *                          prerelease, `latest` for a stable version) of core
+ *                          and of every @ic-reactor/* package the examples
+ *                          declare names <version> (a leading "v" is
+ *                          dropped), and the registry serves its integrity
+ *                          and its tarball: the release workflow runs this
+ *                          right after publishing, with the tag it published.
+ *                          Without it, the run tests the dist-tag of the
+ *                          branch's version (packages/core/package.json), or
+ *                          defers while the examples wait on that version's
+ *                          release
+ *   <example>              a directory under examples/ (default: every one)
+ */
+import { execFileSync, spawn, spawnSync } from "node:child_process"
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { createServer } from "node:net"
+import { tmpdir } from "node:os"
+import { delimiter, dirname, join, relative, resolve, sep } from "node:path"
+import { setTimeout as sleep } from "node:timers/promises"
+import { fileURLToPath } from "node:url"
+
+import { discoverExampleDirs, root as repoRoot } from "./example-projects.js"
+
+/** Where every install and every `npm view` goes, whatever ~/.npmrc says. */
+export const REGISTRY = "https://registry.npmjs.org/"
+
+/** The packages this repository publishes. */
+export const SCOPE = "@ic-reactor/"
+
+/** A version, or a tag of one: MAJOR.MINOR.PATCH, an optional -prerelease. */
+const RELEASE_VERSION =
+  /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+
+/**
+ * The dist-tag a run tests against.
+ *
+ * With `--wait-for`, the one the release of that version publishes under:
+ * `beta` for a prerelease (a `-` part after MAJOR.MINOR.PATCH, with or without
+ * a leading `v`), `latest` for a stable version. This mirrors the rule of
+ * `releaseFor` in scripts/release-tag.mjs, with which release.yml chooses the
+ * dist-tag it publishes under once the GA flip (#836) brings that file; the
+ * rule is repeated here rather than imported, so this script works with or
+ * without it.
+ *
+ * A run without `--wait-for` (push, pull request, weekly, manual) passes the
+ * branch's own version instead (see `resolveRun`), so it gets the tag of the
+ * branch's last release. With no value at all, `latest`.
+ *
+ * @param {string | undefined} waitFor the `--wait-for` value (or the
+ *   branch's version), if any
+ * @returns {"latest" | "beta"}
+ * @throws {Error} when `waitFor` is not a version
+ */
+export function distTagFor(waitFor) {
+  if (waitFor === undefined) return "latest"
+  const match = RELEASE_VERSION.exec(waitFor)
+  if (!match) {
+    throw new Error(
+      `--wait-for ${waitFor} is not a release version (MAJOR.MINOR.PATCH, with an optional -prerelease and no +build).`
+    )
+  }
+  return match[4] === undefined ? "latest" : "beta"
+}
+
+/** Range protocols that only resolve inside a workspace or on one disk. */
+export const LOCAL_PROTOCOLS = ["workspace:", "file:", "link:", "portal:"]
+
+/**
+ * The scopes pinned to REGISTRY on every npm command. `--registry` replaces
+ * only the default registry: a `@scope:registry=` setting in any `.npmrc`
+ * (the user's, or one in the project) still wins for its scope.
+ */
+export const PINNED_SCOPES = ["@ic-reactor", "@meantjs"]
+
+/** The registry flags of every npm command this script runs. */
+export const REGISTRY_ARGS = [
+  `--registry=${REGISTRY}`,
+  ...PINNED_SCOPES.map((scope) => `--${scope}:registry=${REGISTRY}`),
+]
+
+/** The scripts every example must have: what the examples job runs. */
+export const REQUIRED_SCRIPTS = ["typecheck", "test", "build"]
+
+/**
+ * Examples allowed to lack one of REQUIRED_SCRIPTS: { example: { script:
+ * reason } }. Empty: all five have all three.
+ */
+export const SCRIPT_EXCEPTIONS = {}
+
+const DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+]
+
+/** Same shim as typecheck-examples.js: `next build` writes the real one. */
+const NEXT_ENV = `/// <reference types="next" />\n/// <reference types="next/image-types/global" />\n`
+
+const MINUTE = 60_000
+
+/**
+ * A model of what StackBlitz's WebContainer lacks, as the examples' start
+ * commands met it there (its `node --version` says v22.22.3), for a preload
+ * that `--require` puts into every Node process the start command starts:
+ *
+ * - No global `Iterator`: `typeof Iterator` is "undefined" there, though Node
+ *   22 defines it. jsdom 30.1 subclasses it, so all of vite-wallet's test
+ *   files failed to start there with "ReferenceError: Iterator is not
+ *   defined"; the examples pin jsdom 30.0.1.
+ * - An AsyncLocalStorage whose store is gone once `run()` returns, and so
+ *   after any await: StackBlitz says WebContainer does not implement
+ *   AsyncLocalStorage (stackblitz/starters#122), and next-ssr's `next dev`
+ *   answered 500 there with "Invariant: Expected workStore to be
+ *   initialized". Under the model `next dev` fails with the same stack, and
+ *   `next build --webpack` fails at its first prerender.
+ *
+ * Under this model each of the two failures happens here as it did on
+ * StackBlitz, and what worked there (icrc-ledger's dev server, node-agent-tool's
+ * demo) still works. It is the two gaps the examples have met, not a
+ * WebContainer: a start command green under it can still meet another one.
+ */
+export const WEBCONTAINER_MODEL = `"use strict"
+// Written by scripts/test-examples-published.mjs: see WEBCONTAINER_MODEL there.
+delete globalThis.Iterator
+class AsyncLocalStorage {
+  #store = undefined
+  getStore() {
+    return this.#store
+  }
+  run(store, fn, ...args) {
+    const outer = this.#store
+    this.#store = store
+    try {
+      return fn(...args)
+    } finally {
+      this.#store = outer
+    }
+  }
+  exit(fn, ...args) {
+    return this.run(undefined, fn, ...args)
+  }
+  enterWith(store) {
+    this.#store = store
+  }
+  disable() {
+    this.#store = undefined
+  }
+  static bind(fn) {
+    return fn
+  }
+  static snapshot() {
+    return (fn, ...args) => fn(...args)
+  }
+}
+Object.defineProperty(require("node:async_hooks"), "AsyncLocalStorage", {
+  value: AsyncLocalStorage,
+  writable: true,
+  enumerable: true,
+  configurable: true,
+})
+require("node:module").syncBuiltinESMExports()
+`
+
+/**
+ * `env` with the preload at `preload` (WEBCONTAINER_MODEL) added to
+ * NODE_OPTIONS, which every Node process the start command starts inherits:
+ * vitest's workers and Next's servers included.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} preload
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function webContainerEnv(env, preload) {
+  const option = `--require ${JSON.stringify(preload)}`
+  return {
+    ...env,
+    NODE_OPTIONS: env.NODE_OPTIONS ? `${env.NODE_OPTIONS} ${option}` : option,
+  }
+}
+
+/**
+ * Every dependency a manifest declares, with the field it is declared in.
+ *
+ * @param {Record<string, any>} manifest
+ * @returns {{ field: string, name: string, range: string }[]}
+ */
+export function declaredDependencies(manifest) {
+  return DEPENDENCY_FIELDS.flatMap((field) =>
+    Object.entries(manifest[field] ?? {}).map(([name, range]) => ({
+      field,
+      name,
+      range: String(range),
+    }))
+  )
+}
+
+/**
+ * What stops this manifest from installing standalone against the version
+ * `tag` names on npm (`version`). `satisfying(name, range)` resolves with the
+ * published versions of `name` the range accepts (npm's answer, in the
+ * script).
+ *
+ * @param {Record<string, any>} manifest
+ * @param {{
+ *   tag: string,
+ *   version: string,
+ *   satisfying: (name: string, range: string) => Promise<string[]> | string[],
+ * }} options
+ * @returns {Promise<string[]>}
+ */
+export async function checkManifest(manifest, { tag, version, satisfying }) {
+  const findings = []
+  for (const { field, name, range } of declaredDependencies(manifest)) {
+    const protocol = LOCAL_PROTOCOLS.find((p) => range.startsWith(p))
+    if (protocol) {
+      findings.push(
+        `${field}.${name} is "${range}": a ${protocol} range resolves only inside this repository, never in a standalone install or on StackBlitz`
+      )
+      continue
+    }
+    if (!name.startsWith(SCOPE)) continue
+    const versions = await satisfying(name, range)
+    if (!versions.includes(version)) {
+      findings.push(
+        `${field}.${name} is "${range}", which ${tag} (${version}) does not satisfy` +
+          (versions.length > 0
+            ? `: npm would install ${versions.at(-1)}`
+            : ": no published version satisfies it")
+      )
+    }
+  }
+  return findings
+}
+
+/**
+ * Whether the examples wait on a release that is not published yet, so that
+ * a run without `--wait-for` has nothing it can test. That is so when the
+ * branch's own version (`packages/core/package.json`, which `release.js`
+ * bumps, syncing every example to `^<version>`) is not among the registry's
+ * versions, and every @ic-reactor/* range of every example is exactly
+ * `^<version>`: a release pull request, or its merge before the tag publishes
+ * it. No published version can satisfy those ranges yet, and `release.yml`'s
+ * `examples-published` job tests the examples with `--wait-for` once the
+ * release is out. Any other range is checked as usual and fails as usual, and
+ * so does a local protocol (`workspace:`, `file:` …) on any dependency of any
+ * example, @ic-reactor or not: no deferral skips that check.
+ *
+ * @param {Record<string, any>[]} manifests the examples' package.json files
+ * @param {{ branchVersion: string | undefined, publishedVersions: string[] }} state
+ * @returns {boolean}
+ */
+export function awaitsRelease(manifests, { branchVersion, publishedVersions }) {
+  if (!branchVersion || publishedVersions.includes(branchVersion)) return false
+  // A local protocol on any dependency, not only an @ic-reactor one, is what
+  // checkManifest refuses without asking the registry: never defer past it.
+  const local = manifests.some((manifest) =>
+    declaredDependencies(manifest).some(({ range }) =>
+      LOCAL_PROTOCOLS.some((protocol) => range.startsWith(protocol))
+    )
+  )
+  if (local) return false
+  // Every example must wait on the release itself: one with no @ic-reactor
+  // range, or any other range, can be tested now and is not deferred.
+  return (
+    manifests.length > 0 &&
+    manifests.every((manifest) => {
+      const ranges = declaredDependencies(manifest)
+        .filter(({ name }) => name.startsWith(SCOPE))
+        .map(({ range }) => range)
+      return (
+        ranges.length > 0 &&
+        ranges.every((range) => range === `^${branchVersion}`)
+      )
+    })
+  )
+}
+
+/**
+ * The @ic-reactor/* packages installed in `projectDir`, and what is wrong with
+ * them: one the manifest declares that is missing, a symlink (a link into a
+ * workspace, not a package from the registry), or a version other than
+ * `expectedVersion`, the one `tag` names.
+ *
+ * @param {string} projectDir
+ * @param {string[]} declared the @ic-reactor/* names the manifest declares
+ * @param {string} expectedVersion
+ * @param {string} tag the dist-tag that names `expectedVersion`
+ * @returns {{ installed: { name: string, version: string }[], findings: string[] }}
+ */
+export function checkInstalled(projectDir, declared, expectedVersion, tag) {
+  const scopeDir = join(projectDir, "node_modules", SCOPE.slice(0, -1))
+  const present = existsSync(scopeDir)
+    ? readdirSync(scopeDir).map((entry) => `${SCOPE}${entry}`)
+    : []
+  const names = [...new Set([...declared, ...present])].sort()
+  const installed = []
+  const findings = []
+  for (const name of names) {
+    const dir = join(projectDir, "node_modules", name)
+    let stat
+    try {
+      stat = lstatSync(dir)
+    } catch {
+      findings.push(`${name} is declared but not installed`)
+      continue
+    }
+    if (stat.isSymbolicLink()) {
+      findings.push(
+        `${name} is a symlink (to ${realpathSync(dir)}), not a package installed from the registry`
+      )
+      continue
+    }
+    if (!stat.isDirectory()) {
+      findings.push(`${name} is not a directory`)
+      continue
+    }
+    let version
+    try {
+      version = JSON.parse(
+        readFileSync(join(dir, "package.json"), "utf8")
+      ).version
+    } catch {
+      findings.push(`${name} has no readable package.json`)
+      continue
+    }
+    installed.push({ name, version })
+    if (version !== expectedVersion) {
+      findings.push(
+        `${name} installed at ${version}, not ${expectedVersion} (${tag})`
+      )
+    }
+  }
+  return { installed, findings }
+}
+
+/** The @ic-reactor/* entries of a lockfile's `packages`, nested ones too. */
+export function lockedScopePackages(lock) {
+  const scope = SCOPE.slice(0, -1)
+  return Object.entries(lock?.packages ?? {})
+    .map(([path, entry]) => {
+      const match = path.match(/(?:^|\/)node_modules\/(@[^/]+\/[^/]+)$/)
+      return match && match[1].startsWith(`${scope}/`)
+        ? { path, name: match[1], entry }
+        : undefined
+    })
+    .filter(Boolean)
+}
+
+/**
+ * What shows that an @ic-reactor/* package npm installed is not the registry's
+ * published tarball: a lockfile entry that is a link, whose `resolved` is not
+ * the tarball the registry names for that version, or whose `integrity` is not
+ * the one it publishes. Also an installed package the lockfile does not
+ * record. `published` is the registry's `dist` for each name at the version
+ * under test.
+ *
+ * @param {Record<string, any> | undefined} lock package-lock.json
+ * @param {{
+ *   installed: string[],
+ *   published: Record<string, { tarball: string, integrity: string }>,
+ * }} options
+ * @returns {string[]}
+ */
+export function checkLockfile(lock, { installed, published }) {
+  if (!lock || typeof lock.packages !== "object") {
+    return [
+      "npm wrote no package-lock.json with a `packages` map, so where the @ic-reactor/* packages came from is unproven",
+    ]
+  }
+  const findings = []
+  const entries = lockedScopePackages(lock)
+  for (const name of installed) {
+    if (!entries.some((e) => e.path === `node_modules/${name}`)) {
+      findings.push(
+        `${name} is installed but package-lock.json does not record it`
+      )
+    }
+  }
+  for (const { path, name, entry } of entries) {
+    const dist = published[name]
+    if (entry.link) {
+      findings.push(
+        `${path} is a link (to ${entry.resolved}) in package-lock.json, not a tarball from the registry`
+      )
+      continue
+    }
+    if (!dist) {
+      findings.push(
+        `${path} is ${entry.version}: the registry's tarball for it was not looked up`
+      )
+      continue
+    }
+    if (entry.resolved !== dist.tarball || !dist.tarball.startsWith(REGISTRY)) {
+      findings.push(
+        `${path} was resolved from ${entry.resolved ?? "nowhere"}, not ${dist.tarball}`
+      )
+    }
+    if (entry.integrity !== dist.integrity) {
+      findings.push(
+        `${path} has integrity ${entry.integrity ?? "(none)"}, not the registry's ${dist.integrity}`
+      )
+    }
+  }
+  return findings
+}
+
+/**
+ * The example's tracked files that change how npm resolves its packages: a
+ * `.npmrc` can point a scope at another registry, for the install here and
+ * for StackBlitz's.
+ *
+ * @param {string[]} files paths relative to the example
+ * @returns {string[]}
+ */
+export function trackedConfigFindings(files) {
+  return files
+    .filter((file) => file.split("/").at(-1) === ".npmrc")
+    .map(
+      (file) =>
+        `${file} is tracked: an example's .npmrc could point @ic-reactor/* at another registry, here and on StackBlitz, so none is allowed`
+    )
+}
+
+/**
+ * Whether `scripts` defines `name` as npm runs it: a non-empty string. npm
+ * skips any other value, and `npm run <name>` then fails with "Missing script".
+ *
+ * @param {Record<string, unknown> | undefined} scripts
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function definesScript(scripts, name) {
+  const value =
+    scripts && Object.hasOwn(scripts, name) ? scripts[name] : undefined
+  return typeof value === "string" && value.trim() !== ""
+}
+
+/**
+ * The required scripts an example lacks (a script is defined only as a
+ * non-empty string: `definesScript`), unless `exceptions` names them.
+ *
+ * @param {string} example
+ * @param {Record<string, string> | undefined} scripts
+ * @param {Record<string, Record<string, string>>} [exceptions]
+ * @returns {string[]}
+ */
+export function requiredScriptFindings(
+  example,
+  scripts,
+  exceptions = SCRIPT_EXCEPTIONS
+) {
+  return REQUIRED_SCRIPTS.filter(
+    (script) =>
+      !definesScript(scripts, script) && !exceptions[example]?.[script]
+  ).map(
+    (script) =>
+      `package.json has no "${script}" script: every example runs typecheck, test and build here (an exception goes in SCRIPT_EXCEPTIONS, with its reason)`
+  )
+}
+
+/**
+ * The parents of `dir` holding a node_modules or a package.json, from which
+ * Node, Vite or vitest would resolve an import the example does not declare.
+ * Walks up to the filesystem root, or to `stopAt` (included).
+ *
+ * @param {string} dir
+ * @param {{ stopAt?: string }} [options]
+ * @returns {string[]}
+ */
+export function ancestorFindings(dir, { stopAt } = {}) {
+  const findings = []
+  let current = resolve(dir)
+  const last = stopAt === undefined ? undefined : resolve(stopAt)
+  while (current !== last) {
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+    for (const entry of ["node_modules", "package.json"]) {
+      if (existsSync(join(current, entry))) {
+        findings.push(
+          `${join(current, entry)} is above the scratch directory: an import the example does not declare would resolve there (pass --tmp <dir> with no node_modules or package.json above it)`
+        )
+      }
+    }
+  }
+  return findings
+}
+
+/**
+ * A child environment that holds nothing of this repository. A `pnpm run`
+ * sets `npm_*` variables (the workspace's config and package among them) and
+ * puts the repository's `node_modules/.bin` on PATH, where a binary the
+ * example failed to install would still be found.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} root the repository root
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function isolatedEnv(env, root) {
+  const inside = (entry) => {
+    const rel = relative(root, resolve(entry))
+    return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep))
+  }
+  const out = {}
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined) continue
+    if (/^(npm|pnpm)_/i.test(key)) continue
+    if (["NODE_PATH", "INIT_CWD", "PNPM_SCRIPT_SRC_DIR"].includes(key)) continue
+    out[key] = value
+  }
+  out.PATH = (env.PATH ?? "")
+    .split(delimiter)
+    .filter((entry) => entry && !inside(entry))
+    .join(delimiter)
+  out.npm_config_registry = REGISTRY
+  out.npm_config_update_notifier = "false"
+  return out
+}
+
+/**
+ * The checks that need no registry, for one example: its tracked config files
+ * (`trackedConfigFindings`), its required scripts (`requiredScriptFindings`)
+ * and its `.stackblitzrc` start command (`stackblitzStartCommand`'s finding,
+ * and the npm script it names: `startScriptFindings`).
+ * `testExample` runs them on the copy before installing, and `deferredRun`
+ * runs them on the checkout when a run defers to the release
+ * (`awaitsRelease`), so a deferral never skips them.
+ *
+ * @param {string} name the example
+ * @param {{ files: string[], scripts: Record<string, string> | undefined, start: { finding?: string } }} example
+ * @returns {string[]}
+ */
+export function staticFindings(name, { files, scripts, start }) {
+  return [
+    ...trackedConfigFindings(files),
+    ...requiredScriptFindings(name, scripts),
+    ...(start.finding ? [start.finding] : []),
+    ...startScriptFindings(start.command, { files, scripts }),
+  ]
+}
+
+/**
+ * A start command must be a plain npm script command, `npm run <script>`
+ * (or `npm run-script`, or a bare lifecycle command: `npm test`/`npm t`,
+ * `npm start`, `npm stop`, `npm restart`), optionally with
+ * arguments after a bare `--`, naming a script the example defines. npm's one
+ * default, `npm start` with no `start` script, runs `node server.js`, so it
+ * passes when `server.js` is tracked. Anything else is refused, npm options
+ * (`--loglevel=silent`) and other programs (`node x.js`, `npx vite`)
+ * included: this checks the command without running it, so it accepts only
+ * the form it can check (it fails closed).
+ *
+ * @param {string | undefined} command the `.stackblitzrc` start command
+ * @param {{ files: string[], scripts: Record<string, string> | undefined }} example
+ * @returns {string[]}
+ */
+export function startScriptFindings(command, { files, scripts }) {
+  if (!command) return []
+  const parsed = parseNpmCommand(command)
+  if (!parsed) {
+    return [
+      `.stackblitzrc's start command "${command}" is not a plain npm script command: write it as "npm run <script>" (arguments after a bare "--"), so its script can be checked`,
+    ]
+  }
+  if (definesScript(scripts, parsed.script)) return []
+  if (parsed.script === "start" && files.includes("server.js")) return []
+  return [
+    `.stackblitzrc's start command "${command}" runs the npm script "${parsed.script}", which package.json does not define`,
+  ]
+}
+
+/**
+ * The command StackBlitz runs after installing, from `.stackblitzrc`.
+ *
+ * @param {string} projectDir
+ * @returns {{ command?: string, finding?: string }}
+ */
+export function stackblitzStartCommand(projectDir) {
+  const file = join(projectDir, ".stackblitzrc")
+  if (!existsSync(file)) {
+    return {
+      finding:
+        ".stackblitzrc is missing: StackBlitz's own choice of start command is not checked here, so each example names its own",
+    }
+  }
+  let config
+  try {
+    config = JSON.parse(readFileSync(file, "utf8"))
+  } catch (error) {
+    return { finding: `.stackblitzrc is not JSON: ${error.message}` }
+  }
+  if (typeof config.startCommand !== "string" || !config.startCommand.trim()) {
+    return { finding: ".stackblitzrc has no startCommand string" }
+  }
+  return { command: config.startCommand.trim() }
+}
+
+/**
+ * npm's bare commands that run the package script of the same name: the
+ * lifecycle scripts, and `t` for `test`. Any other script runs only as
+ * `npm run <script>`: `npm dev` is an unknown command to npm.
+ */
+const NPM_LIFECYCLE_COMMANDS = {
+  test: "test",
+  t: "test",
+  start: "start",
+  stop: "stop",
+  restart: "restart",
+}
+
+/**
+ * The package script a start command runs, and the arguments it passes after
+ * `--`. `npm run <script>` (or `npm run-script`) for any script, and the bare
+ * lifecycle commands (`npm test`, `npm t`, `npm start`, `npm stop`, `npm
+ * restart`) for theirs; `npm test` and `npm run test` are the same script.
+ * A script name is any unquoted word not starting with `-` (an npm option):
+ * `npm run dev.web` names `dev.web`. Anything else, `npm dev` included, is
+ * not a script command.
+ *
+ * @param {string} command
+ * @returns {{ script: string, args: string[] } | undefined}
+ */
+export function parseNpmCommand(command) {
+  const match = command.match(
+    /^npm\s+(?:(run(?:-script)?)\s+)?([^\s-]\S*)(?:\s+--((?:\s+\S+)*))?\s*$/
+  )
+  if (!match) return undefined
+  const [, run, name, rest] = match
+  if (name === "run" || name === "run-script") return undefined
+  const script = run ? name : NPM_LIFECYCLE_COMMANDS[name]
+  if (!script) return undefined
+  const args = (rest ?? "").split(/\s+/).filter(Boolean)
+  return { script, args }
+}
+
+/**
+ * The same-origin scripts a page loads, as absolute URLs, each with whether it
+ * is an ES module (`type="module"`).
+ *
+ * @param {string} html
+ * @param {string} pageUrl
+ * @returns {{ url: string, module: boolean }[]}
+ */
+export function pageScripts(html, pageUrl) {
+  const origin = new URL(pageUrl).origin
+  const seen = new Set()
+  const scripts = []
+  for (const match of html.matchAll(/<script\b([^>]*)>/gi)) {
+    const src = match[1].match(/\bsrc="([^"]+)"/i)?.[1]
+    if (!src) continue
+    const url = new URL(src.replaceAll("&amp;", "&"), pageUrl)
+    if (url.origin !== origin || seen.has(url.href)) continue
+    seen.add(url.href)
+    scripts.push({
+      url: url.href,
+      module: /\btype=["']?module\b/i.test(match[1]),
+    })
+  }
+  return scripts
+}
+
+/**
+ * The app modules an ES module served by a Vite dev server imports, as
+ * absolute URLs: its static `import`/`export ... from` and string `import()`
+ * specifiers on its own origin. A statement starts a line or follows a `;`:
+ * Vite joins its HMR preamble and the module's first statement onto one line
+ * (`... from "/@vite/client";import { A } from "/src/A.tsx";`). Only
+ * root-relative specifiers are taken: Vite serves every import it resolved as
+ * one (`/src/...`), so a relative one left in served code is text in a string
+ * or a comment (a code sample in a template literal), not an import.
+ * Pre-bundled dependencies (`/node_modules/`) and the dev server's own modules
+ * (`/@vite/client`, `/@id/...`, `/@fs/...`) are left out: they are not the
+ * example's code, and a dependency re-optimisation could answer them 504
+ * while it runs.
+ *
+ * @param {string} code
+ * @param {string} moduleUrl
+ * @returns {string[]}
+ */
+export function moduleImports(code, moduleUrl) {
+  const origin = new URL(moduleUrl).origin
+  const specifiers = [
+    ...code.matchAll(
+      /(?:^|;)[ \t]*(?:import|export)[ \t\n{*][^'"`;]*?\bfrom[ \t]*["']([^"'\n]+)["']/gm
+    ),
+    ...code.matchAll(/(?:^|;)[ \t]*import[ \t]*["']([^"'\n]+)["']/gm),
+    ...code.matchAll(/\bimport\([ \t]*["']([^"'\n]+)["'][ \t]*\)/g),
+  ].map((match) => match[1])
+  const urls = new Set()
+  for (const specifier of specifiers) {
+    if (!specifier.startsWith("/")) continue
+    const url = new URL(specifier, moduleUrl)
+    if (url.origin !== origin) continue
+    if (/^\/(?:node_modules\/|@)/.test(url.pathname)) continue
+    urls.add(url.href)
+  }
+  return [...urls]
+}
+
+/**
+ * The app's own entry modules of a TanStack Start example, from which the walk
+ * also starts: its router (what `#tanstack-router-entry` resolves to) and the
+ * route tree TanStack Router generates. Each is seeded only when the example
+ * tracks it.
+ */
+export const START_ENTRY_FILES = [
+  "src/router.tsx",
+  "src/router.ts",
+  "src/router.jsx",
+  "src/router.js",
+  "src/routeTree.gen.ts",
+]
+
+/**
+ * The modules the walk also starts from when the page's scripts are a TanStack
+ * Start dev entry (a `/@id/virtual:tanstack-start-*` URL): that entry reaches
+ * the app only through @tanstack/react-start's own modules under `/@fs/`,
+ * which `moduleImports` leaves out, so without a seed not one module of the
+ * example's would be fetched. The seeds are START_ENTRY_FILES the example
+ * tracks, as URLs on the page's origin; a finding when it tracks none. No
+ * seeds for any other page.
+ *
+ * @param {{ url: string }[]} scripts the page's scripts (`pageScripts`)
+ * @param {string[]} files the example's tracked files, relative to it
+ * @returns {{ seeds: string[], finding?: string }}
+ */
+export function startEntrySeeds(scripts, files) {
+  const entry = scripts.find(({ url }) =>
+    new URL(url).pathname.startsWith("/@id/virtual:tanstack-start-")
+  )
+  if (!entry) return { seeds: [] }
+  const seeds = START_ENTRY_FILES.filter((file) => files.includes(file)).map(
+    (file) => new URL(`/${file}`, entry.url).href
+  )
+  if (seeds.length > 0) return { seeds }
+  return {
+    seeds,
+    finding: `the page's script ${entry.url} is TanStack Start's dev entry, which reaches the app only through /@fs/, and the example tracks none of ${START_ENTRY_FILES.join(", ")} to start the walk from`,
+  }
+}
+
+/** `npm view <spec> <field> --json`, from the registry; undefined on E404. */
+function npmView(spec, field) {
+  const result = spawnSync(
+    "npm",
+    ["view", spec, field, "--json", ...REGISTRY_ARGS],
+    { encoding: "utf8", env: isolatedEnv(process.env, repoRoot) }
+  )
+  if (result.status !== 0) {
+    if (/E404/.test(result.stdout + result.stderr)) return undefined
+    throw new Error(
+      `npm view ${spec} ${field} failed: ${result.stderr || result.stdout}`
+    )
+  }
+  return result.stdout.trim() ? JSON.parse(result.stdout) : undefined
+}
+
+/** The version a dist-tag names, from the registry. */
+function distTagVersion(name, tag, view = npmView) {
+  const version = view(`${name}@${tag}`, "version")
+  if (typeof version !== "string") {
+    throw new Error(`${name} has no ${tag} dist-tag on ${REGISTRY}`)
+  }
+  return version
+}
+
+/** The published versions of `name` that `range` accepts, from the registry. */
+function npmSatisfying(name, range) {
+  const parsed = npmView(`${name}@${range}`, "version")
+  if (parsed === undefined) return []
+  return Array.isArray(parsed) ? parsed : [parsed]
+}
+
+/** The registry's tarball URL and integrity for each name at `version`. */
+function publishedDist(names, version) {
+  const out = {}
+  for (const name of names) {
+    const dist = npmView(`${name}@${version}`, "dist")
+    if (dist?.tarball && dist?.integrity) {
+      out[name] = { tarball: dist.tarball, integrity: dist.integrity }
+    }
+  }
+  return out
+}
+
+/** The example's git-tracked files, relative to it. */
+function trackedFiles(name) {
+  const prefix = `examples/${name}`
+  return execFileSync("git", ["-C", repoRoot, "ls-files", "-z", "--", prefix], {
+    encoding: "utf8",
+  })
+    .split("\0")
+    .filter(Boolean)
+    .map((file) => relative(prefix, file))
+}
+
+/** Copies the example's git-tracked files to `dest`. */
+function copyTracked(name, files, dest) {
+  const prefix = join(repoRoot, "examples", name)
+  for (const file of files) {
+    const source = join(prefix, file)
+    if (!existsSync(source)) continue
+    const target = join(dest, file)
+    mkdirSync(dirname(target), { recursive: true })
+    copyFileSync(source, target)
+  }
+  return files.length
+}
+
+function seconds(ms) {
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+/** Runs one command with its output shown, and times it. */
+function runStep(label, command, args, cwd, env, timeoutMs = 15 * MINUTE) {
+  console.log(`\n  ▶ ${label}: ${[command, ...args].join(" ")}`)
+  const started = Date.now()
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    stdio: "inherit",
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+  })
+  const ms = Date.now() - started
+  const ok = result.status === 0
+  if (!ok) {
+    const why = result.error
+      ? result.error.message
+      : result.signal
+        ? `killed by ${result.signal}`
+        : `exit ${result.status}`
+    console.error(`  ✗ ${label} failed (${why}) after ${seconds(ms)}`)
+  }
+  return { ok, ms }
+}
+
+function freePort() {
+  return new Promise((resolvePort, reject) => {
+    const server = createServer()
+    server.unref()
+    server.on("error", reject)
+    server.listen(0, () => {
+      const { port } = server.address()
+      server.close(() => resolvePort(port))
+    })
+  })
+}
+
+/** Ends a detached child and everything it started. */
+async function killGroup(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return
+  const exited = new Promise((done) => child.once("exit", done))
+  try {
+    process.kill(-child.pid, "SIGTERM")
+  } catch {
+    return
+  }
+  const timedOut = await Promise.race([
+    exited.then(() => false),
+    sleep(5000).then(() => true),
+  ])
+  if (timedOut) {
+    try {
+      process.kill(-child.pid, "SIGKILL")
+    } catch {
+      // already gone
+    }
+    await exited
+  }
+}
+
+/** At most this many app modules are fetched from one dev server. */
+const MODULE_LIMIT = 500
+
+/**
+ * Fetches the page's scripts and the `seeds` (`startEntrySeeds`) and, from
+ * each ES module among them, every app module it imports, transitively: a
+ * Vite dev server compiles a module only when it is requested, so a module
+ * below the entry that fails to transform (an unresolvable import, say)
+ * answers 500 only when fetched.
+ */
+async function loadScripts(scripts, deadline, seeds = []) {
+  const queue = [
+    ...scripts.map((s) => ({ ...s, from: "the page" })),
+    ...seeds.map((url) => ({
+      url,
+      module: true,
+      from: "TanStack Start's dev entry, through /@fs/ (seeded)",
+    })),
+  ]
+  const seen = new Set(queue.map((s) => s.url))
+  const broken = []
+  let modules = 0
+  while (queue.length > 0) {
+    const { url, module, from } = queue.shift()
+    const res = await fetch(url, {
+      signal: AbortSignal.timeout(Math.max(1000, deadline - Date.now())),
+    })
+    const code = await res.text()
+    if (!res.ok) {
+      broken.push(`${url} (${res.status}, imported by ${from})`)
+      continue
+    }
+    if (!module) continue
+    modules++
+    for (const next of moduleImports(code, url)) {
+      if (seen.has(next) || seen.size >= MODULE_LIMIT) continue
+      seen.add(next)
+      queue.push({ url: next, module: true, from: url })
+    }
+  }
+  const app = [...seen].filter((url) =>
+    new URL(url).pathname.startsWith("/src/")
+  ).length
+  return { broken, fetched: seen.size, modules, app }
+}
+
+/**
+ * Starts `npm run dev -- <args> --port N` on a free port, fetches its first
+ * page and what that page loads, and stops it. The port is passed as
+ * `--port`, which both Vite and Next take, so a server already on the
+ * example's own port on this machine does not fail the run. `files`, the
+ * example's tracked files, are where a TanStack Start example's entry modules
+ * are found (`startEntrySeeds`).
+ */
+async function smokeDevServer(
+  cwd,
+  env,
+  extraArgs,
+  files,
+  timeoutMs = 4 * MINUTE
+) {
+  const port = await freePort()
+  const url = `http://localhost:${port}/`
+  const args = ["run", "dev", "--", ...extraArgs, "--port", String(port)]
+  const shown = env.NEXT_TEST_WASM ? "NEXT_TEST_WASM=1 " : ""
+  console.log(
+    `\n  ▶ start, under the WebContainer model: ${shown}npm ${args.join(" ")}, then GET ${url}`
+  )
+  const started = Date.now()
+  const child = spawn("npm", args, {
+    cwd,
+    env,
+    detached: true,
+    stdio: ["ignore", "inherit", "inherit"],
+  })
+  let exit
+  child.once("exit", (code, signal) => (exit = signal ?? `exit ${code}`))
+  let failure = "no page before the deadline"
+  try {
+    const deadline = started + timeoutMs
+    while (Date.now() < deadline) {
+      if (exit) {
+        failure = `the dev server stopped (${exit}) before serving a page`
+        break
+      }
+      let response
+      let body
+      try {
+        response = await fetch(url, {
+          signal: AbortSignal.timeout(Math.max(1000, deadline - Date.now())),
+        })
+        body = await response.text()
+      } catch {
+        // not listening yet
+        await sleep(1000)
+        continue
+      }
+      if (response.ok && /<html[\s>]/i.test(body)) {
+        // The page alone proves little for Vite, whose index.html is static:
+        // its scripts, and the modules they import, are what the dev server
+        // compiles on request.
+        const scripts = pageScripts(body, url)
+        const { seeds, finding } = startEntrySeeds(scripts, files)
+        if (finding) {
+          failure = finding
+          break
+        }
+        const loaded = await loadScripts(scripts, deadline, seeds)
+        if (loaded.broken.length > 0) {
+          failure = `what the page loads did not load: ${loaded.broken.join(", ")}`
+          break
+        }
+        const ms = Date.now() - started
+        const what =
+          seeds.length > 0
+            ? `its ${scripts.length} script(s), TanStack Start's dev entry among them, the app's entry modules that entry reaches only through /@fs/ (${seeds.map((s) => new URL(s).pathname).join(", ")}), and the app modules they import loaded (${loaded.fetched} fetched, ${loaded.app} under /src/, ${loaded.modules} ES modules)`
+            : `its ${scripts.length} script(s) and the app modules they import loaded (${loaded.fetched} fetched, ${loaded.modules} ES modules)`
+        console.log(
+          `  ✓ ${url} answered ${response.status} with ${body.length} bytes of HTML; ${what}, after ${seconds(ms)}`
+        )
+        return { ok: true, ms }
+      }
+      failure = `${url} answered ${response.status}${response.ok ? " without an <html> document" : ""}`
+      if (!response.ok) break
+      await sleep(1000)
+    }
+  } catch (error) {
+    failure = error.message
+  } finally {
+    await killGroup(child)
+  }
+  const ms = Date.now() - started
+  console.error(`  ✗ start failed: ${failure} after ${seconds(ms)}`)
+  return { ok: false, ms }
+}
+
+/** One example, start to finish. */
+async function testExample(name, { tag, version, workDir, preload }) {
+  const dir = join(workDir, name.replaceAll("/", "__"))
+  const steps = {}
+  const findings = []
+  console.log(`\n━━ ${name} → ${dir}`)
+
+  const files = trackedFiles(name)
+  copyTracked(name, files, dir)
+  console.log(`  copied ${files.length} tracked files`)
+
+  const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"))
+  const start = stackblitzStartCommand(dir)
+  findings.push(
+    ...staticFindings(name, { files, scripts: manifest.scripts, start })
+  )
+  findings.push(
+    ...(await checkManifest(manifest, {
+      tag,
+      version,
+      satisfying: npmSatisfying,
+    }))
+  )
+  if (findings.length > 0) return { name, steps, findings }
+
+  const env = isolatedEnv(process.env, repoRoot)
+  steps.install = runStep(
+    "install",
+    "npm",
+    [
+      "install",
+      "--no-audit",
+      "--no-fund",
+      "--package-lock=true",
+      ...REGISTRY_ARGS,
+    ],
+    dir,
+    env
+  )
+  if (!steps.install.ok) return { name, steps, findings }
+
+  const declared = declaredDependencies(manifest)
+    .map((d) => d.name)
+    .filter((n) => n.startsWith(SCOPE))
+  const { installed, findings: installFindings } = checkInstalled(
+    dir,
+    declared,
+    version,
+    tag
+  )
+  findings.push(...installFindings)
+  let lock
+  try {
+    lock = JSON.parse(readFileSync(join(dir, "package-lock.json"), "utf8"))
+  } catch {
+    lock = undefined
+  }
+  const locked = [...new Set(lockedScopePackages(lock).map((e) => e.name))]
+  findings.push(
+    ...checkLockfile(lock, {
+      installed: installed.map((p) => p.name),
+      published: publishedDist(locked, version),
+    })
+  )
+  console.log(
+    `  installed from ${REGISTRY} (lockfile resolved and integrity match the registry's): ` +
+      installed.map((p) => `${p.name}@${p.version}`).join(", ")
+  )
+  if (findings.length > 0) return { name, steps, findings }
+
+  const isNext = Boolean(
+    manifest.dependencies?.next || manifest.devDependencies?.next
+  )
+  if (isNext && !existsSync(join(dir, "next-env.d.ts"))) {
+    writeFileSync(join(dir, "next-env.d.ts"), NEXT_ENV)
+  }
+  for (const script of REQUIRED_SCRIPTS) {
+    if (!manifest.scripts?.[script]) continue
+    steps[script] = runStep(script, "npm", ["run", script], dir, env)
+  }
+
+  // Under the model of what a WebContainer lacks, even a script step 5 ran:
+  // green on Node says nothing about StackBlitz (vite-wallet's tests were).
+  const modelEnv = webContainerEnv(env, preload)
+  const parsed = parseNpmCommand(start.command)
+  if (parsed?.script === "dev") {
+    // A WebContainer has no native binary: Next loads its WebAssembly
+    // bindings there, and NEXT_TEST_WASM makes it do the same here.
+    const devEnv = isNext ? { ...modelEnv, NEXT_TEST_WASM: "1" } : modelEnv
+    steps.start = await smokeDevServer(dir, devEnv, parsed.args, files)
+  } else {
+    const [command, ...args] = start.command.split(/\s+/)
+    steps.start = runStep(
+      "start, under the WebContainer model",
+      command,
+      args,
+      dir,
+      modelEnv,
+      5 * MINUTE
+    )
+  }
+  return { name, steps, findings }
+}
+
+function report(results, totalMs) {
+  const columns = ["install", "typecheck", "test", "build", "start"]
+  const cell = (step) =>
+    !step ? "-" : `${step.ok ? "ok" : "FAIL"} ${seconds(step.ms)}`
+  const rows = results.map((r) => {
+    const failed =
+      r.findings.length > 0 || Object.values(r.steps).some((s) => !s.ok)
+    return [
+      r.name,
+      ...columns.map((c) => cell(r.steps[c])),
+      failed ? "FAIL" : "ok",
+    ]
+  })
+  const header = ["example", ...columns, "result"]
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...rows.map((row) => row[i].length))
+  )
+  const line = (row) => row.map((v, i) => v.padEnd(widths[i])).join("  ")
+  console.log(
+    `\n${line(header)}\n${widths.map((w) => "-".repeat(w)).join("  ")}`
+  )
+  for (const row of rows) console.log(line(row))
+  for (const r of results) {
+    for (const finding of r.findings) console.error(`\n✗ ${r.name}: ${finding}`)
+  }
+  console.log(`\nTotal ${seconds(totalMs)}`)
+  return rows.some((row) => row.at(-1) === "FAIL")
+}
+
+/**
+ * The command line: `--keep`, `--tmp <dir>`, `--wait-for <version>` and the
+ * example names.
+ *
+ * @param {string[]} argv
+ * @returns {{ keep: boolean, tmp?: string, waitFor?: string, names: string[], error?: string }}
+ */
+export function parseArgs(argv) {
+  const out = { keep: false, names: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === "--keep") out.keep = true
+    else if (arg === "--tmp" || arg === "--wait-for") {
+      const value = argv[++i]
+      if (!value || value.startsWith("--")) {
+        return { ...out, error: `${arg} needs a value` }
+      }
+      if (arg === "--tmp") out.tmp = value
+      else out.waitFor = value.replace(/^v/, "")
+    } else if (arg.startsWith("--")) {
+      return { ...out, error: `Unknown option ${arg}` }
+    } else out.names.push(arg)
+  }
+  return out
+}
+
+/**
+ * The @ic-reactor/* packages a run reads from the registry: every one the
+ * manifests declare, and core (whose dist-tag names the version under test).
+ *
+ * @param {Record<string, any>[]} manifests
+ * @returns {string[]}
+ */
+export function scopePackageNames(manifests) {
+  const names = new Set([`${SCOPE}core`])
+  for (const manifest of manifests) {
+    for (const { name } of declaredDependencies(manifest)) {
+      if (name.startsWith(SCOPE)) names.add(name)
+    }
+  }
+  return [...names].sort()
+}
+
+/**
+ * Polls each package until its `tag` dist-tag names `version`, the registry
+ * answers with `version`'s integrity, and it serves `version`'s tarball, for
+ * up to `timeoutMs`. The release workflow publishes the lane's packages
+ * (core, react, vite-plugin and mcp) one after another, so the last one can
+ * lag the first by minutes; every package the run reads must be served before
+ * the examples install. The tarball can lag that metadata by minutes: on
+ * 4.1.0's release run, core's tarball answered 404 for about five minutes
+ * after its dist-tag and integrity named 4.1.0, and every example's install
+ * failed on it.
+ *
+ * `lookup(name)` resolves with what the registry serves now: the version the
+ * dist-tag names (undefined when it has none), `version`'s integrity
+ * (undefined when that version is not served yet), and whether `version`'s
+ * tarball downloads (`served`).
+ *
+ * @param {string[]} names
+ * @param {string} tag
+ * @param {string} version
+ * @param {{
+ *   lookup: (name: string) => Promise<{ tagged?: string, integrity?: string, served?: boolean }> | { tagged?: string, integrity?: string, served?: boolean },
+ *   timeoutMs?: number,
+ *   pollMs?: number,
+ *   wait?: (ms: number) => Promise<unknown>,
+ *   now?: () => number,
+ *   log?: (line: string) => void,
+ * }} options
+ * @returns {Promise<string>} `version`, once every package serves it
+ */
+export async function waitForPublished(
+  names,
+  tag,
+  version,
+  {
+    lookup,
+    timeoutMs = 10 * MINUTE,
+    pollMs = 15_000,
+    wait = sleep,
+    now = Date.now,
+    log = console.log,
+  }
+) {
+  const deadline = now() + timeoutMs
+  for (;;) {
+    const pending = []
+    for (const name of names) {
+      const { tagged, integrity, served } = await lookup(name)
+      if (tagged !== version) {
+        pending.push(`${name}@${tag} is ${tagged ?? "unset"}`)
+      } else if (!integrity) {
+        pending.push(`${name}@${version} has no dist.integrity yet`)
+      } else if (!served) {
+        pending.push(`${name}@${version}'s tarball is not served yet`)
+      }
+    }
+    if (pending.length === 0) return version
+    if (now() >= deadline) {
+      throw new Error(
+        `Not published as ${version} after ${seconds(timeoutMs)}: ${pending.join("; ")}`
+      )
+    }
+    log(`Waiting for ${version}: ${pending.join("; ")}`)
+    await wait(pollMs)
+  }
+}
+
+/**
+ * The HTTP status the registry answers a HEAD of `url` with now, or 0 when
+ * the request fails.
+ */
+async function headStatus(url) {
+  try {
+    const response = await fetch(url, {
+      method: "HEAD",
+      signal: AbortSignal.timeout(30_000),
+    })
+    return response.status
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * What the registry serves for `name` now, for `waitForPublished`. The
+ * tarball is asked for only once the dist-tag and the integrity name
+ * `version`, at the URL the registry gives for it (`dist.tarball`), which is
+ * the one npm's install fetches.
+ */
+async function registryState(
+  name,
+  tag,
+  version,
+  view = npmView,
+  status = headStatus
+) {
+  const tagged = view(`${name}@${tag}`, "version")
+  const integrity =
+    tagged === version
+      ? view(`${name}@${version}`, "dist.integrity")
+      : undefined
+  const tarball =
+    typeof integrity === "string"
+      ? view(`${name}@${version}`, "dist.tarball")
+      : undefined
+  return {
+    tagged: typeof tagged === "string" ? tagged : undefined,
+    integrity: typeof integrity === "string" ? integrity : undefined,
+    served: typeof tarball === "string" && (await status(tarball)) === 200,
+  }
+}
+
+/**
+ * A run's dist-tag and the version under test, or that the run defers.
+ *
+ * With `--wait-for` (the release's run, which never defers): the tag that
+ * release publishes under (`distTagFor(waitFor)`), and the version is
+ * `waitFor` once every one of `packages` serves it under that tag
+ * (`waitForPublished`).
+ *
+ * Without it (push, pull request, weekly and manual runs), the branch's
+ * version (`branchVersion`, from packages/core/package.json) decides:
+ *
+ * - When the examples wait on it (`awaitsRelease`: it is not among core's
+ *   published versions, every @ic-reactor/* range of every example is exactly
+ *   `^<it>`, and no dependency uses a local protocol), a release pull request
+ *   or its merge before the tag publishes it, the run defers:
+ *   `{ deferred: true, version: branchVersion }`. The caller still runs the
+ *   checks that need no registry (`deferredRun`, over `staticFindings`), and a
+ *   finding there fails the run. Core's versions are asked for only when every example pins
+ *   `^<branchVersion>`.
+ * - Otherwise the tag is that of the branch's version, which is the version
+ *   of its last release: release.js syncs the examples to exactly that
+ *   version (sync-example-versions.js), so `latest` after a stable release
+ *   such as 4.0.0, and `beta` through a later prerelease cycle such as
+ *   4.1.0's, whose ranges no `latest` satisfies; the version is the one that
+ *   tag names. With no branch version, `latest`.
+ *
+ * @param {{
+ *   waitFor?: string,
+ *   branchVersion?: string,
+ *   manifests?: Record<string, any>[],
+ *   packages?: string[],
+ * }} run `manifests` are the examples' package.json files; `packages`, the
+ *   ones a release run waits on, default to `scopePackageNames(manifests)`
+ * @param {{ view?: (spec: string, field: string) => unknown, status?: (url: string) => Promise<number> } & Partial<Parameters<typeof waitForPublished>[3]>} [options]
+ *   `view(spec, field)` answers as `npm view <spec> <field> --json` does
+ *   (undefined for a 404); `status(url)` with the HTTP status of a HEAD of a
+ *   tarball's URL; the rest goes to `waitForPublished`
+ * @returns {Promise<{ tag: "latest" | "beta", version: string, deferred?: undefined } | { deferred: true, version: string }>}
+ */
+export async function resolveRun(
+  {
+    waitFor,
+    branchVersion,
+    manifests = [],
+    packages = scopePackageNames(manifests),
+  },
+  { view = npmView, status = headStatus, ...waitOptions } = {}
+) {
+  if (
+    !waitFor &&
+    // Every example pins ^<branchVersion>: only then is npm asked whether
+    // that version is out.
+    awaitsRelease(manifests, { branchVersion, publishedVersions: [] }) &&
+    awaitsRelease(manifests, {
+      branchVersion,
+      publishedVersions: [view(`${SCOPE}core`, "versions") ?? []].flat(),
+    })
+  ) {
+    return { deferred: true, version: branchVersion }
+  }
+  const tag = distTagFor(waitFor ?? branchVersion)
+  const version = waitFor
+    ? await waitForPublished(packages, tag, waitFor, {
+        ...waitOptions,
+        lookup: (name) => registryState(name, tag, waitFor, view, status),
+      })
+    : distTagVersion(`${SCOPE}core`, tag, view)
+  return { tag, version }
+}
+
+/**
+ * A deferred run (`resolveRun`'s `{ deferred: true }`): it still runs the
+ * checks that need no registry (`staticFindings`) on each example of the
+ * checkout, so deferring never skips them. A finding fails the run (exit 1,
+ * reported); with none it passes (exit 0) and says what it deferred to.
+ *
+ * @param {string[]} names the examples
+ * @param {{
+ *   version: string,
+ *   manifests: Record<string, any>[],
+ *   files?: (name: string) => string[],
+ *   startCommand?: (name: string) => { command?: string, finding?: string },
+ *   onFindings?: (results: { name: string, steps: {}, findings: string[] }[]) => void,
+ *   log?: (message: string) => void,
+ * }} run `manifests` are the examples' package.json files, in `names`'
+ *   order; `files`, `startCommand`, `onFindings` and `log` default to the
+ *   checkout's tracked files, its `.stackblitzrc`, the run's report and
+ *   `console.log`
+ * @returns {0 | 1} the run's exit code
+ */
+export function deferredRun(
+  names,
+  {
+    version,
+    manifests,
+    files = trackedFiles,
+    startCommand = (name) =>
+      stackblitzStartCommand(join(repoRoot, "examples", name)),
+    onFindings = (results) => report(results, 0),
+    log = console.log,
+  }
+) {
+  const results = names.map((name, i) => ({
+    name,
+    steps: {},
+    findings: staticFindings(name, {
+      files: files(name),
+      scripts: manifests[i].scripts,
+      start: startCommand(name),
+    }),
+  }))
+  if (results.some((result) => result.findings.length > 0)) {
+    onFindings(results)
+    return 1
+  }
+  log(
+    `The examples pin ^${version}, this branch's own version, which is not on ${REGISTRY} yet: ` +
+      `a release that has not been published. The checks that need no registry pass. release.yml's examples-published job tests them ` +
+      `against it once it is (--wait-for v${version}). Nothing to test here.`
+  )
+  return 0
+}
+
+async function main(argv) {
+  const args = parseArgs(argv)
+  if (args.error) {
+    console.error(args.error)
+    return 1
+  }
+  const all = discoverExampleDirs()
+  const unknown = args.names.filter((name) => !all.includes(name))
+  if (unknown.length > 0) {
+    console.error(
+      `Not an example: ${unknown.join(", ")} (examples: ${all.join(", ")})`
+    )
+    return 1
+  }
+  const names = args.names.length > 0 ? args.names : all
+  if (names.length === 0) {
+    console.error("No examples found under examples/.")
+    return 1
+  }
+
+  const readManifest = (...path) =>
+    JSON.parse(readFileSync(join(repoRoot, ...path), "utf8"))
+  const manifests = names.map((name) =>
+    readManifest("examples", name, "package.json")
+  )
+  let run
+  try {
+    run = await resolveRun({
+      waitFor: args.waitFor,
+      branchVersion: readManifest("packages", "core", "package.json").version,
+      manifests,
+    })
+  } catch (error) {
+    console.error(error.message)
+    return 1
+  }
+  if (run.deferred) {
+    return deferredRun(names, { version: run.version, manifests })
+  }
+  const { tag, version } = run
+  console.log(
+    `${SCOPE}core@${tag} is ${version} on ${REGISTRY}; testing ${names.join(", ")}`
+  )
+
+  const base = realpathSync(args.tmp ? resolve(args.tmp) : tmpdir())
+  const workDir = realpathSync(
+    mkdtempSync(join(base, "ic-reactor-published-examples-"))
+  )
+  const rel = relative(repoRoot, workDir)
+  const refusals = []
+  if (!rel.startsWith("..") && !rel.startsWith(sep)) {
+    refusals.push(`The scratch directory ${workDir} is inside the repository.`)
+  }
+  refusals.push(...ancestorFindings(workDir))
+  if (refusals.length > 0) {
+    rmSync(workDir, { recursive: true, force: true })
+    for (const refusal of refusals) console.error(refusal)
+    return 1
+  }
+  const keep = args.keep
+  const preload = join(workDir, "webcontainer-model.cjs")
+  writeFileSync(preload, WEBCONTAINER_MODEL)
+
+  const started = Date.now()
+  const results = []
+  try {
+    for (const name of names) {
+      results.push(await testExample(name, { tag, version, workDir, preload }))
+    }
+  } finally {
+    if (keep) console.log(`\nCopies kept in ${workDir}`)
+    else rmSync(workDir, { recursive: true, force: true })
+  }
+  const failed = report(results, Date.now() - started)
+  if (!failed) {
+    console.log(
+      `✅ ${results.length} example(s) green against ${SCOPE}*@${version} (${tag}) from npm`
+    )
+  }
+  return failed ? 1 : 0
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  process.exitCode = await main(process.argv.slice(2))
+}