omakit 0.1.9 → 0.2.1

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"
@@ -23,13 +26,19 @@ import { validationWatch } from "./watch.mjs"
 import { renderSubmit, renderWatch, renderDoctor, renderVerify } from "./report.mjs"
 import { consequence } from "./preflight.mjs"
 import { doctor } from "./doctor.mjs"
-import { setup } from "./setup.mjs"
+import { completionStep, setup } from "./setup.mjs"
+import { staleCompletionNotice } from "./completion-check.mjs"
+import { ACCEPTED, acceptedWords, checkArgs } from "./options.mjs"
 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 { 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, renderList, renderWeigh, renderPlan } from "../weigh/report.mjs"
+import { listWeighings } from "../weigh/list.mjs"
+import { askYes } from "../weigh/confirm.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -51,6 +60,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.",
 })
 
 /**
@@ -78,8 +89,9 @@ function option(args, name) {
   return index >= 0 ? args[index + 1] : undefined
 }
 
+/** The bare arguments, with every valued option's value (options.mjs, one table) left out. */
 function positionals(args) {
-  const valued = new Set(["--profile", "--plugin", "--out", "--category", "--tags", "--notes", "--suggest-tag", "--name", "--count", "--offset"])
+  const valued = new Set(Object.values(ACCEPTED).flatMap((spec) => spec.valued))
   return args.filter((value, index) => !value.startsWith("--") && !valued.has(args[index - 1]))
 }
 
@@ -189,8 +201,16 @@ async function cmdFrontDoor() {
   process.stdout.write(renderSummary({ heading: !drew }))
 }
 
-async function cmdSetup() {
-  const result = await setup({ repoRoot: ROOT, entryPoint: resolve(ROOT, "bin/omakit") })
+async function cmdSetup(args) {
+  // `--completion` is the one step on its own: write the script and prove
+  // it in a new shell, never the rc question. `upgrade` runs it through the
+  // freshly installed omakit, so the script carries the new version.
+  if (args.includes("--completion")) {
+    const identity = requirePin(ROOT).identity
+    const result = await completionStep({ repoRoot: ROOT, pin: identity.commit, version: VERSION, askRc: false })
+    process.exit(result.state === "ok" ? 0 : 1)
+  }
+  const result = await setup({ repoRoot: ROOT, entryPoint: resolve(ROOT, "bin/omakit"), yes: args.includes("--yes") })
   process.exit(result.ok ? 0 : 1)
 }
 
@@ -273,9 +293,144 @@ async function cmdParity(args) {
   process.exit(ok ? 0 : 1)
 }
 
+/**
+ * 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, ACCEPTED.weigh)
+  if (parsed.offending !== null) notWeighed("usage", `${parsed.reason}. Accepted: ${acceptedWords("weigh")}.`, "omakit weigh <plugin-id-or-dir> [--runs N] [--window S] [--settle S] [--yes] [--json] [--out FILE], or omakit weigh --list", 2)
+  const json = parsed.options.has("--json")
+  const all = parsed.options.has("--all")
+  const target = parsed.positionals[0]
+  // --list reads and prints: every installed plugin and its last weighing.
+  // No preflight beyond listPlugins answering, no confirmation, no restart.
+  if (parsed.options.has("--list")) {
+    for (const other of ["--all", "--yes", "--runs", "--window", "--settle", "--out"]) {
+      if (parsed.options.has(other)) notWeighed("usage", `--list only lists, so ${other} has nothing to apply to.`, "omakit weigh --list [--json]", 2)
+    }
+    if (target) notWeighed("usage", `--list lists every installed plugin, so ${JSON.stringify(target)} is one argument more than it takes.`, "omakit weigh --list [--json]", 2)
+    let list
+    try {
+      list = listWeighings()
+    } catch (error) {
+      if (error?.code && typeof error.code === "string") notWeighed(error.code, `${error.message}.`, error.remedy || REMEDY[error.code])
+      throw error
+    }
+    process.stdout.write(json ? `${JSON.stringify(list.rows, null, 2)}\n` : `${renderList(list)}\n`)
+    process.exit(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)
+
+// Every token checked against the command's table before anything runs
+// (options.mjs): an option the command does not know, an option without its
+// value, or one positional too many is a usage error naming the token and
+// the accepted list. `weigh` reports it in its own register, below.
+{
+  const name = command === "marketplace-pin" ? "pin" : command
+  const table = name === "weigh" ? null : ACCEPTED[name] || ((command === "--help" || command === "-h") ? ACCEPTED.pin : null)
+  if (table) {
+    const parsed = checkArgs(rest, table)
+    if (parsed.offending !== null) {
+      const accepted = acceptedWords(name)
+      fail("usage", `${parsed.reason}.${accepted ? ` Accepted: ${accepted}.` : ` \`omakit ${name}\` takes no options.`}`, 2, "omakit help")
+    }
+  }
+}
+
+// Once a day, one dim line on stderr, only at a terminal: the installed
+// completion script names another omakit, so `omakit we<TAB>` may not know
+// `weigh`. One stat and one short read; never under a pipe, whose stderr
+// stays empty on success, and never for setup, which is the fix.
+if (command !== "setup" && process.stderr.isTTY) {
+  const notice = staleCompletionNotice({ version: VERSION })
+  if (notice) process.stderr.write(`${styler(colourEnabled(process.stderr))("label", notice)}\n`)
+}
+
 if (command === "setup") {
-  await cmdSetup()
+  await cmdSetup(rest)
 } else if (command === "pin" || command === "marketplace-pin") {
   const c = styler(colourEnabled())
   const spinner = progress()
@@ -300,9 +455,11 @@ if (command === "setup") {
 } else if (command === "watch") {
   await cmdWatch(rest)
 } else if (command === "verify") {
-  await cmdVerify(rest.filter((value, index) => value !== "marketplace" || rest[index - 1] !== "--profile"))
+  await cmdVerify(rest)
 } 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-check.mjs

@@ -0,0 +1,224 @@
+// Does tab completion actually work, and if not, what is missing.
+//
+// Measured on 15 September 2026 against an installed Omarchy (docs/
+// MEASUREMENTS.md, M8): `omakit setup` wrote the script and reported it
+// installed, and whether a new shell could complete anything was never
+// checked. On a stock Omarchy it can, because `default/bash/shell` has
+// sourced bash-completion since v1.2.0, but `complete -p omakit` in a fresh
+// shell says "no completion specification" all the same, because
+// bash-completion loads the user directory's script on the first TAB and
+// not before. So the probe here does what TAB does: an interactive shell,
+// the loader asked to load `omakit`, and then `complete -p`. Where the
+// loader is missing (a `~/.bashrc` that no longer sources Omarchy's rc, a
+// zsh without `compinit`), setup says so and asks once before it adds one
+// guarded, marked block to the rc file; that block is the only thing omakit
+// ever writes to an rc file, only after a yes, and it is never edited or
+// removed by omakit.
+//
+// The probes are frozen argument lists (tests/unit/read-only.test.mjs asserts
+// every spawn in this file uses them), run through the shell by name, so a
+// test puts a stub shell first on PATH.
+
+import { spawnSync } from "node:child_process"
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+import { completionInstall, parseCompletionHeader } from "./completion.mjs"
+import { omakitStateDir } from "./paths.mjs"
+
+/** Milliseconds an interactive shell may take to answer a probe; a hung rc file is reported, not waited for. */
+export const PROBE_TIMEOUT_MS = 10_000
+
+/**
+ * The probe per shell. Each prints `loader=yes|no` and `spec=eager|lazy|none`:
+ * whether the completion machinery is present in a new interactive shell,
+ * and whether `omakit` has a completion spec, before or after the loader
+ * has been asked for it the way TAB asks. fish has no loader to miss and
+ * autoloads from its completions directory on `complete -C`.
+ */
+export const PROBES = Object.freeze({
+  bash: Object.freeze(["-ic", [
+    "declare -F _init_completion >/dev/null 2>&1 && echo loader=yes || echo loader=no",
+    "if complete -p omakit >/dev/null 2>&1; then echo spec=eager",
+    "else _comp_load omakit >/dev/null 2>&1 || __load_completion omakit >/dev/null 2>&1 || _completion_loader omakit >/dev/null 2>&1",
+    "if complete -p omakit >/dev/null 2>&1; then echo spec=lazy; else echo spec=none; fi; fi",
+  ].join("; ")]),
+  zsh: Object.freeze(["-ic", [
+    "(( $+functions[compdef] )) && echo loader=yes || echo loader=no",
+    "if [[ -n ${_comps[omakit]-} ]]; then echo spec=eager",
+    "elif (( $+functions[compdef] )) && whence -w _omakit >/dev/null 2>&1; then echo spec=lazy",
+    "else echo spec=none; fi",
+  ].join("; ")]),
+  fish: Object.freeze(["-c", [
+    "echo loader=yes",
+    "complete -C 'omakit ' >/dev/null 2>&1",
+    "if complete -c omakit | string match -q '*omakit*'; echo spec=lazy; else; echo spec=none; end",
+  ].join("; ")]),
+})
+
+/**
+ * Ask a new interactive shell whether completion works.
+ *
+ * @param {"bash"|"zsh"|"fish"} shell
+ * @param {{ env?: NodeJS.ProcessEnv, timeoutMs?: number }} [options]
+ * @returns {{ ran: boolean, loader: boolean, spec: "eager"|"lazy"|"none", reason: string|null }}
+ */
+export function verifyCompletion(shell, { env = process.env, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  const probe = PROBES[shell]
+  if (!probe) return { ran: false, loader: false, spec: "none", reason: `no probe for ${shell}` }
+  const result = spawnSync(shell, [...probe], { encoding: "utf8", env, timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"] })
+  if (result.error) {
+    return { ran: false, loader: false, spec: "none", reason: result.error.code === "ENOENT" ? `${shell} is not on PATH` : result.error.code === "ETIMEDOUT" ? `${shell} did not answer within ${timeoutMs / 1000} s` : String(result.error.message) }
+  }
+  const out = result.stdout || ""
+  const loader = /^loader=yes$/m.test(out)
+  const spec = out.match(/^spec=(eager|lazy|none)$/m)?.[1] || "none"
+  return { ran: true, loader, spec, reason: null }
+}
+
+/** The marker every block starts with; its presence is what makes a second run append nothing. */
+export const RC_MARKER = "# omakit completion"
+
+/**
+ * The guarded lines that make completion load, per shell, and the rc file
+ * they belong in: bash sources the system bash-completion if it is there;
+ * zsh puts `~/.zfunc` on fpath and runs compinit. fish needs nothing.
+ *
+ * @returns {{ file: string, display: string, lines: string[] } | null}
+ */
+export function loaderBlock(shell, env = process.env) {
+  const home = env.HOME || ""
+  if (shell === "bash") {
+    return {
+      file: join(home, ".bashrc"),
+      display: "~/.bashrc",
+      lines: [RC_MARKER, "[[ -r /usr/share/bash-completion/bash_completion ]] && source /usr/share/bash-completion/bash_completion"],
+    }
+  }
+  if (shell === "zsh") {
+    const dir = env.ZDOTDIR || home
+    return {
+      file: join(dir, ".zshrc"),
+      display: env.ZDOTDIR ? `${env.ZDOTDIR}/.zshrc` : "~/.zshrc",
+      lines: [RC_MARKER, "fpath+=~/.zfunc", "autoload -Uz compinit && compinit"],
+    }
+  }
+  return null
+}
+
+/** Is the marked block already in the rc file. */
+export function loaderBlockPresent(shell, env = process.env) {
+  const block = loaderBlock(shell, env)
+  if (!block) return false
+  try {
+    return readFileSync(block.file, "utf8").split("\n").some((line) => line.trim() === RC_MARKER)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Append the marked block to the rc file, once. The only write omakit ever
+ * makes to an rc file, and only after `setup` was answered yes: the marker
+ * is looked for first, and a file that has it is left exactly as it is.
+ *
+ * @returns {{ appended: boolean, file: string }}
+ */
+export function appendLoaderBlock(shell, env = process.env) {
+  const block = loaderBlock(shell, env)
+  if (!block) throw new Error(`completion: no loader block for ${shell}`)
+  if (loaderBlockPresent(shell, env)) return { appended: false, file: block.file }
+  let existing = ""
+  try {
+    existing = readFileSync(block.file, "utf8")
+  } catch {
+    existing = ""
+  }
+  mkdirSync(dirname(block.file), { recursive: true })
+  const rcFile = block.file
+  appendFileSync(rcFile, `${existing && !existing.endsWith("\n") ? "\n" : ""}${existing ? "\n" : ""}${block.lines.join("\n")}\n`)
+  return { appended: true, file: block.file }
+}
+
+/**
+ * The installed script's header, read cheaply: one stat, one read of the
+ * first 200 bytes. Null when there is no script for the shell in $SHELL.
+ *
+ * @returns {{ path: string, shell: string, version: string|null, pin: string|null } | null}
+ */
+export function installedCompletion(env = process.env) {
+  const target = completionInstall(env)
+  if (!target) return null
+  let head = ""
+  try {
+    statSync(target.path)
+    const fd = openSync(target.path, "r")
+    try {
+      const buffer = Buffer.alloc(200)
+      const read = readSync(fd, buffer, 0, 200, 0)
+      head = buffer.toString("utf8", 0, read)
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return null
+  }
+  return { path: target.path, shell: target.shell, ...parseCompletionHeader(head) }
+}
+
+/**
+ * Everything `omakit doctor` says under `omakit.completion`: the script,
+ * its version and pin against this omakit's, the loader, and the spec in a
+ * new shell.
+ *
+ * @param {{ version: string, pin: string, env?: NodeJS.ProcessEnv }} options
+ */
+export function completionStatus({ version, pin, env = process.env }) {
+  const shell = basename(env.SHELL || "")
+  const target = completionInstall(env)
+  if (!target) return { state: "info", shell: shell || null, detail: shell ? `no completion script for ${shell}; there is one for bash, zsh and fish` : "$SHELL is not set, so no completion script is installed", action: null, evidence: { shell: shell || null } }
+  const installed = installedCompletion(env)
+  const evidence = { shell: target.shell, path: target.path, present: Boolean(installed), version: installed?.version ?? null, pin: installed?.pin ?? null, loader: null, spec: null }
+  if (!installed) return { state: "advice", shell: target.shell, detail: `no completion script at ${target.display}`, action: "omakit setup", evidence }
+  const probe = verifyCompletion(target.shell, { env })
+  evidence.loader = probe.ran ? probe.loader : null
+  evidence.spec = probe.ran ? probe.spec : null
+  const identity = `${target.display}, omakit ${installed.version || "unknown"}, pin ${installed.pin ? installed.pin.slice(0, 7) : "unknown"}`
+  if (installed.version !== version || installed.pin !== pin) {
+    return { state: "advice", shell: target.shell, detail: `${identity}; this omakit is ${version} at pin ${pin.slice(0, 7)}, so the script is stale`, action: "omakit setup", evidence }
+  }
+  if (!probe.ran) return { state: "unknown", shell: target.shell, detail: `${identity}; a new ${target.shell} could not be asked: ${probe.reason}`, action: null, evidence }
+  if (!probe.loader) return { state: "advice", shell: target.shell, detail: `${identity}; a new ${target.shell} has no completion loader, so the script is never read`, action: "omakit setup", evidence }
+  if (probe.spec === "none") return { state: "advice", shell: target.shell, detail: `${identity}; the loader is there but a new ${target.shell} does not load the script`, action: "omakit setup", evidence }
+  return { state: "ok", shell: target.shell, detail: `${identity}; loader active, \`complete -p omakit\` seen in a new ${target.shell}${probe.spec === "lazy" ? " after the loader was asked, the way TAB asks" : ""}`, action: null, evidence }
+}
+
+/**
+ * At startup, once a day: is the installed script from another omakit. One
+ * stat and one short read, no pin read, and a stamp file so the line is
+ * printed once per day and not once per command.
+ *
+ * @param {{ version: string, env?: NodeJS.ProcessEnv, today?: string }} options
+ * @returns {string|null} the line to print, or null
+ */
+export function staleCompletionNotice({ version, env = process.env, today = new Date().toISOString().slice(0, 10) }) {
+  const installed = installedCompletion(env)
+  if (!installed || installed.version === version) return null
+  const stampFile = join(omakitStateDir("", env), "completion-noticed")
+  try {
+    if (readFileSync(stampFile, "utf8").trim() === today) return null
+  } catch {
+    // No stamp yet: the first notice.
+  }
+  try {
+    mkdirSync(dirname(stampFile), { recursive: true })
+    writeFileSync(stampFile, `${today}\n`)
+  } catch {
+    // A stamp that cannot be written costs one line a command, nothing else.
+  }
+  return `tab completion is from ${installed.version || "an older omakit"}; run omakit setup`
+}
+
+/** Whether a probe result means completion works: a spec seen, eagerly or after the loader was asked. */
+export function completionWorks(probe) {
+  return probe.ran && probe.loader && probe.spec !== "none"
+}