herdr-gentle-shell 1.7.0 → 1.8.1
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 +325 -30
- package/README.md +101 -19
- package/docs/theme-sync.md +737 -0
- package/extensions/gentle-herdr-state.ts +390 -174
- package/extensions/herdr-theme-sync.ts +413 -0
- package/lib/customize-panel.js +608 -239
- package/lib/herdr-theme-apply.js +361 -0
- package/lib/herdr-theme-config.js +1133 -0
- package/lib/theme-projection.js +198 -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` —
|
|
@@ -1012,31 +1012,33 @@ nothing:
|
|
|
1012
1012
|
argument, Esc, or a cancelled menu writes nothing. With no argument the
|
|
1013
1013
|
command opens the floating panel (`lib/customize-panel.js`, painted through its
|
|
1014
1014
|
own palette) over `ctx.ui.custom` in Gentle Shell's own layout: one left
|
|
1015
|
-
`CATEGORIES` list, one right pane headed `<Category> · n/m
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
(
|
|
1019
|
-
|
|
1020
|
-
`
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
`Moshi notifications`, which applies the `gentle-moshi.json` flag
|
|
1034
|
-
`applyMoshiNotifications
|
|
1015
|
+
`CATEGORIES` list, one right pane headed `<Category> · n/m`, and one line per
|
|
1016
|
+
setting with its options inline — `●` the stored option, `›` the cursor while it
|
|
1017
|
+
sits elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
|
|
1018
|
+
applies; `Enter` keeps the card open (only a Moshi settings change that needs a
|
|
1019
|
+
Pi reload closes it), `Esc` closes without a write, `Tab`
|
|
1020
|
+
switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose options
|
|
1021
|
+
do not fit scrolls sideways behind muted `‹`/`›` markers with an `n/m` counter,
|
|
1022
|
+
falling back to a compact `‹ value ›`; the Preview block below the panes reads
|
|
1023
|
+
`Preview · <option> · <title>` plus a sample, and a theme option is painted in
|
|
1024
|
+
that theme's own palette; the footer carries one of three legends (categories,
|
|
1025
|
+
option row, panes) after the `Click · ` prefix, chosen by what the keys do right
|
|
1026
|
+
now and compacted instead of wrapped on a narrow card, with no `p profiles` key
|
|
1027
|
+
because this plugin owns no profiles concept. A click on an option applies
|
|
1028
|
+
exactly that option, a click on a setting's name only moves the focus, a click
|
|
1029
|
+
on a category selects it, and a click outside the panes is ignored (a press only
|
|
1030
|
+
captures the gesture, so a drag never applies anything).
|
|
1031
|
+
Each category owns its own settings: `Herdr Sidebar` shows the single
|
|
1032
|
+
`Sidebar agent rows` setting, the only Moshi switch is the `Notifications`
|
|
1033
|
+
setting under `Moshi notifications`, which applies the `gentle-moshi.json` flag
|
|
1034
|
+
through `applyMoshiNotifications`, and `Herdr Theme` owns the `Theme sync`
|
|
1035
|
+
toggle plus the inline `Gentle Shell theme` list (§12). The two channels are
|
|
1036
|
+
never mixed: the sidebar-rows
|
|
1035
1037
|
switch neither reads nor writes that flag, so disabling the agent rows leaves
|
|
1036
1038
|
the notification channel exactly as it was.
|
|
1037
|
-
An inconclusive sidebar verdict (`unknown`) renders
|
|
1038
|
-
instead of hiding the
|
|
1039
|
-
apply step's own error, exactly like the menu. The plain
|
|
1039
|
+
An inconclusive sidebar verdict (`unknown`) renders with no option marked `●`
|
|
1040
|
+
and a note instead of hiding the setting: toggling still attempts the repair and
|
|
1041
|
+
reports the apply step's own error, exactly like the menu. The plain
|
|
1040
1042
|
two-step `ctx.ui.select` menu remains the
|
|
1041
1043
|
fallback when the TUI helpers or `ctx.ui.custom` are unavailable. The removed
|
|
1042
1044
|
`Plugin tools` and `Reset` sections and the in-process provider slot
|
|
@@ -1161,9 +1163,9 @@ exactly one mechanism writes each piece of state.
|
|
|
1161
1163
|
panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
|
|
1162
1164
|
ship. This package publishes the Herdr producer sidecar and the Moshi channel
|
|
1163
1165
|
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
|
|
1166
|
+
its one in-Pi command, carrying just the sidebar-rows, Moshi and theme-sync
|
|
1167
|
+
switches. Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
|
|
1168
|
+
stays removed, so no other extension renders those switches.
|
|
1167
1169
|
- Rollback: disable this plugin → producer stops writing; consumer sweeps
|
|
1168
1170
|
only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
|
|
1169
1171
|
`↳N` behavior with zero data migration.
|
|
@@ -1251,3 +1253,296 @@ confirming each criterion has a normative section:
|
|
|
1251
1253
|
Task closes when V1–V6 are all traceable above and the file re-read reports
|
|
1252
1254
|
path + line count. Any untraceable cell → `status: partial` with the gap
|
|
1253
1255
|
list, not silent.
|
|
1256
|
+
|
|
1257
|
+
## 12. Theme sync (Pi palette → Herdr theme)
|
|
1258
|
+
|
|
1259
|
+
Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
|
|
1260
|
+
pinned while the sync is off (S1–S7). The switch lives with the other two in
|
|
1261
|
+
`/herdr-gentle:customize`; the user-facing reference is
|
|
1262
|
+
[docs/theme-sync.md](docs/theme-sync.md). Six modules with one owner — this Pi
|
|
1263
|
+
package — and one direction of data:
|
|
1264
|
+
|
|
1265
|
+
| Module | Owns |
|
|
1266
|
+
| --- | --- |
|
|
1267
|
+
| `lib/theme-store.js` | 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. |
|
|
1268
|
+
| `lib/theme-projection.js` | The pure translation: assignable Herdr theme names, Herdr token order, `HERDR_ROLE_SOURCES`, the `DOTS_FIXED` surface tables, `projectPalette`, `paletteFingerprint`, and the `Off` label the projection exposes. No filesystem, no host import. |
|
|
1269
|
+
| `lib/herdr-theme-config.js` | The pure planner — a **line splicer, not a TOML validator**: table-boundary scanning (headers only at real line starts), opaque bytes outside the two theme tables, a strict theme-table grammar, the whole-line `was` marker with byte-exact restoration (the user's latest trailing comment wins), the single regenerated block (`begin` / `begin created` … `end` / `end after a missing line ending`) and the created table it removes again, the ambiguity refusal for a marker-shaped comment above a block being removed or moved, the 1.8.0 marker-pair migration, the BOM, and the enforced splice invariant. |
|
|
1270
|
+
| `lib/herdr-theme-apply.js` | The writer: the availability guard matrix, the bounded snapshot, the two compare-and-swap checks, the atomic non-overwriting backup (a regular existing file is accepted as it is), retried temp cleanup that names a survivor and only ever removes a path it created itself, the growth limit, `forceReload`, the exclusive temp + `fchmod` (all mode bits) + `fsync` + `rename`, and the reload. |
|
|
1271
|
+
| `extensions/herdr-theme-sync.ts` | The follower: session-start evaluation, 500 ms tick, the two identities, one in-process apply per change, the notices. |
|
|
1272
|
+
| `lib/customize-panel.js` + the theme wiring in `extensions/gentle-herdr-state.ts` | The switch and the card: `applyThemeSync`, `writeThemeChoice`, `applyCustomizePanel`, `customize status`, and the setting lines, Preview block, legends and pointer hits. |
|
|
1273
|
+
|
|
1274
|
+
**In process, and why that is the fix.** The 1.8.0 follower spawned
|
|
1275
|
+
`bin/configure-theme.js` from the *separately installed* Herdr plugin, found
|
|
1276
|
+
through `herdr plugin list`, and that writer refused any `[theme]` table outside
|
|
1277
|
+
its own marker block. A Pi-only update therefore kept running the old plugin's
|
|
1278
|
+
writer — or, on an install that never shipped it, ran no writer at all — while
|
|
1279
|
+
the user's real config, which already owns `[theme]`, was never touched. The
|
|
1280
|
+
reference implementation
|
|
1281
|
+
([gentle-herdr](https://github.com/MarsSall/gentle-herdr), MIT License,
|
|
1282
|
+
Copyright (c) MarsSall) applies from Pi itself, so this package does the same:
|
|
1283
|
+
`applyHerdrTheme` edits the config inside the running Pi process, and the
|
|
1284
|
+
plugin-side `configure-theme.js`, its planner and the
|
|
1285
|
+
`# BEGIN herdr-gentle-theme` managed block are gone. The plugin is not involved
|
|
1286
|
+
in theme sync and needs no update for it. A config written by 1.8.0 keeps
|
|
1287
|
+
working: the planner drops those two marker lines only when they are the nearest
|
|
1288
|
+
pair and the pair actually encloses a `[theme]`/`[theme.custom]` table (a stale
|
|
1289
|
+
pair around unrelated keys is the user's text and stays, and a pair closing on an
|
|
1290
|
+
unterminated last line migrates without changing the file's final-newline state),
|
|
1291
|
+
then edits the table between them like any other. Pi colours become hex
|
|
1292
|
+
strings in the follower through `colorToHex` from `@earendil-works/pi-tui`,
|
|
1293
|
+
which is why the follower is its own extension rather than a section of the
|
|
1294
|
+
state sidecar: the sidecar is loaded by every suite as a renamed copy with one
|
|
1295
|
+
stubbed host import, and the projection needs no host at all.
|
|
1296
|
+
|
|
1297
|
+
**Ownership rule, and the two classes it implies.** Sync is a switch the user
|
|
1298
|
+
turns on deliberately, so with the sync on — or a theme pinned — this package
|
|
1299
|
+
OWNS the `name` line and every token it projects, and it must be able to give
|
|
1300
|
+
them back. Two classes, which is what makes switching Pi themes safe:
|
|
1301
|
+
|
|
1302
|
+
- **a value the user already had** is replaced in place and remembered by one
|
|
1303
|
+
comment recording **the whole original line** (minus its indentation, so
|
|
1304
|
+
trailing spaces and an inline comment are part of the record) above it: the
|
|
1305
|
+
first original wins, a later palette change reuses it, and a projection that
|
|
1306
|
+
stops carrying that token — or comes back to the recorded value — **restores
|
|
1307
|
+
the line byte for byte** and drops the comment. The one exception is the
|
|
1308
|
+
**latest edit wins**: if the user changed the line's trailing comment after the
|
|
1309
|
+
planner wrote its value, the restore keeps the recorded key/value and the
|
|
1310
|
+
user's *current* comment. A comment is only a marker when
|
|
1311
|
+
its payload parses as the strict `key = <string> [comment]` line for the key
|
|
1312
|
+
under it, and two markers for one key are refused;
|
|
1313
|
+
- **a token the user did not have** is written inside ONE marked block
|
|
1314
|
+
(`# herdr-gentle-shell: begin` … `# herdr-gentle-shell: end`, or
|
|
1315
|
+
`# herdr-gentle-shell: begin created` when the planner also creates the table,
|
|
1316
|
+
and closed with `# herdr-gentle-shell: end after a missing line ending` when
|
|
1317
|
+
placing the block also added the file's missing final line ending, so a later
|
|
1318
|
+
clear takes back only what the planner added)
|
|
1319
|
+
at the end of `[theme.custom]`, regenerated on every plan, and removed entirely
|
|
1320
|
+
when nothing is left to own — so leaving a projection never leaves a stale
|
|
1321
|
+
colour behind. A table the planner created is removed again once its block
|
|
1322
|
+
empties and nothing else lives in it, which is what makes a cycle of
|
|
1323
|
+
projections ending in an empty custom projection return the original
|
|
1324
|
+
`[theme.custom]` byte for byte; only `<token> = "#rrggbb"` lines may sit
|
|
1325
|
+
inside the block, and anything else there is refused rather than deleted.
|
|
1326
|
+
Removing or moving a block is refused
|
|
1327
|
+
(`line <n>: ambiguous herdr-gentle-shell marker above the managed block`) when a
|
|
1328
|
+
marker-shaped comment directly above `begin` would become adjacent to the token
|
|
1329
|
+
key under the block, because the next plan would promote the user's ordinary
|
|
1330
|
+
comment to ownership.
|
|
1331
|
+
|
|
1332
|
+
A token the user owns with no marker (`panel_bg`, `blue`, `yellow`, …) is never
|
|
1333
|
+
written, merged or repaired, even when the projection stops carrying it: it was
|
|
1334
|
+
never ours. A `[theme.custom]` header the **user** wrote stays even when it ends
|
|
1335
|
+
up empty, because the planner cannot prove it created that line. Two
|
|
1336
|
+
consequences are stated rather than papered over: a tool that rewrites the same
|
|
1337
|
+
keys (a desktop-theme sync such as DMS/Niri, for example) overwrites the
|
|
1338
|
+
projected values on its next run, and the next palette change here overwrites
|
|
1339
|
+
them back; and the revert is per token, not per file — a user-written empty header
|
|
1340
|
+
and the `name` marker stay. This is also where
|
|
1341
|
+
the port deliberately differs from the reference: it accepts
|
|
1342
|
+
`auto_switch = false` untouched — the reference refuses that line outright,
|
|
1343
|
+
which is exactly why the user's real config was never written — and it edits
|
|
1344
|
+
tables the reference treats as foreign.
|
|
1345
|
+
|
|
1346
|
+
**The state file is the only persisted truth.** `gentle-theme.json` holds
|
|
1347
|
+
`{sync, theme, updatedAt}` and nothing else is cached, mirrored or inferred: the
|
|
1348
|
+
panel and the follower read the same document, so the setting, the switch and
|
|
1349
|
+
the applied palette can never disagree. Missing is inert (`sync:false`,
|
|
1350
|
+
`theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
|
|
1351
|
+
no option marked, a `state unknown` note, follower silent — never a guess, and
|
|
1352
|
+
it is written over only
|
|
1353
|
+
when the user acts. The default install (sync off, no theme) therefore writes
|
|
1354
|
+
nothing at all (S7), and a stored pin is carried across a sync toggle so turning
|
|
1355
|
+
the sync off restores that choice instead of unassigning it.
|
|
1356
|
+
|
|
1357
|
+
**Tick, fingerprint and the follower repairs.** The host publishes no
|
|
1358
|
+
theme-change event, so the palette is a pull-read of `ctx.ui.theme` (or
|
|
1359
|
+
`ctx.ui.getTheme(name)` for a pin): one immediate evaluation on `session_start`
|
|
1360
|
+
and then one every 500 ms, on an unreferenced timer so an idle follower never
|
|
1361
|
+
keeps Pi alive, cleared on `session_shutdown` (a shutdown that lands during the
|
|
1362
|
+
first evaluation wins: no tick is armed afterwards). Each evaluation computes two
|
|
1363
|
+
identities — the requested `[sync, chosen]` and the palette fingerprint
|
|
1364
|
+
(`[theme name, sorted token/hex pairs]`) — and acts only when one differs from
|
|
1365
|
+
the last one it recorded, so a theme recoloured in place (same name, new
|
|
1366
|
+
colours) is noticed without a restart, and the same palette is never applied
|
|
1367
|
+
twice. The observation is recorded **before** the apply, so a failed or refused
|
|
1368
|
+
write is never retried on the next tick and never blocks the next real change
|
|
1369
|
+
either; one apply is in flight at a time. With the sync off and no theme pinned
|
|
1370
|
+
the follower asks for nothing at all (no write, no removal) **and forgets what it
|
|
1371
|
+
applied**, which is what makes re-enabling the sync always re-apply: without that
|
|
1372
|
+
reset the next `On` would look unchanged and a config the user repaired in
|
|
1373
|
+
between would never be written (an already-matching config then answers
|
|
1374
|
+
`unchanged`). A projection with no concrete token is refused before the writer is
|
|
1375
|
+
called — `Herdr theme not applied: <name> has no concrete colours to project.`,
|
|
1376
|
+
once per session — because it would otherwise rewrite the theme name and paint
|
|
1377
|
+
nothing. Availability is decided once, by `applyHerdrTheme`, so the follower can
|
|
1378
|
+
never disagree with the writer about who may write; a subagent child
|
|
1379
|
+
(`GENTLE_PI_AGENTS_CHILD=1`) never registers the follower at all, and every
|
|
1380
|
+
user-visible outcome is one of the fixed notices in
|
|
1381
|
+
[docs/theme-sync.md](docs/theme-sync.md). A `partial/reload` sets an **owed
|
|
1382
|
+
reload**: the next apply attempt of the same session is sent with
|
|
1383
|
+
`forceReload`, and a success pays the debt off. It is session memory on purpose
|
|
1384
|
+
(a tick never reloads while the debt stands), which is why the notice ends with
|
|
1385
|
+
`Run 'herdr server reload-config' to apply it.`
|
|
1386
|
+
|
|
1387
|
+
**A splicer, and a strict core.** The writer edits the user's own `[theme]` and
|
|
1388
|
+
`[theme.custom]` tables and preserves every byte it does not own: other tables
|
|
1389
|
+
and keys, comments, blank lines, ordering, indentation, spacing around `=`, a
|
|
1390
|
+
trailing comment on a rewritten line, CRLF or mixed endings, a leading UTF-8 BOM
|
|
1391
|
+
and a missing final newline. **Outside those two tables nothing is validated**:
|
|
1392
|
+
the planner only tracks the three contexts that can hide a line
|
|
1393
|
+
break (multi-line strings, multi-line arrays, inline tables) plus comments, so it
|
|
1394
|
+
can find table boundaries — a header-shaped line must parse and a multi-line
|
|
1395
|
+
construct must be terminated, or the plan refuses — and it treats the rest of the
|
|
1396
|
+
document as opaque bytes: an input that is already invalid TOML there is the
|
|
1397
|
+
user's pre-existing breakage (Herdr refuses to load it) and is left exactly as it
|
|
1398
|
+
is. Escapes there are never validated (a backslash only consumes the next
|
|
1399
|
+
character, in single-line and multi-line strings alike) and a run of three or
|
|
1400
|
+
more quotes closes a multi-line string; the scan validates escapes only where it
|
|
1401
|
+
must read a value back (a quoted key and a strict theme-table line).
|
|
1402
|
+
**Inside the two tables it is strict**: comments, blank lines and
|
|
1403
|
+
`key = value [comment]` with a single-line string, boolean, integer or float; a
|
|
1404
|
+
key the plan must touch in any other form is refused with its line number, while
|
|
1405
|
+
a key it does not touch is kept byte for byte whenever the scanner can find where
|
|
1406
|
+
that line ends. It refuses: `auto_switch` with a value other than `false`,
|
|
1407
|
+
`dark_name`/`light_name`, a top-level `theme` key, a dotted key extending
|
|
1408
|
+
`[theme]` or a Herdr token in `[theme.custom]`, a second `[theme]`/`[theme.custom]`
|
|
1409
|
+
table, a third `[theme.*]` table, `[[theme]]` array-of-tables, `name`/
|
|
1410
|
+
`auto_switch` repeated in `[theme]`, a token repeated in `[theme.custom]` or in
|
|
1411
|
+
both the block and the user's keys, two markers for one key, a touched value that
|
|
1412
|
+
is not a strict single-line string (or a multi-line form, refused as "cannot
|
|
1413
|
+
record the original value … safely"), a control character, a bare carriage
|
|
1414
|
+
return, a malformed block (outside `[theme.custom]`, unterminated, a second
|
|
1415
|
+
begin, an end without a begin, any line in it that is not
|
|
1416
|
+
`<token> = "#rrggbb"`), the ambiguous marker above a block that is about to be
|
|
1417
|
+
removed or moved (`ambiguous herdr-gentle-shell marker above the managed
|
|
1418
|
+
block`), and a table header or unterminated multi-line string/array/inline table
|
|
1419
|
+
the boundary scan cannot resolve. A malformed
|
|
1420
|
+
projection is refused the same way without a line number, because that one is a
|
|
1421
|
+
package bug. **The splice invariant is enforced in code**: before `ok: true` the
|
|
1422
|
+
planner re-derives the non-theme lines of its own output and compares them with
|
|
1423
|
+
the input's (only the 1.8.0 marker lines it wrote may be missing, and only the
|
|
1424
|
+
single terminator needed to append a table after an unterminated last line may be
|
|
1425
|
+
added); a mismatch returns `internal splice invariant violated; no changes
|
|
1426
|
+
proposed.` rather than a document that moved a byte it promised not to touch. The
|
|
1427
|
+
file-level refusals belong to the snapshot and the write: a non-absolute or
|
|
1428
|
+
non-canonical path, a symlinked parent directory, not a regular single-link
|
|
1429
|
+
file, over 256 KiB, invalid UTF-8, a backup path that is not a regular file, a
|
|
1430
|
+
planned document past the 256 KiB limit, bytes that changed between the snapshot
|
|
1431
|
+
and the replacement (`Herdr config changed before replacement`), a backup temp
|
|
1432
|
+
that cannot be removed, a missing config (never bootstrapped), and a failed
|
|
1433
|
+
rename. Every refusal writes nothing, backs up nothing and reloads nothing.
|
|
1434
|
+
|
|
1435
|
+
**Safe write, and exactly one reload.** The snapshot is one bounded strictly
|
|
1436
|
+
decoded read with stat identity checks; a leading BOM is decoded as part of the
|
|
1437
|
+
text (`ignoreBOM`) so a changed write keeps it and the backup and the file agree
|
|
1438
|
+
on those bytes. The plan is refused **before anything is written** if the
|
|
1439
|
+
document would grow past the same 256 KiB limit. The original bytes are re-read
|
|
1440
|
+
and compared immediately before the backup and again immediately before the
|
|
1441
|
+
swap, so a projection computed from stale bytes is never renamed into place. The new text
|
|
1442
|
+
is staged at a path chosen **before the file exists**, so every failure — open,
|
|
1443
|
+
write, `fsync`, `fchmod` — leaves the writer able to remove it: exclusive `0600`,
|
|
1444
|
+
`fchmod`-ed to the original mode (`0o7777`, so setuid/setgid/sticky survive),
|
|
1445
|
+
compared once more, then `rename`d. Temp cleanup is best-effort **and never
|
|
1446
|
+
silent**: the unlink is retried once and then force-removed, and a survivor is
|
|
1447
|
+
reported instead of hiding — if the **backup's** temp survives, the apply fails
|
|
1448
|
+
with `Herdr backup temporary could not be removed: <path>` (so it can never
|
|
1449
|
+
answer `requested` with a stray file), and a surviving **staged** temp appends
|
|
1450
|
+
`; temporary file left behind: <path>` to the `partial`/`config` error. Cleanup
|
|
1451
|
+
only ever removes a path the call created itself: a foreign file at that exact
|
|
1452
|
+
temp name makes the exclusive open fail with `EEXIST`, the apply answers
|
|
1453
|
+
`partial`/`config` with that text, and the file is left alone (config and backup
|
|
1454
|
+
untouched). The
|
|
1455
|
+
backup itself is **published atomically and never overwritten**: written to a
|
|
1456
|
+
temp name and hard-linked into place, so a crash or a full disk leaves no
|
|
1457
|
+
truncated `.bak` that a later run would mistake for "already backed up". A
|
|
1458
|
+
regular file already at the backup path — pre-existing or raced — **is** the
|
|
1459
|
+
existing backup: accepted as it is, never compared and never overwritten (it may
|
|
1460
|
+
be an older original from before the user's last edit), while a non-regular
|
|
1461
|
+
entry (directory, symlink, socket) is refused. `unchanged` writes
|
|
1462
|
+
nothing and reloads nothing — Herdr already holds that palette, and a reload on
|
|
1463
|
+
every tick would make the sidebar flicker for nothing. `forceReload` is the one
|
|
1464
|
+
exception, and it exists for the owed-reload repair above: it reloads an
|
|
1465
|
+
unchanged plan and answers `requested`. A real write is followed by exactly one
|
|
1466
|
+
`herdr server reload-config` through `execFile` with `HERDR_BIN_PATH` (default
|
|
1467
|
+
`herdr`), no shell, a 5 s timeout and a 4096-byte output cap; a reload failure is
|
|
1468
|
+
reported as partial state because the config is already committed. **CAS limit:**
|
|
1469
|
+
an edit that lands between the final compare and the `rename` cannot be detected
|
|
1470
|
+
without holding a lock on the config, which this writer deliberately does not
|
|
1471
|
+
do — everything earlier (snapshot, plan, backup, staging) is still caught. A
|
|
1472
|
+
**pre-existing truncated backup** is a second documented limit: because a regular
|
|
1473
|
+
file at that path is accepted as it is and never repaired or compared, a `.bak`
|
|
1474
|
+
damaged by an earlier failure or another tool stays damaged.
|
|
1475
|
+
|
|
1476
|
+
**The guard matrix.** `applyHerdrTheme` answers `unavailable` with one reason
|
|
1477
|
+
before it opens any file: `not-herdr` (no `HERDR_ENV=1` plus a pane id and an
|
|
1478
|
+
absolute socket path), `child` (a subagent's Pi must never write the user's
|
|
1479
|
+
config), `remote` (an SSH session, where Herdr reads another machine's config),
|
|
1480
|
+
and `unsupported` (a `herdr-dev` binary, a non-Linux host, or a non-absolute
|
|
1481
|
+
socket/config path). The follower reports `not-herdr`, `remote` and
|
|
1482
|
+
`unsupported` as one `info` notice per session and asks again only when the
|
|
1483
|
+
palette itself changes.
|
|
1484
|
+
|
|
1485
|
+
**The panel.** `/herdr-gentle:customize` reuses Gentle Shell's own card shape:
|
|
1486
|
+
one left `CATEGORIES` list, one right pane headed `<Category> · n/m`, one line
|
|
1487
|
+
per setting with its options inline (`●` stored, `›` cursor elsewhere, `○` the
|
|
1488
|
+
rest). The arrows move the option cursor and only Enter applies; Enter keeps the
|
|
1489
|
+
card open (only the Moshi reload closes it), Esc closes without a write, Tab
|
|
1490
|
+
switches panes. A line whose options do not fit scrolls sideways behind muted
|
|
1491
|
+
`‹`/`›` with an `n/m` counter, falling back to a compact `‹ value ›`. The
|
|
1492
|
+
Preview block below the panes is `Preview · <option> · <title>` plus a sample
|
|
1493
|
+
painted with the host theme, where a theme option shows that theme's own palette
|
|
1494
|
+
through the raw SGR the host hands back. Three footer legends (categories,
|
|
1495
|
+
option row, panes) are chosen by what the keys do right now and compact instead
|
|
1496
|
+
of wrapping. The theme list comes from `ctx.ui.getAllThemes()` in the host's own
|
|
1497
|
+
order with `None` first, the `Gentle Shell theme` setting is painted dim and
|
|
1498
|
+
refused with `Turn Theme sync off to pick a specific theme.` while the sync is
|
|
1499
|
+
on, and a host that exposes no list shows one note instead of an empty picker.
|
|
1500
|
+
The panel writes nothing itself: it calls the extension's apply path, swaps in
|
|
1501
|
+
the model that path re-read, and keeps the cursor by structural option ids.
|
|
1502
|
+
|
|
1503
|
+
**Limits** (the §10 style, none of them a promise this design makes):
|
|
1504
|
+
|
|
1505
|
+
- The 500 ms tick is the whole observation granularity — there is no event to
|
|
1506
|
+
subscribe to, so a theme change is noticed within one tick and not sooner.
|
|
1507
|
+
- The automated evidence is a stubbed Pi host plus a real binary stand-in on
|
|
1508
|
+
disk; **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
|
|
1509
|
+
`getAllThemes`, `notify` and the host component contract are used as
|
|
1510
|
+
documented, and a host missing one degrades to "nothing changed" rather than
|
|
1511
|
+
to a guess.
|
|
1512
|
+
- Remote sessions are inactive: in SSH the Herdr client reads the config of the
|
|
1513
|
+
machine it runs on, so writing the server-side file would change nothing on
|
|
1514
|
+
screen and the guard refuses.
|
|
1515
|
+
- Two writers of the same keys fight. The sync owns what it projects, so a
|
|
1516
|
+
desktop-theme sync and this feature overwrite each other on their next run;
|
|
1517
|
+
there is no merge, lock or arbitration, only the `was` comments, the marked
|
|
1518
|
+
block and the one-time backup.
|
|
1519
|
+
- The compare-and-swap has one unavoidable window: an edit between the final
|
|
1520
|
+
compare and the rename is undetectable without a config lock, which this
|
|
1521
|
+
writer does not take.
|
|
1522
|
+
- The planner is a **splicer, not a validator**: it guarantees table boundaries
|
|
1523
|
+
for terminated multi-line constructs and byte-identical non-theme lines (checked
|
|
1524
|
+
by the splice invariant), and it deliberately checks nothing outside the theme
|
|
1525
|
+
tables — invalid TOML there is left as it is, because Herdr already refuses
|
|
1526
|
+
that file. A theme-table line the plan must touch has to be the strict
|
|
1527
|
+
single-line form; the revert is per token, so a user-written empty
|
|
1528
|
+
`[theme.custom]` header and the `name` marker stay behind (a table the planner
|
|
1529
|
+
created is removed, so a full cycle is byte-identical).
|
|
1530
|
+
- A pre-existing truncated backup is kept, not repaired (see above), which is why
|
|
1531
|
+
the `was` comments are the per-value revert path.
|
|
1532
|
+
- There is no "full clear" distinct from an empty custom projection: a projection
|
|
1533
|
+
always carries the theme name, so a `name` line the planner inserted stays (an
|
|
1534
|
+
existing name is restored) and a `[theme]` table it created is not removed —
|
|
1535
|
+
only the `[theme.custom]` table it created is, once its block empties.
|
|
1536
|
+
- Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
|
|
1537
|
+
`selection_bg`, `surface*`) and `peach` are not projected: Pi names
|
|
1538
|
+
foregrounds and accents, not panel backgrounds, so backgrounds and status
|
|
1539
|
+
colours stay with the Herdr base theme — except the `DOTS_FIXED` tables for
|
|
1540
|
+
`Gentleman-Cute`, `Gentleman-Sexy` and `Gentle`, which are the surfaces the
|
|
1541
|
+
user's own Herdr profiles already use.
|
|
1542
|
+
- One machine: another Herdr client reads its own `config.toml`, so this is a
|
|
1543
|
+
local sync and not a fleet setting.
|
|
1544
|
+
- No automatic repair: a `[theme]` table the user or another tool keeps editing
|
|
1545
|
+
is re-projected on the next palette change and never reconciled, and a document
|
|
1546
|
+
whose table boundaries cannot be found (an unterminated multi-line string,
|
|
1547
|
+
array or inline table) stops the writer until it is fixed. A missing
|
|
1548
|
+
`config.toml` is refused, never created.
|
package/README.md
CHANGED
|
@@ -484,26 +484,37 @@ 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
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
the
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
490
|
+
layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
|
|
491
|
+
`Herdr Theme`)
|
|
492
|
+
and one right pane headed `<Category> · n/m`, where each setting is ONE line
|
|
493
|
+
with its options inline — `●` the stored option, `›` the cursor while it sits
|
|
494
|
+
elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
|
|
495
|
+
applies; `Enter` keeps the card open (a Moshi change that needs a Pi reload
|
|
496
|
+
closes it first), `Esc` closes without a write, `Tab`
|
|
497
|
+
switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose
|
|
498
|
+
options do not fit scrolls sideways behind muted `‹` / `›` markers with an
|
|
499
|
+
`n/m` counter (falling back to a compact `‹ value ›` when not even one option
|
|
500
|
+
fits), and the Preview block below the panes reads
|
|
501
|
+
`Preview · <option> · <title>` plus a sample painted with the host theme (a
|
|
502
|
+
theme option shows that theme's own palette). The footer carries one of three
|
|
503
|
+
legends after a `Click · ` prefix —
|
|
504
|
+
`↑/↓ categories · → open · Esc close`,
|
|
505
|
+
`←/→ choose · Enter apply · ↑/↓ settings · Tab panes · Esc close`, or
|
|
506
|
+
`←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close` — and compacts
|
|
507
|
+
instead of wrapping on a narrow card. A click on an option applies exactly
|
|
508
|
+
that option, a click on a setting's name only moves the focus, a click on a
|
|
509
|
+
category selects it, and a click outside the panes is ignored. Each category
|
|
510
|
+
owns its own rows: `Herdr Sidebar`
|
|
503
511
|
shows the single `Sidebar agent rows` row, and the only Moshi switch is the
|
|
504
|
-
`Notifications` row under `Moshi notifications
|
|
505
|
-
|
|
506
|
-
|
|
512
|
+
`Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
|
|
513
|
+
both theme settings (the `Theme sync` toggle and the inline
|
|
514
|
+
`Gentle Shell theme` list described in the subsection below). The
|
|
515
|
+
sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
|
|
516
|
+
reads nor writes `gentle-moshi.json`, so turning the agent rows off never
|
|
517
|
+
turns the notification channel off. Herdr's own
|
|
507
518
|
done/ask attention (the finished and needs-attention pop-ups and their
|
|
508
519
|
sound) is Herdr's native behavior, configured in Herdr itself — its config
|
|
509
520
|
and its settings — and this package deliberately offers no switch for it:
|
|
@@ -518,7 +529,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
518
529
|
`settings.json`, running the `moshi-hook` pairing gate before enabling (a
|
|
519
530
|
refusal writes nothing) and reloading Pi only when that settings entry
|
|
520
531
|
actually changed. `/herdr-gentle:customize status` prints one read-only line
|
|
521
|
-
(`customize status: sidebar=<on|off|unknown> moshi=<on|off
|
|
532
|
+
(`customize status: sidebar=<on|off|unknown> moshi=<on|off>
|
|
533
|
+
theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
|
|
522
534
|
argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
|
|
523
535
|
`unknown` is never a refusal: the panel says the state is unknown and
|
|
524
536
|
choosing `On` still runs the apply step, reporting that step's own error
|
|
@@ -588,6 +600,75 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
588
600
|
reached through `/herdr-gentle:customize`. See
|
|
589
601
|
[docs/herdr-session-open.md](docs/herdr-session-open.md).
|
|
590
602
|
|
|
603
|
+
### Theme sync (Herdr palette follows Pi)
|
|
604
|
+
|
|
605
|
+
`/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned theme.
|
|
606
|
+
`Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
|
|
607
|
+
palette of the theme Pi is showing, and it follows a theme change while Pi keeps
|
|
608
|
+
running. While it is off, `Gentle Shell theme` pins one Gentle Shell / Pi theme
|
|
609
|
+
from Pi's own inline list (`None` first, then the host's order) and `None`
|
|
610
|
+
clears the pin; the setting is painted dim and refused while the sync is on
|
|
611
|
+
(`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
|
|
612
|
+
nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
|
|
613
|
+
whose sync is off and whose theme is unassigned writes nothing at all. State is
|
|
614
|
+
one file, `gentle-theme.json`, beside `gentle-moshi.json`.
|
|
615
|
+
|
|
616
|
+
The writer runs **in process in this Pi package**
|
|
617
|
+
(`lib/herdr-theme-config.js` plans it, `lib/herdr-theme-apply.js` writes it,
|
|
618
|
+
`extensions/herdr-theme-sync.ts` follows the theme), so the Herdr plugin is not
|
|
619
|
+
involved and needs no update for this feature. It is a **line splicer, not a TOML
|
|
620
|
+
validator**: it finds the boundaries of your `[theme]` and `[theme.custom]`
|
|
621
|
+
tables (a header only counts at a real line start, never inside a multi-line
|
|
622
|
+
string, array or comment) and treats every line outside them as opaque bytes —
|
|
623
|
+
nothing there is validated or rewritten (escapes included), and an invalid line
|
|
624
|
+
outside those tables is left exactly as it is, because Herdr already refuses such
|
|
625
|
+
a file (the scanner only looks at those lines far enough to find where a table
|
|
626
|
+
starts and ends). A
|
|
627
|
+
splice invariant is enforced before a plan is returned: the non-theme lines of
|
|
628
|
+
the output must be byte-identical to the input's.
|
|
629
|
+
|
|
630
|
+
Inside the two theme tables it edits in place and keeps two kinds of value
|
|
631
|
+
apart: a value you already had is replaced where it stands and remembered by one
|
|
632
|
+
comment recording **the whole original line** (one per key; the first original
|
|
633
|
+
wins, and restoring gives back your quoting, spacing and inline comment — or
|
|
634
|
+
**your current comment** when you edited it after the planner wrote the value,
|
|
635
|
+
because the latest edit wins), while
|
|
636
|
+
a token you did not have is written inside ONE marked block — a `begin`/`end`
|
|
637
|
+
comment pair naming this package, spelled `begin created` when the planner also
|
|
638
|
+
created the table and closed with `end after a missing line ending` when placing
|
|
639
|
+
the block also added the file's missing final newline, so clearing gives that
|
|
640
|
+
byte back — at the
|
|
641
|
+
end of `[theme.custom]`, regenerated on every apply. Leaving a theme therefore
|
|
642
|
+
never leaves a stale colour: a token that leaves the projection is restored from
|
|
643
|
+
its comment byte for byte (or when the projection returns to the recorded value),
|
|
644
|
+
or dropped with the block when the package created it, and a token you own
|
|
645
|
+
without such a comment is never touched. Removing or moving that block is refused
|
|
646
|
+
(`ambiguous herdr-gentle-shell marker above the managed block`) when a
|
|
647
|
+
marker-shaped comment directly above `begin` would end up attached to the key
|
|
648
|
+
under it. Everything else — other tables,
|
|
649
|
+
comments, ordering, a BOM, CRLF or mixed endings, a missing final newline — is
|
|
650
|
+
preserved, a one-time `<config>.herdr-gentle-shell.bak` is published atomically
|
|
651
|
+
before the first modification and never overwritten, and a temp file that
|
|
652
|
+
survives a failed replace is named in the error instead of being hidden, while a
|
|
653
|
+
temp path the writer did not create itself is never deleted (the apply reports
|
|
654
|
+
the `EEXIST` and leaves it alone). What
|
|
655
|
+
fails closed, with the line number and no write, is what a theme-table edit
|
|
656
|
+
cannot be done safely over: `auto_switch` with a value other than `false`,
|
|
657
|
+
`dark_name`, `light_name`, a top-level `theme` key, a dotted key extending the
|
|
658
|
+
theme tables, a duplicated `[theme]`/`[theme.custom]` table or duplicated key
|
|
659
|
+
inside them, a line inside the marked block that is not a token assignment, and a
|
|
660
|
+
value the plan must touch that is not a strict single-line string/boolean/number
|
|
661
|
+
(an unterminated multi-line string or array anywhere also blocks the plan,
|
|
662
|
+
because table boundaries depend on it). While the sync is on (or a theme is
|
|
663
|
+
pinned) the package owns the tokens it projects, so another tool that rewrites
|
|
664
|
+
the same keys (a desktop-theme sync, for example) overwrites them on its next run
|
|
665
|
+
and the next palette change here overwrites them back. There is no "full clear":
|
|
666
|
+
a projection always carries a theme name, so a `name` line the planner inserted
|
|
667
|
+
stays, and only the `[theme.custom]` table it created is removed again. See
|
|
668
|
+
[docs/theme-sync.md](docs/theme-sync.md) for the golden example, the exact
|
|
669
|
+
comment and block lines, what is and is not guaranteed, the refusals, the
|
|
670
|
+
notices and the limits.
|
|
671
|
+
|
|
591
672
|
## Documentation
|
|
592
673
|
|
|
593
674
|
| Your task | Start here |
|
|
@@ -598,6 +679,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
598
679
|
| Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
|
|
599
680
|
| Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
|
|
600
681
|
| Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
|
|
682
|
+
| Theme sync (Pi palette → Herdr theme, written in process) | [docs/theme-sync.md](docs/theme-sync.md) |
|
|
601
683
|
| Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
|
|
602
684
|
| Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
|
|
603
685
|
|