herdr-gentle-shell 1.8.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 +299 -96
- package/README.md +83 -23
- package/docs/theme-sync.md +634 -181
- package/extensions/gentle-herdr-state.ts +145 -51
- package/extensions/herdr-theme-sync.ts +184 -159
- package/lib/customize-panel.js +602 -308
- package/lib/herdr-theme-apply.js +361 -0
- package/lib/herdr-theme-config.js +1133 -0
- package/lib/theme-projection.js +48 -9
- package/package.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -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
|
|
@@ -1255,91 +1257,292 @@ list, not silent.
|
|
|
1255
1257
|
## 12. Theme sync (Pi palette → Herdr theme)
|
|
1256
1258
|
|
|
1257
1259
|
Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
|
|
1258
|
-
pinned while the sync is off (S1–
|
|
1260
|
+
pinned while the sync is off (S1–S7). The switch lives with the other two in
|
|
1259
1261
|
`/herdr-gentle:customize`; the user-facing reference is
|
|
1260
|
-
[docs/theme-sync.md](docs/theme-sync.md).
|
|
1261
|
-
one direction of data:
|
|
1262
|
-
|
|
1263
|
-
| Module |
|
|
1264
|
-
|
|
1265
|
-
| `lib/theme-store.js` |
|
|
1266
|
-
| `lib/theme-projection.js` |
|
|
1267
|
-
| `
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
`extensions/herdr-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
`
|
|
1274
|
-
`
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
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.
|
|
1278
1345
|
|
|
1279
1346
|
**The state file is the only persisted truth.** `gentle-theme.json` holds
|
|
1280
1347
|
`{sync, theme, updatedAt}` and nothing else is cached, mirrored or inferred: the
|
|
1281
|
-
panel and the follower read the same document, so the
|
|
1282
|
-
applied palette can never disagree. Missing is inert (`sync:false`,
|
|
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`,
|
|
1283
1350
|
`theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
|
|
1284
|
-
|
|
1351
|
+
no option marked, a `state unknown` note, follower silent — never a guess, and
|
|
1352
|
+
it is written over only
|
|
1285
1353
|
when the user acts. The default install (sync off, no theme) therefore writes
|
|
1286
|
-
nothing at all (S7),
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
**Tick and
|
|
1290
|
-
palette is a pull-read of `ctx.ui.theme` (or
|
|
1291
|
-
one immediate evaluation on `session_start`
|
|
1292
|
-
unreferenced timer so an idle follower never
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
name,
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
|
|
1300
|
-
and the
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
applied
|
|
1304
|
-
the
|
|
1305
|
-
|
|
1306
|
-
|
|
1307
|
-
|
|
1308
|
-
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
|
|
1312
|
-
|
|
1313
|
-
`
|
|
1314
|
-
|
|
1315
|
-
and
|
|
1316
|
-
|
|
1317
|
-
|
|
1318
|
-
|
|
1319
|
-
|
|
1320
|
-
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
|
|
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.
|
|
1326
1502
|
|
|
1327
1503
|
**Limits** (the §10 style, none of them a promise this design makes):
|
|
1328
1504
|
|
|
1329
1505
|
- The 500 ms tick is the whole observation granularity — there is no event to
|
|
1330
1506
|
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
|
|
1332
|
-
**no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
|
|
1333
|
-
`getAllThemes`, `
|
|
1334
|
-
missing one degrades to "nothing changed" rather than
|
|
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.
|
|
1335
1536
|
- Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
|
|
1336
|
-
`selection_bg`, `surface*`) and `peach` are
|
|
1537
|
+
`selection_bg`, `surface*`) and `peach` are not projected: Pi names
|
|
1337
1538
|
foregrounds and accents, not panel backgrounds, so backgrounds and status
|
|
1338
|
-
colours stay with the Herdr base theme
|
|
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.
|
|
1339
1542
|
- One machine: another Herdr client reads its own `config.toml`, so this is a
|
|
1340
1543
|
local sync and not a fleet setting.
|
|
1341
|
-
-
|
|
1342
|
-
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
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
|
@@ -489,22 +489,29 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
489
489
|
no argument the command opens the floating panel in Gentle Shell's own
|
|
490
490
|
layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
|
|
491
491
|
`Herdr Theme`)
|
|
492
|
-
and one right pane headed `<Category> · n/m
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
the
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
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`
|
|
504
511
|
shows the single `Sidebar agent rows` row, and the only Moshi switch is the
|
|
505
512
|
`Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
|
|
506
|
-
both theme
|
|
507
|
-
`Gentle Shell theme`
|
|
513
|
+
both theme settings (the `Theme sync` toggle and the inline
|
|
514
|
+
`Gentle Shell theme` list described in the subsection below). The
|
|
508
515
|
sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
|
|
509
516
|
reads nor writes `gentle-moshi.json`, so turning the agent rows off never
|
|
510
517
|
turns the notification channel off. Herdr's own
|
|
@@ -595,19 +602,72 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
595
602
|
|
|
596
603
|
### Theme sync (Herdr palette follows Pi)
|
|
597
604
|
|
|
598
|
-
`/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned
|
|
605
|
+
`/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned theme.
|
|
599
606
|
`Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
|
|
600
607
|
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`
|
|
602
|
-
|
|
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
|
|
603
611
|
(`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
|
|
604
612
|
nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
|
|
605
613
|
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
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
the
|
|
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.
|
|
611
671
|
|
|
612
672
|
## Documentation
|
|
613
673
|
|
|
@@ -619,7 +679,7 @@ the limits.
|
|
|
619
679
|
| Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
|
|
620
680
|
| Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
|
|
621
681
|
| 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) |
|
|
682
|
+
| Theme sync (Pi palette → Herdr theme, written in process) | [docs/theme-sync.md](docs/theme-sync.md) |
|
|
623
683
|
| Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
|
|
624
684
|
| Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
|
|
625
685
|
|