omakit 0.1.0

package/tests/parity/run.mjs

@@ -0,0 +1,194 @@
+// Parity: the pinned official baseline over the GitHub transport must equal the
+// same code over Omakit's local Git transport, for real listed plugin
+// repositories at their exact commits. Read-only: clones and GET requests only.
+//
+// The committed evidence records, per repository, a digest of each transport's
+// comparable result rather than the results themselves. Two reasons. Equal
+// digests are the whole parity claim, and anyone can recompute them from the
+// repository, the commit and the pin. And findings about a specific third-party
+// plugin are not this project's to publish: the aggregate rule distribution in
+// the summary carries no repository names, and the per-repository rows carry no
+// findings, no capabilities, no file paths and no source snippets.
+
+import { createHash } from "node:crypto"
+import { execFileSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { runBaseline } from "../../tools/marketplace/run-baseline.mjs"
+import { requirePin } from "../../tools/marketplace/pin.mjs"
+import { parityCorpus, strataSizes } from "./corpus.mjs"
+import { subjectSlug } from "../../tools/subject/resolve.mjs"
+import { token } from "../../tools/marketplace/github.mjs"
+import { omakitCacheDir } from "../../tools/marketplace/paths.mjs"
+import { parityOutput } from "../../tools/marketplace/parity-output.mjs"
+
+const repoRoot = resolve(process.env.OMAKIT_ROOT || process.cwd())
+const pinDir = requirePin(repoRoot).dir
+const cacheDir = omakitCacheDir("parity")
+const output = parityOutput({ repoRoot, out: process.env.PARITY_OUT || null })
+const count = Number(process.env.PARITY_COUNT || 30)
+const offset = Number(process.env.PARITY_OFFSET || 0)
+
+function shallowClone(repoUrl, commit) {
+  const dir = join(cacheDir, subjectSlug(repoUrl))
+  mkdirSync(dir, { recursive: true })
+  const run = (args) => execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+  try {
+    run(["rev-parse", commit + "^{commit}"])
+    return dir
+  } catch {
+    /* not fetched yet */
+  }
+  // Test for the clone's own .git instead of relying on an outer repository.
+  if (!existsSync(join(dir, ".git"))) {
+    execFileSync("git", ["init", "-q", dir], { encoding: "utf8" })
+    run(["remote", "add", "origin", repoUrl])
+  }
+  run(["fetch", "-q", "--depth", "1", "origin", commit])
+  return dir
+}
+
+function comparable(result) {
+  return JSON.stringify({
+    outcome: result.outcome,
+    disposition: result.disposition,
+    blocksApproval: result.blocksApproval,
+    findings: result.findings,
+    capabilities: result.capabilities,
+  })
+}
+
+/** A digest of the comparable payload: proves equality without publishing it. */
+function digest(result) {
+  return createHash("sha256").update(comparable(result)).digest("hex").slice(0, 32)
+}
+
+function pinCommit(dir) {
+  try {
+    return execFileSync("git", ["-C", dir, "rev-parse", "HEAD"], { encoding: "utf8" }).trim()
+  } catch {
+    return "unknown"
+  }
+}
+
+const corpus = parityCorpus(pinDir, count, offset)
+const rows = []
+const ruleTotals = {}
+const capabilityTotals = {}
+let mismatches = 0
+let failures = 0
+
+for (const target of corpus) {
+  const row = {
+    repo: target.repo,
+    commit: target.commit,
+    type: target.type,
+    registryOutcome: target.registryOutcome,
+    registryOutcomeAtSameCommit: target.registryOutcomeCommit === target.commit,
+  }
+  try {
+    const dir = shallowClone(target.repo, target.commit)
+    const local = await runBaseline({
+      repoRoot,
+      repoUrl: target.repo,
+      commitSha: target.commit,
+      transport: "local",
+      repoDir: dir,
+    })
+    row.localOutcome = local.result.outcome
+    row.requests = local.adapter.requests
+    row.localDigest = digest(local.result)
+    // Rule and capability ids are counted in the summary, unattributed; they are
+    // deliberately not recorded against this repository.
+    for (const finding of local.result.findings || []) {
+      const id = finding.ruleId || finding.id
+      if (id) ruleTotals[id] = (ruleTotals[id] || 0) + 1
+    }
+    for (const capability of local.result.capabilities || []) {
+      if (capability.id) capabilityTotals[capability.id] = (capabilityTotals[capability.id] || 0) + 1
+    }
+    try {
+      const github = await runBaseline({
+        repoRoot,
+        repoUrl: target.repo,
+        commitSha: target.commit,
+        transport: "github",
+        token: token() ?? undefined,
+      })
+      row.githubOutcome = github.result.outcome
+      row.githubDigest = digest(github.result)
+      row.identical = row.localDigest === row.githubDigest
+      if (!row.identical) {
+        mismatches += 1
+        // A mismatch is the one case worth describing, and it is described as a
+        // difference between two transports of the same code, not as a finding
+        // about the plugin: which keys differ, never their contents.
+        const localPayload = JSON.parse(comparable(local.result))
+        const githubPayload = JSON.parse(comparable(github.result))
+        row.differingKeys = Object.keys(localPayload).filter(
+          (key) => JSON.stringify(localPayload[key]) !== JSON.stringify(githubPayload[key]),
+        )
+      }
+    } catch (error) {
+      row.githubError = (error.code || "error") + ": " + error.message
+      failures += 1
+    }
+  } catch (error) {
+    row.localError = (error.code || "error") + ": " + error.message
+    failures += 1
+  }
+  rows.push(row)
+  console.log(
+    [
+      row.identical === true ? "ok  " : row.identical === false ? "DIFF" : "??  ",
+      target.repo.replace("https://github.com/", "").padEnd(44),
+      "local=" + (row.localOutcome || row.localError || "-"),
+      "github=" + (row.githubOutcome || row.githubError || "-"),
+      "registry=" + (row.registryOutcome || "-"),
+    ].join(" "),
+  )
+}
+
+function generatorIdentity() {
+  try {
+    return { omakitCommit: execFileSync("git", ["-C", repoRoot, "rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() }
+  } catch {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
+    return { omakitPackage: `${pkg.name}@${pkg.version}` }
+  }
+}
+
+const summary = {
+  generator: generatorIdentity(),
+  pinnedMarketplaceCommit: pinCommit(pinDir),
+  corpusSize: corpus.length,
+  requestedCount: count,
+  offset,
+  strata: strataSizes(count),
+  outcomes: rows.reduce((acc, row) => {
+    const key = row.localOutcome || "error"
+    acc[key] = (acc[key] || 0) + 1
+    return acc
+  }, {}),
+  identical: rows.filter((row) => row.identical === true).length,
+  mismatches,
+  failures,
+  // Unattributed aggregates. No repository name is attached to any rule.
+  ruleTotals,
+  capabilityTotals,
+  publication: {
+    perRepositoryDetail: "omitted",
+    reason: "Findings about a specific third-party plugin are not published. Equality is evidenced by the sha256 digests below, which anyone can recompute from the repository, the commit and the pinned marketplace commit.",
+    digest: "sha256 of {outcome, disposition, blocksApproval, findings, capabilities}, first 32 hex characters",
+  },
+  rows,
+}
+const date = new Date().toISOString().slice(0, 10)
+const outputIsFile = process.env.PARITY_OUT_EXPLICIT === "1"
+const outputDir = outputIsFile ? resolve(output, "..") : output
+mkdirSync(outputDir, { recursive: true })
+let outFile = outputIsFile ? output : join(outputDir, `${date}-local-vs-github.json`)
+for (let n = 2; !outputIsFile && existsSync(outFile); n += 1) outFile = join(outputDir, `${date}-local-vs-github-${n}.json`)
+writeFileSync(outFile, JSON.stringify(summary, null, 2) + "\n")
+console.log("\nidentical " + summary.identical + "/" + corpus.length + ", mismatches " + mismatches + ", failures " + failures + " -> " + outFile)
+process.exit(mismatches === 0 && failures === 0 ? 0 : 1)

package/tools/marketplace/README.md

@@ -0,0 +1,64 @@
+# Module map
+
+Omakit never copies marketplace policy. It imports the official analysis from a
+read-only checkout of the pinned marketplace commit and feeds it a snapshot of a
+local commit through the transport seam the marketplace tests itself
+(`resolveSecuritySnapshot(..., { fetchImpl })`).
+
+| File | Purpose |
+| --- | --- |
+| `pin.mjs` | The pin identity (one home) and the reproducible setup: `omakit pin` fetches exactly that commit into `$XDG_CACHE_HOME/omakit/marketplace` and refuses a modified checkout. |
+| `local-transport.mjs` | Answers the four request shapes the official resolver makes, from a local clone at the exact commit. No network, no credentials, no writes. |
+| `run-baseline.mjs` | Runs the pinned official baseline over either transport and reports the pin identity beside the result. |
+| `verify.mjs` | Builds the `marketplaceBaseline` section: pin, transport, assumptions, the official result verbatim, the statement. |
+| `preflight.mjs` | Translates that result into what it will cause on submission, using the pinned policy, and renders the marketplace's own report text with its attestation marker stripped and asserted absent. |
+| `yaml.mjs` | A deliberately small YAML reader for the pinned issue form. Accepts that subset and throws on anything else. |
+| `form.mjs` | The submission contract, read from the form and cross-checked against the marketplace's own constants. |
+| `registry.mjs` | The plugin-id and repository universe, and the reserved namespace, read from the pinned registry, catalog and catalog builder. |
+| `tree.mjs` | The installable tree of a subject at one exact commit, from the Git object database. |
+| `plugin.mjs` | The root files the submission contract needs, and the declared plugin identity. |
+| `agent-control.mjs` | The recursive agent-control warning, and its remedy. |
+| `issue.mjs` | Renders the issue the way the form would, then has the marketplace's own parser judge it. |
+| `submit.mjs` | Assembles every check with its measured reason, and withholds the body when a blocking check fails. |
+| `watch.mjs` | The validation watch: validated commit versus current default-branch HEAD, and the one action that refreshes it. |
+| `github.mjs` | Read-only GitHub access. GET only. The credential is your `gh` login, read through one frozen `gh auth token` call, and is never written anywhere. |
+| `style.mjs` | The visual system, defined once: the palette, the status vocabulary, the block ramp, the columns, the motion budgets, and the composition helpers every command draws with. `docs/TUI.md` explains it. |
+| `report.mjs` | Text rendering of submit, watch and doctor for the agent that runs this tool, and the person reading over its shoulder. |
+| `usage.mjs` | The help text, as data. |
+| `completion.mjs` | A completion script for bash, zsh or fish, derived from the help data and the pin's form: the subcommands and flags are read out of `COMMANDS`, the categories and tags out of the pinned submission form, and the script says which pin it came from. `setup` installs it for the shell in `$SHELL`, the one file this tool writes outside its own checkout. |
+| `banner.mjs` | The wordmark, on a bare `omakit` and in `setup` only. |
+| `effect.mjs` | The one text effect: the wordmark through `ttfx` where it is drawn, with frozen arguments, a hard budget, no colour of its own, and nothing at all when `ttfx` is not there. |
+| `progress.mjs` | The progress line, on stderr, only when a person is looking. |
+| `cli.mjs` | The one entry point behind `bin/omakit`, and the one register every failure is reported in. |
+
+```text
+omakit pin
+omakit submit /path/to/plugin-repo --category Widgets --tags bar,quickshell
+omakit submit https://github.com/owner/repo@<40-char sha> --category System --tags system
+omakit watch https://github.com/omacom/omarchy-plugin-marketplace/issues/4829
+omakit verify /path/to/plugin-repo
+omakit parity --count 30
+```
+
+A local repository needs an `origin` on github.com for the official code to name
+the repository; without one the baseline section records `transport: "none"` and
+the reason. Reviewer targets are fetched read-only into
+`.cache/subjects/<owner>__<repo>/` and never executed.
+
+Metadata that cannot be known from a local clone (repository visibility, archived
+and disabled state, tree truncation) is answered with the minimal valid value and
+listed in `assumedByAdapter`. The marketplace rescans the public commit itself; a
+local run is a preview, never an authority.
+
+Parity is proven, not assumed: `omakit parity` compares both transports over real
+listed repositories at their listing-validated commits, stratified on the outcome
+the registry recorded so the corpus always contains repositories that are not
+`passed`. Results land in `docs/evidence/parity/`, recording a digest of each
+side rather than the findings themselves. The GitHub side uses whatever
+credential `github.mjs` resolves (a `gh` login, and only that), read-only.
+
+`parity` and `watch` are the only commands that reach the network, and they do it
+with Node's built-in `fetch`, which does not read proxy environment variables by
+default. Behind a proxy, run them with `NODE_USE_ENV_PROXY=1`. `submit` and
+`verify` need no network at all beyond fetching a reviewer-mode subject, and
+`tests/parity/offline.mjs` proves it.

package/tools/marketplace/agent-control.mjs

@@ -0,0 +1,72 @@
+// The agent-control check.
+//
+// Measured reason (docs/MEASUREMENTS.md M3): 103 marketplace issues mention
+// agent-control files. The maintainer treats an instruction file inside an
+// installed plugin as a prompt-injection surface and blocks listing on it; in a
+// 328-comment sample of his review writing, 24 comments are about exactly this.
+// It is not detected by the marketplace's automated baseline, so an author
+// learns about it only from a human review round, which is the most expensive
+// round there is.
+//
+// This is an Omakit check, derived from public issue text, not a marketplace
+// rule. The verdict field says so, and the wording never reuses the
+// marketplace's outcome vocabulary.
+
+import { isBlob } from "./tree.mjs"
+
+// Names an agent reads as instructions when the plugin is installed.
+export const AGENT_CONTROL_FILES = Object.freeze(["AGENTS.md", "CLAUDE.md", "SKILL.md", ".mcp.json"])
+export const AGENT_CONTROL_DIRECTORIES = Object.freeze([".claude", ".codex"])
+export const INSTRUCTION_DIRECTORY = "skills"
+export const INSTRUCTION_EXTENSIONS = Object.freeze([".md", ".markdown", ".mdc"])
+
+export const REMEDY = Object.freeze([
+  "Move the guidance to a non-agent filename such as DEVELOPMENT.md.",
+  "Untrack the originals (git rm --cached) so they leave the installable tree, and add them to .gitignore.",
+  "Keep a recursive release check so they cannot return.",
+])
+
+function basename(path) {
+  const slash = path.lastIndexOf("/")
+  return slash === -1 ? path : path.slice(slash + 1)
+}
+
+function segments(path) {
+  return path.split("/")
+}
+
+/**
+ * Find every agent-control file anywhere in the tree.
+ *
+ * Matching is case-insensitive on the basename: agents read `agents.md` as
+ * readily as `AGENTS.md`, so a lowercase copy is the same injection surface.
+ *
+ * @param {Array<{ path: string, mode: string, type: string }>} entries
+ * @returns {Array<{ path: string, reason: string }>}
+ */
+export function findAgentControl(entries) {
+  const files = new Set(AGENT_CONTROL_FILES.map((name) => name.toLowerCase()))
+  const directories = new Set(AGENT_CONTROL_DIRECTORIES.map((name) => name.toLowerCase()))
+  const hits = []
+  for (const entry of entries) {
+    if (!isBlob(entry)) continue
+    const parts = segments(entry.path)
+    const name = basename(entry.path).toLowerCase()
+    const directory = parts.slice(0, -1).find((part) => directories.has(part.toLowerCase()))
+    if (directory) {
+      hits.push({ path: entry.path, reason: `inside an agent-control directory (${directory}/)` })
+      continue
+    }
+    if (files.has(name)) {
+      hits.push({ path: entry.path, reason: `agent-control file (${basename(entry.path)})` })
+      continue
+    }
+    const inSkills = parts.slice(0, -1).some((part) => part.toLowerCase() === INSTRUCTION_DIRECTORY)
+    if (inSkills && INSTRUCTION_EXTENSIONS.some((extension) => name.endsWith(extension))) {
+      hits.push({ path: entry.path, reason: `instruction file inside a ${INSTRUCTION_DIRECTORY}/ directory` })
+    }
+  }
+  // Codepoint order, not locale order: the output is read and compared by
+  // agents and tests, so it must not depend on the machine's locale data.
+  return hits.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}

package/tools/marketplace/banner.mjs

@@ -0,0 +1,307 @@
+// The wordmark, and the one place decoration is allowed.
+//
+// It is drawn in two places: a bare `omakit`, the front door, where the short
+// list under it fits on any screen; and `omakit setup`, a first run already
+// spending seconds fetching the pin. Not on `omakit help`, whose 53 lines
+// scroll it off the top before anyone has read it, and not on `doctor`, which
+// is run to read a report. Never in `submit`, `watch` or `verify` output,
+// because that output gets pasted into issues and read by agents, and a
+// banner there costs a reader lines and costs a submission credibility.
+//
+// One more gate. It draws only when stdout is a terminal, so `omakit | less`
+// and `omakit setup | tee` stay plain text; there is no switch of omakit's own, because a pipe
+// and TERM=dumb are the terminal's way of saying the same thing. NO_COLOR does
+// what it says and no more: the wordmark is still drawn, in the terminal's own
+// foreground, because a person who turned colour off did not ask for a
+// different program. The same words arrive either way; a piped run gets them
+// without the wordmark.
+//
+// The animation is on a budget: the whole scan is MOTION.bannerBudgetMs, about
+// a quarter of a second, so the first line under it is on the screen before a
+// person has finished looking at the wordmark. The first version of this took
+// 1.4 seconds. The schedule below is derived from the budget rather than from
+// taste, so the wordmark can grow a letter without the scan growing a delay.
+//
+// How `oma` and `kit` are told apart, and why it is not by colour.
+//
+// The measured problem: on Omarchy's Matte Black theme every ANSI hue resolves
+// to nearly the same grey, so a wordmark whose two halves differ in tint
+// renders as one flat word, and bold does not rescue it, because a block glyph
+// has no stroke for a bold face to thicken and most terminals no longer
+// brighten bold text. What a monochrome terminal does still draw is ink. So
+// the two halves differ in density: `oma`, the ecosystem's prefix, is drawn in
+// the dark shade (▓), and `kit`, this tool's own name, in the full block (█).
+// The prefix recedes into texture and the name stands solid, on any theme, and
+// under NO_COLOR, where there is no escape sequence at all. The tint is still
+// applied on top when colour is on, cyan on the prefix and the foreground on
+// the name, so a colour theme gets both cues and a monochrome one gets the one
+// it can show.
+//
+// The trade-off is the shade glyph itself: ▓ is a pattern, and a pattern only
+// reads as a letter when adjacent cells tile without a seam. Every monospace
+// font ships it as a tiling glyph, and docs/media/render.py measures the
+// rendered wordmark and refuses to produce a GIF in which the shaded rows do
+// not join.
+//
+// The animation is the tool's own motif rather than an ornament: the same
+// scanner that sweeps the progress line during a baseline run sweeps across the
+// name. Nothing here imitates anyone else's logo, character or product; the
+// letters come from the small font below, so renaming the tool is a change to
+// one string and not a redrawing job.
+
+import { code, colourEnabled, DENSITY, motionEnabled, MOTION, rule as floorRule } from "./style.mjs"
+import { effectAvailable, playEffect } from "./effect.mjs"
+
+const ESC = "\u001b["
+const RESET = `${ESC}0m`
+// The tints, applied only when colour is on. The head of the scanner is the
+// one bright thing, the typeable role's tint in bold, the same tint the progress
+// line's head moves; the prefix takes that tint too; the name keeps the
+// terminal's foreground.
+const TINT = Object.freeze({
+  head: `${ESC}${code("typeable.bold")}m`,
+  prefix: `${ESC}${code("typeable")}m`,
+  suffix: `${ESC}${code("prose")}m`,
+})
+
+// A five-row pixel font, "#" lit and " " blank, one blank column between
+// letters. Only the letters the name needs are defined; adding one is adding one
+// entry of five equal-length strings.
+export const GLYPHS = Object.freeze({
+  a: [" ## ", "#  #", "####", "#  #", "#  #"],
+  c: [" ###", "#   ", "#   ", "#   ", " ###"],
+  // Three wide with bars, not a single stroke: a one-column i is ambiguous next
+  // to a k, and the wordmark reads as capitals anyway.
+  i: ["###", " # ", " # ", " # ", "###"],
+  k: ["#  #", "# # ", "##  ", "# # ", "#  #"],
+  m: ["#   #", "## ##", "# # #", "#   #", "#   #"],
+  n: ["#  #", "## #", "# ##", "#  #", "#  #"],
+  o: [" ## ", "#  #", "#  #", "#  #", " ## "],
+  s: [" ###", "#   ", " ## ", "   #", "### "],
+  t: ["###", " # ", " # ", " # ", " # "],
+})
+
+export const GLYPH_ROWS = 5
+
+/** How many leading letters are the prefix: drawn in the shade, and tinted cyan when colour is on. */
+export const PREFIX_LETTERS = 3
+
+/** The two densities: the prefix is texture, the name is solid. */
+export const INK = Object.freeze({ prefix: DENSITY.dark, suffix: DENSITY.full, head: DENSITY.full })
+
+/**
+ * Lay a word out as five rows plus the column span of each letter.
+ * Throws on a letter the font does not have, rather than dropping it silently.
+ */
+export function wordmarkLayout(word) {
+  const letters = [...String(word).toLowerCase()]
+  const missing = letters.filter((letter) => !GLYPHS[letter])
+  if (missing.length) {
+    throw new Error(`banner: no glyph for ${[...new Set(missing)].join(", ")}; add it to GLYPHS`)
+  }
+  const rows = []
+  for (let row = 0; row < GLYPH_ROWS; row += 1) {
+    rows.push(letters.map((letter) => GLYPHS[letter][row]).join(" "))
+  }
+  const spans = []
+  let column = 0
+  for (const [index, letter] of letters.entries()) {
+    const width = GLYPHS[letter][0].length
+    spans.push({ letter, index, from: column, to: column + width - 1 })
+    column += width + 1
+  }
+  return { rows, spans, width: rows[0].length }
+}
+
+/** Kept for the simple case: just the five rows. */
+export function wordmarkRows(word) {
+  return wordmarkLayout(word).rows
+}
+
+/**
+ * The whole animation, in milliseconds, stated once in style.mjs beside every
+ * other budget. Not a taste parameter: `help` exists to put text on the
+ * screen, so the scan has to be over before it is in the way. A quarter of a
+ * second is about one glance.
+ */
+export const BUDGET_MS = MOTION.bannerBudgetMs
+
+// How many columns the head jumps per frame. Two for the reveal keeps the sweep
+// continuous, because the head is two columns wide; three for the return pass
+// is a highlight travelling over letters that are already drawn, where a gap
+// costs nothing.
+const REVEAL_STRIDE = 2
+const SHINE_STRIDE = 3
+
+/**
+ * Frames are spaced to fit the budget, not the other way round, so a longer
+ * name means a quicker step rather than a longer wait.
+ *
+ * @param {number} width
+ * @param {number} [budget]
+ */
+export function schedule(width, budget = BUDGET_MS) {
+  const stride = REVEAL_STRIDE
+  const shineStride = SHINE_STRIDE
+  const frames = Math.floor(width / stride) + 1 + Math.ceil(width / shineStride) + 1
+  const delay = Math.max(4, Math.floor(budget / frames))
+  return { stride, shineStride, delay, frames, total: frames * delay }
+}
+
+export function bannerEnabled(stream = process.stdout, env = process.env) {
+  return motionEnabled(stream, env)
+}
+
+function isPrefix(spans, column) {
+  const span = spans.find((entry) => column >= entry.from && column <= entry.to)
+  return Boolean(span) && span.index < PREFIX_LETTERS
+}
+
+/**
+ * One frame of the scan.
+ *
+ * `band` is where the bright head sits. `revealed` is how far the wordmark has
+ * been drawn at all; columns beyond it are blank. The reveal pass moves both
+ * together; the shine pass afterwards moves the band across a wordmark that is
+ * already complete.
+ *
+ * With `colour` off no escape is written at all: the head is a full block over
+ * the shaded prefix, which is still visible as a change in density, and over
+ * the solid name it is simply the name.
+ */
+export function frame(layout, band, revealed = band, { colour = true } = {}) {
+  const { rows, spans, width } = layout
+  return rows.map((row) => {
+    let out = ""
+    let tint = ""
+    for (let column = 0; column < width; column += 1) {
+      // Unrevealed columns, and blanks inside revealed ones, are plain spaces.
+      // A colour code is only ever emitted for a block that is actually drawn,
+      // so a frame carries no escape it does not use.
+      const lit = column <= revealed && row[column] === "#"
+      if (!lit) {
+        if (tint) { out += RESET; tint = "" }
+        out += " "
+        continue
+      }
+      const atHead = column >= band - 1 && column <= band
+      const prefix = isPrefix(spans, column)
+      const wanted = colour ? (atHead ? TINT.head : prefix ? TINT.prefix : TINT.suffix) : ""
+      if (tint !== wanted) { out += wanted; tint = wanted }
+      out += atHead ? INK.head : prefix ? INK.prefix : INK.suffix
+    }
+    return tint ? out + RESET : out
+  })
+}
+
+/**
+ * @param {{ word?: string, tagline?: string, stream?: NodeJS.WriteStream,
+ *           enabled?: boolean, animate?: boolean, shines?: number,
+ *           effect?: boolean, env?: NodeJS.ProcessEnv }} [options]
+ *   `effect: true` runs the wordmark through `ttfx` when it is there (see
+ *   effect.mjs); both callers, the front door and `setup`, pass it.
+ */
+export async function banner(options = {}) {
+  const stream = options.stream || process.stdout
+  const enabled = options.enabled ?? bannerEnabled(stream)
+  const colour = options.colour ?? colourEnabled(stream)
+  const word = options.word || "omakit"
+  const layout = wordmarkLayout(word)
+  const { width } = layout
+  // The rule and the tagline sit under the wordmark and are still meant to be
+  // read, so neither is dim: on a low-contrast theme grey-on-near-black is a
+  // decoration nobody can see. The rule takes the prefix tint, the tagline the
+  // foreground.
+  const c = (name, text) => (colour ? `${ESC}${name}m${text}${RESET}` : text)
+  const rule = floorRule((_name, text) => c(code("typeable"), text), { width })
+  // The tagline is centred under the wordmark, not set flush left: the rule
+  // is exactly as wide as the letters, so a shorter line starting at column
+  // 0 reads as slid to the left. The padding is spaces, no escape, so the
+  // line is centred under NO_COLOR and in a pipe alike.
+  const tagline = options.tagline
+    ? " ".repeat(Math.max(0, Math.floor((width - [...String(options.tagline)].length) / 2))) + c(code("prose"), options.tagline)
+    : null
+
+  // Nothing at all when it is not a terminal. There is no plain-text substitute
+  // to print: `help` and `setup` already say the name and what it does in words,
+  // and a piped run should differ from a watched one only in decoration.
+  if (!enabled) return
+
+  // A five-row animation redrawn with cursor-up needs five rows that stay put.
+  // In a terminal with no room the screen scrolls under the animation, the
+  // cursor-up lands a line off, and a row from an earlier frame is left stranded
+  // above the wordmark. Rather than animate into that, draw it at once.
+  const rowsAvailable = Number.isFinite(stream.rows) ? stream.rows : Infinity
+  const animate = options.animate !== false && rowsAvailable >= GLYPH_ROWS + 4
+
+  const { stride, shineStride, delay } = schedule(width, options.budgetMs)
+  const paint = (lines) => lines.map((line) => `${ESC}2K${line}`).join("\n")
+  // A frame is written without a trailing newline, and the cursor walks back up
+  // four rows and to column 0. That is not a detail: a newline written while the
+  // cursor is on the last row of the screen scrolls the screen, so a frame that
+  // ends in one scrolls once per frame when the prompt happens to sit at the
+  // bottom, which it usually does. Twenty-six of those leave the partial frames
+  // in the scrollback and a stray row of one of them directly above the
+  // wordmark. Ending inside the block instead means the screen scrolls exactly
+  // once, for the very first frame, before any cursor-up is issued.
+  const redraw = (lines) => stream.write(`${paint(lines)}${ESC}${GLYPH_ROWS - 1}A\r`)
+  const finish = (lines) => stream.write(`${paint(lines)}\n`)
+
+  const draw = (band, revealed, tinted = colour) => frame(layout, band, revealed, { colour: tinted })
+
+  // The text effect, where asked for and where `ttfx` is there. It draws the
+  // plain glyphs, whose density split is in the characters, and leaves the
+  // cursor hidden on the line under them; omakit walks back up over the five
+  // rows and paints the finished wordmark in its own tints. Absent, the scan
+  // below runs exactly as it would have, byte for byte.
+  const env = options.env || process.env
+  const played = animate && options.effect && effectAvailable(env)
+    ? await playEffect(draw(-2, width + 2, false), stream, { env })
+    : "absent"
+  // The one return pass over the finished wordmark, the shine,
+  // on the scan's own schedule. Two looked better and cost twice the budget,
+  // and the budget is the point.
+  const step = async (band, revealed, delay) => {
+    await new Promise((resolve) => setTimeout(resolve, delay))
+    redraw(draw(band, revealed))
+  }
+  const shine = async () => {
+    const shines = options.shines ?? 1
+    for (let pass = 0; pass < shines; pass += 1) {
+      const forward = pass % 2 === 1
+      for (let step_ = 0; step_ <= Math.ceil(width / shineStride); step_ += 1) {
+        const offset = step_ * shineStride
+        await step(forward ? offset : width - offset, width + 2, delay)
+      }
+    }
+  }
+
+  if (played === "played") {
+    // Back up over the effect's plain rows, paint the wordmark in omakit's
+    // tints, and end it the way the scan ends: with the shine.
+    stream.write(`${ESC}${GLYPH_ROWS}A`)
+    redraw(draw(-2, width + 2))
+    await shine()
+    finish(draw(-2, width + 2))
+    stream.write(`${ESC}?25h`)
+  } else if (played === "broken") {
+    // Something reached the screen and then the effect failed. The cursor is
+    // somewhere inside the rows, so the honest thing is to leave what is
+    // there, show the cursor, start a fresh line and draw the wordmark once.
+    stream.write(`${ESC}?25h\n`)
+    finish(draw(-2, width + 2))
+  } else if (!animate) {
+    finish(draw(-2, width + 2))
+  } else {
+    // Claim the five rows first, so whatever scrolling has to happen happens
+    // here, before a single cursor-up is issued and while the geometry can
+    // still shift harmlessly.
+    redraw(draw(-2, -2))
+    for (let band = 0; band <= width; band += stride) await step(band, band, delay)
+    await shine()
+    finish(draw(-2, width + 2))
+  }
+  stream.write(`${rule}\n`)
+  if (tagline) stream.write(`${tagline}\n`)
+  stream.write("\n")
+}