omakit 0.1.9 → 0.2.0

package/tools/marketplace/cli.mjs

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

package/tools/marketplace/completion.mjs

@@ -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
  */
@@ -33,7 +33,7 @@ export function subcommandsOf(commands = COMMANDS) {
       value: placeholder ? placeholderKind(placeholder) : null,
     }))
     const sentence = command.lines.join(" ").replace(/`/g, "").split(/(?<=\.)\s/)[0]
-    return { name, description: sentence, flags, target: /<target>/.test(signature) }
+    return { name, description: sentence, flags, target: /<target>|<plugin-id-or-dir>/.test(signature) }
   })
 }
 

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/usage.mjs

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