dsh-version-manager 0.1.3 → 0.1.4
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/README.md +37 -312
- package/README.zh-CN.md +64 -0
- package/assets/LICENSE-WHALE-ARTWORK +439 -0
- package/assets/NOTICE.md +9 -0
- package/assets/logo.webp +0 -0
- package/docs/assets/banner-en.svg +8 -0
- package/docs/assets/banner-zh-CN.svg +8 -0
- package/docs/assets/feature-1-en-dark.svg +1 -0
- package/docs/assets/feature-1-en-light.svg +1 -0
- package/docs/assets/feature-1-zh-CN-dark.svg +1 -0
- package/docs/assets/feature-1-zh-CN-light.svg +1 -0
- package/docs/assets/feature-2-en-dark.svg +1 -0
- package/docs/assets/feature-2-en-light.svg +1 -0
- package/docs/assets/feature-2-zh-CN-dark.svg +1 -0
- package/docs/assets/feature-2-zh-CN-light.svg +1 -0
- package/docs/assets/feature-3-en-dark.svg +1 -0
- package/docs/assets/feature-3-en-light.svg +1 -0
- package/docs/assets/feature-3-zh-CN-dark.svg +1 -0
- package/docs/assets/feature-3-zh-CN-light.svg +1 -0
- package/docs/git-write-safety.md +22 -0
- package/docs/guide.en.md +362 -0
- package/docs/release-notes-0.1.4.md +13 -0
- package/lib/client.js +117 -35
- package/lib/host/git-routes.js +11 -1
- package/lib/host/git-skill.js +60 -6
- package/lib/host/mutation-lock.js +26 -0
- package/lib/host/skill-restore.js +11 -0
- package/package.json +14 -4
package/README.md
CHANGED
|
@@ -1,339 +1,64 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center"><img src="assets/logo.webp" width="192" height="192" alt="DSH Version Manager logo"></p>
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<h1 align="center">DSH Version Manager</h1>
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
<p align="center">Inspect plugins and Skills in the running profile, preview updates, record verifiable snapshots and show what can actually be restored.</p>
|
|
6
6
|
|
|
7
|
-
|
|
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.
|
|
7
|
+
<p align="center"><a href="https://github.com/tangyixiao/dsh-version-manager"><img src="docs/assets/banner-en.svg" width="100%" alt="DSH Version Manager — Project and usage guide"></a></p>
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
<p align="center"><a href="README.zh-CN.md">简体中文</a> · <a href="README.md">English</a></p>
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
[](https://github.com/tangyixiao/dsh-version-manager/stargazers) [](https://github.com/tangyixiao/dsh-version-manager/actions/workflows/check.yml) [](LICENSE) [](https://www.npmjs.com/package/dsh-version-manager)
|
|
15
12
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
npm pack
|
|
24
|
-
dsh plugin --profile <your-profile> add /absolute/path/dsh-version-manager-<version>.tgz
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Then restart the host and open the panel from the left sidebar.
|
|
13
|
+
<p align="center">
|
|
14
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/feature-1-en-dark.svg"><img src="docs/assets/feature-1-en-light.svg" width="260" alt="Real installed inventory: Declared specs, disk versions and load state"></picture>
|
|
15
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/feature-2-en-dark.svg"><img src="docs/assets/feature-2-en-light.svg" width="260" alt="Snapshot before update: Write and read back SHA-256 evidence"></picture>
|
|
16
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/feature-3-en-dark.svg"><img src="docs/assets/feature-3-en-light.svg" width="260" alt="Explicit restore limits: Known state and a usable recovery path"></picture>
|
|
17
|
+
</p>
|
|
28
18
|
|
|
29
|
-
|
|
19
|
+
## Get started
|
|
30
20
|
|
|
31
|
-
|
|
21
|
+
Desktop: install the release `.tgz` through Extensions → Plugin Management → Add Plugin. For a Web profile you explicitly control:
|
|
32
22
|
|
|
33
|
-
```
|
|
34
|
-
|
|
23
|
+
```sh
|
|
24
|
+
dsh plugin --profile web add dsh-version-manager@0.1.4
|
|
35
25
|
```
|
|
36
26
|
|
|
37
|
-
|
|
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
|
-
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.
|
|
61
|
-
|
|
62
|
-
**Update** always shows the from → to pair plus the four side effects before it runs:
|
|
63
|
-
|
|
64
|
-
- a snapshot is written first and read back before anything else happens;
|
|
65
|
-
- the host saves the target as an *exact* version, so a declared range is replaced;
|
|
66
|
-
- configuration, the dependency tree and agent presets are **not** rolled back;
|
|
67
|
-
- the host is not restarted.
|
|
68
|
-
|
|
69
|
-
### Snapshots and restore
|
|
70
|
-
|
|
71
|
-
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.
|
|
72
|
-
|
|
73
|
-
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).
|
|
74
|
-
|
|
75
|
-
Restore is offered only when it can actually work, and only reports what happened:
|
|
76
|
-
|
|
77
|
-
| reply | meaning |
|
|
78
|
-
| --- | --- |
|
|
79
|
-
| `alreadyAtVersion: true` | the profile already carries that version; nothing was reinstalled |
|
|
80
|
-
| `ok: true` + `evidence.filesMatch: false` | the files had changed (normally because an update ran) and the recorded version was reinstalled |
|
|
81
|
-
| `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 |
|
|
82
|
-
| `409 source-substitution` | the snapshot belongs to a different package name |
|
|
83
|
-
| `409 not-installed` | the package directory cannot be read, so nothing can be fingerprinted |
|
|
84
|
-
|
|
85
|
-
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.
|
|
86
|
-
|
|
87
|
-
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.
|
|
88
|
-
|
|
89
|
-
### Skills tab
|
|
27
|
+
Install into an existing Desktop/Web profile and open Version manager. Review inventory and the exact from → to update first; a new empty profile also needs the Web app bundle.
|
|
90
28
|
|
|
91
|
-
|
|
29
|
+
## Status and compatibility
|
|
92
30
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
**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:
|
|
96
|
-
|
|
97
|
-
| reason | meaning |
|
|
31
|
+
| Item | Current source of truth |
|
|
98
32
|
| --- | --- |
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
| `snapshot-copy-missing` | the stored copy is gone |
|
|
105
|
-
| `no-directory` | a single-file Skill has no directory to swap |
|
|
106
|
-
|
|
107
|
-
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.
|
|
108
|
-
|
|
109
|
-
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.
|
|
110
|
-
|
|
111
|
-
> 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.
|
|
112
|
-
|
|
113
|
-
### Git-managed Skills
|
|
114
|
-
|
|
115
|
-
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.
|
|
116
|
-
|
|
117
|
-
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.
|
|
118
|
-
|
|
119
|
-
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.
|
|
120
|
-
|
|
121
|
-
It refuses, by name, when:
|
|
122
|
-
|
|
123
|
-
| reason | meaning |
|
|
124
|
-
| --- | --- |
|
|
125
|
-
| `local-modifications` | files in the directory no longer match the recorded baseline; the update would silently discard someone's work |
|
|
126
|
-
| `baseline-unknown` | the directory holds files that are not that commit's tree, so no honest baseline can be recorded at registration time |
|
|
127
|
-
| `inside-git-checkout` | the target directory is inside a working tree |
|
|
128
|
-
| `bundled-skill` | the Skill ships with DSH |
|
|
129
|
-
| `system-skill` | the path contains a `.system` segment |
|
|
130
|
-
| `bad-subpath` | the subpath is absolute, contains `..`, or points into `.git` |
|
|
131
|
-
| `unsupported-remote` | the address is not `https`, `ssh`, `git@`, `file://` or an absolute path |
|
|
132
|
-
| `already-registered` | the Skill is already registered to a different source; unregister first, so history cannot become fictional |
|
|
133
|
-
| `revision-not-in-cache` | the requested commit was never fetched; the plugin does not guess or rewrite history |
|
|
134
|
-
| `unsupported-entry` | the commit contains a symlink or a submodule. Writing a symlink as a regular file would change what the Skill means |
|
|
135
|
-
|
|
136
|
-
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.
|
|
137
|
-
|
|
138
|
-
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`).
|
|
139
|
-
|
|
140
|
-
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.
|
|
141
|
-
|
|
142
|
-
## Verification
|
|
143
|
-
|
|
144
|
-
Three kinds of evidence, kept apart on purpose.
|
|
145
|
-
|
|
146
|
-
**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.
|
|
33
|
+
| Source version | `0.1.4` · 以 [package.json](package.json) 为准 |
|
|
34
|
+
| Distribution | `npm` · [Releases](https://github.com/tangyixiao/dsh-version-manager/releases) |
|
|
35
|
+
| DSH | `>=0.2.2-rc.1` |
|
|
36
|
+
| Node.js | `>=22` |
|
|
37
|
+
| Development | [Open issues](https://github.com/tangyixiao/dsh-version-manager/issues?q=is%3Aissue+is%3Aopen) · [CI](https://github.com/tangyixiao/dsh-version-manager/actions) |
|
|
147
38
|
|
|
148
|
-
|
|
39
|
+
Restore is not a full backup: restoring a plugin version does not roll back configuration, the dependency tree or agent presets. Git, tarball and local sources require replay evidence.
|
|
149
40
|
|
|
150
|
-
|
|
41
|
+
[Detailed usage, configuration and troubleshooting](docs/guide.en.md)
|
|
151
42
|
|
|
152
|
-
|
|
43
|
+
## Development and participation
|
|
153
44
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
| `GET /overview` | `profile=final`, `host=0.2.2-rc.1`, source `@deepseek-ai/dsh-app-boot/package.json` |
|
|
158
|
-
| `POST /snapshot` without `confirm` | `400 {"error":"confirm required"}` |
|
|
159
|
-
| `POST /snapshot` with `confirm` | `200`, snapshot written with `seq: 1` |
|
|
160
|
-
| `POST /update` on a registry plugin | `200`, host reported `1.7.2 → 1.7.3`, snapshot taken first, operation journal reached `succeeded` |
|
|
161
|
-
| `POST /restore` with that snapshot | `200`, `restoredVersion: 1.7.2`, `evidence.filesMatch: false` (the files *had* changed, which is the expected evidence) |
|
|
162
|
-
| `POST /skills/snapshot` | `200`, copy re-read and verified, `fileCount: 2` |
|
|
163
|
-
| Skill restore on a bundled Skill | `409 bundled-skill`, directory unchanged |
|
|
164
|
-
| 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 |
|
|
165
|
-
| 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-…`) |
|
|
166
|
-
| 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 |
|
|
167
|
-
| 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 |
|
|
168
|
-
|
|
169
|
-
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.
|
|
170
|
-
|
|
171
|
-
Not verified: another DSH version, a Linux or macOS Desktop, and a non-bundled Skill provider.
|
|
172
|
-
|
|
173
|
-
## Honest limits
|
|
174
|
-
|
|
175
|
-
- **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.
|
|
176
|
-
- **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.
|
|
177
|
-
- **Compatibility uses the package's own declaration.** If a package declares nothing, the panel says so instead of guessing.
|
|
178
|
-
- **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.
|
|
179
|
-
- **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.
|
|
180
|
-
- **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.
|
|
181
|
-
- **`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.
|
|
182
|
-
- **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.
|
|
183
|
-
|
|
184
|
-
## Security
|
|
185
|
-
|
|
186
|
-
- Every route requires a DSH owner session (`connection.admit`); there is no unauthenticated surface.
|
|
187
|
-
- Every write route requires `{"confirm": true}` in the body, so a stray GET or a cross-site form post cannot change anything.
|
|
188
|
-
- 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.
|
|
189
|
-
- 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 `..`.
|
|
190
|
-
- 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.
|
|
191
|
-
- 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.
|
|
192
|
-
- Nothing is uploaded. The panel reads only what the host and the local filesystem expose.
|
|
193
|
-
|
|
194
|
-
## Routes
|
|
195
|
-
|
|
196
|
-
All under `/dsh-version-manager`, same-origin, `Cache-Control: no-store`.
|
|
197
|
-
|
|
198
|
-
| method | path | body | purpose |
|
|
199
|
-
| --- | --- | --- | --- |
|
|
200
|
-
| GET | `/overview` | — | profile, host version, plugin rows, recent operations |
|
|
201
|
-
| GET | `/versions?target=<name>` | — | newer versions, split into stable and prerelease |
|
|
202
|
-
| GET | `/skills` | — | Skill inventory with snapshot counts, a `restoreRefusal` per row, and the Git registry |
|
|
203
|
-
| GET | `/skills/restore-preview?name=&file=` | — | what a restore would do, and every reason it would be refused |
|
|
204
|
-
| GET | `/skills/git` | — | registered Git sources, their pinned revision, local drift, and separate `refusal` / `restoreRefusal` |
|
|
205
|
-
| POST | `/snapshot` | `{targetId, confirm}` | snapshot one plugin |
|
|
206
|
-
| POST | `/snapshots/prune` | `{targetId, confirm}` | delete the snapshots past the per-target limit, listing every file removed |
|
|
207
|
-
| POST | `/update` | `{targetId, toVersion, allowPrerelease?, confirm}` | snapshot, then ask the host to update |
|
|
208
|
-
| POST | `/restore` | `{targetId, snapshotId, confirm}` | reinstall the version a snapshot recorded |
|
|
209
|
-
| POST | `/skills/snapshot` | `{name, confirm}` | snapshot one Skill |
|
|
210
|
-
| POST | `/skills/restore` | `{name, file, confirm}` | replace one Skill directory with the recorded bytes |
|
|
211
|
-
| POST | `/skills/git/register` | `{name, remote, subpath?, ref?, create?, confirm}` | record where a Skill comes from and the commit it currently matches |
|
|
212
|
-
| POST | `/skills/git/remove` | `{name, confirm}` | forget the registration, leaving the directory alone |
|
|
213
|
-
| POST | `/skills/git/preview` | `{name, ref?, confirm}` | fetch into the plugin's cache and report the diff and every refusal |
|
|
214
|
-
| POST | `/skills/git/update` | `{name, ref?, confirm}` | snapshot, then write the tree of the fetched commit |
|
|
215
|
-
| POST | `/skills/git/restore` | `{name, revision, confirm}` | snapshot, then write the tree of a commit already in the cache |
|
|
216
|
-
|
|
217
|
-
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`.
|
|
218
|
-
|
|
219
|
-
## Performance and cache policy
|
|
220
|
-
|
|
221
|
-
Measured in a real Windows Desktop host (0.2.2-rc.1, Electron 44.7.0, Node 24.21.0) against a
|
|
222
|
-
profile with 26 plugin rows, 11 stored snapshots and 8 visible Skills. Timings are
|
|
223
|
-
`fetch()` round trips taken inside the panel's page, so they include the host's own
|
|
224
|
-
serialization:
|
|
225
|
-
|
|
226
|
-
| call | cold | warm |
|
|
227
|
-
| --- | --- | --- |
|
|
228
|
-
| `GET /overview` | 161 ms | 134 ms |
|
|
229
|
-
| `GET /skills` | 426 ms | 313 ms |
|
|
230
|
-
|
|
231
|
-
There is nothing slower here by design. What costs time, and why:
|
|
232
|
-
|
|
233
|
-
- **`/overview` reads the filesystem per row.** For each package it reads the installed
|
|
234
|
-
manifest, the profile manifest, the lockfile entry and the stored snapshot list. That is
|
|
235
|
-
why it is one call and not one call per row: the panel refreshes everything at once.
|
|
236
|
-
- **`/skills` is the slower one** because the host's skill catalog is scanned by the host
|
|
237
|
-
itself; the plugin only aggregates what the host already enumerated.
|
|
238
|
-
- **No caching of version lists anywhere.** `/versions?target=…` asks the registry through
|
|
239
|
-
the host every time it is pressed. A cached answer would be indistinguishable from a
|
|
240
|
-
fresh one in the panel, which is exactly the failure this plugin exists to avoid.
|
|
241
|
-
- **The only on-disk caches** are the snapshot store
|
|
242
|
-
(`<DSH_HOME>/version-manager/snapshots/<profile>/<pkg>/`) and, for Git-managed Skills, a
|
|
243
|
-
bare repository per remote (`<DSH_HOME>/version-manager/git-cache/<hash>.git`). Both are
|
|
244
|
-
yours to delete when the plugin is not running; the plugin recreates what it needs.
|
|
245
|
-
|
|
246
|
-
### Retention is visible, and nothing is deleted for you
|
|
247
|
-
|
|
248
|
-
Every target keeps its snapshots. The panel states the numbers: how many exist, how many
|
|
249
|
-
are past the 20-per-target limit, and which ones. Rows past the limit are labelled
|
|
250
|
-
**超出保留数 / past retention** in the list.
|
|
251
|
-
|
|
252
|
-
They are **not** removed automatically. A version manager that silently deletes the way
|
|
253
|
-
back is worse than one that keeps too much, so removal is one explicit action with its own
|
|
254
|
-
confirmation, which states how many files it will delete before it does it:
|
|
255
|
-
|
|
256
|
-
```
|
|
257
|
-
POST /snapshots/prune { targetId, confirm: true }
|
|
45
|
+
```sh
|
|
46
|
+
npm test
|
|
47
|
+
node tools/check-repository.mjs
|
|
258
48
|
```
|
|
259
49
|
|
|
260
|
-
|
|
261
|
-
A snapshot still in the list can still be restored.
|
|
50
|
+
[Contributing](CONTRIBUTING.md) · [Support](SUPPORT.md) · [Questions](https://github.com/tangyixiao/dsh-version-manager/discussions) · [Report a bug](https://github.com/tangyixiao/dsh-version-manager/issues/new/choose) · [Security](SECURITY.md) · [Maintenance](docs/maintenance.md)
|
|
262
51
|
|
|
263
|
-
##
|
|
52
|
+
## Star History
|
|
264
53
|
|
|
265
|
-
|
|
266
|
-
| --- | --- | --- |
|
|
267
|
-
| 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) |
|
|
268
|
-
| 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 |
|
|
269
|
-
| `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 |
|
|
270
|
-
| 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 |
|
|
271
|
-
| 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 |
|
|
272
|
-
| 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 |
|
|
273
|
-
| 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 |
|
|
274
|
-
| `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 |
|
|
275
|
-
| 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 |
|
|
276
|
-
| 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 |
|
|
277
|
-
| `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 |
|
|
278
|
-
| `local-modifications` | files changed since the registered baseline | update refuses; `回到这个 commit` (restore) still works and snapshots the current bytes first |
|
|
54
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=tangyixiao/dsh-version-manager&type=date&theme=dark&legend=top-left"><img src="https://api.star-history.com/chart?repos=tangyixiao/dsh-version-manager&type=date&legend=top-left" width="900" alt="DSH Version Manager Star History"></picture>
|
|
279
55
|
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
Upgrade in place — the profile manifest and the stored snapshots both survive:
|
|
283
|
-
|
|
284
|
-
```bash
|
|
285
|
-
dsh plugin --profile <profile> add dsh-version-manager@<newer-version>
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
Reinstalling the **same** version is the one case pnpm short-circuits
|
|
289
|
-
(`Already up to date`, files not replaced). Remove first, then add:
|
|
290
|
-
|
|
291
|
-
```bash
|
|
292
|
-
dsh plugin --profile <profile> remove dsh-version-manager
|
|
293
|
-
dsh plugin --profile <profile> add dsh-version-manager@<version>
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
Uninstall removes the code, not your data:
|
|
297
|
-
|
|
298
|
-
```bash
|
|
299
|
-
dsh plugin --profile <profile> remove dsh-version-manager
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
Verified in an isolated profile: after a remove, `node_modules/dsh-version-manager` was
|
|
303
|
-
gone and the `dependencies` / `dsh.profile.bundles` entries with it, while
|
|
304
|
-
`<DSH_HOME>/version-manager/` still held every snapshot and operation record (19 files
|
|
305
|
-
before and after). Reinstalling brought the panel back with the same 11 snapshots and 8
|
|
306
|
-
operations. Delete `<DSH_HOME>/version-manager/` yourself to remove that history.
|
|
307
|
-
|
|
308
|
-
Disabling without uninstalling uses the host's own patch file — add the row's `id` with
|
|
309
|
-
`disabled: true` to `<DSH_HOME>/profiles/<profile>/cordis.patch.yml`, then restart:
|
|
310
|
-
|
|
311
|
-
```yaml
|
|
312
|
-
- id: version-manager
|
|
313
|
-
disabled: true
|
|
314
|
-
```
|
|
315
|
-
|
|
316
|
-
The panel disappears from the sidebar and nothing runs. There is no enable/disable
|
|
317
|
-
subcommand in the DSH CLI (`dsh plugin` only forwards `add` / `remove`); the patch file is
|
|
318
|
-
the supported way. Verified in an isolated profile, both directions.
|
|
319
|
-
|
|
320
|
-
## Compatibility
|
|
321
|
-
|
|
322
|
-
| DSH | status |
|
|
323
|
-
| --- | --- |
|
|
324
|
-
| 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 |
|
|
325
|
-
| 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 |
|
|
326
|
-
|
|
327
|
-
## Development
|
|
328
|
-
|
|
329
|
-
```bash
|
|
330
|
-
npm test # node --test, no build step
|
|
331
|
-
```
|
|
56
|
+
[Interactive chart](https://www.star-history.com/?repos=tangyixiao%2Fdsh-version-manager&type=date) · [GitHub Stars](https://github.com/tangyixiao/dsh-version-manager/stargazers)
|
|
332
57
|
|
|
333
|
-
The
|
|
58
|
+
The external chart uses real star records and may be cached or unavailable; no development percentage is inferred.
|
|
334
59
|
|
|
335
|
-
|
|
60
|
+
## Origin and licenses
|
|
336
61
|
|
|
337
|
-
|
|
62
|
+
[Software license](LICENSE) · [Logo artwork and attribution](assets/NOTICE.md)
|
|
338
63
|
|
|
339
|
-
|
|
64
|
+
Software retains its existing license. Whale-girl derivative artwork is separately CC BY-NC-SA 4.0 with the attribution chain for 上善, ZipZipPipe and Small-tailqwq.
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
<p align="center"><img src="assets/logo.webp" width="192" height="192" alt="DSH Version Manager logo"></p>
|
|
2
|
+
|
|
3
|
+
<h1 align="center">DSH Version Manager</h1>
|
|
4
|
+
|
|
5
|
+
<p align="center">查看运行中 profile 的插件与 Skills,预览更新、保存可验证快照,并明确哪些状态能恢复。</p>
|
|
6
|
+
|
|
7
|
+
<p align="center"><a href="https://github.com/tangyixiao/dsh-version-manager"><img src="docs/assets/banner-zh-CN.svg" width="100%" alt="DSH Version Manager — 查看项目与使用说明"></a></p>
|
|
8
|
+
|
|
9
|
+
<p align="center"><a href="README.zh-CN.md">简体中文</a> · <a href="README.md">English</a></p>
|
|
10
|
+
|
|
11
|
+
[](https://github.com/tangyixiao/dsh-version-manager/stargazers) [](https://github.com/tangyixiao/dsh-version-manager/actions/workflows/check.yml) [](LICENSE) [](https://www.npmjs.com/package/dsh-version-manager)
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/feature-1-zh-CN-dark.svg"><img src="docs/assets/feature-1-zh-CN-light.svg" width="260" alt="真实安装清单: 声明、磁盘版本与加载状态分开"></picture>
|
|
15
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/feature-2-zh-CN-dark.svg"><img src="docs/assets/feature-2-zh-CN-light.svg" width="260" alt="更新前快照: 保存并回读 SHA-256 证据"></picture>
|
|
16
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/feature-3-zh-CN-dark.svg"><img src="docs/assets/feature-3-zh-CN-light.svg" width="260" alt="明确恢复边界: 保留原状态与可用返回路径"></picture>
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
## 开始使用
|
|
20
|
+
|
|
21
|
+
Desktop:从发行页下载 `.tgz`,在“扩展 → 插件管理 → 添加插件”中安装。命令行示例用于你明确控制的 Web profile:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
dsh plugin --profile web add dsh-version-manager@0.1.4
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
在原有 Desktop/Web profile 中安装并打开“版本管理”。先查看清单与更新预览,再确认具体 from → to;新建空 profile 还需要 Web 应用 bundle。
|
|
28
|
+
|
|
29
|
+
## 当前状态与兼容性
|
|
30
|
+
|
|
31
|
+
| 项目 | 当前依据 |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| 源码版本 | `0.1.4` · 以 [package.json](package.json) 为准 |
|
|
34
|
+
| 分发方式 | `npm` · [Releases](https://github.com/tangyixiao/dsh-version-manager/releases) |
|
|
35
|
+
| DSH | `>=0.2.2-rc.1` |
|
|
36
|
+
| Node.js | `>=22` |
|
|
37
|
+
| 开发状态 | [Open issues](https://github.com/tangyixiao/dsh-version-manager/issues?q=is%3Aissue+is%3Aopen) · [CI](https://github.com/tangyixiao/dsh-version-manager/actions) |
|
|
38
|
+
|
|
39
|
+
恢复不等于完整备份:插件版本恢复不回滚配置、依赖树和 agent presets。Git、tarball 与本地来源能否重放按实际证据判断。
|
|
40
|
+
|
|
41
|
+
[Detailed guide](docs/guide.en.md)
|
|
42
|
+
|
|
43
|
+
## 开发与参与
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
npm test
|
|
47
|
+
node tools/check-repository.mjs
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
[Contributing](CONTRIBUTING.md) · [Support](SUPPORT.md) · [Questions](https://github.com/tangyixiao/dsh-version-manager/discussions) · [Report a bug](https://github.com/tangyixiao/dsh-version-manager/issues/new/choose) · [Security](SECURITY.md) · [Maintenance](docs/maintenance.md)
|
|
51
|
+
|
|
52
|
+
## Star History
|
|
53
|
+
|
|
54
|
+
<picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=tangyixiao/dsh-version-manager&type=date&theme=dark&legend=top-left"><img src="https://api.star-history.com/chart?repos=tangyixiao/dsh-version-manager&type=date&legend=top-left" width="900" alt="DSH Version Manager Star History"></picture>
|
|
55
|
+
|
|
56
|
+
[Interactive chart](https://www.star-history.com/?repos=tangyixiao%2Fdsh-version-manager&type=date) · [GitHub Stars](https://github.com/tangyixiao/dsh-version-manager/stargazers)
|
|
57
|
+
|
|
58
|
+
图表由外部服务按真实星标数据生成,可能缓存或暂时不可用;未填造开发百分比。
|
|
59
|
+
|
|
60
|
+
## 来源与许可
|
|
61
|
+
|
|
62
|
+
[Software license](LICENSE) · [Logo artwork and attribution](assets/NOTICE.md)
|
|
63
|
+
|
|
64
|
+
软件保持原许可证;鲸鱼娘衍生美术单独采用 CC BY-NC-SA 4.0,并保留上善、ZipZipPipe、Small-tailqwq 的署名链。
|