omakit 0.1.0

package/tools/marketplace/doctor.mjs

@@ -0,0 +1,156 @@
+// `omakit doctor`: what is installed, what is pinned, and what has moved.
+//
+// It reads and it prints. It installs nothing, updates nothing and touches no
+// checkout, because the two things a person might want "upgraded" here are not
+// the same thing and only one of them may ever move on its own.
+//
+// The tool version belongs to the installer: Git for a checkout, npm for its
+// package, and pacman for the Arch package. A CLI that fetches and executes its
+// own replacement is the supply-chain shape this repository warns about.
+//
+// The pin must not move by itself. Bumping it changes where the submission
+// contract is read from, and the procedure in docs/UPSTREAM_CONTRACT.md requires
+// re-proving transport parity and committing the evidence afterwards. An
+// `upgrade` that quietly advanced the pin would break the one guarantee this
+// tool sells. So doctor reports that the pin is behind and prints the procedure.
+//
+// That the pin goes stale unnoticed is, of course, exactly the defect class
+// `omakit watch` exists to report. It would be poor form not to apply it here.
+
+import { execFileSync } from "node:child_process"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { MARKETPLACE_PIN, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
+import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
+import { upgradeCommand } from "./upgrade.mjs"
+
+function tool(repoRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"))
+    return { name: pkg.name, version: pkg.version, engines: pkg.engines?.node || null }
+  } catch {
+    return { name: "omakit", version: "unknown", engines: null }
+  }
+}
+
+function version(command, args = ["--version"]) {
+  try {
+    return execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split("\n")[0]
+  } catch {
+    return null
+  }
+}
+
+async function latestOnRegistry(name) {
+  try {
+    const meta = await getJson(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`)
+    return meta?.version || null
+  } catch {
+    return null
+  }
+}
+
+/** Full pin evidence for machines; human output deliberately keeps short hashes. */
+export function pinFreshness(identity, head) {
+  const current = head.commit === identity.commit
+  return {
+    id: "pin.freshness",
+    state: current ? "ok" : "advice",
+    detail: current
+      ? `the pin is the marketplace's current ${head.branch || "default"}-branch HEAD`
+      : `the pin is ${identity.commit.slice(0, 7)}; the marketplace's ${head.branch || "default"} branch is now at ${head.commit.slice(0, 7)}`,
+    action: current ? null : "Bumping the pin is a deliberate change: docs/UPSTREAM_CONTRACT.md has the procedure, which ends in re-proving parity and committing its evidence. Nothing here does it for you.",
+    evidence: {
+      pinCommit: identity.commit,
+      marketplaceHead: head.commit,
+      branch: head.branch || "default",
+    },
+  }
+}
+
+/**
+ * @param {{ repoRoot: string, offline?: boolean }} options
+ */
+export async function doctor({ repoRoot, offline = false, onPhase }) {
+  // Optional: told what is being read while the network answers. Never
+  // affects the result.
+  const phase = onPhase || (() => {})
+  const checks = []
+  const add = (id, state, detail, action = null, evidence = null) => checks.push({
+    id,
+    state,
+    detail,
+    action,
+    ...(evidence ? { evidence } : {}),
+  })
+
+  const self = tool(repoRoot)
+  add("omakit.version", "info", `${self.name} ${self.version}`)
+
+  const node = process.versions.node
+  const major = Number(node.split(".")[0])
+  add("node", major >= 22 ? "ok" : "problem", `node ${node}${self.engines ? ` (needs ${self.engines})` : ""}`,
+    major >= 22 ? null : "Install Node 22 or newer.")
+
+  const git = version("git")
+  add("git", git ? "ok" : "problem", git || "git was not found on PATH", git ? null : "Install git.")
+
+  const dir = marketplacePinDir(repoRoot)
+  let identity = null
+  try {
+    identity = requirePin(repoRoot).identity
+    add("pin.checkout", "ok",
+      `${identity.commit} (baseline ${identity.baselineVersion}, ${identity.enforcementMode}) at ${dir}`)
+    const sparse = pinIsSparse(dir)
+    add("pin.size", sparse ? "ok" : "advice", `${pinDiskUsage(dir)}${sparse ? ", sparse" : ", full checkout"}`,
+      sparse ? null : `This checkout predates the sparse fetch and is far larger than it needs to be. Remove ${dir} and run \`omakit pin\` to refetch only what omakit reads.`)
+  } catch (error) {
+    add("pin.checkout", "problem", error.message, error.remedy || "omakit pin")
+  }
+
+  if (!offline && identity) {
+    phase("reading the marketplace's current default-branch HEAD")
+    try {
+      const head = await defaultBranchHead(MARKETPLACE_PIN.repository)
+      checks.push(pinFreshness(identity, head))
+    } catch (error) {
+      add("pin.freshness", "unknown", `could not read the marketplace's HEAD (${error.code || "error"})`,
+        error.code === "network-unavailable" ? "Connect to the network, or pass --offline to skip the two checks that need it." : null,
+        { pinCommit: identity.commit, marketplaceHead: null, branch: null })
+    }
+
+    phase("asking the npm registry for the newest published version")
+    const latest = await latestOnRegistry(self.name)
+    if (latest) {
+      const current = latest === self.version
+      add("omakit.latest", current ? "ok" : "advice",
+        current ? `${latest} is the newest published version` : `${latest} is published, this is ${self.version}`,
+        current ? null : upgradeCommand(repoRoot, self.name))
+    } else {
+      add("omakit.latest", "unknown", "the npm registry did not answer, or this version is unpublished")
+    }
+  }
+
+  // Where the credential comes from, said out loud. Borrowing someone's `gh`
+  // login is the right default and a bad secret: a tool that quietly picks up a
+  // credential is a tool you cannot audit by reading its help text, so doctor
+  // names the source every time.
+  // Just "gh version 2.62.0": the build date gh prints after it would nest a
+  // second parenthetical inside this line.
+  phase("reading the GitHub credential from gh")
+  const cli = version("gh")?.replace(/\s*\(.*\)\s*$/, "") || null
+  const auth = credential({ refresh: true })
+  add("github.auth", auth.value ? "ok" : "info",
+    auth.source === "gh"
+      ? `read-only, from your \`gh\` login${cli ? ` (${cli})` : ""}; omakit stores nothing`
+      : `${auth.detail}. \`submit\` and \`verify\` need none at all; \`watch\` and \`parity\` are capped without one`,
+    auth.value
+      ? null
+      : cli
+        ? "`gh auth login` is enough. omakit reads that login for GET requests only and never copies it anywhere."
+        : "Install GitHub's `gh` CLI and run `gh auth login`. omakit reads that login for GET requests only.")
+
+  return { checks, problems: checks.filter((check) => check.state === "problem").length }
+}
+
+export { GitHubError }

package/tools/marketplace/effect.mjs

@@ -0,0 +1,115 @@
+// The one text effect: the wordmark through `ttfx`, where the wordmark is
+// drawn (a bare `omakit` and `omakit setup`), and only into a terminal.
+//
+// `ttfx` (github.com/omacom/ttfx) is the Rust port of TerminalTextEffects that
+// Omarchy's own screensaver draws with, so its vocabulary reads as native
+// here. It is an enhancement and never a requirement: absent, unexecutable or
+// over budget, the wordmark looks exactly as it does without it, and the probe is a
+// spawn that fails silently, the way the `gh` credential lookup does.
+//
+// Colour stays omakit's. Measured before this was decided, the wordmark with
+// omakit's palette escapes piped through `ttfx` in each of its
+// `--existing-color-handling` modes: `ignore` paints its own truecolor
+// gradient, `always` and `dynamic` honour the input tint but re-encode palette
+// index 36 as the fixed truecolor 0;128;128 and drop 39, so the Omarchy theme
+// no longer decides what cyan is. `--xterm-colors` is the same in 256-colour,
+// which this repository bans just the same. So the effect runs with
+// `--no-color`, over the glyphs alone, whose density split survives because it
+// is carried by the characters, and omakit repaints the finished wordmark in
+// its own tints when the effect is over.
+//
+// The arguments are frozen and asserted by tests/unit/read-only.test.mjs:
+// stdin only, no input file, no path, one pinned effect, one seed, so the
+// recorded setup.gif is reproducible.
+
+import { spawn, spawnSync } from "node:child_process"
+import { MOTION } from "./style.mjs"
+
+export const TTFX = "ttfx"
+
+/** The probe: does `ttfx` start and say its name. */
+export const TTFX_PROBE = Object.freeze(["--version"])
+
+/**
+ * The effect. `--no-restore-cursor` leaves the cursor where an ordinary
+ * program would, on the line under the wordmark, which is where the repaint
+ * starts from; measured, the default leaves it on the wordmark's last row.
+ */
+export const TTFX_ARGS = Object.freeze([
+  "--no-color",
+  "--no-restore-cursor",
+  "--seed", "1",
+  "--frame-rate", String(MOTION.effectFrameRate),
+  "expand",
+])
+
+/** Milliseconds a probe may take: `ttfx` starts in half a millisecond, so this is generous. */
+const PROBE_MS = 200
+
+/**
+ * Whether `ttfx` is on PATH and runs. A spawn that fails for any reason is
+ * "no", silently.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function effectAvailable(env = process.env) {
+  try {
+    const probe = spawnSync(TTFX, [...TTFX_PROBE], { encoding: "utf8", env, timeout: PROBE_MS, stdio: ["ignore", "pipe", "ignore"] })
+    return probe.status === 0 && /^ttfx \d/.test(probe.stdout)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Run the effect over `rows`, relaying its frames to `stream` as they come.
+ * Resolves to what happened, so the caller knows what is on the screen:
+ *
+ * - "played": exit 0 inside the budget; the cursor is on the line under the
+ *   rows, hidden, and the rows are drawn plain
+ * - "absent": nothing reached the screen; draw as if `ttfx` were not there
+ * - "broken": something reached the screen and then it failed or ran out of
+ *   budget; the cursor is somewhere inside the rows
+ *
+ * @param {string[]} rows
+ * @param {{ write: (chunk: string|Buffer) => unknown }} stream
+ * @param {{ budgetMs?: number, env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Promise<"played"|"absent"|"broken">}
+ */
+export function playEffect(rows, stream, { budgetMs = MOTION.effectBudgetMs, env = process.env } = {}) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(TTFX, [...TTFX_ARGS], { env, stdio: ["pipe", "pipe", "ignore"] })
+    } catch {
+      resolve("absent")
+      return
+    }
+    let written = 0
+    let settled = false
+    let overBudget = false
+    const settle = (outcome) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(outcome)
+    }
+    // Over budget the process is killed and the promise settles when it has
+    // exited, not when its pipe closes: a child it left behind could hold the
+    // pipe open. In budget it settles on `close`, after the last relayed
+    // chunk, so the caller never repaints under a late frame.
+    const timer = setTimeout(() => {
+      overBudget = true
+      child.once("exit", () => settle(written ? "broken" : "absent"))
+      child.kill("SIGKILL")
+    }, budgetMs)
+    child.on("error", () => settle(written ? "broken" : "absent"))
+    child.stdin.on("error", () => {})
+    child.stdout.on("data", (chunk) => {
+      written += chunk.length
+      stream.write(chunk)
+    })
+    child.on("close", (code) => settle(code === 0 && !overBudget && written ? "played" : written ? "broken" : "absent"))
+    child.stdin.end(`${rows.join("\n")}\n`)
+  })
+}

package/tools/marketplace/form.mjs

@@ -0,0 +1,209 @@
+// The submission contract, read from the pinned marketplace checkout.
+//
+// Nothing about the submission format is written down in Omakit. The title
+// prefix, the field order, the controlled category and tag lists and the exact
+// checklist text all come from the form an author actually fills in,
+// `.github/ISSUE_TEMPLATE/submit-plugin.yml`, at the pinned commit. Updating
+// the pin changes the contract; no Omakit source changes.
+//
+// Measured reason this is derived rather than copied (docs/MEASUREMENTS.md M2):
+// 39 submissions fell out on the title prefix alone, 14 of them still open and
+// 7 rescued by hand; 11 more open submissions are malformed in the body and get
+// "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 those 11 differs from a valid submission by the single word
+// "Suggested" instead of "Suggest". A contract that drifts from the form by one
+// word reproduces exactly that failure, so the form is the only source.
+//
+// The derived contract is then cross-checked against the marketplace's own
+// constants in `scripts/submission.mjs` at the same commit. Both halves must
+// agree; divergence is a loud failure, never a silent guess.
+
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { pathToFileURL } from "node:url"
+import { parseYaml } from "./yaml.mjs"
+import { requirePin } from "./pin.mjs"
+
+export const SUBMIT_FORM_PATH = ".github/ISSUE_TEMPLATE/submit-plugin.yml"
+export const OFFICIAL_SUBMISSION_MODULE = "scripts/submission.mjs"
+
+export class ContractError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = "ContractError"
+    this.code = code
+  }
+}
+
+/**
+ * The marketplace lowercases a submitted tag and joins words with a hyphen
+ * (`normalizeTag` in scripts/submission.mjs). Omakit does not assume that
+ * mapping: every label it derives is checked against the official
+ * `allowedTags` below, so a form label that stops mapping is an error.
+ */
+export function tagSlug(label) {
+  return String(label).trim().toLowerCase().replace(/\s+/g, "-")
+}
+
+function loadOfficial(pinDir) {
+  return import(pathToFileURL(join(pinDir, OFFICIAL_SUBMISSION_MODULE)).href)
+}
+
+function fieldsOf(form) {
+  if (!Array.isArray(form?.body)) throw new ContractError("form-unreadable", `${SUBMIT_FORM_PATH} has no body`)
+  return form.body
+    .filter((item) => item && item.type !== "markdown")
+    .map((item) => ({
+      id: item.id || "",
+      type: item.type || "",
+      label: item.attributes?.label || "",
+      description: item.attributes?.description || "",
+      options: Array.isArray(item.attributes?.options) ? item.attributes.options : null,
+      multiple: item.attributes?.multiple === true,
+      required: item.validations?.required === true,
+    }))
+}
+
+function only(fields, predicate, what) {
+  const found = fields.filter(predicate)
+  if (found.length !== 1) {
+    throw new ContractError(
+      "form-shape-changed",
+      `${SUBMIT_FORM_PATH} no longer has exactly one ${what} (found ${found.length}); the pin changed shape and the submission contract must be re-read before anything is generated`,
+    )
+  }
+  return found[0]
+}
+
+/**
+ * Read the submission contract from the pinned checkout.
+ * @param {{ repoRoot?: string, pinDir?: string }} [options]
+ */
+export async function submissionContract(options = {}) {
+  const pinDir = options.pinDir || requirePin(options.repoRoot).dir
+  const raw = readFileSync(join(pinDir, SUBMIT_FORM_PATH), "utf8")
+  const form = parseYaml(raw)
+  const fields = fieldsOf(form)
+
+  const titleTemplate = typeof form.title === "string" ? form.title : ""
+  if (!titleTemplate.trim()) throw new ContractError("form-shape-changed", `${SUBMIT_FORM_PATH} has no title template`)
+
+  const repository = only(fields, (f) => f.type === "input" && f.required, "required repository input")
+  const category = only(fields, (f) => f.type === "dropdown" && !f.multiple, "single-select dropdown (category)")
+  const tags = only(fields, (f) => f.type === "dropdown" && f.multiple, "multi-select dropdown (tags)")
+  const checklist = only(fields, (f) => f.type === "checkboxes", "checkboxes group (submission checklist)")
+
+  const official = await loadOfficial(pinDir)
+
+  const headings = fields.map((field) => field.label)
+  if (headings.some((heading) => !heading)) throw new ContractError("form-shape-changed", `${SUBMIT_FORM_PATH} has a field without a label`)
+
+  const checklistItems = (checklist.options || []).map((option) =>
+    typeof option === "string" ? { label: option, required: false } : { label: option.label, required: option.required === true },
+  )
+
+  const contract = {
+    formPath: SUBMIT_FORM_PATH,
+    titleTemplate,
+    titlePrefix: titleTemplate.trimEnd(),
+    labels: Array.isArray(form.labels) ? [...form.labels] : [],
+    headings,
+    fields,
+    headingFor: {
+      repository: repository.label,
+      category: category.label,
+      tags: tags.label,
+      checklist: checklist.label,
+    },
+    categories: [...(category.options || [])],
+    tagLabels: [...(tags.options || [])],
+    checklist: checklistItems,
+    maximumTags: official.maximumSubmissionTags,
+    official: {
+      titlePrefix: official.submissionTitlePrefix,
+      allowedCategories: [...official.allowedCategories],
+      allowedTags: [...official.allowedTags],
+      maximumSubmissionTags: official.maximumSubmissionTags,
+      checklist: [...official.submissionChecklist],
+    },
+    parseCurrentSubmission: official.parseCurrentSubmission,
+    extractRepositoryUrl: official.extractRepositoryUrl,
+  }
+
+  assertContractAgrees(contract)
+  return contract
+}
+
+/**
+ * The form and the marketplace's own constants must describe the same
+ * submission. Anything else means the pin is internally inconsistent, and
+ * generating a body from half of it would produce the malformed submissions
+ * this tool exists to prevent.
+ */
+export function assertContractAgrees(contract) {
+  const divergence = []
+  if (!contract.titlePrefix.startsWith(contract.official.titlePrefix)) {
+    divergence.push(`form title ${JSON.stringify(contract.titleTemplate)} does not start with the official prefix ${JSON.stringify(contract.official.titlePrefix)}`)
+  }
+  const categories = contract.categories.join("|")
+  const officialCategories = contract.official.allowedCategories.join("|")
+  if (categories !== officialCategories) {
+    divergence.push(`form categories [${categories}] differ from allowedCategories [${officialCategories}]`)
+  }
+  const slugs = contract.tagLabels.map(tagSlug)
+  const unmapped = slugs.filter((slug) => !contract.official.allowedTags.includes(slug))
+  if (unmapped.length) {
+    divergence.push(`form tags do not map onto allowedTags: ${unmapped.join(", ")}`)
+  }
+  const checklist = contract.checklist.map((item) => item.label).join("\n")
+  const officialChecklist = contract.official.checklist.join("\n")
+  if (checklist !== officialChecklist) {
+    divergence.push("form checklist text differs from submissionChecklist")
+  }
+  if (!Number.isInteger(contract.maximumTags) || contract.maximumTags < 1) {
+    divergence.push(`maximumSubmissionTags is not a positive integer: ${contract.maximumTags}`)
+  }
+  if (divergence.length) {
+    throw new ContractError(
+      "contract-divergent",
+      `the pinned marketplace commit is internally inconsistent, so no submission is generated:\n  - ${divergence.join("\n  - ")}`,
+    )
+  }
+}
+
+/** Resolve one author-supplied category against the form's controlled list. */
+export function resolveCategory(contract, value) {
+  const text = String(value ?? "").trim()
+  if (!text) return { ok: false, reason: "no category given" }
+  const exact = contract.categories.find((option) => option === text)
+  if (exact) return { ok: true, value: exact }
+  const loose = contract.categories.find((option) => option.toLowerCase() === text.toLowerCase())
+  if (loose) return { ok: true, value: loose }
+  return { ok: false, reason: `"${text}" is not one of the form's categories` }
+}
+
+/**
+ * Resolve author-supplied tags against the form's controlled list, accepting
+ * either the form's display labels or the marketplace's normalised slugs, and
+ * always emitting the display labels the form itself would write.
+ */
+export function resolveTags(contract, values) {
+  const given = (Array.isArray(values) ? values : String(values ?? "").split(","))
+    .map((value) => String(value).trim())
+    .filter(Boolean)
+  if (!given.length) return { ok: false, reason: "no tags given", unknown: [] }
+  const bySlug = new Map(contract.tagLabels.map((label) => [tagSlug(label), label]))
+  const resolved = []
+  const unknown = []
+  for (const value of given) {
+    const label = bySlug.get(tagSlug(value))
+    if (!label) unknown.push(value)
+    else if (!resolved.includes(label)) resolved.push(label)
+  }
+  if (unknown.length) return { ok: false, reason: `not on the form's tag list: ${unknown.join(", ")}`, unknown }
+  if (resolved.length < 1 || resolved.length > contract.maximumTags) {
+    return { ok: false, reason: `the form takes 1 to ${contract.maximumTags} tags, got ${resolved.length}`, unknown: [] }
+  }
+  return { ok: true, value: resolved, unknown: [] }
+}