omakit 0.4.1 → 0.4.3

package/tools/inspect/writes.mjs

@@ -0,0 +1,194 @@
+// Write sites: a `FileView {` with a path and a write adapter or a write
+// call in QML; a redirect, `tee`, `cp`, `mv`, `mkdir`, `mktemp`, `install`
+// or `touch` in shell; `writeFile` and its variants in JavaScript; `open()`
+// for writing in Python. Each row says whether the path's literal prefix,
+// after the `$HOME`, `~` and `XDG_*` idioms are expanded, falls under a
+// directory the plugin controls, and which mode the file shows for it.
+
+import { basename, blankComments, blocks, closingBracket, lineOf, propertyValue, blankShellExpressions, shellLogicalLines, shellPieces, shellWords, stringLiteral, withoutRedirections } from "./text.mjs"
+
+/** The directories a plugin controls, by the names the contract lists. */
+export const CONTROLLED = Object.freeze(["$XDG_STATE_HOME", "$XDG_CACHE_HOME", "$XDG_RUNTIME_DIR"])
+export const SHARED_TEMP = Object.freeze(["/tmp", "/var/tmp", "/dev/shm"])
+const DEVICES = new Set(["/dev/null", "/dev/stderr", "/dev/stdout", "/dev/tty"])
+
+/**
+ * A path's literal prefix in canonical form: `~` and `$HOME` idioms,
+ * `${X}` and `Quickshell.env("X")` all read as `$X`, and the three
+ * dot-directories under the home read as the XDG names they default to.
+ * A JavaScript expression that is a `+` chain of string literals and
+ * `Quickshell.env()` calls is joined; any other expression is returned as
+ * `null`, which the classification reads as unknown.
+ */
+export function canonicalPath(raw) {
+  let text = String(raw).trim()
+  const literal = stringLiteral(text)
+  if (literal !== null) text = literal
+  else if (/[+]/.test(text) || /Quickshell\.env|StandardPaths/.test(text)) {
+    const pieces = text.split(/\s*\+\s*/)
+    const joined = pieces.map((piece) => {
+      const part = stringLiteral(piece)
+      if (part !== null) return part
+      const env = piece.match(/^Quickshell\.env\(\s*(["'])([A-Z_][A-Z0-9_]*)\1\s*\)$/)
+      if (env) return `$${env[2]}`
+      return null
+    })
+    if (joined.some((piece) => piece === null)) return null
+    text = joined.join("")
+  } else if (!/^[~/$.]/.test(text) && !/^[\w.-]+(?:\/[\w.-]*)*$/.test(text)) return null
+  text = text.replace(/\$\{(\w+)\}/g, "$$$1")
+  if (text === "~" || text.startsWith("~/")) text = `$HOME${text.slice(1)}`
+  text = text.replace(/^\$HOME\/\.local\/state(?=\/|$)/, "$XDG_STATE_HOME")
+    .replace(/^\$HOME\/\.cache(?=\/|$)/, "$XDG_CACHE_HOME")
+    .replace(/^\$HOME\/\.config(?=\/|$)/, "$XDG_CONFIG_HOME")
+  return text
+}
+
+/**
+ * Whether a canonical path is under a directory the plugin controls.
+ * @returns {{ controlledDirectory: "observed"|"not-observed"|"unknown", controlledBy: string|null, temp: boolean }}
+ */
+export function classifyPath(path, pluginId) {
+  if (path === null || path === undefined) return { controlledDirectory: "unknown", controlledBy: null, temp: false }
+  for (const prefix of CONTROLLED) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) return { controlledDirectory: "observed", controlledBy: prefix, temp: false }
+  }
+  const own = pluginId ? `$XDG_CONFIG_HOME/omarchy/plugins/${pluginId}` : null
+  if (own && (path === own || path.startsWith(`${own}/`))) return { controlledDirectory: "observed", controlledBy: own, temp: false }
+  for (const prefix of SHARED_TEMP) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) return { controlledDirectory: "not-observed", controlledBy: null, temp: true }
+  }
+  if (path.startsWith("/") || path.startsWith("$HOME") || path.startsWith("$XDG_")) return { controlledDirectory: "not-observed", controlledBy: null, temp: false }
+  return { controlledDirectory: "unknown", controlledBy: null, temp: false }
+}
+
+function row(file, line, rawPath, via, pluginId, mode = null) {
+  const canonical = canonicalPath(rawPath)
+  const classified = classifyPath(canonical, pluginId)
+  return { file: file.path, line, path: String(rawPath).trim(), canonicalPath: canonical, via, ...classified, mode }
+}
+
+function qmlWrites(file, pluginId) {
+  const text = blankComments(file.text)
+  const rows = []
+  for (const block of blocks(text, "FileView")) {
+    const path = propertyValue(block.body, "path")
+    if (!path) continue
+    const writes = /writeAdapter|blockWrites|atomicWrites|setText\s*\(|(?<![\w.])write\s*\(/.test(block.body)
+      || (block.id && new RegExp(`(?<![\\w.])${block.id}\\.(?:writeAdapter|setText|write)\\s*\\(`).test(text))
+    if (!writes) continue
+    rows.push(row(file, lineOf(text, block.open + 1 + path.offset), path.text, "FileView", pluginId))
+  }
+  rows.push(...jsWrites({ ...file, text }, pluginId, true))
+  return rows
+}
+
+function jsWrites(file, pluginId, blanked = false) {
+  const text = blanked ? file.text : blankComments(file.text)
+  const rows = []
+  for (const match of text.matchAll(/(?<![\w.])(writeFileSync|writeFile|appendFileSync|appendFile)\s*\(/g)) {
+    const open = match.index + match[0].length - 1
+    const end = closingBracket(text, open)
+    if (end < 0) continue
+    const first = text.slice(open + 1, end).split(",")[0]
+    rows.push(row(file, lineOf(text, match.index), first, match[1], pluginId))
+  }
+  return rows
+}
+
+function pythonWrites(file, pluginId) {
+  const rows = []
+  const lines = file.text.split("\n")
+  for (const [index, line] of lines.entries()) {
+    const code = line.split("#")[0]
+    for (const match of code.matchAll(/(?<![\w.])open\s*\(\s*([^,()]+)\s*,\s*(["'])([rwaxb+]+)\2/g)) {
+      if (!/[wax]/.test(match[3])) continue
+      rows.push(row(file, index + 1, match[1], "open", pluginId))
+    }
+  }
+  return rows
+}
+
+/** The words that are not options, and the value of `-m`/`--mode` when one is given. */
+function operands(all) {
+  const words = withoutRedirections(all)
+  const out = []
+  let mode = null
+  for (let index = 1; index < words.length; index += 1) {
+    const word = words[index]
+    if (word === "-m" || word === "--mode") {
+      mode = words[index + 1] ?? null
+      index += 1
+    } else if (word.startsWith("--mode=")) mode = word.slice("--mode=".length)
+    else if (word.startsWith("-") && word !== "-") continue
+    else out.push(word)
+  }
+  return { operands: out, mode }
+}
+
+function shellWrites(file, pluginId) {
+  const rows = []
+  const chmods = []
+  let umask = null
+  for (const { line, text } of shellLogicalLines(file.text)) {
+    const trimmed = blankShellExpressions(text).trim()
+    if (!trimmed || trimmed.startsWith("#")) continue
+    for (const segment of shellPieces(trimmed)) {
+      const words = shellWords(segment.text)
+      if (!words.length) continue
+      // Redirections anywhere in the segment: `> path`, `>> path`, `>path`, `&> path`.
+      for (let i = 0; i < words.length; i += 1) {
+        const word = words[i]
+        let target = null
+        let via = null
+        if (/^(?:\d*>>?|&>>?)$/.test(word) && !/^\d*>&/.test(word)) {
+          target = words[i + 1]
+          via = word.includes(">>") ? ">>" : ">"
+          i += 1
+        } else if (/^(?:\d*>>?|&>>?)[^&\s]/.test(word)) {
+          target = word.replace(/^(?:\d*>>?|&>>?)/, "")
+          via = word.includes(">>") ? ">>" : ">"
+        }
+        // A subshell's closing paren clings to the last word; a bare number
+        // or operator where a path would be is a comparison the blanking
+        // did not reach, not a write.
+        if (target) target = target.replace(/[);]+$/, "")
+        if (target && !DEVICES.has(target) && !/^&\d$/.test(target) && !/^[\d=<>!]+$/.test(target)) rows.push(row(file, line, target, via, pluginId))
+      }
+      const command = basename(words[0])
+      if (command === "umask" && words[1]) umask = words[1]
+      if (command === "chmod" && words.length >= 3) chmods.push({ mode: words[1], paths: words.slice(2) })
+      if (["tee", "mkdir", "touch"].includes(command)) {
+        const { operands: paths, mode } = operands(words)
+        for (const path of paths) rows.push(row(file, line, path, command, pluginId, mode))
+      } else if (["cp", "mv", "install", "ln"].includes(command)) {
+        const { operands: paths, mode } = operands(words)
+        if (paths.length >= 2) rows.push(row(file, line, paths[paths.length - 1], command, pluginId, mode))
+      } else if (command === "mktemp") {
+        const { operands: paths } = operands(words)
+        const template = paths[0] || (words.includes("-p") ? `${words[words.indexOf("-p") + 1]}/tmp.XXXXXX` : "/tmp/tmp.XXXXXX")
+        rows.push(row(file, line, template, "mktemp", pluginId, words.includes("-d") ? "0700" : "0600"))
+      }
+    }
+  }
+  for (const write of rows) {
+    if (write.mode) continue
+    const chmod = chmods.find((entry) => entry.paths.includes(write.path))
+    if (chmod) write.mode = `chmod ${chmod.mode}`
+    else if (umask) write.mode = `umask ${umask}`
+  }
+  return rows
+}
+
+/**
+ * @param {{ path: string, kind: string, text: string }} file
+ * @param {{ pluginId?: string|null }} [context]
+ * @returns {Array} write rows, in file order
+ */
+export function extractWrites(file, { pluginId = null } = {}) {
+  if (file.kind === "qml") return qmlWrites(file, pluginId)
+  if (file.kind === "js") return jsWrites(file, pluginId)
+  if (file.kind === "shell") return shellWrites(file, pluginId)
+  if (file.kind === "python") return pythonWrites(file, pluginId)
+  return []
+}

package/tools/marketplace/README.md

@@ -8,7 +8,7 @@ local commit through the transport seam the marketplace tests itself
 | File | Purpose |
 | --- | --- |
 | `pin.mjs` | The pin identity (one home) and the reproducible setup: `omakit pin` fetches exactly that commit into `$XDG_CACHE_HOME/omakit/marketplace` and refuses a modified checkout. |
-| `local-transport.mjs` | Answers the four request shapes the official resolver makes, from a local clone at the exact commit. No network, no credentials, no writes. |
+| `local-transport.mjs` | Answers the four request shapes the official resolver makes, from a local clone at the exact commit. No network, no credentials, no writes. With `subdir`, serves a directory below the root as the whole tree, which is how `inspect` keeps the baseline to the plugin's own tree. |
 | `run-baseline.mjs` | Runs the pinned official baseline over either transport and reports the pin identity beside the result. |
 | `verify.mjs` | Builds the `marketplaceBaseline` section: pin, transport, assumptions, the official result verbatim, the statement. `omakit verify` renders it for a person (`renderVerify` in `report.mjs`) and prints the document itself behind `--json` and `--out`. |
 | `preflight.mjs` | Translates that result into what it will cause on submission, using the pinned policy, and renders the marketplace's own report text with its attestation marker stripped and asserted absent. |
@@ -18,6 +18,8 @@ local commit through the transport seam the marketplace tests itself
 | `tree.mjs` | The installable tree of a subject at one exact commit, from the Git object database. |
 | `plugin.mjs` | The root files the submission contract needs, and the declared plugin identity. |
 | `agent-control.mjs` | The recursive agent-control warning, and its remedy. |
+| `review-cost.mjs` | The advisory review-cost verdict, shared account discovery, and path classification between dated validated snapshots. M4 and M9 carry its evidence. |
+| `measure-review-cost.mjs` | Reproduces M9 across the open update population at live marketplace HEAD, with compare sources and explicit skipped reasons in JSON. |
 | `issue.mjs` | Renders the issue the way the form would, then has the marketplace's own parser judge it. |
 | `submit.mjs` | Assembles every check with its measured reason, and withholds the body when a blocking check fails. Three outcomes: `ready` (the body), `refused` (a blocking check failed) and `listed` (the plugin is already listed by its own repository: `identity.available` passes with the listing's record, the five body checks are omitted rather than drawn as waiting, no body exists on purpose, and `listing` carries the listed commit against the local one and the form to use for a newer commit). Decides the category and tags after the registry: a listed plugin, own or taken, is asked for neither; an unlisted one without them is asked through `ask.mjs` at a terminal, and is a usage error otherwise. Ends with `reproduce`, the command line that repeats the run without asking. Under `--offline` the validation-commit check is `skipped`, not passed: verdict `skipped`, listed under `skipped` and not `unknown`, never blocking, and the READY line says "1 check skipped (--offline)". |
 | `ask.mjs` | The two questions `submit` asks a person at a terminal, and only there: category and tags, numbered from the pinned form, with the marketplace's own presentation for the manifest's kinds (read from the pinned catalog builder) as the default where it is on the list. Prompts on stderr, nothing persisted. |
@@ -53,8 +55,27 @@ machine (docs/WEIGH.md):
 | `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. |
 
+`tools/inspect/` is `omakit inspect`, what a plugin tree does as observations
+(docs/INSPECT.md), regular expressions over QML and shell, read-only against
+the tree, no verdict:
+
+| File | Purpose |
+| --- | --- |
+| `inspect/inspect.mjs` | The command: resolve the subject the way `submit` does, walk the tree, run the four extractors, run `verify` for the baseline, evaluate the patterns, build the document. The fixed blind-spot list lives here. |
+| `inspect/walk.mjs` | The installable tree at the commit (through `tree.mjs`) filtered to the kinds inspect reads: `.qml`, `.js`, `.mjs`, `.cjs`, the shell extensions, `.py`, and any blob with a shebang or the executable bit; the manifest for the id; prose never read for facts. |
+| `inspect/text.mjs` | The text primitives every extractor shares: line numbers, brace blocks, a property's value inside a block, string and array literals, the crude shell word and segment split, command substitutions, redirections. |
+| `inspect/processes.mjs` | Process sites: `Process {` blocks with their `command:` or `<id>.command =`, `execDetached` calls, and every command segment of a shell script; argv, deadline, collector, cap, shell wrapper. |
+| `inspect/hosts.mjs` | Every `http` or `https` literal with its host, the tool it reaches, and the timeout and size-cap flags in the same argv; a host behind an expression is not resolvable, never guessed. |
+| `inspect/writes.mjs` | Write sites in QML (`FileView` with a write), shell (redirects, `tee`, `cp`, `mv`, `mkdir`, `mktemp`, `install`, `touch`), JavaScript and Python, with the controlled-directory test over the canonical path prefix and the mode the file shows. |
+| `inspect/timers.mjs` | `Timer {` blocks: interval, repeat, running, triggeredOnStart, and the handler outside the block that starts it. |
+| `inspect/functions.mjs` | Function sites: `function name(` and multi-line handlers in QML and JavaScript, shell functions, Python defs, each with its length in lines, deepest nesting and branch count. |
+| `inspect/patterns.mjs` | The ten review classes of M11 as data: id, label, precondition over the facts, measurement, share, and the phrase for the `not observed` line. `supply-chain` cites the baseline's own findings and detects nothing. Also the M12 size thresholds as data, and the longest-first order over them. |
+| `inspect/contract.mjs` | The JSON contract of docs/INSPECT.md as a validator, run by the unit tests over every fixture document. |
+| `inspect/report.mjs` | The report for a person, drawn with `style.mjs` only: `░ info` for a fact, `▒ ?` for one that could not be read, `▓ note` for a pattern row, `▔ skip` under `--offline`, and the closing word `INSPECTED`. |
+
 ```text
 omakit pin
+omakit inspect /path/to/plugin-repo                      # what the tree does, as observations; --json for the document
 omakit submit /path/to/plugin-repo                       # asks for the category and tags at a terminal
 omakit submit /path/to/plugin-repo --category Widgets --tags bar,quickshell
 omakit submit https://github.com/owner/repo@<40-char sha> --category System --tags system
@@ -98,7 +119,9 @@ sequences and nothing else.
 built-in `fetch`, which does not read proxy environment variables by default.
 Behind a proxy, run them with `NODE_USE_ENV_PROXY=1`. `submit` reads two things
 online, the subject's default-branch HEAD and the marketplace's current
-registry, and `--offline` turns both off; `verify` needs no network at all
+registry. A manual-review baseline also reads the account's open issue
+discovery and issue bodies for batching advice; `--offline` turns these
+reads off. `verify` needs no network at all
 beyond fetching a reviewer-mode subject, and `tests/parity/offline.mjs` proves
 it.
 

package/tools/marketplace/cli.mjs

@@ -7,6 +7,7 @@
 //   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
+//   omakit inspect <plugin-dir>      what a plugin tree does, as observations; decides nothing
 //
 // 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`
@@ -42,6 +43,8 @@ import { listWeighings } from "../weigh/list.mjs"
 import { askYes } from "../weigh/confirm.mjs"
 import { auditInstalled } from "../audit/audit.mjs"
 import { renderAudit } from "../audit/report.mjs"
+import { inspectPlugin, NOT_READABLE } from "../inspect/inspect.mjs"
+import { renderInspect } from "../inspect/report.mjs"
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..")
 
@@ -68,6 +71,16 @@ const REMEDY = Object.freeze({
   "interrupted": "shell.json was restored; run it again when the desktop is yours to restart.",
 })
 
+/*
+ * A command that has written its result leaves through `process.exitCode`,
+ * never `process.exit()`: stdout is an API, and on a pipe whose reader has
+ * not started reading yet the exit cuts the output. Measured on 0.4.1:
+ * `omakit submit <listed plugin> --json | (sleep 2; cat)` delivered 8,192 of
+ * 14,033 bytes, and a parser downstream saw invalid JSON. The failure
+ * states below still exit at once: they write one short block to stderr,
+ * and their callers use them the way a throw is used.
+ */
+
 /**
  * Every failure, in one register, on stderr. `usage` errors carry the
  * signature that was expected, so the remedy is the reference and not a
@@ -90,9 +103,21 @@ function failFrom(error) {
   throw error
 }
 
+/**
+ * The value of a valued option, written either way the table accepts,
+ * `--name value` or `--name=value`, the last occurrence winning as it does
+ * in options.mjs. Measured on 0.4.1: the table accepted `--out=FILE` and the
+ * value was looked up as the token after `--out`, so `doctor --out=x` wrote
+ * nothing and exited 0, and `submit --category=Widgets` said the flag was
+ * missing.
+ */
 function option(args, name) {
-  const index = args.indexOf(name)
-  return index >= 0 ? args[index + 1] : undefined
+  let value
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === name) value = args[index + 1]
+    else if (args[index].startsWith(`${name}=`)) value = args[index].slice(name.length + 1)
+  }
+  return value
 }
 
 /** The bare arguments, with every valued option's value (options.mjs, one table) left out. */
@@ -169,7 +194,8 @@ async function cmdSubmit(args) {
       const usage = error.usage
       if (json) {
         process.stdout.write(`${JSON.stringify({ usage }, null, 2)}\n`)
-        process.exit(2)
+        process.exitCode = 2
+        return
       }
       const flags = usage.missing.join(" and ")
       fail("usage", `submit needs ${flags}: ${usage.missing.length === 1 ? "it is" : "they are"} an editorial choice nobody else can make, from the pinned form's own lists.`, 2,
@@ -185,7 +211,7 @@ async function cmdSubmit(args) {
   emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : reportText(args, renderSubmit, result))
   // Three outcomes, two exit codes: `ready` and `listed` are both healthy
   // states, and only a refusal is a 1.
-  process.exit(result.outcome === "refused" ? 1 : 0)
+  process.exitCode = result.outcome === "refused" ? 1 : 0
 }
 
 async function cmdWatch(args) {
@@ -224,7 +250,7 @@ async function cmdWatch(args) {
   spinner.done()
   const render = result.mode === "list" ? renderWatchList : result.mode === "all" ? renderWatchAll : renderWatch
   emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : reportText(args, render, result))
-  process.exit(result.verdict?.state === "unknown" || result.summary?.unknown > 0 ? 2 : 0)
+  process.exitCode = result.verdict?.state === "unknown" || result.summary?.unknown > 0 ? 2 : 0
 }
 
 async function cmdFrontDoor() {
@@ -243,15 +269,16 @@ async function cmdSetup(args) {
   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)
+    process.exitCode = result.state === "ok" ? 0 : 1
+    return
   }
   const result = await setup({ repoRoot: ROOT, entryPoint: resolve(ROOT, "bin/omakit"), yes: args.includes("--yes") })
-  process.exit(result.ok ? 0 : 1)
+  process.exitCode = result.ok ? 0 : 1
 }
 
 async function cmdUpgrade(args) {
   const result = await upgrade({ repoRoot: ROOT, dryRun: args.includes("--dry-run") })
-  process.exit(result.ok ? 0 : 1)
+  process.exitCode = result.ok ? 0 : 1
 }
 
 async function cmdDoctor(args) {
@@ -259,7 +286,7 @@ async function cmdDoctor(args) {
   const result = await doctor({ repoRoot: ROOT, offline: args.includes("--offline"), onPhase: spinner.phase })
   spinner.done()
   emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : reportText(args, renderDoctor, result))
-  process.exit(result.problems ? 1 : 0)
+  process.exitCode = result.problems ? 1 : 0
 }
 
 async function cmdVerify(args) {
@@ -325,7 +352,7 @@ async function cmdParity(args) {
   } catch (error) {
     failFrom(error)
   }
-  process.exit(ok ? 0 : 1)
+  process.exitCode = ok ? 0 : 1
 }
 
 function notAudited(message, remedy = null, exit = 1) {
@@ -359,7 +386,50 @@ async function cmdAudit(args) {
   }
   if (parsed.options.has("--json")) process.stdout.write(json)
   else process.stdout.write(`${renderAudit(document)}\n`)
-  process.exit(document.ok ? 0 : 1)
+  process.exitCode = document.ok ? 0 : 1
+}
+
+/**
+ * `omakit inspect`: a report, exit 0 whatever it observed; exit 2 when the
+ * target could not be read (no directory, no Git checkout, no commit, no
+ * manifest), in the one failure register. There is no exit status for
+ * "found something", because finding something is the normal outcome.
+ * `--out` writes the document to a file beside whatever stdout gets, the
+ * way `audit --out` does.
+ */
+async function cmdInspect(args) {
+  const parsed = checkArgs(args, ACCEPTED.inspect)
+  if (parsed.offending !== null) fail("usage", `${parsed.reason}. Accepted: ${acceptedWords("inspect")}.`, 2, "omakit inspect <plugin-dir> [--full] [--json] [--out FILE] [--offline] [--allow-dirty]")
+  const target = parsed.positionals[0]
+  if (!target) fail("usage", "inspect needs a plugin directory: `omakit inspect <plugin-dir>`", 2, "omakit inspect <plugin-dir> [--full] [--json] [--out FILE] [--offline] [--allow-dirty]")
+  const spinner = spinnerFor(args)
+  let document
+  try {
+    document = await inspectPlugin({
+      repoRoot: ROOT,
+      target,
+      offline: parsed.options.has("--offline"),
+      allowDirty: parsed.options.has("--allow-dirty"),
+      omakitVersion: VERSION,
+      onPhase: spinner.phase,
+    })
+  } catch (error) {
+    spinner.done()
+    if (error?.code && typeof error.code === "string") {
+      fail(error.code, error.message, NOT_READABLE.includes(error.code) ? 2 : 1, error.remedy || REMEDY[error.code])
+    }
+    throw error
+  }
+  spinner.done()
+  const json = `${JSON.stringify(document, null, 2)}\n`
+  const out = parsed.options.get("--out")
+  if (out) {
+    mkdirSync(dirname(resolve(out)), { recursive: true })
+    writeFileSync(resolve(out), json)
+  }
+  if (parsed.options.has("--json")) process.stdout.write(json)
+  else process.stdout.write(`${renderInspect(document, { full: parsed.options.has("--full") })}\n`)
+  process.exitCode = 0
 }
 
 /**
@@ -399,7 +469,7 @@ async function cmdWeigh(args) {
       throw error
     }
     process.stdout.write(json ? `${JSON.stringify(list.rows, null, 2)}\n` : `${renderList(list)}\n`)
-    process.exit(0)
+    return
   }
   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)
@@ -466,7 +536,6 @@ async function cmdWeigh(args) {
   } else {
     process.stdout.write(`\n${renderWeigh(document)}\n`)
   }
-  process.exit(0)
 }
 
 const VERSION = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8")).version
@@ -539,6 +608,8 @@ if (command === "setup") {
   await cmdAudit(rest)
 } else if (command === "weigh") {
   await cmdWeigh(rest)
+} else if (command === "inspect") {
+  await cmdInspect(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/github.mjs

@@ -180,10 +180,10 @@ export async function authenticatedUser() {
 }
 
 /** Repository issues by their creator. PRs are excluded; pagination never silently truncates. */
-export async function repositoryIssues(owner, repository, creator, { readJson = getJson, maxPages = 100 } = {}) {
+export async function repositoryIssues(owner, repository, creator, { readJson = getJson, maxPages = 100, labels } = {}) {
   const all = []
   for (let page = 1; page <= maxPages; page += 1) {
-    const query = new URLSearchParams({ creator, state: "open", sort: "updated", direction: "desc", per_page: "100", page: String(page) })
+    const query = new URLSearchParams({ ...(creator ? { creator } : {}), ...(labels ? { labels } : {}), state: "open", sort: "updated", direction: "desc", per_page: "100", page: String(page) })
     const batch = await readJson(`https://api.github.com/repos/${owner}/${repository}/issues?${query}`)
     if (!Array.isArray(batch)) throw new GitHubError("github-unavailable", "GitHub did not return an issue list")
     all.push(...batch.filter((item) => !item.pull_request))
@@ -205,6 +205,17 @@ export async function issueComments(owner, repository, number, maxPages = 10, re
   throw new GitHubError("comments-incomplete", `Issue #${number} exceeded ${maxPages} comment pages; its latest baseline cannot be determined`)
 }
 
+/** Compare exact validated snapshots. The API caps its file list at 300: never classify a truncated diff. */
+export async function compareCommits(repositoryUrl, previous, validated, { readJson = getJson } = {}) {
+  const match = String(repositoryUrl).match(/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?\/?$/)
+  if (!match || ![previous, validated].every((commit) => /^[a-f0-9]{40}$/i.test(commit))) throw new GitHubError("usage", "compare needs a repository and two full commit identifiers")
+  const url = `https://api.github.com/repos/${match[1]}/${match[2]}/compare/${previous}...${validated}?per_page=1`
+  const result = await readJson(url)
+  if (!["ahead", "identical"].includes(result?.status)) throw new GitHubError("compare-not-forward", "validated snapshots are not a forward comparison")
+  if (!Array.isArray(result.files) || result.files.length >= 300) throw new GitHubError("compare-incomplete", "compare file list unavailable or at the 300-file API limit")
+  return { url, files: result.files }
+}
+
 /**
  * The current default-branch HEAD of a repository.
  *

package/tools/marketplace/local-transport.mjs

@@ -92,10 +92,14 @@ function fileResponse(buffer, range) {
 }
 
 /**
- * @param {{ repoDir: string, repoUrl: string, commitSha: string, defaultBranch?: string }} options
+ * @param {{ repoDir: string, repoUrl: string, commitSha: string, defaultBranch?: string, subdir?: string }} options
+ *   `subdir` names a directory below the repository root whose tree is served
+ *   as the whole tree: the commit's `<sha>:<subdir>` tree, paths relative to
+ *   it. `omakit inspect` uses it for a plugin kept below the root of a larger
+ *   repository, so the baseline sees the plugin's tree and never the root's.
  * @returns {{ fetchImpl: Function, stats: { api: number, raw: number } }}
  */
-export function createLocalTransport({ repoDir, repoUrl, commitSha, defaultBranch }) {
+export function createLocalTransport({ repoDir, repoUrl, commitSha, defaultBranch, subdir = "" }) {
   const { owner, repository } = parseRepoUrl(repoUrl)
   let commit = ""
   try {
@@ -106,8 +110,16 @@ export function createLocalTransport({ repoDir, repoUrl, commitSha, defaultBranc
   if (commit.toLowerCase() !== String(commitSha).toLowerCase()) {
     throw new Error(`local transport: ${repoDir} does not contain commit ${commitSha}`)
   }
-  const treeSha = git(repoDir, ["rev-parse", `${commit}^{tree}`]).trim()
-  const tree = readTree(repoDir, commit)
+  const root = subdir ? `${commit}:${subdir.replace(/\/+$/, "")}` : `${commit}^{tree}`
+  let treeSha = ""
+  try {
+    treeSha = git(repoDir, ["rev-parse", "--verify", "-q", root]).trim()
+    if (git(repoDir, ["cat-file", "-t", treeSha]).trim() !== "tree") treeSha = ""
+  } catch {
+    treeSha = ""
+  }
+  if (!treeSha) throw new Error(`local transport: ${repoDir} has no directory ${subdir} at commit ${commitSha}`)
+  const tree = readTree(repoDir, treeSha)
   const byPath = new Map(tree.map((entry) => [entry.path, entry]))
   const branch = defaultBranch
     || (() => {

package/tools/marketplace/measure-review-cost.mjs

@@ -0,0 +1,39 @@
+// Reproduce M9 with GET-only issue discovery and compare reads. No sampling.
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { MARKETPLACE_PIN } from "./pin.mjs"
+import { repositoryIssues } from "./github.mjs"
+import { liveRegistry } from "./registry.mjs"
+import { reviewPolicy } from "./review-cost.mjs"
+import { validationWatchAll } from "./watch.mjs"
+
+export async function measureReviewCost(repoRoot) {
+  const policy = await reviewPolicy(repoRoot)
+  const registry = await liveRegistry({ repoRoot })
+  if (registry.source !== "head") throw new Error(`cannot measure at HEAD: ${registry.reason}`)
+  const [owner, repository] = new URL(MARKETPLACE_PIN.repository).pathname.slice(1).split("/")
+  const openedAt = new Date().toISOString()
+  const subjects = await repositoryIssues(owner, repository, undefined, { labels: policy.updateLabel })
+  const issues = subjects.filter((subject) => subject.state === "open" && !subject.pull_request).map((subject) => ({
+    number: subject.number, url: `${MARKETPLACE_PIN.repository}/issues/${subject.number}`, title: subject.title,
+    state: subject.state, labels: subject.labels.map((label) => typeof label === "string" ? label : label.name),
+  }))
+  // Only the manual-review subset needs comment reads and comparisons. No plugin HEAD reads.
+  const manual = issues.filter((subject) => subject.labels.includes(policy.reviewLabel))
+  const batch = await validationWatchAll({ repoRoot, discovery: { account: null, marketplace: MARKETPLACE_PIN.repository, issues: manual },
+    readRegistry: async () => registry, github: { defaultBranchHead: async () => null } })
+  const counts = batch.reviewCostSummary
+  return {
+    measurement: "M9", openedAt, completedAt: new Date().toISOString(), marketplace: MARKETPLACE_PIN.repository,
+    marketplaceHead: registry.commit, command: "node tools/marketplace/measure-review-cost.mjs", sample: false,
+    pluginUpdates: issues.length, manualQueue: manual.length, manualQueueShare: issues.length ? manual.length / issues.length : null,
+    docsOnly: counts.docsOnly, compared: counts.compared, skipped: counts.skipped.length,
+    docsOnlyShareOfCompared: counts.compared ? counts.docsOnly / counts.compared : null,
+    docsOnlyShareOfManualQueue: counts.skipped.length || !manual.length ? null : counts.docsOnly / manual.length,
+    rows: batch.issues.map((row) => ({ issue: row.issue.number, ...row.documentationDiff })),
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  process.stdout.write(`${JSON.stringify(await measureReviewCost(resolve(process.cwd())), null, 2)}\n`)
+}

package/tools/marketplace/measure-staleness.mjs

@@ -0,0 +1,76 @@
+// M6 reproduction: open author-fixes issues, bot marker against commits.atom.
+// All remote reads use the existing GET-only client. Unknowns stay unknown.
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { MARKETPLACE_PIN } from "./pin.mjs"
+import { repositoryIssues, getText } from "./github.mjs"
+import { validationWatch } from "./watch.mjs"
+
+export function atomHead(feed, source) {
+  const commit = feed.match(/<id>tag:github\.com,2008:Grit::Commit\/([0-9a-f]{40})<\/id>/i)?.[1]
+    || feed.match(/\/commit\/([0-9a-f]{40})/i)?.[1]
+  if (!commit) throw new Error("No full HEAD commit in commits.atom")
+  return { source, commit: commit.toLowerCase(), branch: null,
+    committedAt: feed.match(/<updated>([^<]+)<\/updated>/)?.[1] || null }
+}
+
+export function stalenessCounts(rows) {
+  const stale = rows.filter((row) => row.verdict === "stale").length
+  const current = rows.filter((row) => row.verdict === "current").length
+  const compared = stale + current
+  return { total: rows.length, compared, stale, current, unknown: rows.length - compared,
+    staleShareOfCompared: compared ? stale / compared : null,
+    staleShareOfPopulation: compared === rows.length && rows.length ? stale / rows.length : null }
+}
+
+export async function measureStaleness(repoRoot, { discover = repositoryIssues, watch = validationWatch, readText = getText } = {}) {
+  const openedAt = new Date().toISOString()
+  const [owner, repository] = new URL(MARKETPLACE_PIN.repository).pathname.slice(1).split("/")
+  const batches = await Promise.all(["needs-fixes", "security-needs-fixes"].map((labels) => discover(owner, repository, undefined, { labels })))
+  const subjects = [...new Map(batches.flat().map((subject) => [subject.number, subject])).values()]
+    .filter((subject) => subject.state === "open" && !subject.pull_request)
+    .sort((a, b) => a.number - b.number)
+  const heads = new Map()
+  function readHead(url) {
+    if (!heads.has(url)) {
+      const source = `${url.replace(/\/$/, "")}/commits.atom`
+      heads.set(url, Promise.resolve().then(async () => atomHead(await readText(source, "application/atom+xml"), source)))
+    }
+    return heads.get(url)
+  }
+  const rows = new Array(subjects.length)
+  let next = 0
+  async function worker() {
+    while (next < subjects.length) {
+      const index = next++
+      const subject = subjects[index]
+      const issueUrl = `${MARKETPLACE_PIN.repository}/issues/${subject.number}`
+      const observedAt = new Date().toISOString()
+      try {
+        const report = await watch({ repoRoot, issueUrl, github: { issue: async () => subject, defaultBranchHead: readHead } })
+        rows[index] = { issue: subject.number, issueUrl, observedAt, completedAt: new Date().toISOString(),
+          repository: report.plugin.repository, validatedCommit: report.validated?.commit || null,
+          validationSource: report.validated?.source || null, validatedAt: report.validated?.checkedAt || null,
+          validationCommentsSource: `https://api.github.com/repos/${owner}/${repository}/issues/${subject.number}/comments`,
+          defaultBranchHead: report.head?.commit || null, headSource: report.head?.source || null,
+          verdict: report.verdict.state,
+          reason: report.verdict.state === "unknown" ? report.verdict.summary : null }
+      } catch (error) {
+        rows[index] = { issue: subject.number, issueUrl, observedAt, completedAt: new Date().toISOString(),
+          repository: null, validatedCommit: null, defaultBranchHead: null, verdict: "unknown",
+          reason: `${error.code || "read-unavailable"}: ${error.message}` }
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, subjects.length) }, worker))
+  return { measurement: "M6", date: openedAt.slice(0, 10), openedAt, completedAt: new Date().toISOString(),
+    marketplace: MARKETPLACE_PIN.repository, marketplacePin: MARKETPLACE_PIN.commit,
+    command: "node tools/marketplace/measure-staleness.mjs", sample: false,
+    population: "All open non-PR marketplace issues labelled needs-fixes or security-needs-fixes at discovery",
+    method: "Latest bot security-baseline full commit against default-branch commits.atom HEAD; missing full markers or feeds are unknown; unequal commits are stale, without a claim about ancestry",
+    ...stalenessCounts(rows), rows }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  process.stdout.write(`${JSON.stringify(await measureStaleness(resolve(process.cwd())), null, 2)}\n`)
+}

package/tools/marketplace/options.mjs

@@ -28,6 +28,7 @@ export const ACCEPTED = Object.freeze({
   doctor: Object.freeze({ valued: ["--out"], flags: ["--offline", "--json"], positionals: 0 }),
   parity: Object.freeze({ valued: ["--count", "--offset", "--out"], flags: [], positionals: 0 }),
   audit: Object.freeze({ valued: ["--out"], flags: ["--drift", "--json", "--offline"], positionals: 1 }),
+  inspect: Object.freeze({ valued: ["--out"], flags: ["--full", "--json", "--offline", "--allow-dirty"], positionals: 1 }),
   weigh: Object.freeze({ valued: ["--runs", "--window", "--settle", "--out"], flags: ["--all", "--list", "--json", "--yes"], positionals: 1 }),
 })