dsh-profile-gist-sync 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Meta-Virgo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,295 @@
1
- # Temporary Holding Version
1
+ # dsh-profile-gist-sync
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Back up this DSH profile's configuration to an **unlisted secret GitHub Gist**,
4
+ pull it back on another machine, and see at a glance whether the two agree.
5
+
6
+ A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`)
7
+ plugin: a page in **Settings → Plugins → 配置同步 / Config sync**, and a
8
+ `config_backup` tool for the agent.
9
+
10
+ 页面位置:**设置 → 插件 → 配置同步**。Agent 侧工具:`config_backup`。
11
+
12
+ ## Install
13
+
14
+ ```sh
15
+ dsh plugin --profile web add dsh-profile-gist-sync # from npm
16
+ dsh plugin --profile web add github:Meta-Virgo/dsh-profile-gist-sync # from source
17
+ ```
18
+
19
+ Then restart DSH. No dependencies, no build step, no install scripts: the
20
+ package is plain ESM that Node runs as-is.
21
+
22
+ ## The page
23
+
24
+ Three numbered steps, one button each; nothing has to be typed.
25
+
26
+ 1. **状态** — one line saying whether the cloud copy and this machine agree,
27
+ plus the profile, the file count, and the last upload/sync. It checks the
28
+ cloud by itself on open; 重新检查 does it again.
29
+ 2. **上传** — 上传到云端 backs this machine up to the cloud. The Gist this
30
+ profile already uses is updated, and the first upload creates one and
31
+ remembers it. 另存为本地文件 writes the same backup to a local file instead.
32
+ 3. **同步** — 从云端同步 writes the cloud copy here, with 撤销上次同步 offered
33
+ afterwards. The same card then says which plugins the manifest names and this
34
+ machine does not have, and offers one button to install them.
35
+
36
+ Everything fiddly (the Gist id, a token, the machine-state checkbox, restoring
37
+ from a backup file, the file list, the new-machine checklist) sits in a collapsed
38
+ **高级设置** section. The Gist id and the last upload/sync are remembered in
39
+ `<profile>/.dsh-config-sync/settings.json`; that file is never part of a backup.
40
+
41
+ ## Using this on a second machine
42
+
43
+ 1. Install the plugin there, then restart DSH.
44
+ 2. Give it a token **for the same GitHub account that owns the Gist**. A secret
45
+ Gist is readable through the API only by its owner, so another account does not
46
+ get "forbidden" — it gets "not found".
47
+ 3. Open the page and press 从云端同步.
48
+ 4. What is still missing then appears in ③; press 安装缺的插件 once, then restart
49
+ DSH.
50
+
51
+ Steps 2 and 4 are the two that fail on a new machine, so the page carries them:
52
+ the checklist sits in 高级设置, and the token error spells out all three ways to
53
+ supply one.
54
+
55
+ ## What leaves this machine
56
+
57
+ Short version, for anyone deciding whether to install this:
58
+
59
+ - The only host ever contacted is `api.github.com`. The checks in `test/` fail if
60
+ the plugin opens any other connection.
61
+ - Upload sends text configuration only — the files listed below. Credential
62
+ stores, binaries, `node_modules`, the lockfile, and this machine's usage
63
+ counters are excluded, and the UI names every exclusion instead of hiding it.
64
+ - A dependency whose spec only resolves on this machine — `link:`, `file:`,
65
+ `portal:`, `workspace:`, or a bare path like `E:/x`, `/x`, or `./x` — is left
66
+ out of the uploaded `package.json` and reported, because it would overwrite the
67
+ other machine's own spec with a path that does not exist there. Nothing is
68
+ invented in its place: the other machine keeps whatever it already has.
69
+ - The Gist is created `public: false`. **Unlisted, not private**: anyone with the
70
+ link can read it, so the link is the secret.
71
+ - The GitHub token is never written anywhere; it is used for one request and can
72
+ come from the request body, the host environment, or a signed-in `gh` CLI.
73
+ - The Gist id lives in `<profile>/.dsh-config-sync/settings.json` — inside a
74
+ hidden directory, which backups never carry, so syncing a machine never leaks
75
+ the id of the machine it came from.
76
+ - Restoring is merge-style and reversible: nothing is written before the
77
+ overwritten bytes are snapshotted for 撤销上次同步.
78
+ - Installing missing plugins is additive: it calls `installBundle` for each
79
+ missing spec and nothing else. It never removes, disables, or rewrites a bundle
80
+ selection, and running it twice is safe.
81
+
82
+ ## What a backup carries
83
+
84
+ Text configuration from the profile directory: `package.json`,
85
+ `cordis.patch.yml`, `cordis.yml`, `.npmrc`, `pnpm-workspace.yaml`,
86
+ `data/*.json`, `suppliers/*`, and any other text file the profile holds. The
87
+ document format is `dsh-profile-backup` v0.2 — the same one the DSH plugin market
88
+ reads and writes, so a backup from here imports there and vice versa.
89
+
90
+ Never included, and always listed as excluded in the UI:
91
+
92
+ | Path | Why |
93
+ | --- | --- |
94
+ | `node_modules/`, `pnpm-lock.yaml` | reproducible from `package.json` |
95
+ | `.git/`, `*.bak` | VCS state and repair leftovers |
96
+ | hidden directories (`.dsh-market/`, `.plugin-manager/`, `.dsh-config-sync/`) | logs, caches, this plugin's own undo snapshots |
97
+ | `data/auths/credentials.sqlite`, any other binary file | a credential store, and not portable |
98
+ | `data/usage.json` | this machine's counters — include with the checkbox when wanted |
99
+ | a machine-local `dependencies` entry | `link:`, `file:`, `portal:`, `workspace:`, or a bare path — means nothing elsewhere |
100
+
101
+ The machine-local dependency is the one exclusion that changes a file rather than
102
+ dropping it whole: the entry is removed from the `package.json` in the document,
103
+ every other key in that manifest is left byte-for-byte as it was (including
104
+ `dsh.profile.bundles`, which keeps naming the plugin), and the caller is told the
105
+ package name, the dropped spec, and — when the target's own `package.json` can be
106
+ read — the name and version it would have installed. No `^1.0.0` or any other
107
+ version is invented: the point of dropping it is that the target machine's own
108
+ entry survives, not that a guess replaces it. This travels beside the document,
109
+ not inside it, because the document format is shared with the DSH plugin market
110
+ and gains no new keys.
111
+
112
+ A backup written elsewhere may still carry entries this plugin does not write
113
+ into a profile: the plugin market's exporter, for example, includes
114
+ `data/auths/credentials.sqlite`. Importing such a document is not refused — the
115
+ credential store, cached binaries, backup copies, oversized files, and hidden
116
+ directories are skipped, the rest of the configuration is restored, and the plan
117
+ lists exactly what was ignored and why. Only a path that escapes the profile, a
118
+ dependency directory, a duplicate path, a malformed entry, or a document with no
119
+ usable `package.json` is a hard refusal.
120
+
121
+ ## Restore
122
+
123
+ Merge-style and reversible:
124
+
125
+ - Files in the backup are written; files only the local machine has stay.
126
+ - `package.json` is **merged**: dependencies and `dsh.profile.bundles` are
127
+ unioned, so plugins already installed on the target machine are kept. Where both
128
+ sides declare the same dependency the incoming spec wins — which is exactly why
129
+ a machine-local spec is dropped at export time rather than left to overwrite the
130
+ target's own.
131
+ - Every overwritten or created path is copied into
132
+ `<profile>/.dsh-config-sync/undo/<stamp>/` first, so the import can be undone
133
+ from the page or with the tool's `undo` action.
134
+ - Installed plugins are not part of a backup, so a restore leaves a manifest that
135
+ names packages this machine may not have. ③ lists them after the sync and
136
+ installs them one spec at a time; the same thing is available as
137
+ `GET /api/plugins` and `POST /api/plugins/install`. When the deployment
138
+ publishes no `pluginManager` service, the page says it cannot check rather than
139
+ showing an empty list.
140
+
141
+ ## GitHub Gist
142
+
143
+ Upload updates the Gist this profile remembers, or creates a secret one and
144
+ remembers it the first time; leave the id empty in 高级设置 and save to start a
145
+ different Gist, or paste an id/link to adopt one. Download reads
146
+ `dsh-profile-backup.json` from it and validates the document before anything is
147
+ written.
148
+
149
+ The token is never stored: paste one per session, or set `DSH_GITHUB_TOKEN` /
150
+ `GITHUB_TOKEN` on the host, or sign in with the `gh` CLI — the page offers a
151
+ "check token" button that reports which source answered. When none of the three
152
+ answers, the error names all three in that order and links to a token-creation
153
+ page with the `gist` scope pre-ticked, instead of the library's own
154
+ `Bad credentials`. A secret Gist is unlisted, **not private**: anyone with the
155
+ link can read it, and through the API only its owner can read it at all.
156
+
157
+ ## Agent tool
158
+
159
+ `config_backup` with `action`: `status`, `export`, `gist_upload`, `gist_read`,
160
+ `restore`, `undo`. Gist actions use the remembered cloud copy when `gistId` is
161
+ omitted, so "back this up" and "sync my configuration" work without an id.
162
+ `export` writes inside `<profile>/.dsh-config-sync/exports/`, and `restore`
163
+ reads only from inside the DSH home directory, so the tool cannot be used as a
164
+ file-system escape. `gist_upload` reports which dependencies were left out and
165
+ `status` says the same before anything is uploaded, so an agent can explain the
166
+ omission without reading the document.
167
+
168
+ ## Checks
169
+
170
+ ```sh
171
+ node test/run.mjs
172
+ ```
173
+
174
+ Five check files, each a separate process, all offline: profiles are temporary
175
+ directories, the GitHub HTTP layer is stubbed (and refuses every host but
176
+ `api.github.com`), and the only server any check talks to is its own loopback
177
+ port. They cover the document format and its exclusions, the machine-local
178
+ dependency drop and its report, the restore plan and undo, the union guarantee,
179
+ the missing-plugin computation and the install route against a stubbed plugin
180
+ manager (including the service-absent and service-throwing cases), the activation
181
+ contract, the route and tool surface, the first-run journey against the stubbed
182
+ GitHub, the token error's actionable text — and that the package still activates
183
+ after being packed with only the manifest's `files` list.
184
+
185
+ ## Which profile this plugin works on
186
+
187
+ A DSH process does **not** necessarily carry `DSH_PROFILE_DIR`. DSH Desktop
188
+ starts its host as
189
+ `DeepSeek Harness.exe --expose-internals …/dsh-desktop-host/lib/index.js <checkout> <profile dir> …`
190
+ with no profile variables at all — the `DSH_*` values a shell tool sees are
191
+ injected per call, not inherited by the host. So the profile is resolved from,
192
+ in order, and every source is checked against the filesystem before it is used:
193
+
194
+ 1. what the running host reports (`profileContext`) — the launcher owns the
195
+ location, so this wins when present;
196
+ 2. `DSH_PROFILE_DIR`, then `DSH_HOME` + `DSH_PROFILE` (a CLI-started DSH takes
197
+ these as instructions, and a missing directory is reported as such);
198
+ 3. the `<profile dir>` argument the desktop host is started with;
199
+ 4. the profile that has this plugin installed — the one running it;
200
+ 5. the only profile present.
201
+
202
+ If none of them answers, the page says so instead of backing up the wrong
203
+ directory. `/api/status` carries the source that answered as `profileSource`
204
+ (and the `config_backup` tool prints it in its `status` summary); the page shows
205
+ the profile it settled on at the bottom of 高级设置.
206
+
207
+ ## If the plugin does not load
208
+
209
+ 设置 → 插件 → 插件列表 shows one row per loaded entry, with its `fiberPhase` and,
210
+ when it fails, a one-line diagnostic. When this plugin fails, none of its routes
211
+ exist: the page then answers `操作失败。HTTP 404` and names the missing host half
212
+ itself.
213
+
214
+ Two failures seen while building this, both worth avoiding:
215
+
216
+ - **`Invalid effect`** — a `ctx.effect(...)` callback returned something other
217
+ than a disposer, and Cordis rejects the *whole row* for it (so the routes and
218
+ the `config_backup` tool both disappear). Work that owns no resource belongs in
219
+ a plain call inside `apply`, not in an effect.
220
+ - **`no-profile`** — the host was started without `DSH_PROFILE_DIR` and the
221
+ fallback chain could not name a profile. See above.
222
+
223
+ Toggling that entry off and on re-imports the module from disk, so a source fix
224
+ applies **without restarting DSH**. A restart is only needed when the row's own
225
+ name changed, because the bundle then has to be resolved again at boot.
226
+
227
+ ## Route surface
228
+
229
+ One `prefix` route on the bare web server:
230
+
231
+ ```
232
+ GET /dsh-profile-gist-sync/api/status
233
+ GET /dsh-profile-gist-sync/api/export[?include=machine]
234
+ POST /dsh-profile-gist-sync/api/settings { gistId?, includeMachine? }
235
+ POST /dsh-profile-gist-sync/api/sync { id?, token? }
236
+ POST /dsh-profile-gist-sync/api/preview { backup }
237
+ POST /dsh-profile-gist-sync/api/restore { backup, confirm: true }
238
+ POST /dsh-profile-gist-sync/api/undo {}
239
+ POST /dsh-profile-gist-sync/api/file/read { path }
240
+ POST /dsh-profile-gist-sync/api/gist/token { token? }
241
+ POST /dsh-profile-gist-sync/api/gist/upload { id?, token?, includeMachine? }
242
+ POST /dsh-profile-gist-sync/api/gist/read { id?, token? }
243
+ GET /dsh-profile-gist-sync/api/plugins
244
+ POST /dsh-profile-gist-sync/api/plugins/install {}
245
+ ```
246
+
247
+ `/api/sync` is `/api/gist/read` plus `/api/restore` in one step, restricted to a
248
+ Gist target — that restriction is what keeps it from being a general write
249
+ endpoint: the document still has to be a valid `dsh-profile-backup`.
250
+
251
+ `/api/plugins` answers what the profile declares and this machine lacks:
252
+
253
+ ```jsonc
254
+ // the manager answered
255
+ { "available": true, "reason": null, "checkedAt": "…",
256
+ "sources": { "plugins": true, "bundles": true },
257
+ "installed": ["@deepseek-ai/dsh-base"],
258
+ "missing": [{ "name": "some-plugin", "spec": "^1.0.0", "kind": "dependency",
259
+ "installSpec": "some-plugin@^1.0.0", "resolvable": true,
260
+ "note": null, "version": null }],
261
+ "counts": { "declared": 2, "installed": 1, "missing": 1, "installable": 1, "unresolved": 0 } }
262
+
263
+ // no usable manager: no `missing` array at all, so a reader that ignores
264
+ // `available` breaks instead of reporting a clean bill of health
265
+ { "available": false, "reason": "no-plugin-manager", "checkedAt": "…", "declared": 2 }
266
+ ```
267
+
268
+ `reason` is `no-plugin-manager` or `plugin-manager-error`. `/api/plugins/install`
269
+ takes no body, installs the resolvable entries one at a time, and answers the same
270
+ inventory plus what happened to each spec:
271
+
272
+ ```jsonc
273
+ { …the /api/plugins fields…,
274
+ "results": [{ "name": "some-plugin", "spec": "^1.0.0", "installSpec": "some-plugin@^1.0.0",
275
+ "outcome": "installed", "application": "restart-required", "version": "1.0.0",
276
+ "message": null, "pendingBuilds": [] }],
277
+ "outcomeCounts": { "installed": 1, "already-present": 0, "failed": 0, "skipped": 0 },
278
+ "restart": true }
279
+ ```
280
+
281
+ `outcome` is `installed`, `already-present`, `failed`, or `skipped`; the last is a
282
+ `link:`/`workspace:` spec this machine cannot install, whose `message` carries the
283
+ `note` (`local-path` / `workspace-protocol`). A `failed` row carries the manager's
284
+ own diagnostic. Both routes answer `200` when the service is absent — the degraded
285
+ answer is a fact, not an error — and `/api/gist/upload` additionally returns
286
+ `dropped` and `droppedEntries` describing the dependencies left out of the upload.
287
+
288
+ Every request must pass the host's own gate (`connection.requestRejection`)
289
+ when the host publishes one, and its Host must be loopback or an authority the
290
+ deployment declared.
291
+
292
+ ## Licence
293
+
294
+ MIT. `icon.svg` is the plugin's own mark; `assets/icon-256.png` is the raster
295
+ form the plugin market asks for, generated by `assets/make-icon.py`.
Binary file
@@ -0,0 +1,64 @@
1
+ """Render the storefront icon as a raster PNG.
2
+
3
+ The plugin market's catalogue accepts only GitHub-hosted raster images for a
4
+ storefront tile (SVG is refused), so the same mark as `icon.svg` is drawn here:
5
+ a rounded blue tile, a white cloud, and a downward arrow into it.
6
+
7
+ python assets/make-icon.py
8
+ """
9
+ from pathlib import Path
10
+
11
+ from PIL import Image, ImageDraw
12
+
13
+ SIZE = 256
14
+ SCALE = 4 # draw large, then downsample for clean edges
15
+ BLUE_TOP = (79, 143, 247)
16
+ BLUE_BOTTOM = (43, 98, 214)
17
+ ARROW = (31, 79, 176)
18
+ WHITE = (255, 255, 255)
19
+
20
+
21
+ def lerp(a, b, t):
22
+ return tuple(round(x + (y - x) * t) for x, y in zip(a, b))
23
+
24
+
25
+ def main():
26
+ size = SIZE * SCALE
27
+ image = Image.new("RGBA", (size, size), (0, 0, 0, 0))
28
+
29
+ # Rounded tile with a vertical gradient, masked by the rounded rectangle.
30
+ gradient = Image.new("RGBA", (size, size))
31
+ pen = ImageDraw.Draw(gradient)
32
+ for y in range(size):
33
+ pen.line([(0, y), (size, y)], fill=lerp(BLUE_TOP, BLUE_BOTTOM, y / size) + (255,))
34
+ mask = Image.new("L", (size, size), 0)
35
+ ImageDraw.Draw(mask).rounded_rectangle([0, 0, size - 1, size - 1], radius=int(size * 0.22), fill=255)
36
+ image.paste(gradient, (0, 0), mask)
37
+
38
+ draw = ImageDraw.Draw(image)
39
+
40
+ # The cloud: three overlapping discs on a flat base, as in the SVG path.
41
+ unit = size / 64
42
+ cloud = WHITE + (242,)
43
+ draw.ellipse([22 * unit, 21 * unit, 40 * unit, 39 * unit], fill=cloud)
44
+ draw.ellipse([33 * unit, 26 * unit, 46 * unit, 39 * unit], fill=cloud)
45
+ draw.rounded_rectangle([20 * unit, 28 * unit, 45 * unit, 39 * unit], radius=5 * unit, fill=cloud)
46
+
47
+ # The arrow pointing down into the cloud.
48
+ stroke = 3.4 * unit
49
+ draw.line([32 * unit, 41 * unit, 32 * unit, 52 * unit], fill=ARROW, width=round(stroke))
50
+ draw.line([26.5 * unit, 46 * unit, 32 * unit, 52 * unit], fill=ARROW, width=round(stroke))
51
+ draw.line([37.5 * unit, 46 * unit, 32 * unit, 52 * unit], fill=ARROW, width=round(stroke))
52
+
53
+ # The two white ticks either side, as in the SVG.
54
+ tick = 3 * unit
55
+ draw.line([18 * unit, 46 * unit, 24 * unit, 46 * unit], fill=WHITE + (230,), width=round(tick))
56
+ draw.line([40 * unit, 46 * unit, 46 * unit, 46 * unit], fill=WHITE + (230,), width=round(tick))
57
+
58
+ out = Path(__file__).with_name("icon-256.png")
59
+ image.resize((SIZE, SIZE), Image.LANCZOS).save(out)
60
+ print(f"wrote {out} ({out.stat().st_size} bytes, {SIZE}x{SIZE})")
61
+
62
+
63
+ if __name__ == "__main__":
64
+ main()
Binary file