dsh-version-manager 0.1.2 → 0.1.3
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 +4 -2
- package/lib/host/git-skill.js +6 -1
- package/lib/host/operations.js +2 -8
- package/lib/host/segment.js +53 -0
- package/lib/host/skill-restore.js +6 -1
- package/lib/host/skills.js +7 -2
- package/lib/host/snapshot-store.js +6 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -143,7 +143,7 @@ Sources that are **not** supported, listed rather than implied: any directory th
|
|
|
143
143
|
|
|
144
144
|
Three kinds of evidence, kept apart on purpose.
|
|
145
145
|
|
|
146
|
-
**Unit and integration tests.** `npm test` runs
|
|
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.
|
|
147
147
|
|
|
148
148
|
**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.
|
|
149
149
|
|
|
@@ -162,9 +162,11 @@ What was exercised, and what it produced:
|
|
|
162
162
|
| `POST /skills/snapshot` | `200`, copy re-read and verified, `fileCount: 2` |
|
|
163
163
|
| Skill restore on a bundled Skill | `409 bundled-skill`, directory unchanged |
|
|
164
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 |
|
|
165
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 |
|
|
166
168
|
|
|
167
|
-
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.
|
|
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.
|
|
168
170
|
|
|
169
171
|
Not verified: another DSH version, a Linux or macOS Desktop, and a non-bundled Skill provider.
|
|
170
172
|
|
package/lib/host/git-skill.js
CHANGED
|
@@ -117,7 +117,12 @@ function runGitBytes(args) {
|
|
|
117
117
|
* @returns {string}
|
|
118
118
|
*/
|
|
119
119
|
function registryPath(dshHome, profileId) {
|
|
120
|
-
|
|
120
|
+
// Deliberately not `encodeSegment`: this one is a *file* name with `.json`
|
|
121
|
+
// appended, so `..` cannot traverse, and the stricter alphabet it has always
|
|
122
|
+
// used is what the registries already on disk are named after. Widening it
|
|
123
|
+
// would make an existing registry look empty rather than moved.
|
|
124
|
+
const safe = String(profileId).replace(/[^A-Za-z0-9._-]/g, '_')
|
|
125
|
+
return join(dshHome, 'version-manager', 'git-skills', `${safe}.json`)
|
|
121
126
|
}
|
|
122
127
|
|
|
123
128
|
/**
|
package/lib/host/operations.js
CHANGED
|
@@ -22,6 +22,8 @@ import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
|
|
|
22
22
|
import { join } from 'node:path'
|
|
23
23
|
import { randomUUID } from 'node:crypto'
|
|
24
24
|
|
|
25
|
+
import { encodeSegment } from './segment.js'
|
|
26
|
+
|
|
25
27
|
/** The states a change can be in. Order matters: it is the order they occur. */
|
|
26
28
|
export const STATES = Object.freeze([
|
|
27
29
|
'planned',
|
|
@@ -48,14 +50,6 @@ export function operationRoot(dshHome, profileId) {
|
|
|
48
50
|
return join(dshHome, 'version-manager', 'operations', encodeSegment(profileId))
|
|
49
51
|
}
|
|
50
52
|
|
|
51
|
-
/**
|
|
52
|
-
* @param {string} value
|
|
53
|
-
* @returns {string}
|
|
54
|
-
*/
|
|
55
|
-
function encodeSegment(value) {
|
|
56
|
-
return value.replace(/\//g, '%2F').replace(/[^A-Za-z0-9%._@-]/g, '_')
|
|
57
|
-
}
|
|
58
|
-
|
|
59
53
|
/**
|
|
60
54
|
* Start a record.
|
|
61
55
|
*
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Turning a name from the host into one path segment, safely.
|
|
3
|
+
*
|
|
4
|
+
* Profile ids and package names become directory names under
|
|
5
|
+
* `<DSH_HOME>/version-manager/`. Most of them are already usable as-is, so the
|
|
6
|
+
* encoding stays conservative: only characters that would break a path are
|
|
7
|
+
* replaced, and a name that was fine yesterday lands in the same directory
|
|
8
|
+
* today. Changing the layout for ordinary names would strand every snapshot
|
|
9
|
+
* already on disk.
|
|
10
|
+
*
|
|
11
|
+
* The case worth spelling out is `.` and `..`. Replacing `/` is not enough,
|
|
12
|
+
* because `path.join(root, '..')` walks *up*, out of the plugin's own
|
|
13
|
+
* directory. A segment that is nothing but dots is therefore encoded outright.
|
|
14
|
+
* This cannot happen for a profile the CLI created, and it costs three lines to
|
|
15
|
+
* make sure it cannot happen for one it did not.
|
|
16
|
+
*
|
|
17
|
+
* @module dsh-version-manager/lib/host/segment
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* @param {unknown} value
|
|
22
|
+
* @returns {string}
|
|
23
|
+
*/
|
|
24
|
+
export function encodeSegment(value) {
|
|
25
|
+
const text = typeof value === 'string' ? value : String(value ?? '')
|
|
26
|
+
const encoded = text.replace(/\//g, '%2F').replace(/[^A-Za-z0-9%._@-]/g, '_')
|
|
27
|
+
if (encoded === '') return '_'
|
|
28
|
+
// `.` and `..` (and `...`, which Windows will not keep either) are the only
|
|
29
|
+
// encodings that still mean something to a filesystem.
|
|
30
|
+
if (/^\.+$/.test(encoded)) return encoded.replace(/\./g, '%2E')
|
|
31
|
+
return encoded
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Accept a name as a path segment, or say no.
|
|
36
|
+
*
|
|
37
|
+
* Skill names are directory names reported by the host's own catalog, and they
|
|
38
|
+
* are legitimately non-ASCII — a snapshot directory called `office` and one
|
|
39
|
+
* called `离线诊断` are both fine. Encoding those into ASCII would move every
|
|
40
|
+
* existing snapshot to a new directory, so this path validates instead of
|
|
41
|
+
* rewriting: a name that cannot be a single path segment is refused rather
|
|
42
|
+
* than approximated into one.
|
|
43
|
+
*
|
|
44
|
+
* @param {unknown} value
|
|
45
|
+
* @returns {string | null} the name, unchanged, or null when it is not usable
|
|
46
|
+
*/
|
|
47
|
+
export function safeSegment(value) {
|
|
48
|
+
if (typeof value !== 'string' || value === '') return null
|
|
49
|
+
if (value === '.' || value === '..') return null
|
|
50
|
+
if (value.includes('/') || value.includes('\\')) return null
|
|
51
|
+
if (value.includes('\0')) return null
|
|
52
|
+
return value
|
|
53
|
+
}
|
|
@@ -31,6 +31,7 @@ import { cp, mkdir, readFile, readdir, rename, rm } from 'node:fs/promises'
|
|
|
31
31
|
import { dirname, join, sep } from 'node:path'
|
|
32
32
|
|
|
33
33
|
import { fingerprintTree } from './snapshot-store.js'
|
|
34
|
+
import { encodeSegment, safeSegment } from './segment.js'
|
|
34
35
|
import { directoryState, listSkillSnapshots, readGitState, snapshotSkill } from './skills.js'
|
|
35
36
|
|
|
36
37
|
/**
|
|
@@ -40,7 +41,11 @@ import { directoryState, listSkillSnapshots, readGitState, snapshotSkill } from
|
|
|
40
41
|
* @returns {string}
|
|
41
42
|
*/
|
|
42
43
|
function skillRoot(dshHome, profileId, name) {
|
|
43
|
-
|
|
44
|
+
// A skill name reaches this from a request body as well as from the catalog,
|
|
45
|
+
// and `..` here would walk out of the snapshot store and read somebody else's
|
|
46
|
+
// files. The caller validates first; this is the second lock on the same door.
|
|
47
|
+
const segment = safeSegment(name) ?? encodeSegment(name)
|
|
48
|
+
return join(dshHome, 'version-manager', 'skills', profileId, segment)
|
|
44
49
|
}
|
|
45
50
|
|
|
46
51
|
/**
|
package/lib/host/skills.js
CHANGED
|
@@ -17,6 +17,7 @@ import { cp, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
|
|
|
17
17
|
import { join, relative } from 'node:path'
|
|
18
18
|
|
|
19
19
|
import { fingerprintTree } from './snapshot-store.js'
|
|
20
|
+
import { safeSegment } from './segment.js'
|
|
20
21
|
|
|
21
22
|
const GIT_TIMEOUT_MS = 5000
|
|
22
23
|
const MAX_SKILL_FILES = 5000
|
|
@@ -222,8 +223,10 @@ function emptyGit() {
|
|
|
222
223
|
*/
|
|
223
224
|
export async function snapshotSkill(input) {
|
|
224
225
|
const { dshHome, profileId, name, directory, git, reason } = input
|
|
226
|
+
const segment = safeSegment(name)
|
|
227
|
+
if (segment === null) throw new Error(`A skill snapshot needs a plain name, not ${JSON.stringify(name)}`)
|
|
225
228
|
const stamp = new Date().toISOString().replace(/[:.]/g, '-')
|
|
226
|
-
const root = join(dshHome, 'version-manager', 'skills', profileId,
|
|
229
|
+
const root = join(dshHome, 'version-manager', 'skills', profileId, segment)
|
|
227
230
|
const directoryCopy = join(root, `${stamp}-files`)
|
|
228
231
|
await mkdir(root, { recursive: true })
|
|
229
232
|
|
|
@@ -270,7 +273,9 @@ export async function snapshotSkill(input) {
|
|
|
270
273
|
* @param {string} name
|
|
271
274
|
*/
|
|
272
275
|
export async function listSkillSnapshots(dshHome, profileId, name) {
|
|
273
|
-
const
|
|
276
|
+
const segment = safeSegment(name)
|
|
277
|
+
if (segment === null) return []
|
|
278
|
+
const root = join(dshHome, 'version-manager', 'skills', profileId, segment)
|
|
274
279
|
let entries
|
|
275
280
|
try {
|
|
276
281
|
entries = await readdir(root)
|
|
@@ -24,6 +24,8 @@ import { createHash, randomUUID } from 'node:crypto'
|
|
|
24
24
|
import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
|
|
25
25
|
import { join } from 'node:path'
|
|
26
26
|
|
|
27
|
+
import { encodeSegment } from './segment.js'
|
|
28
|
+
|
|
27
29
|
/** Bumped whenever the shape below changes in a way old readers cannot read. */
|
|
28
30
|
export const SNAPSHOT_SCHEMA = 1
|
|
29
31
|
|
|
@@ -34,12 +36,15 @@ export const SNAPSHOT_KEEP = 20
|
|
|
34
36
|
* A filename-safe form of a package name.
|
|
35
37
|
*
|
|
36
38
|
* `@scope/name` would otherwise create a directory, and a name is not a path.
|
|
39
|
+
* The encoding itself lives in `segment.js` so that the four places that turn a
|
|
40
|
+
* host-supplied name into a directory cannot drift apart; `.` and `..` are the
|
|
41
|
+
* cases it exists for.
|
|
37
42
|
*
|
|
38
43
|
* @param {string} targetId
|
|
39
44
|
* @returns {string}
|
|
40
45
|
*/
|
|
41
46
|
export function encodeTarget(targetId) {
|
|
42
|
-
return targetId
|
|
47
|
+
return encodeSegment(targetId)
|
|
43
48
|
}
|
|
44
49
|
|
|
45
50
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-version-manager",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Version management for DSH plugins and skills: an honest inventory of what is installed, a preview of what an update would change, a verifiable snapshot taken before the change, and a recovery path that is only offered when it can actually work.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/index.js",
|