omakit 0.1.0

package/tools/marketplace/pin.mjs

@@ -0,0 +1,203 @@
+// The one home of the marketplace pin (docs/MARKETPLACE.md). The checkout is a
+// read-only clone at this exact commit in the user's XDG cache; `omakit pin`
+// creates or verifies it.
+//
+// It fetches only what omakit reads. The marketplace at this commit is 325 MB,
+// of which 168 MB is preview imagery and 151 MB is history, and omakit reads
+// seven files out of it. A blob-filtered, sparsely checked out fetch of just
+// those paths is 15 MB and takes 2 seconds instead of 17. PIN_PATHS below is the
+// whole list, and tests/unit/pin.test.mjs fails if any module starts reading a
+// path outside it, because on a partial clone such a read would quietly reach
+// for the network instead of failing.
+import { execFileSync } from "node:child_process"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { omakitCacheDir } from "./paths.mjs"
+
+/** Raised for every way the pin can be missing or wrong; the code is what the CLI keys its remedy on. */
+export class PinError extends Error {
+  constructor(message, { code = "marketplace-unavailable", remedy = null } = {}) {
+    super(message)
+    this.name = "PinError"
+    this.code = code
+    this.remedy = remedy
+  }
+}
+
+export const MARKETPLACE_PIN = Object.freeze({
+  repository: "https://github.com/omacom/omarchy-plugin-marketplace",
+  commit: "38060f89d2a10b1f9b6b5afe8e226451e8a5b3f6",
+  commitSubject: "Add Plugin updates plugin (#6374)",
+  baselineVersion: "3",
+  enforcementMode: "selective",
+})
+
+/**
+ * Everything omakit reads out of the pinned checkout, as sparse-checkout
+ * patterns. Anything not listed here is never fetched.
+ *
+ *   /scripts/                     the official submission parser, baseline
+ *                                 scanner, policy, report and record modules,
+ *                                 and build-catalog.mjs read as text for the
+ *                                 reserved plugin-id namespace. Taken whole
+ *                                 because those modules import each other.
+ *   /registry.json                retired plugin ids, listed repositories
+ *   /site/catalog.json            listed plugin ids
+ *   /.github/ISSUE_TEMPLATE/      the submission form: the whole contract
+ */
+export const PIN_PATHS = Object.freeze([
+  "/scripts/",
+  "/registry.json",
+  "/site/catalog.json",
+  "/.github/ISSUE_TEMPLATE/",
+])
+
+/**
+ * The user-writable pin location: `$XDG_CACHE_HOME/omakit/marketplace`, or
+ * `~/.cache/omakit/marketplace`. omakit reads no variable of its own; a test or
+ * an unusual install that wants the pin elsewhere sets XDG_CACHE_HOME, which is
+ * the same switch every user has.
+ */
+export function marketplacePinDir(_repoRoot, env = process.env) {
+  return omakitCacheDir("marketplace", env)
+}
+
+/** The location used before 0.1.0 packaging made the tool installable read-only. */
+export function legacyMarketplacePinDir(repoRoot) {
+  return join(resolve(repoRoot), ".cache/marketplace")
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+function pinMigration(repoRoot, env = process.env) {
+  const oldDir = legacyMarketplacePinDir(repoRoot)
+  const newDir = marketplacePinDir(repoRoot, env)
+  if (!existsSync(join(oldDir, ".git")) || existsSync(newDir)) return null
+  const remedy = `mkdir -p -- ${shellQuote(dirname(newDir))} && mv -- ${shellQuote(oldDir)} ${shellQuote(newDir)}`
+  return new PinError(
+    `the marketplace pin is still at the old in-repository location ${oldDir}; the user-writable location ${newDir} does not exist. Omakit will not move the measured 15 MB checkout without you.`,
+    { code: "marketplace-pin-migration-required", remedy },
+  )
+}
+
+function git(dir, args, options = {}) {
+  return execFileSync("git", ["-C", dir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...options })
+}
+
+/** Identity of the checkout at `dir`: commit plus the policy constants read from the pinned source. */
+function readPinIdentity(dir) {
+  const commit = git(dir, ["rev-parse", "HEAD"]).trim()
+  const policy = git(dir, ["show", `${commit}:scripts/security-baseline-policy.mjs`])
+  const version = policy.match(/securityBaselineVersion\s*=\s*"?([^";\s]+)"?/)?.[1] || "unknown"
+  const mode = policy.match(/securityBaselineEnforcementMode\s*=\s*"([^"]+)"/)?.[1] || "unknown"
+  const dirty = git(dir, ["status", "--porcelain"]).trim().length > 0
+  return { commit, baselineVersion: version, enforcementMode: mode, dirty }
+}
+
+/**
+ * Verify the pinned checkout without touching the network. Throws with a
+ * stable message when it is missing, at another commit, or modified.
+ */
+export function requirePin(repoRoot, env = process.env) {
+  const migration = pinMigration(repoRoot, env)
+  if (migration) throw migration
+  const dir = marketplacePinDir(repoRoot, env)
+  if (!existsSync(join(dir, "scripts/security-baseline-scanner.mjs"))) {
+    throw new PinError(`no pinned marketplace checkout at ${dir}. Every rule omakit checks is read from that checkout, so nothing can run without it.`)
+  }
+  const identity = readPinIdentity(dir)
+  if (identity.commit !== MARKETPLACE_PIN.commit) {
+    throw new PinError(`${dir} is at ${identity.commit}, expected pin ${MARKETPLACE_PIN.commit}`)
+  }
+  if (identity.dirty) {
+    throw new PinError(`${dir} has local modifications; the pin must stay unmodified`)
+  }
+  return { dir, identity }
+}
+
+/** A checkout that was initialised but never fetched (a run that lost the network) has a .git and no HEAD. */
+function hasCommit(dir) {
+  try {
+    git(dir, ["rev-parse", "--verify", "-q", "HEAD"])
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Reproducible setup: fetch exactly the pinned commit (depth 1) into
+ * the XDG cache and check it out detached. Idempotent; never rewrites
+ * an existing checkout that already sits at the pin.
+ *
+ * `log` is told what is happening as `{ state, text }`: a `pass` or `info`
+ * line to keep, or `fetching` for the slow step about to start, which the CLI
+ * draws as a progress line rather than a line of output.
+ */
+export function ensurePin(repoRoot, log = () => {}, env = process.env) {
+  const migration = pinMigration(repoRoot, env)
+  if (migration) throw migration
+  const dir = marketplacePinDir(repoRoot, env)
+  if (existsSync(join(dir, ".git")) && hasCommit(dir)) {
+    const identity = readPinIdentity(dir)
+    if (identity.commit === MARKETPLACE_PIN.commit && !identity.dirty) {
+      log({ state: "pass", text: `marketplace pin ${identity.commit.slice(0, 7)} present at ${dir}` })
+      return { dir, identity, fetched: false }
+    }
+    if (identity.dirty) throw new PinError(`${dir} has local modifications; remove the directory and run again`)
+    log({ state: "info", text: `${dir} is at ${identity.commit}, not the pin` })
+  } else if (!existsSync(join(dir, ".git"))) {
+    mkdirSync(dir, { recursive: true })
+    execFileSync("git", ["init", "-q", dir], { encoding: "utf8" })
+    git(dir, ["remote", "add", "origin", MARKETPLACE_PIN.repository])
+  }
+  log({ state: "fetching", text: `fetching the pinned marketplace checkout, ${MARKETPLACE_PIN.commit.slice(0, 7)}, about 15 MB` })
+  // Written as plumbing rather than through `git sparse-checkout`, so the
+  // result does not depend on the git version's cone-mode defaults.
+  git(dir, ["config", "core.sparseCheckout", "true"])
+  mkdirSync(join(dir, ".git/info"), { recursive: true })
+  writeFileSync(join(dir, ".git/info/sparse-checkout"), `${PIN_PATHS.join("\n")}\n`)
+  try {
+    // git's own stderr is captured, not inherited: a network failure ends up
+    // as one failure state in the tool's register, not two voices on stderr.
+    git(dir, ["fetch", "-q", "--depth", "1", "--filter=blob:none", "origin", MARKETPLACE_PIN.commit])
+  } catch (error) {
+    const reason = String(error?.stderr || error?.message || "").trim().split("\n").filter((line) => /^fatal:/.test(line)).pop()
+      || String(error?.message || "git fetch failed").trim().split("\n")[0]
+    const offline = /unable to access|Could not resolve|Could not connect|Connection refused|Network is unreachable/i.test(reason)
+    const failure = new PinError(`the pinned marketplace checkout could not be fetched: ${reason.replace(/^fatal:\s*/, "")}`)
+    if (offline) failure.code = "network-unavailable"
+    throw failure
+  }
+  git(dir, ["checkout", "-q", "--detach", MARKETPLACE_PIN.commit])
+  const identity = readPinIdentity(dir)
+  if (identity.commit !== MARKETPLACE_PIN.commit) throw new PinError(`checkout ended at ${identity.commit}`)
+  log({ state: "pass", text: `marketplace pin ${identity.commit.slice(0, 7)} (baseline ${identity.baselineVersion}, ${identity.enforcementMode}) at ${dir}, ${pinDiskUsage(dir)}` })
+  return { dir, identity, fetched: true }
+}
+
+/** Human-readable size of the pinned checkout, for `omakit pin` and `omakit doctor`. */
+export function pinDiskUsage(dir) {
+  // -H follows a symlink given on the command line (POSIX; GNU's -D). Measured
+  // without it: a checkout reached through a symlink reported 0.0 MB, the size
+  // of the link, while the directory behind it was 15 MB.
+  try {
+    const output = execFileSync("du", ["-skH", dir], { encoding: "utf8" }).split(/\s+/)[0]
+    const mib = Number(output) / 1024
+    return `${mib < 10 ? mib.toFixed(1) : Math.round(mib)} MB on disk`
+  } catch {
+    return "size unknown"
+  }
+}
+
+/** True when the checkout was fetched with only PIN_PATHS, as a fresh one is. */
+export function pinIsSparse(dir) {
+  try {
+    const enabled = execFileSync("git", ["-C", dir, "config", "--get", "core.sparseCheckout"], { encoding: "utf8" }).trim()
+    return enabled === "true"
+  } catch {
+    return false
+  }
+}

package/tools/marketplace/plugin.mjs

@@ -0,0 +1,64 @@
+// What the installable tree must contain at the root, and the plugin identity
+// the submission is about.
+//
+// Omakit does not re-validate the manifest. The marketplace validates schema,
+// required fields, id characters, kinds, entry points and symlinks itself, and
+// its validator (`scripts/build-catalog.mjs`) cannot be imported without the
+// marketplace's own native dependencies. Re-implementing those rules here would
+// be copied policy that silently drifts from the pin, which is the failure this
+// repository is built to avoid. So this module checks only what the submission
+// contract needs: that the three root files exist, that there is exactly one
+// root manifest, and what id it declares.
+
+import { isBlob, readText, rootEntries } from "./tree.mjs"
+
+// The marketplace's own patterns for a root README and a root license
+// (`validateRepositoryDocs` in scripts/build-catalog.mjs at the pin).
+export const README_PATTERN = /^readme(?:\.[^/]+)?$/i
+export const LICENSE_PATTERN = /^(?:licen[cs]e|copying)(?:\.[^/]+)?$/i
+export const MANIFEST_PATH = "manifest.json"
+
+// Keyword probes for the first checklist item, "The repository is public and
+// contains installation and removal instructions." This is a text probe on the
+// README, not a semantic reading, and the output says so.
+export const INSTALL_PATTERN = /\binstall(?:ation|ing|s|ed)?\b/i
+export const REMOVAL_PATTERN = /\b(?:uninstall(?:ation|ing|s|ed)?|remov(?:al|e|es|ed|ing)|delet(?:e|es|ed|ing)|purge)\b/i
+
+/**
+ * @param {{ dir: string, commit: string, entries: Array }} subject
+ */
+export function inspectTree({ dir, entries }) {
+  const roots = rootEntries(entries).filter(isBlob)
+  const readme = roots.find((entry) => README_PATTERN.test(entry.path)) || null
+  const license = roots.find((entry) => LICENSE_PATTERN.test(entry.path)) || null
+  const manifests = entries
+    .filter((entry) => isBlob(entry) && /^(?:[^/]+\/)?manifest\.json$/i.test(entry.path))
+    .map((entry) => entry.path)
+    .sort()
+  const rootManifest = roots.find((entry) => entry.path === MANIFEST_PATH) || null
+
+  let manifest = null
+  let manifestError = null
+  if (rootManifest) {
+    try {
+      manifest = JSON.parse(readText(dir, rootManifest.sha))
+    } catch (error) {
+      manifestError = error.message
+    }
+  }
+
+  const readmeText = readme ? readText(dir, readme.sha) : ""
+
+  return {
+    readme: readme?.path || null,
+    license: license?.path || null,
+    manifestPaths: manifests,
+    rootManifestPath: rootManifest?.path || null,
+    manifest,
+    manifestError,
+    pluginId: typeof manifest?.id === "string" ? manifest.id.trim() : "",
+    pluginName: typeof manifest?.name === "string" ? manifest.name.trim() : "",
+    readmeMentionsInstall: INSTALL_PATTERN.test(readmeText),
+    readmeMentionsRemoval: REMOVAL_PATTERN.test(readmeText),
+  }
+}

package/tools/marketplace/preflight.mjs

@@ -0,0 +1,164 @@
+// Baseline preflight: the official Omarchy marketplace security baseline, run
+// locally over the harvested transport, reported verbatim together with what
+// its outcome will cause on submission.
+//
+// Measured reason this runs before submitting (docs/MEASUREMENTS.md M4): of the
+// 2,916 listed sources with a recorded baseline at the pin, it produced 1,681
+// `passed`, 1,215 `review-required` and 20 `needs-fixes` (counted by
+// registry.mjs baselineFigures, pinned by tests/unit/registry-figures.test.mjs). `review-required` is not a defect and
+// needs no source change, but it does mean a human must look, and it is the
+// single largest determinant of whether a submission waits on a person. An
+// author who knows which of the seven capabilities triggered it before
+// submitting can decide to remove it or to explain it in the maintainer notes
+// instead of finding out after the queue.
+//
+// Everything policy-shaped here is read from the pinned checkout: the outcome
+// derivation, the disposition, the blocking rule set and the enforcement mode.
+// The two disclaimer sentences are rendered by the marketplace's own report
+// builder so they are its words, not Omakit's. The machine-readable baseline
+// marker that builder emits is stripped and asserted absent: Omakit must never
+// produce something that could be pasted into an issue as the bot's own
+// attestation.
+
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { requirePin } from "./pin.mjs"
+import { marketplaceBaselineSection } from "./verify.mjs"
+
+export class PreflightError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = "PreflightError"
+    this.code = code
+  }
+}
+
+async function loadPolicy(pinDir) {
+  return import(pathToFileURL(join(pinDir, "scripts/security-baseline-policy.mjs")).href)
+}
+
+async function loadReport(pinDir) {
+  return import(pathToFileURL(join(pinDir, "scripts/security-baseline-report.mjs")).href)
+}
+
+/**
+ * The marketplace's own two closing sentences, read out of the source of its
+ * own report builder at the pin. They are not written down in Omakit: the
+ * baseline result must never be restated as a safety claim, and the least
+ * error-prone way to say so is in the marketplace's words.
+ */
+export async function officialDisclaimers(pinDir) {
+  const report = await loadReport(pinDir)
+  const source = String(report.buildSecurityBaselineReport)
+  const sentences = [...source.matchAll(/"(This [^"]{20,300}\.)"/g)].map((match) => match[1])
+  if (sentences.length < 2) {
+    throw new PreflightError(
+      "disclaimer-unreadable",
+      "cannot read the marketplace's baseline disclaimer sentences from the pin; refusing to report a baseline result without them",
+    )
+  }
+  return sentences
+}
+
+/**
+ * Render the marketplace's own baseline detail section for a local result.
+ *
+ * `buildSecurityBaselineReport` is deliberately not called: it prepends the
+ * machine-readable attestation marker the bot posts, and Omakit must never
+ * construct something that could be pasted into an issue as the marketplace's
+ * own attestation. Only the detail section is rendered, the official closing
+ * sentences are appended, and the absence of either marker is asserted.
+ */
+export async function officialReportText(pinDir, result) {
+  const policy = await loadPolicy(pinDir)
+  const report = await loadReport(pinDir)
+  const text = [
+    "## Automated security baseline",
+    "",
+    report.buildSecurityBaselineDetails(result),
+    "",
+    ...(await officialDisclaimers(pinDir)).flatMap((sentence) => [sentence, ""]),
+  ].join("\n").trim()
+  if (text.includes(policy.securityBaselineMarkerPrefix) || text.includes(policy.securityBaselineErrorMarker)) {
+    throw new PreflightError("marker-leak", "refusing to emit a marketplace security-baseline marker")
+  }
+  return text
+}
+
+/**
+ * What the outcome will cause on submission, derived from the pinned policy.
+ * @param {object} official the verbatim result from the official baseline
+ */
+export async function consequence(pinDir, official) {
+  const policy = await loadPolicy(pinDir)
+  const findings = (official?.findings || []).map((finding) => finding.ruleId || finding.id || String(finding))
+  const capabilities = (official?.capabilities || []).map((capability) => capability.id || String(capability))
+  const blocking = findings.filter((ruleId) => policy.securityBaselineSelectivelyBlockingRules.includes(ruleId))
+  const outcome = official?.outcome ?? policy.securityBaselineOutcome(official?.findings || [], official?.capabilities || [])
+  const disposition = official?.disposition ?? policy.securityBaselineDisposition(official)
+  const blocksApproval = official?.blocksApproval ?? policy.securityBaselineBlocksApproval(official)
+  return {
+    outcome,
+    disposition,
+    blocksApproval: Boolean(blocksApproval),
+    enforcementMode: official?.enforcementMode || policy.securityBaselineEnforcementMode,
+    findings,
+    capabilities,
+    selectivelyBlockingRules: [...policy.securityBaselineSelectivelyBlockingRules],
+    blockingFindings: blocking,
+    knownCapabilities: Object.keys(policy.securityBaselineCapabilityCatalog),
+    meaning: describe({ outcome, blocksApproval: Boolean(blocksApproval), blocking, capabilities, policy }),
+  }
+}
+
+function describe({ outcome, blocksApproval, blocking, capabilities, policy }) {
+  if (outcome === "passed") {
+    return "No findings and no capabilities. Nothing in the baseline holds this submission back."
+  }
+  if (outcome === "review-required") {
+    const names = capabilities.map((id) => policy.securityBaselineCapabilityCatalog[id]?.title || id)
+    return `No findings, but ${capabilities.length} of the ${Object.keys(policy.securityBaselineCapabilityCatalog).length} capabilities are present (${names.join("; ")}), so a maintainer must look at this commit before it can be listed.`
+  }
+  if (outcome === "needs-fixes" && blocksApproval) {
+    return `Findings include ${blocking.join(", ")}, which block publication under the ${policy.securityBaselineEnforcementMode} enforcement mode. These must be fixed in a new commit.`
+  }
+  if (outcome === "needs-fixes") {
+    return `Findings are present but none of them is selectively blocking (${policy.securityBaselineSelectivelyBlockingRules.join(", ")}), so the disposition is review-required: a maintainer may accept them for this exact commit.`
+  }
+  return `Unrecognised outcome ${JSON.stringify(outcome)} from the pinned policy.`
+}
+
+/**
+ * Run the official baseline over the local transport for one subject.
+ * @param {{ repoRoot: string, subject: object }} options
+ */
+export async function baselinePreflight({ repoRoot, subject }) {
+  const { dir: pinDir, identity } = requirePin(repoRoot)
+  const section = await marketplaceBaselineSection({ repoRoot, subject })
+  if (!section.invoked) {
+    return { pin: section.pin, invoked: false, skipReason: section.skipReason, official: null, consequence: null, officialReport: null, statement: section.statement }
+  }
+  if (section.official?.error) {
+    return {
+      pin: section.pin,
+      invoked: true,
+      skipReason: null,
+      official: section.official,
+      consequence: null,
+      officialReport: null,
+      statement: section.statement,
+      refusal: section.official.error,
+    }
+  }
+  return {
+    pin: { ...section.pin, baselineVersion: identity.baselineVersion, enforcementMode: identity.enforcementMode },
+    invoked: true,
+    skipReason: null,
+    transport: section.transport,
+    assumedByAdapter: section.assumedByAdapter,
+    official: section.official,
+    consequence: await consequence(pinDir, section.official),
+    officialReport: await officialReportText(pinDir, section.official),
+    statement: section.statement,
+  }
+}

package/tools/marketplace/progress.mjs

@@ -0,0 +1,96 @@
+// A progress line, on stderr, only when a person is looking.
+//
+// Three rules, and they are the whole design.
+//
+// It writes to stderr, never stdout. An agent piping `omakit submit` gets the
+// same bytes it always got; the recordings in docs/media/ capture stdout and are
+// unaffected. Nothing downstream has to strip anything.
+//
+// It only draws when stderr is a terminal; a pipe or TERM=dumb is what turns
+// it off, and omakit has no switch of its own. NO_COLOR removes the tint and nothing else: a progress line in the
+// terminal's own foreground still says what is happening, and saying what is
+// happening is the point.
+//
+// It says what is happening, not that something is happening. The one genuinely
+// slow step is the official baseline reading a repository snapshot blob by blob;
+// a label naming the current phase is information. A sweep with no phase would
+// be decoration, and decoration in the middle of a security-baseline preview is
+// what makes a tool feel less trustworthy, not more.
+
+import { code, colourEnabled, COLUMNS, DENSITY, motionEnabled, MOTION } from "./style.mjs"
+
+// A scanner sweeping back and forth over a fixed track: a three-cell head
+// moving across twelve cells, with the rest of the track drawn as a floor so
+// the motion reads as direction instead of blinking. The head and the floor
+// are the same two glyphs the wordmark ends on, so the two animations read as
+// one motif.
+const TRACK = 12
+const HEAD = 3
+const INTERVAL = MOTION.progressFrameMs
+
+const ESC = "\u001b["
+const ACCENT = `${ESC}${code("typeable")}m`
+const TRACK_TINT = `${ESC}${code("punctuation")}m`
+const RESET = `${ESC}0m`
+const CLEAR_LINE = `\r${ESC}2K`
+
+/** Which cells the head covers at this step, bouncing rather than wrapping. */
+export function headAt(step, track = TRACK, head = HEAD) {
+  const span = (track - head) * 2
+  const at = ((step % span) + span) % span
+  return at <= track - head ? at : span - at
+}
+
+export function progressEnabled(stream = process.stderr, env = process.env) {
+  return motionEnabled(stream, env)
+}
+
+/**
+ * @param {{ stream?: NodeJS.WriteStream, enabled?: boolean, colour?: boolean }} [options]
+ * @returns {{ phase: (label: string) => void, done: () => void }}
+ */
+export function progress(options = {}) {
+  const stream = options.stream || process.stderr
+  const enabled = options.enabled ?? progressEnabled(stream)
+  const colour = options.colour ?? colourEnabled(stream)
+  if (!enabled) return { phase: () => {}, done: () => {} }
+
+  let label = ""
+  let step = 0
+  let timer = null
+
+  const clear = () => stream.write(CLEAR_LINE)
+  const draw = () => {
+    const start = headAt(step)
+    // Three runs, not twelve cells: the floor before the head, the head, the
+    // floor after it. A frame is one write and carries at most three tints.
+    const paint = (glyph, count, tint) => (count > 0 ? (colour ? `${tint}${glyph.repeat(count)}${RESET}` : glyph.repeat(count)) : "")
+    const track = paint(DENSITY.floor, start, TRACK_TINT)
+      + paint(DENSITY.full, HEAD, ACCENT)
+      + paint(DENSITY.floor, TRACK - start - HEAD, TRACK_TINT)
+    // One write per frame, clear included: two writes can flicker on a slow
+    // terminal, and a partially drawn frame is worse than no animation. The
+    // label is cut to the terminal's width first: a line that wraps is a line
+    // the clear does not reach, and it stays behind as a stray row.
+    const room = (Number.isFinite(stream.columns) && stream.columns > 0 ? stream.columns : COLUMNS) - TRACK - 2
+    const shown = label.length > room ? `${label.slice(0, Math.max(0, room - 1))}\u2026` : label
+    stream.write(`${CLEAR_LINE}${track} ${shown}`)
+    step += 1
+  }
+
+  return {
+    phase(next) {
+      label = String(next)
+      if (!timer) {
+        timer = setInterval(draw, INTERVAL)
+        timer.unref?.()
+      }
+      draw()
+    },
+    done() {
+      if (timer) clearInterval(timer)
+      timer = null
+      clear()
+    },
+  }
+}