herdr-gentle-shell 1.7.0 → 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 +99 -7
- package/README.md +30 -8
- 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
package/DESIGN.md
CHANGED
|
@@ -989,10 +989,10 @@ report with a higher seq lands. Parity contract: `working` carries the specific
|
|
|
989
989
|
|
|
990
990
|
The package ships one CLI switch command,
|
|
991
991
|
`node bin/gentle-sidebar.js (enable|disable|status|toggle)` (§7), and one in-Pi
|
|
992
|
-
command, `/herdr-gentle:customize`, with exactly
|
|
993
|
-
sidebar agent rows
|
|
994
|
-
before the `enabled()` pane gate, so
|
|
995
|
-
Pi session outside a Herdr pane. It owns no state of its own and reimplements
|
|
992
|
+
command, `/herdr-gentle:customize`, with exactly three switches: the managed
|
|
993
|
+
sidebar agent rows, the Moshi notification channel and the Herdr theme sync
|
|
994
|
+
(§12). The command registers before the `enabled()` pane gate, so every switch
|
|
995
|
+
stays reachable from a plain Pi session outside a Herdr pane. It owns no state of its own and reimplements
|
|
996
996
|
nothing:
|
|
997
997
|
|
|
998
998
|
- `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js` —
|
|
@@ -1161,9 +1161,9 @@ exactly one mechanism writes each piece of state.
|
|
|
1161
1161
|
panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
|
|
1162
1162
|
ship. This package publishes the Herdr producer sidecar and the Moshi channel
|
|
1163
1163
|
only; `bin/gentle-sidebar.js` is its one CLI and `/herdr-gentle:customize`
|
|
1164
|
-
its one in-Pi command, carrying just the sidebar-rows and
|
|
1165
|
-
Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
|
|
1166
|
-
removed, so no other extension renders those
|
|
1164
|
+
its one in-Pi command, carrying just the sidebar-rows, Moshi and theme-sync
|
|
1165
|
+
switches. Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
|
|
1166
|
+
stays removed, so no other extension renders those switches.
|
|
1167
1167
|
- Rollback: disable this plugin → producer stops writing; consumer sweeps
|
|
1168
1168
|
only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
|
|
1169
1169
|
`↳N` behavior with zero data migration.
|
|
@@ -1251,3 +1251,95 @@ confirming each criterion has a normative section:
|
|
|
1251
1251
|
Task closes when V1–V6 are all traceable above and the file re-read reports
|
|
1252
1252
|
path + line count. Any untraceable cell → `status: partial` with the gap
|
|
1253
1253
|
list, not silent.
|
|
1254
|
+
|
|
1255
|
+
## 12. Theme sync (Pi palette → Herdr theme)
|
|
1256
|
+
|
|
1257
|
+
Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
|
|
1258
|
+
pinned while the sync is off (S1–S5). The switch lives with the other two in
|
|
1259
|
+
`/herdr-gentle:customize`; the user-facing reference is
|
|
1260
|
+
[docs/theme-sync.md](docs/theme-sync.md). Three modules with three owners, and
|
|
1261
|
+
one direction of data:
|
|
1262
|
+
|
|
1263
|
+
| Module | Package | Owns |
|
|
1264
|
+
|---|---|---|
|
|
1265
|
+
| `lib/theme-store.js` | Pi (`herdr-gentle-shell`) | The one persisted document (`gentle-theme.json`): the state-dir resolution copied verbatim from the sidecar's Moshi flag, a normalised read, and the atomic replace. |
|
|
1266
|
+
| `lib/theme-projection.js` | Pi | The pure translation: assignable Herdr theme names, Herdr token order, `HERDR_ROLE_SOURCES`, `projectPalette`, `paletteFingerprint`, and the `null`/`Off` spelling the panel paints. No filesystem, no host import. |
|
|
1267
|
+
| `herdr-plugin/lib/gentle-theme-config.js` + `bin/configure-theme.js` | Herdr plugin | Everything that touches `config.toml`: payload validation, the managed block, the refusals, the atomic write with its own `.bak`, and the optional reload. |
|
|
1268
|
+
|
|
1269
|
+
Two thin glue layers sit above them and own no state: the follower
|
|
1270
|
+
`extensions/herdr-theme-sync.ts` (tick, fingerprint, one spawn per change,
|
|
1271
|
+
notices) and the switch in `extensions/gentle-herdr-state.ts` plus
|
|
1272
|
+
`lib/customize-panel.js` (`applyThemeSync`, `applyThemeSelection`,
|
|
1273
|
+
`customize status`). Pi colours become hex strings in the follower through
|
|
1274
|
+
`colorToHex` from `@earendil-works/pi-tui`, which is why the follower is its own
|
|
1275
|
+
extension rather than a section of the state sidecar: the sidecar is loaded by
|
|
1276
|
+
every suite as a renamed copy with one stubbed host import, and the projection
|
|
1277
|
+
needs no host at all.
|
|
1278
|
+
|
|
1279
|
+
**The state file is the only persisted truth.** `gentle-theme.json` holds
|
|
1280
|
+
`{sync, theme, updatedAt}` and nothing else is cached, mirrored or inferred: the
|
|
1281
|
+
panel and the follower read the same document, so the row, the switch and the
|
|
1282
|
+
applied palette can never disagree. Missing is inert (`sync:false`,
|
|
1283
|
+
`theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
|
|
1284
|
+
painted `Unknown`, follower silent — never a guess, and it is written over only
|
|
1285
|
+
when the user acts. The default install (sync off, no theme) therefore writes
|
|
1286
|
+
nothing at all (S7), while a stored pin is carried across a sync toggle so
|
|
1287
|
+
turning the sync off restores that choice instead of unassigning it.
|
|
1288
|
+
|
|
1289
|
+
**Tick and fingerprint.** The host publishes no theme-change event, so the
|
|
1290
|
+
palette is a pull-read of `ctx.ui.theme` (or `ctx.ui.getTheme(name)` for a pin):
|
|
1291
|
+
one immediate evaluation on `session_start` and then one every 500 ms, on an
|
|
1292
|
+
unreferenced timer so an idle follower never keeps Pi alive. Each evaluation
|
|
1293
|
+
computes two identities — the requested `[sync, chosen]` and the palette
|
|
1294
|
+
fingerprint (`[theme name, sorted token/hex pairs]`) — and acts only when one
|
|
1295
|
+
differs from the last one it recorded, so a theme recoloured in place (same
|
|
1296
|
+
name, new colours) is noticed without a restart, and the same palette is never
|
|
1297
|
+
applied twice. The observation is recorded **before** the spawn, so a failed or
|
|
1298
|
+
refused apply is never retried on the next tick and never blocks the next real
|
|
1299
|
+
change either. One apply is in flight at a time, each spawn is capped at 60 s,
|
|
1300
|
+
and the apply is exactly
|
|
1301
|
+
`<plugin>/bin/configure-theme.js --apply --json --reload` with the projection on
|
|
1302
|
+
stdin. Nothing on shutdown writes, removes or reloads: Herdr keeps the last
|
|
1303
|
+
applied palette (S5). There is deliberately no Herdr pane gate — the config is
|
|
1304
|
+
the user's own and outlives any pane — and no automatic repair of a config the
|
|
1305
|
+
user also edits.
|
|
1306
|
+
|
|
1307
|
+
**Managed block and refusal policy.** The writer owns a second marker-delimited
|
|
1308
|
+
block (`# BEGIN herdr-gentle-theme (managed; do not edit)` …
|
|
1309
|
+
`# END herdr-gentle-theme`) holding `[theme] name = "one-dark"` and a
|
|
1310
|
+
`[theme.custom]` table, in a fixed token order with lower-cased hex, so the same
|
|
1311
|
+
palette is always the same bytes, `current` is a no-op answer, and a refusal can
|
|
1312
|
+
never be mistaken for a change. It reuses `bin/configure.js`'s
|
|
1313
|
+
`herdrConfigPath`/`readConfig`/`writeAtomic`/`removeBlock`/`appendBlock`/
|
|
1314
|
+
`reloadConfig` primitives rather than copying them, so both blocks fail, back up
|
|
1315
|
+
and reload identically — but shares no marker bytes and no backup file, because
|
|
1316
|
+
two writers that share markers each treat the other's block as their own and the
|
|
1317
|
+
last one erases the first. Validation happens before disk: an unknown theme
|
|
1318
|
+
name, an unknown token or a non-`#rrggbb` value is a refusal, not a file Herdr
|
|
1319
|
+
would reject or silently ignore. A `[theme]` or `[theme.custom]` table outside
|
|
1320
|
+
the markers is user config: refuse, never adopt, merge or overwrite. Malformed
|
|
1321
|
+
markers (lone begin, lone end, end before begin, a second pair) refuse instead
|
|
1322
|
+
of guessing where the block ends. `--remove` on an absent block is `absent` and
|
|
1323
|
+
exits 0 even when a foreign table exists, because uninstall must not touch user
|
|
1324
|
+
config. Every refusal guarantees no write, no reload and unchanged config bytes;
|
|
1325
|
+
exit 1 means a stale `--check` or a reload that failed after a successful write.
|
|
1326
|
+
|
|
1327
|
+
**Limits** (the §10 style, none of them a promise this design makes):
|
|
1328
|
+
|
|
1329
|
+
- The 500 ms tick is the whole observation granularity — there is no event to
|
|
1330
|
+
subscribe to, so a theme change is noticed within one tick and not sooner.
|
|
1331
|
+
- The automated evidence is a stubbed Pi host plus a real CLI stand-in on disk;
|
|
1332
|
+
**no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
|
|
1333
|
+
`getAllThemes`, `select` and `notify` are used as documented, and a host
|
|
1334
|
+
missing one degrades to "nothing changed" rather than to a guess.
|
|
1335
|
+
- Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
|
|
1336
|
+
`selection_bg`, `surface*`) and `peach` are never written: Pi names
|
|
1337
|
+
foregrounds and accents, not panel backgrounds, so backgrounds and status
|
|
1338
|
+
colours stay with the Herdr base theme.
|
|
1339
|
+
- One machine: another Herdr client reads its own `config.toml`, so this is a
|
|
1340
|
+
local sync and not a fleet setting.
|
|
1341
|
+
- Plugin-root resolution goes through `herdr plugin list --json` and fails
|
|
1342
|
+
closed on zero or ambiguous matches; that refusal is reported once per session
|
|
1343
|
+
and retried silently afterwards.
|
|
1344
|
+
- The CLI requires Node 18 or newer; an older runtime exits 1 before reading
|
|
1345
|
+
anything.
|
package/README.md
CHANGED
|
@@ -484,10 +484,11 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
484
484
|
managed Herdr rows and records the owned native-extension exclusion;
|
|
485
485
|
`disable` removes only our owned rows and exclusion, never a user table.
|
|
486
486
|
See [docs/sidebar-control.md](docs/sidebar-control.md).
|
|
487
|
-
- In-Pi switches (`/herdr-gentle:customize`):
|
|
488
|
-
state and
|
|
487
|
+
- In-Pi switches (`/herdr-gentle:customize`): three switches, all local
|
|
488
|
+
state and all reachable from a plain Pi session outside a Herdr pane. With
|
|
489
489
|
no argument the command opens the floating panel in Gentle Shell's own
|
|
490
|
-
layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications
|
|
490
|
+
layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
|
|
491
|
+
`Herdr Theme`)
|
|
491
492
|
and one right pane headed `<Category> · n/m` with its setting rows, each row
|
|
492
493
|
painting the stored value with `●` and the other with `○`; one line above the
|
|
493
494
|
footer describes the focused setting (`<setting> — <what it changes>`), and
|
|
@@ -499,11 +500,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
499
500
|
it is a key the panel answers to, and a narrow card compacts it instead of
|
|
500
501
|
wrapping. Pointer input still works without being advertised — a click on a
|
|
501
502
|
category selects it, a click on a row applies it, and a click outside the
|
|
502
|
-
panes is ignored. Each category owns
|
|
503
|
+
panes is ignored. Each category owns its own rows: `Herdr Sidebar`
|
|
503
504
|
shows the single `Sidebar agent rows` row, and the only Moshi switch is the
|
|
504
|
-
`Notifications` row under `Moshi notifications
|
|
505
|
-
|
|
506
|
-
|
|
505
|
+
`Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
|
|
506
|
+
both theme rows (the `Theme sync` toggle and the non-toggle
|
|
507
|
+
`Gentle Shell theme` value row described in the subsection below). The
|
|
508
|
+
sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
|
|
509
|
+
reads nor writes `gentle-moshi.json`, so turning the agent rows off never
|
|
510
|
+
turns the notification channel off. Herdr's own
|
|
507
511
|
done/ask attention (the finished and needs-attention pop-ups and their
|
|
508
512
|
sound) is Herdr's native behavior, configured in Herdr itself — its config
|
|
509
513
|
and its settings — and this package deliberately offers no switch for it:
|
|
@@ -518,7 +522,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
518
522
|
`settings.json`, running the `moshi-hook` pairing gate before enabling (a
|
|
519
523
|
refusal writes nothing) and reloading Pi only when that settings entry
|
|
520
524
|
actually changed. `/herdr-gentle:customize status` prints one read-only line
|
|
521
|
-
(`customize status: sidebar=<on|off|unknown> moshi=<on|off
|
|
525
|
+
(`customize status: sidebar=<on|off|unknown> moshi=<on|off>
|
|
526
|
+
theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
|
|
522
527
|
argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
|
|
523
528
|
`unknown` is never a refusal: the panel says the state is unknown and
|
|
524
529
|
choosing `On` still runs the apply step, reporting that step's own error
|
|
@@ -588,6 +593,22 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
588
593
|
reached through `/herdr-gentle:customize`. See
|
|
589
594
|
[docs/herdr-session-open.md](docs/herdr-session-open.md).
|
|
590
595
|
|
|
596
|
+
### Theme sync (Herdr palette follows Pi)
|
|
597
|
+
|
|
598
|
+
`/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned value.
|
|
599
|
+
`Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
|
|
600
|
+
palette of the theme Pi is showing, and it follows a theme change while Pi keeps
|
|
601
|
+
running. While it is off, `Gentle Shell theme` assigns one Gentle Shell / Pi
|
|
602
|
+
theme by name and the picker's `Off (no theme assigned)` entry clears the pin; the row is refused while the sync is on
|
|
603
|
+
(`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
|
|
604
|
+
nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
|
|
605
|
+
whose sync is off and whose theme is unassigned writes nothing at all. State is
|
|
606
|
+
one file, `gentle-theme.json`, beside `gentle-moshi.json`; the palette reaches
|
|
607
|
+
Herdr through the plugin's own `bin/configure-theme.js`, which owns a marked
|
|
608
|
+
`[theme]` block and refuses to touch a `[theme]` table you maintain yourself.
|
|
609
|
+
See [docs/theme-sync.md](docs/theme-sync.md) for the projection, the CLI and
|
|
610
|
+
the limits.
|
|
611
|
+
|
|
591
612
|
## Documentation
|
|
592
613
|
|
|
593
614
|
| Your task | Start here |
|
|
@@ -598,6 +619,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
598
619
|
| Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
|
|
599
620
|
| Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
|
|
600
621
|
| Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
|
|
622
|
+
| Theme sync (Pi palette → Herdr theme) | [docs/theme-sync.md](docs/theme-sync.md) |
|
|
601
623
|
| Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
|
|
602
624
|
| Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
|
|
603
625
|
|
|
@@ -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. |
|