@elementspanel/epanel-plugin-instance 1.0.0 → 1.0.1

package/daemon/backend/index.cjs

@@ -109,7 +109,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.StorageSubsystem = exports.MCServerStatus = exports.InstanceStreamListener = exports.GlobalVariable = exports.normalizeDockerPlatform = exports.normalizeDockerOS = exports.normalizeDockerArchitecture = exports.removeTrail = exports.uninstallNpmPlugin = exports.npmPluginRoots = exports.listNpmPlugins = exports.installNpmPlugin = exports.currentProjectRoot = exports.currentPackageRoot = exports.sortPlugins = exports.resolvePluginEntry = exports.readPluginManifest = exports.createFrontendPluginMetadata = exports.discoverPluginsFromRoots = exports.discoverPlugins = exports.arrayUnique = exports.toText = exports.toNumber = exports.toBoolean = exports.supposeValue = exports.isEmpty = exports.configureEntityParams = exports.systemInfo = exports.QueryWrapper = exports.QueryMapWrapper = exports.MySqlSource = exports.LocalFileSource = exports.killProcess = exports.ProcessWrapper = void 0;
+exports.StorageSubsystem = exports.MCServerStatus = exports.InstanceStreamListener = exports.GlobalVariable = exports.normalizeDockerPlatform = exports.normalizeDockerOS = exports.normalizeDockerArchitecture = exports.removeTrail = exports.uninstallNpmPlugin = exports.isEssentialNpmPlugin = exports.npmPluginOperationPending = exports.npmPluginRoots = exports.listNpmPlugins = exports.installNpmPlugin = exports.currentProjectRoot = exports.currentPackageRoot = exports.sortPlugins = exports.resolvePluginEntry = exports.readPluginManifest = exports.createFrontendPluginMetadata = exports.discoverPluginsFromRoots = exports.discoverPlugins = exports.arrayUnique = exports.toText = exports.toNumber = exports.toBoolean = exports.supposeValue = exports.isEmpty = exports.configureEntityParams = exports.systemInfo = exports.QueryWrapper = exports.QueryMapWrapper = exports.MySqlSource = exports.LocalFileSource = exports.killProcess = exports.ProcessWrapper = void 0;
 const global_variable_1 = __importDefault(__webpack_require__("../common/src/global_variable.ts"));
 exports.GlobalVariable = global_variable_1.default;
 const instance_stream_1 = __importDefault(__webpack_require__("../common/src/instance_stream.ts"));
@@ -141,6 +141,8 @@ __exportStar(__webpack_require__("../common/src/plugin_contract.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_overrides.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_lifecycle.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_revision.ts"), exports);
+__exportStar(__webpack_require__("../common/src/plugin_modules.ts"), exports);
+__exportStar(__webpack_require__("../common/src/plugin_watch.ts"), exports);
 __exportStar(__webpack_require__("../common/src/runtime_paths.ts"), exports);
 var plugin_manifest_1 = __webpack_require__("../common/src/plugin_manifest.ts");
 Object.defineProperty(exports, "discoverPlugins", ({ enumerable: true, get: function () { return plugin_manifest_1.discoverPlugins; } }));
@@ -155,6 +157,8 @@ Object.defineProperty(exports, "currentProjectRoot", ({ enumerable: true, get: f
 Object.defineProperty(exports, "installNpmPlugin", ({ enumerable: true, get: function () { return plugin_npm_1.installNpmPlugin; } }));
 Object.defineProperty(exports, "listNpmPlugins", ({ enumerable: true, get: function () { return plugin_npm_1.listNpmPlugins; } }));
 Object.defineProperty(exports, "npmPluginRoots", ({ enumerable: true, get: function () { return plugin_npm_1.npmPluginRoots; } }));
+Object.defineProperty(exports, "npmPluginOperationPending", ({ enumerable: true, get: function () { return plugin_npm_1.npmPluginOperationPending; } }));
+Object.defineProperty(exports, "isEssentialNpmPlugin", ({ enumerable: true, get: function () { return plugin_npm_1.isEssentialNpmPlugin; } }));
 Object.defineProperty(exports, "uninstallNpmPlugin", ({ enumerable: true, get: function () { return plugin_npm_1.uninstallNpmPlugin; } }));
 var string_utils_1 = __webpack_require__("../common/src/string_utils.ts");
 Object.defineProperty(exports, "removeTrail", ({ enumerable: true, get: function () { return string_utils_1.removeTrail; } }));
@@ -654,7 +658,45 @@ function createFrontendPluginMetadata(manifest, extras = {}) {
     };
 }
 const MANIFEST_FILES = ["plugin.json", "manifest.json", "package.json"];
-/** Reads the manifest of one plugin directory, or null if it has none. */
+const ENTRY_FIELDS = ["backend", "frontend", "panel", "daemon", "main", "entry", "ui"];
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Source plugins keep package.json beside plugin.json. Published npm plugins
+ * keep it at the package root, with runtime metadata under elementspanel.<side>.
+ * Stop at the first package boundary so a host's metadata cannot reach a plugin.
+ */
+function readPackageMetadata(directory, id) {
+    const pluginDirectory = node_path_1.default.resolve(directory);
+    let current = pluginDirectory;
+    while (true) {
+        const filename = node_path_1.default.join(current, "package.json");
+        if (node_fs_1.default.existsSync(filename)) {
+            const { elementspanel, ...metadata } = objectValue(JSON.parse(node_fs_1.default.readFileSync(filename, "utf8")));
+            const { id: packageId, panel, daemon, ...shared } = objectValue(elementspanel);
+            const definition = [panel, daemon]
+                .map(objectValue)
+                .find((side) => typeof side.directory === "string" &&
+                node_path_1.default.resolve(current, side.directory) === pluginDirectory);
+            if (current !== pluginDirectory && (packageId !== id || !definition))
+                return {};
+            const { directory: _directory, folder: _folder, ...sideMetadata } = definition ?? {};
+            const result = { ...metadata, ...shared, ...sideMetadata };
+            // npm's main/entry fields do not define a side's execution entry.
+            for (const field of ["dual", ...ENTRY_FIELDS])
+                delete result[field];
+            return result;
+        }
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current)
+            return {};
+        current = parent;
+    }
+}
+/** Merges package metadata with a plugin's identity and entries. Legacy manifests still load. */
 function readPluginManifest(directory, onWarning, fallbackId = node_path_1.default.basename(directory)) {
     for (const file of MANIFEST_FILES) {
         const filePath = node_path_1.default.join(directory, file);
@@ -667,7 +709,18 @@ function readPluginManifest(directory, onWarning, fallbackId = node_path_1.defau
             const id = typeof value.id === "string" ? value.id : fallbackId;
             if (!id.trim())
                 return null;
-            return { ...value, id: id.trim() };
+            const manifest = {
+                ...value,
+                ...readPackageMetadata(directory, id.trim()),
+                id: id.trim()
+            };
+            // Identity and execution paths always belong to plugin.json. Package
+            // metadata wins for descriptions, priority, configuration and dependencies.
+            for (const field of ["version", "dual", ...ENTRY_FIELDS]) {
+                if (value[field] !== undefined)
+                    manifest[field] = value[field];
+            }
+            return manifest;
         }
         catch (error) {
             onWarning?.(`Failed to read plugin manifest: ${filePath}`, error);
@@ -765,6 +818,13 @@ function discoverPluginsFromRoots(roots, options) {
             discovered.push({
                 ...plugin,
                 manifest,
+                ...(root.packageRoot
+                    ? {
+                        packageRoot: root.packageRoot,
+                        packageName: root.packageName,
+                        npmSource: root.npmSource
+                    }
+                    : {}),
                 ...(root.folder ? { folder: root.folder } : {})
             });
         }
@@ -778,6 +838,177 @@ function sortPlugins(plugins) {
 }
 
 
+/***/ },
+
+/***/ "../common/src/plugin_modules.ts"
+(__unused_webpack_module, exports, __webpack_require__) {
+
+
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.pluginBackendRevision = pluginBackendRevision;
+exports.forgetPluginModules = forgetPluginModules;
+exports.loadPluginModule = loadPluginModule;
+const node_fs_1 = __importDefault(__webpack_require__("node:fs"));
+const node_path_1 = __importDefault(__webpack_require__("node:path"));
+const node_url_1 = __webpack_require__("node:url");
+const node_crypto_1 = __webpack_require__("node:crypto");
+const node_module_1 = __webpack_require__("node:module");
+const plugin_revision_1 = __webpack_require__("../common/src/plugin_revision.ts");
+const REVISION = "epanelPluginRevision";
+const graphs = new Map();
+const previousRoots = new Map();
+let hooksInstalled = false;
+const sharedModules = new Set([
+    "cordis",
+    "@cordisjs/core",
+    "@cordisjs/logger",
+    "@cordisjs/timer",
+    "@cordisjs/schema",
+    "cosmokit",
+    "schemastery",
+    "reggol"
+]);
+function dependencyRoots(directory) {
+    const visited = new Set([directory]);
+    const walk = (root) => {
+        const filename = node_path_1.default.join(root, "package.json");
+        if (!node_fs_1.default.existsSync(filename))
+            return;
+        const metadata = JSON.parse(node_fs_1.default.readFileSync(filename, "utf8"));
+        const localRequire = (0, node_module_1.createRequire)(filename);
+        for (const name of Object.keys({
+            ...metadata.dependencies,
+            ...metadata.optionalDependencies
+        })) {
+            if (sharedModules.has(name))
+                continue;
+            const target = (localRequire.resolve.paths(name) || [])
+                .map((directory) => node_path_1.default.join(directory, name, "package.json"))
+                .find((candidate) => node_fs_1.default.existsSync(candidate));
+            if (!target)
+                continue;
+            const dependency = node_fs_1.default.realpathSync(node_path_1.default.dirname(target));
+            if (visited.has(dependency))
+                continue;
+            visited.add(dependency);
+            walk(dependency);
+        }
+    };
+    walk(directory);
+    visited.delete(directory);
+    return [...visited];
+}
+/** Include transitive dependency versions so npm updates replace the affected graph. */
+function pluginBackendRevision(entry, directory) {
+    const hash = (0, node_crypto_1.createHash)("sha256").update((0, plugin_revision_1.pluginDirectoryRevision)(node_path_1.default.dirname(entry)));
+    for (const root of [directory, ...dependencyRoots(directory)]) {
+        const filename = node_path_1.default.join(root, "package.json");
+        if (node_fs_1.default.existsSync(filename))
+            hash.update(root).update(node_fs_1.default.readFileSync(filename));
+    }
+    return hash.digest("hex").slice(0, 24);
+}
+function within(root, filename) {
+    const relative = node_path_1.default.relative(root, filename);
+    return (relative === "" ||
+        (!relative.startsWith(`..${node_path_1.default.sep}`) && relative !== ".." && !node_path_1.default.isAbsolute(relative)));
+}
+/** Clear the plugin's complete CJS graph, keeping shared host modules intact. */
+function forgetPluginModules(directory) {
+    const runtimeRequire = eval("require");
+    const owned = [directory, ...(previousRoots.get(directory) || []), ...dependencyRoots(directory)];
+    previousRoots.delete(directory);
+    const belongs = (filename) => {
+        const parts = filename.split(`${node_path_1.default.sep}node_modules${node_path_1.default.sep}`);
+        if (parts.slice(1).some((part) => {
+            const name = part.startsWith("@")
+                ? part.split(node_path_1.default.sep).slice(0, 2).join("/")
+                : part.split(node_path_1.default.sep)[0];
+            return sharedModules.has(name);
+        }))
+            return false;
+        return owned.some((root) => within(root, filename));
+    };
+    for (const filename of Object.keys(runtimeRequire.cache)) {
+        if (belongs(filename))
+            delete runtimeRequire.cache[filename];
+    }
+    for (const mod of Object.values(runtimeRequire.cache)) {
+        if (mod)
+            mod.children = mod.children.filter((child) => !belongs(child.filename));
+    }
+    // npm can move a dependency or change its main entry. Node's CJS resolver
+    // retains those paths separately from require.cache.
+    const pathCache = runtimeRequire("node:module")._pathCache;
+    for (const [key, filename] of Object.entries(pathCache)) {
+        if (belongs(filename) || owned.some((root) => key.includes(root)))
+            delete pathCache[key];
+    }
+}
+function isEsm(entry) {
+    if (entry.endsWith(".mjs"))
+        return true;
+    if (entry.endsWith(".cjs"))
+        return false;
+    let directory = node_path_1.default.dirname(entry);
+    while (true) {
+        const filename = node_path_1.default.join(directory, "package.json");
+        if (node_fs_1.default.existsSync(filename))
+            return JSON.parse(node_fs_1.default.readFileSync(filename, "utf8")).type === "module";
+        const parent = node_path_1.default.dirname(directory);
+        if (parent === directory)
+            return false;
+        directory = parent;
+    }
+}
+/** Give an ESM entry and its local imports the same immutable revision URL. */
+async function loadPluginModule(entry, directory, revision) {
+    const runtimeRequire = eval("require");
+    previousRoots.set(directory, dependencyRoots(directory));
+    if (!isEsm(entry)) {
+        try {
+            return runtimeRequire(entry);
+        }
+        catch (error) {
+            if (error?.code !== "ERR_REQUIRE_ESM")
+                throw error;
+        }
+    }
+    graphs.set(revision, [directory, ...dependencyRoots(directory)]);
+    if (!hooksInstalled) {
+        const { registerHooks } = runtimeRequire("node:module");
+        if (typeof registerHooks !== "function")
+            throw new Error("ESM plugin updates require Node.js 22.15 or newer.");
+        registerHooks({
+            resolve(specifier, context, nextResolve) {
+                const resolved = nextResolve(specifier, context);
+                if (!context.parentURL?.startsWith("file:") || !resolved.url.startsWith("file:"))
+                    return resolved;
+                const parent = new URL(context.parentURL);
+                const parentRevision = parent.searchParams.get(REVISION);
+                if (!parentRevision)
+                    return resolved;
+                const roots = graphs.get(parentRevision);
+                if (!roots?.some((root) => within(root, (0, node_url_1.fileURLToPath)(parent))) ||
+                    !roots.some((root) => within(root, (0, node_url_1.fileURLToPath)(resolved.url))))
+                    return resolved;
+                const url = new URL(resolved.url);
+                url.searchParams.set(REVISION, parentRevision);
+                return { ...resolved, url: url.href };
+            }
+        });
+        hooksInstalled = true;
+    }
+    const url = (0, node_url_1.pathToFileURL)(entry);
+    url.searchParams.set(REVISION, revision);
+    const dynamicImport = new Function("specifier", "return import(specifier)");
+    return dynamicImport(url.href);
+}
+
+
 /***/ },
 
 /***/ "../common/src/plugin_npm.ts"
@@ -792,15 +1023,19 @@ exports.currentPackageRoot = currentPackageRoot;
 exports.currentProjectRoot = currentProjectRoot;
 exports.npmPluginRoots = npmPluginRoots;
 exports.listNpmPlugins = listNpmPlugins;
+exports.npmPluginOperationPending = npmPluginOperationPending;
+exports.isEssentialNpmPlugin = isEssentialNpmPlugin;
 exports.installNpmPlugin = installNpmPlugin;
 exports.uninstallNpmPlugin = uninstallNpmPlugin;
 const child_process_1 = __webpack_require__("child_process");
 const fs_extra_1 = __importDefault(__webpack_require__("fs-extra"));
 const path_1 = __importDefault(__webpack_require__("path"));
 const module_1 = __webpack_require__("module");
+const plugin_manifest_1 = __webpack_require__("../common/src/plugin_manifest.ts");
+const plugin_contract_1 = __webpack_require__("../common/src/plugin_contract.ts");
 const PLUGIN_ID = /^[a-z][a-z0-9_-]{1,63}$/;
 const PACKAGE_NAME = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
-const VERSION = /^[0-9][^\s/]{0,63}$/;
+const VERSION = /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,63}$/;
 function readJson(filename) {
     try {
         const parsed = JSON.parse(fs_extra_1.default.readFileSync(filename, "utf8"));
@@ -866,8 +1101,20 @@ function pluginRecord(pluginId, name, source, packageRoot, directory, folder, ve
     return { pluginId, name, version, sides: [], directory, folder, packageRoot, source };
 }
 function readPackageEntry(packageRoot, name) {
-    const hostRequire = (0, module_1.createRequire)(path_1.default.join(packageRoot, "package.json"));
-    const manifestPath = hostRequire.resolve(`${name}/package.json`);
+    // Read package boundaries directly: Node caches require.resolve() paths even
+    // after npm moves an installation between nested and hoisted node_modules.
+    let manifestPath;
+    for (const root of [packageRoot, currentProjectRoot(packageRoot)]) {
+        const localRequire = (0, module_1.createRequire)(path_1.default.join(root, "package.json"));
+        manifestPath = (localRequire.resolve.paths(name) || [])
+            .map((directory) => path_1.default.join(directory, name, "package.json"))
+            .find((filename) => fs_extra_1.default.existsSync(filename));
+        if (manifestPath)
+            break;
+    }
+    if (!manifestPath)
+        throw new Error(`Missing npm plugin package: ${name}.`);
+    manifestPath = fs_extra_1.default.realpathSync(manifestPath);
     const metadata = readJson(manifestPath);
     if (!metadata)
         throw new Error(`Missing package metadata for ${name}.`);
@@ -881,7 +1128,10 @@ function sideDirectory(packageRoot, metadata, side) {
         return undefined;
     const target = path_1.default.resolve(packageRoot, directory);
     const relative = path_1.default.relative(packageRoot, target);
-    if (relative === "" || relative.startsWith(`..${path_1.default.sep}`) || path_1.default.isAbsolute(relative))
+    if (relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path_1.default.sep}`) ||
+        path_1.default.isAbsolute(relative))
         return undefined;
     return target;
 }
@@ -898,7 +1148,7 @@ function recordFromPackage(pluginId, name, source, packageRoot, metadata, side)
         return undefined;
     const directory = sideDirectory(packageRoot, metadata, target);
     const folder = stringValue(objectValue(elements[target])?.folder);
-    if (!directory || !folder)
+    if (!directory || !PLUGIN_ID.test(folder))
         return undefined;
     return {
         ...pluginRecord(pluginId, name, source, packageRoot, directory, folder, version),
@@ -918,9 +1168,24 @@ function listNpmPlugins(side, options = {}) {
     const host = readJson(path_1.default.join(packageRoot, "package.json"));
     if (!host)
         throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-    const project = path_1.default.resolve(projectRoot) === path_1.default.resolve(packageRoot) ? null : readProjectManifest(projectRoot);
+    const project = path_1.default.resolve(projectRoot) === path_1.default.resolve(packageRoot)
+        ? null
+        : readProjectManifest(projectRoot);
     const hostMappings = mappingsOf(host);
-    const projectMappings = mappingsOf(project);
+    const projectMappings = { ...mappingsOf(project) };
+    for (const name of Object.keys(dependenciesOf(project))) {
+        if (!PACKAGE_NAME.test(name) || Object.values(projectMappings).includes(name))
+            continue;
+        try {
+            const entry = readPackageEntry(projectRoot, name);
+            const id = stringValue(objectValue(entry.metadata.elementspanel)?.id);
+            if (PLUGIN_ID.test(id) && projectMappings[id] === undefined)
+                projectMappings[id] = name;
+        }
+        catch {
+            /* npm may still be writing the package. */
+        }
+    }
     const mappings = new Map();
     for (const [pluginId, name] of Object.entries(projectMappings)) {
         if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
@@ -930,6 +1195,8 @@ function listNpmPlugins(side, options = {}) {
     for (const [pluginId, name] of Object.entries(hostMappings)) {
         if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
             continue;
+        if (dependenciesOf(host)[name] === undefined)
+            continue;
         mappings.set(pluginId, { name, source: "bundled" });
     }
     const hostDependencies = dependenciesOf(host);
@@ -945,7 +1212,7 @@ function listNpmPlugins(side, options = {}) {
         }
         let entry;
         try {
-            entry = readPackageEntry(packageRoot, mapping.name);
+            entry = readPackageEntry(mapping.source === "project" ? projectRoot : packageRoot, mapping.name);
         }
         catch (error) {
             if (options.skipInvalid)
@@ -977,7 +1244,12 @@ function runNpm(args, cwd) {
             : process.platform === "win32"
                 ? {
                     command: process.env.ComSpec || "cmd.exe",
-                    args: ["/d", "/s", "/c", `npm ${args.map((item) => `"${item.replace(/"/g, '""')}"`).join(" ")}`],
+                    args: [
+                        "/d",
+                        "/s",
+                        "/c",
+                        `npm ${args.map((item) => `"${item.replace(/"/g, '""')}"`).join(" ")}`
+                    ],
                     shell: false
                 }
                 : { command: "npm", args, shell: false };
@@ -996,9 +1268,10 @@ function runNpm(args, cwd) {
         };
         child.stdout?.on("data", append);
         child.stderr?.on("data", append);
+        const action = args.find((argument) => argument === "install" || argument === "uninstall") || "operation";
         const timer = setTimeout(() => {
             child.kill("SIGKILL");
-            reject(new Error(`npm ${args[0] ?? ""} timed out.`));
+            reject(new Error(`npm ${action} timed out.`));
         }, 10 * 60 * 1000);
         timer.unref?.();
         child.once("error", (error) => {
@@ -1009,15 +1282,69 @@ function runNpm(args, cwd) {
             clearTimeout(timer);
             if (code === 0)
                 return resolve(output);
-            reject(new Error(`npm ${args[0] ?? ""} failed (${code}): ${output.trim()}`));
+            reject(new Error(`npm ${action} failed (${code}): ${output.trim()}`));
         });
     });
 }
-const operations = new Map();
+const operationsKey = Symbol.for("elementspanel.npm.operations");
+const shared = globalThis;
+const operations = (shared[operationsKey] ??= new Map());
+const LOCK_NAME = ".elementspanel-npm.lock";
+async function acquireProjectLock(projectRoot) {
+    await fs_extra_1.default.ensureDir(projectRoot);
+    const directory = path_1.default.join(projectRoot, LOCK_NAME);
+    const deadline = Date.now() + 11 * 60 * 1000;
+    while (true) {
+        try {
+            await fs_extra_1.default.mkdir(directory);
+            await fs_extra_1.default.writeJson(path_1.default.join(directory, "owner.json"), { pid: process.pid });
+            return () => fs_extra_1.default.remove(directory);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                const owner = await fs_extra_1.default.readJson(path_1.default.join(directory, "owner.json"));
+                try {
+                    process.kill(owner.pid, 0);
+                }
+                catch (failure) {
+                    if (failure.code === "ESRCH") {
+                        await fs_extra_1.default.remove(directory);
+                        continue;
+                    }
+                }
+            }
+            catch {
+                if (Date.now() - ((await fs_extra_1.default.stat(directory).catch(() => null))?.mtimeMs ?? Date.now()) >
+                    60_000) {
+                    await fs_extra_1.default.remove(directory);
+                    continue;
+                }
+            }
+            if (Date.now() > deadline)
+                throw new Error("Another npm plugin operation is still running.");
+            await new Promise((resolve) => setTimeout(resolve, 200));
+        }
+    }
+}
+function npmPluginOperationPending() {
+    const { packageRoot, projectRoot } = npmPluginRoots();
+    return (operations.size > 0 ||
+        [packageRoot, projectRoot].some((root) => fs_extra_1.default.existsSync(path_1.default.join(root, LOCK_NAME))));
+}
 function withProjectLock(projectRoot, operation) {
     const key = process.platform === "win32" ? projectRoot.toLowerCase() : projectRoot;
     const previous = operations.get(key) ?? Promise.resolve();
-    const result = previous.then(operation);
+    const result = previous.then(async () => {
+        const release = await acquireProjectLock(projectRoot);
+        try {
+            return await operation();
+        }
+        finally {
+            await release();
+        }
+    });
     const settled = result.then(() => { }, () => { });
     operations.set(key, settled);
     return result.finally(() => {
@@ -1025,18 +1352,18 @@ function withProjectLock(projectRoot, operation) {
             operations.delete(key);
     });
 }
-/**
- * Installs (or updates) one npm plugin as a project dependency.
- *
- * The version is pinned with `--save-exact`: the panel performs updates, so a
- * later bare `npm install` must not silently move the plugin to another release.
- */
+/** Core services keep the connection and management interface available. */
+function isEssentialNpmPlugin(pluginId) {
+    return ["i18n", "storage", "runtime", "server", "console", "config"].includes(pluginId);
+}
+/** npm changes dependencies and lockfiles; only append our plugin mapping afterwards. */
 async function installNpmPlugin(options) {
-    const { name, pluginId, version, side } = options;
-    if (!PLUGIN_ID.test(pluginId))
-        throw new Error(`Invalid plugin id: ${pluginId}`);
+    const { name, side } = options;
+    const version = options.version || "latest";
     if (!PACKAGE_NAME.test(name))
         throw new Error(`Invalid npm plugin package: ${name}`);
+    if (options.pluginId && !PLUGIN_ID.test(options.pluginId))
+        throw new Error(`Invalid plugin id: ${options.pluginId}`);
     if (!VERSION.test(version))
         throw new Error(`Invalid plugin version: ${version}`);
     const { packageRoot, projectRoot } = npmPluginRoots(options);
@@ -1044,64 +1371,154 @@ async function installNpmPlugin(options) {
         const host = readJson(path_1.default.join(packageRoot, "package.json"));
         if (!host)
             throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-        if (mappingsOf(host)[pluginId] !== undefined)
-            throw new Error(`BUNDLED:${pluginId}`);
-        const existing = mappingsOf(readProjectManifest(projectRoot))[pluginId];
-        if (existing !== undefined && existing !== name)
-            throw new Error(`Plugin id ${pluginId} is already installed as ${String(existing)}.`);
-        await fs_extra_1.default.ensureDir(projectRoot);
-        await runNpm(["install", `${name}@${version}`, "--save", "--save-exact", "--no-fund", "--no-audit", "--ignore-scripts"], projectRoot);
-        let entry;
+        const hostId = Object.entries(mappingsOf(host)).find(([, value]) => value === name && dependenciesOf(host)[name] !== undefined)?.[0];
+        const targetRoot = hostId ? packageRoot : projectRoot;
+        if (hostId && isEssentialNpmPlugin(hostId))
+            throw new Error(`The essential plugin "${hostId}" cannot be replaced while running.`);
+        if (options.pluginId &&
+            mappingsOf(host)[options.pluginId] &&
+            dependenciesOf(host)[String(mappingsOf(host)[options.pluginId])] !== undefined &&
+            mappingsOf(host)[options.pluginId] !== name)
+            throw new Error(`BUNDLED:${options.pluginId}`);
+        const original = readProjectManifest(targetRoot);
+        const previous = dependenciesOf(original)[name];
+        let previousVersion = previous;
+        if (previous) {
+            try {
+                previousVersion = readPackageEntry(targetRoot, name).metadata.version || previous;
+            }
+            catch {
+                /* Keep the declared spec if the previous package is incomplete. */
+            }
+        }
+        const backups = new Map();
+        for (const filename of ["package.json", "package-lock.json", "npm-shrinkwrap.json"]) {
+            const target = path_1.default.join(targetRoot, filename);
+            backups.set(target, fs_extra_1.default.existsSync(target) ? fs_extra_1.default.readFileSync(target) : null);
+        }
         try {
-            entry = readPackageEntry(packageRoot, name);
+            await runNpm([
+                "--prefix",
+                targetRoot,
+                "install",
+                `${name}@${version}`,
+                "--save",
+                "--save-exact",
+                "--no-fund",
+                "--no-audit",
+                "--ignore-scripts"
+            ], targetRoot);
+            const entry = readPackageEntry(targetRoot, name);
+            const pluginId = options.pluginId || stringValue(objectValue(entry.metadata.elementspanel)?.id);
+            if (!PLUGIN_ID.test(pluginId))
+                throw new Error(`Invalid plugin id in ${name}.`);
+            if (mappingsOf(host)[pluginId] &&
+                dependenciesOf(host)[String(mappingsOf(host)[pluginId])] !== undefined &&
+                mappingsOf(host)[pluginId] !== name)
+                throw new Error(`Plugin id ${pluginId} belongs to a bundled dependency.`);
+            if (hostId && pluginId !== hostId)
+                throw new Error(`The package ${name} changed its plugin id from ${hostId} to ${pluginId}.`);
+            const mapped = mappingsOf(readProjectManifest(targetRoot))[pluginId];
+            if (mapped !== undefined && mapped !== name)
+                throw new Error(`Plugin id ${pluginId} is already installed as ${String(mapped)}.`);
+            const record = recordFromPackage(pluginId, name, hostId ? "bundled" : "project", entry.root, entry.metadata, side);
+            if (!record)
+                throw new Error(`The package ${name} does not provide a ${side} plugin named ${pluginId}.`);
+            if (/^[0-9]/.test(version) && record.version !== version)
+                throw new Error(`The installed package ${name} is ${record.version}, expected ${version}.`);
+            if (!process.env.EPANEL_PACKAGE_ROOT &&
+                (0, plugin_manifest_1.discoverPlugins)(path_1.default.join(packageRoot, "plugins"), {
+                    entryFields: [],
+                    includeDisabled: true
+                }).some((plugin) => plugin.manifest.id === pluginId))
+                throw new Error(`Source plugin ${pluginId} cannot be replaced with an npm dependency.`);
+            const manifest = (0, plugin_manifest_1.readPluginManifest)(record.directory);
+            if (!manifest || manifest.id !== pluginId || manifest.version !== record.version)
+                throw new Error(`The plugin manifest in ${name} does not match its package.`);
+            (0, plugin_contract_1.validatePluginCompatibility)(manifest.elements);
+            for (const field of ["backend", "frontend", "panel", "daemon", "main", "entry", "ui"]) {
+                if (typeof manifest[field] === "string" &&
+                    !(0, plugin_manifest_1.resolvePluginEntry)(record.directory, manifest, { entryFields: [field] }))
+                    throw new Error(`Invalid ${field} entry in ${name}.`);
+            }
+            const others = listNpmPlugins(side, { packageRoot, projectRoot, skipInvalid: true });
+            if (others.some((plugin) => plugin.pluginId === pluginId && plugin.name !== name))
+                throw new Error(`Plugin id ${pluginId} is already provided by another dependency.`);
+            const collision = others.find((plugin) => plugin.pluginId !== pluginId && plugin.folder === record.folder);
+            if (collision)
+                throw new Error(`Plugin asset directory ${record.folder} is already used by ${collision.name}.`);
+            const updated = readProjectManifest(targetRoot);
+            updated.dependencies = { ...dependenciesOf(updated), [name]: record.version };
+            updated.elementspanel = {
+                ...objectValue(updated.elementspanel),
+                plugins: { ...mappingsOf(updated), [pluginId]: name }
+            };
+            writeProjectManifest(targetRoot, updated);
+            return record;
         }
         catch (error) {
-            await runNpm(["uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], projectRoot).catch(() => { });
+            try {
+                await runNpm(previous
+                    ? [
+                        "--prefix",
+                        targetRoot,
+                        "install",
+                        `${name}@${String(previousVersion)}`,
+                        "--save",
+                        "--no-fund",
+                        "--no-audit",
+                        "--ignore-scripts"
+                    ]
+                    : [
+                        "--prefix",
+                        targetRoot,
+                        "uninstall",
+                        name,
+                        "--no-fund",
+                        "--no-audit",
+                        "--ignore-scripts"
+                    ], targetRoot);
+            }
+            catch (rollback) {
+                throw new Error(`${String(error)}; npm rollback failed: ${String(rollback)}`);
+            }
+            finally {
+                for (const [filename, content] of backups) {
+                    if (content === null)
+                        await fs_extra_1.default.remove(filename);
+                    else
+                        await fs_extra_1.default.writeFile(filename, content);
+                }
+            }
             throw error;
         }
-        const record = recordFromPackage(pluginId, name, "project", entry.root, entry.metadata, side);
-        if (!record) {
-            await runNpm(["uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], projectRoot).catch(() => { });
-            throw new Error(`The package ${name} does not provide a ${side} plugin named ${pluginId}.`);
-        }
-        if (record.version !== version) {
-            await runNpm(["uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], projectRoot).catch(() => { });
-            throw new Error(`The installed package ${name} is ${record.version}, expected ${version}.`);
-        }
-        const manifest = readProjectManifest(projectRoot);
-        const dependencies = { ...dependenciesOf(manifest), [name]: version };
-        const elementspanel = { ...(objectValue(manifest.elementspanel) ?? {}) };
-        const plugins = { ...mappingsOf(manifest), [pluginId]: name };
-        manifest.dependencies = dependencies;
-        manifest.elementspanel = { ...elementspanel, plugins };
-        writeProjectManifest(projectRoot, manifest);
-        return record;
     });
 }
-/** Removes one project-installed npm plugin. Built-in packages are left alone. */
+/** Remove the dependency from the manifest that owns it, preserving user configuration. */
 async function uninstallNpmPlugin(pluginId, options = {}) {
     if (!PLUGIN_ID.test(pluginId))
         throw new Error(`Invalid plugin id: ${pluginId}`);
+    if (isEssentialNpmPlugin(pluginId))
+        throw new Error(`The essential plugin "${pluginId}" cannot be uninstalled.`);
     const { packageRoot, projectRoot } = npmPluginRoots(options);
     return withProjectLock(projectRoot, async () => {
         const host = readJson(path_1.default.join(packageRoot, "package.json"));
-        if (host && mappingsOf(host)[pluginId] !== undefined)
-            throw new Error(`BUNDLED:${pluginId}`);
-        const manifest = readProjectManifest(projectRoot);
-        const name = mappingsOf(manifest)[pluginId];
+        const bundledName = mappingsOf(host)[pluginId];
+        const targetRoot = typeof bundledName === "string" && dependenciesOf(host)[bundledName] !== undefined
+            ? packageRoot
+            : projectRoot;
+        const manifest = readProjectManifest(targetRoot);
+        const name = mappingsOf(manifest)[pluginId] ??
+            listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId)?.name;
         if (typeof name !== "string" || !PACKAGE_NAME.test(name))
             return null;
         const record = listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId);
-        await runNpm(["uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], projectRoot);
-        const plugins = { ...mappingsOf(manifest) };
+        await runNpm(["--prefix", targetRoot, "uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], targetRoot);
+        const updated = readProjectManifest(targetRoot);
+        const plugins = { ...mappingsOf(updated) };
         delete plugins[pluginId];
-        const elementspanel = { ...(objectValue(manifest.elementspanel) ?? {}) };
-        if (Object.keys(plugins).length)
-            elementspanel.plugins = plugins;
-        else
-            delete elementspanel.plugins;
-        manifest.elementspanel = elementspanel;
-        writeProjectManifest(projectRoot, manifest);
+        updated.elementspanel = { ...objectValue(updated.elementspanel), plugins };
+        writeProjectManifest(targetRoot, updated);
         return record ?? null;
     });
 }
@@ -1250,6 +1667,82 @@ function pluginDirectoryRevision(directory) {
 }
 
 
+/***/ },
+
+/***/ "../common/src/plugin_watch.ts"
+(__unused_webpack_module, exports, __webpack_require__) {
+
+
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.watchNpmPlugins = watchNpmPlugins;
+const node_fs_1 = __importDefault(__webpack_require__("node:fs"));
+const node_path_1 = __importDefault(__webpack_require__("node:path"));
+const plugin_npm_1 = __webpack_require__("../common/src/plugin_npm.ts");
+/** Poll package boundaries, allowing npm to finish replacing files before reconciliation. */
+function watchNpmPlugins(ctx, side, reload, changed) {
+    const stamp = () => {
+        const { packageRoot, projectRoot } = (0, plugin_npm_1.npmPluginRoots)();
+        if (!node_fs_1.default.existsSync(node_path_1.default.join(packageRoot, "package.json")))
+            return "";
+        const files = [];
+        for (const root of [packageRoot, projectRoot])
+            for (const name of [
+                "package.json",
+                "package-lock.json",
+                "npm-shrinkwrap.json",
+                "node_modules/.package-lock.json"
+            ])
+                files.push(node_path_1.default.join(root, name));
+        for (const plugin of (0, plugin_npm_1.listNpmPlugins)(side, { skipInvalid: true }))
+            files.push(node_path_1.default.join(plugin.packageRoot, "package.json"), node_path_1.default.join(plugin.directory, "plugin.json"));
+        return JSON.stringify(files.map((filename) => {
+            try {
+                const stat = node_fs_1.default.statSync(filename);
+                return [filename, stat.size, stat.mtimeMs, stat.ctimeMs];
+            }
+            catch {
+                return [filename, null];
+            }
+        }));
+    };
+    let applied = stamp();
+    let candidate = applied;
+    let busy = false;
+    ctx.setInterval(() => {
+        if (busy || (0, plugin_npm_1.npmPluginOperationPending)())
+            return;
+        try {
+            const next = stamp();
+            if (next === applied) {
+                candidate = next;
+                return;
+            }
+            if (next !== candidate) {
+                candidate = next;
+                return;
+            }
+            busy = true;
+            void reload()
+                .then(() => {
+                applied = next;
+                candidate = next;
+                changed?.();
+            })
+                .catch((error) => ctx.logger.warn("Failed to synchronize npm plugins", error))
+                .finally(() => {
+                busy = false;
+            });
+        }
+        catch (error) {
+            ctx.logger.warn("Failed to inspect npm plugins", error);
+        }
+    }, 2000);
+}
+
+
 /***/ },
 
 /***/ "../common/src/process_tools.ts"
@@ -1571,6 +2064,9 @@ function npmPluginRoots(side) {
     const { resolveNpmPlugins } = runtimeRequire(resolver);
     return resolveNpmPlugins(packagePath(), side, { skipInvalid: true }).map((record) => ({
         directory: record.directory,
+        packageRoot: record.packageRoot,
+        packageName: record.name,
+        npmSource: record.source,
         ...(record.folder ? { folder: record.folder } : {}),
         // Built-in packages are part of the runtime's default configuration. A
         // project dependency is installed but remains dormant until the user
@@ -10320,6 +10816,13 @@ module.exports = require("node:fs");
 
 /***/ },
 
+/***/ "node:module"
+(module) {
+
+module.exports = require("node:module");
+
+/***/ },
+
 /***/ "node:os"
 (module) {
 
@@ -10341,6 +10844,13 @@ module.exports = require("node:stream");
 
 /***/ },
 
+/***/ "node:url"
+(module) {
+
+module.exports = require("node:url");
+
+/***/ },
+
 /***/ "os"
 (module) {