omakit 0.6.8 → 0.6.10

package/tools/marketplace/doctor.mjs

@@ -54,11 +54,26 @@
 // a rule can change without its version. The other two commits (7dd6e56,
 // 40315f2) touched submission.mjs and the policy module, both executed,
 // and the forms, so they grade advice either way.
+//
+// Nor is "a file omakit reads moved" the same as "what omakit reads out of
+// it moved", for the three files it reads as text and never runs. Measured
+// on 2026-10-01 (M7, docs/evidence/pin-freshness/2026-10-01-grades.json):
+// build-catalog.mjs, the most edited file under scripts/, moved three times
+// after b7b29654 (a166e3ac, b612419c, cb7947ec), the reserved namespace and
+// the category mapping read out of it the same each time, and the blob
+// comparison graded each advice, a release for nothing. So a text-read file
+// whose blob moved is read once at HEAD and each value its `readers`
+// (PIN_READS) take out of it is compared with the pin's, by the same
+// function; one whose every value is unchanged does not count as moved for
+// the grade (`effective`), and one whose value differs is advice with both
+// values printed. Of the five commits since 38060f89 that touched a file in
+// the read set, the tree comparison and the blob comparison grade five
+// advice and this grades two: 7dd6e56 and 40315f2, as above.
 
 import { execFileSync } from "node:child_process"
 import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
-import { MARKETPLACE_PIN, PIN_PATHS, POLICY_MODULE, WORDING_READS, marketplacePinDir, pinDiskUsage, pinShape, pinnedReadSet, policyConstants, requirePin } from "./pin.mjs"
+import { MARKETPLACE_PIN, PIN_PATHS, PIN_READS, POLICY_MODULE, WORDING_READS, marketplacePinDir, pinDiskUsage, pinShape, pinnedReadSet, policyConstants, requirePin } from "./pin.mjs"
 import { LIVE_PATHS, headTextUrl } from "./registry.mjs"
 import { credential, defaultBranchHead, getJson, getText, GitHubError } from "./github.mjs"
 import { compareVersions, NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
@@ -68,6 +83,7 @@ import { pathHint } from "./path-hint.mjs"
 import { completionStatus } from "./completion-check.mjs"
 import { inspectLab } from "../lab/inspect.mjs"
 import { labDoctorChecks } from "../lab/report.mjs"
+import { checkNewestRelease } from "../lab/release.mjs"
 
 export function tool(repoRoot) {
   try {
@@ -92,6 +108,45 @@ function pinObjectId(pinDir, commit, path) {
   return execFileSync("git", ["-C", pinDir, "rev-parse", `${commit}:${path}`], { timeout: 60_000, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim()
 }
 
+/** A file's text at a commit in the pinned checkout. Local: the read set's blobs are in the checkout. */
+function pinFileText(pinDir, commit, path) {
+  return execFileSync("git", ["-C", pinDir, "show", `${commit}:${path}`], { timeout: 60_000, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] })
+}
+
+/**
+ * Each value `readers` takes out of a file, read out of the pin's text and
+ * HEAD's by the same function, and whether the two are the same: equal
+ * when their JSON is, since every reader returns a string, null or plain
+ * data.
+ *
+ * @returns {Record<string, { pin: unknown, head: unknown, same: boolean }>}
+ */
+export function textReadValues(readers, pinText, headText) {
+  return Object.fromEntries(Object.entries(readers).map(([name, read]) => {
+    const pin = read(pinText)
+    const head = read(headText)
+    return [name, { pin, head, same: JSON.stringify(pin) === JSON.stringify(head) }]
+  }))
+}
+
+/**
+ * The text-read files of `reads` (those PIN_READS gives `readers`), each
+ * with whether its blob moved and the values read out of it at both ends.
+ * The pin's text comes from the checkout; HEAD's is fetched once, and only
+ * for a file in `moved`: an identical blob has identical values, so an
+ * unmoved file's values are the pin's at both ends and cost no request.
+ * With nothing moved (a current pin) it reads locally only.
+ */
+export async function textReadsBetween({ pinDir, pinCommit = MARKETPLACE_PIN.commit, headCommit = pinCommit, reads = pinnedReadSet(pinDir), moved = [], fetchText = getText }) {
+  const textReads = {}
+  for (const { path, readers } of PIN_READS.filter((read) => read.readers && reads.some((entry) => entry.path === read.path))) {
+    const atPin = pinFileText(pinDir, pinCommit, path)
+    const blobMoved = moved.includes(path)
+    textReads[path] = { moved: blobMoved, values: textReadValues(readers, atPin, blobMoved ? await fetchText(headTextUrl(headCommit, path)) : atPin) }
+  }
+  return textReads
+}
+
 /** A PIN_PATHS pattern as a path: "/site/catalog.json" -> "site/catalog.json". */
 const asPath = (pattern) => pattern.replace(/^\/|\/$/g, "")
 
@@ -116,10 +171,20 @@ const FORMS = "/.github/ISSUE_TEMPLATE/"
  * `policyAtHead`; otherwise `policyAtHead` is null, because an identical
  * blob has identical constants. The text is never imported.
  *
+ * Each file PIN_READS reads as text is compared by what omakit reads out
+ * of it, under `textReads`: its `readers` run on the pin's text (from the
+ * checkout) and on HEAD's, and each value is returned with both sides and
+ * whether they are the same. HEAD's text is read once through `fetchText`
+ * only when the file's blob moved, one more GET per such file; an
+ * unmoved file's values are the pin's at both ends, and a file gone at
+ * HEAD is in `missing` and not here. The text is compared and dropped,
+ * never imported.
+ *
  * `fetchJson` and `fetchText` are injectable for tests.
  *
  * @returns {Promise<{ changedPaths: string[], reads: number, moved: string[], missing: string[],
- *                     policyAtHead: { baselineVersion: string, enforcementMode: string }|null }>}
+ *                     policyAtHead: { baselineVersion: string, enforcementMode: string }|null,
+ *                     textReads: Record<string, { moved: boolean, values: Record<string, { pin: unknown, head: unknown, same: boolean }> }> }>}
  */
 export async function comparePin({ pinDir, headCommit, pinCommit = MARKETPLACE_PIN.commit, fetchJson = getJson, fetchText = getText, reads = pinnedReadSet(pinDir) }) {
   const match = MARKETPLACE_PIN.repository.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+)$/)
@@ -163,7 +228,8 @@ export async function comparePin({ pinDir, headCommit, pinCommit = MARKETPLACE_P
     }
   }
   const policyAtHead = moved.includes(POLICY_MODULE) ? policyConstants(await fetchText(headTextUrl(headCommit, POLICY_MODULE))) : null
-  return { changedPaths, reads: reads.length, moved, missing, policyAtHead }
+  const textReads = await textReadsBetween({ pinDir, pinCommit, headCommit, reads: reads.filter((read) => !missing.includes(read.path)), moved, fetchText })
+  return { changedPaths, reads: reads.length, moved, missing, policyAtHead, textReads }
 }
 
 /** "a", "a and b", "a, b and c". */
@@ -185,24 +251,36 @@ const verdictBearing = (paths) => paths.filter((path) => !WORDING_READS.includes
  * from HEAD, and `pinned`, everything only a new pin can carry; its `moved`
  * and `missing` name the files omakit reads under scripts/ whose blob
  * differs at HEAD; its `policyAtHead` carries the two policy constants
- * there when the policy module moved.
+ * there when the policy module moved; its `textReads` carries, for each
+ * file read as text, the values omakit reads out of it at both ends.
+ *
+ * A file read as text whose blob moved and whose every value reads the
+ * same at HEAD does not count as moved for the grade: omakit takes those
+ * values out of it and nothing else, so the move cannot reach a verdict or
+ * a line. `effective` is `moved` without such files, and the grade is
+ * taken from it; `moved` keeps meaning the blob. Measured on 2026-10-01
+ * (M7): build-catalog.mjs moved three times after b7b29654, the reserved
+ * namespace and the category mapping read the same each time, and the
+ * blob comparison graded the pin advice for it.
  *
  *   ok      nothing omakit reads moved: HEAD moved elsewhere, or only in
  *           the live-read data files, or scripts/ moved in none of the
- *           files omakit reads.
- *   info    the only read files that moved are ones omakit takes wording
+ *           files omakit reads, or only in files read as text whose values
+ *           are unchanged (named, with how many values).
+ *   info    the only read files that count are ones omakit takes wording
  *           or a label out of (WORDING_READS): what it prints may differ
  *           at HEAD, what it passes or refuses cannot. A newer omakit will
  *           carry the pin. Nothing for a user to do.
  *   advice  a file omakit executes or reads a rule from moved (a verdict
  *           may differ at HEAD, whether or not the two policy constants
  *           still read the same, since a rule can change without its
- *           version), a read file is gone at HEAD, or the form directory
- *           moved (the contract itself). The action is `upgrade` (the
- *           command, when the caller found a newer omakit published), else
- *           that the maintainer is notified; never an issue to open, since
- *           the weekly pin-freshness workflow opens the one there is. The
- *           two constants are printed beside the grade in both cases.
+ *           version), a value read out of a text-read file differs (both
+ *           values printed), a read file is gone at HEAD, or the form
+ *           directory moved (the contract itself). The action is `upgrade`
+ *           (the command, when the caller found a newer omakit published),
+ *           else that the maintainer is notified; never an issue to open,
+ *           since the weekly pin-freshness workflow opens the one there is.
+ *           The two constants are printed beside the grade in both cases.
  *
  * Null for `comparison` means the comparison was not made, which stays
  * advice: HEAD moved and nothing here can say the pin is fine. Full commits
@@ -217,15 +295,22 @@ export function pinFreshness(identity, head, comparison = null, { upgrade = null
   const pinned = changed.filter((pattern) => !LIVE_PATHS.includes(asPath(pattern)))
   const moved = compared ? comparison.moved : []
   const missing = compared ? comparison.missing : []
+  const textReads = comparison?.textReads || {}
   const pinPolicy = { baselineVersion: identity.baselineVersion, enforcementMode: identity.enforcementMode }
   const headPolicy = (compared && comparison.policyAtHead) || pinPolicy
   const policyDiffers = headPolicy.baselineVersion !== pinPolicy.baselineVersion || headPolicy.enforcementMode !== pinPolicy.enforcementMode
   const formMoved = pinned.includes(FORMS)
+  // The text-read files that moved, by whether every value read out of them is the same at HEAD.
+  const valuesOf = (path) => Object.entries(textReads[path]?.moved ? textReads[path].values : {})
+  const unchanged = moved.filter((path) => valuesOf(path).length && valuesOf(path).every(([, value]) => value.same))
+  const differing = moved.filter((path) => valuesOf(path).some(([, value]) => !value.same))
+  const effective = moved.filter((path) => !unchanged.includes(path))
   const verdictMoved = verdictBearing(moved)
+  const verdictEffective = verdictBearing(effective)
   const graded = moved.length > 0 || missing.length > 0 || formMoved
   const state = current ? "ok"
-    : comparison === null || policyDiffers || formMoved || missing.length || verdictMoved.length ? "advice"
-      : moved.length ? "info"
+    : comparison === null || policyDiffers || formMoved || missing.length || differing.length || verdictEffective.length ? "advice"
+      : effective.length ? "info"
         : "ok"
 
   const where = `pin ${identity.commit.slice(0, 7)}; marketplace ${branch} at ${head.commit.slice(0, 7)}`
@@ -233,7 +318,14 @@ export function pinFreshness(identity, head, comparison = null, { upgrade = null
   if (comparison === null) clauses.push("the paths omakit reads were not compared")
   else if (!changed.length) clauses.push("nothing omakit reads moved")
   else {
-    if (moved.length) clauses.push(`moved since the pin: ${list(moved)}${verdictMoved.length ? "" : " (wording and labels only)"}`)
+    if (effective.length) clauses.push(`moved since the pin: ${list(effective)}${verdictEffective.length || differing.length ? "" : " (wording and labels only)"}`)
+    for (const path of differing) {
+      for (const [name, value] of valuesOf(path).filter(([, entry]) => !entry.same)) clauses.push(`${name} ${JSON.stringify(value.pin)} at the pin, ${JSON.stringify(value.head)} at HEAD`)
+    }
+    if (unchanged.length) {
+      const count = unchanged.reduce((sum, path) => sum + valuesOf(path).length, 0)
+      clauses.push(`${list(unchanged)} moved, and ${count === 1 ? "the one value" : `the ${count} values`} omakit reads from ${unchanged.length === 1 ? "it" : "them"} ${count === 1 ? "is" : "are"} unchanged`)
+    }
     if (missing.length) clauses.push(`gone at HEAD: ${list(missing)}`)
     if (formMoved) clauses.push(`the form moved (${asPath(FORMS)}/)`)
     if (pinned.includes("/scripts/") && !moved.length && !missing.length) clauses.push(`scripts/ moved in none of the ${comparison.reads} files omakit reads`)
@@ -244,7 +336,7 @@ export function pinFreshness(identity, head, comparison = null, { upgrade = null
   const detail = current ? `the pin is the marketplace's current ${branch}-branch HEAD` : `${where}; ${clauses.join("; ")}${tail}`
 
   const action = state === "info"
-    ? `${moved.length === 1 ? "That file is" : "Those files are"} read for wording and labels, not for a pass or a refusal; what omakit prints may differ at HEAD, what it decides cannot. A newer omakit will carry the pin; nothing to do.`
+    ? `${effective.length === 1 ? "That file is" : "Those files are"} read for wording and labels, not for a pass or a refusal; what omakit prints may differ at HEAD, what it decides cannot. A newer omakit will carry the pin; nothing to do.`
     : state === "advice"
       ? upgrade
         ? `A newer omakit is published and may carry the pin: run \`${upgrade}\`. Until then every verdict here is the pin's, and the marketplace's own run on your issue is the one that counts.`
@@ -267,7 +359,9 @@ export function pinFreshness(identity, head, comparison = null, { upgrade = null
         reads: comparison.reads,
         moved,
         verdictMoved,
+        effective,
         missing,
+        textReads,
         policy: { pin: pinPolicy, head: headPolicy },
       }),
     },
@@ -278,11 +372,12 @@ export function pinFreshness(identity, head, comparison = null, { upgrade = null
  * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null,
  *           resolveHead?: typeof defaultBranchHead, latest?: typeof registryLatest, compare?: typeof comparePin }} options
  *   `env` and `npmPrefix` are injectable for tests of the PATH check;
- *   `resolveHead`, `latest` and `compare` for tests of the two checks that
- *   read the network, whose defaults are the tool's one HEAD resolver, its
- *   one registry read and the pin comparison above.
+ *   `resolveHead`, `latest`, `compare` and `newestRelease` for tests of the
+ *   checks that read the network, whose defaults are the tool's one HEAD
+ *   resolver, its one registry read, the pin comparison above and the
+ *   lab's read of Omarchy's release list (tools/lab/release.mjs).
  */
-export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = registryLatest, compare = comparePin }) {
+export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = registryLatest, compare = comparePin, newestRelease = checkNewestRelease }) {
   // Optional: told what is being read while the network answers. Never
   // affects the result.
   const phase = onPhase || (() => {})
@@ -394,10 +489,14 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
     phase("reading the marketplace's current default-branch HEAD")
     try {
       const head = await resolveHead(MARKETPLACE_PIN.repository)
-      let comparison = { changedPaths: [], reads: pinnedReadSet(dir).length, moved: [], missing: [], policyAtHead: null }
+      let comparison
       if (head.commit !== identity.commit) {
         phase("comparing each file omakit reads between the pin and HEAD")
         comparison = await compare({ pinDir: dir, headCommit: head.commit, pinCommit: identity.commit })
+      } else {
+        // The pin is HEAD: nothing moved, and the values read as text are the pin's, read locally.
+        const reads = pinnedReadSet(dir)
+        comparison = { changedPaths: [], reads: reads.length, moved: [], missing: [], policyAtHead: null, textReads: await textReadsBetween({ pinDir: dir, pinCommit: identity.commit, reads }) }
       }
       checks.push(pinFreshness(identity, head, comparison, { upgrade }))
     } catch (error) {
@@ -431,9 +530,15 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
   // the base, each with its measured reason, every one advice and never a
   // problem, because the lab is optional and doctor installs nothing.
   // Read-only: inspectLab creates no directory, verifies nothing online
-  // and starts nothing.
+  // and starts nothing. The one read is Omarchy's release list, so the
+  // lab says when a newer release is out; --offline skips it.
+  let newest = { checked: false, code: "offline", reason: "--offline" }
+  if (!offline) {
+    phase("looking for the newest Omarchy release")
+    newest = await newestRelease({ signal: AbortSignal.timeout(45_000) })
+  }
   phase("reading the lab")
-  for (const check of labDoctorChecks(await inspectLab({ env }))) checks.push(check)
+  for (const check of labDoctorChecks(await inspectLab({ env, newest }))) checks.push(check)
 
   return { checks, problems: checks.filter((check) => check.state === "problem").length }
 }

package/tools/marketplace/github.mjs

@@ -119,7 +119,7 @@ export const CREDENTIAL_HOST = "api.github.com"
  */
 export const GET_DEADLINE_MS = 20_000
 
-async function get(url, { accept, signal, rangeFrom = 0 } = {}) {
+async function get(url, { accept, signal, rangeFrom = 0, rangeEnd = null } = {}) {
   const { host } = new URL(url)
   // The credential is GitHub's and goes to GitHub's API and nowhere else.
   // Measured before this held: `omakit upgrade` and `doctor` sent the gh
@@ -136,7 +136,9 @@ async function get(url, { accept, signal, rangeFrom = 0 } = {}) {
   // A resumed download asks for the rest of the object; the lab's ISO
   // fetch is the one caller, and a server that ignores the range answers
   // 200 from the start, which the caller handles by starting over.
-  if (rangeFrom > 0) headers.range = `bytes=${rangeFrom}-`
+  // The lab's release search asks for the first byte alone (`rangeEnd` 0)
+  // to read the ISO's size from Content-Range without fetching the image.
+  if (rangeFrom > 0 || rangeEnd !== null) headers.range = `bytes=${rangeFrom}-${rangeEnd ?? ""}`
   let response
   try {
     response = await fetch(url, { method: "GET", headers, redirect: "follow", signal: signal || AbortSignal.timeout(GET_DEADLINE_MS) })
@@ -144,8 +146,12 @@ async function get(url, { accept, signal, rangeFrom = 0 } = {}) {
     // Node reports every transport failure as "fetch failed" with the real
     // reason in `cause`. A person needs the reason, and the CLI keys its
     // remedy on the code, so both are carried out of here.
-    const cause = error?.name === "TimeoutError" ? `no answer within ${GET_DEADLINE_MS / 1000} s` : error?.cause?.code || error?.cause?.message || error?.message || "fetch failed"
     const { host, pathname } = new URL(url)
+    // The caller stopped it (SIGINT, SIGTERM): that is an interrupt, not a
+    // network that did not answer, and the caller has to be able to tell.
+    if (signal?.aborted && signal.reason?.name !== "TimeoutError") throw new GitHubError("interrupted", `interrupted while reading ${pathname} from ${host}`)
+    // A caller's own deadline is the caller's figure; only the default is 20 s.
+    const cause = error?.name === "TimeoutError" ? (signal ? "no answer before the caller's deadline" : `no answer within ${GET_DEADLINE_MS / 1000} s`) : error?.cause?.code || error?.cause?.message || error?.message || "fetch failed"
     throw new GitHubError("network-unavailable", `${host} did not answer (${cause}) while reading ${pathname}`)
   }
   if (!response.ok) {
@@ -178,8 +184,8 @@ export async function getText(url, accept) {
  * same literal method, and the credential stays with api.github.com; the
  * ISO origin (iso.omarchy.org) never sees it.
  */
-export async function getStream(url, { rangeFrom = 0, signal } = {}) {
-  return get(url, { accept: "application/octet-stream", signal, rangeFrom })
+export async function getStream(url, { rangeFrom = 0, rangeEnd = null, signal } = {}) {
+  return get(url, { accept: "application/octet-stream", signal, rangeFrom, rangeEnd })
 }
 
 /** Parse a marketplace issue URL into its parts. */

package/tools/marketplace/options.mjs

@@ -31,7 +31,7 @@ export const ACCEPTED = Object.freeze({
   inspect: Object.freeze({ valued: ["--out"], flags: ["--full", "--json", "--offline", "--allow-dirty"], positionals: 1 }),
   add: Object.freeze({ valued: [], flags: ["--update", "--json"], positionals: 2 }),
   weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
-  lab: Object.freeze({ valued: ["--runs", "--from", "--toolchain", "--out"], flags: ["--json", "--yes", "--verify", "--plugins", "--keep-iso", "--records"], positionals: 2 }),
+  lab: Object.freeze({ valued: ["--runs", "--from", "--toolchain", "--out"], flags: ["--json", "--yes", "--verify", "--plugins", "--keep-iso", "--records", "--offline"], positionals: 2 }),
 })
 
 /** The accepted options of a command in the words a refusal prints: `--runs N, --all, ...`. */

package/tools/marketplace/pin.mjs

@@ -6,7 +6,8 @@
 // of which 168 MB is preview imagery and 151 MB is history, and omakit reads
 // twenty files out of it, sixteen of them under scripts/ (PIN_READS). A
 // blob-filtered, sparsely checked out fetch of just those paths is 15 MB and
-// takes 2 seconds instead of 17. PIN_PATHS below is the whole list, and
+// takes 2 seconds instead of 17; at pin b441b4f0 (2026-10-01) the same fetch
+// was 23 MB on disk in 3.1 seconds. PIN_PATHS below is the whole list, and
 // tests/unit/pin.test.mjs fails if any module starts reading a path outside
 // it, because on a partial clone such a read would quietly reach for the
 // network instead of failing.
@@ -27,8 +28,8 @@ export class PinError extends Error {
 
 export const MARKETPLACE_PIN = Object.freeze({
   repository: "https://github.com/omacom/omarchy-plugin-marketplace",
-  commit: "b7b2965431c52fc6311fdb389bd9f0d6275235c4",
-  commitSubject: "Add OmaStudio plugin (#6843)",
+  commit: "b441b4f059132b5b7203a7563027f2b3a9adaa1d",
+  commitSubject: "Add LINE for Omarchy plugin (#9470)",
   baselineVersion: "3",
   enforcementMode: "selective",
 })
@@ -40,8 +41,9 @@ export const MARKETPLACE_PIN = Object.freeze({
  *   /scripts/                     the official submission parser, baseline
  *                                 scanner, policy, report and record modules,
  *                                 and build-catalog.mjs read as text for the
- *                                 reserved plugin-id namespace. Taken whole
- *                                 because those modules import each other.
+ *                                 reserved plugin-id namespace and the
+ *                                 category mapping. Taken whole because
+ *                                 those modules import each other.
  *   /registry.json                retired plugin ids, listed repositories
  *   /site/catalog.json            listed plugin ids
  *   /.github/ISSUE_TEMPLATE/      the submission form: the whole contract
@@ -83,8 +85,19 @@ export const POLICY_MODULE = "scripts/security-baseline-policy.mjs"
  *   approve-submission.mjs           watch.mjs, text: one label
  *   approve-plugin-update.mjs        review-cost.mjs, text: one label
  *
+ * A file read as text carries `readers`: each value omakit takes out of
+ * it, by name, as a function from the file's text to the value. This is
+ * the one list of what is read out of such a file, and the functions are
+ * the ones the modules above call on the pin's text and the ones `omakit
+ * doctor` calls on the pin's text and on HEAD's, so the two sides of the
+ * comparison cannot read differently. Measured on 2026-10-01 (M7): the
+ * three commits that moved build-catalog.mjs since b7b29654 changed
+ * neither of the two values read out of it, and the blob comparison
+ * graded each of them advice.
+ *
  * tests/unit/pin.test.mjs derives this list from the sources and fails on
- * a read that is not here, or one listed the wrong way round.
+ * a read that is not here, or one listed the wrong way round, and holds
+ * `readers` to exactly the files read as text.
  */
 export const PIN_READS = Object.freeze([
   Object.freeze({ path: "scripts/submission.mjs", imported: true }),
@@ -94,9 +107,9 @@ export const PIN_READS = Object.freeze([
   Object.freeze({ path: "scripts/security-baseline-report.mjs", imported: true }),
   Object.freeze({ path: "scripts/security-baseline-record.mjs", imported: true }),
   Object.freeze({ path: "scripts/submission-feedback.mjs", imported: true }),
-  Object.freeze({ path: "scripts/build-catalog.mjs", imported: false }),
-  Object.freeze({ path: "scripts/approve-submission.mjs", imported: false }),
-  Object.freeze({ path: "scripts/approve-plugin-update.mjs", imported: false }),
+  Object.freeze({ path: "scripts/build-catalog.mjs", imported: false, readers: Object.freeze({ reservedNamespace, catalogPresentation }) }),
+  Object.freeze({ path: "scripts/approve-submission.mjs", imported: false, readers: Object.freeze({ validatedLabel }) }),
+  Object.freeze({ path: "scripts/approve-plugin-update.mjs", imported: false, readers: Object.freeze({ updateLabel }) }),
 ])
 
 /**
@@ -126,9 +139,9 @@ export const RELATIVE_IMPORT = /\bfrom\s+["'](\.\.?\/[^"']+)["']/g
  * no guard; Node's ESM loader requires an extension.) If one of these ever
  * appears in an executed file of the pinned read set, pinnedReadSet() could
  * miss a file, and tests/unit/pin.test.mjs fails on the file and line
- * instead of doctor staying quiet. Measured at pin b7b29654: none of
- * the 13 executed files uses any of them (the three read as text are not
- * scanned, since nothing they import is loaded).
+ * instead of doctor staying quiet. Measured at pins b7b29654 and
+ * b441b4f0: none of the 13 executed files uses any of them (the three read
+ * as text are not scanned, since nothing they import is loaded).
  */
 export const UNFOLLOWED_IMPORTS = Object.freeze([
   Object.freeze({ form: "dynamic import()", pattern: /\bimport\s*\(/ }),
@@ -164,8 +177,8 @@ export function unfollowedImports(pinDir, reads = pinnedReadSet(pinDir)) {
  * the file that imports it or null for one omakit opens itself. A
  * specifier that leaves scripts/ (the marketplace's site/ assets) or names
  * a package (`sharp`) is not followed: PIN_PATHS does not fetch it, so
- * omakit could not read it. Measured at pin b7b29654: 16 of the 34 files
- * under scripts/, 10 opened by omakit and 6 imported by those.
+ * omakit could not read it. Measured at pins b7b29654 and b441b4f0: 16 of
+ * the 34 files under scripts/, 10 opened by omakit and 6 imported by those.
  *
  * @returns {{ path: string, imported: boolean, via: string|null }[]}
  */
@@ -243,6 +256,58 @@ export function policyConstants(text) {
   }
 }
 
+// The readers PIN_READS registers for the files read as text. Each takes
+// the file's text and returns the value, or null where the text does not
+// carry it, the way policyConstants() does for the policy module: no file
+// is opened here and no module is loaded, so the same function reads the
+// pin's copy for a check and HEAD's copy for doctor's comparison.
+
+/**
+ * The reserved plugin-id namespace as the marketplace states it in
+ * `build-catalog.mjs`, next to its own `reserved-plugin-id` check, with
+ * its trailing dot. Read, not copied, so a pin update moves it.
+ */
+export function reservedNamespace(text) {
+  const source = String(text || "")
+  const match = source.match(/startsWith\("([A-Za-z0-9.\-_]+\.)"\)\s*\)\s*\{\s*\n\s*checkError\("reserved-plugin-id"/)
+    || source.match(/checkError\("reserved-plugin-id",\s*`[^`]*\$\{[^}]*\}:\s*the ([A-Za-z0-9.\-_]+)\.\*\s+namespace is reserved`/)
+  if (!match) return null
+  return match[1].endsWith(".") ? match[1] : `${match[1]}.`
+}
+
+/**
+ * How the marketplace itself presents a plugin it lists, read out of
+ * `build-catalog.mjs` rather than copied: `categoryFor(kinds)` maps the
+ * manifest's kinds to a category in order of its `if` lines, with a
+ * fallback, and the tags are the first three kinds lowercased. `omakit
+ * submit` offers these as the default answer when it has to ask for a
+ * category and tags, so the default is the marketplace's own choice; a
+ * mapping that cannot be read offers no default. tests/unit/registry-
+ * figures.test.mjs pins what the mapping is at this commit, so a
+ * marketplace that changes it fails the suite until the docs follow.
+ *
+ * @returns {{ rules: Array<{ kinds: string[], category: string }>, fallback: string|null, tagsFromKinds: boolean }}
+ */
+export function catalogPresentation(text) {
+  const source = String(text || "")
+  const body = source.match(/function categoryFor\([^)]*\)\s*\{([\s\S]*?)\n\}/)?.[1] || ""
+  const rules = [...body.matchAll(/if \(((?:kinds\.includes\("[^"]+"\)(?:\s*\|\|\s*)?)+)\) return "([^"]+)";/g)]
+    .map((match) => ({ kinds: [...match[1].matchAll(/"([^"]+)"/g)].map((kind) => kind[1]), category: match[2] }))
+  const fallback = body.match(/\n\s*return "([^"]+)";\s*$/)?.[1] || null
+  const tagsFromKinds = /tags:\s*kinds\.slice\(0,\s*3\)\.map\(\(kind\) => kind\.toLowerCase\(\)\)/.test(source)
+  return { rules, fallback, tagsFromKinds }
+}
+
+/** The label `approve-submission.mjs` requires beside `submission` before it approves: the one `omakit watch` reads as validated. */
+export function validatedLabel(text) {
+  return String(text || "").match(/for \(const required of \["submission", "([^"]+)"/)?.[1] || null
+}
+
+/** The first label `approve-plugin-update.mjs` requires: the one an update issue carries, for review cost. */
+export function updateLabel(text) {
+  return String(text || "").match(/for \(const required of \["([^"]+)"/)?.[1] || null
+}
+
 /** Identity of the checkout at `dir`: commit plus the policy constants read from the pinned source. */
 function readPinIdentity(dir) {
   const commit = git(dir, ["rev-parse", "HEAD"]).trim()

package/tools/marketplace/preflight.mjs

@@ -3,8 +3,8 @@
 // its outcome will cause on submission.
 //
 // Measured reason this runs before submitting (docs/MEASUREMENTS.md M4): of the
-// 3,619 listed sources with a recorded baseline at the pin, it produced 2,031
-// `passed`, 1,562 `review-required` and 26 `needs-fixes` (counted by
+// 4,449 listed sources with a recorded baseline at the pin, it produced 2,451
+// `passed`, 1,962 `review-required` and 36 `needs-fixes` (counted by
 // registry.mjs baselineFigures, pinned by tests/unit/registry-figures.test.mjs). `review-required` is not a defect and
 // needs no source change, but it does mean a human must look, and it is the
 // single largest determinant of whether a submission waits on a person. An

package/tools/marketplace/registry.mjs

@@ -26,7 +26,7 @@
 
 import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
-import { MARKETPLACE_PIN, POLICY_MODULE, requirePin } from "./pin.mjs"
+import { MARKETPLACE_PIN, PIN_READS, POLICY_MODULE, catalogPresentation, requirePin, reservedNamespace } from "./pin.mjs"
 import { defaultBranchHead, getJson } from "./github.mjs"
 import { omakitCacheDir } from "./paths.mjs"
 
@@ -38,12 +38,14 @@ export const CATALOG_BUILDER_PATH = "scripts/build-catalog.mjs"
 export const LIVE_PATHS = Object.freeze([REGISTRY_PATH, CATALOG_PATH])
 
 /**
- * The one file read from HEAD as text and used for nothing: `omakit doctor`
- * reads the policy module at HEAD to compare its two constants with the
- * pin's (pin.mjs policyConstants) and drops the text. It is never imported,
- * never cached and never a source of a rule; the rules stay the pin's.
+ * The files read from HEAD as text and used for nothing but a comparison:
+ * `omakit doctor` reads the policy module at HEAD to compare its two
+ * constants with the pin's (pin.mjs policyConstants), and each file
+ * PIN_READS reads as text to compare the values its `readers` take out of
+ * it, and drops the text. None is ever imported, cached or a source of a
+ * rule; the rules stay the pin's.
  */
-export const HEAD_TEXT_PATHS = Object.freeze([POLICY_MODULE])
+export const HEAD_TEXT_PATHS = Object.freeze([POLICY_MODULE, ...PIN_READS.filter((read) => read.readers).map((read) => read.path)])
 
 export class RegistryError extends Error {
   constructor(code, message) {
@@ -62,45 +64,17 @@ function readJson(pinDir, relative) {
 }
 
 /**
- * The reserved namespace as the marketplace states it, read from the pinned
- * `build-catalog.mjs` next to its own `reserved-plugin-id` check. Read, not
- * copied, so a pin update moves it.
+ * The text of the pinned catalog builder, the one file under scripts/ this
+ * module reads: never imported (it imports `sharp`), read for the two
+ * values PIN_READS registers for it, `reservedNamespace` and
+ * `catalogPresentation` (pin.mjs). Those two are re-exported here, where
+ * the checks that use them have always found them.
  */
-export function reservedNamespace(pinDir) {
-  const source = readFileSync(join(pinDir, CATALOG_BUILDER_PATH), "utf8")
-  const match = source.match(/startsWith\("([A-Za-z0-9.\-_]+\.)"\)\s*\)\s*\{\s*\n\s*checkError\("reserved-plugin-id"/)
-    || source.match(/checkError\("reserved-plugin-id",\s*`[^`]*\$\{[^}]*\}:\s*the ([A-Za-z0-9.\-_]+)\.\*\s+namespace is reserved`/)
-  if (!match) {
-    throw new RegistryError(
-      "pin-unreadable",
-      `cannot read the reserved plugin-id namespace from ${CATALOG_BUILDER_PATH} at the pin; refusing to guess it`,
-    )
-  }
-  return match[1].endsWith(".") ? match[1] : `${match[1]}.`
+export function catalogBuilderText(pinDir) {
+  return readFileSync(join(pinDir, CATALOG_BUILDER_PATH), "utf8")
 }
 
-/**
- * How the marketplace itself presents a plugin it lists, read out of the
- * pinned `build-catalog.mjs` rather than copied: `categoryFor(kinds)` maps the
- * manifest's kinds to a category in order of its `if` lines, with a fallback,
- * and the tags are the first three kinds lowercased. `omakit submit` offers
- * these as the default answer when it has to ask for a category and tags, so
- * the default is the marketplace's own choice; a mapping that cannot be read
- * offers no default. tests/unit/registry-figures.test.mjs pins what the
- * mapping is at this commit, so a marketplace that changes it fails the suite
- * until the docs follow.
- *
- * @returns {{ rules: Array<{ kinds: string[], category: string }>, fallback: string|null, tagsFromKinds: boolean }}
- */
-export function catalogPresentation(pinDir) {
-  const source = readFileSync(join(pinDir, CATALOG_BUILDER_PATH), "utf8")
-  const body = source.match(/function categoryFor\([^)]*\)\s*\{([\s\S]*?)\n\}/)?.[1] || ""
-  const rules = [...body.matchAll(/if \(((?:kinds\.includes\("[^"]+"\)(?:\s*\|\|\s*)?)+)\) return "([^"]+)";/g)]
-    .map((match) => ({ kinds: [...match[1].matchAll(/"([^"]+)"/g)].map((kind) => kind[1]), category: match[2] }))
-  const fallback = body.match(/\n\s*return "([^"]+)";\s*$/)?.[1] || null
-  const tagsFromKinds = /tags:\s*kinds\.slice\(0,\s*3\)\.map\(\(kind\) => kind\.toLowerCase\(\)\)/.test(source)
-  return { rules, fallback, tagsFromKinds }
-}
+export { catalogPresentation, reservedNamespace }
 
 /**
  * The marketplace's own presentation for a manifest's kinds: the category its
@@ -149,8 +123,8 @@ export function sameRepository(a, b) {
  * a branch name, so the two files always come from the same commit and the
  * commit named in the output is the one they came from; never a path outside
  * LIVE_PATHS, so nothing executable can arrive this way. (headTextUrl below
- * reaches the same host for one module's text, which is compared and never
- * run.)
+ * reaches the same host for the text of the files doctor compares, which is
+ * compared and never run.)
  */
 export function liveFileUrl(commit, path) {
   if (!/^[0-9a-f]{40}$/.test(String(commit))) {
@@ -163,17 +137,17 @@ export function liveFileUrl(commit, path) {
 }
 
 /**
- * The same URL shape for the one file doctor reads from HEAD as text:
+ * The same URL shape for the files doctor reads from HEAD as text:
  * HEAD_TEXT_PATHS, at a 40-character commit, through the same host and the
- * same GET call site. Its text is compared and dropped; `liveFileUrl` still
- * refuses it, so nothing reads it as data.
+ * same GET call site. Their text is compared and dropped; `liveFileUrl`
+ * still refuses them, so nothing reads them as data.
  */
 export function headTextUrl(commit, path) {
   if (!/^[0-9a-f]{40}$/.test(String(commit))) {
     throw new RegistryError("usage", `a marketplace file is read at a 40-character commit, not "${commit}"`)
   }
   if (!HEAD_TEXT_PATHS.includes(path)) {
-    throw new RegistryError("usage", `${path} is never read from HEAD as text; only ${HEAD_TEXT_PATHS.join(" and ")} ${HEAD_TEXT_PATHS.length === 1 ? "is" : "are"}`)
+    throw new RegistryError("usage", `${path} is never read from HEAD as text; only ${HEAD_TEXT_PATHS.join(", ")} are`)
   }
   return rawFileUrl(commit, path)
 }
@@ -371,9 +345,17 @@ export function idUniverse(options = {}) {
     throw new RegistryError("pin-unreadable", "the pinned catalog and registry produced no listed ids or repositories")
   }
 
+  const reservedPrefix = reservedNamespace(catalogBuilderText(pinDir))
+  if (!reservedPrefix) {
+    throw new RegistryError(
+      "pin-unreadable",
+      `cannot read the reserved plugin-id namespace from ${CATALOG_BUILDER_PATH} at the pin; refusing to guess it`,
+    )
+  }
+
   return {
     pinDir,
-    reservedPrefix: reservedNamespace(pinDir),
+    reservedPrefix,
     listedIds,
     retiredIds,
     listedRepositories,