@1e0zj/dsh-plugin-mall 0.3.2 → 0.3.4

package/README.md

@@ -2,7 +2,7 @@
 
 **An open plugin marketplace for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh): search every GitHub repo tagged `topic:dsh-plugin`, automatically verify which ones are real dsh plugins, install and update with one click.**
 
-[中文说明](#中文说明) · [Install](#install) · [Why another marketplace](#why-another-marketplace)
+[中文说明](#中文说明) · [Install](#install) · [Why another marketplace](#why-another-marketplace) · [Roadmap](ROADMAP.md)
 
 Two surfaces: a **Settings → Plugins → Marketplace** tab in the dsh web UI, and five agent tools usable from any session.
 
@@ -73,9 +73,11 @@ node <profile>/node_modules/@1e0zj/dsh-plugin-mall/src/cli.js guard launch --pro
 
 **A plain `dsh web` already resolves pending installs.** The marketplace plugin runs
 recovery when it loads: reaching that point proves dsh booted far enough to compose
-the profile, so the pending marker is committed (or rolled back when the profile
-fails validation). Without this a single install would wedge the profile — every
-later install and uninstall refuses while a marker is outstanding.
+the profile, so the pending marker is committed — or rolled back, either because the
+profile fails validation or because the install was left paused at the build-script
+approval gate (an unapproved install is never committed, however healthy it looks).
+Without this a single install would wedge the profile — every later install and
+uninstall refuses while a marker is outstanding.
 
 **`guard launch` is still strictly better**, because it also covers what a plain
 start cannot: a plugin that boots fine and then crashes seconds later. It checks the
@@ -83,13 +85,42 @@ profile's pending-install marker before starting the command after `--`:
 
 - **No pending install** — the command runs as-is, inheriting the terminal, and its exit code is preserved.
 - **Clearly broken on disk** — the profile is rolled back to its pre-install snapshot *before* launch, then the command starts on the restored state.
-- **Alive through the grace period** (default **10 seconds**; `--grace-ms <ms>` to change) — the pending snapshot is committed and the wrapper keeps waiting on the process.
+- **Alive through the grace period** (default **10 seconds**; `--grace-ms <ms>` to change) — the pending snapshot is committed and the wrapper keeps waiting on the process. An install still paused at the approval gate is rolled back instead: surviving probation only proves the JS loads, not that you approved its build scripts.
 - **Exits 0 inside the grace period** (one-shot command) — the pending snapshot is committed.
 - **Crashes or exits nonzero inside the grace period** — the profile is rolled back and the *exact same command* is restarted once with the restored state (never in a loop); the restarted process's exit code is preserved. SIGINT/SIGTERM are forwarded to the child where the platform supports it; on Windows `.cmd`/`.bat` shims go through `%ComSpec%` with strict per-argument quoting.
 
 Limitations: the grace window is the probation period — a failure that only surfaces **after** it (a plugin that crashes minutes in, or on a specific interaction) cannot be rolled back automatically, because committing deletes the active snapshot and `guard recover` then has nothing to restore. `guard validate` still diagnoses the on-disk state, but a post-commit failure needs manual repair — uninstall and reinstall the plugin, or restore a backup you kept separately. Both commands do only **static on-disk validation**; neither proves the plugin actually loads. A corrupt pending marker fails closed: the command is not launched and no unvalidated path is deleted. Preserve the snapshot and repair or restore a trustworthy marker, then run `guard recover`; quarantine the marker only after you have independently verified the profile, or decided to abandon automatic recovery.
 
 
+## dsh won't start after an update? (affects 0.2.0 – 0.3.2, fixed in 0.3.3)
+
+Symptom: `dsh web` exits with `cannot resolve profile bundle "<package>"`.
+
+Cause: **updating an already-installed plugin** into a rollback (most often the
+target carries build scripts and the flow paused at the approval card) could lose
+the package — the rollback's reinstall of the old version was fooled by pnpm's
+"Already up to date" short-circuit, so the plugin left node_modules while its
+bundles declaration stayed. Fresh installs and removals are unaffected.
+
+Recovery: add the package back exactly as the profile's `package.json` declares
+it, then run `dsh web`.
+
+```bash
+# <profile> = %USERPROFILE%\.dsh\profiles\web  or  ~/.dsh/profiles/web
+# npm package — package.json says "dsh-better-sidebar": "^0.13.1"
+pnpm --dir <profile> add "dsh-better-sidebar@^0.13.1" --ignore-scripts
+# GitHub source — package.json says "dsh-at-file": "github:omdsh-dev/dsh-at-file"
+pnpm --dir <profile> add "github:omdsh-dev/dsh-at-file" --ignore-scripts
+```
+
+> Do not reach for 0.3.2's `dsh-plugin-guard recover` here. Its per-package
+> fallback refuses `^` (a cmd metacharacter) and skips `github:` entirely, and
+> pnpm writes nearly every dependency with one or the other — so the fallback
+> never fires and recovery fails closed. Fixed on main: the fallback now pins the
+> version (or commit) the lockfile resolved. Fixed in 0.3.3 — on that version
+> `dsh-plugin-guard recover` does repair this.
+
+
 ## Agent tools
 
 | Tool | What it does |
@@ -106,6 +137,8 @@ Limitations: the grace window is the probation period — a failure that only su
 
 **dsh 插件市场** — 搜索 GitHub `dsh-plugin` 话题下的 DeepSeek Harness 插件仓库，自动验证哪些是真 dsh 插件，一键安装与更新。
 
+[路线图](ROADMAP.md)（安全 > 便捷 > 精简，以及明确不做的）
+
 与策展列表不同：**任何打上 `topic:dsh-plugin` 的仓库推送后立即可被发现**——无需投稿、无需审批。为保证开放性可用，做了这些事：
 
 - **自动验证**：逐仓库拉取 `package.json`（jsDelivr/raw 双源 CDN，不占 API 配额），按官方 `dsh.bundle` / `dsh.client` 声明打徽章；默认"只看已验证"视图过滤约 73% 的话题噪音
@@ -191,22 +224,48 @@ node <profile>/node_modules/@1e0zj/dsh-plugin-mall/src/cli.js guard launch --pro
 ```
 
 **普通的 `dsh web` 就会了结 pending 安装。** 本插件加载时即执行恢复——能加载
-本身就证明 dsh 已经组装好 profile、启动到了这一步，于是提交 pending 标记
-（profile 校验不过则回滚）。没有这一步的话，装完一个插件就会把 profile 卡住：
-只要标记还在，之后所有安装和卸载都会被拒绝。
+本身就证明 dsh 已经组装好 profile、启动到了这一步，于是提交 pending 标记；两种
+情况改为回滚：profile 校验不过，或者那次安装停在构建脚本批准闸而未获批准
+（没批准的安装绝不提交，哪怕它看起来一切正常）。没有这一步的话，装完一个插件
+就会把 profile 卡住：只要标记还在，之后所有安装和卸载都会被拒绝。
 
 **`guard launch` 仍然更强**，因为它覆盖普通启动覆盖不了的情况：插件启动正常、
 几秒后才崩。它在启动 `--` 之后的命令前检查该 profile 的 pending 安装标记：
 
 - **无 pending 安装** —— 命令原样运行（继承终端），透传退出码；
 - **静态校验明显过不了** —— 启动*之前*先把 profile 回滚到安装前快照，再在恢复后的状态上启动；
-- **活过缓刑期**（默认 **10 秒**，`--grace-ms <ms>` 可调）—— 提交 pending 快照，包装器继续守候该进程；
+- **活过缓刑期**（默认 **10 秒**，`--grace-ms <ms>` 可调）—— 提交 pending 快照，包装器继续守候该进程；但仍停在批准闸的安装改为回滚：活过缓刑期只证明 JS 能加载，不证明你批准了它的构建脚本；
 - **缓刑期内以 0 退出**（一次性命令）—— 同样提交 pending 快照；
 - **缓刑期内崩溃或非零退出** —— 回滚 profile，并用恢复后的状态**原样重启同一命令一次**（绝不循环），透传重启进程的退出码。支持的平台会把 SIGINT/SIGTERM 转发给子进程；Windows 上 `.cmd`/`.bat` 经 `%ComSpec%` 启动，逐参数严格加引号。
 
 限制：缓刑期就是观察期——**之后**才暴露的故障（跑了几分钟才崩、或某个特定操作才触发）无法自动回滚：提交会删掉当前快照，此时 `guard recover` 已无可恢复的东西。`guard validate` 仍能诊断落盘状态，但提交之后的故障只能手工修复——卸载并重装插件（或恢复你另行保留的备份）。两条命令都只做**静态落盘校验**，都不证明插件真的能加载。pending 标记损坏时关闭式失败：不启动命令、不删除任何未校验路径。要**保留快照**、修复或恢复一个可信的标记后再跑 `guard recover`；只有在你已经独立核实过 profile、或决定放弃自动恢复之后，才去隔离（删除/移走）标记。
 
 
+## 升级后 dsh 起不来？（0.2.0 – 0.3.2 受影响，0.3.3 已修复）
+
+症状：`dsh web` 报 `cannot resolve profile bundle "<包名>"` 直接退出。
+
+原因：**更新已装插件**时若走到回滚（最常见：目标插件带构建脚本、停在批准卡），
+回滚里「装回旧版本」的一步会被 pnpm 的 "Already up to date" 空转骗过——包从
+node_modules 消失而 bundles 声明还在。新装、卸载不受影响。
+
+恢复：照 profile `package.json` 里原本的写法把包装回去，然后 `dsh web`。
+
+```bash
+# <profile> = %USERPROFILE%\.dsh\profiles\web 或 ~/.dsh/profiles/web
+# npm 包 —— package.json 里是 "dsh-better-sidebar": "^0.13.1"
+pnpm --dir <profile> add "dsh-better-sidebar@^0.13.1" --ignore-scripts
+# GitHub 源 —— package.json 里是 "dsh-at-file": "github:omdsh-dev/dsh-at-file"
+pnpm --dir <profile> add "github:omdsh-dev/dsh-at-file" --ignore-scripts
+```
+
+> 别指望 0.3.2 的 `dsh-plugin-guard recover` 修这个：它的 per-package 兜底会
+> 拒掉 `^`（cmd 转义符），`github:` 更是整个跳过，而 pnpm 存依赖几乎不是前者
+> 就是后者——兜底一次也不会触发，恢复只会 fail-closed。main 上已修：兜底改钉
+> lockfile 解析出的版本（或 commit）。0.3.3 已修复——那个版本的
+> `dsh-plugin-guard recover` 确实能修这个故障。
+
+
 ## 工作原理
 
 - 双面包（dual-face）插件：`dsh.bundle` 半边挂在 **host 平面**（profile bundle 层），
@@ -265,10 +324,14 @@ node <profile>/node_modules/@1e0zj/dsh-plugin-mall/src/cli.js guard launch --pro
   三处。`allowBuilds` 是持久化的安全配置，所以安装最终失败时这次放宽会被
   **撤销** —— 否则一个没装成的插件会让那个包名从此静默获得构建脚本执行权。
 - 配置（`cordis.patch.yml` 中可改）：`defaultProfile`（默认装进哪个 profile，
-  默认 `web`）、`apiBase`（GitHub API 地址）、`npmRegistry`（npm 查询源，留空
-  则跟随 pnpm 实际安装源）、`rawSources`（验证用的 package.json 源模板列表，
-  `{repo}` 会替换成 owner/name，留空用内置的 jsDelivr + raw 双源）、
-  `perPageMax`（搜索单页上限）、`allowRestart`（是否允许一键重启，默认 `true`）。
+  **不配则跟随本进程实际启动的那个** —— 从 loader 的配置树锚点 `ctx.baseUrl`
+  推导，那正是 profile 目录；推不出来才退回 `web` 并打日志）、`apiBase`
+  （GitHub API 地址）、`npmRegistry`（npm 查询源，留空则跟随 pnpm 实际安装
+  源）、`rawSources`（验证用的 package.json 源模板列表，`{repo}` 会替换成
+  owner/name，留空用内置的 jsDelivr + raw 双源）、`perPageMax`（搜索单页上限，
+  1–30 的整数，默认 30）、`allowRestart`（是否允许一键重启，默认 `true`）。
+  自动识别同时决定**启动恢复作用在哪个 profile 上**：能在此提交半装状态，
+  凭据是「本次启动成功了」，而那只能证明启动的那个 profile 是好的。
 
 ## 发布
 

package/cordis.patch.yml

@@ -5,8 +5,19 @@
     - id: dsh-plugin-mall
       name: '@1e0zj/dsh-plugin-mall'
       config:
-        # The profile market_install targets when the caller names none.
-        defaultProfile: web
+        # defaultProfile is deliberately NOT set here.
+        #
+        # This file ships inside the package and is read as a bundle layer by
+        # every profile that installs the marketplace, so anything written here
+        # is an explicit config value in ALL of them. Pinning `defaultProfile:
+        # web` (as this file used to) meant a marketplace running in any other
+        # profile still defaulted its installs at web — and the value looked
+        # like the user's own choice, so nothing could tell it apart from one.
+        #
+        # Left unset, the plugin follows the profile this process actually
+        # booted (derived from the loader's config-tree anchor). Set it only to
+        # override that:
+        #   defaultProfile: web
         # GitHub REST API base (override for self-hosted mirrors/proxies).
         apiBase: https://api.github.com
         # npm registry for anti-squatting, update checks and the host-dependency

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1e0zj/dsh-plugin-mall",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "dsh 插件市场：搜索 GitHub dsh-plugin 话题下的插件仓库，一键安装到本地 dsh profile（agent 工具 + 设置页插件市场 tab）",
   "type": "module",
   "main": "src/index.js",

package/src/cli.js

@@ -40,13 +40,18 @@ import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
+  clearPendingApprovalPause,
   commitPendingSnapshot,
   createProfileSnapshot,
+  describeRollbackRebuild,
   listPendingSnapshots,
+  markPendingApprovalPause,
   markPendingSnapshot,
+  pendingApprovalPaused,
   pnpmGuardEnv,
   preflightInstall,
   readPendingSnapshot,
+  readValidatedPendingSnapshot,
   recoverAll,
   recoverProfile,
   resolveDshHome,
@@ -380,6 +385,8 @@ function cmdRecover({ home, profileDir }) {
     } else if (entry.action === "rolled-back") {
       console.log(`ROLLED BACK ${scope}: ${(entry.issues ?? []).map((issueEntry) => issueEntry.title).join("; ") || "profile would not load"}`);
       if (entry.removed?.length) console.log(`  removed from node_modules: ${entry.removed.join(", ")}`);
+      const rebuild = describeRollbackRebuild(entry.rebuild);
+      if (rebuild !== undefined) console.log(`  node_modules rebuild: ${rebuild}`);
     } else if (entry.action === "none") {
       console.log(`no pending  ${scope}`);
     } else {
@@ -693,9 +700,25 @@ async function runPlain(command, args) {
  * Commit the pending snapshot once startup probation passes. A commit failure
  * is a warning, not a launch failure — the process is already running and
  * healthy, and the marker simply stays pending for the next launch.
+ *
+ * An approval-paused marker must never commit: the new version sits there with
+ * its build scripts never approved, so staying alive only proves the JS loads.
+ * Roll it back to the pre-install snapshot instead (a rollback failure keeps
+ * the marker for the next attempt, same as recoverProfile).
  */
 function commitLaunchSnapshot(profileDir) {
   try {
+    let pending;
+    try {
+      pending = readValidatedPendingSnapshot(profileDir);
+    } catch {
+      pending = undefined; // unreadable marker: leave it to guard recover
+    }
+    if (pending !== undefined && pendingApprovalPaused(pending) !== undefined) {
+      rollbackPendingSnapshot(profileDir);
+      console.log(`[guard] startup probation passed, but the install was abandoned at the approval gate — profile rolled back for ${profileDir}`);
+      return;
+    }
     commitPendingSnapshot(profileDir);
     console.log(`[guard] startup probation passed — pending snapshot committed for ${profileDir}`);
   } catch (error) {
@@ -1156,6 +1179,31 @@ async function selfTest() {
     const validated = validateInstalledProfile(profileDir);
     if (validated.ok !== true) throw new Error("healthy profile should validate clean (cli)");
 
+    // commitLaunchSnapshot: a marker paused at the approval gate must roll back
+    // instead of committing even after a healthy probation — the candidate sits
+    // there with its build scripts never approved, and committing would delete
+    // the only rollback snapshot. Layout keeps the candidate a NEW dependency
+    // so the rollback prunes node_modules without spawning pnpm.
+    {
+      const pauseProfile = join(root, "pause-home", "profiles", "web");
+      mkdirSync(join(pauseProfile, "node_modules"), { recursive: true });
+      writeFileSync(join(pauseProfile, "package.json"), JSON.stringify({ dependencies: {} }));
+      writeFileSync(join(pauseProfile, "cordis.patch.yml"), "[]\n");
+      const snap = createProfileSnapshot(pauseProfile, { fixture: true });
+      markPendingSnapshot(snap, { spec: "good@2.0.0", preflight: { candidate: { name: "good", version: "2.0.0", kind: "bundle" } } });
+      // 暂停现场：候选已装、声明已写，静态校验过得去——正是不许提交的原因。
+      writeFileSync(join(pauseProfile, "package.json"), JSON.stringify({ dependencies: { good: "^2.0.0" } }));
+      mkdirSync(join(pauseProfile, "node_modules", "good"), { recursive: true });
+      writeFileSync(join(pauseProfile, "node_modules", "good", "package.json"), JSON.stringify({ name: "good", version: "2.0.0" }));
+      markPendingApprovalPause(pauseProfile);
+      commitLaunchSnapshot(pauseProfile);
+      if (readPendingSnapshot(pauseProfile) !== undefined) throw new Error("commitLaunchSnapshot must consume (roll back) an approval-paused marker");
+      if (existsSync(snap.dir)) throw new Error("the paused rollback must delete the snapshot dir");
+      if (JSON.parse(readFileSync(join(pauseProfile, "package.json"), "utf8")).dependencies?.good !== undefined) {
+        throw new Error("the paused rollback must restore the pre-install manifest");
+      }
+    }
+
     // guarded remove: exact official argv + shell:false runner seam, snapshot
     // before mutation, immediate commit after a statically safe removal.
     {

package/src/client.js

@@ -188,6 +188,7 @@ window.__ModuleLoader__.load({
                 status: snapshot.status,
                 detail: snapshot.detail,
                 needsApproval: snapshot.needsApproval,
+                staleOnRestart: snapshot.staleOnRestart,
                 approvalToken: snapshot.approvalToken,
                 kind: snapshot.kind,
                 output: output,
@@ -249,6 +250,7 @@ window.__ModuleLoader__.load({
             spec: snap.spec,
             detail: snap.detail,
             needsApproval: snap.needsApproval,
+            staleOnRestart: snap.staleOnRestart,
             approvalToken: snap.approvalToken,
             kind: snap.kind,
             output: entry.output || "",
@@ -259,9 +261,13 @@ window.__ModuleLoader__.load({
         // 不在本次服务器列表里的条目属于上一次宿主会话（进程重启后
         // tracker 清空）。已兑现的直接翻篇撤掉：completed 的重启已经
         // 发生；needsApproval 暂停的批准卡片已随进程失效（事务由启动
-        // 恢复处置），留着只会让人点一个必然失败的按钮。running 的标
-        // 中断，别让轮询对着不存在的 id 空转。failed 保留——日志还有
-        // 排障价值。这个判据不依赖 finishedAt（旧镜像里没有该字段）。
+        // 恢复处置），留着只会让人点一个必然失败的按钮；staleOnRestart
+        // 的失败是「被另一个未了结事务挡住」，而那个事务必然已被启动恢复
+        // 处置——它的报错是现在时写的（「还没做完」「现在无法安装」），
+        // 留到重启之后会被当成当前状态读，而它描述的情形已经不存在。
+        // running 的标中断，别让轮询对着不存在的 id 空转。其余 failed
+        // 保留——网络、预检阻断这类原因重启后可能仍然成立，日志有排障
+        // 价值。这个判据不依赖 finishedAt（旧镜像里没有该字段）。
         for (var key in next) {
           if (serverIds[key]) continue;
           var stale = next[key];
@@ -270,7 +276,9 @@ window.__ModuleLoader__.load({
               status: "killed",
               detail: "宿主进程已重启，该任务的记录随之丢失",
             });
-          } else if (stale.status === "completed" || (Array.isArray(stale.needsApproval) && stale.needsApproval.length > 0)) {
+          } else if (stale.status === "completed"
+            || stale.staleOnRestart === true
+            || (Array.isArray(stale.needsApproval) && stale.needsApproval.length > 0)) {
             delete next[key];
           }
         }