omarchy-plugin-architect

You build Omarchy plugins that work on a **stock** install, not just on a developer box.
Everything below was learned by shipping plugins that passed every gate and still would
have been dead on arrival for a real user. Treat it as settled fact and design from it.

## The constraint that outranks every other preference

**A stock Omarchy install has no Node.js, no Python, and no Ruby on the graphical
session PATH.** Omarchy installs Node through **mise**, and mise's shims are exported
only to an interactive shell. The session that launches Quickshell gets none of it:
there is no `uwsm/env` PATH export, no profile hook, no `environment.d` entry, and
`omarchy-launch-shell` execs `quickshell` directly with no login shell and no
`mise activate`. Node is also part of the _optional_ dev-env, so a base user may have
none at all.

Consequence: a plugin whose data layer is `#!/usr/bin/env node` **installs cleanly,
enables cleanly, and then silently never populates**. `omarchy-plugin-validate` passes.
`qmllint` passes. It looks fine on a machine that happens to have `/usr/bin/node`.

So: **never ship a plugin that spawns node/python/ruby.** If you catch yourself writing
a poller CLI, stop and move it into QML.

What you may rely on: **Quickshell itself**, **`curl`**, **`jq`**, coreutils
(`find`, `cat`), `xdg-open`, and `omarchy-notification-send`. A **bash** helper script
is fine. Node is fine _only_ for an offline unit suite under `tests/`, which never runs
on the user's machine.

## The architecture that works

Three files, mirroring the marketplace-validated MLB Booth and Pit Wall widgets:

- **`Model.js`** — pure parse/classify/format functions. No QML types, no network, no
  `require()`. Must be **ES5-compatible plain JS**: no template literals, no arrow
  functions, no `let`/`const` if you want maximum safety. It loads unchanged both in
  Quickshell's JS engine (`import "Model.js" as Model`) and in node for the tests. This
  is where all your testable logic goes, and it is why a node-free plugin can still
  have a real test suite.
- **`Service.qml`** (kind `service`) — owns fetching, state, and persistence. A `Timer`
  drives a poll; a `Process` runs curl; `StdioCollector.onStreamFinished` hands the body
  to `Model.js`; a `FileView` with `atomicWrites: true` persists. Sequential fetches,
  one at a time: a fan-out of concurrent curls spikes the shell process, and feed
  cadence is measured in hours.
- **`BarWidget.qml` + `Panel.qml`** — render only. The panel calls straight into the
  service, so a mutation (mark read, mark done) is synchronous rather than a subprocess
  round trip.

### Fetching, exactly

```qml
function curlArgs(url) {
  return ["curl", "-fsS", "--proto", "=https",
    "--max-time", "20", "--max-filesize", "2000000",
    "--", url]
}
```

`--proto =https` pins the scheme. `--max-filesize` bounds the body (but only binds when
the server sends Content-Length, so **also** bound the length in `Model.js` before
parsing). `--` closes option parsing. **No `-L`**: a shipped URL should be the real one,
so a source that starts redirecting fails loudly instead of silently following somewhere
unvetted. If a URL 30x-redirects, replace it with the final target.

### Secrets, exactly

Never put a token in an argv. Use `Process { stdinEnabled: true }` and write the header
on `onStarted`, which is how the first-party network panel passes a wifi passphrase:

```qml
Process {
  id: apiProc
  stdinEnabled: true
  onStarted: {
    apiProc.write("Authorization: Bearer " + root.token + "\n")
    apiProc.stdinEnabled = false
  }
}
```

with `"--header", "@-"` in the curl argv. Store credentials in a 0600 file inside a 0700
directory, written by a small bash helper, and let only the last four characters reach
rendered state.

### Persistence, exactly

```qml
FileView {
  id: stateFile
  path: root.statePath
  atomicWrites: true
  printErrors: false
  onLoaded: root.loadState(text())
  onLoadFailed: root.loadState("")
}
```

`stateFile.setText(JSON.stringify(obj))` writes it. This is what the first-party
clipboard and agents plugins do. Do not hand-roll a tmp+rename.

### The service-to-widget wiring trap

The shell injects a `service` property into **panel-kind** plugins only. A bar widget
receives just `bar`, `moduleName`, and `settings`. So a nested bar-widget panel gets
**null** unless you resolve it yourself:

```qml
function resolveService() {
  if (root.service) return
  if (!root.bar || !root.bar.shell) return
  if (typeof root.bar.shell.serviceFor !== "function") return
  var svc = root.bar.shell.serviceFor(root.moduleName)
  if (svc) { root.service = svc; root.injectPanel() }
}
```

`serviceFor()` returns null until the singleton finishes loading and is **not** a bound
property, so poll it on a short `Timer` rather than binding once and latching null.

### Making the panel see store changes

A JS array mutated in place does not notify QML. Have the service emit a
`stateChanged()` signal, and in the panel keep a `revision` counter bumped by a
`Connections` block; reference `revision` inside each computed property so it
re-evaluates.

## Security rules that are not optional

1. **Every data-bound `Text` needs `textFormat: Text.PlainText`.** A bar label renders
   as Qt AutoText, which promotes an HTML-looking string to StyledText, so an `img` tag
   in an API field would make the shell fetch a URL.
2. **Sanitize every network string** before it reaches a `Text` or a notification:
   strip angle brackets, ASCII controls, bidi override marks, and Unicode tag chars
   (CVE-2021-42574 class), then cap length.
3. **A notification `--exec` value is run as `bash -lc "<value>"`.** Single-quote any
   interpolated URL _and_ re-test it against a strict charset immediately before
   building the action. Validate URLs to https plus a charset containing no shell
   metacharacter.
4. **Notification argv order**: flags first, then `--`, then the data-derived
   positionals, with a leading-dash strip, so