omakit 0.2.1 → 0.3.0

package/README.md

@@ -28,6 +28,7 @@ See [docs/INSTALL.md](docs/INSTALL.md) for the clone route, PATH, requirements a
 | [`omakit watch <issue-url>`](docs/VALIDATION_WATCH.md) | The commit the marketplace validated, against the plugin's current HEAD. |
 | [`omakit verify <plugin-repo>`](docs/COMMANDS.md) | The official security baseline over the local transport; `--json` for the document. |
 | [`omakit parity`](docs/COMMANDS.md) | The baseline over GitHub versus the local transport, on real listings; writes the evidence. |
+| [`omakit audit [<plugin>]`](docs/AUDIT.md) | Installed third-party commits against the exact commits the marketplace validated. |
 | [`omakit weigh <plugin>`](docs/WEIGH.md) | What a plugin weighs on the shell, measured by restarting it without and with the plugin; asks first. |
 | [`omakit doctor`](docs/COMMANDS.md) | What is installed, what is pinned, and what has moved. |
 | [`omakit pin`](docs/COMMANDS.md) | What setup does for the pin, on its own. |
@@ -95,6 +96,7 @@ Committed evidence records a digest of each side rather than the results themsel
 | [docs/INSTALL.md](docs/INSTALL.md) | install details, PATH, requirements, upgrading, and what Socket reports and why |
 | [docs/HOW.md](docs/HOW.md) | what omakit is doing, why it uses Node, the baseline and check labels |
 | [docs/COMMANDS.md](docs/COMMANDS.md) | command details, authentication and network behaviour |
+| [docs/AUDIT.md](docs/AUDIT.md) | installed plugin drift against marketplace-validated commits, with JSON origins |
 | [docs/SUBMIT.md](docs/SUBMIT.md) | every check and what it decides |
 | [docs/WEIGH.md](docs/WEIGH.md) | what `weigh` measures, the noise floor, the `shell.json` mutation and its restore, and the JSON contract |
 | [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md) | the validation watch: what the marketplace validated, and what moves it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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 against the marketplace, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

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

@@ -0,0 +1,44 @@
+---
+name: omarchy-plugin-audit
+description: Compare installed Omarchy Quattro plugin commits with the exact commits the marketplace validated. Use before touching an installed third-party plugin, before enabling or updating one, or when asked whether installed plugins match marketplace review. Read-only.
+---
+
+# Audit installed plugin commits
+
+Run `omakit audit` before touching an installed third-party plugin. Run
+`omakit audit <plugin-id-or-dir>` when only one installed plugin is in scope.
+The command reads the shell's installed list, the marketplace catalog and local
+Git facts. It changes nothing.
+
+Read the primary state first:
+
+- `validated` means installed HEAD is one of the commits the marketplace
+  records as validated.
+- `ahead` means a validated commit is an ancestor, but HEAD contains later
+  commits the marketplace did not validate.
+- `diverged` means installed history does not descend from a validated commit,
+  or its origin is not the listed repository. A validated object missing from
+  local history is diverged, with the clone's shallow status stated.
+- `unverified` means the listing records no validated commit. Its status is stated.
+- `unlisted` means neither plugin id nor origin identifies a listing.
+- `unknown` means Git or the source directory could not answer. Keep the error.
+
+Then report every stacking flag: `modified`, `disabled`, and `upstream moved`.
+Do not collapse a flag into the primary state. First-party plugins are counted
+and excluded because they ship with the shell.
+
+Use `--json` when another tool needs the document. Every figure carries its
+origin. Use `--offline` when the live catalog must not be read; the header will
+name the pin. `--drift` is a view filter, not a different measurement.
+
+An `ahead` or `diverged` report prints the exact checkout command for the
+validated commit and names the marketplace form for validating a newer one.
+Never run that checkout command without the person's explicit request. Never
+replace it with `omarchy plugin update`; update moves to mutable HEAD and does
+not establish marketplace validation.
+
+`AUDITED`, exit 0, means every audited row is validated, or there was nothing
+third-party to audit. `DRIFT`, exit 1, means drift or an unknown answer.
+Exit 2 means the invocation was refused. `NOT AUDITED` because the shell or
+catalog did not answer is a
+result to report, not a reason to substitute a directory scan.

package/tools/audit/audit.mjs

@@ -0,0 +1,223 @@
+// Compare installed third-party checkouts with commits recorded by the live
+// marketplace catalog. Nothing here fetches or changes a checkout.
+
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { newerCommitChoice } from "../marketplace/form.mjs"
+import { liveRegistry, sameRepository } from "../marketplace/registry.mjs"
+import { installedPlugins } from "../weigh/list.mjs"
+import { ancestorOf, commitsAfter, hasCommit, isShallow, readCheckout } from "./git.mjs"
+
+export class AuditError extends Error {
+  constructor(code, message, remedy = null) {
+    super(message)
+    this.name = "AuditError"
+    this.code = code
+    this.remedy = remedy
+  }
+}
+
+const text = (value) => (typeof value === "string" && value ? value : null)
+const lower = (value) => text(value)?.toLowerCase() || null
+const figure = (value, origin) => (value === null || value === undefined ? null : { value, origin })
+const catalogFigure = (listing, name) => figure(text(listing?.[name]), `site/catalog.json ${name}`)
+const short = (value) => value.slice(0, 8)
+const ROW_ORDER = ["diverged", "ahead", "modified", "unverified", "unlisted", "unknown", "validated"]
+const rowRank = (row) => ROW_ORDER.indexOf(["diverged", "ahead"].includes(row.state) ? row.state : row.flags.includes("modified") ? "modified" : row.state)
+
+function targetId(target) {
+  if (!target || !existsSync(target)) return target || null
+  try {
+    return text(JSON.parse(readFileSync(resolve(target, "manifest.json"), "utf8"))?.id)
+  } catch {
+    return null
+  }
+}
+
+function chooseListing(plugin, checkout, listings) {
+  const byId = listings.find((entry) => entry?.id === plugin.id) || null
+  const byOrigin = listings.find((entry) => sameRepository(entry?.repo, checkout.repository)) || null
+  if (byId && byOrigin && byId !== byOrigin) {
+    return { listing: null, conflict: `manifest id matches ${byId.id}, but origin matches ${byOrigin.id}; neither listing was used` }
+  }
+  return { listing: byId || byOrigin, conflict: null }
+}
+
+function validatedFigures(listing) {
+  const figures = []
+  const add = (prefix) => {
+    const commit = lower(listing?.[`${prefix}ValidatedCommit`])
+    if (!commit || figures.some((entry) => entry.commit.value === commit)) return
+    figures.push({
+      kind: prefix,
+      commit: figure(commit, `site/catalog.json ${prefix}ValidatedCommit`),
+      date: catalogFigure(listing, `${prefix}ValidatedAt`),
+      branch: catalogFigure(listing, prefix === "listing" ? "listingValidatedBranch" : "upstreamObservedBranch"),
+    })
+  }
+  add("upstream")
+  add("listing")
+  return figures
+}
+
+function rowFact(plugin, checkout, listing, conflict, git, env) {
+  const flags = []
+  if (checkout.status) flags.push("modified")
+  if (plugin.enabled !== true) flags.push("disabled")
+  const validated = validatedFigures(listing)
+  const observed = lower(listing?.upstreamObservedCommit)
+  if (observed && observed !== checkout.commit && !validated.some((entry) => entry.commit.value === observed)) flags.push("upstream moved")
+
+  const common = {
+    id: plugin.id,
+    flags,
+    installed: {
+      commit: figure(checkout.commit, "git rev-parse HEAD"),
+      enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled"),
+      modified: figure(Boolean(checkout.status), "git status --porcelain"),
+      repository: figure(checkout.repository, "git remote get-url origin"),
+    },
+    validated,
+    upstream: {
+      observedCommit: catalogFigure(listing, "upstreamObservedCommit"),
+      observedBranch: catalogFigure(listing, "upstreamObservedBranch"),
+      checkedAt: catalogFigure(listing, "upstreamCheckedAt"),
+      checkStatus: catalogFigure(listing, "upstreamCheckStatus"),
+    },
+    sourceDir: plugin.sourceDir,
+    listing: listing ? { id: listing.id, repository: listing.repo } : null,
+  }
+
+  if (!listing) return { ...common, state: "unlisted", fact: conflict || "manifest id and origin match no marketplace listing", aheadBy: null, matchedValidated: null }
+  if (validated.some((entry) => entry.commit.value === checkout.commit)) {
+    const matched = validated.find((entry) => entry.commit.value === checkout.commit)
+    return { ...common, state: "validated", fact: `validated ${short(matched.commit.value)} on ${matched.date?.value || "an unrecorded date"}`, aheadBy: null, matchedValidated: matched }
+  }
+  if (!validated.length) {
+    return { ...common, state: "unverified", fact: `listed with verificationStatus ${listing.verificationStatus || "unrecorded"}, and no validated commit`, aheadBy: null, matchedValidated: null }
+  }
+  const missing = []
+  for (const candidate of validated) {
+    if (!git.hasCommit(plugin.sourceDir, candidate.commit.value, { env })) {
+      missing.push(candidate)
+      continue
+    }
+    if (git.ancestor(plugin.sourceDir, candidate.commit.value, { env })) {
+      const count = git.count(plugin.sourceDir, candidate.commit.value, { env })
+      return { ...common, state: "ahead", fact: `${count} commit${count === 1 ? "" : "s"} ahead of validated ${short(candidate.commit.value)} (${candidate.date?.value || "unrecorded date"}); HEAD ${short(checkout.commit)}`, aheadBy: figure(count, `git rev-list --count ${candidate.commit.value}..HEAD`), matchedValidated: candidate }
+    }
+  }
+  if (missing.length) {
+    const shallow = figure(git.shallow(plugin.sourceDir, { env }), "git rev-parse --is-shallow-repository")
+    return { ...common, state: "diverged", fact: `validated commit not in local history; shallow clone: ${shallow.value}`, shallow, aheadBy: null, matchedValidated: missing[0] }
+  }
+  const moved = sameRepository(checkout.repository, listing.repo)
+  return { ...common, state: "diverged", fact: moved ? "installed commit does not descend from a validated commit" : `origin does not match ${listing.repo}`, aheadBy: null, matchedValidated: validated[0] }
+}
+
+/**
+ * Audit the installed third-party plugin set, or one target from that set.
+ * All external readers are injectable so tests establish every state without
+ * touching the person's shell or plugin directories.
+ */
+export async function auditInstalled(options = {}) {
+  const env = options.env || process.env
+  const readers = {
+    installed: options.installed || ((args) => installedPlugins(args)),
+    registry: options.registry || ((args) => liveRegistry(args)),
+    checkout: options.checkout || ((dir, args) => readCheckout(dir, args)),
+    hasCommit: options.hasCommit || ((dir, sha, args) => hasCommit(dir, sha, args)),
+    shallow: options.shallow || ((dir, args) => isShallow(dir, args)),
+    ancestor: options.ancestor || ((dir, sha, args) => ancestorOf(dir, sha, args)),
+    count: options.count || ((dir, sha, args) => commitsAfter(dir, sha, args)),
+    route: options.route || ((args) => newerCommitChoice(args)),
+  }
+  let installed
+  try {
+    installed = readers.installed({ env })
+  } catch (error) {
+    throw new AuditError(error?.code || "shell-not-running", error?.message || String(error))
+  }
+  let live
+  try {
+    live = await readers.registry({ repoRoot: options.repoRoot, offline: options.offline })
+  } catch (error) {
+    throw new AuditError(error?.code || "marketplace-unavailable", error?.message || String(error), error?.remedy || "omakit pin")
+  }
+  const listings = Array.isArray(live.catalog?.plugins) ? live.catalog.plugins : null
+  if (!listings) throw new AuditError("catalog-unreadable", "the marketplace catalog has no plugins array", "omakit pin")
+
+  const wanted = targetId(options.target)
+  let selected = installed
+  if (options.target) {
+    const path = existsSync(options.target) ? resolve(options.target) : null
+    selected = installed.filter((plugin) => plugin.id === wanted || (path && plugin.sourceDir && resolve(plugin.sourceDir) === path))
+    if (!selected.length) throw new AuditError("plugin-not-installed", `${JSON.stringify(options.target)} is not an installed plugin`, "omakit audit")
+  }
+
+  let firstPartyCount = 0
+  const rows = []
+  for (const plugin of selected) {
+    const idListing = listings.find((entry) => entry?.id === plugin.id)
+    if (plugin.firstParty === true || idListing?.sourceType === "builtin") {
+      firstPartyCount += 1
+      continue
+    }
+    if (!plugin.sourceDir) {
+      rows.push({ id: plugin.id, state: "unknown", flags: plugin.enabled === true ? [] : ["disabled"], installed: { enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled") }, validated: [], upstream: {}, sourceDir: null, listing: idListing ? { id: idListing.id, repository: idListing.repo } : null, fact: "omarchy-plugin-catalog records no source directory", error: "source directory unavailable", aheadBy: null, matchedValidated: null })
+      continue
+    }
+    let checkout
+    try {
+      checkout = readers.checkout(plugin.sourceDir, { env })
+    } catch (error) {
+      rows.push({ id: plugin.id, state: "unknown", flags: plugin.enabled === true ? [] : ["disabled"], installed: { enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled") }, validated: [], upstream: {}, sourceDir: plugin.sourceDir, listing: idListing ? { id: idListing.id, repository: idListing.repo } : null, fact: `git failed: ${error.message}`, error: error.message, aheadBy: null, matchedValidated: null })
+      continue
+    }
+    try {
+      const { listing, conflict } = chooseListing(plugin, checkout, listings)
+      if (listing?.sourceType === "builtin") {
+        firstPartyCount += 1
+        continue
+      }
+      rows.push(rowFact(plugin, checkout, listing, conflict, readers, env))
+    } catch (error) {
+      rows.push({ id: plugin.id, state: "unknown", flags: [checkout.status ? "modified" : null, plugin.enabled === true ? null : "disabled"].filter(Boolean), installed: { commit: figure(checkout.commit, "git rev-parse HEAD"), enabled: figure(plugin.enabled === true, "omarchy plugin list --json enabled"), modified: figure(Boolean(checkout.status), "git status --porcelain"), repository: figure(checkout.repository, "git remote get-url origin") }, validated: validatedFigures(idListing), upstream: {}, sourceDir: plugin.sourceDir, listing: idListing ? { id: idListing.id, repository: idListing.repo } : null, fact: `git failed: ${error.message}`, error: error.message, aheadBy: null, matchedValidated: null })
+    }
+  }
+
+  rows.sort((a, b) => rowRank(a) - rowRank(b))
+  const needsAction = rows.some((row) => row.state === "ahead" || row.state === "diverged")
+  let updateRoute = null
+  let updateRouteError = null
+  if (needsAction) {
+    try {
+      updateRoute = await readers.route({ repoRoot: options.repoRoot })
+    } catch (error) {
+      updateRouteError = error?.message || String(error)
+    }
+  }
+  const drift = rows.filter((row) => row.state !== "validated")
+  return {
+    command: "audit",
+    catalog: {
+      source: live.source,
+      commit: figure(live.commit, live.source === "head" ? "marketplace default-branch HEAD" : "marketplace pin"),
+      readAt: figure(live.fetchedAt, live.source === "head" ? "liveRegistry fetchedAt" : "--offline or liveRegistry fallback"),
+      offline: options.offline === true,
+      reason: live.reason,
+    },
+    counts: {
+      installed: figure(installed.length, "omarchy plugin list --json length"),
+      selected: figure(selected.length, options.target ? "target selection" : "omarchy plugin list --json length"),
+      firstPartyExcluded: figure(firstPartyCount, "sourceType builtin or omarchy plugin list --json firstParty"),
+      audited: figure(rows.length, "audited row count"),
+      validated: figure(rows.length - drift.length, "rows whose state is validated"),
+      drift: figure(drift.length, "rows whose state is not validated"),
+    },
+    rows: options.drift ? drift : rows,
+    updateRoute,
+    updateRouteError,
+    ok: drift.length === 0,
+  }
+}

package/tools/audit/git.mjs

@@ -0,0 +1,63 @@
+// The local Git facts used by `omakit audit`. Every invocation is read-only,
+// has a fixed verb and argument shape, and is passed to Git without a shell.
+
+import { spawnSync } from "node:child_process"
+
+function runGit(sourceDir, args, env = process.env) {
+  const result = spawnSync("git", ["-C", sourceDir, ...args], {
+    encoding: "utf8",
+    env: { ...env, GIT_NO_LAZY_FETCH: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  if (result.status !== 0 || result.error) {
+    const detail = (result.stderr || result.error?.message || `git exited ${result.status}`).trim()
+    throw new Error(`${args.join(" ")}: ${detail}`)
+  }
+  return result.stdout.trim()
+}
+
+/** Read HEAD, tree state and origin from one checkout. */
+export function readCheckout(sourceDir, { env = process.env } = {}) {
+  return {
+    commit: runGit(sourceDir, ["rev-parse", "HEAD"], env).toLowerCase(),
+    status: runGit(sourceDir, ["status", "--porcelain"], env),
+    repository: runGit(sourceDir, ["remote", "get-url", "origin"], env),
+  }
+}
+
+/** A missing object is a local-history fact, not a failed ancestry check. */
+export function hasCommit(sourceDir, commit, { env = process.env } = {}) {
+  const result = spawnSync("git", ["-C", sourceDir, "cat-file", "-e", commit], {
+    encoding: "utf8",
+    env: { ...env, GIT_NO_LAZY_FETCH: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  if (result.error || result.status === null) throw new Error(result.error?.message || "git could not run")
+  return result.status === 0
+}
+
+export function isShallow(sourceDir, { env = process.env } = {}) {
+  const value = runGit(sourceDir, ["rev-parse", "--is-shallow-repository"], env)
+  if (!["true", "false"].includes(value)) throw new Error(`rev-parse --is-shallow-repository returned ${JSON.stringify(value)}`)
+  return value === "true"
+}
+
+/** Is a recorded commit an ancestor of the running checkout? */
+export function ancestorOf(sourceDir, commit, { env = process.env } = {}) {
+  const result = spawnSync("git", ["-C", sourceDir, "merge-base", "--is-ancestor", commit, "HEAD"], {
+    encoding: "utf8",
+    env: { ...env, GIT_NO_LAZY_FETCH: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  if (result.status === 0) return true
+  if (result.status === 1) return false
+  const detail = (result.stderr || result.error?.message || `git exited ${result.status}`).trim()
+  throw new Error(`merge-base --is-ancestor ${commit} HEAD: ${detail}`)
+}
+
+/** Count commits after one recorded ancestor. */
+export function commitsAfter(sourceDir, commit, { env = process.env } = {}) {
+  const value = runGit(sourceDir, ["rev-list", "--count", `${commit}..HEAD`], env)
+  if (!/^\d+$/.test(value)) throw new Error(`rev-list --count returned ${JSON.stringify(value)}`)
+  return Number(value)
+}

package/tools/audit/report.mjs

@@ -0,0 +1,56 @@
+import { action, AUDIT_VERDICTS, colourEnabled, field, GUTTER, mark, styler, verdict, wrap } from "../marketplace/style.mjs"
+
+const short = (value) => value ? String(value).slice(0, 8) : "unrecorded"
+const flagText = (flags) => flags.length ? `; ${flags.join(", ")}` : ""
+const markFor = (row) => {
+  if (row.flags.includes("modified")) return "advisory"
+  if (row.state === "validated") return "pass"
+  if (["ahead", "diverged", "unverified"].includes(row.state)) return "advisory"
+  if (row.state === "unlisted") return "info"
+  if (row.flags.includes("disabled")) return "info"
+  return "unknown"
+}
+
+function catalogText(catalog) {
+  if (catalog.source === "head") return `live HEAD ${short(catalog.commit.value)} at ${catalog.readAt?.value || "an unrecorded time"}`
+  return `pin ${short(catalog.commit.value)}${catalog.offline ? " (offline)" : ""}`
+}
+
+/** A terminal report made only from the shared style vocabulary. */
+export function renderAudit(document, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = []
+  out.push(...field("catalog", catalogText(document.catalog), c))
+  out.push(...field("installed", `${document.counts.installed.value}`, c))
+  out.push(...field("first-party", `${document.counts.firstPartyExcluded.value} left out`, c))
+  out.push(...field("audited", `${document.counts.audited.value}`, c))
+  out.push("")
+  for (const row of document.rows) {
+    const installed = row.installed?.commit?.value
+    const validated = row.matchedValidated?.commit?.value
+    const date = row.matchedValidated?.date?.value
+    const detail = ["validated", "ahead"].includes(row.state)
+      ? `${row.fact}${flagText(row.flags)}`
+      : `${row.state}: ${row.fact}${installed ? `; HEAD ${short(installed)}` : ""}${validated ? `; validated ${short(validated)}${date ? ` on ${date}` : ""}` : ""}${flagText(row.flags)}`
+    out.push(`${mark(markFor(row), c)}${c("name", row.id)}`)
+    out.push(...wrap(detail, { indent: GUTTER }, c))
+    if ((row.state === "ahead" || row.state === "diverged") && validated) {
+      out.push(...action(`git -C ${JSON.stringify(row.sourceDir)} checkout ${validated}`, c))
+    }
+    out.push("")
+  }
+  const total = document.counts.audited.value
+  const good = document.counts.validated.value
+  const drift = document.counts.drift.value
+  if (document.updateRoute) {
+    out.push(...action(`To validate a newer commit: ${document.updateRoute.url}`, c))
+    out.push(...wrap(`${document.updateRoute.name}; choose ${JSON.stringify(document.updateRoute.choice)}.`, { indent: GUTTER }, c))
+    out.push("")
+  }
+  if (document.updateRouteError) {
+    out.push(...wrap(`Verification route unavailable: ${document.updateRouteError}; run omakit pin.`, { indent: GUTTER }, c))
+    out.push("")
+  }
+  out.push(...verdict(document.ok ? "pass" : "fail", document.ok ? AUDIT_VERDICTS.validated : AUDIT_VERDICTS.drift, `${good} of ${total} run a commit the marketplace validated; ${drift} run one it never saw.`, c))
+  return out.join("\n")
+}

package/tools/marketplace/cli.mjs

@@ -33,12 +33,14 @@ 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, labelled, mark, styler, verdict, wrap } from "./style.mjs"
+import { action, AUDIT_VERDICTS, colourEnabled, GUTTER, labelled, mark, styler, verdict, wrap } from "./style.mjs"
 import { omakitCacheDir, withHomeAbbreviated } from "./paths.mjs"
 import { DEFAULTS as WEIGH_DEFAULTS, measureWeigh, planWeigh } from "../weigh/audit.mjs"
 import { confirmationQuestion, renderList, renderWeigh, renderPlan } from "../weigh/report.mjs"
 import { listWeighings } from "../weigh/list.mjs"
 import { askYes } from "../weigh/confirm.mjs"
+import { auditInstalled } from "../audit/audit.mjs"
+import { renderAudit } from "../audit/report.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -293,6 +295,40 @@ async function cmdParity(args) {
   process.exit(ok ? 0 : 1)
 }
 
+function notAudited(message, remedy = null, exit = 1) {
+  const c = styler(colourEnabled(process.stderr))
+  const lines = verdict("fail", AUDIT_VERDICTS.unavailable, message, c)
+  if (remedy) lines.push(...action(remedy, c, { indent: 0 }))
+  process.stderr.write(`${lines.join("\n")}\n`)
+  process.exit(exit)
+}
+
+async function cmdAudit(args) {
+  const parsed = checkArgs(args, ACCEPTED.audit)
+  if (parsed.offending !== null) notAudited(`${parsed.reason}. Accepted: ${acceptedWords("audit")}.`, "omakit audit [<plugin-id-or-dir>] [--drift] [--json] [--out FILE] [--offline]", 2)
+  let document
+  try {
+    document = await auditInstalled({
+      repoRoot: ROOT,
+      target: parsed.positionals[0],
+      drift: parsed.options.has("--drift"),
+      offline: parsed.options.has("--offline"),
+    })
+  } catch (error) {
+    if (error?.code && typeof error.code === "string") notAudited(`${error.message}.`, error.remedy || REMEDY[error.code])
+    throw error
+  }
+  const json = `${JSON.stringify(document, null, 2)}\n`
+  const out = parsed.options.get("--out")
+  if (out) {
+    mkdirSync(dirname(resolve(out)), { recursive: true })
+    writeFileSync(resolve(out), json)
+  }
+  if (parsed.options.has("--json")) process.stdout.write(json)
+  else process.stdout.write(`${renderAudit(document)}\n`)
+  process.exit(document.ok ? 0 : 1)
+}
+
 /**
  * Every way `weigh` stops without weighing, in one register: the closing
  * word a report would have ended with, negated, then the sentence naming
@@ -458,6 +494,8 @@ if (command === "setup") {
   await cmdVerify(rest)
 } else if (command === "parity") {
   await cmdParity(rest)
+} else if (command === "audit") {
+  await cmdAudit(rest)
 } else if (command === "weigh") {
   await cmdWeigh(rest)
 } else if (command === "help" || command === "--help" || command === "-h" || command === undefined) {

package/tools/marketplace/completion.mjs

@@ -47,7 +47,8 @@ export function subcommandsOf(commands = COMMANDS) {
 }
 
 /**
- * The plugin ids a TAB offers for `omakit weigh <TAB>`: what the running
+ * The plugin ids a TAB offers for `omakit weigh <TAB>` and `omakit audit <TAB>`:
+ * what the running
  * shell reports through `omarchy-shell shell listPlugins`, filtered with
  * `jq` at TAB time, enabled ids first and whole bars left out, since a bar
  * cannot be weighed. No node process behind the TAB: a shell that does not
@@ -56,7 +57,15 @@ export function subcommandsOf(commands = COMMANDS) {
  * expression is exported so a test can run it through jq.
  */
 export const PLUGIN_IDS_JQ = "[.[] | select(((.kinds // []) | index(\"bar\")) | not)] | sort_by(.enabled | not) | .[].id"
-export const PLUGIN_IDS_COMMAND = `timeout 1 omarchy-shell shell listPlugins 2>/dev/null | jq -r '${PLUGIN_IDS_JQ}' 2>/dev/null`
+/**
+ * The pipeline, in the shell's own syntax. `timeout 1` bounds the wait
+ * where coreutils has it; a system without `timeout` (measured: the macOS
+ * runner in CI, where the TAB fell back to directories) runs the command
+ * unbounded rather than never, since `omarchy-shell` itself gives up on
+ * its IPC timeout.
+ */
+export const PLUGIN_IDS_COMMAND = `omarchy-shell shell listPlugins 2>/dev/null | jq -r '${PLUGIN_IDS_JQ}' 2>/dev/null`
+export const PLUGIN_IDS_TIMED = `timeout 1 ${PLUGIN_IDS_COMMAND}`
 
 /** What a valued flag takes, by its placeholder: a controlled value, a file, or free text. */
 function placeholderKind(placeholder) {
@@ -175,7 +184,7 @@ function bash({ subcommands, categories, tags, pin, version }) {
   lines.push("# left out, read at TAB time; nothing when the shell does not answer in a")
   lines.push("# second, and the caller falls back to a directory.")
   lines.push("_omakit_plugin_ids() {")
-  lines.push(`  ${PLUGIN_IDS_COMMAND}`)
+  lines.push(`  if command -v timeout >/dev/null 2>&1; then ${PLUGIN_IDS_TIMED}; else ${PLUGIN_IDS_COMMAND}; fi`)
   lines.push("}")
   lines.push("")
   lines.push("# A controlled value may contain a space, so each match is one line and is")
@@ -243,7 +252,7 @@ function zsh({ subcommands, categories, tags, pin, version }) {
   lines.push("# left out, read at TAB time; a directory when the shell does not answer.")
   lines.push("_omakit_plugins() {")
   lines.push("  local -a ids")
-  lines.push(`  ids=(\${(f)"$(${PLUGIN_IDS_COMMAND})"})`)
+  lines.push(`  if (( $+commands[timeout] )); then ids=(\${(f)"$(${PLUGIN_IDS_TIMED})"}); else ids=(\${(f)"$(${PLUGIN_IDS_COMMAND})"}); fi`)
   lines.push("  if (( ${#ids} )); then compadd -a ids; else _directories; fi")
   lines.push("}")
   lines.push("")
@@ -263,7 +272,7 @@ function fish({ subcommands, categories, tags, pin, version }) {
   lines.push("# left out, read at TAB time; nothing when the shell does not answer, and")
   lines.push("# the directories offered beside them stand.")
   lines.push("function __omakit_plugin_ids")
-  lines.push(`  ${PLUGIN_IDS_COMMAND}`)
+  lines.push(`  if command -q timeout; ${PLUGIN_IDS_TIMED}; else; ${PLUGIN_IDS_COMMAND}; end`)
   lines.push("end")
   lines.push("")
   for (const sub of subcommands) {

package/tools/marketplace/form.mjs

@@ -23,7 +23,7 @@ import { readFileSync } from "node:fs"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 import { parseYaml } from "./yaml.mjs"
-import { requirePin } from "./pin.mjs"
+import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
 
 export const SUBMIT_FORM_PATH = ".github/ISSUE_TEMPLATE/submit-plugin.yml"
 export const OFFICIAL_SUBMISSION_MODULE = "scripts/submission.mjs"
@@ -147,7 +147,7 @@ export async function submissionContract(options = {}) {
  * pick something the form no longer offers.
  *
  * @param {{ repoRoot?: string, pinDir?: string }} [options]
- * @returns {Promise<{ formPath: string, name: string, choice: string }>}
+ * @returns {Promise<{ formPath: string, name: string, choice: string, url: string }>}
  */
 export async function newerCommitChoice(options = {}) {
   const pinDir = options.pinDir || requirePin(options.repoRoot).dir
@@ -164,7 +164,9 @@ export async function newerCommitChoice(options = {}) {
   }
   const name = typeof form.name === "string" ? form.name.trim() : ""
   if (!name) throw new ContractError("form-shape-changed", `${VERIFY_FORM_PATH} has no name`)
-  return { formPath: VERIFY_FORM_PATH, name, choice }
+  const url = new URL(`${MARKETPLACE_PIN.repository.replace(/\/$/, "")}/issues/new`)
+  url.searchParams.set("template", VERIFY_FORM_PATH.split("/").at(-1))
+  return { formPath: VERIFY_FORM_PATH, name, choice, url: url.href }
 }
 
 /**

package/tools/marketplace/options.mjs

@@ -27,6 +27,7 @@ export const ACCEPTED = Object.freeze({
   upgrade: Object.freeze({ valued: [], flags: ["--dry-run"], positionals: 0 }),
   doctor: Object.freeze({ valued: ["--out"], flags: ["--offline", "--json"], positionals: 0 }),
   parity: Object.freeze({ valued: ["--count", "--offset", "--out"], flags: [], positionals: 0 }),
+  audit: Object.freeze({ valued: ["--out"], flags: ["--drift", "--json", "--offline"], positionals: 1 }),
   weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
 })
 

package/tools/marketplace/style.mjs

@@ -198,6 +198,12 @@ export const STATUS = Object.freeze({
   skipped: Object.freeze({ glyph: DENSITY.ceiling, word: "skip", tint: "unknown" }),
 })
 
+export const AUDIT_VERDICTS = Object.freeze({
+  validated: "AUDITED",
+  drift: "DRIFT",
+  unavailable: "NOT AUDITED",
+})
+
 /** The width of the widest mark, "█ FAIL"; every mark is padded to it so the names beside them align. */
 export const MARK_WIDTH = Math.max(...Object.values(STATUS).map((s) => `${s.glyph} ${s.word}`.length))
 
@@ -416,10 +422,10 @@ export function continuation(value, c) {
  * under itself. There is exactly one of these under any failure, and it is the
  * only line in the tool that starts with an arrow, so it can be found by shape.
  */
-export function action(text, c, { indent = GUTTER } = {}) {
+export function action(text, c, { indent = GUTTER, width: total = COLUMNS } = {}) {
   // Painted after wrapping, and all of it cyan: the whole line is the thing
   // to do, so a backticked word inside it has nothing to stand out from.
-  const lines = wrap(text, { indent: indent + 2 })
+  const lines = wrap(text, { indent: indent + 2, width: total })
   return lines.map((line, index) => (index === 0
     ? `${" ".repeat(indent)}${c("typeable.bold", ARROW)} ${c("typeable", line.trimStart())}`
     : `${" ".repeat(indent + 2)}${c("typeable", line.trimStart())}`))

package/tools/marketplace/upgrade.mjs

@@ -155,7 +155,10 @@ export const COMPLETION_REFRESH_ARGS = Object.freeze(["setup", "--completion"])
 
 function refreshCompletionWith(root, stream) {
   const entryPoint = join(root, "bin/omakit")
-  if (!existsSync(entryPoint)) return { ran: false, reason: `${entryPoint} is not there` }
+  // The reason names the relative path: the root is printed above it, and a
+  // temporary directory on macOS is long enough to push an absolute one
+  // past eighty columns in a sentence (measured in CI: 109).
+  if (!existsSync(entryPoint)) return { ran: false, reason: "this install has no bin/omakit under its root" }
   try {
     const out = execFileSync(process.execPath, [entryPoint, ...COMPLETION_REFRESH_ARGS], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
     stream.write(out)

package/tools/marketplace/usage.mjs

@@ -39,6 +39,17 @@ export const COMMANDS = Object.freeze([
       `Read-only, exact commit ${MARKETPLACE_PIN.commit}.`,
     ],
   },
+  {
+    signature: [
+      "omakit audit <plugin-id-or-dir> [--drift] [--json] [--out <file>] [--offline]",
+      "omakit audit [--drift] [--json] [--out <file>] [--offline]",
+    ],
+    lines: [
+      "Compare every installed third-party plugin's running commit with the",
+      "exact commits the marketplace records as validated. Read-only. --drift",
+      "shows only rows that are not validated; --offline reads the pin.",
+    ],
+  },
   {
     signature: [
       "omakit submit <target> --category <c> --tags <a,b> [--notes <text>]",

package/tools/weigh/confirm.mjs

@@ -5,13 +5,30 @@
 // typed here is written anywhere.
 
 import { createInterface } from "node:readline"
-import { action, colourEnabled, styler } from "../marketplace/style.mjs"
+import { action, colourEnabled, COLUMNS, styler } from "../marketplace/style.mjs"
 
 /**
- * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream, colour?: boolean, question: string }} options
- * @returns {Promise<boolean>} true only for `y` or `yes`, in any case; the end of stdin is no
+ * The question as it is written to the terminal: the arrow line, wrapped
+ * at the contract width like every other action, with `[y/N]:` at the end
+ * of the last line, and no newline after it, so the cursor waits there.
+ * Measured on 0.2.1: the question grew a clause about --runs, wrapped to
+ * two lines, and only the first was written, so a person saw "for a" and
+ * no prompt, pressed Enter to see the rest, and the empty line was No.
+ *
+ * @param {string} question
+ * @param {(name: string, text: string) => string} c
+ * @param {{ width?: number }} [options]
+ * @returns {string} every line, joined, ending in `[y/N]: `
  */
-export function askYes({ input = process.stdin, output = process.stderr, colour = colourEnabled(output), question }) {
+export function renderQuestion(question, c, { width = COLUMNS } = {}) {
+  return `${action(`${question} [y/N]:`, c, { indent: 0, width }).join("\n")} `
+}
+
+/**
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream, colour?: boolean, question: string, width?: number }} options
+ * @returns {Promise<boolean>} true only for `y` or `yes`, in any case; an empty line and the end of stdin are no
+ */
+export function askYes({ input = process.stdin, output = process.stderr, colour = colourEnabled(output), question, width = COLUMNS }) {
   const c = styler(colour)
   return new Promise((resolve) => {
     const rl = createInterface({ input, terminal: false })
@@ -27,6 +44,6 @@ export function askYes({ input = process.stdin, output = process.stderr, colour
       if (!answered) output.write("\n")
       settle(false)
     })
-    output.write(`${action(`${question} [y/N]:`, c, { indent: 0 })[0]} `)
+    output.write(renderQuestion(question, c, { width }))
   })
 }

package/tools/weigh/list.mjs

@@ -43,12 +43,13 @@ export function lastWeighings(stateDir) {
 }
 
 /**
- * One row per installed plugin, sorted: enabled and not weighed first (by
- * id), then enabled and weighed, oldest weighing first, then disabled.
+ * The installed-plugin list joined to the manifest catalog by id. This is the
+ * one join used by both `weigh --list` and `audit`, so a source directory has
+ * one authority throughout the tool.
  *
  * @param {{ env?: NodeJS.ProcessEnv }} [options]
  */
-export function listWeighings({ env = process.env } = {}) {
+export function installedPlugins({ env = process.env } = {}) {
   const listed = run("listPlugins", { env })
   if (!listed.ok) throw new WeighError("shell-not-running", "omarchy plugin list did not answer, and the list is what the shell has installed", "omarchy-restart-shell")
   let installed
@@ -57,6 +58,7 @@ export function listWeighings({ env = process.env } = {}) {
   } catch {
     throw new WeighError("shell-unreadable", "omarchy plugin list did not answer with JSON", "omarchy-restart-shell, then run it again.")
   }
+  if (!Array.isArray(installed)) throw new WeighError("shell-unreadable", "omarchy plugin list did not answer with a JSON array", "omarchy-restart-shell, then run it again.")
   const catalogRun = run("catalog", { env })
   let catalog = []
   try {
@@ -65,6 +67,17 @@ export function listWeighings({ env = process.env } = {}) {
     catalog = []
   }
   const sourceDirOf = (id) => catalog.find((entry) => entry.id === id)?.sourceDir || null
+  return installed.map((plugin) => ({ ...plugin, sourceDir: sourceDirOf(plugin.id) }))
+}
+
+/**
+ * One row per installed plugin, sorted: enabled and not weighed first (by
+ * id), then enabled and weighed, oldest weighing first, then disabled.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ */
+export function listWeighings({ env = process.env } = {}) {
+  const installed = installedPlugins({ env })
   const stateDir = omakitStateDir("weigh", env)
   const latest = lastWeighings(stateDir)
   const rows = installed.map((plugin) => {
@@ -76,7 +89,7 @@ export function listWeighings({ env = process.env } = {}) {
       kinds,
       enabled: plugin.enabled === true,
       firstParty: plugin.firstParty === true,
-      sourceDir: sourceDirOf(plugin.id),
+      sourceDir: plugin.sourceDir,
       weighable: !kinds.includes("bar"),
       lastWeighed: last ? { date: last.date, readme: last.readme, summary: last.summary, document: last.document } : null,
       enable: plugin.enabled === true ? null : `omarchy plugin enable ${plugin.id}`,