herdr-gentle-shell 1.5.1 → 1.6.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 +185 -85
- package/README.md +90 -45
- package/docs/diagnostics.md +4 -3
- package/docs/performance-trace.md +2 -1
- package/docs/sidebar-control.md +4 -2
- package/docs/supervision.md +17 -3
- package/extensions/gentle-herdr-state.ts +734 -128
- package/lib/gentle-sidebar.js +87 -33
- package/lib/perf-trace.js +83 -13
- package/package.json +1 -1
package/lib/gentle-sidebar.js
CHANGED
|
@@ -28,14 +28,22 @@ const LEGACY_PLUGIN_ID = 'herdr-gentle-agents';
|
|
|
28
28
|
// keeps the existing directory so upgrades keep their mode flag, marker
|
|
29
29
|
// and installer state with no migration step.
|
|
30
30
|
const STATE_PLUGIN_ID = 'herdr-gentle-agents';
|
|
31
|
-
// Family of files proving a state dir is ours:
|
|
32
|
-
//
|
|
33
|
-
//
|
|
34
|
-
//
|
|
35
|
-
//
|
|
36
|
-
//
|
|
37
|
-
//
|
|
38
|
-
//
|
|
31
|
+
// Family of files proving a state dir is ours: the stored dir wins whenever it
|
|
32
|
+
// holds one of these, so pre-rename flags stay readable and one stray known
|
|
33
|
+
// file in the Herdr-injected dir (which changes with the plugin id) may never
|
|
34
|
+
// outrank the stored state — the daemon writes its pidfile into the dir it
|
|
35
|
+
// resolves, so that would make the split self-perpetuating. The active plugin id
|
|
36
|
+
// dir (`herdr-gentle-shell`) is a candidate in every context, because it is what
|
|
37
|
+
// Herdr injects and a legacy install may still keep its live flags only there;
|
|
38
|
+
// the stored canonical dir is the FINAL fallback, so a fresh install resolves the
|
|
39
|
+
// same directory in a context that receives the injected variable and one that
|
|
40
|
+
// never does. Selection order: stored if it holds a known file, else the
|
|
41
|
+
// active-id/injected dir if it holds one, else stored. This family is IDENTICAL
|
|
42
|
+
// in lib/perf-trace.js, herdr-plugin/bin/gentle-status.js,
|
|
43
|
+
// herdr-plugin/lib/gentle-diagnostics.js and the state extension, and every
|
|
44
|
+
// reader here must recognise every file any of them writes: a family that omits
|
|
45
|
+
// a file splits the state across both dirs, and a flag stored disabled then
|
|
46
|
+
// reads as missing (missing means enabled).
|
|
39
47
|
const STATE_KNOWN_FILES = [
|
|
40
48
|
'gentle-sidebar-mode.json',
|
|
41
49
|
'gentle-moshi.json',
|
|
@@ -46,6 +54,14 @@ const STATE_KNOWN_FILES = [
|
|
|
46
54
|
'gentle-worktree-mode.json',
|
|
47
55
|
'gentle-plugin-tools.json',
|
|
48
56
|
];
|
|
57
|
+
// S1c: the only basenames an injected state dir may have to be honoured — the
|
|
58
|
+
// active plugin id Herdr injects today and the stored canonical segment — and
|
|
59
|
+
// the path must also BE the one this package derives for that name under the
|
|
60
|
+
// resolved state home. Any other injected path belongs to another plugin (or a
|
|
61
|
+
// stale/dev id) and is ignored, and so is an owned basename under another root,
|
|
62
|
+
// because the daemon receives the variable while this helper does not:
|
|
63
|
+
// honouring either is exactly what splits their state.
|
|
64
|
+
const OWNED_DIR_NAMES = [ACTIVE_PLUGIN_ID, STATE_PLUGIN_ID];
|
|
49
65
|
// Backwards-compatible alias: the active plugin lookup identity.
|
|
50
66
|
const PLUGIN_ID = ACTIVE_PLUGIN_ID;
|
|
51
67
|
const MODE_VERSION = 1;
|
|
@@ -59,6 +75,62 @@ function storedStateDir(env = process.env) {
|
|
|
59
75
|
: path.join(os.homedir(), '.local', 'state', 'herdr');
|
|
60
76
|
return path.join(base, 'plugins', STATE_PLUGIN_ID);
|
|
61
77
|
}
|
|
78
|
+
|
|
79
|
+
function dirHasKnownFiles(dir) {
|
|
80
|
+
for (const name of STATE_KNOWN_FILES) {
|
|
81
|
+
try {
|
|
82
|
+
if (fs.existsSync(path.join(dir, name))) return true;
|
|
83
|
+
} catch {
|
|
84
|
+
// A single unreadable entry never decides; keep scanning.
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
return false;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
// Two spellings name the same directory when their canonical forms match.
|
|
91
|
+
// realpath resolves symlinks but throws for a path that does not exist yet, so
|
|
92
|
+
// walk up to the deepest existing ancestor and re-append the missing tail: that
|
|
93
|
+
// keeps a symlinked or relative spelling of the derived dir from being rejected
|
|
94
|
+
// as a different directory (S1c/T12 compares paths, never raw strings).
|
|
95
|
+
function canonicalStateDir(dir) {
|
|
96
|
+
const absolute = path.resolve(dir);
|
|
97
|
+
const tail = [];
|
|
98
|
+
let current = absolute;
|
|
99
|
+
for (;;) {
|
|
100
|
+
try {
|
|
101
|
+
const real = fs.realpathSync(current);
|
|
102
|
+
return tail.length ? path.join(real, ...tail) : real;
|
|
103
|
+
} catch {
|
|
104
|
+
const parent = path.dirname(current);
|
|
105
|
+
if (parent === current) return absolute;
|
|
106
|
+
// Prepended so the missing tail is re-appended in its original order.
|
|
107
|
+
tail.unshift(path.basename(current));
|
|
108
|
+
current = parent;
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
// The active-id dir: the Herdr-injected one only when it IS the directory this
|
|
114
|
+
// package derives for that name under the resolved state home, else the same
|
|
115
|
+
// sibling of the stored dir derived from the state home. S1c: an injected path
|
|
116
|
+
// with any other basename (a third plugin id, a stale or dev id) — or an owned
|
|
117
|
+
// basename under another root, which is exactly the case that splits the daemon
|
|
118
|
+
// (it receives the variable) from the producer (it derives its own) — is
|
|
119
|
+
// ignored rather than selected.
|
|
120
|
+
function activeStateDir(env = process.env) {
|
|
121
|
+
const pluginsDir = path.dirname(storedStateDir(env));
|
|
122
|
+
const injected = env.HERDR_PLUGIN_STATE_DIR;
|
|
123
|
+
if (typeof injected === 'string' && injected.length > 0) {
|
|
124
|
+
const name = path.basename(injected);
|
|
125
|
+
if (
|
|
126
|
+
OWNED_DIR_NAMES.includes(name) &&
|
|
127
|
+
canonicalStateDir(injected) === canonicalStateDir(path.join(pluginsDir, name))
|
|
128
|
+
) {
|
|
129
|
+
return injected;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return path.join(pluginsDir, ACTIVE_PLUGIN_ID);
|
|
133
|
+
}
|
|
62
134
|
const MODE_NAME = 'gentle-sidebar-mode.json';
|
|
63
135
|
const MANAGED_BEGIN = '# BEGIN herdr-gentle-agents (managed; do not edit)';
|
|
64
136
|
const MANAGED_END = '# END herdr-gentle-agents';
|
|
@@ -69,35 +141,17 @@ function stateDir(env = process.env) {
|
|
|
69
141
|
const stored = storedStateDir(env);
|
|
70
142
|
// HEAD parity: an explicit-but-empty (or otherwise invalid non-nullish)
|
|
71
143
|
// value ignores every override and uses the stored default. Only an
|
|
72
|
-
// omitted (null/undefined) explicit falls through to the
|
|
144
|
+
// omitted (null/undefined) explicit falls through to the active-id dir.
|
|
73
145
|
if (explicit !== undefined && explicit !== null) return stored;
|
|
74
|
-
const
|
|
75
|
-
if (
|
|
76
|
-
if (injected === stored) return injected;
|
|
146
|
+
const active = activeStateDir(env);
|
|
147
|
+
if (active === stored) return stored;
|
|
77
148
|
try {
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
try {
|
|
81
|
-
if (fs.existsSync(path.join(injected, name))) {
|
|
82
|
-
injectedHas = true;
|
|
83
|
-
break;
|
|
84
|
-
}
|
|
85
|
-
} catch {
|
|
86
|
-
// A single unreadable entry never decides; keep scanning.
|
|
87
|
-
}
|
|
88
|
-
}
|
|
89
|
-
if (injectedHas) return injected;
|
|
90
|
-
for (const name of STATE_KNOWN_FILES) {
|
|
91
|
-
try {
|
|
92
|
-
if (fs.existsSync(path.join(stored, name))) return stored;
|
|
93
|
-
} catch {
|
|
94
|
-
// A single unreadable entry never decides; keep scanning.
|
|
95
|
-
}
|
|
96
|
-
}
|
|
149
|
+
if (dirHasKnownFiles(stored)) return stored;
|
|
150
|
+
if (dirHasKnownFiles(active)) return active;
|
|
97
151
|
} catch {
|
|
98
|
-
// Fall through to the
|
|
152
|
+
// Fall through to the stored canonical dir on unexpected failure.
|
|
99
153
|
}
|
|
100
|
-
return
|
|
154
|
+
return stored;
|
|
101
155
|
}
|
|
102
156
|
|
|
103
157
|
function modePath(env) {
|
package/lib/perf-trace.js
CHANGED
|
@@ -2,13 +2,22 @@
|
|
|
2
2
|
// Writer half of the performance trace (S18/S24).
|
|
3
3
|
//
|
|
4
4
|
// Two plugin-owned files in the resolved plugin state directory:
|
|
5
|
-
// GENTLE_STATUS_STATE_DIR (explicit override), else
|
|
6
|
-
// when it already holds one of our files, else
|
|
5
|
+
// GENTLE_STATUS_STATE_DIR (explicit override), else
|
|
7
6
|
// $XDG_STATE_HOME/herdr/plugins/herdr-gentle-agents, else
|
|
8
|
-
// ~/.local/state/herdr/plugins/herdr-gentle-agents
|
|
9
|
-
//
|
|
10
|
-
//
|
|
11
|
-
//
|
|
7
|
+
// ~/.local/state/herdr/plugins/herdr-gentle-agents — the stored dir wins
|
|
8
|
+
// whenever it holds any of our files, and HERDR_PLUGIN_STATE_DIR is used only
|
|
9
|
+
// when the stored dir holds none while that one does; one stray known file in
|
|
10
|
+
// the injected dir may never outrank the stored state. The stored canonical dir
|
|
11
|
+
// is the FINAL fallback, so a fresh install resolves the same directory in a
|
|
12
|
+
// context that receives the injected variable and one that never does. An
|
|
13
|
+
// injected path is honoured only when it IS the directory this package derives
|
|
14
|
+
// for that name under the resolved state home (an owned basename under another
|
|
15
|
+
// root is ignored too); any other path is ignored (S1c), because the daemon
|
|
16
|
+
// receives that variable while this writer does not.
|
|
17
|
+
// The resolution and its known-file family are byte-for-byte the ones the sidebar
|
|
18
|
+
// switch, the Herdr daemon and its diagnostics use, so all four read and write
|
|
19
|
+
// one directory per install — which is why it lives here rather than in a
|
|
20
|
+
// worktree module.
|
|
12
21
|
//
|
|
13
22
|
// perf-trace.jsonl one JSON object per line — the trace
|
|
14
23
|
// perf-trace.1.jsonl the single previous log, created on rotation
|
|
@@ -51,6 +60,18 @@ const { readHostValues } = require('./host-settings.js');
|
|
|
51
60
|
// still carries them, and a family that differs between consumers splits the
|
|
52
61
|
// state across two directories.
|
|
53
62
|
const STATE_SEGMENT = 'herdr-gentle-agents';
|
|
63
|
+
// The active plugin lookup id: what Herdr injects as HERDR_PLUGIN_STATE_DIR, and
|
|
64
|
+
// where a legacy install may still keep its live flags. Every context resolves
|
|
65
|
+
// it, not only the daemon that receives the variable.
|
|
66
|
+
const ACTIVE_PLUGIN_ID = 'herdr-gentle-shell';
|
|
67
|
+
// S1c: the only basenames an injected state dir may have to be honoured — the
|
|
68
|
+
// active plugin id and the stored canonical segment — and the path must also BE
|
|
69
|
+
// the one this package derives for that name under the resolved state home. Any
|
|
70
|
+
// other injected path belongs to another plugin (a third id, a stale or dev id)
|
|
71
|
+
// and is ignored, and so is an owned basename under another root, because the
|
|
72
|
+
// daemon receives the variable while this writer usually does not: honouring
|
|
73
|
+
// either is exactly what splits the trace away from the rest of the state.
|
|
74
|
+
const OWNED_DIR_NAMES = [ACTIVE_PLUGIN_ID, STATE_SEGMENT];
|
|
54
75
|
const STATE_KNOWN_FILES = [
|
|
55
76
|
'gentle-sidebar-mode.json',
|
|
56
77
|
'gentle-moshi.json',
|
|
@@ -80,24 +101,73 @@ function dirHasKnownFiles(dir) {
|
|
|
80
101
|
return false;
|
|
81
102
|
}
|
|
82
103
|
|
|
104
|
+
// Two spellings name the same directory when their canonical forms match.
|
|
105
|
+
// realpath resolves symlinks but throws for a path that does not exist yet, so
|
|
106
|
+
// walk up to the deepest existing ancestor and re-append the missing tail: that
|
|
107
|
+
// keeps a symlinked or relative spelling of the derived dir from being rejected
|
|
108
|
+
// as a different directory (S1c/T12 compares paths, never raw strings).
|
|
109
|
+
function canonicalStateDir(dir) {
|
|
110
|
+
const absolute = path.resolve(dir);
|
|
111
|
+
const tail = [];
|
|
112
|
+
let current = absolute;
|
|
113
|
+
for (;;) {
|
|
114
|
+
try {
|
|
115
|
+
const real = fs.realpathSync(current);
|
|
116
|
+
return tail.length ? path.join(real, ...tail) : real;
|
|
117
|
+
} catch {
|
|
118
|
+
const parent = path.dirname(current);
|
|
119
|
+
if (parent === current) return absolute;
|
|
120
|
+
// Prepended so the missing tail is re-appended in its original order.
|
|
121
|
+
tail.unshift(path.basename(current));
|
|
122
|
+
current = parent;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
// The active-id dir: the injected one only when it IS the directory this package
|
|
128
|
+
// derives for that name under the resolved state home, else the same sibling of
|
|
129
|
+
// the stored dir derived from the state home (the segment is the only difference,
|
|
130
|
+
// so the parent of the stored dir is the plugins dir). S1c: an injected path with
|
|
131
|
+
// any other basename (a third plugin id, a stale or dev id) — or an owned basename
|
|
132
|
+
// under another root, which is exactly the case that splits this writer from the
|
|
133
|
+
// daemon — is ignored, not selected.
|
|
134
|
+
function activeStateDir(env) {
|
|
135
|
+
const pluginsDir = path.dirname(storedStateDir(env));
|
|
136
|
+
const injected = env.HERDR_PLUGIN_STATE_DIR;
|
|
137
|
+
if (typeof injected === 'string' && injected.length > 0) {
|
|
138
|
+
const name = path.basename(injected);
|
|
139
|
+
if (
|
|
140
|
+
OWNED_DIR_NAMES.includes(name) &&
|
|
141
|
+
canonicalStateDir(injected) === canonicalStateDir(path.join(pluginsDir, name))
|
|
142
|
+
) {
|
|
143
|
+
return injected;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
return path.join(pluginsDir, ACTIVE_PLUGIN_ID);
|
|
147
|
+
}
|
|
148
|
+
|
|
83
149
|
// The explicit-but-empty (or non-string) override keeps using the stored
|
|
84
150
|
// default, so a trace log written before the injected dir was introduced is
|
|
85
|
-
// still the same file after an upgrade.
|
|
151
|
+
// still the same file after an upgrade. The stored dir wins over the active-id
|
|
152
|
+
// (injected) one whenever it holds a known file: the daemon writes its pidfile
|
|
153
|
+
// into the dir it resolves, so one stray known file there would make the split
|
|
154
|
+
// self-perpetuating. The active-id dir wins only when the stored dir holds no
|
|
155
|
+
// known file and it does; the stored canonical dir is the final fallback, so a
|
|
156
|
+
// fresh install resolves the same dir with or without the injected variable.
|
|
86
157
|
function resolveStateDir(env) {
|
|
87
158
|
const explicit = env.GENTLE_STATUS_STATE_DIR;
|
|
88
159
|
if (typeof explicit === 'string' && explicit.length > 0) return explicit;
|
|
89
160
|
const stored = storedStateDir(env);
|
|
90
161
|
if (explicit !== undefined && explicit !== null) return stored;
|
|
91
|
-
const
|
|
92
|
-
if (
|
|
93
|
-
if (injected === stored) return injected;
|
|
162
|
+
const active = activeStateDir(env);
|
|
163
|
+
if (active === stored) return stored;
|
|
94
164
|
try {
|
|
95
|
-
if (dirHasKnownFiles(injected)) return injected;
|
|
96
165
|
if (dirHasKnownFiles(stored)) return stored;
|
|
166
|
+
if (dirHasKnownFiles(active)) return active;
|
|
97
167
|
} catch {
|
|
98
|
-
// Fall through to the
|
|
168
|
+
// Fall through to the stored canonical dir on unexpected failure.
|
|
99
169
|
}
|
|
100
|
-
return
|
|
170
|
+
return stored;
|
|
101
171
|
}
|
|
102
172
|
|
|
103
173
|
const LOG_NAME = 'perf-trace.jsonl';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "herdr-gentle-shell",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.0",
|
|
4
4
|
"description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|