omakit 0.1.9 → 0.2.1

package/tools/marketplace/completion.mjs

@@ -18,8 +18,8 @@ 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
  */
@@ -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>/.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/paths.mjs

@@ -9,6 +9,19 @@ export function omakitCacheDir(name = "", env = process.env) {
   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`

package/tools/marketplace/report.mjs

@@ -35,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))

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.",
@@ -99,6 +102,29 @@ 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",
+      "omakit weigh --list [--json]",
+    ],
+    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. --list is read-only: every installed plugin",
+      "and when it was last weighed, unweighed enabled plugins first.",
+    ],
+  },
 ])
 
 // A command sits one STEP in from the heading; what it does sits one STEP in