omakit 0.1.0

package/tools/marketplace/submit.mjs

@@ -0,0 +1,341 @@
+// `omakit submit`: everything that is knowable before a submission is posted,
+// with the measured reason for every check stated next to the check.
+//
+// The command produces an issue title and body. It never posts them. Creating
+// the issue happens only after the plugin owner explicitly approves, which is
+// also what the marketplace's own agent instructions require.
+//
+// Two sources of authority, never mixed:
+//   source: "marketplace-pin", the rule is the marketplace's, read from the
+//           pinned checkout at an exact commit. A pin update can change it.
+//   source: "omakit",          the check is Omakit's own, derived from public
+//           issue text. It is not marketplace policy and never claims to be.
+
+import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
+import { requirePin } from "./pin.mjs"
+import { submissionContract, resolveCategory, resolveTags } from "./form.mjs"
+import { idUniverse, checkIdentity, baselineFigures, figure } from "./registry.mjs"
+import { readTree } from "./tree.mjs"
+import { inspectTree } from "./plugin.mjs"
+import { findAgentControl, REMEDY as AGENT_CONTROL_REMEDY } from "./agent-control.mjs"
+import { baselinePreflight } from "./preflight.mjs"
+import { renderIssue, verifyAgainstOfficialParser } from "./issue.mjs"
+import { defaultBranchHead } from "./github.mjs"
+import { REFRESH_ACTION } from "./watch.mjs"
+import { omakitCacheDir } from "./paths.mjs"
+
+export class SubmitError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = "SubmitError"
+    this.code = code
+  }
+}
+
+function check(id, fields) {
+  return {
+    id,
+    source: fields.source,
+    why: fields.why,
+    severity: fields.severity || "blocking",
+    verdict: fields.verdict ? "pass" : "fail",
+    detail: fields.detail || "",
+    paths: fields.paths || [],
+    remedy: fields.remedy || null,
+  }
+}
+
+/**
+ * @param {{ repoRoot: string, target: string, category?: string, tags?: string|string[],
+ *           notes?: string, suggestedTag?: string, pluginName?: string,
+ *           allowDirty?: boolean, offline?: boolean }} options
+ */
+export async function submitPreflight(options) {
+  const { repoRoot } = options
+  // Optional: called with the name of the step about to run, so a terminal can
+  // say what is happening. Never affects what is produced.
+  const phase = options.onPhase || (() => {})
+
+  phase("verifying the pinned marketplace checkout")
+  const { identity: pinIdentity } = requirePin(repoRoot)
+  phase("reading the submission contract from the pin")
+  const contract = await submissionContract({ repoRoot })
+  phase("reading the listed and retired plugin ids")
+  const universe = idUniverse({ repoRoot })
+  const figures = baselineFigures({ repoRoot })
+
+  phase("resolving the subject commit")
+  let subject
+  try {
+    subject = resolveSubject(options.target, {
+      cacheRoot: omakitCacheDir(),
+      allowDirty: options.allowDirty === true,
+    })
+  } catch (error) {
+    if (error instanceof SubjectError) throw new SubmitError(error.code, error.message)
+    throw error
+  }
+
+  phase("reading the installable tree at that commit")
+  const entries = readTree(subject.dir, subject.commit)
+  const tree = inspectTree({ dir: subject.dir, entries })
+  const checks = []
+
+  // --- the installable tree -------------------------------------------------
+
+  checks.push(check("plugin.root-manifest", {
+    source: "marketplace-pin",
+    why: "The marketplace refuses a submission that is not exactly one manifest at the repository root: \"New submissions require exactly one plugin manifest at the repository root\" (scripts/build-catalog.mjs at the pin). A layout failure costs a full round trip through a queue whose median submission-to-publication time rose sevenfold between 2026-W33 and 2026-W36.",
+    verdict: tree.manifestPaths.length === 1 && tree.rootManifestPath === "manifest.json" && !tree.manifestError && Boolean(tree.pluginId),
+    detail: tree.manifestError
+      ? `manifest.json is not valid JSON: ${tree.manifestError}`
+      : tree.manifestPaths.length === 1 && tree.rootManifestPath
+        ? `manifest.json declares id "${tree.pluginId}"${tree.pluginName ? ` and name "${tree.pluginName}"` : ""}`
+        : `found ${tree.manifestPaths.length} manifest(s): ${tree.manifestPaths.join(", ") || "none"}`,
+    paths: tree.manifestPaths,
+    remedy: "Keep exactly one manifest.json, at the repository root.",
+  }))
+
+  checks.push(check("plugin.root-readme", {
+    source: "marketplace-pin",
+    why: "`validateRepositoryDocs` at the pin fails a submission with `readme-missing` when no root README exists. A deterministic failure like this one returns the submission to the author's own court, and that court is where submissions die: of the 464 parked there the median item has not moved in 5.6 days, and 77% never produce the fresh validation that would revive them. Knowable here in one read of the tree.",
+    verdict: Boolean(tree.readme),
+    detail: tree.readme ? `root README: ${tree.readme}` : "no root README",
+    remedy: "Add a README at the repository root.",
+  }))
+
+  checks.push(check("plugin.root-license", {
+    source: "marketplace-pin",
+    why: "`validateRepositoryDocs` at the pin fails a submission with `license-missing` when no root license or COPYING file exists. Same cost as a missing README: all 2,963 listed sources in the pinned registry satisfied this rule before they were listed, so it is absolute, and it is knowable here in one read of the tree.",
+    verdict: Boolean(tree.license),
+    detail: tree.license ? `root license: ${tree.license}` : "no root license or COPYING file",
+    remedy: "Add a LICENSE (or COPYING) file at the repository root.",
+  }))
+
+  checks.push(check("plugin.readme-install-removal", {
+    source: "omakit",
+    why: "Checklist item 1 of the form is a statement the author signs: \"The repository is public and contains installation and removal instructions.\" Omakit generates that checklist pre-checked, so it refuses to sign a claim it cannot see evidence for. This is a keyword probe on the README text, not a reading of it, and it is not a marketplace rule.",
+    verdict: tree.readmeMentionsInstall && tree.readmeMentionsRemoval,
+    detail: tree.readme
+      ? `README mentions installation: ${tree.readmeMentionsInstall ? "yes" : "no"}; removal or uninstall: ${tree.readmeMentionsRemoval ? "yes" : "no"}`
+      : "no root README to read",
+    paths: tree.readme ? [tree.readme] : [],
+    remedy: "Document both installing and removing the plugin in the root README, or submit by hand without the generated checklist.",
+  }))
+
+  // --- the agent-control warning --------------------------------------------
+  // Advisory, not blocking: the marketplace lists plugins that ship these files
+  // (docs/MEASUREMENTS.md M3), so a refusal here would refuse what it accepts.
+
+  const agentControl = findAgentControl(entries)
+  checks.push(check("tree.agent-control", {
+    source: "omakit",
+    severity: "advisory",
+    why: "103 marketplace issues mention agent-control files, and 24 of 328 sampled maintainer review comments are about them, so an instruction file inside an installed plugin draws review attention and can cost a round. It is not a listing rule: at their listed commits, 6 of 34 listed plugins inspected on 2026-09-13 ship one, so this is a review-cost warning derived from public issue text, labelled `omakit` for that reason. Nothing in the marketplace's automated baseline reports them.",
+    verdict: agentControl.length === 0,
+    detail: agentControl.length
+      ? `${agentControl.length} agent-control file(s) in the installable tree`
+      : "no agent-control files in the installable tree",
+    paths: agentControl.map((hit) => `${hit.path}: ${hit.reason}`),
+    remedy: AGENT_CONTROL_REMEDY.join(" "),
+  }))
+
+  // --- identity -------------------------------------------------------------
+
+  const identity = checkIdentity(universe, { id: tree.pluginId, repositoryUrl: subject.repository.url })
+  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 ${universe.counts.listedIds} listed ids, ${universe.counts.retiredIds} retired ids and ${universe.counts.listedRepositories} listed repositories read from the pinned registry and catalog.`,
+    verdict: identity.ok,
+    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("; "),
+    remedy: identity.ok ? null : "Choose an unused plugin id outside the reserved namespace.",
+  }))
+
+  // --- the submission itself ------------------------------------------------
+
+  const pluginName = String(options.pluginName || tree.pluginName || "").trim()
+  const category = resolveCategory(contract, options.category)
+  const tags = resolveTags(contract, options.tags)
+
+  checks.push(check("submission.title", {
+    source: "marketplace-pin",
+    why: "39 submissions fell out on the title prefix alone: 14 of them are still open and 7 had to be rescued by hand. The prefix and the requirement that a plugin name follow it are read from the form's own title template at the pin.",
+    verdict: Boolean(pluginName),
+    detail: pluginName
+      ? `title will be "${contract.titleTemplate}${pluginName}"`
+      : "no plugin name: manifest.json declares none and --name was not given",
+    remedy: "Give the plugin a name in manifest.json, or pass --name.",
+  }))
+
+  checks.push(check("submission.category", {
+    source: "marketplace-pin",
+    why: `Exactly one category from the form's controlled list; the marketplace refuses \`submission-category-invalid\` otherwise. The list (${contract.categories.length} options) is read from ${contract.formPath} at the pin.`,
+    verdict: category.ok,
+    detail: category.ok ? `category: ${category.value}` : `${category.reason}. Choose one of: ${contract.categories.join(", ")}`,
+    remedy: category.ok ? null : "Pass --category with one of the listed values.",
+  }))
+
+  checks.push(check("submission.tags", {
+    source: "marketplace-pin",
+    why: `1 to ${contract.maximumTags} tags from the form's controlled list; the marketplace refuses \`submission-tag-count-invalid\` and \`submission-tags-invalid\` otherwise. The list (${contract.tagLabels.length} options) and the maximum are read from the pin.`,
+    verdict: tags.ok,
+    detail: tags.ok ? `tags: ${tags.value.join(", ")}` : `${tags.reason}. Choose from: ${contract.tagLabels.join(", ")}`,
+    remedy: tags.ok ? null : "Pass --tags with 1 to 3 comma-separated values from the list.",
+  }))
+
+  let issue = null
+  let parsed = null
+  if (pluginName && category.ok && tags.ok && subject.repository.url) {
+    issue = renderIssue(contract, {
+      pluginName,
+      repositoryUrl: subject.repository.url,
+      category: category.value,
+      tags: tags.value,
+      suggestedTag: options.suggestedTag,
+      notes: options.notes,
+    })
+    parsed = verifyAgainstOfficialParser(contract, issue)
+  }
+
+  checks.push(check("submission.repository-url", {
+    source: "marketplace-pin",
+    why: "The marketplace refuses `submission-repository-invalid` unless the Repository URL field is a public GitHub repository root URL, and it is the field every later step depends on: all 2,963 listed sources in the pinned registry are identified by exactly that URL. Taken from the subject's `origin`, never invented, because a URL typed by hand is a URL that can point at the wrong repository.",
+    verdict: Boolean(subject.repository.url),
+    detail: subject.repository.url || "the subject has no github.com origin, so no repository URL can be declared",
+    remedy: subject.repository.url ? null : "Give the repository a github.com origin remote.",
+  }))
+
+  checks.push(check("submission.headings", {
+    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",
+  }))
+
+  checks.push(check("submission.checklist", {
+    source: "marketplace-pin",
+    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",
+  }))
+
+  checks.push(check("submission.official-parser", {
+    source: "marketplace-pin",
+    why: "The strongest available proof that the body is well formed: the marketplace's own `parseCurrentSubmission` from the pinned commit is run over the rendered title and body. If it accepts them here it accepts them there, and 0 of the marketplace's heading, tag and checklist rules are duplicated in Omakit, so none of them can drift. This is the check that closes all 50 measured title-and-body failures at once: 39 on the title prefix plus 11 malformed bodies.",
+    verdict: Boolean(parsed?.ok),
+    detail: parsed
+      ? parsed.ok
+        ? `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",
+  }))
+
+  // --- the commit the marketplace will actually validate ---------------------
+
+  let head = null
+  let headError = null
+  if (!options.offline && subject.repository.url) {
+    phase("reading the repository's default-branch HEAD")
+    try {
+      head = await defaultBranchHead(subject.repository.url)
+    } catch (error) {
+      headError = { code: error.code || "head-unreadable", message: error.message }
+    }
+  }
+  const validationMatches = head ? head.commit === subject.commit.toLowerCase() : null
+  checks.push(check("submission.validation-commit", {
+    source: "omakit",
+    why: "The marketplace validates the default-branch HEAD it resolves when the issue is opened or edited, not the commit checked here. 73% of the 464 submissions parked in the author's court have a HEAD ahead of their validated commit, so a preflight against a commit that is not the pushed HEAD describes a tree nobody will review. Not a marketplace rule; an Omakit refusal to report on the wrong tree.",
+    severity: options.offline ? "advisory" : "blocking",
+    verdict: options.offline ? true : validationMatches === true,
+    detail: options.offline
+      ? `not checked (--offline). Local commit ${subject.commit}.`
+      : head
+        ? validationMatches
+          ? `local commit ${subject.commit} is the current ${head.branch || "default"}-branch HEAD`
+          : `local commit ${subject.commit} is not the current ${head.branch || "default"}-branch HEAD (${head.commit})`
+        : `could not read the default-branch HEAD (${headError?.code || "unknown"}): ${headError?.message || ""}`,
+    remedy: validationMatches === false
+      ? "Push this commit to the default branch before submitting, then run submit again."
+      : headError
+        ? "Connect to the network and run submit again, or pass --offline to skip this one check."
+        : null,
+  }))
+
+  // --- the baseline preflight ----------------------------------------------
+
+  phase("running the official security baseline over a local snapshot")
+  const preflight = await baselinePreflight({ repoRoot, subject })
+  phase("assembling the submission")
+  const consequence = preflight.consequence
+  const baselineBlocking = Boolean(consequence?.blocksApproval) || Boolean(preflight.refusal)
+  checks.push(check("baseline.preflight", {
+    source: "marketplace-pin",
+    why: `The official baseline decides whether a human has to look at all: of the ${figure(figures.withBaseline)} listed sources with a recorded baseline at the pin, it produced ${figure(figures.outcomes.passed || 0)} \`passed\`, ${figure(figures.outcomes["review-required"] || 0)} \`review-required\` and ${figure(figures.outcomes["needs-fixes"] || 0)} \`needs-fixes\`. It is the pinned marketplace code itself, run over a local snapshot; Omakit adds no rule and renames no outcome.`,
+    severity: baselineBlocking ? "blocking" : "advisory",
+    // `passed` and `review-required` are both acceptable submission states:
+    // review-required means a maintainer must look, not that anything is wrong.
+    // `needs-fixes` is reported as a failure either way; it is only blocking
+    // when one of the two selectively blocking rules fired.
+    verdict: consequence?.outcome === "passed" || consequence?.outcome === "review-required",
+    detail: preflight.refusal
+      ? `the official code refused the snapshot: ${preflight.refusal.code}, ${preflight.refusal.message}`
+      : preflight.invoked
+        ? `${consequence.outcome} (disposition ${consequence.disposition}, enforcement ${consequence.enforcementMode}, blocksApproval ${consequence.blocksApproval}). ${consequence.meaning}`
+        : `not run: ${preflight.skipReason}`,
+    paths: (preflight.official?.findings || []).flatMap((finding) =>
+      (finding.evidence || []).map((entry) => `${finding.ruleId}: ${entry.path}:${entry.line}`),
+    ),
+    remedy: consequence?.blocksApproval
+      ? "Fix every selectively blocking finding in a new commit before submitting."
+      : consequence?.outcome === "needs-fixes"
+        ? "These findings do not block publication under the current enforcement mode, but a maintainer must accept them for this exact commit. Fixing them first avoids that round."
+        : null,
+  }))
+
+  const blocking = checks.filter((entry) => entry.severity === "blocking" && entry.verdict === "fail")
+  const advisory = checks.filter((entry) => entry.severity === "advisory" && entry.verdict === "fail")
+  const ready = blocking.length === 0
+
+  return {
+    pin: {
+      repository: preflight.pin?.repository || null,
+      commit: pinIdentity.commit,
+      baselineVersion: pinIdentity.baselineVersion,
+      enforcementMode: pinIdentity.enforcementMode,
+    },
+    subject: {
+      mode: subject.mode,
+      directory: subject.dir,
+      repository: subject.repository.url,
+      commit: subject.commit,
+      cleanTree: subject.clean,
+    },
+    validationCommit: {
+      local: subject.commit,
+      defaultBranchHead: head?.commit || null,
+      branch: head?.branch || null,
+      matches: validationMatches,
+      note: "The marketplace validates the default-branch HEAD it resolves when the issue is opened or edited. After submitting, use `omakit watch <issue-url>` to see whether that validated commit has fallen behind.",
+    },
+    plugin: { id: tree.pluginId, name: pluginName },
+    checks,
+    ready,
+    blocking: blocking.map((entry) => entry.id),
+    advisory: advisory.map((entry) => entry.id),
+    issue: ready ? issue : null,
+    baseline: preflight.invoked
+      ? {
+        transport: preflight.transport,
+        assumedByAdapter: preflight.assumedByAdapter,
+        official: preflight.official,
+        consequence,
+        officialReport: preflight.officialReport,
+        statement: preflight.statement,
+      }
+      : { invoked: false, skipReason: preflight.skipReason, statement: preflight.statement },
+    afterSubmitting: REFRESH_ACTION,
+  }
+}

package/tools/marketplace/tree.mjs

@@ -0,0 +1,50 @@
+// The installable tree of a plugin repository at one exact commit, read from
+// the local Git object database. Read-only: `git ls-tree` and `git cat-file`,
+// never a working-tree walk, so what is inspected is exactly what the
+// marketplace would fetch for that commit and nothing the author left
+// untracked.
+
+import { execFileSync } from "node:child_process"
+
+function git(dir, args, encoding = "utf8") {
+  return execFileSync("git", ["-C", dir, ...args], {
+    encoding,
+    maxBuffer: 256 * 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+}
+
+/**
+ * @param {string} dir
+ * @param {string} commit
+ * @returns {Array<{ path: string, mode: string, type: string, sha: string, size?: number }>}
+ */
+export function readTree(dir, commit) {
+  const raw = git(dir, ["ls-tree", "-r", "-t", "-l", commit])
+  const entries = []
+  for (const line of raw.split("\n")) {
+    if (!line) continue
+    const tab = line.indexOf("\t")
+    const [mode, type, sha, size] = line.slice(0, tab).split(/\s+/)
+    const entry = { path: line.slice(tab + 1), mode, type, sha }
+    if (type === "blob") entry.size = Number(size)
+    entries.push(entry)
+  }
+  return entries
+}
+
+export function readBlob(dir, sha) {
+  return git(dir, ["cat-file", "blob", sha], "buffer")
+}
+
+export function readText(dir, sha, limit = 1024 * 1024) {
+  return readBlob(dir, sha).subarray(0, limit).toString("utf8")
+}
+
+export function isBlob(entry) {
+  return entry?.type === "blob" && entry.mode !== "120000"
+}
+
+export function rootEntries(entries) {
+  return entries.filter((entry) => !entry.path.includes("/"))
+}

package/tools/marketplace/upgrade.mjs

@@ -0,0 +1,179 @@
+// `omakit upgrade`: update the tool, and only the tool.
+//
+// This command exists against my earlier judgement, and the reason is worth
+// writing down. The objection to an upgrade command was that "upgrade" can mean
+// two things here and one of them must never happen on its own: bumping the
+// marketplace pin changes where the submission contract and the baseline policy
+// are read from, and the procedure for that ends in re-proving transport parity
+// and committing the evidence. That objection stands, and it is enforced below
+// rather than argued: this command fast-forwards the tool's own checkout and
+// touches nothing in .cache. The pin moves when a human edits MARKETPLACE_PIN,
+// never here.
+//
+// What changed my mind is the ordinary case. After a global install nobody
+// remembers where the checkout went, and a tool people cannot update is a tool
+// people run stale. That is a worse outcome than the one I was protecting
+// against.
+//
+// It is not a self-updater in the sense this repository warns other people
+// about. It does not fetch and execute arbitrary code: it fast-forwards a Git
+// checkout the user cloned themselves, from the remote they cloned it from, and
+// it refuses if any of that is not true.
+
+import { execFileSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { join, resolve, sep } from "node:path"
+import { progress } from "./progress.mjs"
+import { action, colourEnabled, GUTTER, mark, styler, verdict, wrap } from "./style.mjs"
+
+export const REPOSITORY = "https://github.com/mtolhuys/omakit"
+
+/** Identify only the three supported delivery shapes; npm wins under /usr/node_modules. */
+export function installKind(repoRoot) {
+  const root = resolve(repoRoot)
+  if (existsSync(join(root, ".git"))) return "git"
+  if (root.split(sep).includes("node_modules")) return "npm"
+  if (root === "/usr/lib/omakit" || root.startsWith("/usr/lib/omakit/")) return "distro"
+  return "npm"
+}
+
+export function upgradeCommand(repoRoot, name = "omakit") {
+  return {
+    git: "omakit upgrade",
+    npm: `npm i -g ${name}@latest`,
+    distro: `sudo pacman -Syu ${name}`,
+  }[installKind(repoRoot)]
+}
+
+function git(dir, args) {
+  return execFileSync("git", ["-C", dir, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim()
+}
+
+/** Same repository, whatever spelling the remote uses. */
+export function isExpectedRemote(url, expected = REPOSITORY) {
+  const normalise = (value) => String(value || "")
+    .trim()
+    .replace(/^git@github\.com:/i, "https://github.com/")
+    .replace(/\.git$/i, "")
+    .replace(/\/+$/, "")
+    .toLowerCase()
+  return normalise(url) === normalise(expected)
+}
+
+/**
+ * @param {{ repoRoot: string, stream?: NodeJS.WriteStream, dryRun?: boolean,
+ *           expectedRemote?: string }} options `expectedRemote` exists so the
+ *   successful path can be tested end to end against a local remote; it is not
+ *   a way to point the command at somebody else's repository, because nothing
+ *   on the command line reaches it.
+ */
+export async function upgrade({ repoRoot, stream = process.stdout, dryRun = false, expectedRemote = REPOSITORY }) {
+  const c = styler(colourEnabled(stream))
+  const out = (line = "") => stream.write(`${line}\n`)
+  const lines = (list) => { for (const line of list) out(line) }
+  const refuse = (reason, fix = null) => {
+    lines(verdict("fail", "REFUSED", reason, c))
+    if (fix) lines(action(fix, c, { indent: 0 }))
+    return { ok: false, reason }
+  }
+  const note = (text) => out(`${mark("advisory", c)}${wrap(text, { indent: GUTTER }, c).join("\n").trimStart()}`)
+  const ok = (text) => out(`${mark("pass", c)}${wrap(text, { indent: GUTTER }, c).join("\n").trimStart()}`)
+
+  if (!existsSync(join(repoRoot, ".git"))) {
+    const kind = installKind(repoRoot)
+    return refuse(
+      kind === "distro"
+        ? "this is a distro package under /usr, so omakit leaves upgrades to pacman."
+        : "this is an npm package install, so omakit leaves upgrades to npm.",
+      upgradeCommand(repoRoot),
+    )
+  }
+
+  let remote
+  try {
+    remote = git(repoRoot, ["remote", "get-url", "origin"])
+  } catch {
+    return refuse("this checkout has no `origin` remote, so there is nowhere to update from.")
+  }
+  if (!isExpectedRemote(remote, expectedRemote)) {
+    return refuse(
+      `the \`origin\` of this checkout is ${remote}, not ${expectedRemote}. Pulling code from somewhere else is not this command's business.`,
+      `git -C ${repoRoot} pull`,
+    )
+  }
+
+  if (git(repoRoot, ["status", "--porcelain"]).length) {
+    return refuse(
+      "this checkout has local changes. Updating would either lose them or leave you mid-merge; both are worse than stopping.",
+      `git -C ${repoRoot} status`,
+    )
+  }
+
+  const before = git(repoRoot, ["rev-parse", "HEAD"])
+  const branch = git(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"])
+  if (branch === "HEAD") {
+    return refuse("this checkout is on a detached HEAD, so there is no branch to fast-forward.")
+  }
+
+  const spinner = progress({ stream: stream === process.stdout ? process.stderr : stream })
+  spinner.phase(`fetching origin/${branch}`)
+  try {
+    git(repoRoot, ["fetch", "--quiet", "origin", branch])
+  } catch (error) {
+    spinner.done()
+    const reason = String(error?.stderr || "").trim().split("\n").filter((line) => /^fatal:/.test(line)).pop()
+      || "git fetch failed"
+    return refuse(
+      `origin could not be fetched: ${reason.replace(/^fatal:\s*/, "")}`,
+      "Connect to the network, then run `omakit upgrade` again.",
+    )
+  }
+  spinner.done()
+  const target = git(repoRoot, ["rev-parse", `origin/${branch}`])
+
+  if (target === before) {
+    ok(`already current at ${before.slice(0, 7)} on ${branch}`)
+    out()
+    lines(wrap("The marketplace pin is a separate thing and is never touched here. `omakit doctor` says whether it is behind.", {}, c))
+    return { ok: true, changed: false, commit: before }
+  }
+
+  // Fast-forward only. A merge or a rebase here would be this command deciding
+  // what to do with someone else's history.
+  try {
+    git(repoRoot, ["merge-base", "--is-ancestor", before, target])
+  } catch {
+    return refuse(
+      `this checkout at ${before.slice(0, 7)} is not an ancestor of origin/${branch} at ${target.slice(0, 7)}, so it cannot be fast-forwarded.`,
+      `git -C ${repoRoot} log --oneline HEAD..origin/${branch}`,
+    )
+  }
+
+  const log = git(repoRoot, ["log", "--oneline", `${before}..${target}`]).split("\n").filter(Boolean)
+  // A commit subject is the one thing a person actually reads here, so the sha
+  // takes the emphasis and the subject keeps the terminal's own foreground.
+  const body = " ".repeat(GUTTER)
+  const subject = (line) => {
+    const split = line.match(/^(\S+)\s+([\s\S]*)$/)
+    return split ? `${body}${c("name", split[1])} ${c("prose", split[2])}` : `${body}${c("prose", line)}`
+  }
+  if (dryRun) {
+    note(`${log.length} commit(s) available, not applied (--dry-run)`)
+    for (const line of log) out(subject(line))
+    out()
+    lines(action("omakit upgrade", c, { indent: 0 }))
+    return { ok: true, changed: false, commit: before, available: log.length }
+  }
+
+  git(repoRoot, ["merge", "--ff-only", `origin/${branch}`])
+  const after = git(repoRoot, ["rev-parse", "HEAD"])
+
+  ok(`${before.slice(0, 7)} to ${after.slice(0, 7)} on ${branch}, ${log.length} commit(s)`)
+  for (const line of log) out(subject(line))
+  out()
+  lines(wrap("The marketplace pin did not move: this updated the tool, not the commit its rules are read from. `omakit doctor` says whether that pin is behind, and docs/UPSTREAM_CONTRACT.md says what moving it involves.", {}, c))
+  return { ok: true, changed: true, from: before, to: after, commits: log.length }
+}