dsh-version-manager 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tang Yixiao
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,233 @@
1
- # Temporary Holding Version
1
+ # dsh-version-manager
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Version management for DSH plugins and Skills, inside DeepSeek Harness.
4
+
5
+ It answers four questions about the profile you are actually running:
6
+
7
+ 1. **What is installed right now** — declared spec, installed version, where it came from, whether it loaded, whether it is compatible with this host.
8
+ 2. **What an update would change** — the exact versions offered, with prereleases kept apart and deprecations shown.
9
+ 3. **What the state was before the change** — a snapshot with a file fingerprint, written before the host is asked to do anything.
10
+ 4. **Whether it can be undone** — and when it cannot, the specific reason instead of a retry button.
11
+
12
+ The panel is a sidebar entry (`版本管理` / `Version manager`) with two tabs: plugins and Skills. It is a normal DSH bundle: nothing is patched into the host, no DOM is injected, and no private API is reached for.
13
+
14
+ ## Install
15
+
16
+ ```bash
17
+ dsh plugin --profile <your-profile> add dsh-version-manager@<version>
18
+ ```
19
+
20
+ From a local tarball:
21
+
22
+ ```bash
23
+ npm pack
24
+ dsh plugin --profile <your-profile> add /absolute/path/dsh-version-manager-0.1.0.tgz
25
+ ```
26
+
27
+ Then restart the host and open the panel from the left sidebar.
28
+
29
+ One prerequisite is worth knowing before you install into a *brand new* profile. `dsh plugin --profile <new> add …` creates a profile whose bundle list is just `@deepseek-ai/dsh-base`. A panel plugin needs `webServer`, which arrives with `@deepseek-ai/dsh-web-app`; without it this plugin sits in `pending (waiting for service: webServer)` and never draws anything. Desktop profiles already carry that bundle, so installing into the profile you already use is unaffected. Into an empty profile, add the web app bundle too.
30
+
31
+ Verify the bundle was installed from the tarball rather than from a stray checkout:
32
+
33
+ ```bash
34
+ node -e "console.log(require('fs').readFileSync('<profile>/node_modules/dsh-version-manager/package.json','utf8'))"
35
+ ```
36
+
37
+ ## What it does
38
+
39
+ ### Plugins tab
40
+
41
+ One row per entry the host reports, with the fields the host actually provides:
42
+
43
+ | column | meaning |
44
+ | --- | --- |
45
+ | package | the entry name the loader knows |
46
+ | installed version | the version on disk, or `未知` when the host does not know it |
47
+ | source | the declared spec, classified: registry, git, tarball, local path, alias, built into this profile, or unknown |
48
+ | load state | the loader phase: active, pending, loading, failed, unloading |
49
+ | compatibility | whether the package's own DSH version requirement is satisfied by this host |
50
+ | actions | check updates, take a snapshot |
51
+
52
+ Three states are kept apart on purpose, because collapsing them produces false confidence:
53
+
54
+ - **satisfied** — the package declares a DSH requirement and this host meets it.
55
+ - **no requirement declared** — the package declares nothing. This is not a pass; it is the absence of a claim, shown with a neutral dot.
56
+ - **unknown** — the requirement exists but could not be evaluated (for example the running version is unreadable), or the installed manifest was not read.
57
+
58
+ **Check updates** asks the host for versions newer than the installed one. Stable and prerelease are separate lists; a prerelease requires an explicit opt-in, and a row shows whether the version is still a bundle, whether it is deprecated, and what its compatibility verdict is.
59
+
60
+ **Update** always shows the from → to pair plus the four side effects before it runs:
61
+
62
+ - a snapshot is written first and read back before anything else happens;
63
+ - the host saves the target as an *exact* version, so a declared range is replaced;
64
+ - configuration, the dependency tree and agent presets are **not** rolled back;
65
+ - the host is not restarted.
66
+
67
+ ### Snapshots and restore
68
+
69
+ A snapshot records the profile identity, package name, original declared spec, installed version, source (including the registry host when the lockfile records one), enabled state, compatibility verdict, and a SHA-256 fingerprint of the package directory. It does **not** record tokens, credentials, environment variables or file contents.
70
+
71
+ Snapshots live under `<DSH_HOME>/version-manager/snapshots/<profile>/<package>/`, are written through a temporary file and renamed into place, never overwrite an existing snapshot, and are retained at 20 per target (the oldest beyond that are listed, not silently deleted).
72
+
73
+ Restore is offered only when it can actually work, and only reports what happened:
74
+
75
+ | reply | meaning |
76
+ | --- | --- |
77
+ | `alreadyAtVersion: true` | the profile already carries that version; nothing was reinstalled |
78
+ | `ok: true` + `evidence.filesMatch: false` | the files had changed (normally because an update ran) and the recorded version was reinstalled |
79
+ | `409 source-not-replayable` | the snapshot came from a git, tarball or local-path install, so reinstalling it by version would be a different artifact |
80
+ | `409 source-substitution` | the snapshot belongs to a different package name |
81
+ | `409 not-installed` | the package directory cannot be read, so nothing can be fingerprinted |
82
+
83
+ Restore is **version only**. It does not roll back configuration, the dependency tree or agent presets, and it does not restore files that were edited by hand.
84
+
85
+ A restore is a write, so it also leaves a way back: before reinstalling, it snapshots the version it is about to replace (marked `before restore to <version>`) and reads that snapshot back. The reply carries it as `undo`. Without it, restoring would be the one action in this plugin with no return path — the version you were on would be gone the moment it ran. A restore that finds the profile already on the recorded version changes nothing and writes no extra snapshot.
86
+
87
+ ### Skills tab
88
+
89
+ Skills have no version field, so the panel does not invent one. For each Skill the host reports, it shows the source (project `.dsh/skills`, project `.agents/skills`, custom directories, user `.dsh/skills`, user `.agents/skills`, bundled), the file count, and the Git revision when the directory is inside a checkout, along with whether the Skill's own directory has uncommitted changes.
90
+
91
+ **Take a snapshot** copies the Skill directory into the snapshot store, re-reads the copy, and refuses to keep it when the copy does not match the digest of what was read. The snapshot records bytes plus the Git revision the directory happened to be at; it never presents either as a version number.
92
+
93
+ **Restore** puts one Skill directory back to the exact bytes a snapshot recorded. Open a row's snapshot list, preview, and confirm. The preview runs before the confirmation bar, so a refusal is something you read while choosing rather than after committing. A restore is refused when:
94
+
95
+ | reason | meaning |
96
+ | --- | --- |
97
+ | `inside-git-checkout` | the directory is inside a Git working tree; this plugin never rewrites tracked files and never runs `git checkout`, `reset` or `clean` |
98
+ | `system-skill` | the path contains a `.system` segment, which the host does not discover either |
99
+ | `bundled-skill` | the Skill ships with DSH |
100
+ | `snapshot-directory-mismatch` | the snapshot records a different directory, even if the Skill has the same name |
101
+ | `snapshot-copy-corrupt` | the stored copy no longer matches its manifest digest, so it is not a baseline |
102
+ | `snapshot-copy-missing` | the stored copy is gone |
103
+ | `no-directory` | a single-file Skill has no directory to swap |
104
+
105
+ A restore that proceeds keeps a way back: it snapshots the current directory first (marked `before-restore`, shown as an "undo point"), assembles the replacement in a sibling staging directory on the same volume, re-verifies it against the same digest, and only then swaps it in with two renames — parking the old directory rather than deleting it first. Files added after the snapshot are removed: a restore is the recorded tree, not a merge with what is on disk now. The response reports `undo` so the step you just replaced can itself be restored.
106
+
107
+ The `.system` directory and anything outside the host's Skill catalog are never scanned or written. A snapshot or restore request can only name a Skill the host lists — the routes never accept a path, so they cannot be used as a directory copier.
108
+
109
+ > One consequence worth stating plainly: the host's filesystem provider is disabled in a stock profile, so in a default profile the Skills tab lists only bundled Skills unless that provider is enabled. The plugin reports `available: false` with the host's own reason rather than showing an empty list.
110
+
111
+ ### Git-managed Skills
112
+
113
+ A Skill has no version field, so the only honest way to say "which content is this" is the commit it came from. Register a Skill once — name, repository, the exact subpath inside it, and a branch or tag — and the panel can then show what an update would change, move the directory forward, and move it back to any commit already fetched.
114
+
115
+ The plugin never runs a Git command inside your checkout. It keeps its own bare repository at `<DSH_HOME>/version-manager/git-cache/<hash>.git` and does every read there: `fetch` into that cache, `ls-tree` and `cat-file blob` to write files, `diff --name-status` to say what would change. Your branches, index and working tree are not touched, so there is nothing for this feature to corrupt outside the one Skill directory it was pointed at.
116
+
117
+ What an update does, in order: verify the directory still matches the digest recorded at registration, fetch the ref into the cache, diff the trees, snapshot the current directory (reason `before git update to <sha>`), export the tree into a sibling staging directory, re-verify it, swap it in with two renames, then record the new revision and digest. Moving back to an earlier commit is the same path with the revision named explicitly.
118
+
119
+ It refuses, by name, when:
120
+
121
+ | reason | meaning |
122
+ | --- | --- |
123
+ | `local-modifications` | files in the directory no longer match the recorded baseline; the update would silently discard someone's work |
124
+ | `baseline-unknown` | the directory holds files that are not that commit's tree, so no honest baseline can be recorded at registration time |
125
+ | `inside-git-checkout` | the target directory is inside a working tree |
126
+ | `bundled-skill` | the Skill ships with DSH |
127
+ | `system-skill` | the path contains a `.system` segment |
128
+ | `bad-subpath` | the subpath is absolute, contains `..`, or points into `.git` |
129
+ | `unsupported-remote` | the address is not `https`, `ssh`, `git@`, `file://` or an absolute path |
130
+ | `already-registered` | the Skill is already registered to a different source; unregister first, so history cannot become fictional |
131
+ | `revision-not-in-cache` | the requested commit was never fetched; the plugin does not guess or rewrite history |
132
+ | `unsupported-entry` | the commit contains a symlink or a submodule. Writing a symlink as a regular file would change what the Skill means |
133
+
134
+ Registration itself writes one line to a registry file and nothing else — a claim about intent should not be able to destroy content. The first update is what fills the directory, which is also why a freshly registered empty directory reports `populated: false` instead of claiming it is already at that revision.
135
+
136
+ Moving back is allowed in one case where moving forward is not: if you edited the files by hand, an update is refused (`local-modifications`) but a restore still runs, because a restore snapshots the current directory before it writes. Refusing both would leave no way back from the exact situation this feature exists to fix. A restore does still refuse a directory this plugin never populated that now holds files — those belong to something else, and replacing them would delete files the plugin has no record of. The panel reports the two refusals separately (`refusal` and `restoreRefusal`).
137
+
138
+ Sources that are **not** supported, listed rather than implied: any directory this plugin did not create or verify (registration requires an empty directory or an exact match to the named commit), a subpath containing symlinks or submodules, a repository reachable only over a transport Git itself cannot read here, and a Skill whose directory lives inside another Git checkout.
139
+
140
+ ## Verification
141
+
142
+ Three kinds of evidence, kept apart on purpose.
143
+
144
+ **Unit and integration tests.** `npm test` runs 104 tests with no network and no host: spec classification, semver comparison, lockfile parsing, inventory merging, snapshot store, operation journal, Skill restore (including a swap that fails halfway), the Git-managed Skill flow against real throwaway repositories, and the HTTP routes wired against a fake host.
145
+
146
+ **CI.** `.github/workflows/check.yml` runs that suite on Ubuntu, Windows and macOS against Node 22 and 24 — six jobs, no install step, because the package has no dependencies. It also runs `npm pack --dry-run` so a broken `files` list fails the build.
147
+
148
+ **A real host.** The flows below were run against DeepSeek Harness `0.2.2-rc.1` (Electron 44.7.0, Node 24.21.0) on Windows 11, installed from the packed tarball `dsh-version-manager-0.1.0.tgz` into a throwaway `DSH_HOME`. The point of a separate home is that a mistake here cannot touch the profile you work in.
149
+
150
+ What was exercised, and what it produced:
151
+
152
+ | step | observed |
153
+ | --- | --- |
154
+ | fresh profile created by `dsh plugin --profile final add <tarball>` | `dsh: initialized profile final`, `+ dsh-version-manager 0.1.0`, 26 rows rendered |
155
+ | `GET /overview` | `profile=final`, `host=0.2.2-rc.1`, source `@deepseek-ai/dsh-app-boot/package.json` |
156
+ | `POST /snapshot` without `confirm` | `400 {"error":"confirm required"}` |
157
+ | `POST /snapshot` with `confirm` | `200`, snapshot written with `seq: 1` |
158
+ | `POST /update` on a registry plugin | `200`, host reported `1.7.2 → 1.7.3`, snapshot taken first, operation journal reached `succeeded` |
159
+ | `POST /restore` with that snapshot | `200`, `restoredVersion: 1.7.2`, `evidence.filesMatch: false` (the files *had* changed, which is the expected evidence) |
160
+ | `POST /skills/snapshot` | `200`, copy re-read and verified, `fileCount: 2` |
161
+ | Skill restore on a bundled Skill | `409 bundled-skill`, directory unchanged |
162
+ | Git-managed Skill: register, first apply, update A→B, restore A, hand-edit then restore | registered against an empty directory (`populated: false`), first update filled it, an update moved `8569b20 → c3d0909` with `M SKILL.md` / `A extra.md`, a restore put `8569b20` back and removed `extra.md`, a hand-edited file made the update refuse `local-modifications` while the restore still ran and left an undo snapshot holding the edited bytes |
163
+ | the Desktop shell | sidebar entry, panel, both tabs, confirmation bar, operation list and snapshot list all rendered and worked; a snapshot taken by clicking in the UI landed on disk |
164
+
165
+ Two defects found this way and fixed rather than documented away: a nested-but-successful host reply was being classified as a failure, and a bundled Skill could be offered a restore the plugin would refuse everywhere else. A third was cosmetic but worse than cosmetic — one local path was compared in two spellings and reported as a change that never happened. A fourth came out of the Git flow: the panel reported a freshly registered, still-empty directory as "modified, update will be refused" because the empty directory's digest never equals the commit's, while the update path allowed it — the row now reads the same refusal function the update path uses, so the two cannot drift apart again.
166
+
167
+ Not verified: another DSH version, a Linux or macOS Desktop, and a non-bundled Skill provider.
168
+
169
+ ## Honest limits
170
+
171
+ - **A snapshot is not a profile backup.** A version restore reinstalls one package. It does not revert `package.json` ranges, the lockfile, config overlays, or the dependency tree.
172
+ - **Registry host is often unknown.** pnpm's lockfile records a tarball URL only for some packages; when it does not, the panel says the registry is not stored rather than assuming npmjs.
173
+ - **Compatibility uses the package's own declaration.** If a package declares nothing, the panel says so instead of guessing.
174
+ - **Skill writes are one direction per flow.** A snapshot restore replaces a directory with recorded bytes; a Git update moves a registered directory between commits. Neither merges: what is on disk and not in the target tree is removed. A directory the plugin did not register has no baseline, and the plugin will not guess one.
175
+ - **A Skill snapshot is a copy, not a version.** Skills have no version field, so the store keeps bytes and the Git revision separately; it never presents them as a version number.
176
+ - **Git-managed Skills need Git on `PATH`.** The flow shells out to `git` for `fetch`, `ls-tree` and `cat-file`. When Git is missing the panel says `git-not-found` instead of falling back to a filesystem copy.
177
+ - **`skippedBundles` is not visible at runtime.** DSH prints bundles it skipped to stderr at startup; a running plugin cannot read that list, so a bundle that never loaded is reported from the loader's own phases, with `unknown` where the host is silent.
178
+ - **Tested on Windows only** as a real host (0.2.2-rc.1, Electron 44.7.0, Node 24.21.0). Linux and macOS are covered by the unit tests, not by a running Desktop.
179
+
180
+ ## Security
181
+
182
+ - Every route requires a DSH owner session (`connection.admit`); there is no unauthenticated surface.
183
+ - Every write route requires `{"confirm": true}` in the body, so a stray GET or a cross-site form post cannot change anything.
184
+ - The host, not this plugin, writes the profile. Updates go through the host's plugin manager, which owns the manifest lock and its own log.
185
+ - Skill snapshots copy only directories the host catalog lists. No request-supplied path is read, and snapshot file names are rejected when they contain `/`, `\` or `..`.
186
+ - A Skill restore is the only path that writes into a user directory without an explicit commit. It refuses Git checkouts and `.system`, verifies both the stored copy and the staged replacement against one digest, and snapshots what it replaces first.
187
+ - A Git update writes the tree of a commit you named, into a directory you registered. The fetch goes to a bare cache the plugin owns (`<DSH_HOME>/version-manager/git-cache/`); no command runs inside your checkout, and the skills' own Git state is read, never changed. A directory whose files drifted from the recorded baseline is refused rather than overwritten — except by a restore, which is the documented way back and snapshots what it replaces first.
188
+ - Nothing is uploaded. The panel reads only what the host and the local filesystem expose.
189
+
190
+ ## Routes
191
+
192
+ All under `/dsh-version-manager`, same-origin, `Cache-Control: no-store`.
193
+
194
+ | method | path | body | purpose |
195
+ | --- | --- | --- | --- |
196
+ | GET | `/overview` | — | profile, host version, plugin rows, recent operations |
197
+ | GET | `/versions?target=<name>` | — | newer versions, split into stable and prerelease |
198
+ | GET | `/skills` | — | Skill inventory with snapshot counts, a `restoreRefusal` per row, and the Git registry |
199
+ | GET | `/skills/restore-preview?name=&file=` | — | what a restore would do, and every reason it would be refused |
200
+ | GET | `/skills/git` | — | registered Git sources, their pinned revision, local drift, and separate `refusal` / `restoreRefusal` |
201
+ | POST | `/snapshot` | `{targetId, confirm}` | snapshot one plugin |
202
+ | POST | `/update` | `{targetId, toVersion, allowPrerelease?, confirm}` | snapshot, then ask the host to update |
203
+ | POST | `/restore` | `{targetId, snapshotId, confirm}` | reinstall the version a snapshot recorded |
204
+ | POST | `/skills/snapshot` | `{name, confirm}` | snapshot one Skill |
205
+ | POST | `/skills/restore` | `{name, file, confirm}` | replace one Skill directory with the recorded bytes |
206
+ | POST | `/skills/git/register` | `{name, remote, subpath?, ref?, create?, confirm}` | record where a Skill comes from and the commit it currently matches |
207
+ | POST | `/skills/git/remove` | `{name, confirm}` | forget the registration, leaving the directory alone |
208
+ | POST | `/skills/git/preview` | `{name, ref?, confirm}` | fetch into the plugin's cache and report the diff and every refusal |
209
+ | POST | `/skills/git/update` | `{name, ref?, confirm}` | snapshot, then write the tree of the fetched commit |
210
+ | POST | `/skills/git/restore` | `{name, revision, confirm}` | snapshot, then write the tree of a commit already in the cache |
211
+
212
+ Error bodies carry a stable `error` code and, when useful, a `message`. The update and restore flows also return `operationId`, and the operation journal under `<DSH_HOME>/version-manager/operations/<profile>/` records each transition: `planned`, `snapshot_verified`, `applying`, `verifying`, then `succeeded`, `failed`, `cancelled` or `recovery_required`.
213
+
214
+ ## Compatibility
215
+
216
+ | DSH | status |
217
+ | --- | --- |
218
+ | 0.2.2-rc.1 (Windows Desktop shell, Electron 44.7.0) | verified in a real host: sidebar entry, panel, plugin inventory, update, snapshot, restore |
219
+ | other 0.2.x | expected to work; the extension points used (`sidebar.panellist`, `main`, `webServer.register`, `pluginManager`, `skills`) exist across 0.2.x, but they were not exercised against another build |
220
+
221
+ ## Development
222
+
223
+ ```bash
224
+ npm test # node --test, no build step
225
+ ```
226
+
227
+ The panel is a hand-written browser bundle (`lib/client.js`) using the `window.__ModuleLoader__.load` contract, with `react` as its only external. The host half is plain ESM under `lib/host/`.
228
+
229
+ - `docs/baseline.md` — the P0 survey: what this host version actually exposes, what was verified against the running installation, and what could not be verified.
230
+
231
+ ## License
232
+
233
+ MIT. See [LICENSE](./LICENSE).
@@ -0,0 +1,12 @@
1
+ # Loader rows for the version manager.
2
+ #
3
+ # `name` is deliberately a path relative to this file. DSH anchors a relative
4
+ # plugin name to the directory of the patch that declares it, so the row keeps
5
+ # loading this package's own entry after the folder is renamed, and a local
6
+ # checkout and an npm install behave the same way.
7
+ #
8
+ # `id` is what the panel uses to look up its own configuration row; it is not
9
+ # the package name, because one package can be composed into several rows.
10
+ - insert:
11
+ - id: version-manager
12
+ name: ./lib/index.js
@@ -0,0 +1,224 @@
1
+ # P0 baseline — DSH Version Manager
2
+
3
+ Recorded: 2026-11-06 (Asia/Shanghai). Every claim below was read off this machine
4
+ during that session; anything not observed is listed under "Unknown" instead of
5
+ being filled in.
6
+
7
+ ## 1. What is actually installed
8
+
9
+ | Fact | Value | Evidence |
10
+ | --- | --- | --- |
11
+ | Running host | DSH Desktop `0.2.2-rc.1` | `D:\DeepSeek Harness\resources\app.asar` → `dsh/package.json` = `@deepseek-ai/dsh-desktop-runtime@0.2.2-rc.1` |
12
+ | CLI version | `0.2.2-rc.1` | `dsh --version` |
13
+ | Electron | `44.7.0` | `D:\DeepSeek Harness\version` |
14
+ | Node (bundled) | `24.21.0` | `runtime/versions.json` |
15
+ | pnpm (bundled) | `11.28.5` | `runtime/versions.json` |
16
+ | Node (host shell) | `26.9.0` | `node -v` |
17
+ | OS | Windows 11 10.0.26300 | `[System.Environment]::OSVersion` |
18
+
19
+ The real user profile is `C:\Users\tangy\.dsh\profiles\desktop`
20
+ (`package.json` = `dsh-profile-desktop`, 35 dependencies, 47 bundles). It was
21
+ read only; nothing in it was modified while producing this document.
22
+
23
+ Do **not** treat `C:\Users\tangy\.dsh\profiles\node_modules\@deepseek-ai\dsh`
24
+ (`0.1.6-alpha.2`, mtime 2026-09-21) or the source checkout at
25
+ `D:\deepseek-harness` (`@deepseek-ai/dsh-root@0.1.6-alpha.2`, HEAD `ddefc45f`)
26
+ as the running version. Both are stale leftovers; the app.asar is the host that
27
+ is running.
28
+
29
+ ## 2. Official interfaces this plugin is allowed to use
30
+
31
+ All of these live in `D:\DeepSeek Harness\resources\app.asar\dsh\node_modules\@deepseek-ai\`.
32
+
33
+ ### 2.1 `pluginManager` — the inventory and update authority
34
+
35
+ `dsh-plugin-manager/lib/index.js` declares a Cordis service:
36
+
37
+ ```js
38
+ static inject = ['loader', 'profileContext']
39
+ constructor(...) { super(ctx, 'pluginManager') }
40
+ ```
41
+
42
+ Every capability is a method on that service, so a host plugin reaches it with
43
+ `ctx.get('pluginManager')` and needs no `@Remote` wiring of its own.
44
+
45
+ - `listBundles()` — the inventory. Each row carries `name`, `official`,
46
+ `availability` (`profile` | `installation` | `missing`), `source` (the declared
47
+ spec), `enabled`, `installed`, `version`, `error`, `updatable`,
48
+ `readOnlyReason`. `enabled` means *the user saved that choice*, not *it loaded*;
49
+ a load failure appears in `error`. `updatable` is computed by
50
+ `updateRefusal(bundle, name) === undefined`.
51
+ - `updateRefusal(bundle, name)` is the real gate for "may this be updated":
52
+ only a third-party bundle, installed in the profile, whose declared spec is a
53
+ plain registry spec under its own name, with a semver version, is updatable.
54
+ A `git`/`file:`/`link:`/tarball spec, an `npm:` alias, an official bundle, or a
55
+ row the profile does not own returns a human-readable refusal string instead.
56
+ - `listVersions(name, { registry }, signal)` returns only versions *newer* than
57
+ the installed one, newest first, each annotated with `deprecated`,
58
+ `bundle` (does the manifest declare `dsh.bundle`) and `compatibility`.
59
+ - `updateBundle(name, version, options)` refuses an invalid or non-newer
60
+ version, re-checks compatibility, and then removes + installs. It saves the
61
+ target as an **exact** version. With HMR present it is remove-then-install;
62
+ without HMR it installs over the top and reports `restart-required`.
63
+ - `inspect(spec, options, signal)`, `readBundleDetail(...)`,
64
+ `registries()`, `listVersionExemptions()`, `installBundle(...)`,
65
+ `removeBundle(...)`, `setBundleEnabled(...)`, `waitForInstall(...)`,
66
+ `cancelInstall(...)`.
67
+
68
+ Documented limitations that matter to a version manager, straight from the
69
+ package README:
70
+
71
+ - An update is **two** profile operations (remove, then install). Another
72
+ operation can run in between.
73
+ - An update saves the target as an exact version, and a failed update restores
74
+ the previous version exactly — even if the profile had saved a range.
75
+ - With HMR, the reinstalled bundle joins the **end** of the selection, which can
76
+ change which bundle's configuration wins.
77
+ - A new version that needs a build-script approval fails and rolls back.
78
+ - A failure can leave `node_modules` / the pnpm store in a partial state; logs
79
+ are under `.plugin-manager/logs`.
80
+
81
+ ### 2.2 Compatibility and exemptions
82
+
83
+ `dsh-app-boot/lib/index.js`:
84
+
85
+ ```js
86
+ function getDshRuntimeVersion() // reads dsh-app-boot's own package.json version
87
+ function evaluatePluginCompatibility(manifest, exemptions = {}, runtimeVersion = getDshRuntimeVersion())
88
+ ```
89
+
90
+ `unmetRequirements` checks `engines.dsh` **when present and only then**;
91
+ otherwise it walks `peerDependencies` for `@deepseek-ai/dsh` and
92
+ `@deepseek-ai/dsh-*`. Ranges are evaluated with `{ includePrerelease: true }`.
93
+ Exemptions live in the profile root as `compatibility.json`, shaped
94
+ `{"<pkg>@<exactVersion>": ["<dshVersion>"]}`, and are managed through
95
+ `dsh plugin --profile <p> allow-version|revoke-version|version-exemptions`.
96
+
97
+ `reportSkippedBundles(binName, profile)` writes skipped bundles to **stderr at
98
+ startup only**. There is no runtime API for "which bundles were skipped", so a
99
+ version manager must report compatibility from the manifest and from
100
+ `pluginManager`'s own rows, and must not pretend to know the startup skip list.
101
+
102
+ ### 2.3 `loader` — phases
103
+
104
+ `dsh-host-plugin-inventory/lib/index.js` shows the supported pattern: iterate
105
+ `ctx.loader.entries()`, skip `options.group`, map the fiber state to
106
+ `pending|loading|active|failed|unloading|null`, and read the diagnostic after
107
+ `await fiber.await()` when the phase is `failed`. That is a read-only view and it
108
+ is the honest source for "installed but did not load".
109
+
110
+ ### 2.4 HTTP surface for the panel
111
+
112
+ `dsh-host-webserver` `register(route)`:
113
+
114
+ - `kind: 'exact' | 'prefix'`, plus `handler(req, res)` or
115
+ `resource(request, peer) => Response` for GET/HEAD only.
116
+ - Registering the same path twice **throws**, so a route name must be namespaced.
117
+ - There is **no server-wide authentication or origin policy**; the route owner
118
+ must enforce its own policy.
119
+
120
+ `dsh-client-connection` provides the supported policy check:
121
+
122
+ ```js
123
+ const admission = ctx.get('connection')?.admit(req)
124
+ // { rejection: 401 | 403 } outside the browser, or { peer: { principal } }
125
+ ```
126
+
127
+ A third-party plugin has no route into `api-remotes` (that list is a build-time
128
+ capability set), so the panel talks to its own host routes over same-origin
129
+ `fetch`. This is exactly how `dsh-update-checker` and `dsh-wsl-tool` work.
130
+
131
+ ### 2.5 Client extension points that exist in 0.2.2-rc.1
132
+
133
+ - `sidebar.panellist` — list slot, scope root. A row provides `id`, `order` and a
134
+ `label`; the entry component draws only the icon. The sidebar itself renders
135
+ the tooltip, the `aria-label`, `aria-current` and keyboard handling.
136
+ - `main` — keyed slot, scope root. `renderSlot('main', {}, { entryKey: panelId })`,
137
+ so the same `id` used in `sidebar.panellist` selects the panel.
138
+ - `settings.section` — a settings page; also usable when a full panel is too
139
+ much.
140
+ - The client bundle is a CommonJS factory registered through
141
+ `window.__ModuleLoader__.load({ id, factory: (require) => {...} })` and must
142
+ export `apply` and `inject`.
143
+ - `require` inside that factory is limited to the front-end's static table:
144
+ `react`, `react/jsx-runtime`, `react-dom`, `react-dom/client`,
145
+ `@deepseek-ai/cordis`, `zod`, `@tanstack/react-virtual`,
146
+ `@deepseek-ai/dsh-client-store`, `@deepseek-ai/dsh-client-ui-slots`,
147
+ `@deepseek-ai/dsh-client-ui-primitives`, `@deepseek-ai/dsh-client-ui-dockkit`.
148
+ `dsh.client.external` can only add another plugin's package row or an exact key
149
+ from that table.
150
+
151
+ ### 2.6 Skills
152
+
153
+ `dsh-skill-filesystem` scans, in priority order:
154
+
155
+ | Priority | Root |
156
+ | --- | --- |
157
+ | 100 | `<projectRoot>/.dsh/skills` |
158
+ | 200 | `<projectRoot>/.agents/skills` |
159
+ | 300 | each `customSkillDirs` entry |
160
+ | 400 | `<dshHome>/skills` (`.system` skipped) |
161
+ | 500 | `<agentsHome>/skills` |
162
+ | 600 | `bundledSkillDir` |
163
+
164
+ A skill is `<root>/<name>/SKILL.md` or `<root>/<name>.md`, one level deep, with
165
+ `name` (kebab-case) and `description` required in the front matter. The provider
166
+ watches depth 1 and invalidates on `SKILL.md` create/change/delete; changes to a
167
+ skill's supporting files are **not** watched. There is no version field in the
168
+ format and the body is re-read on every load, so a skill's "version" can only be
169
+ established from the directory it came from and a content fingerprint.
170
+
171
+ ## 3. Comparable plugins, checked rather than assumed
172
+
173
+ | Plugin | Version / licence | What it actually does | Where this one differs |
174
+ | --- | --- | --- | --- |
175
+ | `dsh-update-checker` (Airmetro) | `1.7.3`, MIT | Checks host + third-party plugin updates, backs up the deployment, updates, rolls back, restarts a watchdog. Writes `package.json` + lockfile. Routes require `confirm: true` **and** a loopback source. | It owns the whole update-and-restart lifecycle. This plugin deliberately does not restart anything and does not update the host; it documents the profile state before and after and keeps a snapshot that can be verified. |
176
+ | `@michengai/dsh-skills-manager` (MichengAI) | `1.2.35`, Apache-2.0 | Reads 20+ agent skill roots, groups by source repository, fetches skill directories from GitHub on demand, previews a diff before overwriting, keeps history to restore a previous version, has a trash. | It treats a skill directory as the unit and fetches whole directories. This plugin only accepts a skill whose managed Git source and exact sub-path the user named, requires an unchanged local fingerprint, and swaps in a verified copy. |
177
+ | DSH built-in plugin manager | ships with `0.2.2-rc.1` | Install / remove / enable / disable / inspect / list newer versions. Its own README states the page has **no version picker**: changing a version means removing and reinstalling. | This plugin's reason to exist: a per-target version view, an update preview, and a snapshot taken before the change. |
178
+
179
+ The built-in manager already refuses unsafe updates and already reports
180
+ compatibility, so this plugin does not re-implement those rules; it presents them
181
+ and adds the parts the host does not offer.
182
+
183
+ ## 4. Chosen approach
184
+
185
+ - **Host half** (`lib/index.js`) exposes read-only JSON routes under
186
+ `/dsh-version-manager/`. Every route is admitted through
187
+ `ctx.get('connection').admit(req)`; a write route additionally demands
188
+ `confirm: true` in the body and refuses anything that is not a same-request
189
+ explicit action. No background timers, no polling, no automatic installs.
190
+ - **Sources** classify each target from its declared spec: `registry`, `git`,
191
+ `file`/`link`, `tarball`, `builtin`. Only `registry` under the bundle's own name
192
+ is offered an update, and only for a stable release unless the user turns on
193
+ prereleases.
194
+ - **Inventory** merges `pluginManager.listBundles()` with loader phases, so
195
+ "installed", "enabled", "loaded" and "failed" stay four distinct facts.
196
+ - **Snapshot store** writes one JSON document per take under
197
+ `<dshHome>/version-manager/snapshots/<profileId>/`, atomically via a temp file
198
+ in the same directory plus rename, never overwriting an existing snapshot, and
199
+ keeping the newest 20 per target. It records the profile identity, the package
200
+ identity, the declared spec, the installed version, the source, the enabled
201
+ state, a content fingerprint and non-secret metadata. It records no tokens,
202
+ no credentials and no environment variables.
203
+ - **Recovery** is only offered when the snapshot's fingerprint still matches what
204
+ is installed and the recorded spec is one the host can replay. Otherwise the
205
+ row says `recovery_required` and explains why. Restoring a version is never
206
+ described as rolling back configuration, a dependency tree, or an agent preset.
207
+ - **Skills** are read-only in the first release: source identification, the
208
+ installed fingerprint, and a preview of what a named Git source would change.
209
+ The write path is limited to a user-named managed Git source + exact skill
210
+ sub-path + unchanged local fingerprint, uses an isolated staging directory, and
211
+ never runs `reset --hard`, `clean`, or a forced checkout.
212
+
213
+ ## 5. Unknown, and therefore not claimed
214
+
215
+ - Whether the startup skip list can be observed at runtime at all — the only
216
+ evidence of it is a stderr line written before plugins load. Reported as
217
+ unknown rather than inferred from compatibility alone.
218
+ - macOS and Linux behaviour: no machine was available, so those runs are
219
+ automated tests only.
220
+ - The exact npm registry a bundle was installed from is not stored by the host.
221
+ When it cannot be recovered, the record says so instead of guessing.
222
+ - Whether a snapshot can restore a bundle whose update also changed its
223
+ dependency tree: it cannot be verified without a full lockfile copy, which is
224
+ out of scope, and the UI says so.