omakit 0.1.8 → 0.2.0

package/tools/marketplace/cli.mjs

@@ -6,10 +6,13 @@
 //   omakit watch <issue-url>         is this submission's validated commit still current?
 //   omakit verify <target>           the official baseline over the local transport, verbatim
 //   omakit parity [--count n]        prove the local transport equals the GitHub transport
+//   omakit weigh <plugin> | --all     what a plugin weighs on the shell, measured by restarting it
 //
 // Nothing here writes to the marketplace. There is no POST, PATCH, PUT or
 // DELETE anywhere in this repository, and `tests/unit/read-only.test.mjs`
-// proves it.
+// proves it. `weigh` is the one command that changes the user's own machine,
+// their shell and its configuration for the duration of a measurement, and
+// it confirms first; docs/WEIGH.md says what it writes and how it restores.
 
 import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
 import { dirname, resolve } from "node:path"
@@ -28,8 +31,11 @@ import { upgrade } from "./upgrade.mjs"
 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 { action, colourEnabled, GUTTER, labelled, mark, styler, verdict, wrap } from "./style.mjs"
+import { omakitCacheDir, withHomeAbbreviated } from "./paths.mjs"
+import { DEFAULTS as WEIGH_DEFAULTS, measureWeigh, planWeigh } from "../weigh/audit.mjs"
+import { confirmationQuestion, renderWeigh, renderPlan } from "../weigh/report.mjs"
+import { askYes } from "../weigh/confirm.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -51,6 +57,8 @@ const REMEDY = Object.freeze({
   "github-unavailable": "Wait for GitHub, then run it again. `gh auth login` raises the rate limit if that is what ran out.",
   "not-found": "Check the issue URL: it has to be an existing issue on the marketplace repository.",
   "head-unreadable": "Check that the plugin repository is public and its URL is right.",
+  "not-confirmed": "Run it again and answer y, or pass --yes when the person whose shell it is has agreed.",
+  "interrupted": "shell.json was restored; run it again when the desktop is yours to restart.",
 })
 
 /**
@@ -79,7 +87,7 @@ function option(args, name) {
 }
 
 function positionals(args) {
-  const valued = new Set(["--profile", "--plugin", "--out", "--category", "--tags", "--notes", "--suggest-tag", "--name", "--count", "--offset"])
+  const valued = new Set(["--profile", "--plugin", "--out", "--category", "--tags", "--notes", "--suggest-tag", "--name", "--count", "--offset", "--runs", "--window", "--settle"])
   return args.filter((value, index) => !value.startsWith("--") && !valued.has(args[index - 1]))
 }
 
@@ -273,6 +281,140 @@ async function cmdParity(args) {
   process.exit(ok ? 0 : 1)
 }
 
+/**
+ * Strict argument checking for one command: every token is a known option
+ * (valued or not), the value of a valued option, or a positional up to
+ * the allowed count. Anything else is returned as the offending token, so
+ * the command refuses before any preflight instead of running with the
+ * defaults as if nothing had been passed (measured: `weigh <plugin> -n 1`
+ * ran three runs). `--name=value` is accepted for a valued option. Used by
+ * weigh; the other commands still read their flags one by one (see
+ * CONTRIBUTING.md, "Debts").
+ *
+ * @param {string[]} args
+ * @param {{ valued: string[], flags: string[], positionals: number }} spec
+ * @returns {{ offending: string|null, reason: string|null, options: Map<string, string|true>, positionals: string[] }}
+ */
+function checkArgs(args, spec) {
+  const options = new Map()
+  const positionals = []
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index]
+    const [name, inline] = token.startsWith("--") && token.includes("=") ? [token.slice(0, token.indexOf("=")), token.slice(token.indexOf("=") + 1)] : [token, undefined]
+    if (spec.valued.includes(name)) {
+      const value = inline !== undefined ? inline : args[index + 1]
+      if (value === undefined || (inline === undefined && value.startsWith("-"))) return { offending: token, reason: `${name} needs a value`, options, positionals }
+      options.set(name, value)
+      if (inline === undefined) index += 1
+    } else if (spec.flags.includes(token)) {
+      options.set(token, true)
+    } else if (token.startsWith("-")) {
+      return { offending: token, reason: `${token} is not an option this command knows`, options, positionals }
+    } else if (positionals.length < spec.positionals) {
+      positionals.push(token)
+    } else {
+      return { offending: token, reason: `${JSON.stringify(token)} is one argument more than the command takes`, options, positionals }
+    }
+  }
+  return { offending: null, reason: null, options, positionals }
+}
+
+/** What `weigh` accepts, in the words the refusal prints. */
+const WEIGH_ARGS = Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--json", "--yes"], positionals: 1 })
+const WEIGH_ACCEPTED = "--runs N, --window S, --settle S, --all, --json, --out FILE, --yes"
+
+/**
+ * Every way `weigh` stops without weighing, in one register: the closing
+ * word a report would have ended with, negated, then the sentence naming
+ * what is missing, then the one thing to do. Exit 2 for a usage error and
+ * an unanswered confirmation, 130 for an interrupt, 1 for the rest.
+ */
+function notWeighed(code, message, remedy, exit = 1) {
+  const c = styler(colourEnabled(process.stderr))
+  const lines = verdict("fail", "NOT WEIGHED", message, c)
+  if (remedy) lines.push(...action(remedy, c, { indent: 0 }))
+  process.stderr.write(`${lines.join("\n")}\n`)
+  process.exit(exit)
+}
+
+async function cmdWeigh(args) {
+  // Every token is checked before anything else: an option weigh does not
+  // know, or a second positional, is refused with the accepted list.
+  const parsed = checkArgs(args, WEIGH_ARGS)
+  if (parsed.offending !== null) notWeighed("usage", `${parsed.reason}. Accepted: ${WEIGH_ACCEPTED}.`, "omakit weigh <plugin-id-or-dir> [--runs N] [--window S] [--settle S] [--yes] [--json] [--out FILE]", 2)
+  const json = parsed.options.has("--json")
+  const all = parsed.options.has("--all")
+  const target = parsed.positionals[0]
+  if (!target && !all) notWeighed("usage", "weigh needs a plugin: `omakit weigh <plugin-id-or-dir>`, or `omakit weigh --all` for every enabled third-party plugin.", "omakit weigh <plugin-id-or-dir>", 2)
+  if (target && all) notWeighed("usage", `--all weighs every enabled third-party plugin, so ${JSON.stringify(target)} is one argument more than it takes.`, "omakit weigh --all, or omakit weigh <plugin-id-or-dir>", 2)
+  const integer = (name, fallback, letter, min = 1) => {
+    if (!parsed.options.has(name)) return fallback
+    const raw = parsed.options.get(name)
+    if (!/^\d+$/.test(raw) || Number(raw) < min) notWeighed("usage", `${name} needs an integer of at least ${min}, not ${JSON.stringify(raw)}.`, `omakit weigh <plugin-id-or-dir> ${name} ${letter}`, 2)
+    return Number(raw)
+  }
+  const runs = integer("--runs", WEIGH_DEFAULTS.runs, "N")
+  const windowSeconds = integer("--window", WEIGH_DEFAULTS.windowSeconds, "S")
+  const settleSeconds = integer("--settle", WEIGH_DEFAULTS.settleSeconds, "S", 0)
+  let plan
+  try {
+    plan = planWeigh({ target, all, runs, windowSeconds, settleSeconds, out: parsed.options.get("--out") })
+  } catch (error) {
+    if (error?.code && typeof error.code === "string") notWeighed(error.code, `${error.message}.`, error.remedy || REMEDY[error.code], error.code === "usage" ? 2 : 1)
+    throw error
+  }
+  // The narration: what was backed up and with which md5, and what was
+  // restored. For a person it is part of the report, on stdout; under
+  // --json stdout is the document alone, so it goes to stderr.
+  const narrate = json ? process.stderr : process.stdout
+  const c = styler(colourEnabled(narrate))
+  const say = (line) => narrate.write(`${mark(line.state, c)}${wrap(withHomeAbbreviated(line.text), { indent: GUTTER }, c).join("\n").trimStart()}\n`)
+  // The confirmation. The plan is printed either way, so the record says
+  // what was agreed to; the question is asked only at a terminal on both
+  // ends, and --yes is the only other way past it.
+  narrate.write(`${renderPlan(plan, { colour: colourEnabled(narrate) }).join("\n")}\n`)
+  if (!parsed.options.has("--yes")) {
+    const interactive = !json && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)
+    if (!interactive) notWeighed("not-confirmed", `this restarts the shell ${plan.restarts} times and edits shell.json for the duration; a pipe, an agent or --json cannot answer for the person whose shell it is.`, REMEDY["not-confirmed"], 2)
+    const agreed = await askYes({ question: confirmationQuestion(plan) })
+    if (!agreed) notWeighed("not-confirmed", "not confirmed; nothing was changed.", REMEDY["not-confirmed"], 2)
+  }
+  narrate.write("\n")
+  // An interrupt is a request to stop, not a reason to leave the user's
+  // shell on a measurement configuration: the signal aborts the run, the
+  // measurement's own finally restores shell.json and restarts the shell,
+  // and only then does the process exit, 130 as an interrupted program does.
+  const controller = new AbortController()
+  const interrupt = () => {
+    if (!controller.signal.aborted) narrate.write(`\n${mark("advisory", c)}interrupted: restoring shell.json before exiting\n`)
+    controller.abort()
+  }
+  process.on("SIGINT", interrupt)
+  process.on("SIGTERM", interrupt)
+  const spinner = spinnerFor(args)
+  let document
+  try {
+    document = await measureWeigh(plan, { signal: controller.signal, omakitVersion: VERSION, onPhase: spinner.phase, onLine: (line) => { spinner.done(); say(line) } })
+  } catch (error) {
+    spinner.done()
+    if (error?.code === "interrupted") notWeighed("interrupted", "interrupted before the measurement completed.", REMEDY.interrupted, 130)
+    if (error?.code && typeof error.code === "string") notWeighed(error.code, `${error.message}.`, error.remedy || REMEDY[error.code])
+    throw error
+  } finally {
+    process.off("SIGINT", interrupt)
+    process.off("SIGTERM", interrupt)
+  }
+  spinner.done()
+  if (json) {
+    process.stdout.write(`${JSON.stringify(document, null, 2)}\n`)
+  } else {
+    process.stdout.write(`\n${renderWeigh(document)}\n`)
+  }
+  process.exit(0)
+}
+
+const VERSION = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8")).version
+
 const [command, ...rest] = process.argv.slice(2)
 if (command === "setup") {
   await cmdSetup()
@@ -284,7 +426,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()
@@ -303,6 +445,8 @@ if (command === "setup") {
   await cmdVerify(rest.filter((value, index) => value !== "marketplace" || rest[index - 1] !== "--profile"))
 } else if (command === "parity") {
   await cmdParity(rest)
+} else if (command === "weigh") {
+  await cmdWeigh(rest)
 } else if (command === "help" || command === "--help" || command === "-h" || command === undefined) {
   if (rest.includes("--agent")) {
     // The skills ship in the npm package, so this works from a global install

package/tools/marketplace/completion.mjs

@@ -13,12 +13,13 @@ 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
  * after `omakit` in its signature; a flag is every `--word` in it, valued when
- * a `<placeholder>` follows it; `<target>` in the signature means the first
- * positional is a directory.
+ * a `<placeholder>` follows it; `<target>` or `<plugin-id-or-dir>` in the
+ * signature means the first positional can be a directory.
  *
  * @param {ReadonlyArray<{ signature: string|string[], lines: string[] }>} commands
  */
@@ -32,7 +33,7 @@ export function subcommandsOf(commands = COMMANDS) {
       value: placeholder ? placeholderKind(placeholder) : null,
     }))
     const sentence = command.lines.join(" ").replace(/`/g, "").split(/(?<=\.)\s/)[0]
-    return { name, description: sentence, flags, target: /<target>/.test(signature) }
+    return { name, description: sentence, flags, target: /<target>|<plugin-id-or-dir>/.test(signature) }
   })
 }
 
@@ -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,34 @@ export function omakitCacheDir(name = "", env = process.env) {
     : join(env.HOME || homedir(), ".cache")
   return join(base, "omakit", name)
 }
+
+/**
+ * Omakit's user-writable state, following XDG with the usual ~/.local/state
+ * fallback: where `omakit weigh` keeps its documents and its per-restart
+ * timing. State, not cache, because a measurement is not something to
+ * fetch again.
+ */
+export function omakitStateDir(name = "", env = process.env) {
+  const base = env.XDG_STATE_HOME
+    ? resolve(env.XDG_STATE_HOME)
+    : join(env.HOME || homedir(), ".local/state")
+  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)
 
@@ -34,9 +35,10 @@ function stateOf(check) {
 /**
  * A check's head line: the mark, the id in bold, and the source in brackets
  * pushed to the right edge, so the sources form a column of their own and the
- * ids form another.
+ * ids form another. Exported for the weigh report, whose rows are plugins
+ * with their kinds where a check has its source.
  */
-function head(state, id, source, c) {
+export function head(state, id, source, c) {
   const left = `${mark(state, c)}${c("name", id)}`
   const tag = c("punctuation", `[${source}]`)
   const gap = Math.max(2, COLUMNS - width(left) - width(tag))
@@ -317,7 +319,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 +334,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) } }
   }
 }
 

package/tools/marketplace/usage.mjs

@@ -99,6 +99,27 @@ export const COMMANDS = Object.freeze([
       "listed repositories; a packaged install requires --out for evidence.",
     ],
   },
+  {
+    signature: [
+      "omakit weigh <plugin-id-or-dir> [--runs <n>] [--window <s>] [--settle <s>]",
+      "                    [--yes] [--json] [--out <file>]",
+      "omakit weigh --all",
+    ],
+    lines: [
+      "What a plugin weighs on the shell, measured: the shell is restarted",
+      "without it and with it, several runs, and the difference is the weight,",
+      "with the baseline's own spread as the noise floor; memory is printed as",
+      "the shell's own startup variance, CPU and child processes as the weight.",
+      "The one command that changes your machine: it edits shell.json for the",
+      "duration, backs it up first, restores it on every exit path, and asks",
+      "before the first restart (--yes answers for you): about a minute per",
+      "restart, six restarts for one plugin at three runs. --all weighs every",
+      "enabled third-party plugin and is sized for a lab machine, not a working",
+      "desktop. Writes the document to --out, by default",
+      "$XDG_STATE_HOME/omakit/weigh/<date>.json, and ends with the sentence",
+      "for the plugin's README.",
+    ],
+  },
 ])
 
 // A command sits one STEP in from the heading; what it does sits one STEP in