omakit 0.1.6 → 0.1.8

package/README.md

@@ -134,16 +134,32 @@ file and line, and the official text verbatim, then the marketplace's own
 statement. `--json` prints the document itself, unchanged from earlier
 releases, and `--out <file>` writes it; agents and the skills use those.
 
-`omakit submit` reads the marketplace's registry first. A plugin that is
-already listed is refused there and asked for nothing (measured on 0.1.5: it
-exited 2 asking for `--category` and `--tags`, then would have said there was
-nothing to submit). An unlisted plugin needs both, and they are an editorial
+`omakit submit` reads the marketplace's registry first, and a run has three
+outcomes. `READY`, exit 0: every blocking check passed and the title and body
+follow. `REFUSED`, exit 1: a blocking check failed and no body is produced.
+`LISTED`, exit 0: the plugin is already listed by its own repository (the
+manifest id is in the catalog, and the listing's repository is the subject's
+declared `origin`, compared as owner and name), so the submission form is not
+the route. Nothing is wrong and nothing was refused: `identity.available`
+passes with the listing's record (since when, which commit, verified or not),
+the five checks that exist only for the body are omitted, nothing is asked,
+and the closing block names the commit the marketplace lists, the local
+commit, whether they are the same, and the marketplace's verification form
+with the choice that lists a newer commit, read from the pin's
+`verify-plugin.yml`. Measured on 0.1.6: this state printed `FAIL
+identity.available`, `REFUSED`, and "Fix it, then run submit again" under a
+remedy that said there was nothing to submit. An id taken by another
+repository, a retired id or a reserved one is still refused. In `--json`, the
+outcome is `outcome: "ready" | "refused" | "listed"`, `ready` stays a boolean
+that is true for the first only, and a listed run carries a `listing` object.
+
+An unlisted plugin needs a category and tags, and they are an editorial
 choice nobody else can make: at a terminal it asks, once each, with the form's
 own lists numbered and the marketplace's own default for the manifest's kinds
 offered where it is on the list; in a pipe, from an agent, or with `--json` it
-is the usage error with the same lists, exit 2. Either way the report ends
-with the command line that repeats the run without asking, and `--json`
-carries it as `reproduce`.
+is the usage error with the same lists, exit 2. A listed plugin is asked for
+neither. A `READY` or `REFUSED` report ends with the command line that repeats
+the run without asking, and `--json` carries it as `reproduce`.
 
 There is nothing to authenticate. If you have `gh auth login` done, omakit
 reads that credential for GET requests and stores nothing; a token in
@@ -215,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.6",
+  "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

@@ -46,9 +46,9 @@ message lists the controlled values, read from the pinned form; with `--json`
 the same lists come back under `usage`. A person at a terminal is asked
 instead, once each, with the marketplace's own default for the manifest's
 kinds. It is decided after the registry is read: a plugin that is already
-listed is refused at `identity.available` and asked for nothing. Every report
-ends with the command line that repeats the run without asking, and `--json`
-carries it as `reproduce`.
+listed is asked for nothing. A `READY` or `REFUSED` report ends with the
+command line that repeats the run without asking, and `--json` carries it as
+`reproduce`.
 
 To see the official baseline result alone, with no Omakit check around it:
 
@@ -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
@@ -72,9 +74,34 @@ HEAD, tell the owner and choose another id.
 
 ## Reading the result
 
-Exit code 0 means every blocking check passed and the output contains the issue
-title and body. Exit code 1 means it refused, and no body was produced. Exit
-code 2 is a usage error: nothing was checked.
+A run ends one of three ways; `--json` carries it as `outcome`.
+
+- `READY`, exit 0, `outcome: "ready"`: every blocking check passed and the
+  output contains the issue title and body.
+- `REFUSED`, exit 1, `outcome: "refused"`: a blocking check failed and no body
+  was produced.
+- `LISTED`, exit 0, `outcome: "listed"`: the plugin is already listed by its
+  own repository. Nothing is wrong and nothing was refused, and there is no
+  body, because the submission form is not the route. See below.
+
+Exit code 2 is a usage error: nothing was checked.
+
+**If the outcome is `listed`, stop.** Do not open a submission issue, and
+never change the plugin id to get past it: the id is listed by this very
+repository, and a renamed id would be a second listing of the same plugin.
+Tell the owner the update route, which the output states: the marketplace
+lists `verificationCommit`; the local commit is `localCommit`, and
+`sameCommit` says whether they are the same; to get a newer commit listed,
+open the marketplace's verification form (its name and the choice to pick,
+"Verify and publish a newer upstream commit", are printed from the pin's own
+form, under `listing.updateRoute` in `--json`), and `omakit watch <the
+submission issue>` shows which commit is listed now. A listed plugin is asked
+for no category and no tags, and the five body checks are omitted rather than
+shown as waiting.
+
+An id listed by a *different* repository is a refusal, `identity.available`
+names that repository, and the remedy is another id. That is the one case
+where changing the id is the fix.
 
 A check drawn as `▒ ?` did not run because one it depends on failed; its detail
 names that check. It is not a failure of its own, and the closing refusal lists

package/skills/omarchy-plugin-validation-watch/SKILL.md

@@ -44,7 +44,11 @@ it from the operator's `gh` login (which itself honours `GH_TOKEN` and
 If the diagnosis ends in a resubmission under a new id, run `omakit submit`
 online: never pass `--offline` to get around a listed id, because that reads
 the listed ids from the pin, which is stale within hours, and the marketplace
-refuses against its current registry.
+refuses against its current registry. If `omakit submit` ends `LISTED`
+(`outcome: "listed"` in `--json`), the plugin is already listed by its own
+repository: stop, do not change the id, and tell the owner the update route
+the output names, the marketplace's verification form with the choice "Verify
+and publish a newer upstream commit", read from the pin.
 
 ## Acting on each verdict
 

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

@@ -13,17 +13,18 @@ local commit through the transport seam the marketplace tests itself
 | `verify.mjs` | Builds the `marketplaceBaseline` section: pin, transport, assumptions, the official result verbatim, the statement. `omakit verify` renders it for a person (`renderVerify` in `report.mjs`) and prints the document itself behind `--json` and `--out`. |
 | `preflight.mjs` | Translates that result into what it will cause on submission, using the pinned policy, and renders the marketplace's own report text with its attestation marker stripped and asserted absent. |
 | `yaml.mjs` | A deliberately small YAML reader for the pinned issue form. Accepts that subset and throws on anything else. |
-| `form.mjs` | The submission contract, read from the form and cross-checked against the marketplace's own constants. |
-| `registry.mjs` | The plugin-id and repository universe: the reserved namespace from the pinned catalog builder, the listed and retired ids and listed repositories from `registry.json` and `site/catalog.json` at the marketplace's current HEAD when the network is there (cached under `$XDG_CACHE_HOME/omakit/registry/<commit>/`, never in the pin) and at the pin with `--offline`; `liveFileUrl()` is the only way to the raw file host, at a 40-character commit, for those two files. |
+| `form.mjs` | The submission contract, read from the form and cross-checked against the marketplace's own constants. Also the route for a plugin that is already listed: the marketplace's verification form and its "newer commit" choice, read from `verify-plugin.yml` at the pin and cross-checked against `plugin-verification-request.mjs`. |
+| `registry.mjs` | The plugin-id and repository universe: the reserved namespace from the pinned catalog builder, the listed and retired ids and listed repositories from `registry.json` and `site/catalog.json` at the marketplace's current HEAD when the network is there (cached under `$XDG_CACHE_HOME/omakit/registry/<commit>/`, never in the pin) and at the pin with `--offline`; `liveFileUrl()` is the only way to the raw file host, at a 40-character commit, for those two files. `sameRepository()` is the one rule for "the subject's own repository" (owner and name, case-insensitively, a trailing `.git` ignored), and `listingOf()` is what the catalog records about a listing: since when, which commit, verified or not, checked when. |
 | `tree.mjs` | The installable tree of a subject at one exact commit, from the Git object database. |
 | `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. Decides the category and tags after the registry: a listed plugin needs 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. |
@@ -31,7 +32,7 @@ local commit through the transport seam the marketplace tests itself
 | `banner.mjs` | The wordmark, on a bare `omakit` and in `setup` only. |
 | `effect.mjs` | The one text effect: the wordmark through `ttfx` where it is drawn, with frozen arguments, a hard budget, no colour of its own, and nothing at all when `ttfx` is not there. |
 | `progress.mjs` | The progress line, on stderr, only when a person is looking. |
-| `cli.mjs` | The one entry point behind `bin/omakit`, and the one register every failure is reported in. |
+| `cli.mjs` | The one entry point behind `bin/omakit`, and the one register every failure is reported in. `submit` exits on the outcome: 1 for `refused`, 0 for `ready` and `listed`. |
 
 ```text
 omakit pin
@@ -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
@@ -148,13 +159,15 @@ async function cmdSubmit(args) {
   }
   spinner.done()
   emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderSubmit(result))
-  process.exit(result.ready ? 0 : 1)
+  // Three outcomes, two exit codes: `ready` and `listed` are both healthy
+  // states, and only a refusal is a 1.
+  process.exit(result.outcome === "refused" ? 1 : 0)
 }
 
 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 })
@@ -187,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))
@@ -204,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")
@@ -237,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)