omakit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maarten Tolhuijs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+<p align="center">
+  <img src="docs/media/banner.gif" alt="omakit" width="440">
+</p>
+
+**Everything knowable about an Omarchy Quattro plugin submission, checked
+before you post it:** the tree, the manifest, the form, the commit, and the
+marketplace's own security baseline with its outcome reported as it is. A
+submission is judged at one exact commit and drifts from it the moment you
+push; `watch` says when that has happened. All of it runs on your own machine
+and publishes nothing: no issue, no comment, no label, nobody's attention spent
+until you choose to.
+
+![omakit submit refusing a plugin with no license, a README that never says how to uninstall, and a reserved plugin id](docs/media/submit.gif)
+
+The plugin above is refused for three things the marketplace itself refuses,
+and warned about a fourth: it ships instruction files an agent will read once
+installed. **103 marketplace issues mention exactly that, and no automated check
+reports it, so today an author finds out from a human review round.** It is a
+warning and not a refusal, because the marketplace does list plugins that ship
+them: 6 of 34 inspected do, at the commit that was listed.
+
+```bash
+omakit submit <plugin-repo> --category Widgets --tags bar,quickshell
+```
+
+Fifteen checks, each naming its source and, when it fails, the measured reason it
+exists. A blocking failure produces no submission body at all, because a refusal
+that still hands you the body is only a suggestion.
+
+## Why it exists
+
+Four numbers, all measured on public marketplace data on 2026-09-12. Method,
+limits and the rest of the figures: [docs/MEASUREMENTS.md](docs/MEASUREMENTS.md).
+
+| Measured | Consequence |
+| --- | --- |
+| 39 submissions fell out on the title prefix alone, and 11 more are malformed in the body, one by a single word | the format is generated from the pinned form and judged by the marketplace's own parser |
+| 1,215 of the 2,916 listings with a recorded baseline needed a human to look, because of a capability | the official baseline runs locally on the exact commit first, and names the capability |
+| 103 issues mention agent-control files, which no automated check reports | submit names every one with its remedy, before a reviewer has to |
+| 73% of parked submissions have a HEAD the marketplace never saw; 46% of the maintainer's own revalidation requests never produced one | a validation watch that names the one action which re-runs validation |
+
+It does not claim to unblock the maintainer. His review writing barely repeats,
+his median time from submission to publication is hours, and the queue waiting on
+him is a median half a day old. The honest size of what this saves him is the
+staleness paragraph he has written by hand on 358 issues, roughly 5.5% of his
+review writing. The rest of the benefit is the submitter's.
+[docs/MARKETPLACE.md](docs/MARKETPLACE.md) states that in full.
+
+## Install
+
+On Omarchy, or any Arch:
+
+```bash
+yay -S omakit
+omakit setup
+```
+
+Anywhere with Node 22 or newer:
+
+```bash
+npm install --global omakit
+omakit setup
+```
+
+Or read what you run:
+
+```bash
+git clone --depth 1 https://github.com/mtolhuys/omakit ~/.local/share/omakit
+ln -s ~/.local/share/omakit/bin/omakit ~/.local/bin/omakit
+omakit setup
+```
+
+| Needs | Why |
+| --- | --- |
+| Node 22 or newer | the tool is plain ESM with no dependencies and no build step. A stock Omarchy has it through `mise`, along with `git`, `yay`, `gh` and `ttfx` |
+| `git` | the pin, and reading a subject's tree at an exact commit |
+| network, once | `omakit pin`. After that, `submit` and `verify` on a local repository need none at all |
+| 15 MB on disk | the pinned checkout, in `$XDG_CACHE_HOME/omakit/marketplace`, or `~/.cache/omakit/marketplace` |
+
+Updates come from whichever installer you used: `omarchy-update` or `yay -Syu`
+for the package, `npm i -g omakit@latest` for npm, `omakit upgrade` for a
+clone. Nothing in omakit updates itself, and `omarchy-mise-install npm:omakit`
+would, so it is not the way in.
+
+## Watch
+
+![omakit watch reporting that a validated commit has fallen behind](docs/media/watch.gif)
+
+```bash
+omakit watch <submission-issue-url>
+```
+
+That submission passed validation and passed the security baseline with zero
+findings. It is stuck because the marketplace validated one exact commit, and
+the only action that makes it validate a newer one is editing the issue body. Pushing the fix does
+nothing. Commenting "fixed in `abc123`" does nothing. **73% of the 464
+submissions parked in their author's court have a default-branch HEAD the
+marketplace never saw.**
+
+## Commands
+
+Agent-first: the expected user is a coding agent submitting a plugin on an
+owner's behalf. Zero dependencies, plain ESM, one entry point, no build step.
+
+```bash
+omakit setup                 # the environment, the pin, tab completion, and what to try first
+omakit submit <plugin-repo> --category <c> --tags <a,b>
+omakit watch <issue-url>     # the commit the marketplace validated, against the plugin's current HEAD
+omakit verify <plugin-repo>  # the official security baseline over the local transport, reported verbatim
+omakit parity                # the baseline over GitHub versus the local transport, on real listings; writes the evidence
+omakit doctor                # what is installed, what is pinned, and what has moved
+omakit pin                   # what setup does for the pin, on its own
+omakit upgrade               # fast-forwards this checkout of omakit itself
+omakit help --agent          # the operating instructions, for the agent running this
+```
+
+![omakit setup checking the environment and fetching the pinned checkout](docs/media/setup.gif)
+
+`omakit setup` checks the environment, fetches the marketplace checkout that
+every rule is read from, installs tab completion for the shell you run it from
+(bash, zsh or fish, read from `$SHELL`), and tells you what to try first. It is
+idempotent. The fetch takes about 2 seconds and 15 MB, because it takes only the
+seven files omakit reads out of that repository rather than the 325 MB it is at
+that commit. The completion script knows the subcommands and their flags,
+completes a directory for `<target>`, and offers the categories and tags the
+pin's submission form actually has.
+
+There is nothing to authenticate. If you have `gh auth login` done, omakit
+reads that credential for GET requests and stores nothing; a token in
+`GH_TOKEN` or `GITHUB_TOKEN` reaches it the same way, because `gh` honours
+those itself. Without either, `watch` and `parity` share GitHub's
+60-requests-an-hour unauthenticated allowance, and `submit` and `verify` on a
+local repository do not touch the network at all (a `<url>@<sha>` target is
+fetched once, over git, into the cache). omakit reads no environment variable of its own,
+and `omakit doctor` names the credential source it found, or that it found
+none.
+
+Every colour omakit prints is an ANSI palette index, so your Omarchy theme
+decides what it looks like, and nothing is said by colour alone. What the
+terminal shows and why is [docs/TUI.md](docs/TUI.md); which index each role
+gets, measured over all 32 installed themes, is
+[docs/PALETTE.md](docs/PALETTE.md).
+
+## What it is doing
+
+Nothing about the submission format is written down in this repository. The
+title prefix, the six form headings in order, the nine categories, the thirteen
+tags and the exact text of the five checklist items are all read from
+`.github/ISSUE_TEMPLATE/submit-plugin.yml` in a marketplace checkout pinned to an
+exact commit. The rendered body is then handed to the marketplace's own
+`parseCurrentSubmission` from that same commit. If it accepts the body here, it
+accepts it there.
+
+The security baseline is the marketplace's own code, imported unmodified and run
+over a local snapshot with no network. Omakit adds no rule, renames no outcome,
+and never restates the result as a safety claim: the baseline does no data-flow
+analysis and is not a security review, and the output says so in the
+marketplace's own words.
+
+Every check is labelled. `[marketplace-pin]` is the marketplace's rule, read from
+the pin. `[omakit]` is this project's own check, derived from public issue data.
+Those are not marketplace policy and do not claim to be.
+
+## Updating
+
+Two different things could mean "upgrade" here, and only one of them may ever
+move on its own. That distinction is now enforced rather than argued.
+
+**The tool:**
+
+```bash
+omakit upgrade          # fast-forwards this checkout of omakit itself
+omakit upgrade --dry-run
+```
+
+It refuses a dirty tree, a detached HEAD, a remote that is not this repository,
+and anything that is not a fast-forward, and it names what to run yourself in
+each case. It is not a self-updater of the kind this repository warns other
+people about: it fast-forwards a Git checkout you cloned, from the remote you
+cloned it from, and it touches nothing else. On a package install it says so and
+names the installer's own command: `npm i -g omakit@latest`, or
+`sudo pacman -Syu omakit` for the Arch package. `git -C ~/.local/share/omakit pull` still works
+and does the same thing.
+
+**The pin** does not move by itself, ever, and `omakit upgrade` does not move it
+either: a test asserts that its source does not so much as mention the pin or
+the cache. Bumping it changes where the submission contract and the baseline
+policy are read from, and the procedure in
+[docs/UPSTREAM_CONTRACT.md](docs/UPSTREAM_CONTRACT.md) ends in re-proving
+transport parity and committing the evidence. `omakit doctor` tells you when the
+pin is behind the marketplace's current branch and then leaves it alone. That the
+pin can go stale unnoticed is the same defect class `omakit watch` reports, so it
+would be poor form to hide it here.
+
+## Evidence, not claims
+
+```bash
+npm test        # 147 tests, node --test, no dependencies
+```
+
+| Claim | Proof |
+| --- | --- |
+| The local transport produces the marketplace's own result | 30 of 30 identical, [docs/evidence/parity/](docs/evidence/parity/) |
+| A local run touches no network | run inside `unshare -rn`, [docs/evidence/offline/](docs/evidence/offline/) |
+| The generated body is well formed | the marketplace's own parser, `tests/unit/issue.test.mjs` |
+| Nothing writes to the marketplace | `tests/unit/read-only.test.mjs`, over every source file |
+| No agent-control file can reach a plugin | `tests/unit/self-containment.test.mjs` |
+| The GIFs above are real output | captures and renderer in [docs/media/](docs/media/) |
+
+Committed evidence records a digest of each side rather than the results
+themselves: findings about a specific third-party plugin are not this project's
+to publish.
+
+## Documentation
+
+| Document | For |
+| --- | --- |
+| [docs/SUBMIT.md](docs/SUBMIT.md) | every check and what it decides |
+| [docs/VALIDATION_WATCH.md](docs/VALIDATION_WATCH.md) | the validation watch: what the marketplace validated, and what moves it |
+| [docs/MEASUREMENTS.md](docs/MEASUREMENTS.md) | every number, its method and its limits |
+| [docs/UPSTREAM_CONTRACT.md](docs/UPSTREAM_CONTRACT.md) | the seam, the pin, the boundaries |
+| [docs/MARKETPLACE.md](docs/MARKETPLACE.md) | who this actually helps |
+| [docs/PALETTE.md](docs/PALETTE.md) | every installed Omarchy theme measured, and which palette index each role gets |
+| [docs/TUI.md](docs/TUI.md) | what the terminal shows, and why it looks that way |
+| [AGENTS.md](AGENTS.md) | changing this repository |
+
+MIT. Derived work built on public data from
+`omacom/omarchy-plugin-marketplace`; not affiliated with or endorsed by that
+project.

package/bin/omakit

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// The single executable entry point. No build step, no dependencies.
+import "../tools/marketplace/cli.mjs"

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "omakit",
+  "version": "0.1.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, posts nothing, zero dependencies.",
+  "license": "MIT",
+  "author": "Maarten Tolhuijs",
+  "keywords": [
+    "omarchy",
+    "quattro",
+    "plugin",
+    "marketplace",
+    "preflight",
+    "cli",
+    "agent"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "omakit": "bin/omakit"
+  },
+  "scripts": {
+    "pin": "node tools/marketplace/cli.mjs pin",
+    "test": "node --test tests/unit/*.test.mjs",
+    "parity": "node tools/marketplace/cli.mjs parity --count 30",
+    "doctor": "node tools/marketplace/cli.mjs doctor"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mtolhuys/omakit.git"
+  },
+  "files": [
+    "bin",
+    "tools",
+    "skills",
+    "tests/parity/corpus.mjs",
+    "tests/parity/run.mjs"
+  ]
+}

package/skills/omarchy-plugin-submit/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: omarchy-plugin-submit
+description: Submit an Omarchy Quattro plugin to the plugin marketplace on its owner's behalf. Use when asked to submit, list or publish a plugin to the Omarchy marketplace, or to check whether a plugin is ready to submit. Runs every pre-submission check, produces the exact issue title and body, and posts nothing.
+---
+
+# Submitting an Omarchy plugin
+
+## The one thing to get right
+
+**You do not create the issue.** This tool produces a title and a body. Creating
+the issue is a separate, explicit act that needs the plugin owner's approval
+first, which is what the marketplace's own agent instructions require. Show the
+owner the title, the body and the verdicts, ask, and only then post it.
+
+## Run it
+
+```bash
+omakit pin     # once, and after any pin change: fetches the pinned marketplace checkout
+omakit submit <path-to-the-plugin-repo> --category <category> --tags <a,b>
+```
+
+The plugin's name and id come from the root `manifest.json`. The repository URL
+comes from `origin`. You supply the category and the tags, because nobody else
+can: they are an editorial choice about where the plugin belongs.
+
+If you do not know which category and tags are allowed, run the command without
+them. The failing checks print the controlled lists, read from the pinned form.
+
+Useful flags: `--notes` for the Maintainer notes field, `--suggest-tag` for the
+optional suggestion, `--name` when the manifest has no name, `--json` for a
+machine-readable result, `--offline` to skip the one check that needs the network.
+
+## Reading the result
+
+Exit code 0 means every blocking check passed and the output contains the issue
+title and body. Exit code 1 means it refused, and no body was produced.
+
+Each check names a source. `[marketplace-pin]` is the marketplace's own rule, read
+from a pinned checkout. `[omakit]` is this tool's own check, derived from public
+issue data. Do not describe those to the owner as marketplace requirements.
+
+A failing check prints the failing paths, a remedy and the measured reason it
+exists. Fix the cause, do not work around the check.
+
+## The two refusals people argue with
+
+**`tree.agent-control`.** Agent-control files anywhere in the installable tree
+(`AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `.mcp.json`, anything under `.claude/` or
+`.codex/`, instruction files under `skills/`) are read by whatever agent the user
+runs next, and 103 marketplace issues mention them. This is a warning, not a
+refusal: the marketplace lists plugins that ship them (6 of 34 inspected at
+their listed commit), so the body is still produced. Tell the owner, and offer
+the remedy: move the guidance to a non-agent filename such as `DEVELOPMENT.md`,
+untrack the originals so they leave the installable tree, and keep a recursive
+check in the release process so they cannot return. The owner decides; do not
+strip files from their tree on your own.
+
+**`submission.validation-commit`.** The marketplace validates the commit it
+resolves when the issue is opened or edited, which is the pushed default-branch
+HEAD, not whatever is checked out locally. Push first, then submit. 73% of submissions
+parked in their author's court have a HEAD the marketplace never saw.
+
+## What the baseline result means
+
+`baseline.preflight` runs the marketplace's own security baseline over a local
+snapshot of the exact commit and reports it verbatim.
+
+- `passed`: nothing in the baseline holds the submission back.
+- `review-required`: no findings, but one or more of the seven capabilities is
+  present, so a maintainer must look at this exact commit. Not a defect. Worth
+  explaining in `--notes` rather than hiding.
+- `needs-fixes`: findings. Only `sudoers-dangerous-passwordless-command` and
+  `privileged-process-control-from-shared-temp` block publication under the
+  current enforcement mode; the rest a maintainer may accept for that commit.
+  Fixing them first avoids a human round either way.
+
+Never restate any of this as a safety claim. The baseline performs no data-flow
+analysis and is not a security review; the output says so in the marketplace's own
+words, and so should you.
+
+## After the issue exists
+
+Tell the owner the one thing nobody tells them: the marketplace validated one
+exact commit, and **editing the issue body** is the only action that makes it
+validate a newer one. Pushing a fix does nothing. Commenting "fixed in `abc123`" does nothing.
+Then use `omakit watch <issue-url>` to check it later, and see
+`skills/omarchy-plugin-validation-watch/SKILL.md`.

package/skills/omarchy-plugin-validation-watch/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: omarchy-plugin-validation-watch
+description: Diagnose an Omarchy marketplace plugin submission that has gone quiet or is stuck waiting. Use when a submission issue has had no progress, when a reviewer asked for a fresh validation, or when fixes were pushed but nothing happened. Checks whether the validated commit has fallen behind the repository and names the one action that re-runs validation.
+---
+
+# A submission that has gone quiet
+
+## The mechanism, first
+
+The marketplace validates **one exact commit**, and the review that follows is
+of that commit. The only action that makes it validate a newer one is **editing
+the issue body**.
+
+- The only workflow with a direct `issues` trigger fires on
+  `opened, edited, reopened, labeled, unlabeled`.
+- There is no `issue_comment` trigger anywhere in the marketplace.
+- The daily HEAD comparison covers plugins that are already listed, not open
+  submissions.
+
+So pushing a fix does nothing, and commenting "fixed in `abc123`" does nothing.
+Both feel like progress. Neither is. This is the single most common reason a
+submission sits still: of the 464 submissions parked in their author's court, 73%
+have a default-branch HEAD the marketplace never saw, and 82% of the authors whose
+push came after a review comment had also commented: engaged, and stuck.
+
+## Check it
+
+```bash
+omakit watch https://github.com/omacom/omarchy-plugin-marketplace/issues/<number>
+```
+
+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
+`GITHUB_TOKEN`); without one it falls back to the public commit feed. Never ask the operator for a token: run
+`omakit doctor` and read the `github.auth` line, which names the source.
+
+## Acting on each verdict
+
+**`stale`.** The validated commit is behind the repository. Tell the owner plainly: the marketplace has not
+seen the newer commit, and the fix is to **edit the issue body** (any edit
+re-triggers validation and the baseline against the new commit). Do not advise
+them to push again, and do not advise them to comment. If you are asked to do it,
+that is an edit to their issue: get their explicit approval and do it yourself,
+outside this tool.
+
+**`current`.** The validated commit is the current HEAD. The submission is genuinely waiting
+on a person, or on a fix the reviewer asked for that has not been made. Read the
+review comments and address the substance. Do not edit the issue to "bump" it: a
+fresh validation clears the reviewer's human decision and costs him a complete
+re-read of the plugin.
+
+**`unknown`.** There is no validated commit to compare, the last baseline did not
+complete, or the repository's HEAD could not be read. The output says which. Never
+report this as `current`.
+
+## Before you conclude that the reviewer is behind
+
+Check the assumption. The maintainer's own queue is a median half a day old, and
+his median time from submission to publication is hours. If a submission has been
+still for five days, the overwhelmingly likely reason is that it is waiting on its
+author, not on him.

package/tests/parity/corpus.mjs

@@ -0,0 +1,62 @@
+// Deterministic parity corpus: listed marketplace repositories at their exact
+// listing-validated commits, read from the pinned marketplace registry so the
+// set is reproducible and never hand-picked for a favourable result.
+//
+// The registry records the outcome the marketplace itself computed for each
+// listing (`automatedSecurityBaseline.outcome`). The corpus is stratified on
+// that outcome so a run always contains repositories whose official result is
+// not `passed`: for a corpus of n, ceil(n/8) needs-fixes, ceil(n/4)
+// review-required, the rest passed, each stratum sampled by a fixed stride
+// over the repositories sorted by URL. `offset` shifts every stratum.
+
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+const STRATA = ["needs-fixes", "review-required", "passed"]
+
+function registrySources(pinDir) {
+  const registry = JSON.parse(readFileSync(join(pinDir, "registry.json"), "utf8"))
+  const list = Array.isArray(registry.sources) ? registry.sources : Object.values(registry.sources)
+  return list
+    .filter((source) => typeof source?.repo === "string" && /^[a-f0-9]{40}$/i.test(source?.listingValidatedCommit || ""))
+    .map((source) => {
+      const recorded = source.automatedSecurityBaseline || null
+      return {
+        repo: source.repo,
+        commit: source.listingValidatedCommit.toLowerCase(),
+        type: source.type,
+        registryOutcome: recorded?.outcome || null,
+        registryOutcomeCommit: recorded?.commit ? String(recorded.commit).toLowerCase() : null,
+        registryBaselineVersion: recorded?.version || null,
+      }
+    })
+    .sort((a, b) => a.repo.localeCompare(b.repo))
+}
+
+export function strataSizes(count) {
+  const needsFixes = Math.ceil(count / 8)
+  const reviewRequired = Math.ceil(count / 4)
+  return { "needs-fixes": needsFixes, "review-required": reviewRequired, passed: Math.max(0, count - needsFixes - reviewRequired) }
+}
+
+function sample(list, count, offset) {
+  if (count <= 0 || list.length === 0) return []
+  const step = Math.max(1, Math.floor(list.length / count))
+  const picked = []
+  for (let i = offset % Math.max(1, list.length); picked.length < count && picked.length < list.length; i = (i + step) % list.length) {
+    if (picked.includes(list[i])) break
+    picked.push(list[i])
+  }
+  return picked
+}
+
+export function parityCorpus(pinDir, count = 30, offset = 0) {
+  const sources = registrySources(pinDir)
+  const sizes = strataSizes(count)
+  const picked = []
+  for (const stratum of STRATA) {
+    const pool = sources.filter((s) => s.registryOutcome === stratum)
+    picked.push(...sample(pool, sizes[stratum], offset))
+  }
+  return picked.sort((a, b) => a.repo.localeCompare(b.repo))
+}