herdr-gentle-shell 0.5.0 → 1.0.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 +5 -4
- package/README.md +37 -115
- package/docs/sidebar-control.md +1 -1
- package/package.json +4 -4
package/DESIGN.md
CHANGED
|
@@ -804,12 +804,13 @@ exactly one mechanism writes each piece of state.
|
|
|
804
804
|
npm as `herdr-gentle-shell`, installed with
|
|
805
805
|
`pi install`, updated with `pi update --extensions`) and the Herdr plugin
|
|
806
806
|
in `herdr-plugin/` (installed with `herdr plugin install
|
|
807
|
-
jonasotoaguilar/herdr-gentle-
|
|
807
|
+
jonasotoaguilar/herdr-gentle-shell/herdr-plugin`, updated with
|
|
808
808
|
`herdr plugin update herdr-gentle-shell`). Releases run on two tag
|
|
809
809
|
series, `pi-vX.Y.Z` and `herdr-vX.Y.Z`; the Herdr side is not bumped when
|
|
810
|
-
it carries no change. The
|
|
811
|
-
|
|
812
|
-
|
|
810
|
+
it carries no change. The repository ships no install script: the
|
|
811
|
+
documented path is the two plain package installs above. The old
|
|
812
|
+
managed-copy install (copying `extensions/gentle-herdr-state.ts` into the
|
|
813
|
+
Pi agent dir) is retired and needs no migration step of its own.
|
|
813
814
|
Ownership split: the Pi package owns the Pi-side helpers (the extension,
|
|
814
815
|
the exclusion helper, the sidebar bridge); the Herdr plugin owns the
|
|
815
816
|
runtime Herdr consumes (manifest, daemon, configure, diagnostics, token
|
package/README.md
CHANGED
|
@@ -51,40 +51,33 @@ Prerequisites: Linux, Node >= 18, Herdr meeting `min_herdr_version` in
|
|
|
51
51
|
`herdr-pi-tree` installed (it stays installed but disabled for gentle-owned
|
|
52
52
|
panes).
|
|
53
53
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
repository root, published to npm as `herdr-gentle-shell`
|
|
58
|
-
with the `pi-package` keyword, installed with `pi install`). The two
|
|
54
|
+
Two packages install separately: the Herdr plugin (`herdr-plugin/`) and the
|
|
55
|
+
Pi package (the repository root, published to npm as `herdr-gentle-shell`
|
|
56
|
+
with the `pi-package` keyword). The two
|
|
59
57
|
packages version independently and release from two tag series —
|
|
60
|
-
`pi-vX.Y.Z` (npm publish) and `herdr-vX.Y.Z` (GitHub Release
|
|
61
|
-
|
|
62
|
-
|
|
58
|
+
`pi-vX.Y.Z` (npm publish) and `herdr-vX.Y.Z` (GitHub Release) — so either
|
|
59
|
+
side may lag the other; the Herdr side is not bumped when it carries no
|
|
60
|
+
change.
|
|
63
61
|
|
|
64
|
-
Source repository:
|
|
65
|
-
|
|
66
|
-
GitHub URL below keeps that repository; no `herdr-gentle-shell` repository
|
|
67
|
-
was created.
|
|
62
|
+
Source repository: `github.com/jonasotoaguilar/herdr-gentle-shell`, the
|
|
63
|
+
origin that publishes both packages and creates the releases.
|
|
68
64
|
|
|
69
|
-
|
|
70
|
-
`install.sh [--ref REF] [--pi-source auto|npm|git] [--allow-downgrade] [--uninstall] [--help]`
|
|
65
|
+
### Install the Herdr plugin (always)
|
|
71
66
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
it served for a given release never change.
|
|
67
|
+
```sh
|
|
68
|
+
herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin
|
|
69
|
+
```
|
|
76
70
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
handles credentials.
|
|
71
|
+
The Herdr side is always installed; the Pi package below is not optional
|
|
72
|
+
either, since the sidebar states come from it.
|
|
80
73
|
|
|
81
|
-
### Install
|
|
74
|
+
### Install the Pi package
|
|
82
75
|
|
|
83
76
|
```sh
|
|
84
77
|
pi install npm:herdr-gentle-shell
|
|
85
78
|
```
|
|
86
79
|
|
|
87
|
-
|
|
80
|
+
Inside a Gentle Shell session, the same package is installed through the shell's launcher:
|
|
88
81
|
|
|
89
82
|
```sh
|
|
90
83
|
gentle-shell install npm:herdr-gentle-shell
|
|
@@ -93,83 +86,20 @@ gentle-shell install npm:herdr-gentle-shell
|
|
|
93
86
|
Both hosts install the same npm package,
|
|
94
87
|
`herdr-gentle-shell` — the Pi extension that publishes the
|
|
95
88
|
session facts behind the sidebar states — and only the host command differs.
|
|
96
|
-
These two commands install the Pi package only; the Herdr plugin side still
|
|
97
|
-
comes from the installer script below or from
|
|
98
|
-
`herdr plugin install jonasotoaguilar/herdr-gentle-agents/herdr-plugin`.
|
|
99
|
-
|
|
100
|
-
### Public install (stable, one command)
|
|
101
89
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
```
|
|
90
|
+
Running Pi sessions still need `/reload` (or a restart) to pick up the
|
|
91
|
+
updated extension.
|
|
105
92
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
### Pinned install (explicit tag)
|
|
93
|
+
### Apply the sidebar override
|
|
109
94
|
|
|
110
95
|
```sh
|
|
111
|
-
|
|
96
|
+
herdr plugin action invoke configure --plugin herdr-gentle-shell
|
|
112
97
|
```
|
|
113
98
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- Installs and enables the Herdr plugin from the `herdr-plugin/`
|
|
119
|
-
subdirectory at the resolved `--ref` (the newest `herdr-vX.Y.Z` release
|
|
120
|
-
when `--ref` is omitted).
|
|
121
|
-
- Installs the Pi package with `pi install`. `--pi-source` selects the
|
|
122
|
-
source: `npm` installs `npm:herdr-gentle-shell`, `git`
|
|
123
|
-
installs `git:github.com/jonasotoaguilar/herdr-gentle-agents`, and `auto`
|
|
124
|
-
(the default) uses npm when the package resolves on the registry and
|
|
125
|
-
otherwise falls back to git with a warning — so an install before the
|
|
126
|
-
first published npm version still converges through the git source.
|
|
127
|
-
- Migrates an owned legacy managed copy away instead of refreshing it in
|
|
128
|
-
place: a previous install's `~/.pi/agent/extensions/gentle-herdr-state.ts`
|
|
129
|
-
is moved aside to a timestamped backup, never silently destroyed. The
|
|
130
|
-
managed-copy layout is retired; a conflicting destination — including a
|
|
131
|
-
locally modified copy, symlink, directory, or special file — is likewise
|
|
132
|
-
moved aside, never deleted.
|
|
133
|
-
- Records the non-destructive force-exclusion `-extensions/herdr-agent-state.ts`
|
|
134
|
-
in the global Pi settings (`~/.pi/agent/settings.json`, or `$PI_AGENT_DIR`
|
|
135
|
-
when overridden) so the managed native base file stays on disk but is never
|
|
136
|
-
auto-loaded next to our copy — one publisher. The entry is appended
|
|
137
|
-
idempotently; unrelated settings and pre-existing exclusions are preserved,
|
|
138
|
-
and invalid settings fail closed (the installer aborts without rewriting the
|
|
139
|
-
file). Ownership is a bound record (exact entry plus canonical settings
|
|
140
|
-
path): if the record cannot be written, the settings change is rolled back
|
|
141
|
-
byte-identical, and if a later install step fails the exclusion is rolled
|
|
142
|
-
back best-effort so the base is not left disabled with no replacement (an
|
|
143
|
-
already-installed Pi package stays in place — re-run install to converge).
|
|
144
|
-
Symlinked settings are updated atomically through the link with the link and
|
|
145
|
-
mode preserved; fresh files are created 0600. Four limits: running Pi
|
|
146
|
-
sessions still need `/reload` (or a restart) for the exclusion to take
|
|
147
|
-
effect; an explicit project-level `extensions` entry can re-enable the base
|
|
148
|
-
file for that project; a rollback that itself fails says so instead of
|
|
149
|
-
claiming success; two agent dirs sharing one state dir fail closed on the
|
|
150
|
-
second install — separate `XDG_STATE_HOME` or remove the stale record.
|
|
151
|
-
- Runs the installed plugin's Herdr sidebar `configure --apply` plus `--check`, then best-effort
|
|
152
|
-
`herdr server reload-config` and best-effort daemon ensure via the installed
|
|
153
|
-
plugin's `bin/gentle-status.js`.
|
|
154
|
-
Best-effort reload/daemon failures warn without rolling back the completed install
|
|
155
|
-
and config. The `configure` action itself only writes the managed Herdr sidebar
|
|
156
|
-
block described below.
|
|
157
|
-
- Running Pi sessions still need `/reload` (or a restart) to pick up the updated extension.
|
|
158
|
-
|
|
159
|
-
Environment overrides: `HERDR_BIN_PATH`, `PI_BIN_PATH`, `NPM_BIN_PATH`,
|
|
160
|
-
`PI_AGENT_DIR`, `XDG_STATE_HOME`, `HERDR_GENTLE_PLUGIN_ROOT`,
|
|
161
|
-
`HERDR_GENTLE_PI_SOURCE` (same values as `--pi-source`), and
|
|
162
|
-
`HERDR_GENTLE_LATEST_URL` (release lookup for newest-tag resolution).
|
|
163
|
-
|
|
164
|
-
### Migration from a managed copy (pre-split installs)
|
|
165
|
-
|
|
166
|
-
The pre-split installer refreshed a managed copy of
|
|
167
|
-
`extensions/gentle-herdr-state.ts` inside the Pi agent dir; that layout is
|
|
168
|
-
retired. The first two-package install migrates it: an owned legacy copy is
|
|
169
|
-
moved aside to a timestamped backup (a locally modified copy is preserved
|
|
170
|
-
with a warning, never deleted), the Pi package takes over the extension,
|
|
171
|
-
and the ownership-bound exclusion entry is kept. Nothing needs doing by
|
|
172
|
-
hand — re-run the installer to converge.
|
|
99
|
+
The action appends the managed pi-only `[ui.sidebar.agents.rows_by_agent]`
|
|
100
|
+
override described below and reloads the server; `herdr server reload-config`
|
|
101
|
+
and the daemon start (`node bin/gentle-status.js`) are the same commands run by
|
|
102
|
+
hand.
|
|
173
103
|
|
|
174
104
|
### Local development
|
|
175
105
|
|
|
@@ -185,9 +115,8 @@ The repository root is the Pi package (`herdr-gentle-shell`)
|
|
|
185
115
|
and `herdr-plugin/` is the Herdr plugin. Then run `/reload` in Pi to pick up
|
|
186
116
|
the local package.
|
|
187
117
|
|
|
188
|
-
For isolated/local use
|
|
189
|
-
|
|
190
|
-
`PI_AGENT_DIR=/tmp/pi-agent-test sh install.sh --ref herdr-v0.4.0`.
|
|
118
|
+
For isolated/local use point Pi at a throwaway agent dir, e.g. from this
|
|
119
|
+
checkout `PI_AGENT_DIR=/tmp/pi-agent-test pi install .`.
|
|
191
120
|
|
|
192
121
|
### Update
|
|
193
122
|
|
|
@@ -203,16 +132,13 @@ and the Herdr plugin updates with:
|
|
|
203
132
|
herdr plugin update herdr-gentle-shell
|
|
204
133
|
```
|
|
205
134
|
|
|
206
|
-
To move the Herdr side to an explicitly older `herdr-vX.Y.Z` release,
|
|
207
|
-
|
|
135
|
+
To move the Herdr side to an explicitly older `herdr-vX.Y.Z` release, install
|
|
136
|
+
that ref after removing the current one:
|
|
208
137
|
|
|
209
138
|
```sh
|
|
210
|
-
|
|
139
|
+
herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin --ref herdr-vX.Y.Z
|
|
211
140
|
```
|
|
212
141
|
|
|
213
|
-
Without `--allow-downgrade`, installing an older Herdr version than the
|
|
214
|
-
installed one aborts naming both versions.
|
|
215
|
-
|
|
216
142
|
If the installed plugin is locally linked, the remote install replaces it
|
|
217
143
|
automatically and warns naming the plugin id; to restore a checkout afterwards
|
|
218
144
|
re-link it:
|
|
@@ -221,24 +147,20 @@ re-link it:
|
|
|
221
147
|
herdr plugin link --enabled ./herdr-plugin
|
|
222
148
|
```
|
|
223
149
|
|
|
224
|
-
`--force` is deprecated and a no-op kept only so older documented commands
|
|
225
|
-
keep working; use `--allow-downgrade` for downgrades instead.
|
|
226
|
-
|
|
227
150
|
### Removal
|
|
228
151
|
|
|
229
152
|
```sh
|
|
230
|
-
|
|
153
|
+
herdr plugin action invoke unconfigure --plugin herdr-gentle-shell
|
|
154
|
+
pi remove npm:herdr-gentle-shell
|
|
155
|
+
herdr plugin uninstall herdr-gentle-shell
|
|
231
156
|
```
|
|
232
157
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
is ownership-checked: a locally modified `~/.pi/agent/extensions/gentle-herdr-state.ts`
|
|
238
|
-
is preserved with a warning, never deleted. The settings exclusion is likewise
|
|
239
|
-
ownership-checked: only the entry this installer added is removed, while a
|
|
158
|
+
The `unconfigure` action takes the managed sidebar override out of the Herdr
|
|
159
|
+
config and reloads it; the user-owned `[ui.sidebar.agents]` table is left
|
|
160
|
+
intact. The settings exclusion is likewise
|
|
161
|
+
ownership-checked: only the entry this plugin added is removed, while a
|
|
240
162
|
pre-existing identical entry and unrelated settings are preserved. A foreign,
|
|
241
|
-
invalid, or misbound ownership record fails closed:
|
|
163
|
+
invalid, or misbound ownership record fails closed: removal warns, preserves
|
|
242
164
|
the entry, and still removes the plugin.
|
|
243
165
|
|
|
244
166
|
Path convention used below: `node bin/...` runs from the installed plugin
|
package/docs/sidebar-control.md
CHANGED
|
@@ -30,7 +30,7 @@ HERDR_CONFIG_PATH=/tmp/c.toml node bin/gentle-sidebar.js status
|
|
|
30
30
|
Herdr config to verify the managed pi-only rows are present. Only then
|
|
31
31
|
it records the plugin-owned exclusion of the native integration
|
|
32
32
|
(`-extensions/herdr-agent-state.ts` in the Pi `settings.json`
|
|
33
|
-
`extensions` list, with the ownership marker
|
|
33
|
+
`extensions` list, with the plugin-owned ownership marker) and
|
|
34
34
|
writes the shared mode file
|
|
35
35
|
(`gentle-sidebar-mode.json`, `{version:1,enabled:true}`). A zero exit
|
|
36
36
|
alone never commits state: without the verified row effect the apply
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "herdr-gentle-shell",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.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",
|
|
@@ -8,13 +8,13 @@
|
|
|
8
8
|
"herdr",
|
|
9
9
|
"moshi"
|
|
10
10
|
],
|
|
11
|
-
"homepage": "https://github.com/jonasotoaguilar/herdr-gentle-
|
|
11
|
+
"homepage": "https://github.com/jonasotoaguilar/herdr-gentle-shell#readme",
|
|
12
12
|
"bugs": {
|
|
13
|
-
"url": "https://github.com/jonasotoaguilar/herdr-gentle-
|
|
13
|
+
"url": "https://github.com/jonasotoaguilar/herdr-gentle-shell/issues"
|
|
14
14
|
},
|
|
15
15
|
"repository": {
|
|
16
16
|
"type": "git",
|
|
17
|
-
"url": "git+https://github.com/jonasotoaguilar/herdr-gentle-
|
|
17
|
+
"url": "git+https://github.com/jonasotoaguilar/herdr-gentle-shell.git"
|
|
18
18
|
},
|
|
19
19
|
"license": "MIT",
|
|
20
20
|
"engines": {
|