omakit 0.1.3 → 0.1.4

package/README.md

@@ -2,6 +2,8 @@
   <img src="docs/media/banner.gif" alt="omakit" width="440">
 </p>
 
+[![Built for Omarchy](https://raw.githubusercontent.com/tcballard/omarchy-badges/85f859029e236e784e7b05ada6dbe73506d07a91/badges/v1/built-for-omarchy.svg)](https://github.com/tcballard/omarchy-badges)
+
 **Everything knowable about an Omarchy Quattro plugin submission, checked
 before you post it:** the tree, the manifest, the form, the commit, and the
 marketplace's own security baseline with its outcome reported as it is. A

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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

@@ -24,7 +24,9 @@ comes from `origin`. You supply the category and the tags, because nobody else
 can: they are an editorial choice about where the plugin belongs.
 
 If you do not know which category and tags are allowed, run the command without
-them. The failing checks print the controlled lists, read from the pinned form.
+them: that is a usage error (exit 2) whose message lists the controlled values,
+read from the pinned form, before any check runs. With `--json` the same lists
+come back under `usage`.
 
 Useful flags: `--notes` for the Maintainer notes field, `--suggest-tag` for the
 optional suggestion, `--name` when the manifest has no name, `--json` for a
@@ -40,7 +42,12 @@ 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.
+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 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
+root causes only. Fix those.
 
 Each check names a source. `[marketplace-pin]` is the marketplace's own rule, read
 from a pinned checkout. `[omakit]` is this tool's own check, derived from public

package/tools/marketplace/cli.mjs

@@ -17,7 +17,8 @@ import { fileURLToPath } from "node:url"
 import { ensurePin, MARKETPLACE_PIN } from "./pin.mjs"
 import { marketplaceBaselineSection } from "./verify.mjs"
 import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
-import { submitPreflight } from "./submit.mjs"
+import { missingSubmitFlags, submitPreflight } from "./submit.mjs"
+import { submissionContract } from "./form.mjs"
 import { validationWatch } from "./watch.mjs"
 import { renderSubmit, renderWatch, renderDoctor } from "./report.mjs"
 import { doctor } from "./doctor.mjs"
@@ -26,7 +27,7 @@ import { upgrade } from "./upgrade.mjs"
 import { progress } from "./progress.mjs"
 import { banner, bannerEnabled } from "./banner.mjs"
 import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
-import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
+import { action, colourEnabled, GUTTER, labelled, mark, styler, wrap } from "./style.mjs"
 import { omakitCacheDir } from "./paths.mjs"
 import { parityOutput } from "./parity-output.mjs"
 
@@ -55,11 +56,12 @@ const REMEDY = Object.freeze({
 /**
  * Every failure, in one register, on stderr. `usage` errors carry the
  * signature that was expected, so the remedy is the reference and not a
- * restatement of the message.
+ * restatement of the message. `body` is extra labelled lines between the
+ * message and the arrow, for a usage error that has values to list.
  */
-function fail(code, message, exit = 1, remedy = REMEDY[code]) {
+function fail(code, message, exit = 1, remedy = REMEDY[code], body = () => []) {
   const c = styler(colourEnabled(process.stderr))
-  const lines = [`${mark("fail", c)}${c("name", code)}`, ...wrap(message, { indent: GUTTER }, c)]
+  const lines = [`${mark("fail", c)}${c("name", code)}`, ...wrap(message, { indent: GUTTER }, c), ...body(c)]
   if (remedy) lines.push(...action(remedy, c))
   process.stderr.write(`${lines.join("\n")}\n`)
   process.exit(exit)
@@ -96,6 +98,28 @@ function emit(args, text) {
 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)
+  // A missing category or tag list is a usage error, decided before any check
+  // runs and before the spinner starts: nothing can be rendered without them,
+  // and the values the form accepts are the answer, read from the pin.
+  let usage = null
+  try {
+    usage = missingSubmitFlags(await submissionContract({ repoRoot: ROOT }), { category: option(args, "--category"), tags: option(args, "--tags") })
+  } catch (error) {
+    failFrom(error)
+  }
+  if (usage) {
+    if (args.includes("--json")) {
+      process.stdout.write(`${JSON.stringify({ usage }, null, 2)}\n`)
+      process.exit(2)
+    }
+    const flags = usage.missing.join(" and ")
+    fail("usage", `submit needs ${flags}: ${usage.missing.length === 1 ? "it is" : "they are"} an editorial choice nobody else can make, from the pinned form's own lists.`, 2,
+      `omakit submit ${target} --category <c> --tags <a,b>`,
+      (c) => [
+        ...labelled("categories", usage.categories.join(", "), c),
+        ...labelled(`tags, 1 to ${usage.maximumTags}`, usage.tags.join(", "), c),
+      ])
+  }
   const spinner = args.includes("--json") ? { phase: () => {}, done: () => {} } : progress()
   let result
   try {

package/tools/marketplace/registry.mjs

@@ -236,7 +236,10 @@ export function registrySourceDetail(live) {
  *   `registry` and `catalog` are the parsed files from liveRegistry(); without
  *   them the pin's copies are read.
  * @returns {{ reservedPrefix: string, listedIds: Set<string>, retiredIds: Set<string>,
- *             listedRepositories: Set<string>, counts: object }}
+ *             listedRepositories: Set<string>, listedBy: Map<string, string>, counts: object }}
+ *   `listedBy` names the repository slug that lists each id, where the
+ *   registry or catalog says which, so a taken id can be blamed on a
+ *   repository and told apart from the subject's own listing.
  */
 export function idUniverse(options = {}) {
   const pinDir = options.pinDir || requirePin(options.repoRoot).dir
@@ -244,8 +247,14 @@ export function idUniverse(options = {}) {
   const registry = options.registry || readJson(pinDir, REGISTRY_PATH)
 
   const listedIds = new Set()
+  const listedBy = new Map()
+  const listed = (id, repo) => {
+    listedIds.add(id)
+    const slug = repositorySlug(repo)
+    if (slug && !listedBy.has(id)) listedBy.set(id, slug)
+  }
   for (const plugin of Array.isArray(catalog.plugins) ? catalog.plugins : []) {
-    if (typeof plugin?.id === "string" && plugin.id) listedIds.add(plugin.id)
+    if (typeof plugin?.id === "string" && plugin.id) listed(plugin.id, plugin.repo)
   }
   const catalogIds = listedIds.size
 
@@ -255,17 +264,17 @@ export function idUniverse(options = {}) {
     const slug = repositorySlug(source?.repo)
     if (slug) listedRepositories.add(slug)
     if (source?.plugins && typeof source.plugins === "object" && !Array.isArray(source.plugins)) {
-      for (const id of Object.keys(source.plugins)) listedIds.add(id)
+      for (const id of Object.keys(source.plugins)) listed(id, source.repo)
     }
     if (Array.isArray(source?.plugins)) {
       for (const entry of source.plugins) {
         const id = typeof entry === "string" ? entry : entry?.id
-        if (id) listedIds.add(id)
+        if (id) listed(id, source.repo)
       }
     }
-    if (typeof source?.catalog?.id === "string") listedIds.add(source.catalog.id)
+    if (typeof source?.catalog?.id === "string") listed(source.catalog.id, source.repo)
     for (const id of source?.automatedSecurityBaseline?.pluginIds || []) {
-      if (typeof id === "string") listedIds.add(id)
+      if (typeof id === "string") listed(id, source.repo)
     }
   }
 
@@ -281,6 +290,7 @@ export function idUniverse(options = {}) {
     listedIds,
     retiredIds,
     listedRepositories,
+    listedBy,
     counts: {
       catalogPlugins: catalogIds,
       registrySources: sources.length,
@@ -354,7 +364,11 @@ export function figure(n) {
 
 /**
  * @param {{ id: string, repositoryUrl?: string|null }} subject
- * @returns {{ ok: boolean, problems: Array<{ code: string, detail: string }> }}
+ * @returns {{ ok: boolean, problems: Array<{ code: string, detail: string, repository?: string|null, sameRepository?: boolean }> }}
+ *   A `plugin-id-listed` problem names the repository that lists the id
+ *   (`repository`, a slug, or null when the registry does not say) and
+ *   whether that is the subject's own (`sameRepository`), because the two
+ *   have different remedies: another id, or nothing to submit at all.
  */
 export function checkIdentity(universe, subject) {
   const problems = []
@@ -363,6 +377,7 @@ export function checkIdentity(universe, subject) {
     problems.push({ code: "plugin-id-missing", detail: "the root manifest declares no id" })
     return { ok: false, problems }
   }
+  const slug = repositorySlug(subject.repositoryUrl)
   if (id.toLowerCase().startsWith(universe.reservedPrefix)) {
     problems.push({
       code: "reserved-plugin-id",
@@ -373,11 +388,17 @@ export function checkIdentity(universe, subject) {
     problems.push({ code: "plugin-id-retired", detail: `"${id}" was used by a previous listing (registry.json retiredPluginIds)` })
   }
   if (universe.listedIds.has(id)) {
-    problems.push({ code: "plugin-id-listed", detail: `"${id}" is already listed` })
+    const repository = universe.listedBy?.get(id) || null
+    const sameRepository = Boolean(repository && slug && repository === slug)
+    problems.push({
+      code: "plugin-id-listed",
+      detail: `"${id}" is already listed${repository ? ` by ${repository}` : ""}`,
+      repository,
+      sameRepository,
+    })
   }
-  const slug = repositorySlug(subject.repositoryUrl)
   if (slug && universe.listedRepositories.has(slug)) {
-    problems.push({ code: "submission-repository-listed", detail: `${slug} is already listed` })
+    problems.push({ code: "submission-repository-listed", detail: `${slug} is already listed`, repository: slug, sameRepository: true })
   }
   return { ok: problems.length === 0, problems }
 }

package/tools/marketplace/report.mjs

@@ -23,9 +23,10 @@ import {
 
 const body = " ".repeat(GUTTER)
 
-/** The state a check renders in: an advisory failure is a note, not a FAIL. */
+/** 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. */
 function stateOf(check) {
   if (check.verdict === "pass") return "pass"
+  if (check.verdict === "unknown") return "unknown"
   return check.severity === "advisory" ? "advisory" : "fail"
 }
 
@@ -53,7 +54,7 @@ function checkBlock(check, c) {
           ? `${body}${c("fail", "-")} ${c("placeholder", line.trimStart().slice(2))}`
           : `${" ".repeat(GUTTER + STEP)}${c("placeholder", line.trimStart())}`)))
     }
-    if (check.remedy) out.push(...action(check.remedy, c))
+    for (const remedy of [].concat(check.remedy || [])) out.push(...action(remedy, c))
     // The measured reason is the point of the check, so it is not dimmed: only
     // its label is grey, and on a low-contrast theme the number still reads.
     out.push(...labelled("why", check.why, c))
@@ -69,12 +70,14 @@ 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; anything else gets a blank line on each side,
+  // 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"
   let previous = "pass"
   for (const [index, check] of result.checks.entries()) {
     const state = stateOf(check)
-    if (index > 0 && (state !== "pass" || previous !== "pass")) out.push("")
+    if (index > 0 && (!quiet(state) || !quiet(previous))) out.push("")
     out.push(...checkBlock(check, c))
     previous = state
   }
@@ -89,13 +92,17 @@ export function renderSubmit(result, { colour = colourEnabled() } = {}) {
   }
 
   if (!result.ready) {
+    // Root causes only: a check that waited on a failed one is not listed,
+    // and the count says how many waited.
     const failed = result.checks.filter((check) => result.blocking.includes(check.id))
+    const waited = result.checks.filter((check) => check.verdict === "unknown").length
     const count = failed.length === 1 ? "1 blocking check" : `${failed.length} blocking checks`
-    out.push(...verdict("fail", "REFUSED", `${count} failed, so no submission body is produced.`, c))
+    const waiting = waited ? ` ${waited === 1 ? "1 check" : `${waited} checks`} could not run until ${failed.length === 1 ? "it passes" : "they pass"}.` : ""
+    out.push(...verdict("fail", "REFUSED", `${count} failed, so no submission body is produced.${waiting}`, c))
     out.push("")
     for (const check of failed) {
       out.push(`${body}${c("name", check.id)}`)
-      if (check.remedy) out.push(...action(check.remedy, c))
+      if (check.remedy) for (const remedy of [].concat(check.remedy)) out.push(...action(remedy, c))
       else out.push(...wrap(check.detail, { indent: GUTTER }, c))
       out.push("")
     }

package/tools/marketplace/submit.mjs

@@ -23,6 +23,39 @@ import { renderIssue, verifyAgainstOfficialParser } from "./issue.mjs"
 import { defaultBranchHead } from "./github.mjs"
 import { REFRESH_ACTION } from "./watch.mjs"
 import { omakitCacheDir } from "./paths.mjs"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+
+/**
+ * The marketplace's own name for the verification action that lists a newer
+ * commit of an already listed plugin, read from the pin rather than typed:
+ * a form option retyped here would drift by a word, and a person would be
+ * sent to choose something the form no longer offers.
+ */
+async function newerCommitAction(pinDir) {
+  const verification = await import(pathToFileURL(join(pinDir, "scripts/plugin-verification-request.mjs")).href)
+  return verification.upstreamUpdateVerificationAction
+}
+
+/**
+ * One arrow per cause, in this order, so a person fixes the thing that is
+ * actually wrong. Measured before this: an id listed by its own repository
+ * was told to "choose an unused plugin id outside the reserved namespace",
+ * which is the remedy for a different failure, and an author who followed
+ * it would have renamed a plugin the marketplace already lists.
+ */
+function identityRemedies(identity, universe, newerCommit) {
+  const remedies = []
+  const codes = new Set(identity.problems.map((problem) => problem.code))
+  if (codes.has("reserved-plugin-id")) remedies.push(`Choose a plugin id outside the reserved ${universe.reservedPrefix}* namespace.`)
+  if (codes.has("plugin-id-retired")) remedies.push("That id was retired by the marketplace and cannot be reused; choose another.")
+  const taken = identity.problems.find((problem) => problem.code === "plugin-id-listed" && !problem.sameRepository)
+  if (taken) remedies.push(taken.repository ? `That id is taken by ${taken.repository}; choose another.` : "That id is already listed; choose another.")
+  if (identity.problems.some((problem) => problem.sameRepository)) {
+    remedies.push(`This plugin is already listed, so there is nothing to submit. To get a newer commit listed, use the marketplace's verification form and choose "${newerCommit}"; \`omakit watch <the submission issue>\` shows which commit is listed now.`)
+  }
+  return remedies
+}
 
 export class SubmitError extends Error {
   constructor(code, message) {
@@ -32,19 +65,49 @@ export class SubmitError extends Error {
   }
 }
 
+/**
+ * A check has three 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.
+ * Measured before this: a run with no --category and no --tags on a listed
+ * plugin said "6 blocking checks failed" for two causes, because headings,
+ * 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.
+ */
 function check(id, fields) {
+  const waitedOn = (fields.waitedOn || []).filter(Boolean)
   return {
     id,
     source: fields.source,
     why: fields.why,
     severity: fields.severity || "blocking",
-    verdict: fields.verdict ? "pass" : "fail",
-    detail: fields.detail || "",
+    verdict: waitedOn.length ? "unknown" : fields.verdict ? "pass" : "fail",
+    detail: waitedOn.length ? `not checked: it needs ${waitedOn.join(" and ")} to pass first` : fields.detail || "",
     paths: fields.paths || [],
-    remedy: fields.remedy || null,
+    // 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,
   }
 }
 
+/**
+ * What `submit` needs on the command line, decided before any check runs:
+ * the category and the tags are editorial choices nobody else can make, and
+ * a run without them has nothing to render. The controlled values come from
+ * the form at the pin, so the usage message lists exactly what the form
+ * accepts. Null when nothing is missing.
+ *
+ * @returns {{ missing: string[], categories: string[], tags: string[], maximumTags: number }|null}
+ */
+export function missingSubmitFlags(contract, { category, tags } = {}) {
+  const missing = []
+  if (!String(category ?? "").trim()) missing.push("--category")
+  if (!(Array.isArray(tags) ? tags : String(tags ?? "").split(",")).some((value) => String(value).trim())) missing.push("--tags")
+  if (!missing.length) return null
+  return { missing, categories: [...contract.categories], tags: [...contract.tagLabels], maximumTags: contract.maximumTags }
+}
+
 /**
  * @param {{ repoRoot: string, target: string, category?: string, tags?: string|string[],
  *           notes?: string, suggestedTag?: string, pluginName?: string,
@@ -60,7 +123,7 @@ export async function submitPreflight(options) {
   const phase = options.onPhase || (() => {})
 
   phase("verifying the pinned marketplace checkout")
-  const { identity: pinIdentity } = requirePin(repoRoot)
+  const { dir: pinDir, identity: pinIdentity } = requirePin(repoRoot)
   phase("reading the submission contract from the pin")
   const contract = await submissionContract({ repoRoot })
   phase(options.offline ? "reading the listed and retired plugin ids from the pin" : "reading the marketplace's current registry")
@@ -149,6 +212,7 @@ export async function submitPreflight(options) {
   // --- identity -------------------------------------------------------------
 
   const identity = checkIdentity(universe, { id: tree.pluginId, repositoryUrl: subject.repository.url })
+  const identityRemedy = identity.ok ? null : identityRemedies(identity, universe, await newerCommitAction(pinDir))
   checks.push(check("identity.available", {
     source: "marketplace-pin",
     why: `The marketplace refuses \`plugin-id-listed\`, \`plugin-id-retired\`, \`reserved-plugin-id\` and \`submission-repository-listed\`. Checked here against ${figure(universe.counts.listedIds)} listed ids, ${figure(universe.counts.retiredIds)} retired ids and ${figure(universe.counts.listedRepositories)} listed repositories from the registry and catalog at the commit the detail names, and the reserved namespace from the pinned catalog builder. The registry is read from the marketplace's current HEAD when the network is there because the pin's copy is stale within hours: registry.json changed in 4,201 of the marketplace's 4,293 commits in the 30 days to 2026-09-13, about 140 a day (docs/MEASUREMENTS.md M7). Code and the form are only ever read from the pin.`,
@@ -156,7 +220,7 @@ export async function submitPreflight(options) {
     detail: `${identity.ok
       ? `id "${tree.pluginId}" is unused, outside the reserved ${universe.reservedPrefix}* namespace, and the repository is not listed`
       : identity.problems.map((problem) => `${problem.code}: ${problem.detail}`).join("; ")}; ${registrySourceDetail(live)}`,
-    remedy: identity.ok ? null : "Choose an unused plugin id outside the reserved namespace.",
+    remedy: identityRemedy,
   }))
 
   // --- the submission itself ------------------------------------------------
@@ -191,9 +255,17 @@ export async function submitPreflight(options) {
     remedy: tags.ok ? null : "Pass --tags with 1 to 3 comma-separated values from the list.",
   }))
 
+  // The body needs every field above and the repository URL below; the three
+  // checks that read it wait on whichever of those failed.
+  const bodyWaitsOn = [
+    !pluginName && "submission.title",
+    !category.ok && "submission.category",
+    !tags.ok && "submission.tags",
+    !subject.repository.url && "submission.repository-url",
+  ].filter(Boolean)
   let issue = null
   let parsed = null
-  if (pluginName && category.ok && tags.ok && subject.repository.url) {
+  if (!bodyWaitsOn.length) {
     issue = renderIssue(contract, {
       pluginName,
       repositoryUrl: subject.repository.url,
@@ -217,7 +289,8 @@ export async function submitPreflight(options) {
     source: "marketplace-pin",
     why: `The six form headings must appear in exact order: ${contract.headings.join(", ")}. 11 open submissions are malformed in the body and receive "The validation result could not be published to the issue. A maintainer must review the workflow.", which blames the maintainer for the author's mistake; one of them differs from a valid submission by the single word "Suggested" instead of "Suggest". The headings are rendered from the form at the pin, never typed.`,
     verdict: Boolean(issue),
-    detail: issue ? `${contract.headings.length} headings rendered in form order` : "not rendered: an earlier submission field is missing",
+    detail: issue ? `${contract.headings.length} headings rendered in form order` : "not rendered",
+    waitedOn: bodyWaitsOn,
   }))
 
   checks.push(check("submission.checklist", {
@@ -225,6 +298,7 @@ export async function submitPreflight(options) {
     why: `All ${contract.checklist.length} checklist items must be present with their exact text and checked; the marketplace refuses \`submission-checklist-unconfirmed\` otherwise. The text is read from the form at the pin, character for character.`,
     verdict: Boolean(issue),
     detail: issue ? `${contract.checklist.length} items rendered with the form's exact text, all checked` : "not rendered",
+    waitedOn: bodyWaitsOn,
   }))
 
   checks.push(check("submission.official-parser", {
@@ -236,6 +310,7 @@ export async function submitPreflight(options) {
         ? `accepted: repo ${parsed.submission.repo}, category ${parsed.submission.category}, tags ${parsed.submission.tags.join(", ")}`
         : `refused by the marketplace's own parser: ${parsed.code}, ${parsed.message}`
       : "not run: no body was rendered",
+    waitedOn: bodyWaitsOn,
   }))
 
   // --- the commit the marketplace will actually validate ---------------------
@@ -303,6 +378,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 ready = blocking.length === 0
 
   return {
@@ -337,6 +413,7 @@ export async function submitPreflight(options) {
     ready,
     blocking: blocking.map((entry) => entry.id),
     advisory: advisory.map((entry) => entry.id),
+    unknown: unknown.map((entry) => entry.id),
     issue: ready ? issue : null,
     baseline: preflight.invoked
       ? {