@aalis/plugin-package-manager 0.10.1 → 0.11.0

package/dist/index.js

@@ -1,11 +1,10 @@
-import { createRequire } from 'node:module';
 import { failureText, unmetDependencies } from '@aalis/api-doctor';
 import { hostConfig } from '@aalis/api-host-config';
 import { hostPaths } from '@aalis/api-host-paths';
 import { packageManager, } from '@aalis/api-package-manager';
-import { pluginDefinitionOf, pluginSource } from '@aalis/api-plugin-source';
+import { declaresPlugin, pluginSource } from '@aalis/api-plugin-source';
 import { processService } from '@aalis/api-process';
-import { appService, definePlugin, logger, optional, pluginsService, provide, services, } from '@aalis/core';
+import { appService, definePlugin, lifecycle, logger, optional, pluginsService, provide, services, } from '@aalis/core';
 import { TextError, textClauses, textOf, toSource } from '@aalis/schema-i18n';
 import { classifyDepSpec, isRegistryDep, isUpgrade } from '@aalis/util-dep-spec';
 import { t } from './texts.js';
@@ -24,15 +23,16 @@ const INSTALL_TIMEOUT_MS = 600_000;
  * 静默失效。环境变量优先于项目根的 `.npmrc`（install-chain 里有真 npm 用例）。
  */
 const STRICT_PEERS_ENV = { npm_config_legacy_peer_deps: 'false' };
-async function execProc(proc, cmd, args, cwd, timeout = QUICK_TIMEOUT_MS) {
-    return (await execProcBoth(proc, cmd, args, cwd, timeout)).stdout;
+async function execProc(proc, cmd, args, cwd, signal) {
+    return (await execProcBoth(proc, cmd, args, cwd, QUICK_TIMEOUT_MS, undefined, signal)).stdout;
 }
 /** 同 {@link execProc}，但同时给出 stderr——npm 的诊断（含 peer 告警）都写在 stderr。 */
-async function execProcBoth(proc, cmd, args, cwd, timeout = QUICK_TIMEOUT_MS, extraEnv) {
+async function execProcBoth(proc, cmd, args, cwd, timeout = QUICK_TIMEOUT_MS, extraEnv, signal) {
     try {
         const result = await proc.execFile(cmd, args, {
             cwd,
             timeout,
+            signal,
             ...(extraEnv ? { env: { ...process.env, ...extraEnv } } : {}),
         });
         return { stdout: result.stdout, stderr: result.stderr ?? '' };
@@ -65,17 +65,6 @@ export function hasWorkspaceProtocol(pkgJson) {
     }
     return false;
 }
-/**
- * 包是否声明自己是可加载插件（与两个加载器同一判据：纯 `aalis-plugin` 关键词正向门）。
- *
- * 用途是把「装完没发现新插件」分成两种情形：目标本就不是插件（如 `aalis-interface`
- * 前端包）→ 正常；目标声明了自己是插件却没被发现 → **静默假成功**，必须报失败。
- * 纯函数，便于单测。
- */
-export function declaresPlugin(pkgJson) {
-    const kw = pkgJson?.keywords;
-    return Array.isArray(kw) && kw.includes('aalis-plugin');
-}
 /**
  * 包类型是否归市场装卸：插件（判据同 {@link declaresPlugin}）与前端界面（`aalis-interface`）
  * 归市场管，返回 `undefined`；其余按类型关键词返回种类码（没有类型关键词的是 other），拒绝时显示 KIND_NAMES 里的名字。
@@ -110,7 +99,7 @@ const KIND_NAMES = {
 /**
  * 找出「卸载 target 会断其服务依赖」的插件：target 的某个实例正在提供或马上就提供的某服务 S 没有别的插件正在提供，且有别的
  * 插件 required 依赖 S（uses 里未包 optional）→ 这些插件会被打断。卸载连同 target 的全部实例一起卸下，所以按同名的每个实例判：算在提供的是
- * active、activating，以及 pending 而只是在等的（按 api-doctor 的共享判据不缺什么，它要的在启动，起来就提供）；disabled、
+ * active、activating，以及 pending 而只是在等的（按 api-doctor 的共享判据不缺什么，它要的在启动，启动后就提供）；disabled、
  * error 与 pending 而缺服务的不在提供。别的提供者只算 active 与 activating（替代得是确定的）。已禁用（disabled / disposed）
  * 的依赖者不算。available 是当前有提供者的服务名（services.names()）。纯函数，便于单测。
  */
@@ -135,34 +124,24 @@ export function findServiceDependents(targetName, status, available) {
     }
     return [...dependents];
 }
-/** 从项目 node_modules 解析已装包入口并取出定义 name；解析失败返回 undefined。 */
-async function resolveInstalledDefinitionName(root, pkgName) {
-    try {
-        const req = createRequire(`${root}/package.json`);
-        const entry = req.resolve(pkgName);
-        const ns = await import(new URL(`file://${entry}`).href);
-        return pluginDefinitionOf(ns)?.name;
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
- * 合法 npm 包 spec：包名（可选 scope）+ 可选 `@version` 后缀。
+ * 交给 npm 的 argv 里的包名（可选 scope，不含版本）与版本，spec = 包名(@版本)?。
  *
- * 名段与版本段的首字符**都**必须是字母数字。该值最终作为一个 argv 传给 npm，而 npm 会：
+ * 两段的首字符**都**必须是字母数字。spec 最终作为一个 argv 传给 npm，而 npm 会：
  *   - 把以 `-` 开头的 token 当命令行标志（`--force`、`--ignore-scripts` 都是 npm 上真实存在的可发布包名）；
  *   - 把 `.` / `..` / `./x` 当本地目录 spec —— **`foo@.` 与 `@a/b@..` 同样是目录 spec**，
  *     只锚名段挡不住；实测这条能让 npm 转去打包宿主工作目录并执行其 prepack/prepare 生命周期脚本。
- * 两段各自锚住首字符，即封死目录 spec 与标志注入两条面。
+ * 两段各自锚住首字符，即封死目录 spec 与标志注入两条面。版本只含字母数字与 `.` `-` `+`：版本号（可带预发布与
+ * 构建元数据）与 dist-tag，`^`、`~`、`>=` 这类带运算符的范围与路径都不收。
  */
-const PKG_SPEC_RE = /^(@[a-z0-9][a-z0-9\-_.]*\/)?[a-z0-9][a-z0-9\-_.]*(@[a-z0-9][a-z0-9.-]*)?$/i;
+const PKG_NAME_RE = /^(@[a-z0-9][a-z0-9\-_.]*\/)?[a-z0-9][a-z0-9\-_.]*$/i;
+const VERSION_RE = /^[a-z0-9][a-z0-9.\-+]*$/i;
 /**
- * 校验单个包 spec，合法返回 `undefined`、非法返回可读理由。
+ * 校验单个包 spec（包名，可带 `@版本`），合法返回 `undefined`、非法返回可读理由。
  *
  * 放在**服务层**：本服务对外公开，任何插件都能绕过 HTTP 路由直接调用。
  * 这与 `buildUpdateSpecs` 是同一条纪律——路由只做「是不是字符串」的形状检查，安全校验
- * 收在所有调用方的必经之路上。**argv 面只有这一份实现**（两份正则漂移是本仓栽过的坑）；
+ * 收在所有调用方的必经之路上。argv 面的包名与版本各只有一个正则，装、卸（本函数）与更新（buildUpdateSpecs）共用；
  * URL 路径段另有一份不含版本段的（webui-server 的 depgraph 端点，见那里的注释）——
  * 两者挡的东西不同，不是同一份的拷贝，别再把它们合并成一条。
  * 纯函数，便于单测。
@@ -170,33 +149,31 @@ const PKG_SPEC_RE = /^(@[a-z0-9][a-z0-9\-_.]*\/)?[a-z0-9][a-z0-9\-_.]*(@[a-z0-9]
 export function validatePackageSpec(spec) {
     if (typeof spec !== 'string' || spec.length === 0)
         return t('emptyName');
-    if (!PKG_SPEC_RE.test(spec))
-        return t('badName', { name: JSON.stringify(spec) });
-    return undefined;
+    // 包名里的 @ 只能是开头的 scope：开头之后还有 @，最后一个就是版本的分隔
+    const at = spec.lastIndexOf('@');
+    const valid = at > 0 ? PKG_NAME_RE.test(spec.slice(0, at)) && VERSION_RE.test(spec.slice(at + 1)) : PKG_NAME_RE.test(spec);
+    return valid ? undefined : t('badName', { name: JSON.stringify(spec) });
 }
 // ===== 插件入口 =====
 const uses = {
     proc: processService,
     paths: hostPaths,
+    lifecycle,
     logger,
     provide,
     services,
-    app: optional(appService),
-    plugins: optional(pluginsService),
+    app: appService,
+    plugins: pluginsService,
     hostConfig: optional(hostConfig),
     source: optional(pluginSource),
 };
 function createService(caps) {
     const log = caps.logger.use;
     const proc = caps.proc.use;
-    function getApp() {
-        if (!caps.app.present)
-            throw new TextError(t('noApp'));
-        return caps.app.use;
-    }
-    return createPackageManager({
+    const { settled, ...service } = createPackageManager({
         proc,
         log: log,
+        signal: caps.lifecycle.use.signal,
         // 装到宿主的安装集：与插件加载器读的是同一份 package.json，否则装了永远不加载
         projectRoot: () => caps.paths.use.app,
         // 经 process 服务的 readExternalFile 读，而非 node:fs：目标（项目根 package.json、
@@ -210,30 +187,19 @@ function createService(caps) {
                 return undefined;
             }
         },
-        // 宿主不提供插件来源（打包宿主）时视同本次没有新插件；随后仍按注册表判定，声明为插件的包会报「未被加载」
+        // 宿主不提供插件来源（打包宿主）时视同本次没有新插件
         rescanPlugins: async () => (await (caps.source.present ? caps.source.use.rescan() : undefined)) ?? [],
-        // 判据取运行时注册表而非 rescan 返回值（理由见 PackageManagerDeps.isPluginRegistered）。
-        // plugins 服务缺席时保守返回 false——宁可让「声明为插件却没加载」的诊断多报一次，
-        // 也不要在真没装上时谎报成功。
-        isPluginRegistered: name => caps.plugins.present ? caps.plugins.use.getStatus().some(p => p.name === name) : false,
-        pluginStatus: () => (caps.plugins.present ? caps.plugins.use.getStatus() : []),
+        // 宿主不提供插件来源时没有经它登记的插件：已登记的同名插件一律不是这次装的包
+        loaded: name => caps.source.present && caps.source.use.loaded(name),
+        // 与发现驱动跳过声明了已登记插件名的包同一判据：看主实例
+        isPluginRegistered: name => caps.plugins.use.getPlugin(name) !== undefined,
+        pluginStatus: () => caps.plugins.use.getStatus(),
         availableServices: () => caps.services.use.names(),
-        idle: async () => {
-            if (caps.plugins.present)
-                await caps.plugins.use.idle();
-        },
-        resolveDefinitionName: pkgName => resolveInstalledDefinitionName(caps.paths.use.app, pkgName),
-        listPluginInstanceIds: definitionName => (caps.plugins.present ? caps.plugins.use.getStatus() : [])
-            .filter(p => p.name === definitionName)
-            .map(p => p.instanceId),
+        idle: () => caps.plugins.use.idle(),
         // 重启并交付回滚凭据。core 只透传 rollback（不解释形状），由 runtime 的重启策略
         // 在「新实例 ready 前夭折」时消费——触发者与执行者同为父进程，全程内存不落盘。
-        //
-        // `restart(opts)` 收参数是 core **0.10.0** 才有的；0.9.x 的 `restart()` 不收参数，
-        // 多传的对象被静默丢弃 —— 不报错、不告警，只是更新失败后重启起来的是坏版本，
-        // 回滚安全网整个不存在。故 peerDependencies 下界必须是 `>=0.10.0`，不能沿用 0.2.0。
-        restartApp: rollback => getApp().restart({ rollback }),
-        // 彻底卸载：dispose 上下文并从注册表移除（plugins 服务缺席则 no-op）。
+        restartApp: rollback => caps.app.use.restart({ rollback }),
+        // 彻底卸载：dispose 上下文并从注册表移除。
         // 区别于 disable（仅置禁用态，仍滞留在插件列表里）。
         // 撤销通道 = 市场页能用所依赖的三样：页面本身 / 托管它的服务端 / 装卸能力本身。
         // 取每个服务当前生效的 provider（`services.all` 的首个即是），contextId 就是包名
@@ -251,8 +217,7 @@ function createService(caps) {
             })),
         ],
         unloadPlugin: async (name) => {
-            if (caps.plugins.present)
-                await caps.plugins.use.unload(name);
+            await caps.plugins.use.unload(name);
         },
         // 文档没有改动时不保存：没东西要写，也就不该因配置文件的状况报失败
         cleanupConfig: async (instanceIds, removeConfig) => {
@@ -271,22 +236,16 @@ function createService(caps) {
             await doc.save();
         },
     });
+    // 停用、重启与停机时中止信号已打断在途的 npm：等它退出、被打断的把 package.json 与锁文件还原之后才算收尾完。超过清理宽限
+    // 还没落定时 core 把本实例记为未停下，落定之前不启动新实例，新实例的 npm 不会与旧实例的 npm 或还原同时改这两份文件
+    caps.lifecycle.use.onDrain(settled, '等在途的 npm 退出，被打断的还原 package.json 与锁文件');
+    return service;
 }
 /** `@scope/foo@1.2.3` → `@scope/foo`（剥掉版本后缀，保留 scope）。 */
 export function stripVersion(spec) {
     const at = spec.lastIndexOf('@');
     return at > 0 ? spec.slice(0, at) : spec;
 }
-/**
- * 合法 npm 包名（可选 scope），**不含**版本后缀。
- *
- * 首字符锚死字母数字：npm 会把 `-` 开头的 token 当命令行标志，把 `.` / `..` / `./x`
- * 当本地目录 spec（`foo@.` 能让 npm 转去打包宿主工作目录并执行其 prepack 脚本）。
- * 版本段单独用 {@link isSafeVersion} 校验，两段各自锚住首字符才封得死。
- */
-const PKG_NAME_ONLY_RE = /^(@[a-z0-9][a-z0-9\-_.]*\/)?[a-z0-9][a-z0-9\-_.]*$/i;
-/** 精确版本号：只收字母数字打头、不含路径与标志字符的形态。 */
-const VERSION_RE = /^[a-z0-9][a-z0-9.\-+]*$/i;
 /**
  * 读 npm 的隐藏锁 `node_modules/.package-lock.json`，得到「此刻树上装的是哪些版本」。
  *
@@ -353,7 +312,7 @@ export function buildUpdateSpecs(targets) {
     for (const target of targets) {
         const name = typeof target?.name === 'string' ? target.name : '';
         const version = typeof target?.version === 'string' ? target.version : '';
-        if (!PKG_NAME_ONLY_RE.test(name))
+        if (!PKG_NAME_RE.test(name))
             return { error: t('badName', { name: JSON.stringify(name) }) };
         if (!VERSION_RE.test(version))
             return { error: t('badVersion', { name, version: JSON.stringify(version) }) };
@@ -489,7 +448,7 @@ export function findUnmetPeers(output, targetNames) {
  * 能力组装层见 createService。
  */
 export function createPackageManager(deps) {
-    const { proc, log } = deps;
+    const { proc, log, signal } = deps;
     /**
      * 当前占用的操作描述；`null` = 空闲。
      *
@@ -504,37 +463,66 @@ export function createPackageManager(deps) {
      */
     let inflight = null;
     /**
-     * 进程即将重启（update 成功后置位），此后**永不释放**锁。
+     * 进程即将重启（update 装完、重启已受理后置位），此后**永不释放**锁。
      *
      * 重启不是立刻发生的（延迟 500ms + stop + spawn），这段窗口里若放新操作进来，
      * 它会被 `process.exit` 腰斩在半路，留下半装状态。
      */
     let terminal = false;
+    /** 在途操作落定（npm 退出，被打断的已还原两份文件）；本激活收尾时等它，见 settled */
+    let current = Promise.resolve();
     /**
      * 串行闸：占用中直接**拒绝**而非排队。
      *
      * 拒绝而非排队的决定性理由：update 成功后进程立即重启，排在它后面的操作必然被腰斩。
      * 排队在这里是错的语义——「一次一个」才是这三个操作的真实约束。
+     * 本激活已开始关闭时同样拒绝：收尾段里服务还登记着，这时进来的请求不再启动 npm。
      */
     async function exclusive(what, run) {
+        if (signal.aborted)
+            return { ok: false, message: t('closing') };
         if (inflight) {
             return { ok: false, message: t('busy', { operation: inflight }) };
         }
         inflight = what;
+        const running = run();
+        current = running.then(() => { }, () => { });
         try {
-            return await run();
+            return await running;
         }
         finally {
             if (!terminal)
                 inflight = null;
         }
     }
+    /**
+     * 等 work 落定，本激活一开始关闭就不再等（work 照常往下走）。收尾在等本操作落定（onDrain），而 idle、卸载本插件选中的
+     * 提供者都要等这次收尾所在的计划走完：不这样两边互等到清理宽限。等完摘掉监听，不挂在长寿的信号上
+     */
+    async function untilClosing(work) {
+        if (signal.aborted)
+            return;
+        let stopWaiting;
+        const aborted = new Promise(resolve => {
+            stopWaiting = resolve;
+        });
+        signal.addEventListener('abort', stopWaiting, { once: true });
+        try {
+            await Promise.race([work, aborted]);
+        }
+        finally {
+            signal.removeEventListener('abort', stopWaiting);
+        }
+    }
     /** 跑一条 npm 命令：失败时整段输出记进日志，抛出的错误只带 {@link describeNpmFailure} 认出的原因与修法 */
     async function npm(args, cwd, timeout, extraEnv) {
         try {
-            return (await execProcBoth(proc, 'npm', args, cwd, timeout, extraEnv)).stdout;
+            return (await execProcBoth(proc, 'npm', args, cwd, timeout, extraEnv, signal)).stdout;
         }
         catch (err) {
+            // 随本激活关闭被中止的不算失败：调用方按中止回执
+            if (signal.aborted)
+                throw err;
             const output = err instanceof Error ? err.message : String(err);
             log.error(`npm ${args.join(' ')} 失败: ${output}`);
             throw new TextError(describeNpmFailure(output));
@@ -545,7 +533,7 @@ export function createPackageManager(deps) {
     function registry() {
         if (!registryUrl) {
             // 与 install / update 同一 cwd：项目根的 .npmrc 一并生效
-            registryUrl = execProc(proc, 'npm', ['config', 'get', 'registry'], deps.projectRoot()).then(out => {
+            registryUrl = execProc(proc, 'npm', ['config', 'get', 'registry'], deps.projectRoot(), signal).then(out => {
                 const url = out.trim().replace(/\/+$/, '');
                 if (!/^https?:\/\/\S+$/i.test(url)) {
                     throw new Error(`npm config get registry 的输出不是 http(s) 地址: ${JSON.stringify(out.trim())}`);
@@ -558,13 +546,17 @@ export function createPackageManager(deps) {
         }
         return registryUrl;
     }
-    /** 路径存在性：`test -d|-f <abs>`（不存在 → exit 1 → 抛 → false）。绝对路径，cwd 无关。 */
+    /**
+     * 路径存在性：`test -d|-f <abs>`（不存在 → exit 1 → 抛 → false）。绝对路径，cwd 无关。被本激活中止时照抛，不读成「没有」
+     */
     async function pathExists(absPath, kind) {
         try {
-            await proc.execFile('test', [`-${kind}`, absPath], { cwd: deps.projectRoot(), timeout: 10_000 });
+            await proc.execFile('test', [`-${kind}`, absPath], { cwd: deps.projectRoot(), timeout: 10_000, signal });
             return true;
         }
-        catch {
+        catch (err) {
+            if (signal.aborted)
+                throw err;
             return false;
         }
     }
@@ -580,19 +572,99 @@ export function createPackageManager(deps) {
             return undefined;
         }
     }
-    /** 加载器口径的定义 name；解析不到则回退包名。name≠包名时 warn（与 runtime 加载包装同文案）。 */
-    async function definitionNameFor(pkgName) {
-        const resolved = await deps.resolveDefinitionName?.(pkgName);
-        const defName = typeof resolved === 'string' && resolved.length > 0 ? resolved : pkgName;
-        if (defName !== pkgName) {
-            deps.log.warn?.(`插件包 "${pkgName}" 的定义 name 为 "${defName}"——配置键/热扫描/卸载均以定义的 name 为准，二者应一致`);
-        }
-        return defName;
+    /**
+     * 操作前的 package.json 与锁文件（RestartRollback 的 restore 形状）：被打断时由本插件写回，更新成功时原样交给重启策略作回滚。
+     * 原本没有的记为「写回时删掉」：npm install 会新建锁文件，回滚只写回不删的话，留着它会让 postRestore 判定新版仍满足
+     * 还原后的范围、`up to date` 什么都不做；用空内容占位也不行（会得到坏 JSON）。readText 不分不存在与读失败：读不到的再看
+     * 在不在，在而读不出的不启动 npm，免得记成「原本没有」、还原时把它删掉。取不到快照（在而读不出，或查在不在时被中止）时交回
+     * 回执，与 npmOnTree 同一口径：都还没动文件
+     */
+    async function snapshotProject(root) {
+        const files = [];
+        for (const path of [`${root}/package.json`, `${root}/package-lock.json`]) {
+            const content = await deps.readText(path);
+            if (content !== undefined) {
+                files.push({ path, content });
+                continue;
+            }
+            // pathExists 只在被中止时抛
+            const exists = await pathExists(path, 'f').catch(() => null);
+            if (exists === null)
+                return t('abortedNoChange');
+            if (exists)
+                return t('snapshotUnreadable', { path });
+            files.push({ path, content: '', deleteIfEmpty: true });
+        }
+        return files;
+    }
+    /**
+     * 把 snapshot 写回（npm 已退出，不会在写回之后再写一遍）。经 process 服务：先 tee 到临时文件再 mv 换上，写到一半出错时
+     * 目标仍是 npm 留下的那份、不是半截。这几条命令不接中止信号：写回本身就是中止之后的收尾。返回没还原成的那几份与原因
+     */
+    async function restoreProject(snapshot, root) {
+        const run = (cmd, args, input) => proc.execFile(cmd, args, { cwd: root, timeout: 10_000, ...(input === undefined ? {} : { input }) });
+        const failed = [];
+        for (const file of snapshot) {
+            const tmp = `${file.path}.aalis-restore`;
+            try {
+                if (file.deleteIfEmpty && file.content === '')
+                    await run('rm', ['-f', file.path]);
+                else {
+                    await run('tee', [tmp], file.content);
+                    await run('mv', ['-f', tmp, file.path]);
+                }
+            }
+            catch (err) {
+                failed.push({ path: file.path, error: err instanceof Error ? err.message : String(err) });
+                await run('rm', ['-f', tmp]).catch(() => { });
+            }
+        }
+        return failed;
+    }
+    /**
+     * 跑一条会改安装树的 npm（install、uninstall）。本激活关闭时随中止信号打断：等它退出后把 package.json 与锁文件写回
+     * snapshot，返回中止的回执（warn 日志同样写明）；执行完毕返回 undefined，npm 自己失败照常抛出。开始执行之前已中止的不跑
+     */
+    async function npmOnTree(args, root, snapshot, extraEnv) {
+        if (signal.aborted)
+            return t('abortedNoChange');
+        try {
+            await npm(args, root, INSTALL_TIMEOUT_MS, extraEnv);
+            return undefined;
+        }
+        catch (err) {
+            if (!signal.aborted)
+                throw err;
+        }
+        const failed = await restoreProject(snapshot, root);
+        const message = failed.length === 0
+            ? t('interrupted')
+            : t('interruptedRestoreFailed', { items: failed.map(f => t('restoreFailedItem', f)) });
+        log.warn(`npm ${args.join(' ')} 随本插件停用被中止：${toSource(message)}（安装目录 ${root}）`);
+        return message;
+    }
+    /**
+     * 插件名即包名。这个名字被不是从这个包加载的插件占着（宿主直接登记的）时，那些实例、配置与它提供的服务都不是这个包的：
+     * 卸这个包只卸包
+     */
+    function heldByHost(name) {
+        return deps.isPluginRegistered(name) && !deps.loaded(name);
+    }
+    /**
+     * 卸载 name 会打断的插件（{@link findServiceDependents}）；名字被宿主直接登记的插件占着时卸的只是包，断不了谁。
+     * 卸载闸与市场的卸载前预警共用这一份
+     */
+    function dependentsOf(name) {
+        if (heldByHost(name))
+            return [];
+        return findServiceDependents(name, deps.pluginStatus(), deps.availableServices());
     }
-    /** 注册表里该定义的全部 instanceId；没有枚举函数时只卸定义 name 本身。 */
+    /** 注册表里该定义的全部 instanceId；一个都没登记（包没加载上）时只整理定义 name 本身。 */
     function instanceIdsFor(defName) {
-        const listed = deps.listPluginInstanceIds?.(defName) ?? [];
-        const ids = [...new Set(listed.filter(id => id.length > 0))];
+        const ids = deps
+            .pluginStatus()
+            .filter(p => p.name === defName)
+            .map(p => p.instanceId);
         return ids.length > 0 ? ids : [defName];
     }
     /**
@@ -613,18 +685,19 @@ export function createPackageManager(deps) {
     /**
      * 装完的统一判定：rescan 出新插件即成功；没出新插件时按目标是否**声明自己是插件**分流。
      * 「声明了插件却没被发现」正是那条静默假成功——必须报失败，否则用户看到 ok 却什么也没装上。
-     * 就位查的是加载器解析出的定义 name，不是 npm 包名。就位但主实例没有激活时仍回 ok：包确实装上、已进插件列表；
+     * 插件名即包名。就位查的是以包名登记的主实例是不是从目标包加载的，不只看名字已登记：名字被宿主直接登记的插件占着时
+     * 发现驱动跳过目标包，同样报失败并写明。就位但主实例没有激活时仍回 ok：包确实装上、已进插件列表；
      * message 按重算落定后的状态说明——激活失败（如缺配置，改好配置即可重试）、慢激活转入后台仍在进行、等待 required 依赖。
      */
     async function settleInstall(npmPkg, installedPkgJsonPath, where) {
         const target = stripVersion(npmPkg);
         // rescan 只当副作用用（让加载器发现新包），**不看返回值**——判据是目标自身是否就位。
         await deps.rescanPlugins();
-        const defName = await definitionNameFor(target);
-        if (deps.isPluginRegistered(defName)) {
-            await deps.idle?.();
-            const main = deps.pluginStatus?.().find(p => p.instanceId === defName);
-            const settled = (message) => ({ ok: true, message, plugin: defName });
+        if (deps.loaded(target)) {
+            // 回执按等完（或不再等）时读到的状态写
+            await untilClosing(deps.idle());
+            const main = deps.pluginStatus().find(p => p.instanceId === target);
+            const settled = (message) => ({ ok: true, message, plugin: target });
             switch (main?.state) {
                 case 'error':
                     return settled(t('installedErrored', { target, error: failureText(main) ?? t('seeLogs') }));
@@ -636,9 +709,11 @@ export function createPackageManager(deps) {
             return settled(t('installedLoaded', { target }));
         }
         const meta = await readJson(installedPkgJsonPath);
-        if (declaresPlugin(meta))
+        if (!declaresPlugin(meta))
+            return { ok: true, message: t('installedNonPlugin', { target }) };
+        if (!deps.isPluginRegistered(target))
             return { ok: false, message: t('installedNotLoaded', { where }) };
-        return { ok: true, message: t('installedNonPlugin', { target }) };
+        return { ok: false, message: t('installedNameTakenByHost', { target }) };
     }
     /**
      * 安装：写根 `dependencies` —— 加载器**唯一**的发现来源。
@@ -657,7 +732,16 @@ export function createPackageManager(deps) {
         if (hasWorkspaceProtocol(rootPkg)) {
             return { ok: false, message: t('workspaceInstall') };
         }
-        const refused = await installKindRefusal(npmPkg, root);
+        let refused;
+        try {
+            refused = await installKindRefusal(npmPkg, root);
+        }
+        catch (err) {
+            // 查类型的 npm view 被中止：还没动文件
+            if (signal.aborted)
+                return { ok: false, message: t('abortedNoChange') };
+            throw err;
+        }
         if (refused)
             return { ok: false, message: refused };
         log.info(`正在安装: ${npmPkg} → 根依赖 + node_modules`);
@@ -669,7 +753,12 @@ export function createPackageManager(deps) {
         //
         // peer 护栏与更新预检相同（STRICT_PEERS_ENV）。代价：本就靠 legacy-peer-deps 容忍既有
         // peer 冲突的项目，市场安装会整体失败，故失败文案要点明原因（见 describeNpmFailure）。
-        await npm(['install', npmPkg, '--no-audit', '--no-fund'], root, INSTALL_TIMEOUT_MS, STRICT_PEERS_ENV);
+        const snapshot = await snapshotProject(root);
+        if (!Array.isArray(snapshot))
+            return { ok: false, message: snapshot };
+        const stopped = await npmOnTree(['install', npmPkg, '--no-audit', '--no-fund'], root, snapshot, STRICT_PEERS_ENV);
+        if (stopped)
+            return { ok: false, message: stopped };
         const bare = stripVersion(npmPkg);
         return settleInstall(npmPkg, `${root}/node_modules/${bare}/package.json`, 'node_modules');
     }
@@ -680,7 +769,7 @@ export function createPackageManager(deps) {
      * 1. `--dry-run` **有副作用**——它不碰 `package.json` 与 `package-lock.json`，却会把
      *    `node_modules/.package-lock.json`（npm 的隐藏 lockfile）重写成「目标版本已装」。
      *    紧接着的真装读到它就判定树已就绪，直接 `up to date` 什么都不做：于是声明成了新版、
-     *    node_modules 里仍是旧代码，而旧代码起得来 → 重启成功 → 回滚永不触发 → 整次更新
+     *    node_modules 里仍是旧代码，而旧代码能启动 → 重启成功 → 回滚永不触发 → 整次更新
      *    空转却报成功。副本里跑则 live tree 分毫未动，无需事后补救。
      * 2. 用户 `.npmrc` 里的 `legacy-peer-deps=true`（React 生态常见 workaround）会让 npm
      *    **完全不报** peer 告警，唯一的护栏静默失效。副本在项目树之外，天然不继承项目级
@@ -702,16 +791,18 @@ export function createPackageManager(deps) {
         try {
             // 直接 cp 现有文件，不重新写内容——与本插件其余文件操作同一路子（走 process 服务的
             // POSIX 命令），也省掉一个只为此处存在的写原语。
-            await execProc(proc, 'cp', [`${root}/package.json`, `${tmp.path}/package.json`], tmp.path);
+            await execProc(proc, 'cp', [`${root}/package.json`, `${tmp.path}/package.json`], tmp.path, signal);
             const lock = `${root}/package-lock.json`;
             if (await pathExists(lock, 'f')) {
-                await execProc(proc, 'cp', [lock, `${tmp.path}/package-lock.json`], tmp.path);
+                await execProc(proc, 'cp', [lock, `${tmp.path}/package-lock.json`], tmp.path, signal);
             }
             let output;
             try {
-                output = await execProcBoth(proc, 'npm', ['install', ...specs, '--dry-run', '--no-audit', '--no-fund'], tmp.path, INSTALL_TIMEOUT_MS, STRICT_PEERS_ENV);
+                output = await execProcBoth(proc, 'npm', ['install', ...specs, '--dry-run', '--no-audit', '--no-fund'], tmp.path, INSTALL_TIMEOUT_MS, STRICT_PEERS_ENV, signal);
             }
             catch (err) {
+                if (signal.aborted)
+                    throw err;
                 // 非零退出：npm 判定 peer 无解（ERESOLVE 等）时报冲突要点；别的失败（连不上源等）不是冲突，抛出原因与修法
                 const raw = err instanceof Error ? err.message : String(err);
                 const conflicts = extractPeerConflicts(raw);
@@ -736,12 +827,8 @@ export function createPackageManager(deps) {
         if (built.error)
             return { ok: false, message: built.error };
         const { specs } = built;
-        if (!deps.restartApp)
-            return { ok: false, message: t('noRestart') };
         const root = deps.projectRoot();
-        // 没有「项目形态」这一层判断了：能不能更新是**每个包自己的来源**说了算（下面的
-        // isRegistryDep 闸），不是整个项目的属性。旧写法拿 `pnpm-workspace.yaml` 是否存在
-        // 当整体开关，既挡掉了工作区项目里合法的 npm 依赖，也与真正生效的加载器无因果关系。
+        // 能不能更新是**每个包自己的来源**说了算（下面的 isRegistryDep 闸），不是整个项目的属性。
         const rootPkgPath = `${root}/package.json`;
         const rootPkgText = await deps.readText(rootPkgPath);
         if (rootPkgText === undefined)
@@ -796,27 +883,17 @@ export function createPackageManager(deps) {
             verdict = await preflightInSandbox(specs, root);
         }
         catch (err) {
+            if (signal.aborted)
+                return { ok: false, message: t('abortedNoChange') };
             return { ok: false, message: t('preflightFailed', { error: textOf(err) }) };
         }
         if (verdict)
             return reject(verdict);
         // ── 快照：预检过了才有必要 ──
-        // lockfile 与 package.json 必须一起回退，否则还原后的树是「声明旧版、锁定新版」。
-        const restore = [
-            { path: rootPkgPath, content: rootPkgText },
-        ];
-        const lockPath = `${root}/package-lock.json`;
-        const lockText = await deps.readText(lockPath);
-        if (lockText !== undefined) {
-            restore.push({ path: lockPath, content: lockText });
-        }
-        else {
-            // 原本没有 lockfile（pnpm/yarn 装的工程），而 npm install 会**新建**一个锁到新版。
-            // 回滚只能写回文件、不能删除新增文件，留着它会让 postRestore 判定新版仍满足还原后的
-            // 范围 → `up to date` → node_modules 纹丝不动。用空内容占位不行（会得到坏 JSON），
-            // 故记为「回滚时删掉它」，把工程还原成它原本无锁的样子。
-            restore.push({ path: lockPath, content: '', deleteIfEmpty: true });
-        }
+        // lockfile 与 package.json 必须一起回退，否则还原后的树是「声明旧版、锁定新版」。被打断时本插件按它写回，装完交给重启策略
+        const restore = await snapshotProject(root);
+        if (!Array.isArray(restore))
+            return { ok: false, message: restore };
         // 装之前记下整棵树的实装版本。回滚不能只钉被点名的包：npm 会顺带把**传递依赖**升上去
         // （新版把某个依赖的下界抬高了），而回滚时 `npm install <被点名的包>@<旧版>` 只会
         // `changed 1 package` —— 被顺带升上去的那个仍满足旧版声明的范围，npm 不动它，于是它
@@ -830,21 +907,20 @@ export function createPackageManager(deps) {
         // ── 提交 ──
         // 预检在副本里做，live tree 此刻**未被任何 dry-run 触碰**，可以直接装。
         try {
-            await npm(['install', ...specs, '--no-audit', '--no-fund'], root, INSTALL_TIMEOUT_MS);
+            const stopped = await npmOnTree(['install', ...specs, '--no-audit', '--no-fund'], root, restore);
+            if (stopped)
+                return { ok: false, message: stopped };
         }
         catch (err) {
             return { ok: false, message: t('installFailedRetry', { error: textOf(err) }) };
         }
         // ── 重启接管 ──
         // 回滚凭据交给重启策略：只有它能观察到「新实例 ready 前夭折」。插件级失败不在此列
-        // ——插件起不来会停在 error 态且 WebUI 可见，自动回滚反而会掩盖问题。
-        log.info(`更新完成，正在重启接管: ${specs.join(' ')}`);
-        // 置位后锁不再释放：重启是延迟发生的，这段窗口放新操作进来会被 process.exit 腰斩。
-        terminal = true;
+        // ——插件启动失败会停在 error 态且 WebUI 可见，自动回滚反而会掩盖问题。
         // postRestore 钉**精确旧版**，不用裸 `npm install`。
         // 裸 install 只能按还原后的 package.json 重解析，而声明通常是 caret 范围（`^1.0.0`），
         // 刚崩掉的新版（1.1.0）本身就满足它——于是 npm 又把它装回来，node_modules 分毫未变，
-        // 而重启策略照样报告已回滚并拉起旧版本。实测：有锁时正常，无锁时静默失效。
+        // 而重启策略照样报告已回滚，并重新启动进程运行旧版本。实测：有锁时正常，无锁时静默失效。
         // `--no-save` 保证 package.json 维持 restore 写回的原样，不被 npm 改写成 `^旧版`。
         // 降级守卫已保证每个 target 都有已装版本（读不到的在那里就被拒了），此处的 undefined
         // 过滤只是让类型收窄，不承担逻辑。
@@ -865,11 +941,20 @@ export function createPackageManager(deps) {
             if (after !== undefined && after !== before)
                 pinned.push(`${name}@${before}`);
         }
-        deps.restartApp({
-            reason: `marketplace-update:${specs.join(',')}`,
-            restore,
-            postRestore: { cmd: 'npm', args: ['install', ...pinned, '--no-save', '--no-audit', '--no-fund'], cwd: root },
-        });
+        try {
+            deps.restartApp({
+                reason: `marketplace-update:${specs.join(',')}`,
+                restore,
+                postRestore: { cmd: 'npm', args: ['install', ...pinned, '--no-save', '--no-audit', '--no-fund'], cwd: root },
+            });
+        }
+        catch (err) {
+            // 宿主没有重启策略（嵌入宿主）或应用已开始停机时 core 同步抛错：包已装好、不会重启，锁照常放开，回执照实说
+            return { ok: true, restarting: false, message: t('updatedRestartUnavailable', { specs, error: textOf(err) }) };
+        }
+        log.info(`更新完成，正在重启接管: ${specs.join(' ')}`);
+        // 重启受理之后锁不再释放：重启是延迟发生的，这段窗口放新操作进来会被 process.exit 腰斩。
+        terminal = true;
         return { ok: true, restarting: true, message: t('updated', { specs }) };
     }
     return {
@@ -888,8 +973,9 @@ export function createPackageManager(deps) {
             }
         }),
         uninstall: (pluginName, options) => exclusive(t('opUninstall', { name: pluginName }), () => uninstallOne(pluginName, options)),
-        serviceDependents: name => findServiceDependents(name, deps.pluginStatus?.() ?? [], deps.availableServices?.() ?? []),
+        serviceDependents: dependentsOf,
         registry,
+        settled: () => current,
     };
     /**
      * 卸载：服务层各道闸 + npm uninstall。
@@ -910,8 +996,8 @@ export function createPackageManager(deps) {
         // ── 闸一：类型 ──
         // 市场管的是**插件**。core / runtime / api / schema / util 不是插件，不在本工具职权内。
         // 这不是「权限不够」——owner 权限很高，走 `npm uninstall` 随时能删。这道闸拦的是
-        // 「**这个操作会把你用来撤销它的那条通道一起销毁**」：卸掉插件，实例照常跑、市场里点
-        // 一下就能装回来（带内可恢复）；卸掉内核或宿主，实例起不来、市场随之消失，只能开
+        // 「**这个操作会把你用来撤销它的那条通道一起销毁**」：卸掉插件，实例照常运行、市场里点
+        // 一下就能装回来（带内可恢复）；卸掉内核或宿主，实例无法启动、市场随之消失，只能开
         // shell 修（带外）。更新不在此列——它保留实例且失败会自动回滚。
         // 判据与安装同一份（nonMarketKind）。
         const kind = nonMarketKind(meta.keywords);
@@ -936,7 +1022,7 @@ export function createPackageManager(deps) {
         //
         // 只拦「当前生效的那个」：想换实现的正常路径是「装新的 → 切过去 → 再卸旧的」，
         // 那时它已不是提供者，本闸自然放行。
-        const lifeline = deps.recoveryChannelProviders?.() ?? [];
+        const lifeline = deps.recoveryChannelProviders();
         if (lifeline.includes(pluginName)) {
             return { ok: false, message: t('lifeline', { name: pluginName }) };
         }
@@ -956,29 +1042,36 @@ export function createPackageManager(deps) {
             };
             return { ok: false, message: t('notFromMarket', { name: pluginName, why: why[origin] }) };
         }
-        // 先解析定义 name 并枚举实例：npm uninstall 会拆掉 node_modules，之后就读不到入口了。
-        const defName = await definitionNameFor(pluginName);
-        const instanceIds = instanceIdsFor(defName);
+        // 名字被宿主直接登记的插件占着时只卸包：不卸实例、不过服务依赖者闸、不整理配置
+        const held = heldByHost(pluginName);
+        const instanceIds = held ? [] : instanceIdsFor(pluginName);
         // ── 闸三：服务依赖者 ──
         // 某服务没有别的插件正在提供时，卸掉它的提供者会打断 required 该服务的插件（已禁用的不算）。
-        // 与市场卸载前的预警同一份判定（serviceDependents），按加载器解析出的定义 name 查。
-        const dependents = findServiceDependents(defName, deps.pluginStatus?.() ?? [], deps.availableServices?.() ?? []);
+        // 与市场卸载前的预警同一份判定（serviceDependents）。
+        const dependents = dependentsOf(pluginName);
         if (dependents.length > 0) {
             return { ok: false, message: t('breaksDependents', { dependents }) };
         }
         try {
-            await npm(['uninstall', pluginName, '--no-audit', '--no-fund'], root, INSTALL_TIMEOUT_MS);
-            // 从运行时注册表彻底移除（dispose + delete），幂等
+            const snapshot = await snapshotProject(root);
+            if (!Array.isArray(snapshot))
+                return { ok: false, message: snapshot };
+            const stopped = await npmOnTree(['uninstall', pluginName, '--no-audit', '--no-fund'], root, snapshot);
+            if (stopped)
+                return { ok: false, message: stopped };
+            // 从运行时注册表彻底移除（dispose + delete），幂等。卸的可能正是本插件选中的提供者，本激活随之关闭时不再等
             for (const id of instanceIds)
-                await deps.unloadPlugin(id);
+                await untilClosing(deps.unloadPlugin(id));
         }
         catch (err) {
             return { ok: false, message: textOf(err) };
         }
         log.info(`${pluginName}: 已从根依赖与 node_modules 移除`);
+        if (held)
+            return { ok: true, message: t('uninstalledNameTakenByHost', { name: pluginName }) };
         // 包已经卸掉了，配置文件没写成不改变这一点：回执照样 ok，写明原因与残留
         try {
-            await deps.cleanupConfig?.(instanceIds, removeConfig);
+            await deps.cleanupConfig(instanceIds, removeConfig);
         }
         catch (err) {
             return {