omakit 0.1.8 → 0.1.9

package/README.md

@@ -2,7 +2,7 @@
   <img src="docs/media/banner.gif" alt="omakit" width="440">
 </p>
 
-[![Built for Omarchy](https://raw.githubusercontent.com/tcballard/omarchy-badges/85f859029e236e784e7b05ada6dbe73506d07a91/badges/v1/built-for-omarchy.svg)](https://github.com/tcballard/omarchy-badges)
+[![Built for Omarchy: App](https://raw.githubusercontent.com/tcballard/omarchy-badges/75975e5b5bf75e7ede3764bcd2950046f7abfe2c/badges/v1/omarchy-app.svg)](https://github.com/tcballard/omarchy-badges)
 
 **Everything knowable about an Omarchy Quattro plugin submission, checked
 before you post it:** the tree, the manifest, the form, the commit, and the
@@ -56,7 +56,7 @@ omakit setup
 ```
 
 If `omakit` is not found afterwards, npm's global `bin` is not on your PATH
-(measured: a prefix of `~/.local/share/lerd/node-global` whose `bin` no shell
+(measured: an npm global prefix under `~/.local/share` whose `bin` no shell
 searched). Run `"$(npm prefix --global)/bin/omakit" setup` once: it prints the
 one line that puts that directory on PATH for the shell in `$SHELL`, and the
 rc file to keep it in; `omakit doctor` reports the same as `omakit.path`.
@@ -192,6 +192,11 @@ the marketplace's current HEAD when the network is there, because the pin's
 copy is stale within hours (4,201 of 4,293 commits in 30 days touched only
 `registry.json`), and from the pin with `--offline`.
 
+This is why the tool is Node: the marketplace's scanner, form parser and
+catalog builder are Node modules, and omakit runs them verbatim from the
+pinned commit instead of reimplementing their rules, where a different
+language would mean a copy that can drift.
+
 The security baseline is the marketplace's own code, imported unmodified and run
 over a local snapshot with no network. Omakit adds no rule, renames no outcome,
 and never restates the result as a safety claim: the baseline does no data-flow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "The safe place to find out: everything knowable about an Omarchy Quattro plugin submission before you post it, on your own machine. Agent-first, read-only, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/tools/marketplace/README.md

@@ -21,7 +21,7 @@ local commit through the transport seam the marketplace tests itself
 | `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. Three outcomes: `ready` (the body), `refused` (a blocking check failed) and `listed` (the plugin is already listed by its own repository: `identity.available` passes with the listing's record, the five body checks are omitted rather than drawn as waiting, no body exists on purpose, and `listing` carries the listed commit against the local one and the form to use for a newer commit). Decides the category and tags after the registry: a listed plugin, own or taken, is asked for neither; an unlisted one without them is asked through `ask.mjs` at a terminal, and is a usage error otherwise. Ends with `reproduce`, the command line that repeats the run without asking. Under `--offline` the validation-commit check is `skipped`, not passed: verdict `skipped`, listed under `skipped` and not `unknown`, never blocking, and the READY line says "1 check skipped (--offline)". |
 | `ask.mjs` | The two questions `submit` asks a person at a terminal, and only there: category and tags, numbered from the pinned form, with the marketplace's own presentation for the manifest's kinds (read from the pinned catalog builder) as the default where it is on the list. Prompts on stderr, nothing persisted. |
-| `doctor.mjs` | What is installed, what is pinned, and what has moved. `pin.freshness` compares each path in `PIN_PATHS` between the pin and the marketplace's HEAD by tree or blob id and splits what moved by the list `registry.mjs` reads live from: `registry.json` and `site/catalog.json` moving is `ok`, because those are read from HEAD anyway; anything else moving (`scripts/`, the two forms) is a `note` naming the paths, with an action a user can take, `omakit upgrade` and then an issue at the repository named in package.json. The maintainer's pin procedure stays in `docs/UPSTREAM_CONTRACT.md` and is never printed. HEAD unreadable is `unknown`. `--json` carries `changedPaths`, `readLive` and `pinned` under the check's evidence. |
+| `doctor.mjs` | What is installed, what is pinned, and what has moved. `omakit.version` is one check for one question, is this the current omakit: `ok` with "0.1.8, the newest published version", a `note` with "0.1.8; 0.1.9 is published" and the upgrade command, `unknown` with the registry's failure code, `info` offline; its evidence carries `{ installed, latest, source }`. `pin.freshness` compares each path in `PIN_PATHS` between the pin and the marketplace's HEAD by tree or blob id and splits what moved by the list `registry.mjs` reads live from: `registry.json` and `site/catalog.json` moving is `ok`, because those are read from HEAD anyway; anything else moving (`scripts/`, the two forms) is a `note` naming the paths, with an action a user can take, `omakit upgrade` and then an issue at the repository named in package.json. The maintainer's pin procedure stays in `docs/UPSTREAM_CONTRACT.md` and is never printed. HEAD unreadable is `unknown`. `--json` carries `changedPaths`, `readLive` and `pinned` under the check's evidence. |
 | `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. Six states: `▁ ok`, `█ FAIL`, `▓ note`, `░ info`, `▒ ?` for a check that could not be made, and `▔ skip` for a check a flag said not to make, the floor's ink at the ceiling so it is never read as a pass. `docs/TUI.md` explains it. |
@@ -32,6 +32,7 @@ local commit through the transport seam the marketplace tests itself
 | `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. |
+| `paths.mjs` | Omakit's cache directory, following XDG, and `withHomeAbbreviated()`: a path under `$HOME` written as `~/...` for a person, applied where doctor, setup and pin render text and never where a result is built, so `--json` keeps every path absolute. |
 | `cli.mjs` | The one entry point behind `bin/omakit`, and the one register every failure is reported in. `submit` exits on the outcome: 1 for `refused`, 0 for `ready` and `listed`. |
 
 ```text

package/tools/marketplace/cli.mjs

@@ -29,7 +29,7 @@ import { progress } from "./progress.mjs"
 import { banner, bannerEnabled } from "./banner.mjs"
 import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
 import { action, colourEnabled, GUTTER, labelled, mark, styler, wrap } from "./style.mjs"
-import { omakitCacheDir } from "./paths.mjs"
+import { omakitCacheDir, withHomeAbbreviated } from "./paths.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -284,7 +284,7 @@ if (command === "setup") {
       // ensurePin narrates: a state line to keep, then a fetch it is about to
       // start. The fetch is the slow part, so it gets the progress line.
       if (line.state === "fetching") spinner.phase(line.text)
-      else process.stdout.write(`${mark(line.state, c)}${wrap(line.text, { indent: GUTTER }, c).join("\n").trimStart()}\n`)
+      else process.stdout.write(`${mark(line.state, c)}${wrap(withHomeAbbreviated(line.text), { indent: GUTTER }, c).join("\n").trimStart()}\n`)
     })
   } catch (error) {
     spinner.done()

package/tools/marketplace/completion.mjs

@@ -13,6 +13,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { basename, dirname, join } from "node:path"
 import { tagSlug } from "./form.mjs"
 import { COMMANDS, COMPLETION_SHELLS } from "./usage.mjs"
+import { withHomeAbbreviated } from "./paths.mjs"
 
 /**
  * The completion model, read out of the help data. A subcommand is the word
@@ -221,7 +222,7 @@ export function completionInstall(env = process.env) {
   const shell = basename(env.SHELL || "")
   const home = env.HOME || ""
   if (!home || !COMPLETION_SHELLS.includes(shell)) return null
-  const tilde = (dir) => (dir.startsWith(home) ? `~${dir.slice(home.length)}` : dir)
+  const tilde = (dir) => withHomeAbbreviated(dir, env)
   if (shell === "bash") {
     const dir = join(env.XDG_DATA_HOME || join(home, ".local/share"), "bash-completion/completions")
     return { shell, path: join(dir, "omakit"), display: `${tilde(dir)}/omakit`, note: null }

package/tools/marketplace/doctor.mjs

@@ -42,7 +42,7 @@ import { join } from "node:path"
 import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
 import { LIVE_PATHS } from "./registry.mjs"
 import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
-import { latestOnRegistry, upgradeCommand } from "./upgrade.mjs"
+import { NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
 import { pathHint } from "./path-hint.mjs"
 
 /** "git+https://github.com/owner/name.git" in package.json -> "https://github.com/owner/name", or null. */
@@ -172,13 +172,13 @@ export function pinFreshness(identity, head, changedPaths = null, { issues = nul
 
 /**
  * @param {{ repoRoot: string, offline?: boolean, env?: object, npmPrefix?: () => string|null,
- *           resolveHead?: typeof defaultBranchHead, latest?: typeof latestOnRegistry }} options
+ *           resolveHead?: typeof defaultBranchHead, latest?: typeof registryLatest }} options
  *   `env` and `npmPrefix` are injectable for tests of the PATH check;
  *   `resolveHead` and `latest` for tests of the two checks that read the
  *   network, whose defaults are the tool's one HEAD resolver and its one
  *   registry read.
  */
-export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = latestOnRegistry }) {
+export async function doctor({ repoRoot, offline = false, onPhase, env = process.env, npmPrefix, resolveHead = defaultBranchHead, latest: latestVersion = registryLatest }) {
   // Optional: told what is being read while the network answers. Never
   // affects the result.
   const phase = onPhase || (() => {})
@@ -192,7 +192,27 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
   })
 
   const self = tool(repoRoot)
-  add("omakit.version", "info", `${self.name} ${self.version}`)
+  // What is installed and what is published, one check: the two facts are
+  // one question, "is this the current omakit", and were two lines before.
+  // Offline, the first fact alone, as information. The evidence carries both
+  // and where the second came from.
+  const versionCheck = (state, detail, action = null, latest = null, source = null) =>
+    add("omakit.version", state, detail, action, { installed: self.version, latest, source })
+  if (offline) {
+    versionCheck("info", `${self.version}; the newest published version is not checked (--offline)`)
+  } else {
+    phase("asking the npm registry for the newest published version")
+    const published = await latestVersion(self.name)
+    if (published.version) {
+      const current = published.version === self.version
+      versionCheck(current ? "ok" : "advice",
+        current ? `${self.version}, the newest published version` : `${self.version}; ${published.version} is published`,
+        current ? null : `run \`${upgradeCommand(repoRoot, self.name)}\``,
+        published.version, NPM_REGISTRY)
+    } else {
+      versionCheck("unknown", `${self.version}; could not read the npm registry (${published.error?.code || "error"})`)
+    }
+  }
 
   // Reachable as a bare command, or the one line that makes it so for this
   // install (path-hint.mjs). Measured: an npm prefix whose bin is not on PATH
@@ -241,16 +261,6 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
         { pinCommit: identity.commit, marketplaceHead: null, branch: null })
     }
 
-    phase("asking the npm registry for the newest published version")
-    const latest = await latestVersion(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`

package/tools/marketplace/path-hint.mjs

@@ -2,7 +2,7 @@
 // it so, for the install that is actually here.
 //
 // Measured: after `npm install --global omakit` on a machine whose npm prefix
-// was ~/.local/share/lerd/node-global, the command was missing, because that
+// was a directory under ~/.local/share, the command was missing, because that
 // prefix's `bin` was not on PATH. `omakit setup` then printed the `ln -s` hint
 // written for a clone, which points at a bin/omakit that npm did not lay out
 // where the hint assumes. An npm install needs the npm prefix's `bin` on PATH,

package/tools/marketplace/paths.mjs

@@ -8,3 +8,21 @@ export function omakitCacheDir(name = "", env = process.env) {
     : join(env.HOME || homedir(), ".cache")
   return join(base, "omakit", name)
 }
+
+/**
+ * Text for a person, with every path under the home directory written the
+ * way a shell would take it: `~/.cache/omakit/marketplace`. Only `$HOME`
+ * counts, because `~` is what the shell expands to `$HOME` and nothing else;
+ * with it unset, or for a path outside it, the text is returned as it came.
+ * Human output only: `--json` keeps every path absolute, so this is applied
+ * where text is rendered, never where a result is built.
+ */
+export function withHomeAbbreviated(text, env = process.env) {
+  const home = String(env.HOME || "").replace(/\/+$/, "")
+  if (!home || !home.startsWith("/")) return String(text)
+  // The home directory where a path starts: at the start of the text or after
+  // the characters a path follows in prose or a command, and followed by a
+  // separator or the end, so /tmp/home/me/x and /home/meh/x are left alone.
+  const literal = home.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return String(text).replace(new RegExp(`(^|[\\s"'(=:])${literal}(?=/|$|[\\s"'),:])`, "g"), "$1~")
+}

package/tools/marketplace/report.mjs

@@ -20,6 +20,7 @@
 import {
   action, colourEnabled, COLUMNS, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
 } from "./style.mjs"
+import { withHomeAbbreviated } from "./paths.mjs"
 
 const body = " ".repeat(GUTTER)
 
@@ -317,7 +318,13 @@ export function renderVerify(document, { colour = colourEnabled(), blockingRules
 
 const DOCTOR_STATE = { ok: "pass", advice: "advisory", problem: "fail", info: "info", unknown: "unknown" }
 
-export function renderDoctor(result, { colour = colourEnabled() } = {}) {
+/**
+ * @param {{ colour?: boolean, env?: object }} [options] `env` is where `$HOME`
+ *   is read from: a path under it is printed as `~/...` for a person, the
+ *   way a shell takes it, while the result itself, and so `--json`, keeps
+ *   every path absolute.
+ */
+export function renderDoctor(result, { colour = colourEnabled(), env = process.env } = {}) {
   const c = styler(colour)
   const out = []
   let previous = false
@@ -326,8 +333,8 @@ export function renderDoctor(result, { colour = colourEnabled() } = {}) {
     const loud = state === "fail" || state === "advisory"
     if (index > 0 && (loud || previous)) out.push("")
     out.push(`${mark(state, c)}${c("name", check.id)}`)
-    out.push(...wrap(check.detail, { indent: GUTTER }, c))
-    if (check.action) out.push(...action(check.action, c))
+    out.push(...wrap(withHomeAbbreviated(check.detail, env), { indent: GUTTER }, c))
+    if (check.action) out.push(...action(withHomeAbbreviated(check.action, env), c))
     previous = loud
   }
   out.push("")

package/tools/marketplace/setup.mjs

@@ -20,6 +20,7 @@ import { TAGLINE } from "./usage.mjs"
 import { installCompletion } from "./completion.mjs"
 import { submissionContract } from "./form.mjs"
 import { pathHint } from "./path-hint.mjs"
+import { withHomeAbbreviated } from "./paths.mjs"
 
 function version(command) {
   try {
@@ -32,16 +33,18 @@ function version(command) {
 }
 
 /**
- * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream }} options
+ * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream, env?: object }} options
+ *   `env` is where `$HOME` is read from: this is output for a person, so a
+ *   path under it is printed as `~/...`.
  */
-export async function setup({ repoRoot, entryPoint, stream = process.stdout }) {
+export async function setup({ repoRoot, entryPoint, stream = process.stdout, env = process.env }) {
   const c = styler(colourEnabled(stream))
   const out = (line = "") => stream.write(`${line}\n`)
   // A step is a status line: the mark, then the fact, wrapped under itself.
-  const step = (state, text) => out(`${mark(state, c)}${wrap(text, { indent: GUTTER }, c).join("\n").trimStart()}`)
+  const step = (state, text) => out(`${mark(state, c)}${wrap(withHomeAbbreviated(text, env), { indent: GUTTER }, c).join("\n").trimStart()}`)
   // The one action under a step sits in the step's body; under a sentence it
   // sits where the sentence does.
-  const fix = (text, indent = GUTTER) => { for (const line of action(text, c, { indent })) out(line) }
+  const fix = (text, indent = GUTTER) => { for (const line of action(withHomeAbbreviated(text, env), c, { indent })) out(line) }
 
   // The one place the wordmark runs through `ttfx` (effect.mjs): a first run
   // already spending seconds fetching the pin.

package/tools/marketplace/upgrade.mjs

@@ -59,11 +59,29 @@ export const NPM_UPGRADE_ARGS = Object.freeze(["install", "--global", "--ignore-
 
 /** The newest published version, or null when the registry did not answer. */
 export async function latestOnRegistry(name) {
+  return (await registryLatest(name)).version
+}
+
+/** The registry the newest version is read from, named in doctor's evidence. */
+export const NPM_REGISTRY = "https://registry.npmjs.org"
+
+/**
+ * The newest published version, with the reason when there is none: the
+ * failure code from the one GET call site (network-unavailable,
+ * github-unavailable's npm sibling, not-found for an unpublished name), or
+ * `unpublished` when the registry answered without a version. `doctor` prints
+ * the code; `upgrade` only needs the version.
+ *
+ * @returns {Promise<{ version: string|null, error: { code: string, message: string }|null }>}
+ */
+export async function registryLatest(name) {
   try {
-    const meta = await getJson(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`)
-    return meta?.version || null
-  } catch {
-    return null
+    const meta = await getJson(`${NPM_REGISTRY}/${encodeURIComponent(name)}/latest`)
+    return meta?.version
+      ? { version: meta.version, error: null }
+      : { version: null, error: { code: "unpublished", message: "the registry answered without a version" } }
+  } catch (error) {
+    return { version: null, error: { code: error?.code || "error", message: String(error?.message || error) } }
   }
 }