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 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 109 tests with no network and no host: spec classification, semver comparison, lockfile parsing, inventory merging, snapshot store, snapshot retention and pruning, operation journal, Skill restore (including a swap that fails halfway), the Git-managed Skill flow against real throwaway repositories, and the HTTP routes wired against a fake host.
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
 
@@ -117,7 +117,12 @@ function runGitBytes(args) {
117
117
  * @returns {string}
118
118
  */
119
119
  function registryPath(dshHome, profileId) {
120
- return join(dshHome, 'version-manager', 'git-skills', `${profileId.replace(/[^A-Za-z0-9._-]/g, '_')}.json`)
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
  /**
@@ -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
- return join(dshHome, 'version-manager', 'skills', profileId, name)
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
  /**
@@ -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, name)
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 root = join(dshHome, 'version-manager', 'skills', profileId, name)
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.replace(/\//g, '%2F').replace(/[^A-Za-z0-9%._@-]/g, '_')
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.2",
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",