dsh-version-manager 0.1.3 → 0.1.5

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.
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#161d2b" stroke="#34425b"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">1</text><text x="18" y="76" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">Real installed inventory</text><text x="18" y="105" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">Declared specs, disk versions and load state</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#f5f8ff" stroke="#dce5f4"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">1</text><text x="18" y="76" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">Real installed inventory</text><text x="18" y="105" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">Declared specs, disk versions and load state</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#161d2b" stroke="#34425b"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">1</text><text x="18" y="76" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">真实安装清单</text><text x="18" y="105" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">声明、磁盘版本与加载状态分开</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#f5f8ff" stroke="#dce5f4"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">1</text><text x="18" y="76" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">真实安装清单</text><text x="18" y="105" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">声明、磁盘版本与加载状态分开</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#161d2b" stroke="#34425b"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">2</text><text x="18" y="76" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">Snapshot before update</text><text x="18" y="105" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">Write and read back SHA-256 evidence</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#f5f8ff" stroke="#dce5f4"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">2</text><text x="18" y="76" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">Snapshot before update</text><text x="18" y="105" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">Write and read back SHA-256 evidence</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#161d2b" stroke="#34425b"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">2</text><text x="18" y="76" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">更新前快照</text><text x="18" y="105" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">保存并回读 SHA-256 证据</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#f5f8ff" stroke="#dce5f4"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">2</text><text x="18" y="76" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">更新前快照</text><text x="18" y="105" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">保存并回读 SHA-256 证据</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#161d2b" stroke="#34425b"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">3</text><text x="18" y="76" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">Explicit restore limits</text><text x="18" y="105" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">Known state and a usable recovery path</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#f5f8ff" stroke="#dce5f4"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">3</text><text x="18" y="76" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">Explicit restore limits</text><text x="18" y="105" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">Known state and a usable recovery path</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#161d2b" stroke="#34425b"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">3</text><text x="18" y="76" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">明确恢复边界</text><text x="18" y="105" fill="#eef3ff" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">保留原状态与可用返回路径</text></svg>
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="280" height="132" viewBox="0 0 280 132"><rect x="1" y="1" width="278" height="130" rx="14" fill="#f5f8ff" stroke="#dce5f4"/><rect x="18" y="18" width="28" height="28" rx="7" fill="#4771c8"/><text x="32" y="38" text-anchor="middle" fill="white" font-family="system-ui,sans-serif" font-size="15">3</text><text x="18" y="76" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="17" font-weight="600">明确恢复边界</text><text x="18" y="105" fill="#182a4b" font-family="system-ui,'Microsoft YaHei',sans-serif" font-size="11">保留原状态与可用返回路径</text></svg>
@@ -0,0 +1,22 @@
1
+ # Git skill write safety
2
+
3
+ Git updates require the full commit ID returned by `/skills/git/preview` as
4
+ `expectedRevision`. The bundled client also sends `expectedFromRevision` and
5
+ `expectedDigest` from that preview. A moved branch or changed registration/local
6
+ tree returns `preview-changed`; preview again before confirming. Requests that
7
+ omit the full preview commit return `missing-preview-revision`.
8
+
9
+ Exports validate every entry before writing the first file. Windows separators,
10
+ drive/alternate-stream syntax, device names, dot/space aliases, `.git` names and
11
+ portable case collisions are refused. Gitlinks and symbolic links are refused
12
+ instead of silently approximated or omitted.
13
+
14
+ Git registry edits, Git skill swaps and snapshot restores use the same exclusive
15
+ filesystem lock at `version-manager/git-skills/.write.lock` under the selected
16
+ DSH home. It covers separate host processes and profiles. Concurrent requests
17
+ return `operation-in-progress`. Git cache fetches have separate exclusive locks
18
+ so they cannot race on `FETCH_HEAD`.
19
+
20
+ A crashed owner can leave a lock behind. Locks are never stolen automatically:
21
+ inspect the recorded PID, confirm that no owner is still running, and only then
22
+ remove the stale lock. Refusal is safer than allowing a second writer to race.
@@ -0,0 +1,362 @@
1
+ # Detailed usage and technical guide
2
+
3
+ Run commands from the repository root. Return to the [README](../README.md).
4
+
5
+ <p><img src="../assets/logo.webp" width="96" height="96" alt="dsh-version-manager logo"></p>
6
+
7
+ # dsh-version-manager
8
+
9
+ Version management for DSH plugins and Skills, inside DeepSeek Harness.
10
+
11
+ It answers four questions about the profile you are actually running:
12
+
13
+ 1. **What is installed right now** — declared spec, installed version, where it came from, whether it loaded, whether it is compatible with this host.
14
+ 2. **What an update would change** — the exact versions offered, with prereleases kept apart and deprecations shown.
15
+ 3. **What the state was before the change** — a snapshot with a file fingerprint, written before the host is asked to do anything.
16
+ 4. **Whether it can be undone** — and when it cannot, the specific reason instead of a retry button.
17
+
18
+ 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.
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ dsh plugin --profile <your-profile> add dsh-version-manager@<version>
24
+ ```
25
+
26
+ From a local tarball:
27
+
28
+ ```bash
29
+ npm pack
30
+ dsh plugin --profile <your-profile> add /absolute/path/dsh-version-manager-<version>.tgz
31
+ ```
32
+
33
+ Then restart the host and open the panel from the left sidebar.
34
+
35
+ 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.
36
+
37
+ Verify the bundle was installed from the tarball rather than from a stray checkout:
38
+
39
+ ```bash
40
+ node -e "console.log(require('fs').readFileSync('<profile>/node_modules/dsh-version-manager/package.json','utf8'))"
41
+ ```
42
+
43
+ ## What it does
44
+
45
+ ### Plugins tab
46
+
47
+ One row per entry the host reports, with the fields the host actually provides:
48
+
49
+ | column | meaning |
50
+ | --- | --- |
51
+ | package | the entry name the loader knows |
52
+ | installed version | the version on disk, or `未知` when the host does not know it |
53
+ | source | the declared spec, classified: registry, git, tarball, local path, alias, built into this profile, or unknown |
54
+ | load state | the loader phase: active, pending, loading, failed, unloading |
55
+ | compatibility | whether the package's own DSH version requirement is satisfied by this host |
56
+ | actions | check updates, take a snapshot |
57
+
58
+ Three states are kept apart on purpose, because collapsing them produces false confidence:
59
+
60
+ - **satisfied** — the package declares a DSH requirement and this host meets it.
61
+ - **no requirement declared** — the package declares nothing. This is not a pass; it is the absence of a claim, shown with a neutral dot.
62
+ - **unknown** — the requirement exists but could not be evaluated (for example the running version is unreadable), or the installed manifest was not read.
63
+
64
+ **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.
65
+
66
+ The summary line above the table counts entries the host would let this plugin write (**writable** or 可写入), not entries that have a newer version. Those are different questions: only a per-target version check can answer the second one, and the panel does not pretend to know it in advance. A writable row with nothing newer available is the normal case, not a contradiction.
67
+
68
+ **Update** always shows the from → to pair plus the four side effects before it runs:
69
+
70
+ - a snapshot is written first and read back before anything else happens;
71
+ - the host saves the target as an *exact* version, so a declared range is replaced;
72
+ - configuration, the dependency tree and agent presets are **not** rolled back;
73
+ - the host is not restarted.
74
+
75
+ ### Snapshots and restore
76
+
77
+ 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.
78
+
79
+ 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 kept at 20 per target. Anything older than that stays restorable and is labelled as past retention rather than deleted for you; see [Retention](#retention-is-visible-and-nothing-is-deleted-for-you).
80
+
81
+ Restore is offered only when it can actually work, and only reports what happened:
82
+
83
+ | reply | meaning |
84
+ | --- | --- |
85
+ | `alreadyAtVersion: true` | the profile already carries that version; nothing was reinstalled |
86
+ | `ok: true` + `evidence.filesMatch: false` | the files had changed (normally because an update ran) and the recorded version was reinstalled |
87
+ | `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 |
88
+ | `409 source-substitution` | the snapshot belongs to a different package name |
89
+ | `409 not-installed` | the package directory cannot be read, so nothing can be fingerprinted |
90
+
91
+ 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.
92
+
93
+ 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.
94
+
95
+ ### Skills tab
96
+
97
+ 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.
98
+
99
+ **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.
100
+
101
+ **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:
102
+
103
+ | reason | meaning |
104
+ | --- | --- |
105
+ | `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` |
106
+ | `system-skill` | the path contains a `.system` segment, which the host does not discover either |
107
+ | `bundled-skill` | the Skill ships with DSH |
108
+ | `snapshot-directory-mismatch` | the snapshot records a different directory, even if the Skill has the same name |
109
+ | `snapshot-copy-corrupt` | the stored copy no longer matches its manifest digest, so it is not a baseline |
110
+ | `snapshot-copy-missing` | the stored copy is gone |
111
+ | `no-directory` | a single-file Skill has no directory to swap |
112
+
113
+ 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.
114
+
115
+ 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.
116
+
117
+ > 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.
118
+
119
+ ### Git-managed Skills
120
+
121
+ 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.
122
+
123
+ 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.
124
+
125
+ 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.
126
+
127
+ It refuses, by name, when:
128
+
129
+ | reason | meaning |
130
+ | --- | --- |
131
+ | `local-modifications` | files in the directory no longer match the recorded baseline; the update would silently discard someone's work |
132
+ | `baseline-unknown` | the directory holds files that are not that commit's tree, so no honest baseline can be recorded at registration time |
133
+ | `inside-git-checkout` | the target directory is inside a working tree |
134
+ | `bundled-skill` | the Skill ships with DSH |
135
+ | `system-skill` | the path contains a `.system` segment |
136
+ | `bad-subpath` | the subpath is absolute, contains `..`, or points into `.git` |
137
+ | `unsupported-remote` | the address is not `https`, `ssh`, `git@`, `file://` or an absolute path |
138
+ | `already-registered` | the Skill is already registered to a different source; unregister first, so history cannot become fictional |
139
+ | `revision-not-in-cache` | the requested commit was never fetched; the plugin does not guess or rewrite history |
140
+ | `unsupported-entry` | the commit contains a symlink or a submodule. Writing a symlink as a regular file would change what the Skill means |
141
+
142
+ 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.
143
+
144
+ 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`).
145
+
146
+ 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.
147
+
148
+ ## Verification
149
+
150
+ Three kinds of evidence, kept apart on purpose.
151
+
152
+ **Unit and integration tests.** `npm test` runs 141 tests with no network and no host: spec classification, semver comparison, lockfile parsing, inventory merging, snapshot store, snapshot retention and pruning, operation journal, path-segment encoding, host location, 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.
153
+
154
+ **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.
155
+
156
+ **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 into a throwaway `DSH_HOME`. The point of a separate home is that a mistake here cannot touch the profile you work in.
157
+
158
+ What was exercised, and what it produced:
159
+
160
+ | step | observed |
161
+ | --- | --- |
162
+ | fresh profile created by `dsh plugin --profile final add <tarball>` | `dsh: initialized profile final`, the packaged version reported by the host, 26 rows rendered |
163
+ | `GET /overview` | `profile=final`, `host=0.2.2-rc.1`, source `@deepseek-ai/dsh-app-boot/package.json` |
164
+ | `POST /snapshot` without `confirm` | `400 {"error":"confirm required"}` |
165
+ | `POST /snapshot` with `confirm` | `200`, snapshot written with `seq: 1` |
166
+ | `POST /update` on a registry plugin | `200`, host reported `1.7.2 → 1.7.3`, snapshot taken first, operation journal reached `succeeded` |
167
+ | `POST /restore` with that snapshot | `200`, `restoredVersion: 1.7.2`, `evidence.filesMatch: false` (the files *had* changed, which is the expected evidence) |
168
+ | `POST /skills/snapshot` | `200`, copy re-read and verified, `fileCount: 2` |
169
+ | Skill restore on a bundled Skill | `409 bundled-skill`, directory unchanged |
170
+ | 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 |
171
+ | retention, driven from the panel of the **published** 0.1.2 | three snapshots past the limit made the row read `23 份快照,其中 3 份超出每个目标保留的 20 份。超出的不会自动删除,仍然可以恢复。` with three `超出保留数` badges and a `删除超出的快照` button; the confirmation named the target and the count; after confirming, the panel said `已删除 3 份超出保留数的快照,现在剩 20 份。`, `/overview` reported `{stored: 20, beyondLimit: 0}`, and exactly three files were gone from disk (oldest remaining `0006-…`) |
172
+ | lifecycle: install, disable, uninstall, reinstall | disabling needed `- id: version-manager` / `disabled: true` in the profile's `cordis.patch.yml` (the CLI has no enable/disable); after uninstall the sidebar entry was gone and the snapshot store was untouched; reinstalling brought back every snapshot and operation |
173
+ | 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 |
174
+
175
+ 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. A fifth was found by installing the published package: the panel said "2 updatable" for two rows that had no newer version at all, because the number was counting rows the host would accept a write for. The field and its labels now say **writable** — what is actually measured. A sixth came from asking which modules had no test at all: `operations.js` and `locate.js` had none, and writing the first test for the journal found that `encodeSegment('..')` returned `..`, so `path.join(root, '..')` climbed out of the plugin's own store. Four modules each had their own copy of that encoder. They now share one, which treats a name made only of dots as dots-that-are-not-a-path. The ordinary names are untouched — a test pins `desktop` → `desktop` and `team/blue` → `team%2Fblue`, because a stricter encoding would silently move every snapshot already on disk.
176
+
177
+ Not verified: another DSH version, a Linux or macOS Desktop, and a non-bundled Skill provider.
178
+
179
+ ### Keyboard and accessibility
180
+
181
+ Audited against the P4 checklist. Four defects were real, not hypothetical, and the fix lives entirely in `lib/client.js`:
182
+
183
+ | defect | effect | fix |
184
+ | --- | --- | --- |
185
+ | the strip had `role="tablist"` and `role="tab"` but no keyboard behaviour | both tabs sat in the tab order and the arrow keys did nothing — a tablist is one stop, not two | roving `tabindex`, ArrowLeft/ArrowRight with wraparound, Home and End; focus follows the selection |
186
+ | `aria-controls` pointed at an element that did not exist | there was no `role="tabpanel"` at all | one stable `#vm-panel` with `role="tabpanel"` whose `aria-labelledby` follows the selected tab, so every tab's `aria-controls` resolves |
187
+ | every row rendered the same two button names | dozens of identically named buttons in the accessibility tree — "check versions" says nothing about *which* package | per-row accessible names, e.g. `check versions: @deepseek-ai/dsh-base` |
188
+ | two different buttons were both "refresh" | the plugin list and the Skill catalog were indistinguishable | the Skill one is named in its `aria-label`; the visible word is unchanged |
189
+
190
+ The row expander also stopped being announced as a triangle (`▸ dsh-update-checker`): it now reads `show details: <package>` / `hide details: <package>`, alongside the `aria-expanded` it already had.
191
+
192
+ Measured on the real host in an isolated `DSH_HOME` (Desktop 0.2.2-rc.1) over CDP with real `Input.dispatchKeyEvent` events rather than synthetic `dispatchEvent` calls: one tablist stop instead of two; ArrowRight moves focus and `aria-selected` together and the panel label follows; ArrowRight again wraps; End and Home jump; Enter and Space open and close the expander with the name flipping; the focus ring is present (`outline: auto 2px`, `:focus-visible` matches) because nothing in the bundle removes it; and this plugin contributes no unnamed and no duplicate-named controls (the only repeated name on the page belongs to the host).
193
+
194
+ Not claimed: no screen-reader session (NVDA or Narrator) was run — the statements above are about the accessibility tree and keyboard behaviour as measured through CDP, not about how a particular screen reader voices them. Windows only. Contrast was not measured; the panel adds no text colours of its own beyond the status dots and badges.
195
+
196
+ ## Honest limits
197
+
198
+ - **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.
199
+ - **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.
200
+ - **Compatibility uses the package's own declaration.** If a package declares nothing, the panel says so instead of guessing.
201
+ - **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.
202
+ - **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.
203
+ - **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.
204
+ - **`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.
205
+ - **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.
206
+
207
+ ## Security
208
+
209
+ - Every route requires a DSH owner session (`connection.admit`); there is no unauthenticated surface.
210
+ - Every write route requires `{"confirm": true}` in the body, so a stray GET or a cross-site form post cannot change anything.
211
+ - 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.
212
+ - 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 `..`.
213
+ - 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.
214
+ - 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.
215
+ - Nothing is uploaded. The panel reads only what the host and the local filesystem expose.
216
+
217
+ ## Routes
218
+
219
+ All under `/dsh-version-manager`, same-origin, `Cache-Control: no-store`.
220
+
221
+ | method | path | body | purpose |
222
+ | --- | --- | --- | --- |
223
+ | GET | `/overview` | — | profile, host version, plugin rows, recent operations |
224
+ | GET | `/versions?target=<name>` | — | newer versions, split into stable and prerelease |
225
+ | GET | `/skills` | — | Skill inventory with snapshot counts, a `restoreRefusal` per row, and the Git registry |
226
+ | GET | `/skills/restore-preview?name=&file=` | — | what a restore would do, and every reason it would be refused |
227
+ | GET | `/skills/git` | — | registered Git sources, their pinned revision, local drift, and separate `refusal` / `restoreRefusal` |
228
+ | POST | `/snapshot` | `{targetId, confirm}` | snapshot one plugin |
229
+ | POST | `/snapshots/prune` | `{targetId, confirm}` | delete the snapshots past the per-target limit, listing every file removed |
230
+ | POST | `/update` | `{targetId, toVersion, allowPrerelease?, confirm}` | snapshot, then ask the host to update |
231
+ | POST | `/restore` | `{targetId, snapshotId, confirm}` | reinstall the version a snapshot recorded |
232
+ | POST | `/skills/snapshot` | `{name, confirm}` | snapshot one Skill |
233
+ | POST | `/skills/restore` | `{name, file, confirm}` | replace one Skill directory with the recorded bytes |
234
+ | POST | `/skills/git/register` | `{name, remote, subpath?, ref?, create?, confirm}` | record where a Skill comes from and the commit it currently matches |
235
+ | POST | `/skills/git/remove` | `{name, confirm}` | forget the registration, leaving the directory alone |
236
+ | POST | `/skills/git/preview` | `{name, ref?, confirm}` | fetch into the plugin's cache and report the diff and every refusal |
237
+ | POST | `/skills/git/update` | `{name, ref?, expectedRevision, expectedFromRevision?, expectedDigest?, confirm}` | apply only the previewed commit; changed previews are refused |
238
+ | POST | `/skills/git/restore` | `{name, revision, confirm}` | snapshot, then write the tree of a commit already in the cache |
239
+
240
+ 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`.
241
+
242
+ ## Performance and cache policy
243
+
244
+ Measured in a real Windows Desktop host (0.2.2-rc.1, Electron 44.7.0, Node 24.21.0) against a
245
+ profile with 26 plugin rows, 11 stored snapshots and 8 visible Skills. Timings are
246
+ `fetch()` round trips taken inside the panel's page, so they include the host's own
247
+ serialization:
248
+
249
+ | call | cold | warm |
250
+ | --- | --- | --- |
251
+ | `GET /overview` | 161 ms | 134 ms |
252
+ | `GET /skills` | 426 ms | 313 ms |
253
+
254
+ There is nothing slower here by design. What costs time, and why:
255
+
256
+ - **`/overview` reads the filesystem per row.** For each package it reads the installed
257
+ manifest, the profile manifest, the lockfile entry and the stored snapshot list. That is
258
+ why it is one call and not one call per row: the panel refreshes everything at once.
259
+ - **`/skills` is the slower one** because the host's skill catalog is scanned by the host
260
+ itself; the plugin only aggregates what the host already enumerated.
261
+ - **No caching of version lists anywhere.** `/versions?target=…` asks the registry through
262
+ the host every time it is pressed. A cached answer would be indistinguishable from a
263
+ fresh one in the panel, which is exactly the failure this plugin exists to avoid.
264
+ - **The only on-disk caches** are the snapshot store
265
+ (`<DSH_HOME>/version-manager/snapshots/<profile>/<pkg>/`) and, for Git-managed Skills, a
266
+ bare repository per remote (`<DSH_HOME>/version-manager/git-cache/<hash>.git`). Both are
267
+ yours to delete when the plugin is not running; the plugin recreates what it needs.
268
+
269
+ ### Retention is visible, and nothing is deleted for you
270
+
271
+ Every target keeps its snapshots. The panel states the numbers: how many exist, how many
272
+ are past the 20-per-target limit, and which ones. Rows past the limit are labelled
273
+ **超出保留数 / past retention** in the list.
274
+
275
+ They are **not** removed automatically. A version manager that silently deletes the way
276
+ back is worse than one that keeps too much, so removal is one explicit action with its own
277
+ confirmation, which states how many files it will delete before it does it:
278
+
279
+ ```
280
+ POST /snapshots/prune { targetId, confirm: true }
281
+ ```
282
+
283
+ The response lists every removed file, every file it failed to remove, and how many remain.
284
+ A snapshot still in the list can still be restored.
285
+
286
+ ## Troubleshooting
287
+
288
+ | symptom | what it means | what to do |
289
+ | --- | --- | --- |
290
+ | Sidebar has no **Version Manager** entry | the plugin did not activate | `dsh --profile <p> --no-open` prints the entries that did not activate; a fresh profile usually reports `pending (waiting for service: webServer)` — see [Install](#install) |
291
+ | Panel opens but every row says `unknown` compatibility | the installed manifest could not be read for those packages | the row's `加载状态` detail names the reason; `unknown` is deliberately not rendered as a pass |
292
+ | `registry 未知` on a package | pnpm's lockfile stored no tarball URL for it | nothing is broken; a version check still works, but this plugin will not guess which registry host to record |
293
+ | A row is read-only and offers no update | the host itself keeps that entry read-only (official bundles, or an `install` source the plugin must not rewrite) | the row shows the host's own reason; updates to those entries are not attempted |
294
+ | Update answers `not-updatable` | the row was writable at render time but not when the request arrived | press refresh; if it stays read-only, the host changed its mind and the panel is telling you |
295
+ | Update answers `already-installed` | the host reached the target without changing anything | this is reported as a failure on purpose: nothing was applied, so nothing is claimed as applied |
296
+ | Restore answers `409` | a precondition failed | the body's `error` is a stable code (`source-not-replayable`, `not-installed`, `snapshot-incomplete`, …) and `evidence` shows what was compared |
297
+ | `evidence.filesMatch: false` after a restore | the files on disk differ from the snapshot's recorded fingerprint | expected when the package's files change between versions; it is evidence, not a veto |
298
+ | Skill tab says the skills service is unavailable | the host exposes no skill provider in that process | the panel prints the host's own reason; the Git-managed section still works, because it does not need the catalog |
299
+ | Only bundled Skills are listed | `skill-filesystem` is `disabled: true` in a stock profile | enable that provider in the profile to see your own Skill directories |
300
+ | `git-not-found` | Git is not on `PATH` for the host process | install Git; the Git Skill flow refuses rather than copying files without it |
301
+ | `local-modifications` | files changed since the registered baseline | update refuses; `回到这个 commit` (restore) still works and snapshots the current bytes first |
302
+
303
+ ## Upgrade and uninstall
304
+
305
+ Upgrade in place — the profile manifest and the stored snapshots both survive:
306
+
307
+ ```bash
308
+ dsh plugin --profile <profile> add dsh-version-manager@<newer-version>
309
+ ```
310
+
311
+ Reinstalling the **same** version is the one case pnpm short-circuits
312
+ (`Already up to date`, files not replaced). Remove first, then add:
313
+
314
+ ```bash
315
+ dsh plugin --profile <profile> remove dsh-version-manager
316
+ dsh plugin --profile <profile> add dsh-version-manager@<version>
317
+ ```
318
+
319
+ Uninstall removes the code, not your data:
320
+
321
+ ```bash
322
+ dsh plugin --profile <profile> remove dsh-version-manager
323
+ ```
324
+
325
+ Verified in an isolated profile: after a remove, `node_modules/dsh-version-manager` was
326
+ gone and the `dependencies` / `dsh.profile.bundles` entries with it, while
327
+ `<DSH_HOME>/version-manager/` still held every snapshot and operation record (19 files
328
+ before and after). Reinstalling brought the panel back with the same 11 snapshots and 8
329
+ operations. Delete `<DSH_HOME>/version-manager/` yourself to remove that history.
330
+
331
+ Disabling without uninstalling uses the host's own patch file — add the row's `id` with
332
+ `disabled: true` to `<DSH_HOME>/profiles/<profile>/cordis.patch.yml`, then restart:
333
+
334
+ ```yaml
335
+ - id: version-manager
336
+ disabled: true
337
+ ```
338
+
339
+ The panel disappears from the sidebar and nothing runs. There is no enable/disable
340
+ subcommand in the DSH CLI (`dsh plugin` only forwards `add` / `remove`); the patch file is
341
+ the supported way. Verified in an isolated profile, both directions.
342
+
343
+ ## Compatibility
344
+
345
+ | DSH | status |
346
+ | --- | --- |
347
+ | 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 |
348
+ | 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 |
349
+
350
+ ## Development
351
+
352
+ ```bash
353
+ npm test # node --test, no build step
354
+ ```
355
+
356
+ 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/`.
357
+
358
+ - `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.
359
+
360
+ ## License
361
+
362
+ MIT. See [LICENSE](../LICENSE).
@@ -0,0 +1,13 @@
1
+ # dsh-version-manager 0.1.5
2
+
3
+ ## 简体中文
4
+
5
+ - 适配 DeepSeek Harness 0.2.2-rc.3,保留原有宿主版本的兼容声明。
6
+ - 使用 rc.3 的实际宿主与客户端接口检查,并执行现有离线测试和发布包检查。
7
+ - 本次兼容性更新不等同于真实上游模型推理验收。稳定与预览渠道分别发布,预览功能不自动进入稳定渠道。
8
+
9
+ ## English
10
+
11
+ - Qualify DeepSeek Harness 0.2.2-rc.3 while preserving previously declared host compatibility.
12
+ - Check against rc.3 host/client interfaces, existing offline suites, and the packaged release.
13
+ - Compatibility qualification does not establish successful upstream model generation. Stable and preview channels remain separate.