herdr-gentle-shell 1.5.2 → 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.
@@ -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: when the Herdr-injected
32
- // dir (which changes with the plugin id) holds none of these while the
33
- // stored dir does, the stored dir wins so pre-rename flags stay readable.
34
- // This family is IDENTICAL in lib/perf-trace.js, herdr-plugin/bin/
35
- // gentle-status.js, herdr-plugin/lib/gentle-diagnostics.js and the state
36
- // extension, and every reader here must recognise every file any of them
37
- // writes: a family that omits a file splits the state across both dirs, and a
38
- // flag stored disabled then reads as missing (missing means enabled).
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 injected dir.
144
+ // omitted (null/undefined) explicit falls through to the active-id dir.
73
145
  if (explicit !== undefined && explicit !== null) return stored;
74
- const injected = env.HERDR_PLUGIN_STATE_DIR;
75
- if (typeof injected !== 'string' || injected.length === 0) return stored;
76
- if (injected === stored) return injected;
146
+ const active = activeStateDir(env);
147
+ if (active === stored) return stored;
77
148
  try {
78
- let injectedHas = false;
79
- for (const name of STATE_KNOWN_FILES) {
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 injected dir on unexpected failure.
152
+ // Fall through to the stored canonical dir on unexpected failure.
99
153
  }
100
- return injected;
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 HERDR_PLUGIN_STATE_DIR
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. The resolution and its
9
- // known-file family are byte-for-byte the ones the sidebar switch, the Herdr
10
- // daemon and its diagnostics use, so all four read and write one directory per
11
- // install — which is why it lives here rather than in a worktree module.
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 injected = env.HERDR_PLUGIN_STATE_DIR;
92
- if (typeof injected !== 'string' || injected.length === 0) return stored;
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 injected dir on unexpected failure.
168
+ // Fall through to the stored canonical dir on unexpected failure.
99
169
  }
100
- return injected;
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.5.2",
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",