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 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-agents/herdr-plugin`, updated with
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 old managed-copy install (the installer copying
811
- `extensions/gentle-herdr-state.ts` into the Pi agent dir) is retired: the
812
- installer installs both packages and migrates an owned legacy copy aside.
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
- One script installs two packages: the Herdr plugin (`herdr-plugin/`,
55
- installed with `herdr plugin install
56
- jonasotoaguilar/herdr-gentle-agents/herdr-plugin`) and the Pi package (the
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 with the
61
- `install.sh` and `install.sh.sha256` assets) — so either side may lag the
62
- other; the Herdr side is not bumped when it carries no change.
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: only the published names above were renamed. The code
65
- still lives at `github.com/jonasotoaguilar/herdr-gentle-agents`, so every
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
- Installer usage:
70
- `install.sh [--ref REF] [--pi-source auto|npm|git] [--allow-downgrade] [--uninstall] [--help]`
65
+ ### Install the Herdr plugin (always)
71
66
 
72
- The stable entrypoint always resolves to the newest `herdr-vX.Y.Z` release,
73
- while each
74
- release freezes its uploaded asset bytes — the URL moves forward, the bytes
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
- Review the script before piping it to a shell — fetch the URL
78
- (never `main`) and read it first. The installer never uses `sudo` and never
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 in Pi
74
+ ### Install the Pi package
82
75
 
83
76
  ```sh
84
77
  pi install npm:herdr-gentle-shell
85
78
  ```
86
79
 
87
- ### Install in Gentle Shell
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
- ```sh
103
- curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh
104
- ```
90
+ Running Pi sessions still need `/reload` (or a restart) to pick up the
91
+ updated extension.
105
92
 
106
- With no `--ref` the installer resolves the newest `herdr-vX.Y.Z` release tag automatically.
107
-
108
- ### Pinned install (explicit tag)
93
+ ### Apply the sidebar override
109
94
 
110
95
  ```sh
111
- curl -fsSL https://raw.githubusercontent.com/jonasotoaguilar/herdr-gentle-agents/herdr-v0.4.0/install.sh | sh -s -- --ref herdr-v0.4.0
96
+ herdr plugin action invoke configure --plugin herdr-gentle-shell
112
97
  ```
113
98
 
114
- Pass `--ref <tag>` to pin an older `herdr-vX.Y.Z` release instead of following latest.
115
-
116
- What the installer does:
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 the installer honors a `PI_AGENT_DIR` override (default
189
- `$HOME/.pi/agent`) without touching the live Pi dir, e.g.
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, pass
207
- `--ref` with `--allow-downgrade`:
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
- curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh -s -- --ref herdr-vX.Y.Z --allow-downgrade
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
- curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh -s -- --uninstall
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
- Uninstall runs the installed plugin's `configure --uninstall`, best-effort daemon `--stop --purge` and
234
- `herdr server reload-config`, then removes both packages (the Herdr plugin and
235
- the Pi package), the owned native-extension exclusion entry, and the installer
236
- state. A legacy managed Pi copy
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: uninstall warns, preserves
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
@@ -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 from the installer) and
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.5.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-agents#readme",
11
+ "homepage": "https://github.com/jonasotoaguilar/herdr-gentle-shell#readme",
12
12
  "bugs": {
13
- "url": "https://github.com/jonasotoaguilar/herdr-gentle-agents/issues"
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-agents.git"
17
+ "url": "git+https://github.com/jonasotoaguilar/herdr-gentle-shell.git"
18
18
  },
19
19
  "license": "MIT",
20
20
  "engines": {