omakit 0.3.0 → 0.4.0

package/README.md

@@ -25,7 +25,7 @@ See [docs/INSTALL.md](docs/INSTALL.md) for the clone route, PATH, requirements a
 | --- | --- |
 | [`omakit setup`](docs/COMMANDS.md) | The environment, the pin, tab completion, and what to try first. |
 | [`omakit submit <plugin-repo>`](docs/SUBMIT.md) | Every check, the issue title and body; asks for a category and tags at a terminal. |
-| [`omakit watch <issue-url>`](docs/VALIDATION_WATCH.md) | The commit the marketplace validated, against the plugin's current HEAD. |
+| [`omakit watch [<issue-url>]`](docs/VALIDATION_WATCH.md) | Pick your marketplace issues, list them, or check all with `--all`. |
 | [`omakit verify <plugin-repo>`](docs/COMMANDS.md) | The official security baseline over the local transport; `--json` for the document. |
 | [`omakit parity`](docs/COMMANDS.md) | The baseline over GitHub versus the local transport, on real listings; writes the evidence. |
 | [`omakit audit [<plugin>]`](docs/AUDIT.md) | Installed third-party commits against the exact commits the marketplace validated. |
@@ -35,6 +35,11 @@ See [docs/INSTALL.md](docs/INSTALL.md) for the clone route, PATH, requirements a
 | [`omakit upgrade`](docs/COMMANDS.md) | Updates omakit through its own installer: npm, or a fast-forward. |
 | [`omakit help --agent`](docs/COMMANDS.md) | The operating instructions, for the agent running this. |
 
+Normal terminal use also checks for a newer npm release at most once daily
+and shows the upgrade command. It installs nothing automatically; scripts
+and JSON stay quiet. `DISABLE_UPDATE_NOTIFIER=1` disables the notice, and
+`omakit doctor` checks explicitly. [Update behaviour](docs/INSTALL.md#updating).
+
 ### `submit`
 
 ```bash
@@ -51,10 +56,15 @@ Read more: [docs/SUBMIT.md](docs/SUBMIT.md).
 
 ```bash
 omakit watch <submission-issue-url>
+omakit watch --all
+omakit watch --list
+omakit watch                 # choose one or several issues at a terminal
 ```
 
 It decides whether the marketplace validated the plugin's current commit; [73% of parked submissions have a HEAD the marketplace never saw](docs/MEASUREMENTS.md).
 
+Account-wide discovery uses your signed-in `gh` account and reads your open marketplace issues. `--user <login>` reads another public account. Batch output includes baseline results, labels and the latest human discussion; `current` compares commits and does not imply approval or publication. Each command takes one snapshot and posts nothing.
+
 ![omakit watch reporting that a validated commit has fallen behind](docs/media/watch.gif)
 
 Read more: [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omakit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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/skills/omarchy-plugin-validation-watch/SKILL.md

@@ -27,6 +27,8 @@ push came after a review comment had also commented: engaged, and stuck.
 
 ```bash
 omakit watch https://github.com/omacom/omarchy-plugin-marketplace/issues/<number>
+omakit watch --all --json
+omakit watch --list --json
 ```
 
 If `omakit` is not installed: `npm install --global omakit` (Omarchy ships Node
@@ -35,6 +37,10 @@ the install, `"$(npm prefix --global)/bin/omakit" setup` prints the one line
 that puts npm's bin on PATH. `omakit upgrade` keeps it current through npm.
 Add `--json` for a machine-readable result.
 
+Use `--all --json` to discover and check every open marketplace issue authored by the signed-in `gh` account. `--list --json` discovers issue URLs without reading every plugin; use an individual URL for focused follow-up. `--user <login>` selects an explicit public author. A bare `omakit watch` opens a numbered picker only at a terminal; an agent must pass a URL, `--all` or `--list` and never wait on keyboard input.
+
+Inspect every batch row, including read errors and unknown results; a successful row cannot stand in for a failed one. `current` only says the commit matches HEAD. Read the baseline outcome, labels and latest discussion to understand outstanding work; never equate it with approval, publication or restored catalog verification. A run is a single read-only snapshot, not a background monitor.
+
 Read-only. It does not comment, label, or edit anything, and it cannot. It reads
 the default branch through the REST API when a credential is available, taking
 it from the operator's `gh` login (which itself honours `GH_TOKEN` and

package/tools/marketplace/README.md

@@ -26,6 +26,7 @@ local commit through the transport seam the marketplace tests itself
 | `github.mjs` | Read-only GitHub access. GET only. The credential is your `gh` login, read through one frozen `gh auth token` call, and is never written anywhere. |
 | `style.mjs` | The visual system, defined once: the palette, the status vocabulary, the block ramp, the columns, the motion budgets, and the composition helpers every command draws with. Six states: `▁ ok`, `█ FAIL`, `▓ note`, `░ info`, `▒ ?` for a check that could not be made, and `▔ skip` for a check a flag said not to make, the floor's ink at the ceiling so it is never read as a pass. `docs/TUI.md` explains it. |
 | `report.mjs` | Text rendering of submit, watch, doctor and verify for the agent that runs this tool, and the person reading over its shoulder. |
+| `update-check.mjs` | A passive npm-release notice during normal terminal use, throttled to one check per day with a one-second network budget. Stores only installed/latest version metadata and time under XDG_STATE_HOME/omakit. Offline, JSON, pipes, help and CI skip it; DISABLE_UPDATE_NOTIFIER disables it. Version precedence and the registry GET are shared with doctor/upgrade. |
 | `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. |
@@ -99,3 +100,5 @@ online, the subject's default-branch HEAD and the marketplace's current
 registry, and `--offline` turns both off; `verify` needs no network at all
 beyond fetching a reviewer-mode subject, and `tests/parity/offline.mjs` proves
 it.
+
+`watch --list` discovers the signed-in account's open marketplace issues through `github.mjs`; `--user` bypasses the account lookup. `watch --all` runs the existing single-issue watch with four workers and shared repository HEAD promises, preserving each read failure. A bare terminal invocation uses `ask.mjs` to choose one or several issues. `report.mjs` composes the list and batch views; all options remain in `options.mjs` and `usage.mjs`, which also generate completion. The batch JSON retains complete single-issue reports; `current` compares commits and never substitutes for review or publication.

package/tools/marketplace/ask.mjs

@@ -17,6 +17,7 @@
 import { createInterface } from "node:readline"
 import { colourEnabled, STEP, action, styler, wrap } from "./style.mjs"
 import { resolveCategory, resolveTags } from "./form.mjs"
+import { watchIssueTitle } from "./watch.mjs"
 
 export class AskError extends Error {
   constructor(message) {
@@ -49,11 +50,13 @@ function reader(input) {
 }
 
 /** Ask one question until an answer resolves; `parse` returns { ok, value } or { ok: false, reason }. */
-async function question(lines, output, c, { name, heading, options, defaultIndexes, parse }) {
+async function question(lines, output, c, { name, heading, options, defaultIndexes, parse, wrapOptions = false, eofRemedy }) {
   const step = " ".repeat(STEP)
   output.write(`${wrap(heading, {}, c).join("\n")}\n`)
   for (const [index, option] of options.entries()) {
-    output.write(`${step}${c("typeable", String(index + 1).padStart(2))}  ${option}\n`)
+    output.write(wrapOptions
+      ? `${wrap(`${String(index + 1).padStart(2)} ${option}`, { indent: STEP }, c).join("\n")}\n`
+      : `${step}${c("typeable", String(index + 1).padStart(2))}  ${option}\n`)
   }
   const fallback = defaultIndexes.length ? defaultIndexes.map((index) => index + 1).join(",") : null
   const prompt = `${action(fallback ? `${name} [${fallback}]:` : `${name}:`, c, { indent: 0 })[0]} `
@@ -62,7 +65,7 @@ async function question(lines, output, c, { name, heading, options, defaultIndex
     const raw = await lines.next()
     if (raw === null) {
       output.write("\n")
-      throw new AskError(`stdin ended before the ${name} was answered; pass --${name} on the command line`)
+      throw new AskError(`stdin ended before the ${name} was answered; ${eofRemedy || `pass --${name} on the command line`}`)
     }
     const text = raw.trim() || (fallback ?? "")
     const parsed = parse(text)
@@ -138,3 +141,30 @@ export async function askChoices({ contract, defaults, missing, input = process.
   }
   return answers
 }
+
+/** Select one or several discovered issues; nothing is written or opened. */
+export async function askWatchIssues({ issues, input = process.stdin, output = process.stderr, colour = colourEnabled(output) }) {
+  const c = styler(colour)
+  const lines = reader(input)
+  try {
+    return await question(lines, output, c, {
+      name: "issues",
+      heading: "Choose list numbers, comma-separated; all checks every issue, q cancels.",
+      options: issues.map((issue) => `#${issue.number} ${watchIssueTitle(issue.title)}`),
+      defaultIndexes: [],
+      wrapOptions: true,
+      eofRemedy: "pass an issue URL, --all or --list on the command line",
+      parse: (text) => {
+        if (text.toLowerCase() === "q") return { ok: true, value: [] }
+        if (text.toLowerCase() === "all") return { ok: true, value: issues }
+        const indexes = text.split(",").map((value) => value.trim())
+        if (indexes.some((value) => !/^\d+$/.test(value) || Number(value) < 1 || Number(value) > issues.length)) {
+          return { ok: false, reason: `Answer with list numbers from 1 to ${issues.length}, all, or q.` }
+        }
+        return { ok: true, value: [...new Set(indexes.map(Number))].map((index) => issues[index - 1]) }
+      },
+    })
+  } finally {
+    lines.close()
+  }
+}

package/tools/marketplace/cli.mjs

@@ -21,15 +21,16 @@ import { ensurePin, MARKETPLACE_PIN, requirePin } from "./pin.mjs"
 import { marketplaceBaselineSection } from "./verify.mjs"
 import { resolveSubject, SubjectError } from "../subject/resolve.mjs"
 import { submitPreflight } from "./submit.mjs"
-import { askChoices } from "./ask.mjs"
-import { validationWatch } from "./watch.mjs"
-import { renderSubmit, renderWatch, renderDoctor, renderVerify } from "./report.mjs"
+import { askChoices, askWatchIssues } from "./ask.mjs"
+import { validationWatch, discoverWatchIssues, validationWatchAll } from "./watch.mjs"
+import { renderSubmit, renderWatch, renderWatchList, renderWatchAll, renderDoctor, renderVerify } from "./report.mjs"
 import { consequence } from "./preflight.mjs"
 import { doctor } from "./doctor.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 { updateCheckEnabled, updateNotice } from "./update-check.mjs"
 import { progress } from "./progress.mjs"
 import { banner, bannerEnabled } from "./banner.mjs"
 import { COMMANDS, renderSummary, renderUsage, TAGLINE } from "./usage.mjs"
@@ -62,6 +63,7 @@ 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.",
+  "login-required": "gh auth login",
   "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.",
 })
@@ -180,18 +182,41 @@ async function cmdSubmit(args) {
 
 async function cmdWatch(args) {
   const issueUrl = positionals(args)[0]
-  if (!issueUrl) fail("usage", "watch needs an issue: `omakit watch <issue-url>`", 2)
+  const all = args.includes("--all")
+  const list = args.includes("--list")
+  const user = option(args, "--user")
+  const interactive = !args.includes("--json") && !option(args, "--out") && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)
+  if ((all && list) || (issueUrl && (all || list || user !== undefined))) {
+    fail("usage", "Use an issue URL, --all, or --list; --user belongs to account-wide discovery.", 2)
+  }
+  if (!issueUrl && !all && !list && !interactive) {
+    fail("usage", "watch needs an issue or a mode: `omakit watch <issue-url>`, `omakit watch --all`, or `omakit watch --list`. A terminal can pick issues with `omakit watch`.", 2)
+  }
   const spinner = spinnerFor(args)
   let result
   try {
-    result = await validationWatch({ repoRoot: ROOT, issueUrl, onPhase: spinner.phase })
+    if (issueUrl) {
+      result = await validationWatch({ repoRoot: ROOT, issueUrl, onPhase: spinner.phase })
+    } else {
+      const discovery = await discoverWatchIssues({ user, onPhase: spinner.phase })
+      if (list) {
+        result = discovery
+      } else {
+        if (!all && discovery.issues.length) {
+          spinner.done()
+          discovery.issues = await askWatchIssues({ issues: discovery.issues })
+        }
+        result = await validationWatchAll({ repoRoot: ROOT, discovery, onPhase: spinner.phase })
+      }
+    }
   } catch (error) {
     spinner.done()
     failFrom(error)
   }
   spinner.done()
-  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : renderWatch(result))
-  process.exit(result.verdict.state === "unknown" ? 2 : 0)
+  const render = result.mode === "list" ? renderWatchList : result.mode === "all" ? renderWatchAll : renderWatch
+  emit(args, args.includes("--json") ? `${JSON.stringify(result, null, 2)}\n` : render(result))
+  process.exit(result.verdict?.state === "unknown" || result.summary?.unknown > 0 ? 2 : 0)
 }
 
 async function cmdFrontDoor() {
@@ -460,6 +485,11 @@ const [command, ...rest] = process.argv.slice(2)
 // 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 (updateCheckEnabled({ command, args: rest, stdinTTY: process.stdin.isTTY, stdoutTTY: process.stdout.isTTY, stderrTTY: process.stderr.isTTY })) {
+  const notice = await updateNotice({ repoRoot: ROOT, version: VERSION })
+  if (notice) process.stderr.write(`${wrap(notice, {}, styler(colourEnabled(process.stderr))).join("\n")}\n`)
+}
+
 if (command !== "setup" && process.stderr.isTTY) {
   const notice = staleCompletionNotice({ version: VERSION })
   if (notice) process.stderr.write(`${styler(colourEnabled(process.stderr))("label", notice)}\n`)

package/tools/marketplace/doctor.mjs

@@ -42,7 +42,7 @@ import { join } from "node:path"
 import { MARKETPLACE_PIN, PIN_PATHS, marketplacePinDir, pinDiskUsage, pinIsSparse, requirePin } from "./pin.mjs"
 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 { compareVersions, NPM_REGISTRY, registryLatest, upgradeCommand } from "./upgrade.mjs"
 import { pathHint } from "./path-hint.mjs"
 import { completionStatus } from "./completion-check.mjs"
 
@@ -205,11 +205,17 @@ export async function doctor({ repoRoot, offline = false, onPhase, env = process
     phase("asking the npm registry for the newest published version")
     const published = await latestVersion(self.name)
     if (published.version) {
-      const current = published.version === self.version
-      versionCheck(current ? "ok" : "advice",
-        current ? `${self.version}, the newest published version` : `${self.version}; ${published.version} is published`,
-        current ? null : `run \`${upgradeCommand(repoRoot, self.name)}\``,
-        published.version, NPM_REGISTRY)
+      const comparison = compareVersions(published.version, self.version)
+      if (comparison === null) {
+        versionCheck("unknown", `${self.version}; the installed or published version is invalid`)
+      } else {
+        versionCheck(comparison > 0 ? "advice" : "ok",
+          comparison === 0 ? `${self.version}, the newest published version`
+            : comparison < 0 ? `${self.version}; ahead of the newest published version ${published.version}`
+              : `${self.version}; ${published.version} is published`,
+          comparison > 0 ? `run \`${upgradeCommand(repoRoot, self.name)}\`` : null,
+          published.version, NPM_REGISTRY)
+      }
     } else {
       versionCheck("unknown", `${self.version}; could not read the npm registry (${published.error?.code || "error"})`)
     }

package/tools/marketplace/github.mjs

@@ -109,7 +109,7 @@ export function token() {
 /** The one host the borrowed gh credential may be sent to. */
 export const CREDENTIAL_HOST = "api.github.com"
 
-async function get(url, { accept } = {}) {
+async function get(url, { accept, signal } = {}) {
   const { host } = new URL(url)
   // The credential is GitHub's and goes to GitHub's API and nowhere else.
   // Measured before this held: `omakit upgrade` and `doctor` sent the gh
@@ -125,7 +125,7 @@ async function get(url, { accept } = {}) {
   if (auth) headers.authorization = `Bearer ${auth}`
   let response
   try {
-    response = await fetch(url, { method: "GET", headers, redirect: "follow" })
+    response = await fetch(url, { method: "GET", headers, redirect: "follow", ...(signal ? { signal } : {}) })
   } catch (error) {
     // Node reports every transport failure as "fetch failed" with the real
     // reason in `cause`. A person needs the reason, and the CLI keys its
@@ -150,8 +150,8 @@ async function get(url, { accept } = {}) {
   return response
 }
 
-export async function getJson(url) {
-  return (await get(url)).json()
+export async function getJson(url, options) {
+  return (await get(url, options)).json()
 }
 
 export async function getText(url, accept) {
@@ -171,17 +171,38 @@ export async function issue(owner, repository, number) {
   return getJson(`https://api.github.com/repos/${owner}/${repository}/issues/${number}`)
 }
 
-export async function issueComments(owner, repository, number, maxPages = 10) {
+/** Resolve the account whose credential gh lent us; never persist it. */
+export async function authenticatedUser() {
+  if (!token()) throw new GitHubError("login-required", "Account-wide watch needs your GitHub login. Run `gh auth login`, or pass --user <login> to read a public account.")
+  const user = await getJson("https://api.github.com/user")
+  if (!user?.login) throw new GitHubError("github-unavailable", "GitHub did not return the signed-in account's login")
+  return user.login
+}
+
+/** Repository issues by their creator. PRs are excluded; pagination never silently truncates. */
+export async function repositoryIssues(owner, repository, creator, { readJson = getJson, maxPages = 100 } = {}) {
+  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 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))
+    if (batch.length < 100) return all
+  }
+  throw new GitHubError("issue-list-incomplete", `The issue list exceeded ${maxPages} pages; no complete account-wide result is available`)
+}
+
+export async function issueComments(owner, repository, number, maxPages = 10, readJson = getJson) {
   const all = []
   for (let page = 1; page <= maxPages; page += 1) {
-    const batch = await getJson(
+    const batch = await readJson(
       `https://api.github.com/repos/${owner}/${repository}/issues/${number}/comments?per_page=100&page=${page}`,
     )
-    if (!Array.isArray(batch) || !batch.length) break
+    if (!Array.isArray(batch)) throw new GitHubError("github-unavailable", "GitHub did not return issue comments")
     all.push(...batch)
-    if (batch.length < 100) break
+    if (batch.length < 100) return all
   }
-  return all
+  throw new GitHubError("comments-incomplete", `Issue #${number} exceeded ${maxPages} comment pages; its latest baseline cannot be determined`)
 }
 
 /**

package/tools/marketplace/options.mjs

@@ -21,7 +21,7 @@ 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 }),
+  watch: Object.freeze({ valued: ["--out", "--user"], flags: ["--json", "--all", "--list"], 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 }),

package/tools/marketplace/report.mjs

@@ -21,6 +21,7 @@ import {
   action, colourEnabled, COLUMNS, continuation, field, GUTTER, labelled, mark, section, STEP, styler, verdict, width, wrap,
 } from "./style.mjs"
 import { withHomeAbbreviated } from "./paths.mjs"
+import { watchIssueTitle } from "./watch.mjs"
 
 const body = " ".repeat(GUTTER)
 
@@ -244,6 +245,50 @@ export function renderWatch(result, { colour = colourEnabled() } = {}) {
   return out.join("\n")
 }
 
+/** Discovery is cheap: issue metadata and repeatable commands, no plugin HEAD reads. */
+export function renderWatchList(result, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = [...field("account", result.account, c), ...field("issues", `${result.issues.length} open marketplace issue(s)`, c), ""]
+  for (const issue of result.issues) {
+    out.push(...wrap(`#${issue.number} ${watchIssueTitle(issue.title)}`, {}, c))
+    out.push(...field("state", `${issue.state}${issue.labels.length ? `; labels ${issue.labels.map(watchIssueTitle).join(", ")}` : ""}`, c))
+    out.push(...action(`omakit watch ${issue.url}`, c, { indent: 0 }), "")
+  }
+  if (!result.issues.length) out.push(...wrap("No open marketplace issues found for this account.", {}, c))
+  else out.push(...action(`omakit watch --all --user ${result.account}`, c, { indent: 0 }))
+  return out.join("\n")
+}
+
+/** Compact batch report; exact commits and full discussion remain in JSON. */
+export function renderWatchAll(result, { colour = colourEnabled() } = {}) {
+  const c = styler(colour)
+  const out = [...field("account", result.account, c), ...field("issues", `${result.summary.total} checked; ${result.summary.current} current, ${result.summary.stale} stale, ${result.summary.unknown} unknown`, c), ""]
+  for (const row of result.issues) {
+    const state = row.report?.verdict.state || "unknown"
+    const style = { current: "pass", stale: "fail", unknown: "unknown" }[state]
+    out.push(...verdict(style, state.toUpperCase(), `#${row.issue.number} ${watchIssueTitle(row.report?.read.title || row.issue.title)}`, c))
+    out.push(...field("issue", row.issue.url, c, { wrapValue: false }))
+    if (row.error) {
+      out.push(...field("read error", watchIssueTitle(`${row.error.code}: ${row.error.message}`), c))
+    } else {
+      const report = row.report
+      out.push(...field("baseline", report.validated ? `${report.validated.outcome}; ${report.validated.findings.length} finding(s); capabilities ${report.validated.capabilities.join(", ") || "none"}` : "no complete baseline", c))
+      out.push(...field("state", `${report.read.state}; labels ${report.read.labels.map(watchIssueTitle).join(", ") || "none"}`, c))
+      if (state !== "current") out.push(...field("comparison", report.verdict.summary, c))
+      if (report.discussion) {
+        const text = watchIssueTitle(report.discussion.body).replace(/\s+/g, " ").trim()
+        out.push(...field("discussion", text.length > 240 ? `${text.slice(0, 240)}…` : text, c))
+        if (report.discussion.url) out.push(...field("source", report.discussion.url, c, { wrapValue: false }))
+      }
+      if (report.verdict.action) out.push(...action(report.verdict.action, c, { indent: 0 }))
+    }
+    out.push("")
+  }
+  if (!result.issues.length) out.push(...wrap("No issues selected for checking.", {}, c))
+  out.push(...wrap("Current means the validated commit matches HEAD. It does not mean review, approval or publication is complete. Read-only; this run posts nothing.", {}, c))
+  return out.join("\n")
+}
+
 /** A list of paths at fault, the way a failing check prints them: a tinted dash, the path in the placeholder tint. */
 function pathLines(paths, c, dash = "fail") {
   return paths.flatMap((path) => wrap(`- ${path}`, { indent: GUTTER + STEP, first: GUTTER })

package/tools/marketplace/update-check.mjs

@@ -0,0 +1,48 @@
+// A passive npm-version notice. Only metadata and a throttle stamp are stored;
+// nothing is installed or executed. Explicit doctor checks bypass this throttle.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { homedir } from "node:os"
+import { compareVersions, registryLatest, upgradeCommand } from "./upgrade.mjs"
+
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
+export const UPDATE_RETRY_INTERVAL_MS = 60 * 60 * 1000
+export const UPDATE_CHECK_TIMEOUT_MS = 1000
+
+export function updateCheckEnabled({ command, args = [], stdinTTY, stdoutTTY, stderrTTY, env = process.env }) {
+  return Boolean(stdinTTY && stdoutTTY && stderrTTY)
+    && !env.DISABLE_UPDATE_NOTIFIER && !env.CI
+    && !args.some((arg) => arg === "--offline" || arg === "--json" || arg === "--agent" || arg === "--out" || arg.startsWith("--out="))
+    && (command === undefined || ["watch", "submit", "verify", "audit", "weigh"].includes(command))
+    && !args.includes("--help") && !args.includes("-h")
+}
+
+/** At most one registry read and one notice per successful day (failure retries after an hour). */
+export async function updateNotice({ repoRoot, version, name = "omakit", env = process.env, now = Date.now(), latest = registryLatest, timeoutMs = UPDATE_CHECK_TIMEOUT_MS }) {
+  if (compareVersions(version, version) === null) return null
+  const updateFile = join(env.XDG_STATE_HOME || join(homedir(), ".local/state"), "omakit", "update-check.json")
+  try {
+    const cached = JSON.parse(readFileSync(updateFile, "utf8"))
+    const age = now - cached.checkedAt
+    const validMetadata = cached.latest === null || compareVersions(cached.latest, cached.latest) !== null
+    if (cached.installed === version && cached.name === name && validMetadata && Number.isFinite(age) && age >= 0
+      && age < (cached.latest ? UPDATE_CHECK_INTERVAL_MS : UPDATE_RETRY_INTERVAL_MS)) return null
+  } catch { /* Missing or malformed state triggers a fresh bounded read. */ }
+  const controller = new AbortController()
+  let timer
+  let published
+  try {
+    published = await Promise.race([
+      Promise.resolve().then(() => latest(name, { signal: controller.signal })).catch(() => ({ version: null })),
+      new Promise((resolve) => { timer = setTimeout(() => { controller.abort(); resolve({ version: null }) }, timeoutMs) }),
+    ])
+  } finally { clearTimeout(timer) }
+  const newest = compareVersions(published?.version, published?.version) === null ? null : published.version
+  try {
+    mkdirSync(dirname(updateFile), { recursive: true })
+    writeFileSync(updateFile, `${JSON.stringify({ name, installed: version, latest: newest, checkedAt: now })}\n`, { mode: 0o600 })
+  } catch { /* An unwritable state directory must not break the user's command. */ }
+  return newest && compareVersions(newest, version) > 0
+    ? `Omakit ${newest} is available (installed ${version}). Run \`${upgradeCommand(repoRoot, name)}\`.`
+    : null
+}

package/tools/marketplace/upgrade.mjs

@@ -74,9 +74,12 @@ export const NPM_REGISTRY = "https://registry.npmjs.org"
  *
  * @returns {Promise<{ version: string|null, error: { code: string, message: string }|null }>}
  */
-export async function registryLatest(name) {
+export async function registryLatest(name, { signal } = {}) {
   try {
-    const meta = await getJson(`${NPM_REGISTRY}/${encodeURIComponent(name)}/latest`)
+    const meta = await getJson(`${NPM_REGISTRY}/${encodeURIComponent(name)}/latest`, { signal })
+    if (meta?.version && compareVersions(meta.version, meta.version) === null) {
+      return { version: null, error: { code: "invalid-version", message: "the registry did not return a valid semantic version" } }
+    }
     return meta?.version
       ? { version: meta.version, error: null }
       : { version: null, error: { code: "unpublished", message: "the registry answered without a version" } }
@@ -85,6 +88,33 @@ export async function registryLatest(name) {
   }
 }
 
+/** Semantic precedence, including prereleases; invalid versions are never update targets. */
+export function compareVersions(left, right) {
+  const parse = (value) => {
+    const match = String(value || "").match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/)
+    if (!match) return null
+    const pre = match[4]?.split(".") || []
+    if (pre.some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith("0"))) return null
+    return { core: match.slice(1, 4).map(BigInt), pre }
+  }
+  const a = parse(left), b = parse(right)
+  if (!a || !b) return null
+  for (let index = 0; index < 3; index += 1) {
+    if (a.core[index] !== b.core[index]) return a.core[index] > b.core[index] ? 1 : -1
+  }
+  if (!a.pre.length || !b.pre.length) return a.pre.length === b.pre.length ? 0 : a.pre.length ? -1 : 1
+  for (let index = 0; index < Math.max(a.pre.length, b.pre.length); index += 1) {
+    const x = a.pre[index], y = b.pre[index]
+    if (x === undefined || y === undefined) return x === y ? 0 : x === undefined ? -1 : 1
+    if (x === y) continue
+    const xn = /^\d+$/.test(x), yn = /^\d+$/.test(y)
+    if (xn && yn) return BigInt(x) > BigInt(y) ? 1 : -1
+    if (xn !== yn) return xn ? -1 : 1
+    return x > y ? 1 : -1
+  }
+  return 0
+}
+
 function installedVersion(repoRoot) {
   try {
     return JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version || null
@@ -300,8 +330,10 @@ async function upgradeNpm({ repoRoot, stream, dryRun, latest, npmRoot, name, ref
   if (!newest) {
     return refuse("the npm registry did not answer, so there is nothing to compare against.", "Connect to the network, then run `omakit upgrade` again.")
   }
-  if (newest === current) {
-    ok(`already current at ${current}, the newest published version`)
+  const compared = compareVersions(newest, current)
+  if (compared === null) return refuse("the installed or published version is invalid, so an exact newer release cannot be selected.")
+  if (compared <= 0) {
+    ok(compared === 0 ? `already current at ${current}, the newest published version` : `${current} is ahead of the newest published version ${newest}; no downgrade applied`)
     out()
     lines(wrap("The marketplace pin is a separate thing and is never touched here. `omakit doctor` says whether it is behind.", {}, c))
     return { ok: true, changed: false, version: current }

package/tools/marketplace/usage.mjs

@@ -69,11 +69,18 @@ export const COMMANDS = Object.freeze([
     ],
   },
   {
-    signature: "omakit watch <issue-url> [--json] [--out <file>]",
+    signature: [
+      "omakit watch <issue-url> [--json] [--out <file>]",
+      "omakit watch [--all | --list] [--user <login>] [--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",
       "it validate a newer one. Read-only.",
+      "--all checks your open marketplace issues; --list lists them first.",
+      "Without a URL or either flag, a terminal asks which issues to check.",
+      "Uses your gh account, or --user to read another public account. JSON",
+      "and pipes never prompt: use --all or --list. Each run is one snapshot.",
     ],
   },
   {
@@ -104,6 +111,8 @@ export const COMMANDS = Object.freeze([
     lines: [
       "What is installed, what is pinned, and what has moved since. Reads and",
       "prints; it installs nothing and never moves the pin.",
+      "Checks the newest npm release explicitly. Normal terminal use also",
+      "checks at most once daily; DISABLE_UPDATE_NOTIFIER=1 disables notices.",
     ],
   },
   {

package/tools/marketplace/watch.mjs

@@ -29,7 +29,7 @@
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 import { MARKETPLACE_PIN, requirePin } from "./pin.mjs"
-import { defaultBranchHead, issue, issueComments, parseIssueUrl, token, GitHubError } from "./github.mjs"
+import { authenticatedUser, repositoryIssues, defaultBranchHead, issue, issueComments, parseIssueUrl, token, GitHubError } from "./github.mjs"
 
 export class WatchError extends Error {
   constructor(code, message) {
@@ -41,6 +41,70 @@ export class WatchError extends Error {
 
 const MARKETPLACE_SLUG = MARKETPLACE_PIN.repository.replace(/^https:\/\/github\.com\//, "").toLowerCase()
 
+/** Text from an issue remains data, including at a terminal. JSON retains the original title. */
+export function watchIssueTitle(value) {
+  return String(value || "").replace(/[\p{Cc}\p{Cf}]/gu, " ")
+}
+
+/** Discover the account's open marketplace issues, without reading every plugin. */
+export async function discoverWatchIssues({ user, github = {}, onPhase = () => {} } = {}) {
+  const read = { authenticatedUser, repositoryIssues, ...github }
+  if (user !== undefined && !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(user)) {
+    throw new WatchError("usage", "--user needs a GitHub login, not a URL or search query")
+  }
+  onPhase("reading the GitHub account")
+  const account = user || await read.authenticatedUser()
+  const [owner, repository] = MARKETPLACE_SLUG.split("/")
+  onPhase(`reading open marketplace issues for ${account}`)
+  const subjects = await read.repositoryIssues(owner, repository, account)
+  // Check the response as well as the server-side creator filter. Never turn
+  // another author's issue, or a PR, into an account-wide watch target.
+  const seen = new Set()
+  const issues = subjects.filter((subject) => {
+    if (subject.pull_request || subject.state !== "open" || subject.user?.login?.toLowerCase() !== account.toLowerCase()) return false
+    if (!Number.isSafeInteger(subject.number) || subject.number < 1 || seen.has(subject.number)) return false
+    seen.add(subject.number)
+    return true
+  }).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).filter(Boolean),
+    updatedAt: subject.updated_at || null,
+  }))
+  return { mode: "list", account, marketplace: MARKETPLACE_PIN.repository, issues }
+}
+
+/** A batch keeps independent read failures visible and shares repository HEAD reads. */
+export async function validationWatchAll({ repoRoot, discovery, github = {}, onPhase = () => {} }) {
+  if (discovery.issues.length) requirePin(repoRoot)
+  const heads = new Map()
+  const readHead = github.defaultBranchHead || defaultBranchHead
+  const shared = { ...github, defaultBranchHead: (url) => {
+    if (!heads.has(url)) heads.set(url, Promise.resolve().then(() => readHead(url)))
+    return heads.get(url)
+  } }
+  const results = new Array(discovery.issues.length)
+  let next = 0
+  async function worker() {
+    while (next < discovery.issues.length) {
+      const index = next++
+      const target = discovery.issues[index]
+      onPhase(`checking issue #${target.number} (${index + 1}/${discovery.issues.length})`)
+      try {
+        results[index] = { issue: target, report: await validationWatch({ repoRoot, issueUrl: target.url, github: shared }), error: null }
+      } catch (error) {
+        results[index] = { issue: target, report: null, error: { code: error.code || "watch-unavailable", message: error.message } }
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, discovery.issues.length) }, worker))
+  const summary = { total: results.length, current: 0, stale: 0, unknown: 0 }
+  for (const result of results) summary[result.report?.verdict.state || "unknown"] += 1
+  return { mode: "all", account: discovery.account, marketplace: discovery.marketplace, summary, issues: results }
+}
+
 // The one action that re-runs validation, in the register the marketplace itself
 // uses in its own failure feedback.
 export const REFRESH_ACTION =
@@ -207,6 +271,12 @@ export async function validationWatch({ repoRoot, issueUrl, onPhase, github = {}
     baselineError,
     head,
     headError,
+    discussion: maintainerComments.length ? {
+      body: maintainerComments.at(-1).body || "",
+      url: maintainerComments.at(-1).html_url || null,
+      createdAt: maintainerComments.at(-1).created_at || null,
+      authorAssociation: maintainerComments.at(-1).author_association || null,
+    } : null,
     verdict: validationVerdict({ comparable, stale, validated, head, fallback, baselineError, headError, pushedAfterReview, repositoryUrl }),
   }
 }