@1e0zj/dsh-plugin-mall 0.3.5 → 0.4.0

package/README.md

@@ -11,12 +11,12 @@ Two surfaces: a **Settings → Plugins → Marketplace** tab in the dsh web UI,
 Curated lists only show what has been reviewed and merged. This marketplace is open by construction: **any repo tagged `topic:dsh-plugin` is discoverable the moment it is pushed** — no submission, no approval queue. To keep that openness usable:
 
 - **Automatic verification** — every search result's `package.json` is fetched (jsDelivr/raw dual-source CDN, no API quota) and checked for the official `dsh.bundle` / `dsh.client` manifest. Verified plugins get a green badge; the default "verified only" view filters out ~73% of topic noise (empty repos and unrelated projects riding the tag).
-- **Browse-time compatibility badges** — each card is also statically scanned against your profile before you click anything: declared conflicts, exclusive groups, loader-id collisions (from the repo's patch file), host-module shadowing, and peer/Node/OS ranges. Cards show 适配 / 有风险 / 冲突 / 适配未知 accordingly — advisory only; the install preflight remains the enforcing gate.
+- **Browse-time compatibility badges** — each card is also statically scanned against your profile before you click anything: declared conflicts, exclusive groups, loader-id collisions (from the repo's patch file), rows the candidate's patch would switch off or reconfigure in the profile you already run, host-module shadowing, and peer/Node/OS ranges. Cards show 适配 / 有风险 / 冲突 / 适配未知 accordingly — advisory only; the install preflight remains the enforcing gate.
 - **Anti-squatting** — an install prefers the npm tarball only when the registry entry's `repository` URL points back to the same GitHub repo; anything else falls back to the explicit `github:` spec.
 - **npm-first installs** — registry tarballs are smaller than whole-repo GitHub downloads and come with integrity checks. Lookups follow the registry pnpm actually installs from (profile `.npmrc` → `pnpm config get registry` → npmjs), so a mirror user keeps npm-first instead of silently falling back to whole-repo clones.
 - **Update management** — installed plugins are compared against the registry `latest`; one-click update per plugin.
-- **Conflict guard** — every install runs an isolated preflight first: the candidate is installed with scripts disabled into a throwaway directory and scanned against the live profile for loader-id collisions, double mounts, host-module shadowing and version/OS/peer ranges. A hard conflict is blocked, warnings require explicit confirmation. The profile's load-bearing files are snapshotted before `pnpm` touches them and restored on failure. A pending install is resolved on the next start, however you start it: this plugin runs recovery as it loads, which only happens because dsh booted far enough to compose the profile. Starting through `guard launch` adds a grace window on top, so a plugin that boots and then crashes seconds later is rolled back and restarted once (see [Startup protection](#startup-protection-guard-cli)).
-- **Resilience** — rate-limit circuit breaker, GitHub's 1000-result search window handled gracefully, `corepack enable pnpm` self-heal when pnpm is missing, one-click dsh restart (loopback-only, `allowRestart: false` to disable).
+- **Conflict guard** — every install runs an isolated preflight first: the candidate is installed with scripts disabled into a throwaway directory and scanned against the live profile for loader-id collisions, double mounts, host-module shadowing and version/OS/peer ranges. A patch layer is not read entry by entry but composed the way the loader applies it — the profile is assembled with and without the candidate's layer, in the position dsh would apply it, and the two trees are diffed. That composition is checked against the loader's own `applyEntryPatches` on every test run, over fixed shapes and 300 generated patch combinations, so "what dsh would boot" is not a guess. What gets reported is what would actually change: disabling, re-enabling or replacing the config of someone else's rows warns and names them, past ten such rows the candidate is a rival composition rather than an addition and is blocked, and a bundle that is itself another front door (own `bin`, terminal peers, no browser half) is blocked once it switches rows on or off or rewrites a protection row — the fingerprint corroborates, it never blocks on its own. A hard conflict is blocked, warnings require explicit confirmation. The profile's load-bearing files are snapshotted before `pnpm` touches them and restored on failure. A pending install is resolved on the next start, however you start it: this plugin runs recovery as it loads, which only happens because dsh booted far enough to compose the profile. Starting through `guard launch` adds a grace window on top, so a plugin that boots and then crashes seconds later is rolled back and restarted once (see [Startup protection](#startup-protection-guard-cli)).
+- **Resilience** — rate-limit circuit breaker, GitHub's 1000-result search window handled gracefully, `corepack enable pnpm` self-heal when pnpm is missing, one-click dsh restart (loopback-only, `allowRestart: false` to disable). The successor waits for the outgoing host to be gone before it binds — starting into an occupied port would read as "the pending plugin crashed dsh" and roll back an install that was fine. It leaves no stray console behind and does not re-open the browser, because the page that asked for the restart is still there and reconnects on its own; whatever the restart prints lands in `<home>/guard/restart-<profile>.log`.
 
 ## Install
 
@@ -149,12 +149,12 @@ pnpm --dir <profile> add "github:omdsh-dev/dsh-at-file" --ignore-scripts
 与策展列表不同：**任何打上 `topic:dsh-plugin` 的仓库推送后立即可被发现**——无需投稿、无需审批。为保证开放性可用，做了这些事：
 
 - **自动验证**：逐仓库拉取 `package.json`（jsDelivr/raw 双源 CDN，不占 API 配额），按官方 `dsh.bundle` / `dsh.client` 声明打徽章；默认"只看已验证"视图过滤约 73% 的话题噪音
-- **浏览期适配徽章**：点安装之前，每张卡片就已对照你的 profile 做过一次静态扫描——声明冲突、独占组、loader-id 冲突（取自仓库补丁文件）、宿主模块遮蔽、peer/Node/OS 范围；卡片上直接显示 适配 / 有风险 / 冲突 / 适配未知。徽章只是提示，真正的拦截闸门仍是安装预检
+- **浏览期适配徽章**：点安装之前，每张卡片就已对照你的 profile 做过一次静态扫描——声明冲突、独占组、loader-id 冲突（取自仓库补丁文件）、候选包的补丁会停用或改写你当前 profile 里的哪些行、宿主模块遮蔽、peer/Node/OS 范围；卡片上直接显示 适配 / 有风险 / 冲突 / 适配未知。徽章只是提示，真正的拦截闸门仍是安装预检
 - **防抢注**：仅当 npm registry 条目的 `repository` 指回同一 GitHub 仓库时才用 npm 安装，否则回退 `github:` 源
 - **npm 优先安装**：registry tarball 比整仓库下载更小且带完整性校验；查询用的 registry 跟随 pnpm 实际安装源（profile `.npmrc` → `pnpm config get registry` → npmjs），换了镜像也不会退化成整仓库克隆
 - **更新管理**：已装插件与 registry `latest` 比对，逐个一键更新
-- **冲突防护**：每次安装先跑隔离预检——候选包在一次性目录里以禁用脚本的方式装好后，对照 live profile 扫描 loader-id 冲突、重复挂载、宿主模块遮蔽和版本/OS/peer 范围；硬冲突直接拦截，警告需显式确认。安装前给 profile 的承重文件拍快照、失败即回滚；pending 安装在下次启动时自动了结，**不挑启动方式**：本插件加载时就跑恢复，而能加载本身就证明 dsh 已经组装好 profile、活到了这一步。经 `guard launch` 启动则多一层观察期——插件启动几秒后才崩的情况也能回滚并原样重启一次（见下方「启动保护」）。
-- **工程韧性**：限流熔断、GitHub 5xx/超时退避重试（504 瞬时故障不再直达用户）、GitHub 1000 条搜索上限优雅处理、pnpm 缺失时 `corepack` 自愈、一键重启 dsh（仅 loopback，可 `allowRestart: false` 关闭）
+- **冲突防护**：每次安装先跑隔离预检——候选包在一次性目录里以禁用脚本的方式装好后，对照 live profile 扫描 loader-id 冲突、重复挂载、宿主模块遮蔽和版本/OS/peer 范围。补丁不是逐条读，而是**按 loader 的方式组装**——把候选包的层放进 dsh 会放的位置，装前装后各组装一棵树再逐行比对。这套组装每次跑测试都会和 loader 自己的 `applyEntryPatches` 对拍（固定形状 + 300 组随机生成的补丁组合），所以「dsh 会装出什么树」不是猜的。报出来的是真正会变的东西：停用、重新启用、或替换别人整块 config，都点名是哪几条 id 并警告；超过十条就不是叠加而是另一套组合，直接拦截；候选包本身就是另一套门面（自带 bin、依赖终端栈、没有浏览器半边）时，只要它停用/启用了行、或改了沙箱审批这类保护行，就直接拦截——指纹只做佐证，单凭它不拦。硬冲突直接拦截，警告需显式确认。安装前给 profile 的承重文件拍快照、失败即回滚；pending 安装在下次启动时自动了结，**不挑启动方式**：本插件加载时就跑恢复，而能加载本身就证明 dsh 已经组装好 profile、活到了这一步。经 `guard launch` 启动则多一层观察期——插件启动几秒后才崩的情况也能回滚并原样重启一次（见下方「启动保护」）。
+- **工程韧性**：限流熔断、GitHub 5xx/超时退避重试（504 瞬时故障不再直达用户）、GitHub 1000 条搜索上限优雅处理、pnpm 缺失时 `corepack` 自愈、一键重启 dsh（仅 loopback，可 `allowRestart: false` 关闭）。重启会**等旧进程真正退出**再绑端口——抢在端口没释放时启动，会被判成「新装的插件把 dsh 搞崩了」，把一次本来正常的安装回滚掉。重启后不留控制台窗口、也不再重开浏览器：发起重启的那个页面还在，会自己重连；重启过程的输出写进 `<home>/guard/restart-<profile>.log`（想停 dsh 用任务管理器结束 node 进程）
 
 ## 安装
 

package/package.json

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

package/src/cli.js

@@ -637,6 +637,42 @@ function resolveWindowsCommand(command) {
   return command;
 }
 
+/** How long `--await-exit` waits for the outgoing host before giving up. */
+const AWAIT_EXIT_TIMEOUT_MS = 30000;
+/** Settle time after the pid is gone, before the successor binds the port. */
+const PORT_SETTLE_MS = 400;
+
+const delay = (ms) => new Promise((resolvePromise) => { setTimeout(resolvePromise, ms); });
+
+/**
+ * Poll until `pid` is gone, or the timeout elapses.
+ *
+ * `kill(pid, 0)` is the portable liveness probe: it delivers no signal and
+ * throws ESRCH once the process is gone. EPERM means it exists under another
+ * owner — still alive, so keep waiting rather than racing it.
+ *
+ * A pid is only meaningful because the caller is the process that spawned us
+ * and named itself. It can still be recycled in principle; the bounded wait
+ * and the refusal on timeout keep that from turning into a hang.
+ *
+ * @returns true when the process is gone, false on timeout.
+ */
+async function waitForProcessExit(pid, timeoutMs, pollMs = 100) {
+  const target = Number(pid);
+  if (!Number.isInteger(target) || target <= 0) return true; // nothing to wait for
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      process.kill(target, 0);
+    } catch (error) {
+      if (error?.code === "ESRCH") return true;
+      if (error?.code !== "EPERM") return true; // unprobeable: do not block the restart on it
+    }
+    if (Date.now() >= deadline) return false;
+    await delay(pollMs);
+  }
+}
+
 /**
  * Spawn the command after `--` with inherited stdio. POSIX uses shell:false so
  * the argv reaches execvp untouched. On Windows a bare name is first resolved
@@ -644,8 +680,25 @@ function resolveWindowsCommand(command) {
  * so they go through %ComSpec% with every token strictly quoted; .exe/.com and
  * explicit paths spawn directly with shell:false.
  */
+/**
+ * Whether to stop Windows conjuring a console for the child.
+ *
+ * Inherit the console we have; never create one we do not. Run from a terminal
+ * our stdio IS that terminal, the child attaches to it, and hiding would cost
+ * the interactive session its Ctrl+C. Run from the detached restart our stdio
+ * is the log file and we hold no console at all, so the child would be handed
+ * a brand-new window — blank, since its output goes to the log — which is the
+ * stray console a restart used to leave on screen. Every subprocess this
+ * package spawns already passes `windowsHide` (installer.js, six call sites),
+ * so nothing downstream depends on inheriting a visible console.
+ */
+function hideChildConsole() {
+  return process.platform === "win32" && process.stdout.isTTY !== true;
+}
+
 function spawnCommand(command, args) {
   const resolved = process.platform === "win32" ? resolveWindowsCommand(command) : command;
+  const windowsHide = hideChildConsole();
   if (process.platform === "win32" && /\.(?:cmd|bat)$/i.test(resolved)) {
     const comspec = process.env.ComSpec ?? "cmd.exe";
     const line = [resolved, ...args].map(quoteCmdArg).join(" ");
@@ -654,9 +707,9 @@ function spawnCommand(command, args) {
     // windowsVerbatimArguments passes the line to CreateProcess exactly as
     // built — otherwise libuv would re-quote it for CommandLineToArgvW and the
     // escaped quotes would break cmd's /s stripping.
-    return spawn(comspec, ["/d", "/s", "/c", `"${line}"`], { shell: false, stdio: "inherit", env: process.env, windowsVerbatimArguments: true });
+    return spawn(comspec, ["/d", "/s", "/c", `"${line}"`], { shell: false, stdio: "inherit", env: process.env, windowsVerbatimArguments: true, windowsHide });
   }
-  return spawn(resolved, args, { shell: false, stdio: "inherit", env: process.env });
+  return spawn(resolved, args, { shell: false, stdio: "inherit", env: process.env, windowsHide });
 }
 
 /** Forward SIGINT/SIGTERM to the child where the platform delivers them to us. */
@@ -831,10 +884,26 @@ function markerLooksValid(marker, profileDir, home) {
  * A corrupt or legacy (pre-v2) marker, or a failed static-recovery step, fails
  * closed: the command is NOT launched and no unvalidated path is deleted.
  */
-async function cmdLaunch({ profile, home, graceMs, commandArgv }) {
+async function cmdLaunch({ profile, home, graceMs, commandArgv, awaitExitPid, _waitForExit = waitForProcessExit }) {
   const profileDir = profileDirOf(home, profile);
   const grace = graceMs ?? DEFAULT_GRACE_MS;
   const [command, ...args] = commandArgv;
+
+  // A restart hands us the pid of the host that is on its way out. Starting
+  // the successor while it still holds the listening port is not a race worth
+  // taking: the bind fails, the probation below reads that as "the pending
+  // install crashed dsh", and it rolls back an install that was fine. Wait for
+  // the process to be gone, then let the port settle.
+  //
+  // Refuse rather than start anyway if it outlives the timeout. Starting is
+  // the outcome that costs the user their install; not starting leaves the old
+  // host running and the marker pending, which the next launch resolves.
+  if (awaitExitPid !== undefined) {
+    if (!await _waitForExit(awaitExitPid, AWAIT_EXIT_TIMEOUT_MS)) {
+      throw new Error(`process ${awaitExitPid} was still running after ${AWAIT_EXIT_TIMEOUT_MS}ms — refusing to start a second host that would collide with it on the listening port (the old one is still up; nothing was changed)`);
+    }
+    await delay(PORT_SETTLE_MS);
+  }
   // Mirrors guard.js pendingPath(): <home>/guard/pending-<profile>.json.
   const markerPath = join(home, "guard", `pending-${profile}.json`);
 
@@ -915,7 +984,7 @@ Usage:
   node src/cli.js guard list [--home <dir>]
   node src/cli.js guard add <spec> --profile <name> [--home <dir>] [--accept-warnings]
   node src/cli.js guard remove <package> --profile <name> [--home <dir>]
-  node src/cli.js guard launch --profile <name> [--home <dir>] [--grace-ms <ms>] -- <command> [args...]
+  node src/cli.js guard launch --profile <name> [--home <dir>] [--grace-ms <ms>] [--await-exit <pid>] -- <command> [args...]
   node src/cli.js guard self-test
 
 Commands:
@@ -956,7 +1025,7 @@ function parseArgs(argv) {
   if (args[0] === "guard") args.shift(); // `node cli.js guard recover` / `node cli.js recover`
   let command = args.shift() ?? "help";
   if (command === "--help" || command === "-h") command = "help"; // `cli.js --help`
-  const opts = { home: undefined, profile: undefined, graceMs: undefined, acceptWarnings: false, positionals: [], commandArgv: [] };
+  const opts = { home: undefined, profile: undefined, graceMs: undefined, awaitExit: undefined, acceptWarnings: false, positionals: [], commandArgv: [] };
   for (let index = 0; index < args.length; index++) {
     const arg = args[index];
     if (arg === "--") { opts.commandArgv = args.slice(index + 1); break; } // launch: the wrapped command, verbatim
@@ -968,6 +1037,8 @@ function parseArgs(argv) {
     if (arg.startsWith("--profile=")) { opts.profile = arg.slice("--profile=".length); continue; }
     if (arg === "--grace-ms") { opts.graceMs = args[++index]; continue; }
     if (arg.startsWith("--grace-ms=")) { opts.graceMs = arg.slice("--grace-ms=".length); continue; }
+    if (arg === "--await-exit") { opts.awaitExit = args[++index]; continue; }
+    if (arg.startsWith("--await-exit=")) { opts.awaitExit = arg.slice("--await-exit=".length); continue; }
     if (arg === "--all") { opts.all = true; continue; }
     if (arg.startsWith("-")) throw new Error(`unknown option ${JSON.stringify(arg)}`);
     opts.positionals.push(arg);
@@ -1038,7 +1109,12 @@ async function main(argv) {
           graceMs = Number(parsed.graceMs);
           if (!Number.isFinite(graceMs) || graceMs < 0) throw usageError(`--grace-ms must be a non-negative number, got ${JSON.stringify(parsed.graceMs)}`);
         }
-        process.exitCode = await cmdLaunch({ profile: parsed.profile, home, graceMs, commandArgv: parsed.commandArgv });
+        let awaitExitPid;
+        if (parsed.awaitExit !== undefined) {
+          awaitExitPid = Number(parsed.awaitExit);
+          if (!Number.isInteger(awaitExitPid) || awaitExitPid <= 0) throw usageError(`--await-exit must be a positive process id, got ${JSON.stringify(parsed.awaitExit)}`);
+        }
+        process.exitCode = await cmdLaunch({ profile: parsed.profile, home, graceMs, commandArgv: parsed.commandArgv, awaitExitPid });
         return;
       }
       case "self-test": {
@@ -1101,6 +1177,78 @@ async function selfTest() {
       if (p2.graceMs !== "0" || p2.commandArgv[0] !== "dsh.cmd" || p2.commandArgv.length !== 2) throw new Error("parseArgs launch =fixture failed");
       const p3 = parseArgs(["launch", "--profile", "web", "--", "--weird-but-verbatim"]);
       if (p3.commandArgv[0] !== "--weird-but-verbatim") throw new Error("parseArgs should pass post-`--` args through verbatim");
+      const p4 = parseArgs(["launch", "--profile", "web", "--await-exit", "4321", "--", "dsh"]);
+      if (p4.awaitExit !== "4321") throw new Error("parseArgs --await-exit fixture failed");
+      const p5 = parseArgs(["launch", "--profile=web", "--await-exit=99", "--", "dsh"]);
+      if (p5.awaitExit !== "99") throw new Error("parseArgs --await-exit= fixture failed");
+      // A pid after `--` belongs to the wrapped command, not to us.
+      const p6 = parseArgs(["launch", "--profile", "web", "--", "dsh", "--await-exit", "7"]);
+      if (p6.awaitExit !== undefined || p6.commandArgv.join(" ") !== "dsh --await-exit 7") throw new Error("--await-exit after `--` must stay with the wrapped command");
+    }
+
+    // `--await-exit`: the successor must not start while the outgoing host is
+    // still holding the port. A pid that never goes away is refused outright —
+    // starting anyway is what costs the user their install, because the failed
+    // bind reads as "the pending plugin crashed dsh" and rolls it back.
+    {
+      const p = join(root, "profiles", "await-exit");
+      mkdirSync(p, { recursive: true });
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: {} }));
+      writeFileSync(join(p, "cordis.patch.yml"), "[]\n");
+      const home = root;
+
+      let launched = false;
+      const neverExits = async () => false;
+      let refused = false;
+      try {
+        await cmdLaunch({
+          profile: "await-exit",
+          home,
+          commandArgv: [process.execPath, "-e", "launched=1"],
+          awaitExitPid: 999999,
+          _waitForExit: neverExits,
+        });
+      } catch (error) {
+        refused = /still running after/.test(error.message);
+      }
+      if (!refused) throw new Error("a pid that outlives the timeout must refuse the launch, not race it");
+
+      // …and a pid that does go away lets the command through.
+      const exitsPromptly = async () => true;
+      const code = await cmdLaunch({
+        profile: "await-exit",
+        home,
+        commandArgv: [process.execPath, "-e", "process.exit(0)"],
+        awaitExitPid: 999999,
+        _waitForExit: exitsPromptly,
+      });
+      launched = code === 0;
+      if (!launched) throw new Error("once the outgoing pid is gone the command must run");
+
+      // waitForProcessExit itself: this process is alive, a pid that cannot
+      // exist is gone, and a nonsense pid is not something to wait on.
+      if (await waitForProcessExit(process.pid, 120, 20)) throw new Error("waitForProcessExit must not report a live process as gone");
+      if (!await waitForProcessExit(0x7ffffff0, 500, 20)) throw new Error("waitForProcessExit must report an absent pid as gone");
+      if (!await waitForProcessExit(undefined, 500, 20)) throw new Error("waitForProcessExit must not block on a missing pid");
+    }
+
+    // hideChildConsole: inherit the console we have, never create one we do
+    // not. Getting this backwards is visible either way — a stray blank window
+    // after every restart, or an interactive `guard launch` that has lost its
+    // Ctrl+C. Windows-only by construction; asserted on both platforms so the
+    // Linux CI still pins the POSIX half.
+    {
+      const realIsTty = process.stdout.isTTY;
+      try {
+        Object.defineProperty(process.stdout, "isTTY", { value: true, configurable: true });
+        if (hideChildConsole()) throw new Error("a child of an interactive terminal must inherit its console, not be hidden from it");
+        Object.defineProperty(process.stdout, "isTTY", { value: undefined, configurable: true });
+        if (hideChildConsole() !== (process.platform === "win32")) {
+          throw new Error("with no console of our own the child must not be given a new window on Windows (and the flag is meaningless elsewhere)");
+        }
+      } finally {
+        Object.defineProperty(process.stdout, "isTTY", { value: realIsTty, configurable: true });
+      }
     }
 
     // quoteCmdArg: strict MSVCRT/CommandLineToArgvW quoting; cmd metacharacters
@@ -1333,9 +1481,11 @@ async function selfTest() {
       if (!refused || !rolledBack) throw new Error("cmdRemove partial dsh reconcile must roll back despite generic validation passing");
     }
 
-    // Startup must apply the same remove-completion check before probation;
-    // otherwise a long-running app would commit a crash-partial remove after
-    // the grace period merely because generic validation says "loadable".
+    // Startup must apply the remove-completion check before probation, so a
+    // long-running app cannot commit a crash-partial remove once the grace
+    // period elapses. The leftover bundle entry fails generic validation too
+    // (a layer without a dsh.bundle manifest stops dsh at startup); the
+    // remove-specific check is what names the actual cause.
     {
       const launchHome = join(root, "remove-launch-home");
       const launchProfile = join(launchHome, "profiles", "web");
@@ -1353,7 +1503,7 @@ async function selfTest() {
         dependencies: {},
         dsh: { profile: { bundles: ["victim"] } },
       }));
-      if (!validateInstalledProfile(launchProfile).ok) throw new Error("launch partial-remove fixture must reproduce generic false-safe validation");
+      if (validateInstalledProfile(launchProfile).ok) throw new Error("launch partial-remove fixture must fail validation before probation");
       const exitCode = await cmdLaunch({
         profile: "web",
         home: launchHome,