herdr-gentle-shell 1.8.0 → 1.9.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 +384 -101
- package/README.md +128 -30
- package/docs/theme-sync.md +676 -182
- package/extensions/gentle-herdr-state.ts +413 -55
- package/extensions/herdr-theme-sync.ts +188 -159
- package/lib/customize-panel.js +602 -308
- package/lib/customize-rows.js +366 -0
- 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
|
@@ -1008,35 +1008,76 @@ nothing:
|
|
|
1008
1008
|
settings entry actually changed, because that entry is the only part that
|
|
1009
1009
|
waits for the next Pi extension load.
|
|
1010
1010
|
|
|
1011
|
+
The command always exists and the page is additive.
|
|
1012
|
+
`/herdr-gentle:customize` is registered in the extension factory, unconditionally
|
|
1013
|
+
and before the pane gate, exactly as it always was; when gentle-shell-bridge
|
|
1014
|
+
answers its handshake — the `gentle-shell-bridge/api/v1` object published on
|
|
1015
|
+
`globalThis`, gated exactly like the bridge's own `isBridgeApi` — the extension
|
|
1016
|
+
ALSO registers one row provider (`registerRows`, a row `category`, never
|
|
1017
|
+
`registerSection`) on the `Herdr` page of Gentle Shell's own `/gentle:customize`
|
|
1018
|
+
menu, holding exactly the four options S1 names: `Herd agents`, `Moshi`,
|
|
1019
|
+
`Theme sync`, `Select theme`. Two surfaces coexisting is by design: Pi gives an
|
|
1020
|
+
extension no way to withdraw a registered command, and a bridge with no host
|
|
1021
|
+
menu must never leave the user with none. The page is asked for at
|
|
1022
|
+
`session_start` and again on the bridge's `gentle-shell-bridge:ready` announce,
|
|
1023
|
+
so a bridge that publishes after this extension or after the session start still
|
|
1024
|
+
produces it; the live provider is its own guard, so a second `session_start` or a
|
|
1025
|
+
repeated announce never stacks a second page, and only the provider is disposed
|
|
1026
|
+
at `session_shutdown` while the command stays as registered.
|
|
1027
|
+
|
|
1028
|
+
Each row is that switch and nothing else: its action calls the same
|
|
1029
|
+
`applyCustomizePanel` the panel calls, so the writes, the `moshi-hook`
|
|
1030
|
+
prerequisite gate and the "a refusal writes nothing" promise are identical by
|
|
1031
|
+
construction, and the model is re-read on every menu build so `current()` is the
|
|
1032
|
+
stored value rather than a copy taken at registration. The page's four lines are
|
|
1033
|
+
the same four switches under their row names — `Herd agents` for
|
|
1034
|
+
`Sidebar agent rows`, `Moshi` for `Moshi notifications`, `Theme sync` and
|
|
1035
|
+
`Select theme` for the two `Herdr Theme` settings — one row per value, applied
|
|
1036
|
+
with `Enter` (the bridge stages `applyOnMove: false` on every row it
|
|
1037
|
+
contributes), with the theme rows hidden while the sync is on instead of
|
|
1038
|
+
refused in place. One accepted limitation: a row action receives only the
|
|
1039
|
+
inline helpers (`input`, `confirm`, `capture`), so it has no reload handle —
|
|
1040
|
+
the Moshi toggle still writes the settings exclusion and then asks for a
|
|
1041
|
+
restart (`Restart Pi so the new Moshi hook exclusion takes effect.`) where the
|
|
1042
|
+
command and the panel reload immediately (`Reloading now to apply the change.`).
|
|
1043
|
+
Every string that sends the user back to these switches names
|
|
1044
|
+
`/herdr-gentle:customize`, byte-identical to the pre-page build: the command
|
|
1045
|
+
always exists, so no message needs a surface-dependent wording — the Moshi gate
|
|
1046
|
+
refusals end `… re-apply On from /herdr-gentle:customize.` and the follower's
|
|
1047
|
+
missing-theme notice says `… pick an installed theme in
|
|
1048
|
+
/herdr-gentle:customize.`
|
|
1049
|
+
|
|
1011
1050
|
`/herdr-gentle:customize status` prints one read-only line; an unknown
|
|
1012
1051
|
argument, Esc, or a cancelled menu writes nothing. With no argument the
|
|
1013
1052
|
command opens the floating panel (`lib/customize-panel.js`, painted through its
|
|
1014
1053
|
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
|
|
1054
|
+
`CATEGORIES` list, one right pane headed `<Category> · n/m`, and one line per
|
|
1055
|
+
setting with its options inline — `●` the stored option, `›` the cursor while it
|
|
1056
|
+
sits elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
|
|
1057
|
+
applies; `Enter` keeps the card open (only a Moshi settings change that needs a
|
|
1058
|
+
Pi reload closes it), `Esc` closes without a write, `Tab`
|
|
1059
|
+
switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose options
|
|
1060
|
+
do not fit scrolls sideways behind muted `‹`/`›` markers with an `n/m` counter,
|
|
1061
|
+
falling back to a compact `‹ value ›`; the Preview block below the panes reads
|
|
1062
|
+
`Preview · <option> · <title>` plus a sample, and a theme option is painted in
|
|
1063
|
+
that theme's own palette; the footer carries one of three legends (categories,
|
|
1064
|
+
option row, panes) after the `Click · ` prefix, chosen by what the keys do right
|
|
1065
|
+
now and compacted instead of wrapped on a narrow card, with no `p profiles` key
|
|
1066
|
+
because this plugin owns no profiles concept. A click on an option applies
|
|
1067
|
+
exactly that option, a click on a setting's name only moves the focus, a click
|
|
1068
|
+
on a category selects it, and a click outside the panes is ignored (a press only
|
|
1069
|
+
captures the gesture, so a drag never applies anything).
|
|
1070
|
+
Each category owns its own settings: `Herdr Sidebar` shows the single
|
|
1071
|
+
`Sidebar agent rows` setting, the only Moshi switch is the `Notifications`
|
|
1072
|
+
setting under `Moshi notifications`, which applies the `gentle-moshi.json` flag
|
|
1073
|
+
through `applyMoshiNotifications`, and `Herdr Theme` owns the `Theme sync`
|
|
1074
|
+
toggle plus the inline `Gentle Shell theme` list (§12). The two channels are
|
|
1075
|
+
never mixed: the sidebar-rows
|
|
1035
1076
|
switch neither reads nor writes that flag, so disabling the agent rows leaves
|
|
1036
1077
|
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
|
|
1078
|
+
An inconclusive sidebar verdict (`unknown`) renders with no option marked `●`
|
|
1079
|
+
and a note instead of hiding the setting: toggling still attempts the repair and
|
|
1080
|
+
reports the apply step's own error, exactly like the menu. The plain
|
|
1040
1081
|
two-step `ctx.ui.select` menu remains the
|
|
1041
1082
|
fallback when the TUI helpers or `ctx.ui.custom` are unavailable. The removed
|
|
1042
1083
|
`Plugin tools` and `Reset` sections and the in-process provider slot
|
|
@@ -1160,10 +1201,12 @@ exactly one mechanism writes each piece of state.
|
|
|
1160
1201
|
`worktree_close` / `worktree_session_open` / `worktree_warp`), the warp
|
|
1161
1202
|
panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
|
|
1162
1203
|
ship. This package publishes the Herdr producer sidecar and the Moshi channel
|
|
1163
|
-
only; `bin/gentle-sidebar.js` is its one CLI and
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1204
|
+
only; `bin/gentle-sidebar.js` is its one CLI and the customize switches are
|
|
1205
|
+
reached two ways, additively: `/herdr-gentle:customize`, always, and — when
|
|
1206
|
+
gentle-shell-bridge answers its handshake — the `Herdr` page of Gentle Shell's
|
|
1207
|
+
own `/gentle:customize` menu as well (§7). The former
|
|
1208
|
+
in-process provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
|
|
1209
|
+
stays removed.
|
|
1167
1210
|
- Rollback: disable this plugin → producer stops writing; consumer sweeps
|
|
1168
1211
|
only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
|
|
1169
1212
|
`↳N` behavior with zero data migration.
|
|
@@ -1255,91 +1298,331 @@ list, not silent.
|
|
|
1255
1298
|
## 12. Theme sync (Pi palette → Herdr theme)
|
|
1256
1299
|
|
|
1257
1300
|
Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
|
|
1258
|
-
pinned while the sync is off (S1–
|
|
1259
|
-
`/herdr-gentle:customize
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
|
1266
|
-
|
|
|
1267
|
-
| `
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
`
|
|
1271
|
-
|
|
1272
|
-
`lib/customize-panel.js`
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1301
|
+
pinned while the sync is off (S1–S7). The switch lives with the other two on
|
|
1302
|
+
`/herdr-gentle:customize` and, beside it, on the `Herdr` page of Gentle Shell's
|
|
1303
|
+
own customize menu whenever the bridge answers the handshake (§7), where it is
|
|
1304
|
+
the `Theme sync` and `Select theme` rows; the user-facing reference is
|
|
1305
|
+
[docs/theme-sync.md](docs/theme-sync.md). Six modules with one owner — this Pi
|
|
1306
|
+
package — and one direction of data:
|
|
1307
|
+
|
|
1308
|
+
| Module | Owns |
|
|
1309
|
+
| --- | --- |
|
|
1310
|
+
| `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. |
|
|
1311
|
+
| `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. |
|
|
1312
|
+
| `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. |
|
|
1313
|
+
| `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. |
|
|
1314
|
+
| `extensions/herdr-theme-sync.ts` | The follower: session-start evaluation, 500 ms tick, the two identities, one in-process apply per change, the notices. |
|
|
1315
|
+
| `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. |
|
|
1316
|
+
|
|
1317
|
+
**In process, and why that is the fix.** The 1.8.0 follower spawned
|
|
1318
|
+
`bin/configure-theme.js` from the *separately installed* Herdr plugin, found
|
|
1319
|
+
through `herdr plugin list`, and that writer refused any `[theme]` table outside
|
|
1320
|
+
its own marker block. A Pi-only update therefore kept running the old plugin's
|
|
1321
|
+
writer — or, on an install that never shipped it, ran no writer at all — while
|
|
1322
|
+
the user's real config, which already owns `[theme]`, was never touched. The
|
|
1323
|
+
reference implementation
|
|
1324
|
+
([gentle-herdr](https://github.com/MarsSall/gentle-herdr), MIT License,
|
|
1325
|
+
Copyright (c) MarsSall) applies from Pi itself, so this package does the same:
|
|
1326
|
+
`applyHerdrTheme` edits the config inside the running Pi process, and the
|
|
1327
|
+
plugin-side `configure-theme.js`, its planner and the
|
|
1328
|
+
`# BEGIN herdr-gentle-theme` managed block are gone. The plugin is not involved
|
|
1329
|
+
in theme sync and needs no update for it. A config written by 1.8.0 keeps
|
|
1330
|
+
working: the planner drops those two marker lines only when they are the nearest
|
|
1331
|
+
pair and the pair actually encloses a `[theme]`/`[theme.custom]` table (a stale
|
|
1332
|
+
pair around unrelated keys is the user's text and stays, and a pair closing on an
|
|
1333
|
+
unterminated last line migrates without changing the file's final-newline state),
|
|
1334
|
+
then edits the table between them like any other. Pi colours become hex
|
|
1335
|
+
strings in the follower through `colorToHex` from `@earendil-works/pi-tui`,
|
|
1336
|
+
which is why the follower is its own extension rather than a section of the
|
|
1337
|
+
state sidecar: the sidecar is loaded by every suite as a renamed copy with one
|
|
1338
|
+
stubbed host import, and the projection needs no host at all.
|
|
1339
|
+
|
|
1340
|
+
**Ownership rule, and the two classes it implies.** Sync is a switch the user
|
|
1341
|
+
turns on deliberately, so with the sync on — or a theme pinned — this package
|
|
1342
|
+
OWNS the `name` line and every token it projects, and it must be able to give
|
|
1343
|
+
them back. Two classes, which is what makes switching Pi themes safe:
|
|
1344
|
+
|
|
1345
|
+
- **a value the user already had** is replaced in place and remembered by one
|
|
1346
|
+
comment recording **the whole original line** (minus its indentation, so
|
|
1347
|
+
trailing spaces and an inline comment are part of the record) above it: the
|
|
1348
|
+
first original wins, a later palette change reuses it, and a projection that
|
|
1349
|
+
stops carrying that token — or comes back to the recorded value — **restores
|
|
1350
|
+
the line byte for byte** and drops the comment. The one exception is the
|
|
1351
|
+
**latest edit wins**: if the user changed the line's trailing comment after the
|
|
1352
|
+
planner wrote its value, the restore keeps the recorded key/value and the
|
|
1353
|
+
user's *current* comment. A comment is only a marker when
|
|
1354
|
+
its payload parses as the strict `key = <string> [comment]` line for the key
|
|
1355
|
+
under it, and two markers for one key are refused;
|
|
1356
|
+
- **a token the user did not have** is written inside ONE marked block
|
|
1357
|
+
(`# herdr-gentle-shell: begin` … `# herdr-gentle-shell: end`, or
|
|
1358
|
+
`# herdr-gentle-shell: begin created` when the planner also creates the table,
|
|
1359
|
+
and closed with `# herdr-gentle-shell: end after a missing line ending` when
|
|
1360
|
+
placing the block also added the file's missing final line ending, so a later
|
|
1361
|
+
clear takes back only what the planner added)
|
|
1362
|
+
at the end of `[theme.custom]`, regenerated on every plan, and removed entirely
|
|
1363
|
+
when nothing is left to own — so leaving a projection never leaves a stale
|
|
1364
|
+
colour behind. A table the planner created is removed again once its block
|
|
1365
|
+
empties and nothing else lives in it, which is what makes a cycle of
|
|
1366
|
+
projections ending in an empty custom projection return the original
|
|
1367
|
+
`[theme.custom]` byte for byte; only `<token> = "#rrggbb"` lines may sit
|
|
1368
|
+
inside the block, and anything else there is refused rather than deleted.
|
|
1369
|
+
Removing or moving a block is refused
|
|
1370
|
+
(`line <n>: ambiguous herdr-gentle-shell marker above the managed block`) when a
|
|
1371
|
+
marker-shaped comment directly above `begin` would become adjacent to the token
|
|
1372
|
+
key under the block, because the next plan would promote the user's ordinary
|
|
1373
|
+
comment to ownership.
|
|
1374
|
+
|
|
1375
|
+
A token the user owns with no marker (`panel_bg`, `blue`, `yellow`, …) is never
|
|
1376
|
+
written, merged or repaired, even when the projection stops carrying it: it was
|
|
1377
|
+
never ours. A `[theme.custom]` header the **user** wrote stays even when it ends
|
|
1378
|
+
up empty, because the planner cannot prove it created that line. Two
|
|
1379
|
+
consequences are stated rather than papered over: a tool that rewrites the same
|
|
1380
|
+
keys (a desktop-theme sync such as DMS/Niri, for example) overwrites the
|
|
1381
|
+
projected values on its next run, and the next palette change here overwrites
|
|
1382
|
+
them back; and the revert is per token, not per file — a user-written empty header
|
|
1383
|
+
and the `name` marker stay. This is also where
|
|
1384
|
+
the port deliberately differs from the reference: it accepts
|
|
1385
|
+
`auto_switch = false` untouched — the reference refuses that line outright,
|
|
1386
|
+
which is exactly why the user's real config was never written — and it edits
|
|
1387
|
+
tables the reference treats as foreign.
|
|
1278
1388
|
|
|
1279
1389
|
**The state file is the only persisted truth.** `gentle-theme.json` holds
|
|
1280
1390
|
`{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`,
|
|
1391
|
+
panel and the follower read the same document, so the setting, the switch and
|
|
1392
|
+
the applied palette can never disagree. Missing is inert (`sync:false`,
|
|
1283
1393
|
`theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
|
|
1284
|
-
|
|
1394
|
+
no option marked, a `state unknown` note, follower silent — never a guess, and
|
|
1395
|
+
it is written over only
|
|
1285
1396
|
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
|
-
|
|
1397
|
+
nothing at all (S7), and a stored pin is carried across a sync toggle so turning
|
|
1398
|
+
the sync off restores that choice instead of unassigning it.
|
|
1399
|
+
|
|
1400
|
+
**Tick, fingerprint and the follower repairs.** The host publishes no
|
|
1401
|
+
theme-change event, so the palette is a pull-read of `ctx.ui.theme` (or
|
|
1402
|
+
`ctx.ui.getTheme(name)` for a pin): one immediate evaluation on `session_start`
|
|
1403
|
+
and then one every 500 ms, on an unreferenced timer so an idle follower never
|
|
1404
|
+
keeps Pi alive, cleared on `session_shutdown` (a shutdown that lands during the
|
|
1405
|
+
first evaluation wins: no tick is armed afterwards). Each evaluation computes two
|
|
1406
|
+
identities — the requested `[sync, chosen]` and the palette fingerprint
|
|
1407
|
+
(`[theme name, sorted token/hex pairs]`) — and acts only when one differs from
|
|
1408
|
+
the last one it recorded, so a theme recoloured in place (same name, new
|
|
1409
|
+
colours) is noticed without a restart, and the same palette is never applied
|
|
1410
|
+
twice. The observation is recorded **before** the apply, so a failed or refused
|
|
1411
|
+
write is never retried on the next tick and never blocks the next real change
|
|
1412
|
+
either; one apply is in flight at a time. With the sync off and no theme pinned
|
|
1413
|
+
the follower asks for nothing at all (no write, no removal) **and forgets what it
|
|
1414
|
+
applied**, which is what makes re-enabling the sync always re-apply: without that
|
|
1415
|
+
reset the next `On` would look unchanged and a config the user repaired in
|
|
1416
|
+
between would never be written (an already-matching config then answers
|
|
1417
|
+
`unchanged`). A projection with no concrete token is refused before the writer is
|
|
1418
|
+
called — `Herdr theme not applied: <name> has no concrete colours to project.`,
|
|
1419
|
+
once per session — because it would otherwise rewrite the theme name and paint
|
|
1420
|
+
nothing. Availability is decided once, by `applyHerdrTheme`, so the follower can
|
|
1421
|
+
never disagree with the writer about who may write; a subagent child
|
|
1422
|
+
(`GENTLE_PI_AGENTS_CHILD=1`) never registers the follower at all, and every
|
|
1423
|
+
user-visible outcome is one of the fixed notices in
|
|
1424
|
+
[docs/theme-sync.md](docs/theme-sync.md). A `partial/reload` sets an **owed
|
|
1425
|
+
reload**: the next apply attempt of the same session is sent with
|
|
1426
|
+
`forceReload`, and a success pays the debt off. It is session memory on purpose
|
|
1427
|
+
(a tick never reloads while the debt stands), which is why the notice ends with
|
|
1428
|
+
`Run 'herdr server reload-config' to apply it.`
|
|
1429
|
+
|
|
1430
|
+
**A splicer, and a strict core.** The writer edits the user's own `[theme]` and
|
|
1431
|
+
`[theme.custom]` tables and preserves every byte it does not own: other tables
|
|
1432
|
+
and keys, comments, blank lines, ordering, indentation, spacing around `=`, a
|
|
1433
|
+
trailing comment on a rewritten line, CRLF or mixed endings, a leading UTF-8 BOM
|
|
1434
|
+
and a missing final newline. **Outside those two tables nothing is validated**:
|
|
1435
|
+
the planner only tracks the three contexts that can hide a line
|
|
1436
|
+
break (multi-line strings, multi-line arrays, inline tables) plus comments, so it
|
|
1437
|
+
can find table boundaries — a header-shaped line must parse and a multi-line
|
|
1438
|
+
construct must be terminated, or the plan refuses — and it treats the rest of the
|
|
1439
|
+
document as opaque bytes: an input that is already invalid TOML there is the
|
|
1440
|
+
user's pre-existing breakage (Herdr refuses to load it) and is left exactly as it
|
|
1441
|
+
is. Escapes there are never validated (a backslash only consumes the next
|
|
1442
|
+
character, in single-line and multi-line strings alike) and a run of three or
|
|
1443
|
+
more quotes closes a multi-line string; the scan validates escapes only where it
|
|
1444
|
+
must read a value back (a quoted key and a strict theme-table line).
|
|
1445
|
+
**Inside the two tables it is strict**: comments, blank lines and
|
|
1446
|
+
`key = value [comment]` with a single-line string, boolean, integer or float; a
|
|
1447
|
+
key the plan must touch in any other form is refused with its line number, while
|
|
1448
|
+
a key it does not touch is kept byte for byte whenever the scanner can find where
|
|
1449
|
+
that line ends. It refuses: `auto_switch` with a value other than `false`,
|
|
1450
|
+
`dark_name`/`light_name`, a top-level `theme` key, a dotted key extending
|
|
1451
|
+
`[theme]` or a Herdr token in `[theme.custom]`, a second `[theme]`/`[theme.custom]`
|
|
1452
|
+
table, a third `[theme.*]` table, `[[theme]]` array-of-tables, `name`/
|
|
1453
|
+
`auto_switch` repeated in `[theme]`, a token repeated in `[theme.custom]` or in
|
|
1454
|
+
both the block and the user's keys, two markers for one key, a touched value that
|
|
1455
|
+
is not a strict single-line string (or a multi-line form, refused as "cannot
|
|
1456
|
+
record the original value … safely"), a control character, a bare carriage
|
|
1457
|
+
return, a malformed block (outside `[theme.custom]`, unterminated, a second
|
|
1458
|
+
begin, an end without a begin, any line in it that is not
|
|
1459
|
+
`<token> = "#rrggbb"`), the ambiguous marker above a block that is about to be
|
|
1460
|
+
removed or moved (`ambiguous herdr-gentle-shell marker above the managed
|
|
1461
|
+
block`), and a table header or unterminated multi-line string/array/inline table
|
|
1462
|
+
the boundary scan cannot resolve. A malformed
|
|
1463
|
+
projection is refused the same way without a line number, because that one is a
|
|
1464
|
+
package bug. **The splice invariant is enforced in code**: before `ok: true` the
|
|
1465
|
+
planner re-derives the non-theme lines of its own output and compares them with
|
|
1466
|
+
the input's (only the 1.8.0 marker lines it wrote may be missing, and only the
|
|
1467
|
+
single terminator needed to append a table after an unterminated last line may be
|
|
1468
|
+
added); a mismatch returns `internal splice invariant violated; no changes
|
|
1469
|
+
proposed.` rather than a document that moved a byte it promised not to touch. The
|
|
1470
|
+
file-level refusals belong to the snapshot and the write: a non-absolute or
|
|
1471
|
+
non-canonical path, a symlinked parent directory, not a regular single-link
|
|
1472
|
+
file, over 256 KiB, invalid UTF-8, a backup path that is not a regular file, a
|
|
1473
|
+
planned document past the 256 KiB limit, bytes that changed between the snapshot
|
|
1474
|
+
and the replacement (`Herdr config changed before replacement`), a backup temp
|
|
1475
|
+
that cannot be removed, a missing config (never bootstrapped), and a failed
|
|
1476
|
+
rename. Every refusal writes nothing, backs up nothing and reloads nothing.
|
|
1477
|
+
|
|
1478
|
+
**Safe write, and exactly one reload.** The snapshot is one bounded strictly
|
|
1479
|
+
decoded read with stat identity checks; a leading BOM is decoded as part of the
|
|
1480
|
+
text (`ignoreBOM`) so a changed write keeps it and the backup and the file agree
|
|
1481
|
+
on those bytes. The plan is refused **before anything is written** if the
|
|
1482
|
+
document would grow past the same 256 KiB limit. The original bytes are re-read
|
|
1483
|
+
and compared immediately before the backup and again immediately before the
|
|
1484
|
+
swap, so a projection computed from stale bytes is never renamed into place. The new text
|
|
1485
|
+
is staged at a path chosen **before the file exists**, so every failure — open,
|
|
1486
|
+
write, `fsync`, `fchmod` — leaves the writer able to remove it: exclusive `0600`,
|
|
1487
|
+
`fchmod`-ed to the original mode (`0o7777`, so setuid/setgid/sticky survive),
|
|
1488
|
+
compared once more, then `rename`d. Temp cleanup is best-effort **and never
|
|
1489
|
+
silent**: the unlink is retried once and then force-removed, and a survivor is
|
|
1490
|
+
reported instead of hiding — if the **backup's** temp survives, the apply fails
|
|
1491
|
+
with `Herdr backup temporary could not be removed: <path>` (so it can never
|
|
1492
|
+
answer `requested` with a stray file), and a surviving **staged** temp appends
|
|
1493
|
+
`; temporary file left behind: <path>` to the `partial`/`config` error. Cleanup
|
|
1494
|
+
only ever removes a path the call created itself: a foreign file at that exact
|
|
1495
|
+
temp name makes the exclusive open fail with `EEXIST`, the apply answers
|
|
1496
|
+
`partial`/`config` with that text, and the file is left alone (config and backup
|
|
1497
|
+
untouched). The
|
|
1498
|
+
backup itself is **published atomically and never overwritten**: written to a
|
|
1499
|
+
temp name and hard-linked into place, so a crash or a full disk leaves no
|
|
1500
|
+
truncated `.bak` that a later run would mistake for "already backed up". A
|
|
1501
|
+
regular file already at the backup path — pre-existing or raced — **is** the
|
|
1502
|
+
existing backup: accepted as it is, never compared and never overwritten (it may
|
|
1503
|
+
be an older original from before the user's last edit), while a non-regular
|
|
1504
|
+
entry (directory, symlink, socket) is refused. `unchanged` writes
|
|
1505
|
+
nothing and reloads nothing — Herdr already holds that palette, and a reload on
|
|
1506
|
+
every tick would make the sidebar flicker for nothing. `forceReload` is the one
|
|
1507
|
+
exception, and it exists for the owed-reload repair above: it reloads an
|
|
1508
|
+
unchanged plan and answers `requested`. A real write is followed by exactly one
|
|
1509
|
+
`herdr server reload-config` through `execFile` with `HERDR_BIN_PATH` (default
|
|
1510
|
+
`herdr`), no shell, a 5 s timeout and a 4096-byte output cap; a reload failure is
|
|
1511
|
+
reported as partial state because the config is already committed. **CAS limit:**
|
|
1512
|
+
an edit that lands between the final compare and the `rename` cannot be detected
|
|
1513
|
+
without holding a lock on the config, which this writer deliberately does not
|
|
1514
|
+
do — everything earlier (snapshot, plan, backup, staging) is still caught. A
|
|
1515
|
+
**pre-existing truncated backup** is a second documented limit: because a regular
|
|
1516
|
+
file at that path is accepted as it is and never repaired or compared, a `.bak`
|
|
1517
|
+
damaged by an earlier failure or another tool stays damaged.
|
|
1518
|
+
|
|
1519
|
+
**The guard matrix.** `applyHerdrTheme` answers `unavailable` with one reason
|
|
1520
|
+
before it opens any file: `not-herdr` (no `HERDR_ENV=1` plus a pane id and an
|
|
1521
|
+
absolute socket path), `child` (a subagent's Pi must never write the user's
|
|
1522
|
+
config), `remote` (an SSH session, where Herdr reads another machine's config),
|
|
1523
|
+
and `unsupported` (a `herdr-dev` binary, a non-Linux host, or a non-absolute
|
|
1524
|
+
socket/config path). The follower reports `not-herdr`, `remote` and
|
|
1525
|
+
`unsupported` as one `info` notice per session and asks again only when the
|
|
1526
|
+
palette itself changes.
|
|
1527
|
+
|
|
1528
|
+
**The panel.** `/herdr-gentle:customize` — the surface that always exists (§7) —
|
|
1529
|
+
reuses Gentle Shell's own card shape:
|
|
1530
|
+
one left `CATEGORIES` list, one right pane headed `<Category> · n/m`, one line
|
|
1531
|
+
per setting with its options inline (`●` stored, `›` cursor elsewhere, `○` the
|
|
1532
|
+
rest). The arrows move the option cursor and only Enter applies; Enter keeps the
|
|
1533
|
+
card open (only the Moshi reload closes it), Esc closes without a write, Tab
|
|
1534
|
+
switches panes. A line whose options do not fit scrolls sideways behind muted
|
|
1535
|
+
`‹`/`›` with an `n/m` counter, falling back to a compact `‹ value ›`. The
|
|
1536
|
+
Preview block below the panes is `Preview · <option> · <title>` plus a sample
|
|
1537
|
+
painted with the host theme, where a theme option shows that theme's own palette
|
|
1538
|
+
through the raw SGR the host hands back. Three footer legends (categories,
|
|
1539
|
+
option row, panes) are chosen by what the keys do right now and compact instead
|
|
1540
|
+
of wrapping. The theme list comes from `ctx.ui.getAllThemes()` in the host's own
|
|
1541
|
+
order with `None` first, the `Gentle Shell theme` setting is painted dim and
|
|
1542
|
+
refused with `Turn Theme sync off to pick a specific theme.` while the sync is
|
|
1543
|
+
on, and a host that exposes no list shows one note instead of an empty picker.
|
|
1544
|
+
The panel writes nothing itself: it calls the extension's apply path, swaps in
|
|
1545
|
+
the model that path re-read, and keeps the cursor by structural option ids.
|
|
1546
|
+
|
|
1547
|
+
**The page.** The `Herdr` page of Gentle Shell's own customize menu (§7) is not
|
|
1548
|
+
this card: Gentle Shell paints its own rows and enters their actions. The
|
|
1549
|
+
switch side is the same — two rows, `Theme sync` and `Select theme`, built from
|
|
1550
|
+
the same model by `lib/customize-rows.js`, applied through the same
|
|
1551
|
+
`applyCustomizePanel` — so the notices above are the same strings, a theme row
|
|
1552
|
+
keeps its swatch, and the theme rows are hidden while the sync is on rather
|
|
1553
|
+
than refused in place. The sync never needs a Pi reload on either surface; the
|
|
1554
|
+
one surface-specific difference in this feature is Moshi's, which asks for a
|
|
1555
|
+
restart on the page because a row action has no reload handle (§7).
|
|
1556
|
+
|
|
1557
|
+
The page's row set is FIXED for the life of the menu, and the cache in
|
|
1558
|
+
`lib/customize-rows.js` is what makes that affordable: one model read per paint
|
|
1559
|
+
burst (one synchronous `configure.js --check`, not one per callback), dropped
|
|
1560
|
+
after an `apply` settles and after a one-second TTL. Two properties follow and
|
|
1561
|
+
are accepted rather than promised away. First, an external write while the menu
|
|
1562
|
+
is idle becomes visible on the first read after the cache expires, or on a
|
|
1563
|
+
rebuild: the cache never asks the host to repaint, so a repaint that lands
|
|
1564
|
+
before expiry redraws the previous model and the displayed state has no upper
|
|
1565
|
+
freshness bound. Second, when an external write hides the row the user had
|
|
1566
|
+
focused (the theme
|
|
1567
|
+
picker, with the sync turned on elsewhere), the host clamps the focus to the
|
|
1568
|
+
neighbouring row, so Enter can act on that one; the clamp itself writes nothing.
|
|
1569
|
+
The fixed row set is also why a theme applied from a row is checked against a
|
|
1570
|
+
fresh `ctx.ui.getAllThemes()` read at apply time: a theme removed after the
|
|
1571
|
+
build refuses and writes nothing instead of pinning a name this install no
|
|
1572
|
+
longer has. That check lives on the page's own apply path, so the command's
|
|
1573
|
+
picker and the mounted panel keep the `865d360` write (S2).
|
|
1326
1574
|
|
|
1327
1575
|
**Limits** (the §10 style, none of them a promise this design makes):
|
|
1328
1576
|
|
|
1329
1577
|
- The 500 ms tick is the whole observation granularity — there is no event to
|
|
1330
1578
|
subscribe to, so a theme change is noticed within one tick and not sooner.
|
|
1331
|
-
- The
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1579
|
+
- The page's displayed state has **no upper freshness bound**: its row cache
|
|
1580
|
+
never requests a repaint, so a write from another process while the menu is
|
|
1581
|
+
idle appears on the first read after the cache expires, or on a rebuild, not
|
|
1582
|
+
when it lands; a repaint that lands before expiry redraws the previous model,
|
|
1583
|
+
and on a menu nobody touches the write is not shown at all.
|
|
1584
|
+
- The page cannot keep the cursor on a row an external write hid: the host clamps
|
|
1585
|
+
the focus to the neighbouring row, so the next Enter can act on that neighbour.
|
|
1586
|
+
The clamp writes nothing; it only moves the cursor.
|
|
1587
|
+
- The automated evidence is a stubbed Pi host plus a real binary stand-in on
|
|
1588
|
+
disk; **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
|
|
1589
|
+
`getAllThemes`, `notify` and the host component contract are used as
|
|
1590
|
+
documented, and a host missing one degrades to "nothing changed" rather than
|
|
1591
|
+
to a guess.
|
|
1592
|
+
- Remote sessions are inactive: in SSH the Herdr client reads the config of the
|
|
1593
|
+
machine it runs on, so writing the server-side file would change nothing on
|
|
1594
|
+
screen and the guard refuses.
|
|
1595
|
+
- Two writers of the same keys fight. The sync owns what it projects, so a
|
|
1596
|
+
desktop-theme sync and this feature overwrite each other on their next run;
|
|
1597
|
+
there is no merge, lock or arbitration, only the `was` comments, the marked
|
|
1598
|
+
block and the one-time backup.
|
|
1599
|
+
- The compare-and-swap has one unavoidable window: an edit between the final
|
|
1600
|
+
compare and the rename is undetectable without a config lock, which this
|
|
1601
|
+
writer does not take.
|
|
1602
|
+
- The planner is a **splicer, not a validator**: it guarantees table boundaries
|
|
1603
|
+
for terminated multi-line constructs and byte-identical non-theme lines (checked
|
|
1604
|
+
by the splice invariant), and it deliberately checks nothing outside the theme
|
|
1605
|
+
tables — invalid TOML there is left as it is, because Herdr already refuses
|
|
1606
|
+
that file. A theme-table line the plan must touch has to be the strict
|
|
1607
|
+
single-line form; the revert is per token, so a user-written empty
|
|
1608
|
+
`[theme.custom]` header and the `name` marker stay behind (a table the planner
|
|
1609
|
+
created is removed, so a full cycle is byte-identical).
|
|
1610
|
+
- A pre-existing truncated backup is kept, not repaired (see above), which is why
|
|
1611
|
+
the `was` comments are the per-value revert path.
|
|
1612
|
+
- There is no "full clear" distinct from an empty custom projection: a projection
|
|
1613
|
+
always carries the theme name, so a `name` line the planner inserted stays (an
|
|
1614
|
+
existing name is restored) and a `[theme]` table it created is not removed —
|
|
1615
|
+
only the `[theme.custom]` table it created is, once its block empties.
|
|
1335
1616
|
- Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
|
|
1336
|
-
`selection_bg`, `surface*`) and `peach` are
|
|
1617
|
+
`selection_bg`, `surface*`) and `peach` are not projected: Pi names
|
|
1337
1618
|
foregrounds and accents, not panel backgrounds, so backgrounds and status
|
|
1338
|
-
colours stay with the Herdr base theme
|
|
1619
|
+
colours stay with the Herdr base theme — except the `DOTS_FIXED` tables for
|
|
1620
|
+
`Gentleman-Cute`, `Gentleman-Sexy` and `Gentle`, which are the surfaces the
|
|
1621
|
+
user's own Herdr profiles already use.
|
|
1339
1622
|
- One machine: another Herdr client reads its own `config.toml`, so this is a
|
|
1340
1623
|
local sync and not a fleet setting.
|
|
1341
|
-
-
|
|
1342
|
-
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
1624
|
+
- No automatic repair: a `[theme]` table the user or another tool keeps editing
|
|
1625
|
+
is re-projected on the next palette change and never reconciled, and a document
|
|
1626
|
+
whose table boundaries cannot be found (an unterminated multi-line string,
|
|
1627
|
+
array or inline table) stops the writer until it is fixed. A missing
|
|
1628
|
+
`config.toml` is refused, never created.
|