herdr-gentle-shell 1.6.2 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DESIGN.md +130 -41
- package/README.md +48 -25
- package/docs/theme-sync.md +284 -0
- package/extensions/gentle-herdr-state.ts +279 -157
- package/extensions/herdr-theme-sync.ts +388 -0
- package/lib/customize-panel.js +92 -17
- package/lib/theme-projection.js +159 -0
- package/lib/theme-store.js +230 -0
- package/package.json +3 -2
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# Theme sync (Herdr palette follows the active Pi theme)
|
|
2
|
+
|
|
3
|
+
Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
|
|
4
|
+
pinned while the sync is off. This page covers the switch, the one state file,
|
|
5
|
+
the managed `[theme]` block, the writer CLI and the limits. Protocol context is
|
|
6
|
+
in [DESIGN.md](../DESIGN.md) §12; the switch is described beside the sidebar and
|
|
7
|
+
Moshi switches in [README.md](../README.md).
|
|
8
|
+
|
|
9
|
+
## The switch
|
|
10
|
+
|
|
11
|
+
`/herdr-gentle:customize` → `Herdr Theme` holds two rows. The row's note and
|
|
12
|
+
the extension's refusal carry the same words, so the panel and the apply path
|
|
13
|
+
cannot tell you different things.
|
|
14
|
+
|
|
15
|
+
- `Theme sync` is a pill toggle and is **OFF by default**. `On` makes Herdr's
|
|
16
|
+
palette the palette of the theme Pi is showing, and it follows a change of
|
|
17
|
+
the active theme while Pi keeps running. Turning the sync off stops following and leaves
|
|
18
|
+
Herdr with the palette it already has: nothing is removed from Herdr's
|
|
19
|
+
config, so the last applied palette survives Pi closing.
|
|
20
|
+
- `Gentle Shell theme` is the card's only non-toggle row (`Select…`): it opens
|
|
21
|
+
the host's theme list plus the unassign entry `Off (no theme assigned)`, which shifts
|
|
22
|
+
by a numeric suffix if a theme literally carries that spelling. It is painted dim, denied the selection
|
|
23
|
+
band and refused while the sync is on, with
|
|
24
|
+
`Turn Theme sync off to pick a specific theme.` Picking `Off` clears the pin
|
|
25
|
+
(`theme: null`); picking a name stores it. The stored pin is carried across a
|
|
26
|
+
sync toggle untouched, so turning the sync off restores that choice instead of
|
|
27
|
+
unassigning it.
|
|
28
|
+
- Esc, a cancelled menu, an unknown argument and a host without
|
|
29
|
+
`getAllThemes()` all write nothing. The plain two-step menu stays as the
|
|
30
|
+
fallback when the TUI helpers or `ctx.ui.custom` are unavailable, and offers
|
|
31
|
+
the same two rows.
|
|
32
|
+
|
|
33
|
+
The notices are fixed strings:
|
|
34
|
+
|
|
35
|
+
| Action | Notice |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| Sync turned on | `Theme sync on; Herdr's palette follows the theme active in Pi.` |
|
|
38
|
+
| Sync turned off | `Theme sync off; Herdr keeps the palette it was last given.` |
|
|
39
|
+
| Toggle already in that state | `Theme sync already on/off; nothing was changed.` |
|
|
40
|
+
| Theme row while the sync is on | `Turn Theme sync off to pick a specific theme.` |
|
|
41
|
+
| Theme assigned | `Gentle Shell theme set to <name>.` |
|
|
42
|
+
| Pin cleared | `Gentle Shell theme set to Off; Herdr keeps the palette it was last given.` (the stored value and the row read `Off`; only the picker entry is spelled `Off (no theme assigned)`) |
|
|
43
|
+
| Host exposes no theme list | `Could not read Pi's theme list (this host exposes no getAllThemes()); nothing was changed.` |
|
|
44
|
+
| Theme store missing | `Could not reach the theme store (lib/theme-store.js is unavailable); nothing was changed.` |
|
|
45
|
+
| State file not writable | `Could not write the theme store: <detail>; nothing was changed.` |
|
|
46
|
+
|
|
47
|
+
`/herdr-gentle:customize status` prints one read-only line and writes nothing:
|
|
48
|
+
|
|
49
|
+
```text
|
|
50
|
+
customize status: sidebar=<on|off|unknown> moshi=<on|off> theme-sync=<on|off|unknown> theme=<name|none|unknown>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## State file
|
|
54
|
+
|
|
55
|
+
One document is the only persisted truth: `gentle-theme.json`.
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"sync": true,
|
|
60
|
+
"theme": null,
|
|
61
|
+
"updatedAt": "2026-09-19T10:00:00.000Z"
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
It lives in the directory `gentle-moshi.json` already uses: `GENTLE_STATUS_STATE_DIR`
|
|
66
|
+
when set, else `$XDG_STATE_HOME/herdr/plugins/herdr-gentle-agents` (else
|
|
67
|
+
`~/.local/state/herdr/plugins/herdr-gentle-agents`), unless the stored
|
|
68
|
+
directory holds no file of ours and the newer `herdr-gentle-shell` directory
|
|
69
|
+
does — then that one is used. `sync` is the switch, `theme` is the pinned name
|
|
70
|
+
or `null`, and `updatedAt` is stamped by the writer — a caller cannot record a
|
|
71
|
+
timestamp it made up. Writes are atomic (temporary file in the same directory,
|
|
72
|
+
then rename), preserve an existing file's mode and create a new one as `0600`.
|
|
73
|
+
|
|
74
|
+
- **Missing file** is an inert document (`sync: false`, `theme: null`): a fresh
|
|
75
|
+
install writes nothing, so nothing is what it reads.
|
|
76
|
+
- **Unreadable or unparsable file** is a refusal, never a guess: the sync row
|
|
77
|
+
reads `Unknown`, no theme name is shown, and the follower does nothing. It is
|
|
78
|
+
written over only when you act — toggling the sync writes a fresh document,
|
|
79
|
+
and the pinned-theme row is refused only by a *stored* `sync: true`.
|
|
80
|
+
- **`sync: false` with `theme: null`** is the default install: the follower
|
|
81
|
+
spawns nothing, writes nothing and removes nothing (S7).
|
|
82
|
+
- A blank or non-string `theme` normalises to `null`; nothing is trimmed into a
|
|
83
|
+
theme name that no install has.
|
|
84
|
+
|
|
85
|
+
## What gets written
|
|
86
|
+
|
|
87
|
+
The writer owns one marker-delimited block in Herdr's config
|
|
88
|
+
(`$HERDR_CONFIG_PATH`, else `<XDG_CONFIG_HOME>/herdr/config.toml`, else
|
|
89
|
+
`~/.config/herdr/config.toml`; `%APPDATA%\herdr\config.toml` on Windows):
|
|
90
|
+
|
|
91
|
+
```toml
|
|
92
|
+
# BEGIN herdr-gentle-theme (managed; do not edit)
|
|
93
|
+
[theme]
|
|
94
|
+
name = "one-dark"
|
|
95
|
+
|
|
96
|
+
[theme.custom]
|
|
97
|
+
accent = "#89b4fa"
|
|
98
|
+
text = "#cdd6f4"
|
|
99
|
+
red = "#f38ba8"
|
|
100
|
+
green = "#a6e3a1"
|
|
101
|
+
subtext0 = "#7c7f93"
|
|
102
|
+
overlay0 = "#7c7f93"
|
|
103
|
+
overlay1 = "#9399b2"
|
|
104
|
+
mauve = "#cba6f7"
|
|
105
|
+
yellow = "#f9e2af"
|
|
106
|
+
blue = "#89b4fa"
|
|
107
|
+
teal = "#94e2d5"
|
|
108
|
+
# END herdr-gentle-theme
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The hex values above are illustrative; the token set, their order and the base
|
|
112
|
+
theme name are not. Tokens are emitted in Herdr's own order (`accent`, `text`,
|
|
113
|
+
`red`, `green`, `subtext0`, `overlay0`, `overlay1`, `mauve`, `yellow`, `blue`,
|
|
114
|
+
`teal`) and lower-cased, so the same palette always renders the same bytes and a
|
|
115
|
+
re-apply of the same palette is a no-op (`current`, no write, no reload). A
|
|
116
|
+
`[theme.custom]` table is omitted entirely when no token survives conversion:
|
|
117
|
+
an empty table would still be an override.
|
|
118
|
+
|
|
119
|
+
The projection is exactly `HERDR_ROLE_SOURCES` in `lib/theme-projection.js`:
|
|
120
|
+
|
|
121
|
+
| Herdr token | Pi theme token |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| `accent` | `accent` |
|
|
124
|
+
| `text` | `text` |
|
|
125
|
+
| `red` | `error` |
|
|
126
|
+
| `green` | `success` |
|
|
127
|
+
| `yellow` | `warning` |
|
|
128
|
+
| `blue` | `mdLink` |
|
|
129
|
+
| `teal` | `syntaxType` |
|
|
130
|
+
| `subtext0` | `muted` |
|
|
131
|
+
| `overlay0` | `muted` |
|
|
132
|
+
| `overlay1` | `thinkingText` |
|
|
133
|
+
| `mauve` | `borderAccent` |
|
|
134
|
+
|
|
135
|
+
`muted` paints two Herdr surfaces on purpose: they are converted once and always
|
|
136
|
+
emitted together, never half-applied. Herdr's surface tokens — `sidebar_bg`,
|
|
137
|
+
`panel_bg`, `active_row_bg`, `selection_bg`, `surface0`, `surface1`,
|
|
138
|
+
`surface_dim` — and `peach` are **never written**: backgrounds and status
|
|
139
|
+
colours stay with the Herdr base theme (`one-dark`) because a Pi theme names
|
|
140
|
+
foregrounds and accents, not panel surfaces, and a guessed background would
|
|
141
|
+
paint a colour nobody chose. A Pi token that is empty (Pi's "terminal default",
|
|
142
|
+
which has no hex spelling) or that does not convert to `#rrggbb` is dropped for
|
|
143
|
+
that apply; the rest of the palette still lands.
|
|
144
|
+
|
|
145
|
+
The block is a *second* managed block, distinct from the sidebar override's
|
|
146
|
+
`herdr-gentle-agents` block, with its own backup file
|
|
147
|
+
`<config>.herdr-gentle-theme.bak`. The two writers share no marker bytes and no
|
|
148
|
+
backup, so each can only ever rewrite its own block.
|
|
149
|
+
|
|
150
|
+
## The writer CLI
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
node herdr-plugin/bin/configure-theme.js [--apply | --remove | --check] [--reload] [--json]
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`--apply` is the default verb. It reads a payload on stdin
|
|
157
|
+
(`{"theme":{"name":"<herdr-theme>","custom":{"<token>":"#rrggbb"}}}`); the Pi
|
|
158
|
+
follower sends exactly that, and a terminal stdin (no pipe) reads as "no
|
|
159
|
+
payload". Accepted names are `catppuccin`, `terminal`, `tokyo-night`, `dracula`,
|
|
160
|
+
`nord`, `gruvbox`, `one-dark`, `solarized`, `kanagawa`, `rose-pine`, `vesper`;
|
|
161
|
+
accepted tokens are the nineteen in
|
|
162
|
+
`herdr-plugin/lib/gentle-theme-config.js` `CUSTOM_TOKENS`.
|
|
163
|
+
|
|
164
|
+
| Verb | Meaning |
|
|
165
|
+
| --- | --- |
|
|
166
|
+
| `--apply` | Validate the payload and write (or repair) the managed block. |
|
|
167
|
+
| `--remove` | Remove the managed block; absent means nothing to do, and a foreign table is left alone. |
|
|
168
|
+
| `--check` | Read-only: `0` when the block is present and current, or absent, `1` when it is stale, `2` when refused. Never writes. Without a payload it round-trips the block on its own; a block that does not match the rendered form is `stale`. |
|
|
169
|
+
| `--reload` | Run `herdr server reload-config` — only after a write. |
|
|
170
|
+
| `--json` | One JSON line on stdout (`op`, `status`, `file`, `theme`, `changed`, plus `reloaded` under `--reload` and `error` on a refusal) instead of a sentence. |
|
|
171
|
+
|
|
172
|
+
Exit codes: `0` applied/current/removed/absent (and `--check` current or
|
|
173
|
+
absent), `1` `--check` found a stale block **or** a requested reload failed
|
|
174
|
+
after a successful write, `2` refused or bad argv. A payload or config refusal
|
|
175
|
+
prints exactly one `configure-theme: …` line on stderr, in every output mode
|
|
176
|
+
(an argv error adds the usage block), and it **guarantees no write, no reload
|
|
177
|
+
and config bytes unchanged**. Node 18 or newer is required; older runtimes exit
|
|
178
|
+
`1` before reading anything.
|
|
179
|
+
|
|
180
|
+
## Refusals
|
|
181
|
+
|
|
182
|
+
Every one of these exits `2` with the config untouched:
|
|
183
|
+
|
|
184
|
+
- **A `[theme]` or `[theme.custom]` table outside the markers** is user config:
|
|
185
|
+
`refusing --apply: a [theme] or [theme.custom] table already exists outside
|
|
186
|
+
the managed markers. This tool only manages its marked block; move or delete
|
|
187
|
+
that table, then re-run.` It is never adopted, merged or overwritten. A bare
|
|
188
|
+
`theme = …` key inside another table is a different key path and is not
|
|
189
|
+
matched.
|
|
190
|
+
- **Malformed markers** — a lone begin, a lone end, end before begin, or a
|
|
191
|
+
second pair — refuse instead of guessing where the block ends:
|
|
192
|
+
`refusing --<verb>: managed theme markers are malformed (unterminated); fix
|
|
193
|
+
them manually.`
|
|
194
|
+
- **An unknown theme name**, an unknown custom token, a non-`#rrggbb` value, an
|
|
195
|
+
extra top-level key or an unknown `theme` key:
|
|
196
|
+
`refusing malformed payload: …`, naming the exact problem.
|
|
197
|
+
- **No payload** for `--apply`, or invalid JSON on stdin.
|
|
198
|
+
- **An unreadable or unwritable config**: `cannot read <file>: …`, or
|
|
199
|
+
`write failed, original untouched: …`.
|
|
200
|
+
- **Argv**: an unknown flag, or more than one verb
|
|
201
|
+
(`choose exactly one of --apply, --remove, --check`).
|
|
202
|
+
|
|
203
|
+
`--remove` on a config with no managed block is `absent` and exits `0` even when
|
|
204
|
+
a foreign `[theme]` table exists: there is nothing of ours to take away, and an
|
|
205
|
+
uninstall must not touch user config.
|
|
206
|
+
|
|
207
|
+
## Failure modes and notices
|
|
208
|
+
|
|
209
|
+
The Pi follower (`extensions/herdr-theme-sync.ts`) applies the palette; it never
|
|
210
|
+
reports success, only failures:
|
|
211
|
+
|
|
212
|
+
- **Plugin root unresolvable** — no `herdr plugin list --json` match, an
|
|
213
|
+
ambiguous or non-absolute root, or no `bin/configure.js` there — notifies
|
|
214
|
+
once per session: `Could not apply the palette to Herdr: <reason> The palette
|
|
215
|
+
Herdr has was left untouched.` and retries on later ticks silently.
|
|
216
|
+
- **Assigned theme not installed** — `ctx.ui.getTheme(name)` returns nothing —
|
|
217
|
+
notifies once per session: `The Pi theme "<name>" is not installed, so Herdr's
|
|
218
|
+
palette was left unchanged; pick an installed theme in /herdr-gentle:customize.`
|
|
219
|
+
A later install of that exact theme is picked up without a restart.
|
|
220
|
+
- **CLI failure** — non-zero exit, a spawn failure or a start error — notifies
|
|
221
|
+
`Could not apply the palette to Herdr: configure-theme exited <status>[: <last
|
|
222
|
+
stderr line>]` (or `<script> could not start (<detail>)`), once per distinct
|
|
223
|
+
message. A success clears the memo, so the same refusal after a good apply is
|
|
224
|
+
reported again. The last stderr line is capped at 300 characters.
|
|
225
|
+
- **A failed apply is never retried automatically.** The observation is recorded
|
|
226
|
+
*before* the spawn, so the next tick acts only on a new palette (or a new
|
|
227
|
+
failure text). One apply is in flight at a time, and a spawn is capped at 60 s.
|
|
228
|
+
- **A theme whose colours cannot be read at all** skips the tick instead of
|
|
229
|
+
stripping Herdr's custom block: an unreadable palette is not evidence that you
|
|
230
|
+
have no palette.
|
|
231
|
+
|
|
232
|
+
## Environment
|
|
233
|
+
|
|
234
|
+
- `HERDR_CONFIG_PATH` — the config file the writer edits and reports.
|
|
235
|
+
- `XDG_CONFIG_HOME` — default config directory (`<xdg>/herdr/config.toml`) when
|
|
236
|
+
`HERDR_CONFIG_PATH` is unset.
|
|
237
|
+
- `HERDR_BIN_PATH` — Herdr binary (default `herdr`) for `plugin list --json`
|
|
238
|
+
(plugin-root lookup) and `server reload-config` (the optional reload).
|
|
239
|
+
- `GENTLE_HERDR_PLUGIN_ROOT` — skip the `plugin list` lookup and name the
|
|
240
|
+
installed plugin root directly (isolated runs).
|
|
241
|
+
- `GENTLE_STATUS_STATE_DIR` — state directory override for `gentle-theme.json`
|
|
242
|
+
and every other file this package writes there.
|
|
243
|
+
- `GENTLE_THEME_SYNC_LIB_DIR` — the directory the follower requires
|
|
244
|
+
`theme-store.js` and `theme-projection.js` from (defaults to this package's
|
|
245
|
+
`lib/`).
|
|
246
|
+
- `GENTLE_CUSTOMIZE_LIB_DIR` — the directory the state sidecar loads the panel
|
|
247
|
+
and the theme store from, so the switch and the follower read the same files.
|
|
248
|
+
|
|
249
|
+
## Limits
|
|
250
|
+
|
|
251
|
+
- **The observation tick is 500 ms**, because the host publishes no
|
|
252
|
+
theme-change event: the palette is a pull-read of `ctx.ui.theme`, evaluated
|
|
253
|
+
once immediately on session start and then every 500 ms. A change is noticed
|
|
254
|
+
within one tick, and a theme recoloured in place (same name, new colours) is
|
|
255
|
+
caught by the palette fingerprint, not only by its name. The timer is
|
|
256
|
+
unreferenced, so an idle follower never keeps Pi alive.
|
|
257
|
+
- **Not proven against a live Pi TUI.** The automated evidence is a stubbed Pi
|
|
258
|
+
host plus a real CLI stand-in on disk; no live-TUI run is recorded.
|
|
259
|
+
`ctx.ui.theme`, `getTheme()`, `getAllThemes()`, `select()` and `notify()` are
|
|
260
|
+
used as the host documents them, and a host that lacks one degrades to
|
|
261
|
+
"nothing changed" rather than a guess.
|
|
262
|
+
- **Herdr keeps the last applied palette** when Pi closes: nothing on shutdown
|
|
263
|
+
writes, removes or reloads. Backgrounds and status colours stay with the Herdr
|
|
264
|
+
base theme, so the sync recolours a sidebar's text and accent surfaces, not
|
|
265
|
+
the whole app chrome.
|
|
266
|
+
- **One machine.** A Herdr client on another host reads its own `config.toml`;
|
|
267
|
+
the sync is local to the machine where Pi runs. There is no pane gate either:
|
|
268
|
+
a Pi session started outside a Herdr pane still updates the config.
|
|
269
|
+
- **No automatic repair.** A `[theme]` table you also maintain by hand outside
|
|
270
|
+
the markers is never reconciled — the writer refuses until you move or delete
|
|
271
|
+
it. Managed markers you edit by hand become "malformed" and stop the writer
|
|
272
|
+
until they are fixed.
|
|
273
|
+
|
|
274
|
+
## Implementation
|
|
275
|
+
|
|
276
|
+
| File | Role |
|
|
277
|
+
| --- | --- |
|
|
278
|
+
| `lib/theme-store.js` | The state document: directory resolution, normalized read, atomic write. |
|
|
279
|
+
| `lib/theme-projection.js` | The pure projection: theme names, token order, `HERDR_ROLE_SOURCES`, `projectPalette`, `paletteFingerprint`, the `Off` label. |
|
|
280
|
+
| `extensions/herdr-theme-sync.ts` | The follower: tick, fingerprint, one `configure-theme.js --apply --json --reload` per change, once-per-failure notices. |
|
|
281
|
+
| `extensions/gentle-herdr-state.ts` | The switch: `applyThemeSync`, `applyThemeSelection`, `customize status`. |
|
|
282
|
+
| `lib/customize-panel.js` | The `Herdr Theme` category and its two rows. |
|
|
283
|
+
| `herdr-plugin/lib/gentle-theme-config.js` | Payload validation, the managed block, refusals, backup and reload. |
|
|
284
|
+
| `herdr-plugin/bin/configure-theme.js` | The CLI verbs, exit codes and output modes. |
|