@cosyte/script-utils 0.1.2 → 0.1.3

package/attw.js

@@ -160,9 +160,16 @@
  *      one, and `prepare` and `postpack` double the same way. `prepublishOnly` does
  *      not run under `npm pack` AT ALL (measured: 0 through either gate), which is
  *      why this cannot recurse into the gate that runs it. Of the three that do
- *      double, every repo here defines only `prepare`, and defines it as the same
- *      `command -v simple-git-hooks … || true` one-liner, so
- *      nothing reds today. IT IS NOT FIXED WITH `--ignore-scripts`, AND THAT IS
+ *      double, the repos here define only `prepare`. AN EARLIER VERSION OF THIS
+ *      PARAGRAPH SAID EVERY ONE DEFINES IT AS THE SAME ONE-LINER, SO NOTHING REDS,
+ *      AND THAT WAS FALSE. The `prepare` lines differ, and the one the parser
+ *      template shipped printed simple-git-hooks' `[INFO]` lines on STDOUT, inside
+ *      the JSON this net parses: every repo scaffolded from it was born with a gate
+ *      that refused ("did not print JSON"). The template now sends that output to
+ *      stderr (`simple-git-hooks 1>&2`, cosyte/config#131), and twelve sibling
+ *      repos still carry the older line, so a `prepare` that writes to stdout is
+ *      a refusal here rather than a pass, by design: what it printed is in the
+ *      message. IT IS NOT FIXED WITH `--ignore-scripts`, AND THAT IS
  *      DELIBERATE: a `prepack` may GENERATE files that belong in the tarball, so
  *      suppressing it would make this net read a listing the real publish would not
  *      produce, which is a correctness bug wearing a performance fix.
@@ -734,15 +741,17 @@ import { spawnSync } from "node:child_process";
 import {
   accessSync,
   constants,
+  existsSync,
   mkdtempSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   rmSync,
   statSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { basename, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { gunzipSync } from "node:zlib";
 
 /**
@@ -990,6 +999,27 @@ function summarizeProblems(out) {
   return [`attw reported ${lines.length} problem kind(s):`, ...lines].join("\n");
 }
 
+/**
+ * The entries of an `npm pack --json` report that describe the package `name`.
+ *
+ * npm 10 and 11 print an ARRAY of entries; npm 12 prints an OBJECT keyed by
+ * package name. An entry counts only when its own `name` is `name`, and in the
+ * object shape only under the key `name` as well, so a key and an entry that
+ * disagree count for nothing. Any other document (a string, a number, `null`)
+ * yields no entries, which the caller refuses rather than grades.
+ *
+ * @param {unknown} doc The parsed report.
+ * @param {string | undefined} name The package name from package.json.
+ * @returns {Array<{ name?: unknown, files?: unknown }>}
+ */
+function packReportEntries(doc, name) {
+  if (Array.isArray(doc)) return doc.filter((entry) => entry?.name === name);
+  if (doc === null || typeof doc !== "object") return [];
+  return Object.entries(doc)
+    .filter(([key, entry]) => key === name && entry?.name === name)
+    .map(([, entry]) => entry);
+}
+
 /**
  * The paths a published tarball of this directory would carry, read from npm
  * rather than recomputed from `files`/`.npmignore` here.
@@ -1006,6 +1036,15 @@ function summarizeProblems(out) {
  * file list, because a partial answer graded as a whole one is the false green
  * this whole file exists to refuse.
  *
+ * TWO SHAPES OF REPORT ARE READ, AND ONLY TWO. npm 10 and 11 print an ARRAY of
+ * tarball entries; npm 12 prints an OBJECT keyed by package name whose values
+ * are the same entries. Measured on npm 12.2.0: `npm pack --dry-run --json` on a
+ * package named `@scope/probe` printed `{"@scope/probe": {"name": "@scope/probe",
+ * "files": [...], ...}}`. Before this read both, the object fell through to an
+ * empty list and the net refused every package ("npm described 0 tarball(s)"),
+ * which is a red for the right reason (it read nothing) and the wrong outcome
+ * (CI moving to npm 12 would have refused every publish). See `packReportEntries`.
+ *
  * @param {{ name?: string }} pkg The parsed manifest.
  * @param {NodeJS.ProcessEnv} childEnv The environment to hand npm.
  * @returns {{ files: Set<string>, error?: undefined } | { error: string, files?: undefined }}
@@ -1032,11 +1071,12 @@ function packedFiles(pkg, childEnv) {
       error: `\`npm pack --dry-run --json\` did not print JSON. What it printed:\n\n${res.stdout ?? ""}`,
     };
   }
-  // npm reports an ARRAY of tarballs, because the same command run at a workspace
-  // root describes several. Only this package's own entry is gradeable here, and
+  // npm describes one entry per tarball, because the same command run at a
+  // workspace root describes several, in one of the two shapes read by
+  // `packReportEntries`. Only this package's own entry is gradeable here, and
   // anything other than exactly one of them means npm was asked a different
   // question than this net thinks it asked.
-  const mine = (Array.isArray(doc) ? doc : []).filter((entry) => entry?.name === pkg.name);
+  const mine = packReportEntries(doc, pkg.name);
   if (mine.length !== 1) {
     return {
       error:
@@ -1677,3 +1717,143 @@ function gate({ callerUrl, argv = process.argv.slice(2) }) {
   );
   return 0;
 }
+
+// ---- The command-line form (ST34) --------------------------------------------
+//
+// `node node_modules/@cosyte/script-utils/attw.js` runs this gate for the
+// package in the working directory with no caller file of its own: it is what
+// the one-line `scripts/attw.mjs` caller does, resolving the package's own
+// `node_modules/.bin/attw`. What the package leaves out of attw's analysis is
+// declared in `scripts/attw.exclude`, one resolution per line, `#` for comments:
+//
+//   node10       left out by attw's `node16` profile
+//   node16-cjs   left out, with node10, by its `esm-only` profile
+//
+// The file SELECTS A PROFILE and nothing else, so it reaches only what the
+// argument allow-list already forwards. A name it does not know, a repeat,
+// node16-cjs without node10 (no profile leaves out that one alone) and a
+// `--profile` on the command line beside the file are each refused: one source
+// for the profile, and nothing an exclusion could use to blind net 2.
+
+/** The resolutions an exclusions file may name. */
+const EXCLUDABLE_RESOLUTIONS = new Set(["node10", "node16-cjs"]);
+
+/** Where the command-line form reads what a package leaves out. */
+export const ATTW_EXCLUDE_PATH = "scripts/attw.exclude";
+
+/**
+ * Read an attw exclusions file into the one profile it selects.
+ *
+ * @param {string} text The file's contents.
+ * @returns {{ profile: "node16" | "esm-only" | null, problems: string[] }}
+ */
+export function readAttwExclusions(text) {
+  const problems = [];
+  const seen = new Set();
+  text.split("\n").forEach((raw, index) => {
+    const hash = raw.indexOf("#");
+    const entry = (hash < 0 ? raw : raw.slice(0, hash)).trim();
+    if (entry === "") return;
+    if (!EXCLUDABLE_RESOLUTIONS.has(entry)) {
+      problems.push(
+        `line ${index + 1}: ${JSON.stringify(entry)} is not a resolution this gate can ` +
+          `leave out (node10, node16-cjs).`,
+      );
+    } else if (seen.has(entry)) {
+      problems.push(`line ${index + 1}: ${entry} is listed twice.`);
+    } else {
+      seen.add(entry);
+    }
+  });
+  let profile = null;
+  if (seen.has("node16-cjs") && !seen.has("node10")) {
+    problems.push(
+      "node16-cjs can be left out only with node10: attw's esm-only profile leaves out both " +
+        "CommonJS resolutions, and no profile leaves out node16-cjs alone.",
+    );
+  } else if (seen.has("node16-cjs")) {
+    profile = "esm-only";
+  } else if (seen.has("node10")) {
+    profile = "node16";
+  }
+  return { profile, problems };
+}
+
+/**
+ * Run the gate from the command line for the package in the working directory.
+ *
+ * @param {string[]} argv The command-line arguments, graded by the same allow-list.
+ * @returns {number} The gate's exit code: 0 pass, attw's own status, or 1 for a refusal.
+ */
+export function runAttwCli(argv) {
+  const args = argv.filter((arg) => arg !== "--");
+  const file = join(process.cwd(), ...ATTW_EXCLUDE_PATH.split("/"));
+  const profile = [];
+  if (existsSync(file)) {
+    let text;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch (err) {
+      process.stderr.write(`\n✗ attw gate: could not read ${ATTW_EXCLUDE_PATH}: ${err.message}\n`);
+      return 1;
+    }
+    const read = readAttwExclusions(text);
+    if (read.problems.length > 0) {
+      process.stderr.write(
+        `\n✗ attw gate: ${ATTW_EXCLUDE_PATH} is not usable, so nothing was checked:\n` +
+          read.problems.map((problem) => `  ${problem}\n`).join(""),
+      );
+      return 1;
+    }
+    if (read.profile !== null) {
+      if (args.some((arg) => arg.split("=")[0] === "--profile")) {
+        process.stderr.write(
+          `\n✗ attw gate: --profile was given and ${ATTW_EXCLUDE_PATH} selects a profile ` +
+            `too. Declare it in the file alone.\n`,
+        );
+        return 1;
+      }
+      profile.push("--profile", read.profile);
+    }
+  }
+  // The caller this form stands in for lives at `scripts/attw.mjs`, so the gate
+  // resolves `../node_modules/.bin/attw` from there: this package's own binary.
+  return runAttwGate({
+    callerUrl: pathToFileURL(join(process.cwd(), "scripts", "attw.mjs")).href,
+    argv: [...args, ...profile],
+  });
+}
+
+/**
+ * Whether node was pointed at this file, which is the command-line form.
+ *
+ * SELF-CONTAINED ON PURPOSE: this module is also vendored and copied as a single file, so it may not
+ * import a sibling at load. A file whose name differs from the one node was pointed at cannot be the
+ * entry point, and that is settled without loading anything; only a matching name asks `index.js`'s
+ * `isCliEntrypoint`, and a copy with no `index.js` beside it compares real paths instead. Unsure is
+ * yes, so a gate that cannot tell runs loudly rather than skipping.
+ *
+ * @param {string} moduleUrl This module's `import.meta.url`.
+ * @returns {Promise<boolean>}
+ */
+async function invokedAsCommand(moduleUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== "string" || entry === "") return false;
+  const own = fileURLToPath(moduleUrl);
+  const stem = (path) => basename(path).replace(/\.[cm]?[jt]s$/, "");
+  if (stem(entry) !== stem(own)) return false;
+  try {
+    const { isCliEntrypoint } = await import("./index.js");
+    return isCliEntrypoint(moduleUrl);
+  } catch {
+    try {
+      return realpathSync(entry) === realpathSync(own);
+    } catch {
+      return true;
+    }
+  }
+}
+
+void invokedAsCommand(import.meta.url).then((command) => {
+  if (command) process.exitCode = runAttwCli(process.argv.slice(2));
+});

package/catalog.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Types for `@cosyte/script-utils/catalog`: the catalog of Cosyte's libraries and Pathways
+ * (ST13, ST14), generated in cosyte/config from each package's package.json, and the check every
+ * library runs that its description is the catalog's.
+ */
+
+/** The three tiers, in the order ST13 names them. */
+export declare const TIERS: readonly ["standard", "built-on", "engine"];
+
+/** What every record carries, generated from the package's package.json. */
+export interface CatalogRecord {
+  /** The npm package name, for example `@cosyte/hl7`. */
+  readonly name: string;
+  /** The name without its scope, for example `hl7`. */
+  readonly slug: string;
+  /** The package.json description: the package's one canonical line. */
+  readonly description: string;
+  /** The release line, for example `0.1`. */
+  readonly line: string;
+  readonly engines: { readonly node: string };
+  /** `https://github.com/cosyte/<repo>`. */
+  readonly repository: string;
+  /** `https://docs.cosyte.com/<slug>`. */
+  readonly docs: string;
+}
+
+/** One of the 14 libraries. */
+export interface CatalogLibrary extends CatalogRecord {
+  /** `https://www.npmjs.com/package/<name>`. */
+  readonly npm: string;
+  readonly tier: "standard" | "built-on";
+  /** The standard, as readers see it (`HL7 v2`, `C-CDA`), for a library of the standard tier. */
+  readonly standard?: string;
+}
+
+/** Pathways, our integration engine. */
+export interface CatalogEngine extends CatalogRecord {
+  readonly tier: "engine";
+  /** The product name, `Pathways`. */
+  readonly displayName: string;
+  /** For example `in development`. */
+  readonly status: string;
+  /** Whether it is published to npm. */
+  readonly onNpm: boolean;
+}
+
+export interface Catalog {
+  /** The 8 standards' libraries, then the 6 built on them, in the order ST13 names them. */
+  readonly libraries: readonly CatalogLibrary[];
+  readonly engine: CatalogEngine;
+}
+
+/** The hand-kept tiers file, `catalog/tiers.json` in cosyte/config. */
+export interface CatalogTiers {
+  standards: { package: string; standard: string }[];
+  builtOn: string[];
+  engine: { package: string; name: string; status: string; onNpm: boolean };
+}
+
+/** The catalog, as the `catalog.json` beside this module carries it. Deeply frozen. */
+export declare const CATALOG: Catalog;
+
+/** The release line a version is on: `0.<minor>` below 1.0.0, the major from 1.0.0 on. */
+export declare function releaseLine(version: string): string;
+
+/**
+ * Build the catalog from the tiers file and each package's parsed package.json, keyed by name.
+ *
+ * @throws {TypeError} When a tier names a package with no usable manifest, or names one twice.
+ */
+export declare function buildCatalog(
+  tiers: CatalogTiers,
+  manifests: Map<string, Record<string, unknown>> | Record<string, Record<string, unknown>>,
+): Catalog;
+
+/** The record for a package name: a library, the engine, or `undefined`. */
+export declare function catalogEntry(
+  name: string,
+  catalog?: Catalog,
+): CatalogLibrary | CatalogEngine | undefined;
+
+/** A field where a package.json and its catalog record disagree. */
+export interface CatalogDifference {
+  field: "description";
+  catalog: string;
+  packageJson: string;
+}
+
+/**
+ * Compare a package.json with its catalog record. Only the description is compared.
+ *
+ * @throws {TypeError} When the catalog does not list the package.
+ */
+export declare function compareWithCatalog(
+  manifest: Record<string, unknown>,
+  catalog?: Catalog,
+): CatalogDifference[];
+
+export interface CatalogCheckOptions {
+  /** The package directory holding package.json. Default: the working directory. */
+  dir?: string;
+  /** CLI arguments; only `--dir <path>` is accepted. */
+  argv?: string[];
+}
+
+/**
+ * Run the check over one package directory and return the exit code: 0 the description is the
+ * catalog's, 1 it is not, 2 the check could not run. It never exits the process.
+ */
+export declare function runCatalogCheck(options?: CatalogCheckOptions): 0 | 1 | 2;

package/catalog.js

@@ -0,0 +1,251 @@
+// @cosyte/script-utils/catalog
+//
+// THE CATALOG OF COSYTE'S LIBRARIES (ST13, ST14). One record per library, generated from that
+// library's own package.json, with the tier it belongs to; and one for Pathways, our integration
+// engine, which is in development and not on npm. The tiers and Pathways' status come from a small
+// hand-kept file in cosyte/config (`catalog/tiers.json`); everything else is read out of each
+// package.json by `scripts/catalog.mjs` there, and written beside this module as `catalog.json`.
+// A site, the org profile, a deck or a knowledgebase page reads that one list instead of keeping
+// its own roster.
+//
+// IT ALSO CARRIES THE CHECK EVERY LIBRARY RUNS. Each package.json description is that library's one
+// canonical line (ST14), so the description in a library's package.json must be the catalog's.
+// When a library changes its description, its check fails until the catalog is regenerated and a
+// script-utils release carries it: the catalog and the package cannot quietly disagree.
+//
+//   node node_modules/@cosyte/script-utils/catalog.js              # the package in this directory
+//   node node_modules/@cosyte/script-utils/catalog.js --dir <path> # another package directory
+//
+// EXIT CODES, the contract every gate here keeps: 0 the description agrees, 1 it does not, 2 the
+// check could not run (no package.json, or a package the catalog does not list).
+//
+// ZERO DEPENDENCIES AND NO BUILD STEP, like the rest of this package.
+
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { isCliEntrypoint } from "./index.js";
+
+/** The three tiers, in the order ST13 names them. */
+export const TIERS = Object.freeze(["standard", "built-on", "engine"]);
+
+/** Deep-freeze a parsed JSON value, so no consumer can edit the shared catalog in place. */
+function freeze(value) {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) freeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** The catalog, as `catalog.json` beside this module carries it. */
+export const CATALOG = freeze(
+  JSON.parse(readFileSync(new URL("./catalog.json", import.meta.url), "utf8")),
+);
+
+/**
+ * The release line a version is on: `0.<minor>` below 1.0.0, where a minor may break, and the
+ * major from 1.0.0 on. `0.1.2` is the 0.1 line (ST16).
+ *
+ * @param {string} version A `major.minor.patch` version.
+ * @returns {string} The line, for example `0.1`.
+ */
+export function releaseLine(version) {
+  const match = /^(\d+)\.(\d+)\.\d+(?:[-+].*)?$/.exec(String(version));
+  if (match === null) throw new TypeError(`${JSON.stringify(version)} is not a semver version.`);
+  return match[1] === "0" ? `0.${match[2]}` : match[1];
+}
+
+/** The `https://github.com/cosyte/<repo>` a package.json's repository names, or `null`. */
+function repositoryUrl(manifest) {
+  const raw =
+    typeof manifest.repository === "string" ? manifest.repository : manifest.repository?.url;
+  if (typeof raw !== "string") return null;
+  const match = /github\.com[/:]cosyte\/([A-Za-z0-9._-]+?)(?:\.git)?\/?$/.exec(raw);
+  return match === null ? null : `https://github.com/cosyte/${match[1]}`;
+}
+
+/** The slug a `@cosyte/<slug>` name carries. */
+function slugOf(name) {
+  const match = /^@cosyte\/([a-z0-9][a-z0-9.-]*)$/.exec(String(name));
+  if (match === null)
+    throw new TypeError(`${JSON.stringify(name)} is not a @cosyte/<name> package.`);
+  return match[1];
+}
+
+/** The fields every record takes from its package.json, refusing a manifest that lacks one. */
+function fromManifest(name, manifest) {
+  if (manifest === undefined || manifest === null || typeof manifest !== "object") {
+    throw new TypeError(`no package.json was read for ${name}.`);
+  }
+  if (manifest.name !== name) {
+    throw new TypeError(
+      `the package.json read for ${name} names ${JSON.stringify(manifest.name)}.`,
+    );
+  }
+  const slug = slugOf(name);
+  const problems = [];
+  if (typeof manifest.description !== "string" || manifest.description.trim() === "") {
+    problems.push("no description");
+  }
+  if (typeof manifest.version !== "string") problems.push("no version");
+  if (typeof manifest.engines?.node !== "string") problems.push("no engines.node");
+  const repository = repositoryUrl(manifest);
+  if (repository === null) problems.push("no github.com/cosyte repository");
+  if (problems.length > 0)
+    throw new TypeError(`${name}'s package.json has ${problems.join(", ")}.`);
+  return {
+    name,
+    slug,
+    description: manifest.description,
+    line: releaseLine(manifest.version),
+    engines: { node: manifest.engines.node },
+    repository,
+    docs: `https://docs.cosyte.com/${slug}`,
+  };
+}
+
+/**
+ * Build the catalog from the hand-kept tiers file and each package's package.json. Pure: it reads
+ * nothing, so the generator decides where the manifests come from.
+ *
+ * @param {{ standards: { package: string, standard: string }[], builtOn: string[],
+ *   engine: { package: string, name: string, status: string, onNpm: boolean } }} tiers
+ * @param {Map<string, Record<string, any>> | Record<string, Record<string, any>>} manifests
+ *   Each package's parsed package.json, keyed by package name.
+ * @returns {{ libraries: object[], engine: object }} The catalog.
+ * @throws {TypeError} When a tier names a package with no usable manifest, or names one twice.
+ */
+export function buildCatalog(tiers, manifests) {
+  const get = (name) => (manifests instanceof Map ? manifests.get(name) : manifests[name]);
+  const seen = new Set();
+  const claim = (name) => {
+    if (seen.has(name)) throw new TypeError(`${name} is listed twice in the tiers.`);
+    seen.add(name);
+  };
+  const libraries = [];
+  for (const { package: name, standard } of tiers.standards) {
+    claim(name);
+    libraries.push({
+      ...fromManifest(name, get(name)),
+      npm: `https://www.npmjs.com/package/${name}`,
+      tier: "standard",
+      standard,
+    });
+  }
+  for (const name of tiers.builtOn) {
+    claim(name);
+    libraries.push({
+      ...fromManifest(name, get(name)),
+      npm: `https://www.npmjs.com/package/${name}`,
+      tier: "built-on",
+    });
+  }
+  const { package: enginePackage, name: engineName, status, onNpm } = tiers.engine;
+  claim(enginePackage);
+  const engine = {
+    ...fromManifest(enginePackage, get(enginePackage)),
+    tier: "engine",
+    displayName: engineName,
+    status,
+    onNpm,
+  };
+  return { libraries, engine };
+}
+
+/**
+ * The catalog record for a package name: a library or the engine, or `undefined`.
+ *
+ * @param {string} name A package name, for example `@cosyte/hl7`.
+ * @param {{ libraries: object[], engine: object }} [catalog] Defaults to `CATALOG`.
+ */
+export function catalogEntry(name, catalog = CATALOG) {
+  if (catalog.engine?.name === name) return catalog.engine;
+  return catalog.libraries.find((entry) => entry.name === name);
+}
+
+/**
+ * Compare a package.json with its catalog record. Only the description is compared: it is the line
+ * ST14 makes canonical, and the other generated fields move with a release (the version line) or
+ * cannot drift without the package moving (the name and repository).
+ *
+ * @param {Record<string, any>} manifest The package's parsed package.json.
+ * @param {{ libraries: object[], engine: object }} [catalog] Defaults to `CATALOG`.
+ * @returns {{ field: string, catalog: string, packageJson: string }[]} The disagreements.
+ * @throws {TypeError} When the catalog does not list the package.
+ */
+export function compareWithCatalog(manifest, catalog = CATALOG) {
+  const entry = catalogEntry(manifest?.name, catalog);
+  if (entry === undefined) {
+    throw new TypeError(`the catalog does not list ${JSON.stringify(manifest?.name ?? null)}.`);
+  }
+  if (manifest.description === entry.description) return [];
+  return [
+    {
+      field: "description",
+      catalog: entry.description,
+      packageJson: String(manifest.description ?? ""),
+    },
+  ];
+}
+
+/**
+ * Run the check over one package directory and return the exit code. It never exits the process.
+ *
+ * @param {{ dir?: string, argv?: string[] }} [options] `dir` is the package directory (default:
+ *   the working directory). `argv` is the CLI arguments, read only for `--dir <path>`.
+ * @returns {0 | 1 | 2} 0 agree, 1 disagree, 2 the check could not run.
+ */
+export function runCatalogCheck(options = {}) {
+  let dir = options.dir ?? process.cwd();
+  const argv = options.argv ?? [];
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === "--dir" && typeof argv[i + 1] === "string") {
+      dir = argv[i + 1];
+      i += 1;
+    } else if (argv[i] !== "--") {
+      process.stderr.write(
+        `catalog check: ${JSON.stringify(argv[i])} is not an argument this check accepts (only ` +
+          `--dir <package directory>). Nothing was checked.\n`,
+      );
+      return 2;
+    }
+  }
+  dir = resolve(dir);
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  } catch (err) {
+    process.stderr.write(`catalog check: could not read package.json in ${dir}: ${err.message}\n`);
+    return 2;
+  }
+  let differences;
+  try {
+    differences = compareWithCatalog(manifest);
+  } catch (err) {
+    process.stderr.write(`catalog check: ${err.message} Nothing was checked.\n`);
+    return 2;
+  }
+  if (differences.length === 0) {
+    process.stdout.write(`catalog check: ${manifest.name}'s description is the catalog's.\n`);
+    return 0;
+  }
+  const report = differences
+    .map(
+      (d) =>
+        `  ${d.field}\n    package.json: ${JSON.stringify(d.packageJson)}\n` +
+        `    catalog:      ${JSON.stringify(d.catalog)}`,
+    )
+    .join("\n");
+  process.stderr.write(
+    `catalog check: ${manifest.name}'s package.json and the catalog disagree.\n${report}\n` +
+      `The catalog is generated from package.json in cosyte/config (scripts/catalog.mjs) and ` +
+      `ships in @cosyte/script-utils. Change both together: regenerate the catalog, release ` +
+      `script-utils, then move this package to that release.\n`,
+  );
+  return 1;
+}
+
+if (isCliEntrypoint(import.meta.url)) {
+  process.exitCode = runCatalogCheck({ argv: process.argv.slice(2) });
+}