omakit 0.1.0

package/tools/marketplace/registry.mjs

@@ -0,0 +1,216 @@
+// The plugin-id and repository universe, read from the pinned marketplace
+// checkout. Like the submission contract, nothing here is hardcoded: the
+// reserved namespace is read out of the marketplace's own catalog builder, the
+// listed ids out of the published catalog and the registry sources, and the
+// retired ids out of `registry.json`.
+//
+// Measured reason these three checks exist (docs/MEASUREMENTS.md M2): the
+// marketplace refuses a submission whose id is already listed
+// (`plugin-id-listed`), was used by a previous listing (`plugin-id-retired`),
+// or sits in the reserved namespace (`reserved-plugin-id`), and it refuses a
+// repository that is already listed (`submission-repository-listed`). Each
+// refusal costs the author a full round trip through a human queue whose
+// median submission-to-publication time rose sevenfold between 2026-W33 and
+// 2026-W36, and it is knowable before submitting from data the marketplace
+// publishes.
+
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { requirePin } from "./pin.mjs"
+
+export const CATALOG_PATH = "site/catalog.json"
+export const REGISTRY_PATH = "registry.json"
+export const CATALOG_BUILDER_PATH = "scripts/build-catalog.mjs"
+
+export class RegistryError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = "RegistryError"
+    this.code = code
+  }
+}
+
+function readJson(pinDir, relative) {
+  try {
+    return JSON.parse(readFileSync(join(pinDir, relative), "utf8"))
+  } catch (error) {
+    throw new RegistryError("pin-unreadable", `cannot read ${relative} from the pinned checkout: ${error.message}`)
+  }
+}
+
+/**
+ * The reserved namespace as the marketplace states it, read from the pinned
+ * `build-catalog.mjs` next to its own `reserved-plugin-id` check. Read, not
+ * copied, so a pin update moves it.
+ */
+export function reservedNamespace(pinDir) {
+  const source = readFileSync(join(pinDir, CATALOG_BUILDER_PATH), "utf8")
+  const match = source.match(/startsWith\("([A-Za-z0-9.\-_]+\.)"\)\s*\)\s*\{\s*\n\s*checkError\("reserved-plugin-id"/)
+    || source.match(/checkError\("reserved-plugin-id",\s*`[^`]*\$\{[^}]*\}:\s*the ([A-Za-z0-9.\-_]+)\.\*\s+namespace is reserved`/)
+  if (!match) {
+    throw new RegistryError(
+      "pin-unreadable",
+      `cannot read the reserved plugin-id namespace from ${CATALOG_BUILDER_PATH} at the pin; refusing to guess it`,
+    )
+  }
+  return match[1].endsWith(".") ? match[1] : `${match[1]}.`
+}
+
+function repositorySlug(value) {
+  try {
+    return new URL(String(value)).pathname.replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "").toLowerCase()
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * @param {{ repoRoot?: string, pinDir?: string }} [options]
+ * @returns {{ reservedPrefix: string, listedIds: Set<string>, retiredIds: Set<string>,
+ *             listedRepositories: Set<string>, counts: object }}
+ */
+export function idUniverse(options = {}) {
+  const pinDir = options.pinDir || requirePin(options.repoRoot).dir
+  const catalog = readJson(pinDir, CATALOG_PATH)
+  const registry = readJson(pinDir, REGISTRY_PATH)
+
+  const listedIds = new Set()
+  for (const plugin of Array.isArray(catalog.plugins) ? catalog.plugins : []) {
+    if (typeof plugin?.id === "string" && plugin.id) listedIds.add(plugin.id)
+  }
+  const catalogIds = listedIds.size
+
+  const sources = Array.isArray(registry.sources) ? registry.sources : Object.values(registry.sources || {})
+  const listedRepositories = new Set()
+  for (const source of sources) {
+    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)
+    }
+    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 (typeof source?.catalog?.id === "string") listedIds.add(source.catalog.id)
+    for (const id of source?.automatedSecurityBaseline?.pluginIds || []) {
+      if (typeof id === "string") listedIds.add(id)
+    }
+  }
+
+  const retiredIds = new Set((registry.retiredPluginIds || []).filter((id) => typeof id === "string"))
+
+  if (!listedIds.size || !listedRepositories.size) {
+    throw new RegistryError("pin-unreadable", "the pinned catalog and registry produced no listed ids or repositories")
+  }
+
+  return {
+    pinDir,
+    reservedPrefix: reservedNamespace(pinDir),
+    listedIds,
+    retiredIds,
+    listedRepositories,
+    counts: {
+      catalogPlugins: catalogIds,
+      registrySources: sources.length,
+      listedIds: listedIds.size,
+      retiredIds: retiredIds.size,
+      listedRepositories: listedRepositories.size,
+    },
+  }
+}
+
+/**
+ * The recorded baseline over every listed source, counted from registry.json at
+ * the pin. This is the one place the figures cited by `baseline.preflight` and
+ * docs/MEASUREMENTS.md M4 come from; tests/unit/registry-figures.test.mjs pins
+ * the values, so a pin bump changes the printed number rather than leaving a
+ * stale literal behind.
+ *
+ * @param {{ repoRoot?: string, pinDir?: string }} [options]
+ * @returns {{ sources: number, withBaseline: number, outcomes: Record<string, number>,
+ *             capabilities: Record<string, number>, findings: Record<string, number>,
+ *             findingsTotal: number, superseded: { sources: number, commits: number, most: number },
+ *             retiredIds: number, catalogPlugins: number }}
+ */
+export function baselineFigures(options = {}) {
+  const pinDir = options.pinDir || requirePin(options.repoRoot).dir
+  const registry = readJson(pinDir, REGISTRY_PATH)
+  const catalog = readJson(pinDir, CATALOG_PATH)
+  const sources = Array.isArray(registry.sources) ? registry.sources : Object.values(registry.sources || {})
+  const count = (table, key) => { table[key] = (table[key] || 0) + 1 }
+  const outcomes = {}
+  const capabilities = {}
+  const findings = {}
+  let withBaseline = 0
+  let findingsTotal = 0
+  let supersededSources = 0
+  let supersededCommits = 0
+  let most = 0
+  for (const source of sources) {
+    const baseline = source?.automatedSecurityBaseline
+    if (baseline && typeof baseline.outcome === "string") {
+      withBaseline += 1
+      count(outcomes, baseline.outcome)
+      for (const capability of baseline.capabilities || []) count(capabilities, typeof capability === "string" ? capability : capability?.id)
+      for (const finding of baseline.findings || []) {
+        count(findings, typeof finding === "string" ? finding : finding?.rule || finding?.id)
+        findingsTotal += 1
+      }
+    }
+    const history = Array.isArray(source?.listingValidationHistory) ? source.listingValidationHistory.length : 0
+    if (history > 0) supersededSources += 1
+    supersededCommits += history
+    if (history > most) most = history
+  }
+  return {
+    sources: sources.length,
+    withBaseline,
+    outcomes,
+    capabilities,
+    findings,
+    findingsTotal,
+    superseded: { sources: supersededSources, commits: supersededCommits, most },
+    retiredIds: (registry.retiredPluginIds || []).length,
+    catalogPlugins: Array.isArray(catalog.plugins) ? catalog.plugins.length : 0,
+  }
+}
+
+/** 1681 -> "1,681", the way the docs print figures. */
+export function figure(n) {
+  return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",")
+}
+
+/**
+ * @param {{ id: string, repositoryUrl?: string|null }} subject
+ * @returns {{ ok: boolean, problems: Array<{ code: string, detail: string }> }}
+ */
+export function checkIdentity(universe, subject) {
+  const problems = []
+  const id = String(subject.id || "")
+  if (!id) {
+    problems.push({ code: "plugin-id-missing", detail: "the root manifest declares no id" })
+    return { ok: false, problems }
+  }
+  if (id.toLowerCase().startsWith(universe.reservedPrefix)) {
+    problems.push({
+      code: "reserved-plugin-id",
+      detail: `"${id}" is inside the reserved ${universe.reservedPrefix}* namespace`,
+    })
+  }
+  if (universe.retiredIds.has(id)) {
+    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 slug = repositorySlug(subject.repositoryUrl)
+  if (slug && universe.listedRepositories.has(slug)) {
+    problems.push({ code: "submission-repository-listed", detail: `${slug} is already listed` })
+  }
+  return { ok: problems.length === 0, problems }
+}
+
+export { repositorySlug }

package/tools/marketplace/report.mjs

@@ -0,0 +1,192 @@
+// Text rendering of a submit preflight, a validation watch and a doctor run, for the
+// agent that runs this tool and the person reading over its shoulder. Every
+// check prints its verdict, its source and the measured reason it exists; a
+// failing check prints its paths and the one action that clears it.
+//
+// Everything here is drawn with style.mjs and nothing of its own: the marks,
+// the columns, the arrow and the rule are the same ones every other command
+// uses. Colour is added only when a person is looking at a terminal. The text
+// itself is identical either way, so a piped run and a watched run say exactly
+// the same thing.
+//
+// Two decisions are about scanning rather than reading. Passing checks are
+// dense, two lines each with nothing between them, and a failing check is a
+// block with a blank line on either side, so on a monochrome theme the
+// failures are still the things with air around them. And a refusal ends with
+// the failing checks and their actions again, because after fifteen checks and
+// the marketplace's forty-line report the fail blocks are off the top of the
+// screen, and the last screen is the one a person is looking at.
+
+import {
+  action, colourEnabled, COLUMNS, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
+} from "./style.mjs"
+
+const body = " ".repeat(GUTTER)
+
+/** The state a check renders in: an advisory failure is a note, not a FAIL. */
+function stateOf(check) {
+  if (check.verdict === "pass") return "pass"
+  return check.severity === "advisory" ? "advisory" : "fail"
+}
+
+/**
+ * A check's head line: the mark, the id in bold, and the source in brackets
+ * pushed to the right edge, so the sources form a column of their own and the
+ * ids form another.
+ */
+function head(state, id, source, c) {
+  const left = `${mark(state, c)}${c("name", id)}`
+  const tag = c("punctuation", `[${source}]`)
+  const gap = Math.max(2, COLUMNS - width(left) - width(tag))
+  return `${left}${" ".repeat(gap)}${tag}`
+}
+
+function checkBlock(check, c) {
+  const state = stateOf(check)
+  const out = [head(state, check.id, check.source, c)]
+  if (check.detail) out.push(...wrap(check.detail, { indent: GUTTER }, c))
+  if (check.verdict === "fail") {
+    // A path is the thing at fault, so it is yellow; its reason wraps under it.
+    for (const path of check.paths) {
+      out.push(...wrap(`- ${path}`, { indent: GUTTER + STEP, first: GUTTER })
+        .map((line, index) => (index === 0
+          ? `${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))
+    // 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))
+  }
+  return out
+}
+
+export function renderSubmit(result, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = []
+  out.push(...field("subject", result.subject.repository || result.subject.directory, c, { wrapValue: false }))
+  out.push(...field("commit", `${result.subject.commit}${result.subject.cleanTree ? "" : c("advisory", " (dirty worktree)")}`, c, { wrapValue: false }))
+  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,
+  // collapsed where two blocks meet.
+  let previous = "pass"
+  for (const [index, check] of result.checks.entries()) {
+    const state = stateOf(check)
+    if (index > 0 && (state !== "pass" || previous !== "pass")) out.push("")
+    out.push(...checkBlock(check, c))
+    previous = state
+  }
+  out.push("")
+
+  if (result.baseline?.officialReport) {
+    out.push(...section("the marketplace's own baseline report for this commit", c))
+    out.push(result.baseline.officialReport)
+    out.push("")
+    out.push(...wrap(result.baseline.statement, {}, c))
+    out.push("")
+  }
+
+  if (!result.ready) {
+    const failed = result.checks.filter((check) => result.blocking.includes(check.id))
+    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))
+    out.push("")
+    for (const check of failed) {
+      out.push(`${body}${c("name", check.id)}`)
+      if (check.remedy) out.push(...action(check.remedy, c))
+      else out.push(...wrap(check.detail, { indent: GUTTER }, c))
+      out.push("")
+    }
+    out.push(failed.length === 1 ? "Fix it, then run submit again." : "Fix them, then run submit again.")
+    return out.join("\n")
+  }
+
+  const validation = result.validationCommit.defaultBranchHead
+    ? `${result.validationCommit.local} is the ${result.validationCommit.branch || "default"}-branch HEAD, so it is the commit the marketplace will validate.`
+    : `${result.validationCommit.local} is the local commit; the marketplace validates the default-branch HEAD it resolves when the issue is opened.`
+  out.push(...verdict("pass", "READY", `every blocking check passed. ${validation}`, c))
+  out.push("")
+  out.push(...section("issue title", c))
+  out.push(c("heading", result.issue.title))
+  out.push("")
+  out.push(...section("issue body", c))
+  out.push(result.issue.body.trimEnd())
+  out.push("")
+  out.push(...wrap("This is not posted. Ask the plugin owner to approve it, then create the issue yourself, for example:", {}, c))
+  out.push("")
+  // The one action, as a command a person runs. It is not wrapped as prose
+  // because a shell command breaks on its backslashes, not on its spaces.
+  const step = " ".repeat(STEP)
+  out.push(...action("gh issue create --repo omacom/omarchy-plugin-marketplace \\", c, { indent: 0 }))
+  out.push(`${step}${c("typeable", `--title ${JSON.stringify(result.issue.title)} \\`)}`)
+  out.push(`${step}${c("typeable", "--body-file <the body above>")}`)
+  out.push("")
+  out.push(...wrap(`After it is created: ${result.afterSubmitting}`, {}, c))
+  return out.join("\n")
+}
+
+export function renderWatch(result, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = []
+  out.push(...field("issue", result.read.issue, c, { wrapValue: false }))
+  out.push(...field("state", `${result.read.state}${result.read.labels.length ? `; labels ${result.read.labels.join(", ")}` : ""}`, c))
+  out.push(...field("title", result.read.title, c))
+  out.push(...field("plugin repo", result.plugin.repository || `unreadable: ${result.plugin.repositoryError}`, c, { wrapValue: false }))
+  if (result.plugin.form === "verify" || result.plugin.form === "verify-legacy") {
+    out.push(...field("form", "plugin update request, read with the marketplace's verification parser", c))
+  }
+  out.push("")
+  if (result.validated) {
+    out.push(...field("validated", c("name", result.validated.commit), c, { wrapValue: false }))
+    out.push(...continuation(`outcome ${result.validated.outcome}, ${result.validated.findings.length} finding(s), ${result.validated.capabilities.length} capability/ies, checked ${result.validated.checkedAt}`, c))
+  } else if (result.validationCommentFallback) {
+    out.push(...field("validated", `${result.validationCommentFallback.short} (short form, from the validation comment)`, c))
+  } else {
+    out.push(...field("validated", "none", c))
+  }
+  if (result.head) {
+    const sha = result.verdict.state === "stale" ? c("fail", result.head.commit) : c("name", result.head.commit)
+    out.push(...field("current HEAD", sha, c, { wrapValue: false }))
+    out.push(...continuation(`${result.head.branch || "default"} branch, via ${result.head.source}${result.head.committedAt ? `, ${result.head.committedAt}` : ""}`, c))
+  } else if (result.headError) {
+    out.push(...field("current HEAD", `unreadable: ${result.headError.message}`, c))
+  }
+  out.push("")
+  const state = { current: "pass", stale: "fail", unknown: "unknown" }[result.verdict.state] || "unknown"
+  out.push(...verdict(state, `VALIDATION ${result.verdict.state.toUpperCase()}`, result.verdict.summary, c))
+  if (result.verdict.action) {
+    out.push("")
+    out.push(...action(result.verdict.action, c, { indent: 0 }))
+  }
+  out.push("")
+  out.push(...wrap(
+    `Read-only. This command did not comment, label or edit anything. Comments on the issue: ${result.read.comments} (${result.read.authorComments} from the author, ${result.read.maintainerComments} from a reviewer).`,
+    {},
+    c,
+  ))
+  return out.join("\n")
+}
+
+const DOCTOR_STATE = { ok: "pass", advice: "advisory", problem: "fail", info: "info", unknown: "unknown" }
+
+export function renderDoctor(result, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = []
+  let previous = false
+  for (const [index, check] of result.checks.entries()) {
+    const state = DOCTOR_STATE[check.state] || "unknown"
+    const loud = state === "fail" || state === "advisory"
+    if (index > 0 && (loud || previous)) out.push("")
+    out.push(`${mark(state, c)}${c("name", check.id)}`)
+    out.push(...wrap(check.detail, { indent: GUTTER }, c))
+    if (check.action) out.push(...action(check.action, c))
+    previous = loud
+  }
+  out.push("")
+  out.push(...(result.problems
+    ? verdict("fail", "NOT READY", `${result.problems === 1 ? "1 problem" : `${result.problems} problems`} to fix before omakit can run.`, c)
+    : verdict("pass", "READY", "nothing to fix.", c)))
+  return out.join("\n")
+}

package/tools/marketplace/run-baseline.mjs

@@ -0,0 +1,72 @@
+// Run the pinned official Omarchy marketplace security baseline over one
+// commit, either through GitHub (the transport the marketplace itself uses) or
+// through the local Git transport in this directory.
+//
+// Omakit never copies or edits marketplace policy: the analysis below is the
+// official code, imported unmodified from a pinned read-only checkout.
+
+import { join, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { createLocalTransport, ADAPTER_VERSION, ASSUMED_BY_ADAPTER } from "./local-transport.mjs"
+import { requirePin } from "./pin.mjs"
+import { token } from "./github.mjs"
+
+async function loadScanner(pinDir) {
+  const url = pathToFileURL(join(pinDir, "scripts/security-baseline-scanner.mjs")).href
+  return import(url)
+}
+
+/**
+ * @param {{ repoRoot: string, repoUrl: string, commitSha: string, transport: "local"|"github",
+ *           repoDir?: string, listedPlugins?: Array, token?: string }} options
+ */
+export async function runBaseline(options) {
+  const { dir: pinDir, identity } = requirePin(options.repoRoot)
+  const pin = { commit: identity.commit, baselineVersion: identity.baselineVersion, enforcementMode: identity.enforcementMode }
+  const { runSecurityBaseline } = await loadScanner(pinDir)
+
+  const scanOptions = { checkedAt: "1970-01-01T00:00:00.000Z" }
+  if (options.listedPlugins) scanOptions.listedPlugins = options.listedPlugins
+  let adapter = null
+
+  if (options.transport === "local") {
+    const transport = createLocalTransport({
+      repoDir: options.repoDir,
+      repoUrl: options.repoUrl,
+      commitSha: options.commitSha,
+    })
+    scanOptions.fetchImpl = transport.fetchImpl
+    adapter = {
+      transport: "local-git",
+      adapterVersion: ADAPTER_VERSION,
+      assumedByAdapter: ASSUMED_BY_ADAPTER,
+      requests: transport.stats,
+    }
+  } else {
+    if (options.token) scanOptions.token = options.token
+    adapter = { transport: "github" }
+  }
+
+  const result = await runSecurityBaseline(options.repoUrl, options.commitSha, scanOptions)
+  return { pin, adapter, result }
+}
+
+function arg(name) {
+  const prefix = `--${name}=`
+  return process.argv.find((value) => value.startsWith(prefix))?.slice(prefix.length)
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+if (isMain) {
+  const repoRoot = resolve(arg("repo-root") || process.cwd())
+  const transport = arg("transport") === "github" ? "github" : "local"
+  const out = await runBaseline({
+    repoRoot,
+    repoUrl: arg("repo-url"),
+    commitSha: arg("commit"),
+    transport,
+    repoDir: arg("dir") ? resolve(arg("dir")) : undefined,
+    token: token() ?? undefined,
+  })
+  process.stdout.write(`${JSON.stringify(out, null, 2)}\n`)
+}

package/tools/marketplace/setup.mjs

@@ -0,0 +1,136 @@
+// `omakit setup`: the first run, in one command.
+//
+// It replaces the three things a newcomer otherwise has to know: that a pinned
+// marketplace checkout has to be fetched before anything works, where it goes,
+// and what to try first. It is idempotent, so running it again on a machine that
+// is already set up just confirms that.
+//
+// It writes exactly one thing: the pinned checkout, through the same `ensurePin`
+// that `omakit pin` uses. It does not create symlinks, edit a shell profile or
+// install anything. Where a step is the user's to take, it prints the command
+// and stops, which is the same contract every other command here keeps.
+
+import { execFileSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { delimiter, join } from "node:path"
+import { banner } from "./banner.mjs"
+import { credential, UNAUTHENTICATED_LIMIT } from "./github.mjs"
+import { ensurePin, marketplacePinDir, pinDiskUsage } from "./pin.mjs"
+import { progress } from "./progress.mjs"
+import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
+import { TAGLINE } from "./usage.mjs"
+import { installCompletion } from "./completion.mjs"
+import { submissionContract } from "./form.mjs"
+
+function version(command) {
+  try {
+    return execFileSync(command, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .trim()
+      .split("\n")[0]
+  } catch {
+    return null
+  }
+}
+
+/** Is `omakit` reachable as a bare command, without asking a shell? */
+export function onPath(name = "omakit", env = process.env) {
+  return (env.PATH || "").split(delimiter).some((dir) => dir && existsSync(join(dir, name)))
+}
+
+/**
+ * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream }} options
+ */
+export async function setup({ repoRoot, entryPoint, stream = process.stdout }) {
+  const c = styler(colourEnabled(stream))
+  const out = (line = "") => stream.write(`${line}\n`)
+  // A step is a status line: the mark, then the fact, wrapped under itself.
+  const step = (state, text) => out(`${mark(state, c)}${wrap(text, { indent: GUTTER }, c).join("\n").trimStart()}`)
+  // The one action under a step sits in the step's body; under a sentence it
+  // sits where the sentence does.
+  const fix = (text, indent = GUTTER) => { for (const line of action(text, c, { indent })) out(line) }
+
+  // The one place the wordmark runs through `ttfx` (effect.mjs): a first run
+  // already spending seconds fetching the pin.
+  await banner({ stream, tagline: TAGLINE, effect: true })
+
+  const node = process.versions.node
+  const major = Number(node.split(".")[0])
+  if (major < 22) {
+    step("fail", `node ${node} is too old; omakit needs 22 or newer.`)
+    fix("Install Node 22 or newer, then run `omakit setup` again.")
+    return { ok: false }
+  }
+  step("pass", `node ${node}`)
+
+  const git = version("git")
+  if (!git) {
+    step("fail", "git was not found on PATH. omakit needs it for the pin and for reading a commit's tree.")
+    fix("Install git, then run `omakit setup` again.")
+    return { ok: false }
+  }
+  step("pass", git)
+
+  // GitHub access, before the pin, because this is the one step a newcomer might
+  // otherwise think they have to prepare a token for. They do not.
+  const auth = credential({ refresh: true })
+  if (auth.source === "gh") {
+    step("pass", "GitHub: your `gh` login, read-only. omakit stores nothing.")
+  } else {
+    step("info", `no GitHub login. \`submit\` and \`verify\` need none at all; \`watch\` and \`parity\` are capped at ${UNAUTHENTICATED_LIMIT} requests an hour without one.`)
+    fix("`gh auth login` is enough; omakit reads it read-only and stores nothing.")
+  }
+
+  const dir = marketplacePinDir(repoRoot)
+  const spinner = progress()
+  let identity
+  try {
+    identity = ensurePin(repoRoot, (line) => {
+      if (line.state === "fetching") spinner.phase(line.text)
+    }).identity
+  } catch (error) {
+    spinner.done()
+    step("fail", error.message)
+    fix(error.remedy || (error.code === "network-unavailable"
+      ? "Connect to the network, then run `omakit setup` again."
+      : "Remove the checkout, then run `omakit setup` again."))
+    return { ok: false }
+  }
+  spinner.done()
+  step("pass", `marketplace pin ${identity.commit.slice(0, 7)} (baseline ${identity.baselineVersion}, ${identity.enforcementMode}), ${pinDiskUsage(dir)}`)
+  out()
+  for (const line of wrap("Every rule omakit checks is read from that checkout, at that exact commit. It never moves on its own. `omakit doctor` says when it is behind.", {}, c)) out(line)
+  out()
+
+  if (!onPath()) {
+    step("info", "`omakit` is not on your PATH yet. This puts it there:")
+    fix(`ln -s ${entryPoint} ~/.local/bin/omakit`)
+    out()
+  }
+
+  // Tab completion, installed for the shell in $SHELL where that shell loads
+  // it from, so nobody has to know the path. The script carries the pin's
+  // categories and tags, so it is rewritten when the pin has moved and left
+  // alone otherwise.
+  try {
+    const contract = await submissionContract({ repoRoot })
+    const completion = installCompletion({ contract, pin: identity.commit })
+    if (completion.state === "unsupported") {
+      step("info", completion.shell
+        ? `tab completion: no script for ${completion.shell}; there is one for bash, zsh and fish.`
+        : "tab completion: $SHELL is not set, so no script was installed.")
+    } else {
+      const what = { installed: "installed", updated: "updated for this pin", current: "already installed" }[completion.state]
+      step("pass", `tab completion for ${completion.shell} ${what} at ${completion.display}${completion.note ? `, ${completion.note}` : ""}.`)
+    }
+  } catch (error) {
+    step("info", `tab completion was not installed: ${error.message}`)
+  }
+  out()
+
+  out("Try it on a plugin you have checked out:")
+  out()
+  fix("omakit submit <plugin-repo> --category Widgets --tags bar,quickshell", 0)
+  out()
+  for (const line of wrap("It prints the issue title and body. It never posts anything.", {}, c)) out(line)
+  return { ok: true }
+}