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.
@@ -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
+ };