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
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
// The in-process Herdr theme writer (theme-sync-fix T2 over S3/S4, correction
|
|
5
|
+
// pass; risk 1 — it replaces a file the user owns).
|
|
6
|
+
//
|
|
7
|
+
// Why this exists at all: the shipped 1.8.0 writer ran from the separately
|
|
8
|
+
// installed Herdr plugin, so a Pi-only update left it behind (evidence E2), and
|
|
9
|
+
// it refused any `[theme]` table outside its own markers, which the user's real
|
|
10
|
+
// config owns (E1). Everything here happens inside the Pi package.
|
|
11
|
+
//
|
|
12
|
+
// Ported from gentle-herdr `lib/herdr-visuals-application.ts`
|
|
13
|
+
// (https://github.com/MarsSall/gentle-herdr, MIT License, Copyright (c) MarsSall):
|
|
14
|
+
// the availability guard matrix, the bounded snapshot, the compare-and-swap
|
|
15
|
+
// replacement and the reload invocation are that file's logic in plain
|
|
16
|
+
// CommonJS, so the two implementations fail in the same places.
|
|
17
|
+
//
|
|
18
|
+
// What the guards mean, in a user's terms:
|
|
19
|
+
// - `not-herdr`/`unsupported`: there is no local Linux Herdr whose config this
|
|
20
|
+
// process may edit (a `herdr-dev` binary or a non-Linux host is not the
|
|
21
|
+
// Herdr the user is looking at);
|
|
22
|
+
// - `child`: a subagent's Pi must never write the user's config, because its
|
|
23
|
+
// "active theme" is not the palette the user sees;
|
|
24
|
+
// - `remote`: in an SSH session Herdr's client reads another machine's config,
|
|
25
|
+
// so writing the server-side file would change nothing on screen.
|
|
26
|
+
//
|
|
27
|
+
// A write is bounded and staged: the path must be a regular, single-link file of
|
|
28
|
+
// at most 256 KiB in a non-symlinked directory, the bytes are decoded strictly
|
|
29
|
+
// and the BOM is preserved, the planned document is refused if it would grow
|
|
30
|
+
// past the same limit, and the new bytes are written to an exclusive 0o600 file
|
|
31
|
+
// in the same directory, chmod'ed to the original mode (all permission bits),
|
|
32
|
+
// fsynced and renamed. The original bytes are kept once in
|
|
33
|
+
// `<config>.herdr-gentle-shell.bak`, published atomically and never overwritten.
|
|
34
|
+
//
|
|
35
|
+
// LIMITS, stated rather than hidden and deliberately not coded in this pass: an
|
|
36
|
+
// edit that lands between the final compare and the rename cannot be detected
|
|
37
|
+
// without holding a lock on the config, which this writer deliberately does not
|
|
38
|
+
// do; and a projected palette is checked for shape only (#rrggbb, known token),
|
|
39
|
+
// never for Herdr's own semantics. The compare is therefore as close to the
|
|
40
|
+
// rename as it can be, and everything earlier is still detected.
|
|
41
|
+
//
|
|
42
|
+
// `unchanged` performs no write and NO reload (Herdr already holds that palette,
|
|
43
|
+
// and a reload on every theme tick would make the sidebar flicker). `forceReload`
|
|
44
|
+
// exists for the one case that needs it: repairing a config whose previous
|
|
45
|
+
// reload failed.
|
|
46
|
+
|
|
47
|
+
const childProcess = require('node:child_process');
|
|
48
|
+
const fs = require('node:fs');
|
|
49
|
+
const path = require('node:path');
|
|
50
|
+
const { randomUUID } = require('node:crypto');
|
|
51
|
+
|
|
52
|
+
const { planThemeConfig } = require('./herdr-theme-config.js');
|
|
53
|
+
|
|
54
|
+
const MAX_BYTES = 256 * 1024;
|
|
55
|
+
const RELOAD_TIMEOUT_MS = 5000;
|
|
56
|
+
const RELOAD_MAX_BUFFER = 4096;
|
|
57
|
+
const BACKUP_SUFFIX = '.herdr-gentle-shell.bak';
|
|
58
|
+
const CHANGED_BEFORE_REPLACEMENT = 'Herdr config changed before replacement';
|
|
59
|
+
|
|
60
|
+
function message(error) {
|
|
61
|
+
return error instanceof Error ? error.message : String(error);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/* ------------------------------------------------------------- resolution */
|
|
65
|
+
|
|
66
|
+
function nonEmpty(value) {
|
|
67
|
+
return typeof value === 'string' && value.length > 0;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// Herdr sets all three of these in every pane it owns. Requiring them is what
|
|
71
|
+
// keeps a plain Pi session (which happens to run on a machine with Herdr
|
|
72
|
+
// installed) from writing a config nobody is looking at.
|
|
73
|
+
function herdrDetected(env) {
|
|
74
|
+
return env.HERDR_ENV === '1' && nonEmpty(env.HERDR_PANE_ID) && nonEmpty(env.HERDR_SOCKET_PATH);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// `HERDR_CONFIG_PATH`, then XDG, then the default under `~/.config`. `null` when
|
|
78
|
+
// nothing is resolvable, which the guard reports as `unsupported`.
|
|
79
|
+
function herdrConfigPath(env = process.env) {
|
|
80
|
+
if (nonEmpty(env.HERDR_CONFIG_PATH)) return env.HERDR_CONFIG_PATH;
|
|
81
|
+
const root = nonEmpty(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : nonEmpty(env.HOME) ? path.join(env.HOME, '.config') : null;
|
|
82
|
+
return root === null ? null : path.join(root, 'herdr', 'config.toml');
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
// The single guard behind both the exported availability answer and the apply
|
|
86
|
+
// path, so the two can never disagree about who may write.
|
|
87
|
+
function herdrTarget(env, platform) {
|
|
88
|
+
if (!herdrDetected(env)) return { available: false, reason: 'not-herdr' };
|
|
89
|
+
if (env.GENTLE_PI_AGENTS_CHILD === '1') return { available: false, reason: 'child' };
|
|
90
|
+
if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY) return { available: false, reason: 'remote' };
|
|
91
|
+
const binary = nonEmpty(env.HERDR_BIN_PATH) ? env.HERDR_BIN_PATH : 'herdr';
|
|
92
|
+
// A build-tree binary belongs to whoever is developing Herdr; its config is
|
|
93
|
+
// not the installed one the user's session reads.
|
|
94
|
+
if (/^herdr-dev(?:\.exe)?$/i.test(path.basename(binary))) return { available: false, reason: 'unsupported' };
|
|
95
|
+
if (platform !== 'linux') return { available: false, reason: 'unsupported' };
|
|
96
|
+
if (!path.isAbsolute(env.HERDR_SOCKET_PATH)) return { available: false, reason: 'unsupported' };
|
|
97
|
+
const configPath = herdrConfigPath(env);
|
|
98
|
+
if (!configPath || !path.isAbsolute(configPath) || path.resolve(configPath) !== configPath) {
|
|
99
|
+
return { available: false, reason: 'unsupported' };
|
|
100
|
+
}
|
|
101
|
+
return { available: true, binary, configPath };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// Pure eligibility: not a filesystem health check and not a build attestation.
|
|
105
|
+
function herdrThemeAvailability(env = process.env, platform = process.platform) {
|
|
106
|
+
const target = herdrTarget(env, platform);
|
|
107
|
+
return target.available ? { available: true } : { available: false, reason: target.reason };
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/* --------------------------------------------------------------- snapshot */
|
|
111
|
+
|
|
112
|
+
function sameStat(before, after) {
|
|
113
|
+
return (
|
|
114
|
+
before.dev === after.dev
|
|
115
|
+
&& before.ino === after.ino
|
|
116
|
+
&& before.size === after.size
|
|
117
|
+
&& before.mtimeMs === after.mtimeMs
|
|
118
|
+
&& before.ctimeMs === after.ctimeMs
|
|
119
|
+
&& before.mode === after.mode
|
|
120
|
+
);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// A bounded, strictly decoded read. Every rejection names the invariant it
|
|
124
|
+
// protects: a symlinked, linked, directory or oversized path is not a config
|
|
125
|
+
// this process may replace, and reading through one could write somewhere else.
|
|
126
|
+
function snapshot(file) {
|
|
127
|
+
const directory = path.dirname(file);
|
|
128
|
+
if (!path.isAbsolute(file) || path.resolve(file) !== file || fs.realpathSync(directory) !== directory) {
|
|
129
|
+
throw new Error('Unsupported or symlinked Herdr config path');
|
|
130
|
+
}
|
|
131
|
+
const before = fs.lstatSync(file);
|
|
132
|
+
if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.size > MAX_BYTES) {
|
|
133
|
+
throw new Error('Herdr config must be a bounded regular single-link file');
|
|
134
|
+
}
|
|
135
|
+
const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | (fs.constants.O_NOFOLLOW ?? 0));
|
|
136
|
+
try {
|
|
137
|
+
const opened = fs.fstatSync(fd);
|
|
138
|
+
if (!sameStat(before, opened)) throw new Error('Herdr config changed during read');
|
|
139
|
+
const buffer = Buffer.alloc(MAX_BYTES + 1);
|
|
140
|
+
let size = 0;
|
|
141
|
+
let count = 0;
|
|
142
|
+
do {
|
|
143
|
+
count = fs.readSync(fd, buffer, size, buffer.length - size, size);
|
|
144
|
+
size += count;
|
|
145
|
+
} while (count > 0 && size < buffer.length);
|
|
146
|
+
if (size > MAX_BYTES || size !== opened.size || !sameStat(opened, fs.fstatSync(fd))) {
|
|
147
|
+
throw new Error('Herdr config changed or exceeded the read limit');
|
|
148
|
+
}
|
|
149
|
+
return { bytes: buffer.subarray(0, size), stat: opened };
|
|
150
|
+
} finally {
|
|
151
|
+
fs.closeSync(fd);
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function unchangedSince(file, original) {
|
|
156
|
+
const fresh = snapshot(file);
|
|
157
|
+
if (!sameStat(original.stat, fresh.stat) || !original.bytes.equals(fresh.bytes)) {
|
|
158
|
+
throw new Error(CHANGED_BEFORE_REPLACEMENT);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/* ------------------------------------------------------------------ write */
|
|
163
|
+
|
|
164
|
+
function writeAll(fd, bytes) {
|
|
165
|
+
fs.writeFileSync(fd, bytes);
|
|
166
|
+
fs.fsyncSync(fd);
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
// The backup is published atomically and never overwritten. Writing it straight
|
|
170
|
+
// at its final name is what made a failed write (ENOSPC, a killed process) leave
|
|
171
|
+
// a truncated `.bak` that every later run then treated as "already backed up",
|
|
172
|
+
// so the true original was lost. Staging + link gives atomicity AND "fail if it
|
|
173
|
+
// already exists", and a path that is not a regular file is refused rather than
|
|
174
|
+
// followed.
|
|
175
|
+
function ensureBackup(file, bytes) {
|
|
176
|
+
const backup = `${file}${BACKUP_SUFFIX}`;
|
|
177
|
+
let existing = null;
|
|
178
|
+
try {
|
|
179
|
+
existing = fs.lstatSync(backup);
|
|
180
|
+
} catch (error) {
|
|
181
|
+
if (!error || error.code !== 'ENOENT') throw error;
|
|
182
|
+
}
|
|
183
|
+
if (existing) {
|
|
184
|
+
if (!existing.isFile() || existing.isSymbolicLink()) {
|
|
185
|
+
throw new Error(`Herdr backup path is not a regular file: ${backup}`);
|
|
186
|
+
}
|
|
187
|
+
return backup;
|
|
188
|
+
}
|
|
189
|
+
const temporary = `${backup}.${randomUUID()}.tmp`;
|
|
190
|
+
let published = false;
|
|
191
|
+
// Only a path THIS call created may ever be removed. An exclusive open that
|
|
192
|
+
// fails with EEXIST means the name belongs to someone else (another writer,
|
|
193
|
+
// or a left-over file), and deleting it would destroy a file we do not own.
|
|
194
|
+
let created = false;
|
|
195
|
+
try {
|
|
196
|
+
const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
|
|
197
|
+
created = true;
|
|
198
|
+
try {
|
|
199
|
+
writeAll(fd, bytes);
|
|
200
|
+
} finally {
|
|
201
|
+
fs.closeSync(fd);
|
|
202
|
+
}
|
|
203
|
+
try {
|
|
204
|
+
fs.linkSync(temporary, backup);
|
|
205
|
+
} catch (error) {
|
|
206
|
+
if (!error || error.code !== 'EEXIST') throw error;
|
|
207
|
+
// DECISION: a regular file that already sits at the backup path — whether
|
|
208
|
+
// it was there when we checked or appeared in this race — IS the existing
|
|
209
|
+
// backup and is accepted as it is. It may legitimately be an older original
|
|
210
|
+
// from before the user edited the config, and a raced copy is
|
|
211
|
+
// indistinguishable from it, so we neither compare it nor overwrite it.
|
|
212
|
+
// (A pre-existing truncated backup is therefore a documented limit: it is
|
|
213
|
+
// kept, not repaired.) Only something that is not a real file — a
|
|
214
|
+
// directory, a symlink, a socket — is refused, because writing next to it
|
|
215
|
+
// could mean writing somewhere else.
|
|
216
|
+
const raced = fs.lstatSync(backup);
|
|
217
|
+
if (!raced.isFile() || raced.isSymbolicLink()) {
|
|
218
|
+
throw new Error(`Herdr backup path is not a regular file: ${backup}`);
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
published = true;
|
|
222
|
+
} finally {
|
|
223
|
+
// A leftover temp is a stray file in the user's config directory: remove it,
|
|
224
|
+
// and never report `requested` while one survives.
|
|
225
|
+
const leftover = created ? discard(temporary) : null;
|
|
226
|
+
if (leftover !== null && published) {
|
|
227
|
+
throw new Error(`Herdr backup temporary could not be removed: ${leftover}`);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
return backup;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
// Removing a temporary file this call created. A single transient failure must
|
|
234
|
+
// not leave a stray file beside the user's config, so retry once and then force-
|
|
235
|
+
// remove; if even that fails the caller must report the path instead of claiming
|
|
236
|
+
// success. Returns the leftover path, or null when the path is gone.
|
|
237
|
+
function discard(path) {
|
|
238
|
+
if (path === null) return null;
|
|
239
|
+
for (let attempt = 0; attempt < 2; attempt += 1) {
|
|
240
|
+
try {
|
|
241
|
+
fs.unlinkSync(path);
|
|
242
|
+
return null;
|
|
243
|
+
} catch (error) {
|
|
244
|
+
if (error && error.code === 'ENOENT') return null;
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
try {
|
|
248
|
+
fs.rmSync(path, { force: true });
|
|
249
|
+
return null;
|
|
250
|
+
} catch {
|
|
251
|
+
return path;
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
// Exclusive 0o600 staging at a path the CALLER already knows, then the original
|
|
256
|
+
// mode (all permission bits, including setuid/setgid/sticky), so the rename never
|
|
257
|
+
// widens or narrows the file's permissions even for a moment. The path is chosen
|
|
258
|
+
// before the file exists so that every failure — open, write, fsync, chmod —
|
|
259
|
+
// leaves the caller able to unlink it.
|
|
260
|
+
function writeStaged(temporary, bytes, mode, state) {
|
|
261
|
+
const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
|
|
262
|
+
// Only a file this call created may ever be removed by its caller.
|
|
263
|
+
state.created = true;
|
|
264
|
+
try {
|
|
265
|
+
writeAll(fd, bytes);
|
|
266
|
+
fs.fchmodSync(fd, mode & 0o7777);
|
|
267
|
+
} finally {
|
|
268
|
+
fs.closeSync(fd);
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
// No shell: the binary is exec'd with this exact argv, and the bounded output
|
|
273
|
+
// keeps a chatty server from buffering without limit.
|
|
274
|
+
function reload(binary, env) {
|
|
275
|
+
return new Promise((resolve, reject) => {
|
|
276
|
+
childProcess.execFile(
|
|
277
|
+
binary,
|
|
278
|
+
['server', 'reload-config'],
|
|
279
|
+
{ env, timeout: RELOAD_TIMEOUT_MS, maxBuffer: RELOAD_MAX_BUFFER },
|
|
280
|
+
(error) => (error ? reject(error) : resolve()),
|
|
281
|
+
);
|
|
282
|
+
});
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
// `ignoreBOM` keeps the leading U+FEFF in the decoded text. Without it a changed
|
|
286
|
+
// write silently drops the user's byte-order mark while the backup still has it,
|
|
287
|
+
// so the backup and the file would disagree about the first three bytes.
|
|
288
|
+
function decodeUtf8(bytes) {
|
|
289
|
+
return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/* ------------------------------------------------------------------ apply */
|
|
293
|
+
|
|
294
|
+
// One entry point. The guard is evaluated here, before any file is opened, and a
|
|
295
|
+
// refusal returns the reason instead of guessing a target.
|
|
296
|
+
async function applyHerdrTheme({ projection, env = process.env, platform = process.platform, forceReload = false } = {}) {
|
|
297
|
+
const target = herdrTarget(env, platform);
|
|
298
|
+
if (!target.available) return { status: 'unavailable', reason: target.reason };
|
|
299
|
+
|
|
300
|
+
let temporary = null;
|
|
301
|
+
const staged = { created: false };
|
|
302
|
+
try {
|
|
303
|
+
const original = snapshot(target.configPath);
|
|
304
|
+
const plan = planThemeConfig(decodeUtf8(original.bytes), projection);
|
|
305
|
+
if (plan.ok === false) return { status: 'partial', stage: 'config', error: plan.error };
|
|
306
|
+
if (plan.changed) {
|
|
307
|
+
const bytes = Buffer.from(plan.text, 'utf8');
|
|
308
|
+
// The read limit is also the write limit: a file we could read but not
|
|
309
|
+
// write back would make the next run refuse its own output.
|
|
310
|
+
if (bytes.length > MAX_BYTES) {
|
|
311
|
+
return {
|
|
312
|
+
status: 'partial',
|
|
313
|
+
stage: 'config',
|
|
314
|
+
error: `Herdr config would grow to ${bytes.length} bytes, past the ${MAX_BYTES}-byte limit; no changes proposed.`,
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
// Compare before the backup so the backup is never taken from bytes that
|
|
318
|
+
// are already gone.
|
|
319
|
+
unchangedSince(target.configPath, original);
|
|
320
|
+
ensureBackup(target.configPath, original.bytes);
|
|
321
|
+
// The path exists before the bytes do: a failure inside staging must leave
|
|
322
|
+
// this function able to remove it.
|
|
323
|
+
temporary = `${target.configPath}.${randomUUID()}.tmp`;
|
|
324
|
+
writeStaged(temporary, bytes, original.stat.mode, staged);
|
|
325
|
+
// The final compare sits immediately before the rename: an edit that
|
|
326
|
+
// landed while the new bytes were staged is still caught here, and one
|
|
327
|
+
// that lands after this point is the inherent limit of rename-based
|
|
328
|
+
// writes (see the module header).
|
|
329
|
+
unchangedSince(target.configPath, original);
|
|
330
|
+
fs.renameSync(temporary, target.configPath);
|
|
331
|
+
temporary = null;
|
|
332
|
+
} else if (!forceReload) {
|
|
333
|
+
// Nothing to write means nothing to reload: Herdr already shows this palette.
|
|
334
|
+
return { status: 'unchanged' };
|
|
335
|
+
}
|
|
336
|
+
} catch (error) {
|
|
337
|
+
// A staged temp file must never survive a failed replace: it would sit
|
|
338
|
+
// beside the user's config forever. The original is never touched here.
|
|
339
|
+
const leftover = temporary !== null && staged.created ? discard(temporary) : null;
|
|
340
|
+
return {
|
|
341
|
+
status: 'partial',
|
|
342
|
+
stage: 'config',
|
|
343
|
+
error: leftover === null ? message(error) : `${message(error)}; temporary file left behind: ${leftover}`,
|
|
344
|
+
};
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
try {
|
|
348
|
+
await reload(target.binary, env);
|
|
349
|
+
} catch (error) {
|
|
350
|
+
// The config is committed and Herdr's client state is unknown; retrying a
|
|
351
|
+
// reload here would race the next tick, so the caller sees partial state.
|
|
352
|
+
return { status: 'partial', stage: 'reload', error: message(error) };
|
|
353
|
+
}
|
|
354
|
+
return { status: 'requested' };
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
module.exports = {
|
|
358
|
+
applyHerdrTheme,
|
|
359
|
+
herdrThemeAvailability,
|
|
360
|
+
herdrConfigPath,
|
|
361
|
+
};
|