# Writing a Gzyms plugin

A plugin is a folder with a `plugin.toml` and a program in any language. Gzyms starts the program, reads JSON lines from its stdout and writes JSON lines to its stdin. Use one only when the CLI is not enough (see `gzyms skill`).

## Commands

- `gzyms plugin new <name>` makes `~/.config/gzyms/plugins/<name>/` with a working click counter in bash. Start from it. The name is lowercase letters, digits, `-` and `_`.
- `gzyms plugin list` lists the plugins with `on`, `off` or `broken` and why.
- `gzyms plugin add <name>` installs a ready plugin from the built-in catalog. Without a name it lists them: `log-watcher` (log lines to notifications), `gh-prs` (your pull requests through the gh CLI: a glyph per state, fix, merge, comments and draft, with the number of PRs in it) and `gh-builds` (CI of your pull requests and chosen branches: a glyph for failed, running and passed, with the number of PRs or branches) and `star-watcher` (GitHub stars of repos you pick on one gold pill, a row per repo that opens its stargazers, a notification with the name of each new stargazer, also for stars that came while Gzyms was off). Each is a plain script you can read and change after `add`. Gzyms keeps an unchanged catalog plugin up to date: on launch it puts the new version in place before the plugin starts, and options in config.toml stay. A plugin you edited is left alone. When the catalog has a newer version, the plugin's side panel in Settings → Plugins offers Update, which keeps your copy as `<name>.bak-<date>` next to it. The `.gzyms-catalog` file in the folder is how Gzyms tells an edit from an old copy.
- `gzyms plugin remove <name>` moves the folder to the Trash.

Coding agents are no plugin any more: they are built into Gzyms (Settings → Agents, and the `[agents]` keys under Settings in `gzyms skill`). An unchanged `agents` plugin from the catalog goes to the Trash on launch and its options move to `[agents]`. A copy you changed stays in its folder and does not run, since the name `agents` is Gzyms' own now. Rename the folder to run it.

Gzyms watches the plugins folder, so a new or removed folder needs no restart. Gzyms keeps running the program it started: after editing it, turn the plugin off and on with `gzyms set plugins.<name>.enabled false` and then `gzyms set plugins.<name>.enabled true` (or in Settings → Plugins).

## plugin.toml

```toml
name = "PR watch"
description = "Open pull requests on one pill."
command = "./plugin.sh"
icon = "arrow.triangle.branch"

[[option]]
key = "repos"
title = "Repos"
type = "list"
default = ["owner/repo"]
note = "one owner/repo per line"

[[option]]
key = "style"
title = "Style"
type = "choice"
choices = ["short", "long"]
default = "short"
```

- `command =` is required. It runs with `/bin/sh -c` inside the plugin's folder, so `./plugin.sh` needs to be executable (`chmod +x`).
- `name =` defaults to the folder name. `icon =` is an SF Symbol name.
- Each `[[option]]` becomes a field in Settings → Plugins, no UI code needed. `key =` is lowercase letters, digits and `_`, and `enabled` is taken. `type =` is `toggle`, `choice` (with `choices =`), `text` (default), `number` or `list`. `title =`, `default =` and `note =` are optional.
- The user's values live in config.toml as `[plugins.<name>]`, so `gzyms set plugins.<name>.<key> <value>` sets one. A change restarts the plugin.

## Environment

- `GZYMS_PLUGIN`: the folder name.
- `GZYMS_OPT_<KEY>`: each option, the user's value or the default. A list has one item per line, a toggle is `true` or `false`.
- `GZYMS_OPTIONS`: all options as one JSON object.

## Plugin to Gzyms: stdout, one JSON object per line

A pill on the bar. A line with the same `"id"` updates it.

```json
{"item":{"id":"prs","text":"3 open","icon":"arrow.triangle.branch","color":"green","tooltip":"3 pull requests wait for review"}}
```

`"color"` is a theme colour name (`green`, `peach`, `red`, `gold`, `sky`, `mauve`) or a hex. In `"text"`, and in a menu row's `"tag"`, `"text"` and `"detail"`, `:name:` with an SF Symbol name inside draws that symbol in the text's colour: `":xmark.circle: 2 :clock: 1"`. `:name@red:` draws one symbol in its own colour (a theme colour name or `#rrggbb`): `":xmark.circle@red: 2 :checkmark.circle@green: 5"`. Use it instead of emoji, so the pill looks like the rest of the bar. Remove a pill:

```json
{"item":{"id":"prs","remove":true}}
```

A pill that cannot get its data says so with `"error"` on the item, a sentence of what broke and how to fix it. Gzyms greys the pill out with a small warning, and the tooltip and the top of its popup say the sentence and since when. Send the same pill without `"error"` once it works again. Never keep showing old numbers as if they were fresh: send the error instead.

```json
{"item":{"id":"prs","text":"3","icon":"arrow.triangle.branch","error":"gh is logged out. Run gh auth login in a terminal."}}
```

A plugin that polls promises how often with `"expect"`, in seconds, on every item it sends. Gzyms greys the pill out when the plugin stays silent for more than twice that and half a minute, for example when a call hangs. Then print the pill on every poll, also when nothing changed, so Gzyms hears that you are alive. No `"expect"` means no promise: a plugin that speaks only when something happens may be quiet for ever.

```json
{"item":{"id":"prs","text":"3","expect":120}}
```

A pill with `"menu"` opens a list on click. A row with an `"id"` can be clicked, a row without one is a label, `"separator":true` draws a line. `"tag"` is a coloured tag on the left, `"detail"` sits on the right.

```json
{"item":{"id":"prs","text":"3 open","menu":[{"id":"pr:12","tag":"review","color":"peach","text":"#12 fix login","detail":"2h"},{"separator":true},{"text":"updated just now"}]}}
```

A notification, with the same fields as `gzyms notify`. Its `"level"` is one of `info`, `warning`, `error`, `critical`, `armageddon`. A notification with the same `"id"` replaces the earlier one from this plugin. Once its banner is gone it waits on the plugin's first pill: a count in the pill's corner and a list at the top of its popup. Only a plugin with no pill files them under the 🔔. `"sound"` is an event name (`message`, `success`, `fail`, `waiting`), a macOS sound name, or a path to an audio file (`.mp3`, `.m4a`, `.wav`, `.aiff`).

```json
{"notify":{"id":"deploy","title":"Deploy done","subtitle":"api","body":"1.4.2 is live","level":"info","sound":"success","link":"https://example.com"}}
```

`"row"` ties a notification to a menu row of the plugin's: once no pill of the plugin has a row with that id, the notification leaves the list. Use it for a notification about a thing a row stands for, so it goes when the thing does.

```json
{"notify":{"id":"job-3","title":"Job waits","row":"3"}}
```

`"dismiss"` takes one of the plugin's notifications off the bar and out of the list, by the `"id"` it gave it. Send it once a notification has nothing left to say, for example a question that was answered.

```json
{"dismiss":"job-3"}
```

A second action: `"alt_label"` names it on the banner's hints, `"alt_link"` is the URL it opens. With `"alt_label"` and no `"alt_link"`, the second action sends `notify_alt` back to the plugin, so the plugin does the work itself.

```json
{"notify":{"id":"job-3","title":"Job waits","alt_label":"Open in agent"}}
```

A line for `~/Library/Logs/Gzyms/gzyms.log`, written as `plugin <name>: …`. Use it to say what a click did.

```json
{"log":"click: job 3 opened"}
```

## Gzyms to plugin: stdin, one JSON object per line

```json
{"event":"click","id":"prs"}
```

`"event"` is one of:

- `"click"` and `"right_click"`: on a pill without a menu, or on a menu row (the row's id).
- `"open"`: its menu opened, a good moment to refresh.
- `"notify_open"`: the user opened one of its notifications that has no link (the id is the plugin's own).
- `"notify_alt"`: the user took the second action of one of its notifications that has `"alt_label"` and no `"alt_link"` (the id is the plugin's own).

## Rules

- Print only when something changed. Gzyms redraws only when a line differs. A plugin with `"expect"` prints every poll anyway.
- When stdin ends, Gzyms is gone: exit.
- Long work (network, a slow command) runs in the background, so clicks are still read.
- A plugin that exits is started again after 1 s, 2 s, 4 s and so on, up to a minute. Until it talks again, its pills stay on the bar greyed out with a warning, so a crash never shows old numbers as fresh.
- A line that is not a message, and the first 20 lines of stderr, go to `~/Library/Logs/Gzyms/gzyms.log` as `plugin <name>: …`. Read it when a pill does not show up.
