@verdaccio/plugin-verifier 1.0.0-next-9.1

package/src/diagnostics.ts

@@ -0,0 +1,274 @@
+import buildDebug from 'debug';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { PLUGIN_PREFIX } from '@verdaccio/core';
+
+import { getSanityCheck } from './sanity-checks';
+import type { DiagnosticStep, VerifyPluginOptions } from './types';
+
+const debug = buildDebug('verdaccio:plugin:verifier:diagnostics');
+
+// createRequire needs an absolute path; works in both ESM and CJS contexts
+const requireModule = createRequire(
+  typeof __filename !== 'undefined' ? __filename : import.meta.url
+);
+
+function isValidExport(plugin: any): boolean {
+  return typeof plugin === 'function' || typeof plugin?.default === 'function';
+}
+
+function isES6(plugin: any): boolean {
+  return plugin && typeof plugin === 'object' && 'default' in plugin;
+}
+
+/**
+ * Resolve the ESM entry point for a directory-based plugin.
+ * import() doesn't support directory imports, so we resolve via package.json.
+ */
+export function resolveEntryPoint(dirPath: string): string {
+  const pkgPath = join(dirPath, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.exports) {
+        const dotExport = pkg.exports['.'];
+        if (typeof dotExport === 'string') {
+          return join(dirPath, dotExport);
+        }
+        if (dotExport?.import?.default) {
+          return join(dirPath, dotExport.import.default);
+        }
+        if (dotExport?.import && typeof dotExport.import === 'string') {
+          return join(dirPath, dotExport.import);
+        }
+        if (dotExport?.default) {
+          return join(dirPath, dotExport.default);
+        }
+      }
+      if (pkg.module) {
+        return join(dirPath, pkg.module);
+      }
+      if (pkg.main) {
+        return join(dirPath, pkg.main);
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return join(dirPath, 'index.js');
+}
+
+/**
+ * Try to load a module, falling back from require() to import() for ESM.
+ * Handles CJS require(), ESM require() shim errors (bundlers), and
+ * ERR_REQUIRE_ESM — always falls through to dynamic import() on any
+ * require() failure.
+ */
+async function tryResolve(modulePath: string): Promise<{ module: any; error?: string }> {
+  // Try require() first (fast path for CJS modules)
+  try {
+    return { module: requireModule(modulePath) };
+  } catch (requireErr: any) {
+    debug('require() failed for %o: %s — trying dynamic import', modulePath, requireErr.message);
+  }
+
+  // Fallback to dynamic import() for ESM modules
+  try {
+    let importPath = modulePath;
+    if (existsSync(modulePath) && existsSync(join(modulePath, 'package.json'))) {
+      importPath = resolveEntryPoint(modulePath);
+      debug('resolved ESM entry point: %o', importPath);
+    }
+    const importUrl = importPath.startsWith('/') ? pathToFileURL(importPath).href : importPath;
+    const mod = await import(importUrl);
+    return { module: mod };
+  } catch (importErr: any) {
+    return { module: null, error: importErr.message };
+  }
+}
+
+/**
+ * Runs step-by-step diagnostics to identify exactly which phase of
+ * plugin loading fails. This replicates the same resolution logic
+ * as `asyncLoadPlugin` but tests each step independently.
+ */
+export async function runDiagnostics(options: VerifyPluginOptions): Promise<DiagnosticStep[]> {
+  const {
+    pluginPath,
+    category,
+    pluginConfig = {},
+    sanityCheck: customSanityCheck,
+    prefix = PLUGIN_PREFIX,
+    pluginsFolder,
+  } = options;
+
+  const steps: DiagnosticStep[] = [];
+  const isScoped = pluginPath.startsWith('@') && pluginPath.includes('/');
+  const pluginName = isScoped ? pluginPath : `${prefix}-${pluginPath}`;
+
+  debug('running diagnostics for %o (resolved name: %o)', pluginPath, pluginName);
+
+  // --- Phase 1: Resolve ---
+  let pluginModule: any = null;
+  let resolvedFrom = '';
+
+  // Try plugins folder first
+  if (pluginsFolder) {
+    const absFolder = resolve(pluginsFolder);
+    const pluginDir = join(absFolder, pluginName);
+    debug('checking plugins folder: %o', pluginDir);
+
+    if (!existsSync(absFolder)) {
+      steps.push({
+        phase: 'resolve',
+        pass: false,
+        message: `Plugins folder does not exist: ${absFolder}`,
+      });
+      return steps;
+    }
+
+    if (!existsSync(pluginDir)) {
+      debug('plugin directory not found: %o', pluginDir);
+      steps.push({
+        phase: 'resolve',
+        pass: false,
+        message: `Plugin directory not found: ${pluginDir} — expected a folder named "${pluginName}" inside "${absFolder}"`,
+      });
+      return steps;
+    }
+
+    const result = await tryResolve(pluginDir);
+    if (result.module) {
+      pluginModule = result.module;
+      resolvedFrom = pluginDir;
+      debug('resolved from plugins folder: %o', pluginDir);
+    } else {
+      const missingDep = parseMissingDependency(result.error ?? '', pluginDir);
+      steps.push({
+        phase: 'resolve',
+        pass: false,
+        message: missingDep
+          ? `Plugin found at ${pluginDir} but has a missing dependency: ${missingDep}`
+          : `Plugin found at ${pluginDir} but failed to load: ${result.error}`,
+      });
+      return steps;
+    }
+  }
+
+  // Try node_modules if not found in plugins folder
+  if (!pluginModule) {
+    const result = await tryResolve(pluginName);
+    if (result.module) {
+      pluginModule = result.module;
+      resolvedFrom = pluginName;
+      debug('resolved from node_modules: %o', pluginName);
+    } else {
+      const missingDep = parseMissingDependency(result.error ?? '', pluginName);
+      steps.push({
+        phase: 'resolve',
+        pass: false,
+        message: missingDep
+          ? `Package "${pluginName}" found but has a missing dependency: ${missingDep}`
+          : `Package "${pluginName}" not found in node_modules — try: npm install ${pluginName}`,
+      });
+      return steps;
+    }
+  }
+
+  steps.push({
+    phase: 'resolve',
+    pass: true,
+    message: `Module resolved from ${resolvedFrom}`,
+  });
+
+  // --- Phase 2: Export validation ---
+  if (!isValidExport(pluginModule)) {
+    const exportKeys = pluginModule ? Object.keys(pluginModule).join(', ') : 'none';
+    steps.push({
+      phase: 'export',
+      pass: false,
+      message: `Module does not export a function or class (default export). Exported keys: [${exportKeys}]`,
+    });
+    return steps;
+  }
+
+  const moduleType = isES6(pluginModule) ? 'ES6 (default export)' : 'CommonJS (factory function)';
+  steps.push({
+    phase: 'export',
+    pass: true,
+    message: `Valid ${moduleType} plugin export detected`,
+  });
+
+  // --- Phase 3: Instantiation ---
+  let instance: any;
+  try {
+    if (isES6(pluginModule)) {
+      instance = new pluginModule.default(pluginConfig, { config: pluginConfig, logger: console });
+    } else {
+      instance = pluginModule(pluginConfig, { config: pluginConfig, logger: console });
+    }
+  } catch (err: any) {
+    steps.push({
+      phase: 'instantiate',
+      pass: false,
+      message: `Plugin threw during instantiation: ${err.message}`,
+    });
+    return steps;
+  }
+
+  if (!instance || (typeof instance !== 'object' && typeof instance !== 'function')) {
+    steps.push({
+      phase: 'instantiate',
+      pass: false,
+      message: `Plugin constructor/factory returned ${instance === null ? 'null' : typeof instance} instead of an object`,
+    });
+    return steps;
+  }
+
+  steps.push({
+    phase: 'instantiate',
+    pass: true,
+    message: 'Plugin instantiated successfully',
+  });
+
+  // --- Phase 4: Sanity check ---
+  const sanityCheck = customSanityCheck ?? getSanityCheck(category);
+  const passed = sanityCheck(instance);
+
+  if (!passed) {
+    const methods = Object.getOwnPropertyNames(Object.getPrototypeOf(instance) ?? {})
+      .filter((m) => m !== 'constructor')
+      .concat(Object.keys(instance));
+    const unique = [...new Set(methods)];
+
+    steps.push({
+      phase: 'sanity-check',
+      pass: false,
+      message: `Plugin does not implement the required methods for category "${category}". Available methods: [${unique.join(', ')}]`,
+    });
+    return steps;
+  }
+
+  steps.push({
+    phase: 'sanity-check',
+    pass: true,
+    message: `Plugin passes sanity check for category "${category}"`,
+  });
+
+  return steps;
+}
+
+/**
+ * When a MODULE_NOT_FOUND error is about a transitive dependency
+ * (not the plugin itself), extract the missing module name.
+ */
+function parseMissingDependency(message: string, pluginPath: string): string | null {
+  const match = message.match(/Cannot find module '([^']+)'/);
+  if (match && match[1] && !match[1].includes(pluginPath)) {
+    return match[1];
+  }
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { verifyPlugin } from './verify-plugin';
+export {
+  authSanityCheck,
+  storageSanityCheck,
+  middlewareSanityCheck,
+  filterSanityCheck,
+  getSanityCheck,
+} from './sanity-checks';
+export { runDiagnostics } from './diagnostics';
+export type { VerifyPluginOptions, VerifyResult, PluginCategory, DiagnosticStep } from './types';

package/src/sanity-checks.ts

@@ -0,0 +1,27 @@
+import { PLUGIN_CATEGORY, pluginUtils } from '@verdaccio/core';
+
+import type { PluginCategory } from './types';
+
+// Re-export sanity checks from @verdaccio/core for convenience.
+export const authSanityCheck = pluginUtils.authSanityCheck;
+export const storageSanityCheck = pluginUtils.storageSanityCheck;
+export const middlewareSanityCheck = pluginUtils.middlewareSanityCheck;
+export const filterSanityCheck = pluginUtils.filterSanityCheck;
+
+/**
+ * Returns the appropriate sanity check function for the given plugin category.
+ */
+export function getSanityCheck(category: PluginCategory): (plugin: any) => boolean {
+  switch (category) {
+    case PLUGIN_CATEGORY.AUTHENTICATION:
+      return authSanityCheck;
+    case PLUGIN_CATEGORY.STORAGE:
+      return storageSanityCheck;
+    case PLUGIN_CATEGORY.MIDDLEWARE:
+      return middlewareSanityCheck;
+    case PLUGIN_CATEGORY.FILTER:
+      return filterSanityCheck;
+    default:
+      return () => true;
+  }
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+import type { PLUGIN_CATEGORY } from '@verdaccio/core';
+
+export type PluginCategory = (typeof PLUGIN_CATEGORY)[keyof typeof PLUGIN_CATEGORY];
+
+export interface VerifyPluginOptions {
+  /**
+   * The plugin identifier as it would appear in config.yaml.
+   * For file-based plugins, this is the folder name inside `pluginsFolder`.
+   * For npm plugins, this is the package name (without the prefix for unscoped packages).
+   */
+  pluginPath: string;
+  /**
+   * The plugin category to verify against.
+   */
+  category: PluginCategory;
+  /**
+   * Optional plugin configuration passed as the first argument when instantiating the plugin.
+   */
+  pluginConfig?: Record<string, unknown>;
+  /**
+   * Optional custom sanity check function. If not provided, the default
+   * sanity check for the given category is used.
+   */
+  sanityCheck?: (plugin: any) => boolean;
+  /**
+   * Plugin name prefix. Defaults to 'verdaccio'.
+   */
+  prefix?: string;
+  /**
+   * Absolute path to a plugins folder for file-based plugin loading.
+   * Maps to `config.plugins` in Verdaccio configuration.
+   */
+  pluginsFolder?: string;
+  /**
+   * Absolute path to the Verdaccio configuration file.
+   * Maps to `config.configPath` — required by plugins that resolve
+   * relative paths (e.g. htpasswd resolves its `file` relative to this).
+   */
+  configPath?: string;
+}
+
+export interface DiagnosticStep {
+  /**
+   * The verification phase this diagnostic refers to.
+   */
+  phase: 'resolve' | 'export' | 'instantiate' | 'sanity-check';
+  /**
+   * Whether this phase passed.
+   */
+  pass: boolean;
+  /**
+   * Human-readable message describing the result.
+   */
+  message: string;
+}
+
+export interface VerifyResult {
+  /**
+   * Whether the plugin was successfully loaded and passed all checks.
+   */
+  success: boolean;
+  /**
+   * The plugin identifier used.
+   */
+  pluginName: string;
+  /**
+   * The plugin category verified against.
+   */
+  category: PluginCategory;
+  /**
+   * Number of plugins successfully loaded.
+   */
+  pluginsLoaded: number;
+  /**
+   * Error message if loading failed.
+   */
+  error?: string;
+  /**
+   * Step-by-step diagnostics showing which phase passed or failed.
+   * Only populated when the plugin fails to load.
+   */
+  diagnostics?: DiagnosticStep[];
+}

package/src/verify-plugin.ts

@@ -0,0 +1,115 @@
+import buildDebug from 'debug';
+import { resolve } from 'node:path';
+
+import { PLUGIN_PREFIX } from '@verdaccio/core';
+import { asyncLoadPlugin } from '@verdaccio/loaders';
+import { logger, setup } from '@verdaccio/logger';
+
+import { runDiagnostics } from './diagnostics';
+import { getSanityCheck } from './sanity-checks';
+import type { VerifyPluginOptions, VerifyResult } from './types';
+
+const debug = buildDebug('verdaccio:plugin:verifier');
+
+/**
+ * Verifies that a plugin can be loaded by Verdaccio.
+ *
+ * Uses `asyncLoadPlugin` from `@verdaccio/loaders` — the same loader
+ * Verdaccio uses at startup — so the verification is identical to what
+ * happens in production.
+ *
+ * Steps verified:
+ * 1. Module resolution — can the plugin be found/required?
+ * 2. Export validation — does it export a function or a class (default export)?
+ * 3. Instantiation — can the plugin be instantiated with a config and options?
+ * 4. Sanity check — does the instance implement the required methods for its category?
+ *
+ * When loading fails, detailed diagnostics are included in the result
+ * to pinpoint exactly which step failed and why.
+ */
+export async function verifyPlugin(options: VerifyPluginOptions): Promise<VerifyResult> {
+  const {
+    pluginPath,
+    category,
+    pluginConfig = {},
+    sanityCheck: customSanityCheck,
+    prefix = PLUGIN_PREFIX,
+    pluginsFolder,
+    configPath,
+  } = options;
+
+  debug('verifying plugin %o for category %o', pluginPath, category);
+  debug('prefix: %o, pluginsFolder: %o', prefix, pluginsFolder);
+
+  await setup({});
+
+  const sanityCheck = customSanityCheck ?? getSanityCheck(category);
+  debug('using %s sanity check', customSanityCheck ? 'custom' : 'default');
+
+  const config: any = {
+    ...pluginConfig,
+  };
+
+  if (pluginsFolder) {
+    config.plugins = resolve(pluginsFolder);
+    debug('resolved plugins folder: %o', config.plugins);
+  }
+
+  if (configPath) {
+    config.configPath = configPath;
+    debug('config path: %o', config.configPath);
+  }
+
+  const pluginConfigs = { [pluginPath]: pluginConfig };
+  debug('plugin config: %o', pluginConfigs);
+
+  try {
+    const plugins = await asyncLoadPlugin(
+      pluginConfigs,
+      { config, logger },
+      sanityCheck,
+      false,
+      prefix,
+      category
+    );
+
+    debug('plugins loaded: %o', plugins.length);
+
+    if (plugins.length > 0) {
+      debug('verification succeeded for %o', pluginPath);
+      return {
+        success: true,
+        pluginName: pluginPath,
+        category,
+        pluginsLoaded: plugins.length,
+      };
+    }
+
+    debug('verification failed, running diagnostics for %o', pluginPath);
+    const diagnostics = await runDiagnostics(options);
+    const failedStep = diagnostics.find((d) => !d.pass);
+
+    return {
+      success: false,
+      pluginName: pluginPath,
+      category,
+      pluginsLoaded: 0,
+      error:
+        failedStep?.message ??
+        `Plugin "${pluginPath}" could not be loaded for category "${category}"`,
+      diagnostics,
+    };
+  } catch (err: any) {
+    debug('verification error for %o: %o', pluginPath, err.message);
+    const diagnostics = await runDiagnostics(options);
+
+    return {
+      success: false,
+      pluginName: pluginPath,
+      category,
+      pluginsLoaded: 0,
+      error: err.message,
+      diagnostics,
+    };
+  }
+}