omakit 0.1.7 → 0.1.8

package/README.md

@@ -231,16 +231,20 @@ the cache. Bumping it changes where the submission contract and the baseline
 policy are read from, and the procedure in
 [docs/UPSTREAM_CONTRACT.md](docs/UPSTREAM_CONTRACT.md) ends in re-proving
 transport parity and committing the evidence. `omakit doctor` tells you when the
-pin is behind the marketplace's current branch, names which of the paths omakit
-reads actually changed (about 140 commits a day touch only `registry.json`, so
-"behind" alone would be true of every run), and then leaves it alone. That the
+pin is behind in something omakit reads from it, names which paths changed,
+and then leaves it alone: `registry.json` and `site/catalog.json` moving is
+fine, because those are read live from HEAD (about 140 commits a day touch
+only `registry.json`, so "behind" alone would be true of every run); the
+marketplace's code or forms moving is a note, and what you can do about it
+is run `omakit upgrade`, since a newer omakit may already carry the new pin,
+and otherwise open an issue naming the paths. That the
 pin can go stale unnoticed is the same defect class `omakit watch` reports, so it
 would be poor form to hide it here.
 
 ## Evidence, not claims
 
 ```bash
-npm test        # 147 tests, node --test, no dependencies
+npm test        # node --test, no dependencies; green from `git archive` too
 ```
 
 | Claim | Proof |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "The safe place to find out: everything knowable about an Omarchy Quattro plugin submission before you post it, on your own machine. Agent-first, read-only, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/skills/omarchy-plugin-submit/SKILL.md

@@ -57,7 +57,9 @@ omakit verify <path-to-the-plugin-repo> --json
 ```
 
 `verify` without `--json` prints a report for a person; `--json` is the
-document, unchanged between releases.
+document, unchanged between releases. It needs no network once the pin
+exists; a reviewer-mode target (`<https url>@<40-char sha>`) is fetched once,
+read-only, into omakit's own cache.
 
 Useful flags: `--notes` for the Maintainer notes field, `--suggest-tag` for the
 optional suggestion, `--name` when the manifest has no name, `--json` for a

package/tests/parity/run.mjs

@@ -14,6 +14,7 @@ import { createHash } from "node:crypto"
 import { execFileSync } from "node:child_process"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
 import { runBaseline } from "../../tools/marketplace/run-baseline.mjs"
 import { requirePin } from "../../tools/marketplace/pin.mjs"
 import { parityCorpus, strataSizes } from "./corpus.mjs"
@@ -22,14 +23,7 @@ import { token } from "../../tools/marketplace/github.mjs"
 import { omakitCacheDir } from "../../tools/marketplace/paths.mjs"
 import { parityOutput } from "../../tools/marketplace/parity-output.mjs"
 
-const repoRoot = resolve(process.env.OMAKIT_ROOT || process.cwd())
-const pinDir = requirePin(repoRoot).dir
-const cacheDir = omakitCacheDir("parity")
-const output = parityOutput({ repoRoot, out: process.env.PARITY_OUT || null })
-const count = Number(process.env.PARITY_COUNT || 30)
-const offset = Number(process.env.PARITY_OFFSET || 0)
-
-function shallowClone(repoUrl, commit) {
+function shallowClone(cacheDir, repoUrl, commit) {
   const dir = join(cacheDir, subjectSlug(repoUrl))
   mkdirSync(dir, { recursive: true })
   const run = (args) => execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
@@ -71,124 +65,162 @@ function pinCommit(dir) {
   }
 }
 
-const corpus = parityCorpus(pinDir, count, offset)
-const rows = []
-const ruleTotals = {}
-const capabilityTotals = {}
-let mismatches = 0
-let failures = 0
-
-for (const target of corpus) {
-  const row = {
-    repo: target.repo,
-    commit: target.commit,
-    type: target.type,
-    registryOutcome: target.registryOutcome,
-    registryOutcomeAtSameCommit: target.registryOutcomeCommit === target.commit,
-  }
+function generatorIdentity(repoRoot) {
   try {
-    const dir = shallowClone(target.repo, target.commit)
-    const local = await runBaseline({
-      repoRoot,
-      repoUrl: target.repo,
-      commitSha: target.commit,
-      transport: "local",
-      repoDir: dir,
-    })
-    row.localOutcome = local.result.outcome
-    row.requests = local.adapter.requests
-    row.localDigest = digest(local.result)
-    // Rule and capability ids are counted in the summary, unattributed; they are
-    // deliberately not recorded against this repository.
-    for (const finding of local.result.findings || []) {
-      const id = finding.ruleId || finding.id
-      if (id) ruleTotals[id] = (ruleTotals[id] || 0) + 1
-    }
-    for (const capability of local.result.capabilities || []) {
-      if (capability.id) capabilityTotals[capability.id] = (capabilityTotals[capability.id] || 0) + 1
+    return { omakitCommit: execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() }
+  } catch {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
+    return { omakitPackage: `${pkg.name}@${pkg.version}` }
+  }
+}
+
+/**
+ * The parity run. `cli.mjs` calls this with its own root and the flags it
+ * parsed; the adapter at the bottom of this file calls it from the command
+ * line. Everything the run needs arrives as an argument: omakit reads no
+ * environment variable of its own, and this handoff used to be four
+ * PARITY_* variables and an OMAKIT_ROOT, which was the one OMAKIT_* name in
+ * the tree and needed an exemption in the test that forbids them.
+ *
+ * @param {{ repoRoot: string, count?: number, offset?: number, out?: string|null, log?: (line: string) => void }} options
+ *   `out` is an explicit evidence file; without it the evidence lands in
+ *   `docs/evidence/parity/` under a dated name that never overwrites.
+ * @returns {Promise<{ summary: object, outFile: string, ok: boolean }>}
+ */
+export async function runParity({ repoRoot, count = 30, offset = 0, out = null, log = console.log }) {
+  const root = resolve(repoRoot)
+  const pinDir = requirePin(root).dir
+  const cacheDir = omakitCacheDir("parity")
+  // Resolved before any fetch, so a packaged read-only install refuses here.
+  const output = parityOutput({ repoRoot: root, out })
+  const corpus = parityCorpus(pinDir, count, offset)
+  const rows = []
+  const ruleTotals = {}
+  const capabilityTotals = {}
+  let mismatches = 0
+  let failures = 0
+
+  for (const target of corpus) {
+    const row = {
+      repo: target.repo,
+      commit: target.commit,
+      type: target.type,
+      registryOutcome: target.registryOutcome,
+      registryOutcomeAtSameCommit: target.registryOutcomeCommit === target.commit,
     }
     try {
-      const github = await runBaseline({
-        repoRoot,
+      const dir = shallowClone(cacheDir, target.repo, target.commit)
+      const local = await runBaseline({
+        repoRoot: root,
         repoUrl: target.repo,
         commitSha: target.commit,
-        transport: "github",
-        token: token() ?? undefined,
+        transport: "local",
+        repoDir: dir,
       })
-      row.githubOutcome = github.result.outcome
-      row.githubDigest = digest(github.result)
-      row.identical = row.localDigest === row.githubDigest
-      if (!row.identical) {
-        mismatches += 1
-        // A mismatch is the one case worth describing, and it is described as a
-        // difference between two transports of the same code, not as a finding
-        // about the plugin: which keys differ, never their contents.
-        const localPayload = JSON.parse(comparable(local.result))
-        const githubPayload = JSON.parse(comparable(github.result))
-        row.differingKeys = Object.keys(localPayload).filter(
-          (key) => JSON.stringify(localPayload[key]) !== JSON.stringify(githubPayload[key]),
-        )
+      row.localOutcome = local.result.outcome
+      row.requests = local.adapter.requests
+      row.localDigest = digest(local.result)
+      // Rule and capability ids are counted in the summary, unattributed; they are
+      // deliberately not recorded against this repository.
+      for (const finding of local.result.findings || []) {
+        const id = finding.ruleId || finding.id
+        if (id) ruleTotals[id] = (ruleTotals[id] || 0) + 1
+      }
+      for (const capability of local.result.capabilities || []) {
+        if (capability.id) capabilityTotals[capability.id] = (capabilityTotals[capability.id] || 0) + 1
+      }
+      try {
+        const github = await runBaseline({
+          repoRoot: root,
+          repoUrl: target.repo,
+          commitSha: target.commit,
+          transport: "github",
+          token: token() ?? undefined,
+        })
+        row.githubOutcome = github.result.outcome
+        row.githubDigest = digest(github.result)
+        row.identical = row.localDigest === row.githubDigest
+        if (!row.identical) {
+          mismatches += 1
+          // A mismatch is the one case worth describing, and it is described as a
+          // difference between two transports of the same code, not as a finding
+          // about the plugin: which keys differ, never their contents.
+          const localPayload = JSON.parse(comparable(local.result))
+          const githubPayload = JSON.parse(comparable(github.result))
+          row.differingKeys = Object.keys(localPayload).filter(
+            (key) => JSON.stringify(localPayload[key]) !== JSON.stringify(githubPayload[key]),
+          )
+        }
+      } catch (error) {
+        row.githubError = (error.code || "error") + ": " + error.message
+        failures += 1
       }
     } catch (error) {
-      row.githubError = (error.code || "error") + ": " + error.message
+      row.localError = (error.code || "error") + ": " + error.message
       failures += 1
     }
-  } catch (error) {
-    row.localError = (error.code || "error") + ": " + error.message
-    failures += 1
+    rows.push(row)
+    log(
+      [
+        row.identical === true ? "ok  " : row.identical === false ? "DIFF" : "??  ",
+        target.repo.replace("https://github.com/", "").padEnd(44),
+        "local=" + (row.localOutcome || row.localError || "-"),
+        "github=" + (row.githubOutcome || row.githubError || "-"),
+        "registry=" + (row.registryOutcome || "-"),
+      ].join(" "),
+    )
   }
-  rows.push(row)
-  console.log(
-    [
-      row.identical === true ? "ok  " : row.identical === false ? "DIFF" : "??  ",
-      target.repo.replace("https://github.com/", "").padEnd(44),
-      "local=" + (row.localOutcome || row.localError || "-"),
-      "github=" + (row.githubOutcome || row.githubError || "-"),
-      "registry=" + (row.registryOutcome || "-"),
-    ].join(" "),
-  )
-}
 
-function generatorIdentity() {
-  try {
-    return { omakitCommit: execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() }
-  } catch {
-    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
-    return { omakitPackage: `${pkg.name}@${pkg.version}` }
+  const summary = {
+    generator: generatorIdentity(root),
+    pinnedMarketplaceCommit: pinCommit(pinDir),
+    corpusSize: corpus.length,
+    requestedCount: count,
+    offset,
+    strata: strataSizes(count),
+    outcomes: rows.reduce((acc, row) => {
+      const key = row.localOutcome || "error"
+      acc[key] = (acc[key] || 0) + 1
+      return acc
+    }, {}),
+    identical: rows.filter((row) => row.identical === true).length,
+    mismatches,
+    failures,
+    // Unattributed aggregates. No repository name is attached to any rule.
+    ruleTotals,
+    capabilityTotals,
+    publication: {
+      perRepositoryDetail: "omitted",
+      reason: "Findings about a specific third-party plugin are not published. Equality is evidenced by the sha256 digests below, which anyone can recompute from the repository, the commit and the pinned marketplace commit.",
+      digest: "sha256 of {outcome, disposition, blocksApproval, findings, capabilities}, first 32 hex characters",
+    },
+    rows,
   }
+  const date = new Date().toISOString().slice(0, 10)
+  const outputIsFile = Boolean(out)
+  const outputDir = outputIsFile ? resolve(output, "..") : output
+  mkdirSync(outputDir, { recursive: true })
+  let outFile = outputIsFile ? output : join(outputDir, `${date}-local-vs-github.json`)
+  for (let n = 2; !outputIsFile && existsSync(outFile); n += 1) outFile = join(outputDir, `${date}-local-vs-github-${n}.json`)
+  writeFileSync(outFile, JSON.stringify(summary, null, 2) + "\n")
+  log("\nidentical " + summary.identical + "/" + corpus.length + ", mismatches " + mismatches + ", failures " + failures + " -> " + outFile)
+  return { summary, outFile, ok: mismatches === 0 && failures === 0 }
 }
 
-const summary = {
-  generator: generatorIdentity(),
-  pinnedMarketplaceCommit: pinCommit(pinDir),
-  corpusSize: corpus.length,
-  requestedCount: count,
-  offset,
-  strata: strataSizes(count),
-  outcomes: rows.reduce((acc, row) => {
-    const key = row.localOutcome || "error"
-    acc[key] = (acc[key] || 0) + 1
-    return acc
-  }, {}),
-  identical: rows.filter((row) => row.identical === true).length,
-  mismatches,
-  failures,
-  // Unattributed aggregates. No repository name is attached to any rule.
-  ruleTotals,
-  capabilityTotals,
-  publication: {
-    perRepositoryDetail: "omitted",
-    reason: "Findings about a specific third-party plugin are not published. Equality is evidenced by the sha256 digests below, which anyone can recompute from the repository, the commit and the pinned marketplace commit.",
-    digest: "sha256 of {outcome, disposition, blocksApproval, findings, capabilities}, first 32 hex characters",
-  },
-  rows,
+// The command-line adapter: `node tests/parity/run.mjs [--count n] [--offset n]
+// [--out file]` from the repository root. Thin on purpose; `omakit parity`
+// is the same call with cli.mjs's own root.
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const args = process.argv.slice(2)
+  const flag = (name) => {
+    const index = args.indexOf(name)
+    return index >= 0 ? args[index + 1] : undefined
+  }
+  const { ok } = await runParity({
+    repoRoot: process.cwd(),
+    count: Number(flag("--count") || 30),
+    offset: Number(flag("--offset") || 0),
+    out: flag("--out") || null,
+  })
+  process.exit(ok ? 0 : 1)
 }
-const date = new Date().toISOString().slice(0, 10)
-const outputIsFile = process.env.PARITY_OUT_EXPLICIT === "1"
-const outputDir = outputIsFile ? resolve(output, "..") : output
-mkdirSync(outputDir, { recursive: true })
-let outFile = outputIsFile ? output : join(outputDir, `${date}-local-vs-github.json`)
-for (let n = 2; !outputIsFile && existsSync(outFile); n += 1) outFile = join(outputDir, `${date}-local-vs-github-${n}.json`)
-writeFileSync(outFile, JSON.stringify(summary, null, 2) + "\n")
-console.log("\nidentical " + summary.identical + "/" + corpus.length + ", mismatches " + mismatches + ", failures " + failures + " -> " + outFile)
-process.exit(mismatches === 0 && failures === 0 ? 0 : 1)

package/tools/marketplace/README.md

@@ -19,11 +19,12 @@ local commit through the transport seam the marketplace tests itself
 | `plugin.mjs` | The root files the submission contract needs, and the declared plugin identity. |
 | `agent-control.mjs` | The recursive agent-control warning, and its remedy. |
 | `issue.mjs` | Renders the issue the way the form would, then has the marketplace's own parser judge it. |
-| `submit.mjs` | Assembles every check with its measured reason, and withholds the body when a blocking check fails. Three outcomes: `ready` (the body), `refused` (a blocking check failed) and `listed` (the plugin is already listed by its own repository: `identity.available` passes with the listing's record, the five body checks are omitted rather than drawn as waiting, no body exists on purpose, and `listing` carries the listed commit against the local one and the form to use for a newer commit). Decides the category and tags after the registry: a listed plugin, own or taken, is asked for neither; an unlisted one without them is asked through `ask.mjs` at a terminal, and is a usage error otherwise. Ends with `reproduce`, the command line that repeats the run without asking. |
+| `submit.mjs` | Assembles every check with its measured reason, and withholds the body when a blocking check fails. Three outcomes: `ready` (the body), `refused` (a blocking check failed) and `listed` (the plugin is already listed by its own repository: `identity.available` passes with the listing's record, the five body checks are omitted rather than drawn as waiting, no body exists on purpose, and `listing` carries the listed commit against the local one and the form to use for a newer commit). Decides the category and tags after the registry: a listed plugin, own or taken, is asked for neither; an unlisted one without them is asked through `ask.mjs` at a terminal, and is a usage error otherwise. Ends with `reproduce`, the command line that repeats the run without asking. Under `--offline` the validation-commit check is `skipped`, not passed: verdict `skipped`, listed under `skipped` and not `unknown`, never blocking, and the READY line says "1 check skipped (--offline)". |
 | `ask.mjs` | The two questions `submit` asks a person at a terminal, and only there: category and tags, numbered from the pinned form, with the marketplace's own presentation for the manifest's kinds (read from the pinned catalog builder) as the default where it is on the list. Prompts on stderr, nothing persisted. |
+| `doctor.mjs` | What is installed, what is pinned, and what has moved. `pin.freshness` compares each path in `PIN_PATHS` between the pin and the marketplace's HEAD by tree or blob id and splits what moved by the list `registry.mjs` reads live from: `registry.json` and `site/catalog.json` moving is `ok`, because those are read from HEAD anyway; anything else moving (`scripts/`, the two forms) is a `note` naming the paths, with an action a user can take, `omakit upgrade` and then an issue at the repository named in package.json. The maintainer's pin procedure stays in `docs/UPSTREAM_CONTRACT.md` and is never printed. HEAD unreadable is `unknown`. `--json` carries `changedPaths`, `readLive` and `pinned` under the check's evidence. |
 | `watch.mjs` | The validation watch: validated commit versus current default-branch HEAD, and the one action that refreshes it. |
 | `github.mjs` | Read-only GitHub access. GET only. The credential is your `gh` login, read through one frozen `gh auth token` call, and is never written anywhere. |
-| `style.mjs` | The visual system, defined once: the palette, the status vocabulary, the block ramp, the columns, the motion budgets, and the composition helpers every command draws with. `docs/TUI.md` explains it. |
+| `style.mjs` | The visual system, defined once: the palette, the status vocabulary, the block ramp, the columns, the motion budgets, and the composition helpers every command draws with. Six states: `▁ ok`, `█ FAIL`, `▓ note`, `░ info`, `▒ ?` for a check that could not be made, and `▔ skip` for a check a flag said not to make, the floor's ink at the ceiling so it is never read as a pass. `docs/TUI.md` explains it. |
 | `report.mjs` | Text rendering of submit, watch, doctor and verify for the agent that runs this tool, and the person reading over its shoulder. |
 | `path-hint.mjs` | Is `omakit` reachable as a bare command, and if not, the one line that makes it so for the install that is here: a symlink for a clone, the npm prefix's `bin` on PATH for a package, said for the shell in `$SHELL`. `setup` and `doctor` print it; nothing writes an rc file. |
 | `usage.mjs` | The help text, as data. |
@@ -60,6 +61,19 @@ the registry recorded so the corpus always contains repositories that are not
 side rather than the findings themselves. The GitHub side uses whatever
 credential `github.mjs` resolves (a `gh` login, and only that), read-only.
 
+Two rules about the output, stated as rules because each is an exception to
+a wider one. Everything omakit writes itself stays within 80 columns; text
+that will be posted verbatim, the marketplace's own baseline report and the
+issue body rendered from the pinned form, is never wrapped and may exceed 80,
+because a wrapped body would not be the body. And stdout is the whole result;
+stderr carries interactive decoration, the progress line from `progress.mjs`
+and the chooser from `ask.mjs`, only when stderr is a TTY, so a piped stderr
+is empty on success, and failures go to stderr always. `tests/unit/cli.test.mjs`
+holds both: the width test names the two verbatim regions by their heading
+and holds every other line to 80, the three-way test asserts the empty pipe,
+and a pseudo-terminal test asserts that a terminal's stderr gets the progress
+sequences and nothing else.
+
 `parity`, `watch`, `doctor` and `submit` reach the network, with Node's
 built-in `fetch`, which does not read proxy environment variables by default.
 Behind a proxy, run them with `NODE_USE_ENV_PROXY=1`. `submit` reads two things

package/tools/marketplace/cli.mjs

@@ -30,7 +30,6 @@ import { banner, bannerEnabled } from "./banner.mjs"
 import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
 import { action, colourEnabled, GUTTER, labelled, mark, styler, wrap } from "./style.mjs"
 import { omakitCacheDir } from "./paths.mjs"
-import { parityOutput } from "./parity-output.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -84,6 +83,18 @@ function positionals(args) {
   return args.filter((value, index) => !value.startsWith("--") && !valued.has(args[index - 1]))
 }
 
+/**
+ * The progress line for a command, or nothing under --json: a machine
+ * reading the document on stdout gets no decoration on stderr either.
+ * Measured on 0.1.6: submit, watch and doctor silenced it and verify did
+ * not, so `verify --json` at a terminal drew a progress line the others
+ * never drew.
+ */
+const SILENT = Object.freeze({ phase: () => {}, done: () => {} })
+function spinnerFor(args) {
+  return args.includes("--json") ? SILENT : progress()
+}
+
 function emit(args, text) {
   const out = option(args, "--out")
   if (out) {
@@ -100,7 +111,7 @@ async function cmdSubmit(args) {
   const target = positionals(args)[0]
   if (!target) fail("usage", "submit needs a target: `omakit submit <target> --category <c> --tags <a,b>`", 2)
   const json = args.includes("--json")
-  const spinner = json ? { phase: () => {}, done: () => {} } : progress()
+  const spinner = spinnerFor(args)
   // A missing --category or --tags on an unlisted plugin is asked for, once
   // each, when a person is at a terminal on both ends and no machine is
   // reading the result. Anything else, a pipe, an agent, --json, gets the
@@ -156,7 +167,7 @@ async function cmdSubmit(args) {
 async function cmdWatch(args) {
   const issueUrl = positionals(args)[0]
   if (!issueUrl) fail("usage", "watch needs an issue: `omakit watch <issue-url>`", 2)
-  const spinner = args.includes("--json") ? { phase: () => {}, done: () => {} } : progress()
+  const spinner = spinnerFor(args)
   let result
   try {
     result = await validationWatch({ repoRoot: ROOT, issueUrl, onPhase: spinner.phase })
@@ -189,7 +200,7 @@ async function cmdUpgrade(args) {
 }
 
 async function cmdDoctor(args) {
-  const spinner = args.includes("--json") ? { phase: () => {}, done: () => {} } : progress()
+  const spinner = spinnerFor(args)
   const result = await doctor({ repoRoot: ROOT, offline: args.includes("--offline"), onPhase: spinner.phase })
   spinner.done()
   emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderDoctor(result))
@@ -206,7 +217,7 @@ async function cmdVerify(args) {
     if (error instanceof SubjectError) fail(error.code, error.message, error.code === "usage" ? 2 : 1)
     throw error
   }
-  const spinner = progress()
+  const spinner = spinnerFor(args)
   let section
   try {
     spinner.phase("running the official security baseline over a local snapshot")
@@ -239,23 +250,27 @@ async function cmdVerify(args) {
 }
 
 async function cmdParity(args) {
-  const count = option(args, "--count")
-  const offset = option(args, "--offset")
-  if (count) process.env.PARITY_COUNT = count
-  if (offset) process.env.PARITY_OFFSET = offset
+  // The runner takes everything as arguments. Before 0.1.8 this handed over
+  // four PARITY_* variables and an OMAKIT_ROOT through the process
+  // environment, and OMAKIT_ROOT was the one OMAKIT_* name in the tree.
+  let ok = false
   try {
-    const out = option(args, "--out")
-    process.env.PARITY_OUT = parityOutput({ repoRoot: ROOT, out })
-    if (out) process.env.PARITY_OUT_EXPLICIT = "1"
-  } catch (error) {
-    failFrom(error)
-  }
-  process.env.OMAKIT_ROOT = ROOT
-  try {
-    await import("../../tests/parity/run.mjs")
+    // Imported here, not at the top: the runner ships with the package, but
+    // no other command needs it, and a copy of bin/ and tools/ alone runs
+    // everything else.
+    const { runParity } = await import("../../tests/parity/run.mjs")
+    const count = option(args, "--count")
+    const offset = option(args, "--offset")
+    ;({ ok } = await runParity({
+      repoRoot: ROOT,
+      count: count ? Number(count) : undefined,
+      offset: offset ? Number(offset) : undefined,
+      out: option(args, "--out") || null,
+    }))
   } catch (error) {
     failFrom(error)
   }
+  process.exit(ok ? 0 : 1)
 }
 
 const [command, ...rest] = process.argv.slice(2)

package/tools/marketplace/doctor.mjs

@@ -13,33 +13,51 @@
 // contract is read from, and the procedure in docs/UPSTREAM_CONTRACT.md requires
 // re-proving transport parity and committing the evidence afterwards. An
 // `upgrade` that quietly advanced the pin would break the one guarantee this
-// tool sells. So doctor reports that the pin is behind and prints the procedure.
+// tool sells. So doctor reports that the pin is behind, and that is all it
+// does: the procedure is the maintainer's, it lives in that document and in
+// this comment, and it is never printed, because the person running doctor
+// is a user of a package that does not even ship docs/. What a user can do
+// is run `omakit upgrade`, since a newer omakit may already carry the new
+// pin, and otherwise open an issue naming the paths that moved.
 //
 // That the pin goes stale unnoticed is, of course, exactly the defect class
 // `omakit watch` exists to report. It would be poor form not to apply it here.
 //
 // And "behind" is not the same as "behind in something omakit reads". Measured
 // on 2026-09-13 (docs/MEASUREMENTS.md M7): 4,201 of the marketplace's 4,293
-// commits in 30 days touched only registry.json, which omakit now reads live,
+// commits in 30 days touched only registry.json, which omakit reads live,
 // while nothing under scripts/ or .github/ISSUE_TEMPLATE/ changed since the
 // pin. A doctor that only said "behind" would say it about every run. So it
 // compares each path in PIN_PATHS between the pin and HEAD, by tree or blob
-// id, and names the ones that moved.
+// id, and splits the ones that moved by the same list registry.mjs reads
+// live from: the two data files, which a moved HEAD cannot make stale, and
+// everything else, which only a new pin can carry. Measured on 0.1.7: with
+// only registry.json and site/catalog.json moved, doctor said `note` and
+// pointed a user at docs/UPSTREAM_CONTRACT.md, though the pin was behind in
+// nothing the tool uses.
 
 import { execFileSync } from "node:child_process"
 import { readFileSync } from "node:fs"
 import { join } from "node:path"
 import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
+import { LIVE_PATHS } from "./registry.mjs"
 import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
 import { latestOnRegistry, upgradeCommand } from "./upgrade.mjs"
 import { pathHint } from "./path-hint.mjs"
 
+/** "git+https://github.com/owner/name.git" in package.json -> "https://github.com/owner/name", or null. */
+function repositoryPage(repository) {
+  const url = typeof repository === "string" ? repository : repository?.url
+  const match = String(url || "").match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/)
+  return match ? `https://github.com/${match[1]}/${match[2]}` : null
+}
+
 function tool(repoRoot) {
   try {
     const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
-    return { name: pkg.name, version: pkg.version, engines: pkg.engines?.node || null }
+    return { name: pkg.name, version: pkg.version, engines: pkg.engines?.node || null, repository: repositoryPage(pkg.repository) }
   } catch {
-    return { name: "omakit", version: "unknown", engines: null }
+    return { name: "omakit", version: "unknown", engines: null, repository: null }
   }
 }
 
@@ -102,40 +120,65 @@ export async function changedPinPaths({ pinDir, headCommit, pinCommit = MARKETPL
   return changed
 }
 
+/** A PIN_PATHS pattern as a path: "/site/catalog.json" -> "site/catalog.json". */
+const asPath = (pattern) => pattern.replace(/^\/|\/$/g, "")
+
+/** "a", "a and b", "a, b and c". */
+function list(items) {
+  return items.length < 3 ? items.join(" and ") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`
+}
+
 /**
- * Full pin evidence for machines; human output deliberately keeps short
- * hashes. `changedPaths` is the answer from changedPinPaths(); null when the
- * comparison was not made, and then the detail says only that HEAD moved.
+ * The pin against the marketplace's HEAD, for a user. `changedPaths` is the
+ * answer from changedPinPaths(), split by LIVE_PATHS into `readLive`, the
+ * data files a moved HEAD cannot make stale because registry.mjs reads them
+ * from HEAD, and `pinned`, everything only a new pin can carry. Only the
+ * second set is worth a note; the action for it is a user's, not the
+ * maintainer's. Null when the comparison was not made, and then the detail
+ * says only that HEAD moved. Full commits in the evidence; short ones in
+ * the detail. `issues` is where a user reports a pinned path that moved,
+ * read from package.json by the caller.
  */
-export function pinFreshness(identity, head, changedPaths = null) {
+export function pinFreshness(identity, head, changedPaths = null, { issues = null } = {}) {
   const current = head.commit === identity.commit
   const branch = head.branch || "default"
+  const changed = current ? [] : changedPaths || []
+  const readLive = changed.filter((pattern) => LIVE_PATHS.includes(asPath(pattern)))
+  const pinned = changed.filter((pattern) => !LIVE_PATHS.includes(asPath(pattern)))
+  const where = `pin ${identity.commit.slice(0, 7)}; marketplace ${branch} at ${head.commit.slice(0, 7)}`
   const moved = changedPaths === null
-    ? ""
-    : changedPaths.length
-      ? `; changed since the pin: ${changedPaths.join(", ")}`
-      : "; every path omakit reads is unchanged since the pin"
+    ? "; the paths omakit reads were not compared"
+    : pinned.length
+      ? `; changed since the pin: ${pinned.join(", ")}${readLive.length ? ` (${list(readLive.map(asPath))} moved too, and ${readLive.length === 1 ? "that is" : "those are"} read live)` : ""}`
+      : readLive.length
+        ? `; only ${list(readLive.map(asPath))} moved, and ${readLive.length === 1 ? "that is" : "those are"} read live`
+        : "; nothing omakit reads moved"
+  const stale = !current && (changedPaths === null || pinned.length > 0)
   return {
     id: "pin.freshness",
-    state: current ? "ok" : "advice",
-    detail: current
-      ? `the pin is the marketplace's current ${branch}-branch HEAD`
-      : `the pin is ${identity.commit.slice(0, 7)}; the marketplace's ${branch} branch is now at ${head.commit.slice(0, 7)}${moved}`,
-    action: current ? null : "Bumping the pin is a deliberate change: docs/UPSTREAM_CONTRACT.md has the procedure, which ends in re-proving parity and committing its evidence. Nothing here does it for you.",
+    state: stale ? "advice" : "ok",
+    detail: current ? `the pin is the marketplace's current ${branch}-branch HEAD` : `${where}${moved}`,
+    action: stale
+      ? `A newer omakit may already carry the new pin: run \`omakit upgrade\`. If it does not, open an issue${issues ? ` at ${issues}/issues` : ""} naming the paths above.`
+      : null,
     evidence: {
       pinCommit: identity.commit,
       marketplaceHead: head.commit,
       branch,
-      ...(changedPaths === null ? {} : { changedPaths: current ? [] : changedPaths }),
+      ...(changedPaths === null ? {} : { changedPaths: changed, readLive, pinned }),
     },
   }
 }
 
 /**
- * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null }} options
- *   `env` and `npmPrefix` are injectable for tests of the PATH check.
+ * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null,
+ *           resolveHead?: typeof defaultBranchHead, latest?: typeof latestOnRegistry }} options
+ *   `env` and `npmPrefix` are injectable for tests of the PATH check;
+ *   `resolveHead` and `latest` for tests of the two checks that read the
+ *   network, whose defaults are the tool's one HEAD resolver and its one
+ *   registry read.
  */
-export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix }) {
+export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = latestOnRegistry }) {
   // Optional: told what is being read while the network answers. Never
   // affects the result.
   const phase = onPhase || (() => {})
@@ -185,13 +228,13 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
   if (!offline && identity) {
     phase("reading the marketplace's current default-branch HEAD")
     try {
-      const head = await defaultBranchHead(MARKETPLACE_PIN.repository)
+      const head = await resolveHead(MARKETPLACE_PIN.repository)
       let changedPaths = []
       if (head.commit !== identity.commit) {
         phase("comparing each path omakit reads between the pin and HEAD")
         changedPaths = await changedPinPaths({ pinDir: dir, headCommit: head.commit, pinCommit: identity.commit })
       }
-      checks.push(pinFreshness(identity, head, changedPaths))
+      checks.push(pinFreshness(identity, head, changedPaths, { issues: self.repository }))
     } catch (error) {
       add("pin.freshness", "unknown", `could not read the marketplace's HEAD (${error.code || "error"})`,
         error.code === "network-unavailable" ? "Connect to the network, or pass --offline to skip the two checks that need it." : null,
@@ -199,7 +242,7 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
     }
 
     phase("asking the npm registry for the newest published version")
-    const latest = await latestOnRegistry(self.name)
+    const latest = await latestVersion(self.name)
     if (latest) {
       const current = latest === self.version
       add("omakit.latest", current ? "ok" : "advice",

package/tools/marketplace/report.mjs

@@ -23,10 +23,11 @@ import {
 
 const body = " ".repeat(GUTTER)
 
-/** The state a check renders in: an advisory failure is a note, not a FAIL, and a check that waited on another is a question. */
+/** The state a check renders in: an advisory failure is a note, not a FAIL, a check that waited on another is a question, and a check a flag skipped says so. */
 function stateOf(check) {
   if (check.verdict === "pass") return "pass"
   if (check.verdict === "unknown") return "unknown"
+  if (check.verdict === "skipped") return "skipped"
   return check.severity === "advisory" ? "advisory" : "fail"
 }
 
@@ -101,10 +102,10 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
   out.push(...field("marketplace", `${result.pin.commit}, baseline ${result.pin.baselineVersion}, ${result.pin.enforcementMode}`, c))
   out.push("")
 
-  // Passing checks run together, and so does a check that waited on another:
-  // both are two quiet lines. Anything else gets a blank line on each side,
-  // collapsed where two blocks meet.
-  const quiet = (state) => state === "pass" || state === "unknown"
+  // Passing checks run together, and so do a check that waited on another
+  // and one a flag skipped: all are two quiet lines. Anything else gets a
+  // blank line on each side, collapsed where two blocks meet.
+  const quiet = (state) => state === "pass" || state === "unknown" || state === "skipped"
   let previous = "pass"
   for (const [index, check] of result.checks.entries()) {
     const state = stateOf(check)
@@ -168,7 +169,12 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
   const validation = result.validationCommit.defaultBranchHead
     ? `${result.validationCommit.local} is the ${result.validationCommit.branch || "default"}-branch HEAD, so it is the commit the marketplace will validate.`
     : `${result.validationCommit.local} is the local commit; the marketplace validates the default-branch HEAD it resolves when the issue is opened.`
-  out.push(...verdict("pass", "READY", `every blocking check passed. ${validation}`, c))
+  // A skipped check is said on the READY line itself, so the one line an
+  // agent quotes does not read as "everything passed" when one check never
+  // ran. The count is the whole `skipped` list; today only --offline skips.
+  const skipped = (result.skipped || []).length
+  const skippedNote = skipped ? ` ${skipped === 1 ? "1 check" : `${skipped} checks`} skipped (--offline).` : ""
+  out.push(...verdict("pass", "READY", `every blocking check passed.${skippedNote} ${validation}`, c))
   out.push("")
   out.push(...section("issue title", c))
   out.push(c("heading", result.issue.title))

package/tools/marketplace/style.mjs

@@ -162,6 +162,7 @@ export const DENSITY = Object.freeze({
   medium: "▒", // ▒  unknown: neither here nor there
   light: "░", // ░  information: present, weightless
   floor: "▁", // ▁  settled: a pass, a rule, the track the scanner runs on
+  ceiling: "▔", // ▔  skipped: the floor's own ink, never landed, because a flag said not to look
 })
 
 /** The glyph that starts the one line that fixes things. */
@@ -170,15 +171,23 @@ export const ARROW = "→"
 // --- the status vocabulary ---------------------------------------------------
 
 /**
- * Five states, and only five. Each has one glyph, one word and one tint, and
+ * Six states, and only six. Each has one glyph, one word and one tint, and
  * every command prints them through `mark()` below. `pass` and `fail` are
  * verdicts; `advisory` is a failure that does not block; `info` is a fact with
- * no verdict; `unknown` is a check that could not be made.
+ * no verdict; `unknown` is a check that could not be made; `skipped` is a
+ * check that was not made because a flag said not to (`--offline`).
  *
  * The glyph is the density ramp read as severity: the more ink, the more it
  * matters. The word is the same thing in letters, and its case carries it too:
  * FAIL is the only upper-case mark, so it is the one the eye lands on in a
  * column of lower-case ones, with or without colour.
+ *
+ * `skipped` and `unknown` are one family: neither has a verdict, both wear the
+ * same tint, and only the glyph and the word tell them apart. Measured on
+ * 0.1.6: `--offline` drew the skipped validation-commit check as `▁ ok`, and
+ * `--json` said `"verdict": "pass"`, for a comparison that never happened. The
+ * skipped mark is the floor's ink at the ceiling: the same weight as a pass,
+ * visibly not landed on one, on a theme that shows no hue.
  */
 export const STATUS = Object.freeze({
   pass: Object.freeze({ glyph: DENSITY.floor, word: "ok", tint: "pass" }),
@@ -186,6 +195,7 @@ export const STATUS = Object.freeze({
   advisory: Object.freeze({ glyph: DENSITY.dark, word: "note", tint: "advisory" }),
   info: Object.freeze({ glyph: DENSITY.light, word: "info", tint: "info" }),
   unknown: Object.freeze({ glyph: DENSITY.medium, word: "?", tint: "unknown" }),
+  skipped: Object.freeze({ glyph: DENSITY.ceiling, word: "skip", tint: "unknown" }),
 })
 
 /** The width of the widest mark, "█ FAIL"; every mark is padded to it so the names beside them align. */
@@ -360,7 +370,7 @@ export function wrap(text, { indent = 0, width: total = COLUMNS, first = indent
  * after it starts at GUTTER. This is the only place a status is turned into
  * characters.
  *
- * @param {"pass"|"fail"|"advisory"|"info"|"unknown"} state
+ * @param {"pass"|"fail"|"advisory"|"info"|"unknown"|"skipped"} state
  * @param {(name: string, text: string) => string} c
  */
 export function mark(state, c) {

package/tools/marketplace/submit.mjs

@@ -56,7 +56,7 @@ export class SubmitError extends Error {
 }
 
 /**
- * A check has three verdicts. `pass` and `fail` are its own. `unknown` is
+ * A check has four verdicts. `pass` and `fail` are its own. `unknown` is
  * for a check that could not run because one it depends on failed: it is
  * rendered as a question, its detail names what it waited on, and it counts
  * in neither `blocking` nor `advisory`, so a refusal lists root causes only.
@@ -65,19 +65,28 @@ export class SubmitError extends Error {
  * checklist and official-parser each failed for want of a body nobody could
  * render yet, and the closing refusal listed them with "not rendered" where
  * a remedy goes.
+ *
+ * `skipped` is for a check that was not made because a flag said not to,
+ * independent of `waitedOn`: it never blocks, it counts in `skipped` and
+ * not in `unknown`, and its detail says which flag. Measured on 0.1.6:
+ * `--offline` handed `verdict: true` to the validation-commit check, so
+ * `--json` said `"verdict": "pass"` and the report drew `▁ ok` for a
+ * comparison that never happened, and an agent reading `checks` rather than
+ * the prose could tell the owner every check passed.
  */
 function check(id, fields) {
   const waitedOn = (fields.waitedOn || []).filter(Boolean)
+  const skipped = fields.skipped === true
   return {
     id,
     source: fields.source,
     why: fields.why,
     severity: fields.severity || "blocking",
-    verdict: waitedOn.length ? "unknown" : fields.verdict ? "pass" : "fail",
-    detail: waitedOn.length ? `not checked: it needs ${waitedOn.join(" and ")} to pass first` : fields.detail || "",
+    verdict: skipped ? "skipped" : waitedOn.length ? "unknown" : fields.verdict ? "pass" : "fail",
+    detail: !skipped && waitedOn.length ? `not checked: it needs ${waitedOn.join(" and ")} to pass first` : fields.detail || "",
     paths: fields.paths || [],
     // One arrow, or one per cause in the order they should be read.
-    remedy: waitedOn.length ? null : Array.isArray(fields.remedy) ? (fields.remedy.length ? fields.remedy : null) : fields.remedy || null,
+    remedy: skipped || waitedOn.length ? null : Array.isArray(fields.remedy) ? (fields.remedy.length ? fields.remedy : null) : fields.remedy || null,
   }
 }
 
@@ -405,7 +414,8 @@ export async function submitPreflight(options) {
     source: "omakit",
     why: "The marketplace validates the default-branch HEAD it resolves when the issue is opened or edited, not the commit checked here. 73% of the 464 submissions parked in the author's court have a HEAD ahead of their validated commit, so a preflight against a commit that is not the pushed HEAD describes a tree nobody will review. Not a marketplace rule; an Omakit refusal to report on the wrong tree.",
     severity: options.offline ? "advisory" : "blocking",
-    verdict: options.offline ? true : validationMatches === true,
+    skipped: options.offline === true,
+    verdict: validationMatches === true,
     detail: options.offline
       ? `not checked (--offline). Local commit ${subject.commit}.`
       : head
@@ -454,6 +464,7 @@ export async function submitPreflight(options) {
   const blocking = checks.filter((entry) => entry.severity === "blocking" && entry.verdict === "fail")
   const advisory = checks.filter((entry) => entry.severity === "advisory" && entry.verdict === "fail")
   const unknown = checks.filter((entry) => entry.verdict === "unknown")
+  const skipped = checks.filter((entry) => entry.verdict === "skipped")
   // Three outcomes. `refused`: a blocking check failed and no body exists.
   // `listed`: nothing failed and the plugin is already listed by this
   // repository, so there is no body either, and nothing is wrong. `ready`:
@@ -506,6 +517,7 @@ export async function submitPreflight(options) {
     blocking: blocking.map((entry) => entry.id),
     advisory: advisory.map((entry) => entry.id),
     unknown: unknown.map((entry) => entry.id),
+    skipped: skipped.map((entry) => entry.id),
     issue: ready ? issue : null,
     baseline: preflight.invoked
       ? {

package/tools/marketplace/usage.mjs

@@ -118,10 +118,11 @@ export const TARGET_NOTE = "<target> is a local Git repository path, or <https u
  */
 export const AUTHENTICATION = Object.freeze([
   "Read-only, and optional. omakit uses your `gh` login if you have one, and",
-  "otherwise goes unauthenticated. `verify` needs no network; `submit` reads",
-  "two things online and `--offline` turns both off; `watch` and `parity` are",
-  `capped at ${UNAUTHENTICATED_LIMIT} requests an hour without a login. omakit never writes a`,
-  "credential anywhere.",
+  "otherwise goes unauthenticated. `verify` needs no network once the pin",
+  "exists, except to fetch a reviewer-mode <https url>@<sha> target, once;",
+  "`submit` reads two things online and `--offline` turns both off; `watch` and",
+  `\`parity\` are capped at ${UNAUTHENTICATED_LIMIT} requests an hour without a login. omakit never`,
+  "writes a credential anywhere.",
 ])
 
 /**

package/tools/marketplace/watch.mjs

@@ -106,12 +106,17 @@ export function validationCommentCommit(comments) {
 }
 
 /**
- * @param {{ repoRoot: string, issueUrl: string }} options
+ * @param {{ repoRoot: string, issueUrl: string, onPhase?: (name: string) => void,
+ *           github?: { issue?: typeof issue, issueComments?: typeof issueComments, defaultBranchHead?: typeof defaultBranchHead } }} options
+ *   `github` is injectable for tests, so the whole path from an issue body to
+ *   a verdict can be run on data that never left the machine; the default is
+ *   the read-only GitHub access in `github.mjs`.
  */
-export async function validationWatch({ repoRoot, issueUrl, onPhase }) {
+export async function validationWatch({ repoRoot, issueUrl, onPhase, github = {} }) {
   // Optional: told the name of the step about to run, so a terminal can say
   // what is happening while the network answers. Never affects the result.
   const phase = onPhase || (() => {})
+  const read = { issue, issueComments, defaultBranchHead, ...github }
   const { dir: pinDir } = requirePin(repoRoot)
   const target = parseIssueUrl(issueUrl)
   if (`${target.owner}/${target.repository}`.toLowerCase() !== MARKETPLACE_SLUG) {
@@ -124,14 +129,14 @@ export async function validationWatch({ repoRoot, issueUrl, onPhase }) {
   const record = await loadRecord(pinDir)
 
   phase(`reading issue #${target.number}`)
-  const subject = await issue(target.owner, target.repository, target.number)
+  const subject = await read.issue(target.owner, target.repository, target.number)
   phase(`reading the comments on issue #${target.number}`)
-  const comments = await issueComments(target.owner, target.repository, target.number)
+  const comments = await read.issueComments(target.owner, target.repository, target.number)
 
-  const read = await repositoryFor(pinDir, subject)
-  const repositoryUrl = read.url
-  const repositoryError = read.error
-  const issueKind = read.kind
+  const repository = await repositoryFor(pinDir, subject)
+  const repositoryUrl = repository.url
+  const repositoryError = repository.error
+  const issueKind = repository.kind
 
   let validated = null
   let baselineError = null
@@ -164,7 +169,7 @@ export async function validationWatch({ repoRoot, issueUrl, onPhase }) {
   if (repositoryUrl) {
     phase("reading the plugin repository's default-branch HEAD")
     try {
-      head = await defaultBranchHead(repositoryUrl)
+      head = await read.defaultBranchHead(repositoryUrl)
     } catch (error) {
       headError = { code: error.code || "head-unreadable", message: error.message }
     }
@@ -202,11 +207,16 @@ export async function validationWatch({ repoRoot, issueUrl, onPhase }) {
     baselineError,
     head,
     headError,
-    verdict: validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview }),
+    verdict: validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview, repositoryUrl }),
   }
 }
 
-export function validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview, repositoryUrl = "unknown" }) {
+// `repositoryUrl` has no default on purpose. Measured on 0.1.6: the command
+// computed it and then did not pass it, and the parameter defaulted to the
+// truthy string "unknown", so an issue whose body named no repository was
+// reported as a HEAD that could not be read, and the branch below that names
+// the real cause was reachable from the unit test alone.
+export function validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview, repositoryUrl }) {
   if (baselineError) {
     return {
       state: "unknown",