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.
@@ -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. |