omakit 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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 against the marketplace, posts nothing, zero dependencies.",
   "license": "MIT",
   "author": "Maarten Tolhuijs",

package/tools/marketplace/README.md

@@ -28,7 +28,9 @@ local commit through the transport seam the marketplace tests itself
 | `report.mjs` | Text rendering of submit, watch, doctor and verify for the agent that runs this tool, and the person reading over its shoulder. |
 | `path-hint.mjs` | Is `omakit` reachable as a bare command, and if not, the one line that makes it so for the install that is here: a symlink for a clone, the npm prefix's `bin` on PATH for a package, said for the shell in `$SHELL`. `setup` and `doctor` print it; nothing writes an rc file. |
 | `usage.mjs` | The help text, as data. |
+| `options.mjs` | Every option every command accepts, in one table, and the parser that reads a command line against it before anything runs; `tests/unit/options.test.mjs` holds the help signatures, and through them the completion scripts, to the table. |
 | `completion.mjs` | A completion script for bash, zsh or fish, derived from the help data and the pin's form: the subcommands and flags are read out of `COMMANDS`, the categories and tags out of the pinned submission form, and the script says which pin it came from. `setup` installs it for the shell in `$SHELL`, the one file this tool writes outside its own checkout. |
+| `completion-check.mjs` | Whether tab completion actually works: a frozen probe per shell run interactively, asking the loader to load `omakit` the way TAB does; the one marked block `setup` may append to an rc file after a yes, looked for by its marker first; the installed script's version and pin read from its first line; `doctor`'s `omakit.completion`; and the once-a-day stale notice. |
 | `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. |
@@ -46,6 +48,7 @@ machine (docs/WEIGH.md):
 | `weigh/stats.mjs` | Median, spread, the stats object, and the within-noise comparison. |
 | `weigh/audit.mjs` | `planWeigh()` reads and decides (what runs, how many restarts, the estimate) and writes nothing; `measureWeigh()` restarts, samples and restores in a `finally`; `buildDocument()` turns the samples into the document. |
 | `weigh/contract.mjs` | The JSON contract of docs/WEIGH.md as a validator, run by the unit tests and by the lab over a real document. |
+| `weigh/list.mjs` | `weigh --list`: every installed plugin with its last weighing from the documents under the state directory, read-only, unweighed enabled plugins first. |
 | `weigh/report.mjs` | The confirmation and the report for a person, drawn with `style.mjs`; the README sentence and the evidence path come last. |
 | `weigh/confirm.mjs` | The one question, at a terminal, on stderr. |
 

package/tools/marketplace/cli.mjs

@@ -26,7 +26,9 @@ 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"
@@ -34,7 +36,8 @@ import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.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 { 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)), "../..")
@@ -86,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", "--runs", "--window", "--settle"])
+  const valued = new Set(Object.values(ACCEPTED).flatMap((spec) => spec.valued))
   return args.filter((value, index) => !value.startsWith("--") && !valued.has(args[index - 1]))
 }
 
@@ -197,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)
 }
 
@@ -281,48 +293,6 @@ 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
@@ -340,11 +310,28 @@ function notWeighed(code, message, remedy, exit = 1) {
 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 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) => {
@@ -416,8 +403,34 @@ async function cmdWeigh(args) {
 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()
@@ -442,7 +455,7 @@ 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") {

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"
+}

package/tools/marketplace/completion.mjs

@@ -28,15 +28,36 @@ export function subcommandsOf(commands = COMMANDS) {
     const signature = [].concat(command.signature).join(" ")
     const name = signature.match(/^omakit +([a-z][a-z-]*)/)?.[1]
     if (!name) throw new Error(`completion: no subcommand in signature ${JSON.stringify(signature)}`)
-    const flags = [...signature.matchAll(/(--[a-z][a-z-]*)(?: <([^>]+)>)?/g)].map(([, flag, placeholder]) => ({
-      flag,
-      value: placeholder ? placeholderKind(placeholder) : null,
-    }))
+    // A flag named on two signature lines (`--json` on weigh's main line and
+    // on its `--list` line) is one flag.
+    const seen = new Set()
+    const flags = [...signature.matchAll(/(--[a-z][a-z-]*)(?: <([^>]+)>)?/g)]
+      .filter(([, flag]) => !seen.has(flag) && seen.add(flag))
+      .map(([, flag, placeholder]) => ({
+        flag,
+        value: placeholder ? placeholderKind(placeholder) : null,
+      }))
     const sentence = command.lines.join(" ").replace(/`/g, "").split(/(?<=\.)\s/)[0]
-    return { name, description: sentence, flags, target: /<target>|<plugin-id-or-dir>/.test(signature) }
+    // `<target>` completes as a directory; `<plugin-id-or-dir>` as the ids
+    // the running shell has installed, read at TAB time, with a directory
+    // as the fallback.
+    const target = /<plugin-id-or-dir>/.test(signature) ? "plugin" : /<target>/.test(signature) ? "directory" : false
+    return { name, description: sentence, flags, target }
   })
 }
 
+/**
+ * The plugin ids a TAB offers for `omakit weigh <TAB>`: what the running
+ * shell reports through `omarchy-shell shell listPlugins`, filtered with
+ * `jq` at TAB time, enabled ids first and whole bars left out, since a bar
+ * cannot be weighed. No node process behind the TAB: a shell that does not
+ * answer within a second yields nothing, and the script falls back to a
+ * directory. The pipeline is the same in every shell's script and the jq
+ * expression is exported so a test can run it through jq.
+ */
+export const PLUGIN_IDS_JQ = "[.[] | select(((.kinds // []) | index(\"bar\")) | not)] | sort_by(.enabled | not) | .[].id"
+export const PLUGIN_IDS_COMMAND = `timeout 1 omarchy-shell shell listPlugins 2>/dev/null | jq -r '${PLUGIN_IDS_JQ}' 2>/dev/null`
+
 /** What a valued flag takes, by its placeholder: a controlled value, a file, or free text. */
 function placeholderKind(placeholder) {
   if (placeholder === "c") return "category"
@@ -50,32 +71,59 @@ function placeholderKind(placeholder) {
  * @param {{ contract: { categories: string[], tagLabels: string[] }, pin: string, commands?: typeof COMMANDS }} options
  * @returns {string} the script
  */
-export function renderCompletion(shell, { contract, pin, commands = COMMANDS }) {
+export function renderCompletion(shell, { contract, pin, version = "unknown", commands = COMMANDS }) {
   if (!COMPLETION_SHELLS.includes(shell)) throw new Error(`completion: no script for ${shell}`)
   const model = {
     subcommands: subcommandsOf(commands),
     categories: [...contract.categories],
     tags: contract.tagLabels.map(tagSlug),
     pin,
+    version,
   }
   return { bash, zsh, fish }[shell](model)
 }
 
-function header(comment, shell, pin) {
+/**
+ * The first line of every script names the omakit version and the pin it
+ * was rendered from, in one line, so the run-time staleness check
+ * (completion-check.mjs) reads one line and nothing else. The pin is what
+ * decides the categories and tags; the version is what decides the
+ * subcommands and flags, and a script from 0.1.9 knows no `weigh`.
+ */
+function header(comment, shell, pin, version) {
   return [
-    `${comment} omakit completion for ${shell}. Generated by \`omakit setup\` from`,
-    `${comment} marketplace pin ${pin}; the categories and tags`,
-    `${comment} below are that pin's submission form. Regenerate it by running setup`,
-    `${comment} again.`,
+    `${comment} omakit completion for ${shell}, omakit ${version}, marketplace pin ${pin}.`,
+    `${comment} Generated by \`omakit setup\`; the categories and tags below are that pin's`,
+    `${comment} submission form and the commands are that version's. Regenerate it by`,
+    `${comment} running setup again.`,
   ]
 }
 
+/**
+ * The version and the pin a script names, from its first line (its second
+ * for zsh, under `#compdef`), or null when
+ * the line is not one omakit wrote (a script from before the version was
+ * recorded reads as version null and its pin from the old header).
+ *
+ * @param {string} text the first two lines are enough
+ * @returns {{ shell: string|null, version: string|null, pin: string|null }}
+ */
+export function parseCompletionHeader(text) {
+  // zsh's script starts with its `#compdef` line; the header is the next.
+  const lines = String(text).split("\n", 2)
+  const line = lines[0].startsWith("#compdef") ? lines[1] || "" : lines[0]
+  const current = line.match(/^# omakit completion for (\w+), omakit (\S+), marketplace pin ([0-9a-f]{40})\.$/)
+  if (current) return { shell: current[1], version: current[2], pin: current[3] }
+  const older = line.match(/^#\s*omakit completion for (\w+)\./)
+  return { shell: older ? older[1] : null, version: null, pin: null }
+}
+
 const single = (text) => `'${String(text).replace(/'/g, "'\\''")}'`
 
 // --- bash ---------------------------------------------------------------------
 
-function bash({ subcommands, categories, tags, pin }) {
-  const lines = [...header("#", "bash", pin), ""]
+function bash({ subcommands, categories, tags, pin, version }) {
+  const lines = [...header("#", "bash", pin, version), ""]
   lines.push("_omakit() {")
   lines.push("  local cur prev command")
   lines.push("  cur=${COMP_WORDS[COMP_CWORD]}")
@@ -109,7 +157,12 @@ function bash({ subcommands, categories, tags, pin }) {
       lines.push("      return")
       lines.push("    fi")
     }
-    if (sub.target) {
+    if (sub.target === "plugin") {
+      lines.push('    if ((COMP_CWORD == 2)); then')
+      lines.push('      COMPREPLY=($(compgen -W "$(_omakit_plugin_ids)" -- "$cur"))')
+      lines.push('      if ((${#COMPREPLY[@]} == 0)); then COMPREPLY=($(compgen -d -- "$cur")); compopt -o filenames 2>/dev/null; fi')
+      lines.push("    fi")
+    } else if (sub.target) {
       lines.push('    COMPREPLY=($(compgen -d -- "$cur"))')
       lines.push("    compopt -o filenames 2>/dev/null")
     }
@@ -118,6 +171,13 @@ function bash({ subcommands, categories, tags, pin }) {
   lines.push("  esac")
   lines.push("}")
   lines.push("")
+  lines.push("# The plugin ids the running shell has installed, enabled first, whole bars")
+  lines.push("# left out, read at TAB time; nothing when the shell does not answer in a")
+  lines.push("# second, and the caller falls back to a directory.")
+  lines.push("_omakit_plugin_ids() {")
+  lines.push(`  ${PLUGIN_IDS_COMMAND}`)
+  lines.push("}")
+  lines.push("")
   lines.push("# A controlled value may contain a space, so each match is one line and is")
   lines.push("# escaped on the way out, the way the shell would have to type it.")
   lines.push("_omakit_values() {")
@@ -142,8 +202,8 @@ function bash({ subcommands, categories, tags, pin }) {
 
 const zshDescribe = (name, description) => single(`${name}:${description.replace(/:/g, "\\:")}`)
 
-function zsh({ subcommands, categories, tags, pin }) {
-  const lines = ["#compdef omakit", ...header("#", "zsh", pin), ""]
+function zsh({ subcommands, categories, tags, pin, version }) {
+  const lines = ["#compdef omakit", ...header("#", "zsh", pin, version), ""]
   lines.push("_omakit() {")
   lines.push("  local curcontext=\"$curcontext\" state line")
   lines.push("  typeset -A opt_args")
@@ -169,7 +229,8 @@ function zsh({ subcommands, categories, tags, pin }) {
       if (value === "text") return single(`${flag}:text:`)
       return single(flag)
     })
-    if (sub.target) specs.push(single("1:target:_directories"))
+    if (sub.target === "plugin") specs.push(single("1:plugin:_omakit_plugins"))
+    else if (sub.target) specs.push(single("1:target:_directories"))
     if (specs.length) lines.push(`      _arguments ${specs.join(" ")}`)
     lines.push("      ;;")
   }
@@ -178,6 +239,14 @@ function zsh({ subcommands, categories, tags, pin }) {
   lines.push("  esac")
   lines.push("}")
   lines.push("")
+  lines.push("# The plugin ids the running shell has installed, enabled first, whole bars")
+  lines.push("# left out, read at TAB time; a directory when the shell does not answer.")
+  lines.push("_omakit_plugins() {")
+  lines.push("  local -a ids")
+  lines.push(`  ids=(\${(f)"$(${PLUGIN_IDS_COMMAND})"})`)
+  lines.push("  if (( ${#ids} )); then compadd -a ids; else _directories; fi")
+  lines.push("}")
+  lines.push("")
   lines.push('_omakit "$@"')
   return `${lines.join("\n")}\n`
 }
@@ -186,14 +255,23 @@ function zsh({ subcommands, categories, tags, pin }) {
 
 const fishWord = (text) => String(text).replace(/([\\'" ])/g, "\\$1")
 
-function fish({ subcommands, categories, tags, pin }) {
-  const lines = [...header("#", "fish", pin), ""]
+function fish({ subcommands, categories, tags, pin, version }) {
+  const lines = [...header("#", "fish", pin, version), ""]
   lines.push("complete -c omakit -f")
+  lines.push("")
+  lines.push("# The plugin ids the running shell has installed, enabled first, whole bars")
+  lines.push("# left out, read at TAB time; nothing when the shell does not answer, and")
+  lines.push("# the directories offered beside them stand.")
+  lines.push("function __omakit_plugin_ids")
+  lines.push(`  ${PLUGIN_IDS_COMMAND}`)
+  lines.push("end")
+  lines.push("")
   for (const sub of subcommands) {
     lines.push(`complete -c omakit -n __fish_use_subcommand -a ${sub.name} -d ${single(sub.description)}`)
   }
   for (const sub of subcommands) {
     const when = `-n ${single(`__fish_seen_subcommand_from ${sub.name}`)}`
+    if (sub.target === "plugin") lines.push(`complete -c omakit ${when} -a '(__omakit_plugin_ids)'`)
     if (sub.target) lines.push(`complete -c omakit ${when} -a '(__fish_complete_directories)'`)
     for (const { flag, value } of sub.flags) {
       const long = `-l ${flag.slice(2)}`
@@ -243,13 +321,13 @@ export function completionInstall(env = process.env) {
  * the completion script at the path `completionInstall` names, and
  * tests/unit/self-containment.test.mjs holds it to that.
  *
- * @param {{ contract: { categories: string[], tagLabels: string[] }, pin: string, env?: NodeJS.ProcessEnv }} options
- * @returns {{ state: "installed"|"updated"|"current"|"unsupported", shell: string|null, display: string|null, note: string|null }}
+ * @param {{ contract: { categories: string[], tagLabels: string[] }, pin: string, version?: string, env?: NodeJS.ProcessEnv }} options
+ * @returns {{ state: "installed"|"updated"|"current"|"unsupported", shell: string|null, display: string|null, note: string|null, path?: string }}
  */
-export function installCompletion({ contract, pin, env = process.env }) {
+export function installCompletion({ contract, pin, version = "unknown", env = process.env }) {
   const target = completionInstall(env)
   if (!target) return { state: "unsupported", shell: basename(env.SHELL || "") || null, display: null, note: null }
-  const script = renderCompletion(target.shell, { contract, pin })
+  const script = renderCompletion(target.shell, { contract, pin, version })
   let existing = null
   try {
     existing = readFileSync(target.path, "utf8")

package/tools/marketplace/doctor.mjs

@@ -44,6 +44,7 @@ import { LIVE_PATHS } from "./registry.mjs"
 import { credential, defaultBranchHead, getJson, UNAUTHENTICATED_LIMIT, GitHubError } from "./github.mjs"
 import { NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
 import { pathHint } from "./path-hint.mjs"
+import { completionStatus } from "./completion-check.mjs"
 
 /** "git+https://github.com/owner/name.git" in package.json -> "https://github.com/owner/name", or null. */
 function repositoryPage(repository) {
@@ -52,7 +53,7 @@ function repositoryPage(repository) {
   return match ? `https://github.com/${match[1]}/${match[2]}` : null
 }
 
-function tool(repoRoot) {
+export 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, repository: repositoryPage(pkg.repository) }
@@ -224,6 +225,13 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
       : `${reach.reason}${reach.where ? ` Keep the line below in ${reach.where}.` : ""}`,
     reach.reachable ? null : reach.line)
 
+  // Tab completion, as it is and not as it was written: the script, its
+  // omakit version and pin against this one's, and a new shell asked
+  // whether it loads (completion-check.mjs). Measured before this (M8):
+  // setup reported success for a script no shell was ever asked about.
+  const completion = completionStatus({ version: self.version, pin: MARKETPLACE_PIN.commit, env })
+  add("omakit.completion", completion.state, completion.detail, completion.action, completion.evidence)
+
   const node = process.versions.node
   const major = Number(node.split(".")[0])
   add("node", major >= 22 ? "ok" : "problem", `node ${node}${self.engines ? ` (needs ${self.engines})` : ""}`,

package/tools/marketplace/options.mjs

@@ -0,0 +1,72 @@
+// Every option every command accepts, in one table, and the one parser
+// that reads a command line against it.
+//
+// The table is the source the help signatures and the completion scripts
+// are held to (tests/unit/options.test.mjs): a flag a command reads must
+// be in its signature, and a flag in a signature must be one the command
+// reads, so `omakit help`, tab completion and the code cannot disagree. A
+// token the command does not know, an option without its value, or one
+// positional more than the command takes is refused before anything runs.
+// Measured before this: `omakit weigh <plugin> -n 1` ran three runs as if
+// nothing had been passed, and the other commands read their flags one by
+// one and ignored the rest.
+
+/**
+ * What each command accepts. `valued` options take the next token (or
+ * `--name=value`); `flags` stand alone; `positionals` is how many bare
+ * arguments the command takes. `--help` and `-h` are handled before any
+ * command runs and are not options of one.
+ */
+export const ACCEPTED = Object.freeze({
+  setup: Object.freeze({ valued: [], flags: ["--yes", "--completion"], positionals: 0 }),
+  pin: Object.freeze({ valued: [], flags: [], positionals: 0 }),
+  submit: Object.freeze({ valued: ["--category", "--tags", "--notes", "--suggest-tag", "--name", "--out"], flags: ["--offline", "--allow-dirty", "--json"], positionals: 1 }),
+  watch: Object.freeze({ valued: ["--out"], flags: ["--json"], positionals: 1 }),
+  verify: Object.freeze({ valued: ["--out"], flags: ["--allow-dirty", "--json"], positionals: 1 }),
+  help: Object.freeze({ valued: [], flags: ["--agent"], positionals: 0 }),
+  upgrade: Object.freeze({ valued: [], flags: ["--dry-run"], positionals: 0 }),
+  doctor: Object.freeze({ valued: ["--out"], flags: ["--offline", "--json"], positionals: 0 }),
+  parity: Object.freeze({ valued: ["--count", "--offset", "--out"], flags: [], positionals: 0 }),
+  weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
+})
+
+/** The accepted options of a command in the words a refusal prints: `--runs N, --all, ...`. */
+export function acceptedWords(name) {
+  const spec = ACCEPTED[name]
+  const value = (option) => ({ "--out": "FILE", "--runs": "N", "--count": "N", "--offset": "N", "--window": "S", "--settle": "S", "--category": "C", "--tags": "A,B" }[option] || "TEXT")
+  return [...spec.valued.map((option) => `${option} ${value(option)}`), ...spec.flags].join(", ")
+}
+
+/**
+ * Read a command line against a command's table. Every token is a known
+ * option (valued or not), the value of a valued option, or a positional up
+ * to the allowed count; the first token that is none of those is returned
+ * as `offending` with a reason, so the command refuses before any preflight.
+ *
+ * @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[] }}
+ */
+export 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 }
+}

package/tools/marketplace/setup.mjs

@@ -5,10 +5,12 @@
 // and what to try first. It is idempotent, so running it again on a machine that
 // is already set up just confirms that.
 //
-// It writes exactly one thing: the pinned checkout, through the same `ensurePin`
-// that `omakit pin` uses. It does not create symlinks, edit a shell profile or
-// install anything. Where a step is the user's to take, it prints the command
-// and stops, which is the same contract every other command here keeps.
+// It writes the pinned checkout, through the same `ensurePin` that `omakit
+// pin` uses, and the completion script where the shell in $SHELL loads it
+// from. It does not create symlinks or install anything, and it edits a shell
+// profile in exactly one case, after an explicit yes: the guarded block that
+// makes completions load, when a new shell has no loader. Everywhere else a
+// step that is the user's to take is printed as the command, and stops.
 
 import { execFileSync } from "node:child_process"
 import { banner } from "./banner.mjs"
@@ -18,9 +20,86 @@ import { progress } from "./progress.mjs"
 import { action, colourEnabled, GUTTER, mark, styler, wrap } from "./style.mjs"
 import { TAGLINE } from "./usage.mjs"
 import { installCompletion } from "./completion.mjs"
+import { appendLoaderBlock, completionWorks, loaderBlock, loaderBlockPresent, verifyCompletion } from "./completion-check.mjs"
 import { submissionContract } from "./form.mjs"
 import { pathHint } from "./path-hint.mjs"
 import { withHomeAbbreviated } from "./paths.mjs"
+import { askYes } from "../weigh/confirm.mjs"
+import { tool } from "./doctor.mjs"
+
+/**
+ * Tab completion, end to end: the script written for the shell in $SHELL
+ * where that shell loads it from, then a new interactive shell asked
+ * whether it can complete `omakit`, the way TAB asks. Measured before this
+ * (docs/MEASUREMENTS.md M8): setup reported the script installed and never
+ * asked a shell. When the shell has no completion loader, the one guarded
+ * block that gives it one is offered, once, and appended only on yes; with
+ * `askRc: false` (the step `upgrade` re-runs) it is named and not offered.
+ * `▁ ok` is printed only when a new shell shows the spec.
+ *
+ * @param {{ repoRoot: string, pin: string, version: string, stream?: NodeJS.WriteStream, env?: object,
+ *           yes?: boolean, askRc?: boolean, input?: NodeJS.ReadStream, verify?: typeof verifyCompletion }} options
+ * @returns {Promise<{ state: "ok"|"note"|"unsupported"|"error", shell: string|null, rcAppended: boolean }>}
+ */
+export async function completionStep({ repoRoot, pin, version, stream = process.stdout, env = process.env, yes = false, askRc = true, input = process.stdin, verify = verifyCompletion }) {
+  const c = styler(colourEnabled(stream))
+  const out = (line = "") => stream.write(`${line}\n`)
+  const step = (state, text) => out(`${mark(state, c)}${wrap(withHomeAbbreviated(text, env), { indent: GUTTER }, c).join("\n").trimStart()}`)
+  const fix = (text) => { for (const line of action(withHomeAbbreviated(text, env), c)) out(line) }
+  let completion
+  try {
+    const contract = await submissionContract({ repoRoot })
+    completion = installCompletion({ contract, pin, version, env })
+  } catch (error) {
+    step("info", `tab completion was not installed: ${error.message}`)
+    return { state: "error", shell: null, rcAppended: false }
+  }
+  if (completion.state === "unsupported") {
+    step("info", completion.shell
+      ? `tab completion: no script for ${completion.shell}; there is one for bash, zsh and fish.`
+      : "tab completion: $SHELL is not set, so no script was installed.")
+    return { state: "unsupported", shell: completion.shell, rcAppended: false }
+  }
+  const what = { installed: "installed", updated: "updated for this omakit and pin", current: "already installed" }[completion.state]
+  const where = `${completion.display}${completion.note ? `, ${completion.note}` : ""}`
+  let probe = verify(completion.shell, { env })
+  let rcAppended = false
+  if (!probe.ran) {
+    step("advisory", `tab completion for ${completion.shell} ${what} at ${where}, but a new ${completion.shell} could not be asked whether it loads: ${probe.reason}.`)
+    return { state: "note", shell: completion.shell, rcAppended }
+  }
+  if (!probe.loader) {
+    const block = loaderBlock(completion.shell, env)
+    const missing = completion.shell === "bash"
+      ? "a new bash has no completion loader: /usr/share/bash-completion/bash_completion is not sourced, so a script under ~/.local/share/bash-completion/ is never read"
+      : "a new zsh has not run compinit, so no completion function is ever loaded"
+    step("advisory", `tab completion for ${completion.shell} ${what} at ${where}, but ${missing}.`)
+    if (block && !loaderBlockPresent(completion.shell, env)) {
+      const question = `Add one guarded line to ${block.display} so completions load?`
+      const agreed = askRc ? (yes || (Boolean(input.isTTY) && Boolean(stream.isTTY) && await askYes({ input, output: process.stderr, question }))) : false
+      if (agreed) {
+        const wrote = appendLoaderBlock(completion.shell, env)
+        rcAppended = wrote.appended
+        step("info", `appended to ${block.display}, marked \`${block.lines[0]}\`; omakit never edits or removes it.`)
+        probe = verify(completion.shell, { env })
+      } else {
+        step("info", `nothing was written. The lines that make completions load, for ${block.display}:`)
+        for (const line of block.lines) fix(line)
+        return { state: "note", shell: completion.shell, rcAppended }
+      }
+    } else if (block) {
+      step("info", `${block.display} already carries the \`${block.lines[0]}\` block; a new shell still reports no loader, so something later in that file undoes it.`)
+      return { state: "note", shell: completion.shell, rcAppended }
+    }
+  }
+  if (completionWorks(probe)) {
+    step("pass", `tab completion for ${completion.shell} ${what} at ${where}; a new ${completion.shell} completes \`omakit\`${probe.spec === "lazy" ? " on the first TAB" : ""}.${rcAppended ? ` Open terminals need a new shell: \`exec ${completion.shell}\`.` : ""}`)
+    return { state: "ok", shell: completion.shell, rcAppended }
+  }
+  step("advisory", `tab completion for ${completion.shell} ${what} at ${where}, but a new ${completion.shell} ${probe.loader ? "does not load it" : "still has no completion loader"}${rcAppended ? " even after the block was appended" : ""}.`)
+  fix(`Open a new shell (\`exec ${completion.shell}\`) and run \`omakit doctor\`; it reports the script, the loader and the spec as \`omakit.completion\`.`)
+  return { state: "note", shell: completion.shell, rcAppended }
+}
 
 function version(command) {
   try {
@@ -33,11 +112,13 @@ function version(command) {
 }
 
 /**
- * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream, env?: object }} options
+ * @param {{ repoRoot: string, entryPoint: string, stream?: NodeJS.WriteStream, env?: object, yes?: boolean,
+ *           input?: NodeJS.ReadStream, verify?: typeof verifyCompletion }} options
  *   `env` is where `$HOME` is read from: this is output for a person, so a
- *   path under it is printed as `~/...`.
+ *   path under it is printed as `~/...`. `yes` answers the one question
+ *   setup can ask (the rc block for completion), for an agent.
  */
-export async function setup({ repoRoot, entryPoint, stream = process.stdout, env = process.env }) {
+export async function setup({ repoRoot, entryPoint, stream = process.stdout, env = process.env, yes = false, input = process.stdin, verify = verifyCompletion }) {
   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.
@@ -110,23 +191,8 @@ export async function setup({ repoRoot, entryPoint, stream = process.stdout, env
   }
 
   // Tab completion, installed for the shell in $SHELL where that shell loads
-  // it from, so nobody has to know the path. The script carries the pin's
-  // categories and tags, so it is rewritten when the pin has moved and left
-  // alone otherwise.
-  try {
-    const contract = await submissionContract({ repoRoot })
-    const completion = installCompletion({ contract, pin: identity.commit })
-    if (completion.state === "unsupported") {
-      step("info", completion.shell
-        ? `tab completion: no script for ${completion.shell}; there is one for bash, zsh and fish.`
-        : "tab completion: $SHELL is not set, so no script was installed.")
-    } else {
-      const what = { installed: "installed", updated: "updated for this pin", current: "already installed" }[completion.state]
-      step("pass", `tab completion for ${completion.shell} ${what} at ${completion.display}${completion.note ? `, ${completion.note}` : ""}.`)
-    }
-  } catch (error) {
-    step("info", `tab completion was not installed: ${error.message}`)
-  }
+  // it from, and then proven in a new shell (completionStep).
+  await completionStep({ repoRoot, pin: identity.commit, version: tool(repoRoot).version, stream, env, yes, askRc: true, input, verify })
   out()
 
   out("Try it on a plugin you have checked out:")

package/tools/marketplace/upgrade.mjs

@@ -144,7 +144,29 @@ export function isExpectedRemote(url, expected = REPOSITORY) {
  *   a way to point the command at somebody else's repository, because nothing
  *   on the command line reaches it.
  */
-export async function upgrade({ repoRoot, stream = process.stdout, dryRun = false, expectedRemote = REPOSITORY, latest = latestOnRegistry, npmRoot = npmGlobalRoot, name = "omakit" }) {
+/**
+ * After a successful install, the completion step of the omakit that was
+ * just installed: it renders the script with its own version and proves it
+ * in a new shell, and never asks the rc question (the loader does not
+ * change with an upgrade). Run as a child of the new entry point, not in
+ * this process, whose code is the old version's. Frozen arguments.
+ */
+export const COMPLETION_REFRESH_ARGS = Object.freeze(["setup", "--completion"])
+
+function refreshCompletionWith(root, stream) {
+  const entryPoint = join(root, "bin/omakit")
+  if (!existsSync(entryPoint)) return { ran: false, reason: `${entryPoint} is not there` }
+  try {
+    const out = execFileSync(process.execPath, [entryPoint, ...COMPLETION_REFRESH_ARGS], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+    stream.write(out)
+    return { ran: true, ok: true }
+  } catch (error) {
+    stream.write(error.stdout || "")
+    return { ran: true, ok: false, reason: String(error.stderr || error.message).trim() }
+  }
+}
+
+export async function upgrade({ repoRoot, stream = process.stdout, dryRun = false, expectedRemote = REPOSITORY, latest = latestOnRegistry, npmRoot = npmGlobalRoot, name = "omakit", refreshCompletion = refreshCompletionWith }) {
   const c = styler(colourEnabled(stream))
   const out = (line = "") => stream.write(`${line}\n`)
   const lines = (list) => { for (const line of list) out(line) }
@@ -160,7 +182,7 @@ export async function upgrade({ repoRoot, stream = process.stdout, dryRun = fals
     if (installKind(repoRoot) === "distro") {
       return refuse("this is a distro package under /usr, so omakit leaves upgrades to the package manager.", upgradeCommand(repoRoot))
     }
-    return upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, refuse, note, ok, out, lines, c })
+    return upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, refuse, note, ok, out, lines, c, refreshCompletion })
   }
 
   let remote
@@ -245,15 +267,17 @@ export async function upgrade({ repoRoot, stream = process.stdout, dryRun = fals
   ok(`${before.slice(0, 7)} to ${after.slice(0, 7)} on ${branch}, ${log.length} commit(s)`)
   for (const line of log) out(subject(line))
   out()
+  const completion = refreshCompletion(resolve(repoRoot), stream)
+  if (completion.ran === false) note(`tab completion was not refreshed: ${completion.reason}. Run \`omakit setup\`.`)
   lines(wrap("The marketplace pin did not move: this updated the tool, not the commit its rules are read from. `omakit doctor` says whether that pin is behind, and docs/UPSTREAM_CONTRACT.md says what moving it involves.", {}, c))
-  return { ok: true, changed: true, from: before, to: after, commits: log.length }
+  return { ok: true, changed: true, from: before, to: after, commits: log.length, completion }
 }
 
 /**
  * The npm route. `latest` and `npmRoot` are injectable for the tests only, the
  * way `expectedRemote` is: nothing on the command line reaches them.
  */
-async function upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, refuse, note, ok, out, lines, c }) {
+async function upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, refuse, note, ok, out, lines, c, refreshCompletion }) {
   const root = resolve(repoRoot)
   const globalRoot = npmRoot()
   if (!globalRoot) {
@@ -302,6 +326,8 @@ async function upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, ref
   }
   ok(`${current} to ${after}, through the npm that installed it`)
   out()
+  const completion = refreshCompletion(root, stream)
+  if (completion.ran === false) note(`tab completion was not refreshed: ${completion.reason}. Run \`omakit setup\`.`)
   lines(wrap("The marketplace pin did not move: this updated the tool, not the commit its rules are read from. `omakit doctor` says whether that pin is behind, and docs/UPSTREAM_CONTRACT.md says what moving it involves.", {}, c))
-  return { ok: true, changed: true, from: current, to: after }
+  return { ok: true, changed: true, from: current, to: after, completion }
 }

package/tools/marketplace/usage.mjs

@@ -22,10 +22,13 @@ export const COMPLETION_SHELLS = Object.freeze(["bash", "zsh", "fish"])
 
 export const COMMANDS = Object.freeze([
   {
-    signature: "omakit setup",
+    signature: "omakit setup [--yes] [--completion]",
     lines: [
       "First run, in one command: check the environment, fetch the pinned",
-      "marketplace checkout, and say what to try first. Idempotent.",
+      "marketplace checkout, install tab completion and prove it in a new shell,",
+      "and say what to try first. Idempotent. When a new shell has no completion",
+      "loader it asks once before adding one guarded block to the rc file; --yes",
+      "answers for an agent. --completion is that step alone, never the question.",
     ],
   },
   {
@@ -55,7 +58,7 @@ export const COMMANDS = Object.freeze([
     ],
   },
   {
-    signature: "omakit watch <issue-url> [--json]",
+    signature: "omakit watch <issue-url> [--json] [--out <file>]",
     lines: [
       "Compare the commit the marketplace validated on a submission issue with",
       "the plugin repository's current default-branch HEAD, and say what makes",
@@ -86,7 +89,7 @@ export const COMMANDS = Object.freeze([
     ],
   },
   {
-    signature: "omakit doctor [--offline] [--json]",
+    signature: "omakit doctor [--offline] [--json] [--out <file>]",
     lines: [
       "What is installed, what is pinned, and what has moved since. Reads and",
       "prints; it installs nothing and never moves the pin.",
@@ -104,6 +107,7 @@ export const COMMANDS = Object.freeze([
       "omakit weigh <plugin-id-or-dir> [--runs <n>] [--window <s>] [--settle <s>]",
       "                    [--yes] [--json] [--out <file>]",
       "omakit weigh --all",
+      "omakit weigh --list [--json]",
     ],
     lines: [
       "What a plugin weighs on the shell, measured: the shell is restarted",
@@ -117,7 +121,8 @@ export const COMMANDS = Object.freeze([
       "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.",
+      "for the plugin's README. --list is read-only: every installed plugin",
+      "and when it was last weighed, unweighed enabled plugins first.",
     ],
   },
 ])

package/tools/weigh/list.mjs

@@ -0,0 +1,90 @@
+// `omakit weigh --list`: every installed plugin, and when it was last
+// weighed. Read-only: `listPlugins` answering is the only preflight, no
+// shell is restarted, nothing is written, and the documents under
+// `$XDG_STATE_HOME/omakit/weigh/` are read for the last sentence per id.
+
+import { readdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { run } from "./commands.mjs"
+import { WeighError } from "./audit.mjs"
+import { omakitStateDir } from "../marketplace/paths.mjs"
+
+/**
+ * The last weighing of each plugin id, from the documents in the state
+ * directory: the newest `started` wins. A document that cannot be read or
+ * parsed is skipped; `timing.json` is not a document.
+ *
+ * @returns {Map<string, { date: string, started: string, readme: string|null, summary: string, document: string }>}
+ */
+export function lastWeighings(stateDir) {
+  const latest = new Map()
+  let names = []
+  try {
+    names = readdirSync(stateDir).filter((name) => name.endsWith(".json") && name !== "timing.json")
+  } catch {
+    return latest
+  }
+  for (const name of names) {
+    const file = join(stateDir, name)
+    let document
+    try {
+      document = JSON.parse(readFileSync(file, "utf8"))
+    } catch {
+      continue
+    }
+    if (document?.command !== "weigh" || !Array.isArray(document.plugins) || typeof document.started !== "string") continue
+    for (const row of document.plugins) {
+      const known = latest.get(row.id)
+      if (known && known.started >= document.started) continue
+      latest.set(row.id, { date: document.started.slice(0, 10), started: document.started, readme: row.readme ?? null, summary: row.verdict?.summary ?? "", document: file })
+    }
+  }
+  return latest
+}
+
+/**
+ * One row per installed plugin, sorted: enabled and not weighed first (by
+ * id), then enabled and weighed, oldest weighing first, then disabled.
+ *
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ */
+export function listWeighings({ env = process.env } = {}) {
+  const listed = run("listPlugins", { env })
+  if (!listed.ok) throw new WeighError("shell-not-running", "omarchy plugin list did not answer, and the list is what the shell has installed", "omarchy-restart-shell")
+  let installed
+  try {
+    installed = JSON.parse(listed.stdout)
+  } catch {
+    throw new WeighError("shell-unreadable", "omarchy plugin list did not answer with JSON", "omarchy-restart-shell, then run it again.")
+  }
+  const catalogRun = run("catalog", { env })
+  let catalog = []
+  try {
+    catalog = catalogRun.ok ? JSON.parse(catalogRun.stdout) : []
+  } catch {
+    catalog = []
+  }
+  const sourceDirOf = (id) => catalog.find((entry) => entry.id === id)?.sourceDir || null
+  const stateDir = omakitStateDir("weigh", env)
+  const latest = lastWeighings(stateDir)
+  const rows = installed.map((plugin) => {
+    const kinds = plugin.kinds || []
+    const last = latest.get(plugin.id) || null
+    return {
+      id: plugin.id,
+      name: plugin.name || plugin.id,
+      kinds,
+      enabled: plugin.enabled === true,
+      firstParty: plugin.firstParty === true,
+      sourceDir: sourceDirOf(plugin.id),
+      weighable: !kinds.includes("bar"),
+      lastWeighed: last ? { date: last.date, readme: last.readme, summary: last.summary, document: last.document } : null,
+      enable: plugin.enabled === true ? null : `omarchy plugin enable ${plugin.id}`,
+    }
+  })
+  const rank = (row) => (row.enabled ? (row.lastWeighed ? 1 : 0) : 2)
+  rows.sort((a, b) => rank(a) - rank(b)
+    || (rank(a) === 1 ? a.lastWeighed.date.localeCompare(b.lastWeighed.date) : 0)
+    || a.id.localeCompare(b.id))
+  return { stateDir, rows }
+}

package/tools/weigh/report.mjs

@@ -164,3 +164,33 @@ export function renderWeigh(document, { colour = colourEnabled(), env = process.
   }
   return out.join("\n")
 }
+
+/**
+ * `omakit weigh --list` for a person: one `░ info` row per installed
+ * plugin, in the list's order (enabled and not weighed first), each with
+ * its name, its state and its last weighing in words. Every row is
+ * information: the list decides nothing, so no row is a pass, a note or a
+ * question.
+ */
+export function renderList(list, { colour = colourEnabled(), env = process.env } = {}) {
+  const c = styler(colour)
+  const out = []
+  const { rows } = list
+  const weighed = rows.filter((row) => row.lastWeighed).length
+  const enabled = rows.filter((row) => row.enabled).length
+  out.push(...field("installed", `${rows.length} plugin${rows.length === 1 ? "" : "s"}, ${enabled} enabled, ${weighed} weighed; weighings read from ${withHomeAbbreviated(list.stateDir, env)}`, c))
+  out.push("")
+  for (const [index, row] of rows.entries()) {
+    if (index > 0) out.push("")
+    out.push(head("info", row.id, row.kinds.join(", ") || "no kinds", c))
+    out.push(...field("name", row.name, c))
+    out.push(...field("state", row.enabled ? "enabled" : `disabled; \`${row.enable}\` enables it`, c))
+    const last = row.lastWeighed
+    out.push(...field("weighed", !row.weighable
+      ? "not weighed: a whole bar, and replacing the bar is not a weight"
+      : last
+        ? `${last.date}: ${last.readme || last.summary}`
+        : "not weighed", c))
+  }
+  return out.join("\n")
+}