Merge pull request #117 from muench-dev/feature/plugin-peer-dependency-check

feat(plugins): validate peerDependency version on plugin load

Author: cmuench

lib/plugin-loader.js

@@ -4,9 +4,11 @@ import { pathToFileURL } from 'url';
 import globalDirs from 'global-dirs';
 import chalk from 'chalk';
 import { createRequire } from 'module';
+import semver from 'semver';
 import { loadConfig } from './config.js';
 
 const require = createRequire(import.meta.url);
+const TOOL_VERSION = require('../package.json').version;
 
 function expandHomeDirectory(pluginRef) {
     if (pluginRef.startsWith('~/') || pluginRef.startsWith('~\\')) {
@@ -114,13 +116,17 @@ export class PluginLoader {
         const mageConfigPath = path.join(pluginRoot, 'mage-remote-run.json');
         const pkgPath = path.join(pluginRoot, 'package.json');
 
+        // Always read package.json to check peer dependencies and static config
+        let pluginPkg = null;
+        if (await fs.promises.access(pkgPath).then(() => true).catch(() => false)) {
+            pluginPkg = JSON.parse(await fs.promises.readFile(pkgPath, 'utf8'));
+            this._checkPeerDependency(pluginName, pluginPkg);
+        }
+
         if (await fs.promises.access(mageConfigPath).then(() => true).catch(() => false)) {
             staticConfig = JSON.parse(await fs.promises.readFile(mageConfigPath, 'utf8'));
-        } else if (await fs.promises.access(pkgPath).then(() => true).catch(() => false)) {
-            const pkg = JSON.parse(await fs.promises.readFile(pkgPath, 'utf8'));
-            if (pkg['mage-remote-run']) {
-                staticConfig = pkg['mage-remote-run'];
-            }
+        } else if (pluginPkg?.['mage-remote-run']) {
+            staticConfig = pluginPkg['mage-remote-run'];
         }
 
         if (staticConfig) {
@@ -171,4 +177,16 @@ export class PluginLoader {
              console.warn(chalk.yellow(`Plugin ${pluginName} could not be loaded because it has no default export and no static config.`));
         }
     }
+
+    _checkPeerDependency(pluginName, pkg) {
+        const requiredRange = pkg.peerDependencies?.['mage-remote-run'];
+        if (!requiredRange) return;
+
+        if (!semver.satisfies(TOOL_VERSION, requiredRange)) {
+            console.warn(chalk.yellow(
+                `Plugin "${pluginName}" requires mage-remote-run "${requiredRange}" but the running version is ${TOOL_VERSION}. ` +
+                `The plugin may not work correctly.`
+            ));
+        }
+    }
 }

package-lock.json

@@ -47,6 +47,7 @@
     "mkdirp": "^3.0.1",
     "oauth-1.0a": "^2.2.6",
     "openapi-client-axios": "^7.8.0",
+    "semver": "^7.8.4",
     "zod": "^4.2.1"
   },
   "devDependencies": {

package.json

@@ -0,0 +1 @@
+export default async function (appContext) {}

tests/fixtures/compatible-peer-plugin/index.js

@@ -0,0 +1,9 @@
+{
+  "name": "compatible-peer-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "peerDependencies": {
+    "mage-remote-run": "^1.0.0"
+  }
+}

tests/fixtures/compatible-peer-plugin/package.json

@@ -0,0 +1 @@
+export default async function (appContext) {}

tests/fixtures/incompatible-peer-plugin/index.js

@@ -0,0 +1,9 @@
+{
+  "name": "incompatible-peer-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "peerDependencies": {
+    "mage-remote-run": "^99.0.0"
+  }
+}

tests/fixtures/incompatible-peer-plugin/package.json

@@ -11,6 +11,8 @@ const PKG_CONFIG_PLUGIN_PATH = path.join(__dirname, 'fixtures/pkg-config-plugin'
 const OBJECT_DEFAULT_WITH_CONFIG_PATH = path.join(__dirname, 'fixtures/object-default-with-config-plugin');
 const NESTED_SRC_PLUGIN_PATH = path.join(__dirname, 'fixtures/nested-src-plugin');
 const BAD_IMPORT_PLUGIN_PATH = path.join(__dirname, 'fixtures/bad-import-plugin');
+const COMPATIBLE_PEER_PLUGIN_PATH = path.join(__dirname, 'fixtures/compatible-peer-plugin');
+const INCOMPATIBLE_PEER_PLUGIN_PATH = path.join(__dirname, 'fixtures/incompatible-peer-plugin');
 
 // Mock Config
 jest.unstable_mockModule('../lib/config.js', () => ({
@@ -340,4 +342,37 @@ describe('PluginLoader', () => {
         delete process.env.DEBUG;
         consoleSpy.mockRestore();
     });
+
+    it('should not warn when plugin peerDependency is satisfied', async () => {
+        loadConfig.mockResolvedValue({
+            plugins: [COMPATIBLE_PEER_PLUGIN_PATH]
+        });
+
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+        const loader = new PluginLoader(context);
+        await loader.loadPlugins();
+
+        const peerWarnings = warnSpy.mock.calls.filter(args =>
+            args.some(a => typeof a === 'string' && a.includes('requires mage-remote-run'))
+        );
+        expect(peerWarnings).toHaveLength(0);
+        warnSpy.mockRestore();
+    });
+
+    it('should warn when plugin peerDependency is not satisfied', async () => {
+        loadConfig.mockResolvedValue({
+            plugins: [INCOMPATIBLE_PEER_PLUGIN_PATH]
+        });
+
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+        const loader = new PluginLoader(context);
+        await loader.loadPlugins();
+
+        const peerWarnings = warnSpy.mock.calls.filter(args =>
+            args.some(a => typeof a === 'string' && a.includes('requires mage-remote-run'))
+        );
+        expect(peerWarnings).toHaveLength(1);
+        expect(peerWarnings[0].join(' ')).toContain('^99.0.0');
+        warnSpy.mockRestore();
+    });
 });