@verdaccio/plugin-verifier 1.0.0-next-9.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# @verdaccio/plugin-verifier
+
+## 1.0.0-next-9.1
+
+### Minor Changes
+
+- a9d7b4a: feat: add @verdaccio/plugin-verifier tool package
+
+  - feat(plugin-verifier): new package to verify that a Verdaccio plugin can be loaded, instantiated, and passes sanity checks — uses `asyncLoadPlugin` from `@verdaccio/loaders` (the same loader Verdaccio runs at startup)
+  - feat(plugin-verifier): CLI built with clipanion (`verdaccio-plugin-verifier <plugin> --category <category>`)
+  - feat(plugin-verifier): programmatic API for use in plugin test suites
+  - feat(plugin-verifier): step-by-step diagnostics on failure (resolve, export, instantiate, sanity-check) with actionable error messages
+  - feat(core): add shared sanity check functions (`authSanityCheck`, `storageSanityCheck`, `middlewareSanityCheck`, `filterSanityCheck`) to `pluginUtils` in `@verdaccio/core`
+  - feat(loaders): add ESM plugin support — `tryLoadAsync` falls back from `require()` to dynamic `import()` when loading ESM plugins
+  - refactor(auth,store,server): replace inline sanity check callbacks with shared functions from `@verdaccio/core`
+  - fix(core): replace removed `pseudoRandomBytes` with `randomBytes` for Node.js 24 compatibility
+  - fix(core): fix `process-warning` ESM interop — use default import instead of named imports for CJS compatibility
+
+### Patch Changes
+
+- Updated dependencies [4eda7ac]
+- Updated dependencies [8f9bcc8]
+- Updated dependencies [a9d7b4a]
+- Updated dependencies [1d5462f]
+- Updated dependencies [fd09d4f]
+  - @verdaccio/logger@9.0.0-next-9.5
+  - @verdaccio/core@9.0.0-next-9.5
+  - @verdaccio/loaders@9.0.0-next-9.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Verdaccio contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# @verdaccio/plugin-verifier
+
+A testing tool that verifies whether a Verdaccio plugin can be properly loaded, instantiated, and passes the required sanity checks for its category.
+
+It uses `asyncLoadPlugin` from `@verdaccio/loaders` internally — the **same loader Verdaccio uses at startup** — so the verification is identical to what happens in production.
+
+Available as both a **CLI** and a **programmatic API**.
+
+This is a **pure ESM** package.
+
+## Install
+
+```bash
+npm install --save-dev @verdaccio/plugin-verifier
+```
+
+## How It Works
+
+When a plugin is verified, it runs through the same pipeline Verdaccio executes at boot time:
+
+1. **Module resolution** — can the plugin be found via `require()`?
+2. **Export validation** — does it export a function (CommonJS) or a class with a `default` export (ES6)?
+3. **Instantiation** — can the plugin be constructed with a config and plugin options?
+4. **Sanity check** — does the instance implement the required methods for its category?
+
+### Required Methods by Category
+
+| Category         | Required methods (at least one)                 |
+| ---------------- | ----------------------------------------------- |
+| `authentication` | `authenticate`, `allow_access`, `allow_publish` |
+| `storage`        | `getPackageStorage`                             |
+| `middleware`     | `register_middlewares`                          |
+| `filter`         | `filter_metadata`                               |
+
+## CLI
+
+The CLI is built with [clipanion](https://mael.dev/clipanion/) (the same framework used by `@verdaccio/cli`).
+
+### Usage
+
+```bash
+verdaccio-plugin-verifier <plugin> --category <category> [options]
+```
+
+### Options
+
+| Option                 | Description                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| `--category, -c`       | **(required)** Plugin category: `authentication`, `storage`, `middleware`, `filter` |
+| `--plugins-folder, -d` | Absolute path to the plugins directory (maps to `config.plugins`)                   |
+| `--prefix, -p`         | Plugin name prefix (default: `verdaccio`)                                           |
+
+### Examples
+
+Verify an auth plugin from a local plugins folder:
+
+```bash
+verdaccio-plugin-verifier my-auth --category authentication --plugins-folder /path/to/plugins
+```
+
+Verify a storage plugin installed via npm:
+
+```bash
+verdaccio-plugin-verifier my-storage --category storage
+```
+
+Verify a scoped plugin:
+
+```bash
+verdaccio-plugin-verifier @myorg/my-plugin --category middleware
+```
+
+Use a custom plugin prefix:
+
+```bash
+verdaccio-plugin-verifier auth --category authentication --prefix mycompany
+# resolves to "mycompany-auth"
+```
+
+### Exit Codes
+
+| Code | Meaning                                                   |
+| ---- | --------------------------------------------------------- |
+| `0`  | Plugin loaded and passed all checks                       |
+| `1`  | Plugin failed to load, instantiate, or pass sanity checks |
+
+### CI Integration
+
+Add a verification step to your plugin's CI pipeline:
+
+```yaml
+# GitHub Actions example
+- name: Verify plugin
+  run: npx verdaccio-plugin-verifier my-auth --category authentication --plugins-folder ./build
+```
+
+## Programmatic API
+
+### Verify a file-based plugin
+
+Use `pluginsFolder` to point to the directory containing your plugin. The plugin folder must be prefixed with `verdaccio-` (or your custom prefix), matching the convention Verdaccio uses to resolve plugins from a folder.
+
+```
+plugins/
+  verdaccio-my-auth/
+    index.js
+    package.json
+```
+
+```typescript
+import { PLUGIN_CATEGORY } from '@verdaccio/core';
+import { verifyPlugin } from '@verdaccio/plugin-verifier';
+
+const result = await verifyPlugin({
+  pluginPath: 'my-auth',
+  category: PLUGIN_CATEGORY.AUTHENTICATION,
+  pluginsFolder: '/absolute/path/to/plugins',
+});
+
+if (result.success) {
+  console.log(`Plugin loaded successfully (${result.pluginsLoaded} instance(s))`);
+} else {
+  console.error('Plugin verification failed:', result.error);
+}
+```
+
+### Verify an npm-installed plugin
+
+When `pluginsFolder` is omitted, the loader resolves the plugin from `node_modules` using Node's `require` algorithm, exactly as Verdaccio does in production.
+
+```typescript
+// Unscoped: looks for `verdaccio-my-auth` in node_modules
+const result = await verifyPlugin({
+  pluginPath: 'my-auth',
+  category: PLUGIN_CATEGORY.AUTHENTICATION,
+});
+
+// Scoped: looks for `@myorg/my-auth` as-is
+const result = await verifyPlugin({
+  pluginPath: '@myorg/my-auth',
+  category: PLUGIN_CATEGORY.AUTHENTICATION,
+});
+```
+
+### Use in tests (vitest / jest)
+
+This is the primary use case — add a test in your plugin repository to ensure it can be loaded by Verdaccio:
+
+```typescript
+import { describe, expect, it } from 'vitest';
+
+import { PLUGIN_CATEGORY } from '@verdaccio/core';
+import { verifyPlugin } from '@verdaccio/plugin-verifier';
+
+describe('my verdaccio plugin', () => {
+  it('should be loadable by verdaccio', async () => {
+    const result = await verifyPlugin({
+      pluginPath: 'my-auth',
+      category: PLUGIN_CATEGORY.AUTHENTICATION,
+      pluginsFolder: '/path/to/build/output',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.pluginsLoaded).toBe(1);
+  });
+});
+```
+
+### Pass plugin configuration
+
+If your plugin requires configuration to instantiate, pass it via `pluginConfig`:
+
+```typescript
+const result = await verifyPlugin({
+  pluginPath: 'my-storage',
+  category: PLUGIN_CATEGORY.STORAGE,
+  pluginsFolder: '/path/to/plugins',
+  pluginConfig: {
+    dataDir: '/tmp/verdaccio-storage',
+    maxSize: 1024,
+  },
+});
+```
+
+### Custom sanity check
+
+Override the default sanity check to verify additional methods specific to your plugin:
+
+```typescript
+const result = await verifyPlugin({
+  pluginPath: 'my-auth',
+  category: PLUGIN_CATEGORY.AUTHENTICATION,
+  pluginsFolder: '/path/to/plugins',
+  sanityCheck: (plugin) => {
+    return typeof plugin.authenticate === 'function' && typeof plugin.changePassword === 'function';
+  },
+});
+```
+
+### Custom plugin prefix
+
+If your Verdaccio instance uses a custom plugin prefix (via `server.pluginPrefix` in `config.yaml`), pass it to the verifier:
+
+```typescript
+const result = await verifyPlugin({
+  pluginPath: 'auth',
+  category: PLUGIN_CATEGORY.AUTHENTICATION,
+  pluginsFolder: '/path/to/plugins',
+  prefix: 'mycompany', // looks for "mycompany-auth" instead of "verdaccio-auth"
+});
+```
+
+## API Reference
+
+### `verifyPlugin(options: VerifyPluginOptions): Promise<VerifyResult>`
+
+#### `VerifyPluginOptions`
+
+| Property        | Type                       | Default          | Description                                                                                               |
+| --------------- | -------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `pluginPath`    | `string`                   | **(required)**   | Plugin identifier as it would appear in `config.yaml` (e.g. `my-auth`, `@scope/my-plugin`)                |
+| `category`      | `PluginCategory`           | **(required)**   | Plugin category: `authentication`, `storage`, `middleware`, or `filter`                                   |
+| `pluginConfig`  | `Record<string, unknown>`  | `{}`             | Configuration passed to the plugin constructor                                                            |
+| `sanityCheck`   | `(plugin: any) => boolean` | _(per category)_ | Custom validation function; overrides the built-in check                                                  |
+| `prefix`        | `string`                   | `'verdaccio'`    | Plugin name prefix (maps to `server.pluginPrefix`)                                                        |
+| `pluginsFolder` | `string`                   | `undefined`      | Absolute path to plugins directory (maps to `config.plugins`); when omitted, resolves from `node_modules` |
+
+#### `VerifyResult`
+
+| Property        | Type             | Description                                     |
+| --------------- | ---------------- | ----------------------------------------------- |
+| `success`       | `boolean`        | Whether the plugin loaded and passed all checks |
+| `pluginName`    | `string`         | The plugin identifier used                      |
+| `category`      | `PluginCategory` | The category verified against                   |
+| `pluginsLoaded` | `number`         | Number of plugin instances successfully loaded  |
+| `error`         | `string?`        | Error message if verification failed            |
+
+### Sanity Check Helpers
+
+Individual sanity check functions are also exported for direct use:
+
+```typescript
+import {
+  authSanityCheck,
+  filterSanityCheck,
+  getSanityCheck,
+  // returns the right check for a given category
+  middlewareSanityCheck,
+  storageSanityCheck,
+} from '@verdaccio/plugin-verifier';
+```
+
+## License
+
+MIT

package/bin/verdaccio-plugin-verifier

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+require('../build/cli.cjs');

package/build/_virtual/_rolldown/runtime.cjs

@@ -0,0 +1,23 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+exports.__toESM = __toESM;

package/build/cli.cjs

@@ -0,0 +1,15 @@
+require("./_virtual/_rolldown/runtime.cjs");
+const require_verify = require("./commands/verify.cjs");
+let clipanion = require("clipanion");
+//#region src/cli.ts
+var [node, app, ...args] = process.argv;
+var cli = new clipanion.Cli({
+	binaryLabel: "verdaccio-plugin-verifier",
+	binaryName: `${node} ${app}`,
+	binaryVersion: "1.0.0-next-9.0"
+});
+cli.register(require_verify.VerifyCommand);
+cli.runExit(args, clipanion.Cli.defaultContext);
+//#endregion
+
+//# sourceMappingURL=cli.cjs.map

package/build/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.cjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { Cli } from 'clipanion';\n\nimport { VerifyCommand } from './commands/verify';\n\nconst [node, app, ...args] = process.argv;\n\nconst cli = new Cli({\n  binaryLabel: 'verdaccio-plugin-verifier',\n  binaryName: `${node} ${app}`,\n  binaryVersion: '1.0.0-next-9.0',\n});\n\ncli.register(VerifyCommand);\ncli.runExit(args, Cli.defaultContext);\n"],"mappings":";;;;AAIA,IAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,QAAQ;AAErC,IAAM,MAAM,IAAI,UAAA,IAAI;CAClB,aAAa;CACb,YAAY,GAAG,KAAK,GAAG;CACvB,eAAe;CAChB,CAAC;AAEF,IAAI,SAAS,eAAA,cAAc;AAC3B,IAAI,QAAQ,MAAM,UAAA,IAAI,eAAe"}

package/build/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/build/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/build/cli.js

@@ -0,0 +1,14 @@
+import { VerifyCommand } from "./commands/verify.js";
+import { Cli } from "clipanion";
+//#region src/cli.ts
+var [node, app, ...args] = process.argv;
+var cli = new Cli({
+	binaryLabel: "verdaccio-plugin-verifier",
+	binaryName: `${node} ${app}`,
+	binaryVersion: "1.0.0-next-9.0"
+});
+cli.register(VerifyCommand);
+cli.runExit(args, Cli.defaultContext);
+//#endregion
+
+//# sourceMappingURL=cli.js.map

package/build/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { Cli } from 'clipanion';\n\nimport { VerifyCommand } from './commands/verify';\n\nconst [node, app, ...args] = process.argv;\n\nconst cli = new Cli({\n  binaryLabel: 'verdaccio-plugin-verifier',\n  binaryName: `${node} ${app}`,\n  binaryVersion: '1.0.0-next-9.0',\n});\n\ncli.register(VerifyCommand);\ncli.runExit(args, Cli.defaultContext);\n"],"mappings":";;;AAIA,IAAM,CAAC,MAAM,KAAK,GAAG,QAAQ,QAAQ;AAErC,IAAM,MAAM,IAAI,IAAI;CAClB,aAAa;CACb,YAAY,GAAG,KAAK,GAAG;CACvB,eAAe;CAChB,CAAC;AAEF,IAAI,SAAS,cAAc;AAC3B,IAAI,QAAQ,MAAM,IAAI,eAAe"}

package/build/commands/verify.cjs

@@ -0,0 +1,76 @@
+const require_runtime = require("../_virtual/_rolldown/runtime.cjs");
+const require_verify_plugin = require("../verify-plugin.cjs");
+let debug = require("debug");
+debug = require_runtime.__toESM(debug);
+let _verdaccio_core = require("@verdaccio/core");
+let clipanion = require("clipanion");
+//#region src/commands/verify.ts
+var debug$1 = (0, debug.default)("verdaccio:plugin:verifier:cli");
+var VALID_CATEGORIES = Object.values(_verdaccio_core.PLUGIN_CATEGORY);
+var VerifyCommand = class extends clipanion.Command {
+	static paths = [clipanion.Command.Default];
+	static usage = clipanion.Command.Usage({
+		description: "Verify that a Verdaccio plugin can be loaded and passes sanity checks",
+		details: `
+      This command uses the same plugin loader that Verdaccio runs at startup
+      (\`asyncLoadPlugin\` from \`@verdaccio/loaders\`) to verify that a plugin
+      can be resolved, instantiated, and passes the required sanity checks
+      for its category.
+
+      The plugin is identified by its short name (as it appears in \`config.yaml\`),
+      and the loader applies the prefix automatically. For example, \`my-auth\`
+      resolves to \`verdaccio-my-auth\` in the plugins folder or \`node_modules\`.
+
+      Scoped packages (e.g. \`@myorg/my-plugin\`) are used as-is without a prefix.
+
+      Enable debug output with the DEBUG environment variable:
+        DEBUG=verdaccio:plugin:verifier* verdaccio-plugin-verifier my-auth --category authentication
+    `,
+		examples: [
+			["Verify an auth plugin from a plugins folder", "verdaccio-plugin-verifier my-auth --category authentication --plugins-folder ./plugins"],
+			["Verify a storage plugin installed via npm", "verdaccio-plugin-verifier my-storage --category storage"],
+			["Verify a scoped plugin with a custom prefix", "verdaccio-plugin-verifier @myorg/my-plugin --category middleware --prefix mycompany"]
+		]
+	});
+	pluginPath = clipanion.Option.String({
+		required: true,
+		name: "plugin"
+	});
+	category = clipanion.Option.String("--category,-c", {
+		required: true,
+		description: `Plugin category: ${VALID_CATEGORIES.join(", ")}`
+	});
+	pluginsFolder = clipanion.Option.String("--plugins-folder,-d", { description: "Absolute path to the plugins directory (maps to config.plugins)" });
+	prefix = clipanion.Option.String("--prefix,-p", { description: `Plugin name prefix (default: "${_verdaccio_core.PLUGIN_PREFIX}")` });
+	async execute() {
+		debug$1("command invoked with plugin=%o category=%o", this.pluginPath, this.category);
+		debug$1("pluginsFolder=%o prefix=%o", this.pluginsFolder, this.prefix);
+		if (!VALID_CATEGORIES.includes(this.category)) {
+			this.context.stderr.write(`Error: Invalid category "${this.category}". Must be one of: ${VALID_CATEGORIES.join(", ")}\n`);
+			return 1;
+		}
+		const result = await require_verify_plugin.verifyPlugin({
+			pluginPath: this.pluginPath,
+			category: this.category,
+			pluginsFolder: this.pluginsFolder,
+			prefix: this.prefix
+		});
+		if (result.success) {
+			this.context.stdout.write(`Plugin "${result.pluginName}" verified successfully for category "${result.category}" (${result.pluginsLoaded} instance(s) loaded)\n`);
+			return 0;
+		}
+		this.context.stderr.write(`Plugin verification failed: ${result.error}\n`);
+		if (result.diagnostics && result.diagnostics.length > 0) {
+			this.context.stderr.write("\nDiagnostics:\n");
+			for (const step of result.diagnostics) {
+				const icon = step.pass ? "PASS" : "FAIL";
+				this.context.stderr.write(`  [${icon}] ${step.phase}: ${step.message}\n`);
+			}
+		}
+		return 1;
+	}
+};
+//#endregion
+exports.VerifyCommand = VerifyCommand;
+
+//# sourceMappingURL=verify.cjs.map

package/build/commands/verify.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.cjs","names":[],"sources":["../../src/commands/verify.ts"],"sourcesContent":["import { Command, Option } from 'clipanion';\nimport buildDebug from 'debug';\n\nimport { PLUGIN_CATEGORY, PLUGIN_PREFIX } from '@verdaccio/core';\n\nimport { verifyPlugin } from '../verify-plugin';\n\nconst debug = buildDebug('verdaccio:plugin:verifier:cli');\nconst VALID_CATEGORIES = Object.values(PLUGIN_CATEGORY);\n\nexport class VerifyCommand extends Command {\n  public static paths = [Command.Default];\n\n  static usage = Command.Usage({\n    description: 'Verify that a Verdaccio plugin can be loaded and passes sanity checks',\n    details: `\n      This command uses the same plugin loader that Verdaccio runs at startup\n      (\\`asyncLoadPlugin\\` from \\`@verdaccio/loaders\\`) to verify that a plugin\n      can be resolved, instantiated, and passes the required sanity checks\n      for its category.\n\n      The plugin is identified by its short name (as it appears in \\`config.yaml\\`),\n      and the loader applies the prefix automatically. For example, \\`my-auth\\`\n      resolves to \\`verdaccio-my-auth\\` in the plugins folder or \\`node_modules\\`.\n\n      Scoped packages (e.g. \\`@myorg/my-plugin\\`) are used as-is without a prefix.\n\n      Enable debug output with the DEBUG environment variable:\n        DEBUG=verdaccio:plugin:verifier* verdaccio-plugin-verifier my-auth --category authentication\n    `,\n    examples: [\n      [\n        'Verify an auth plugin from a plugins folder',\n        'verdaccio-plugin-verifier my-auth --category authentication --plugins-folder ./plugins',\n      ],\n      [\n        'Verify a storage plugin installed via npm',\n        'verdaccio-plugin-verifier my-storage --category storage',\n      ],\n      [\n        'Verify a scoped plugin with a custom prefix',\n        'verdaccio-plugin-verifier @myorg/my-plugin --category middleware --prefix mycompany',\n      ],\n    ],\n  });\n\n  private pluginPath = Option.String({\n    required: true,\n    name: 'plugin',\n  });\n\n  private category = Option.String('--category,-c', {\n    required: true,\n    description: `Plugin category: ${VALID_CATEGORIES.join(', ')}`,\n  });\n\n  private pluginsFolder = Option.String('--plugins-folder,-d', {\n    description: 'Absolute path to the plugins directory (maps to config.plugins)',\n  });\n\n  private prefix = Option.String('--prefix,-p', {\n    description: `Plugin name prefix (default: \"${PLUGIN_PREFIX}\")`,\n  });\n\n  public async execute(): Promise<number> {\n    debug('command invoked with plugin=%o category=%o', this.pluginPath, this.category);\n    debug('pluginsFolder=%o prefix=%o', this.pluginsFolder, this.prefix);\n\n    if (!VALID_CATEGORIES.includes(this.category)) {\n      this.context.stderr.write(\n        `Error: Invalid category \"${this.category}\". Must be one of: ${VALID_CATEGORIES.join(', ')}\\n`\n      );\n      return 1;\n    }\n\n    const result = await verifyPlugin({\n      pluginPath: this.pluginPath,\n      category: this.category,\n      pluginsFolder: this.pluginsFolder,\n      prefix: this.prefix,\n    });\n\n    if (result.success) {\n      this.context.stdout.write(\n        `Plugin \"${result.pluginName}\" verified successfully for category \"${result.category}\" (${result.pluginsLoaded} instance(s) loaded)\\n`\n      );\n      return 0;\n    }\n\n    this.context.stderr.write(`Plugin verification failed: ${result.error}\\n`);\n    if (result.diagnostics && result.diagnostics.length > 0) {\n      this.context.stderr.write('\\nDiagnostics:\\n');\n      for (const step of result.diagnostics) {\n        const icon = step.pass ? 'PASS' : 'FAIL';\n        this.context.stderr.write(`  [${icon}] ${step.phase}: ${step.message}\\n`);\n      }\n    }\n    return 1;\n  }\n}\n"],"mappings":";;;;;;;AAOA,IAAM,WAAA,GAAA,MAAA,SAAmB,gCAAgC;AACzD,IAAM,mBAAmB,OAAO,OAAO,gBAAA,gBAAgB;AAEvD,IAAa,gBAAb,cAAmC,UAAA,QAAQ;CACzC,OAAc,QAAQ,CAAC,UAAA,QAAQ,QAAQ;CAEvC,OAAO,QAAQ,UAAA,QAAQ,MAAM;EAC3B,aAAa;EACb,SAAS;;;;;;;;;;;;;;;EAeT,UAAU;GACR,CACE,+CACA,yFACD;GACD,CACE,6CACA,0DACD;GACD,CACE,+CACA,sFACD;GACF;EACF,CAAC;CAEF,aAAqB,UAAA,OAAO,OAAO;EACjC,UAAU;EACV,MAAM;EACP,CAAC;CAEF,WAAmB,UAAA,OAAO,OAAO,iBAAiB;EAChD,UAAU;EACV,aAAa,oBAAoB,iBAAiB,KAAK,KAAK;EAC7D,CAAC;CAEF,gBAAwB,UAAA,OAAO,OAAO,uBAAuB,EAC3D,aAAa,mEACd,CAAC;CAEF,SAAiB,UAAA,OAAO,OAAO,eAAe,EAC5C,aAAa,iCAAiC,gBAAA,cAAc,KAC7D,CAAC;CAEF,MAAa,UAA2B;AACtC,UAAM,8CAA8C,KAAK,YAAY,KAAK,SAAS;AACnF,UAAM,8BAA8B,KAAK,eAAe,KAAK,OAAO;AAEpE,MAAI,CAAC,iBAAiB,SAAS,KAAK,SAAS,EAAE;AAC7C,QAAK,QAAQ,OAAO,MAClB,4BAA4B,KAAK,SAAS,qBAAqB,iBAAiB,KAAK,KAAK,CAAC,IAC5F;AACD,UAAO;;EAGT,MAAM,SAAS,MAAM,sBAAA,aAAa;GAChC,YAAY,KAAK;GACjB,UAAU,KAAK;GACf,eAAe,KAAK;GACpB,QAAQ,KAAK;GACd,CAAC;AAEF,MAAI,OAAO,SAAS;AAClB,QAAK,QAAQ,OAAO,MAClB,WAAW,OAAO,WAAW,wCAAwC,OAAO,SAAS,KAAK,OAAO,cAAc,wBAChH;AACD,UAAO;;AAGT,OAAK,QAAQ,OAAO,MAAM,+BAA+B,OAAO,MAAM,IAAI;AAC1E,MAAI,OAAO,eAAe,OAAO,YAAY,SAAS,GAAG;AACvD,QAAK,QAAQ,OAAO,MAAM,mBAAmB;AAC7C,QAAK,MAAM,QAAQ,OAAO,aAAa;IACrC,MAAM,OAAO,KAAK,OAAO,SAAS;AAClC,SAAK,QAAQ,OAAO,MAAM,MAAM,KAAK,IAAI,KAAK,MAAM,IAAI,KAAK,QAAQ,IAAI;;;AAG7E,SAAO"}

package/build/commands/verify.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'clipanion';
+export declare class VerifyCommand extends Command {
+    static paths: never[][];
+    static usage: import('clipanion').Usage;
+    private pluginPath;
+    private category;
+    private pluginsFolder;
+    private prefix;
+    execute(): Promise<number>;
+}
+//# sourceMappingURL=verify.d.ts.map

package/build/commands/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/commands/verify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAU5C,qBAAa,aAAc,SAAQ,OAAO;IACxC,OAAc,KAAK,YAAqB;IAExC,MAAM,CAAC,KAAK,4BA+BT;IAEH,OAAO,CAAC,UAAU,CAGf;IAEH,OAAO,CAAC,QAAQ,CAGb;IAEH,OAAO,CAAC,aAAa,CAElB;IAEH,OAAO,CAAC,MAAM,CAEX;IAEU,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;CAmCxC"}

package/build/commands/verify.js

@@ -0,0 +1,74 @@
+import { verifyPlugin } from "../verify-plugin.js";
+import buildDebug from "debug";
+import { PLUGIN_CATEGORY, PLUGIN_PREFIX } from "@verdaccio/core";
+import { Command, Option } from "clipanion";
+//#region src/commands/verify.ts
+var debug = buildDebug("verdaccio:plugin:verifier:cli");
+var VALID_CATEGORIES = Object.values(PLUGIN_CATEGORY);
+var VerifyCommand = class extends Command {
+	static paths = [Command.Default];
+	static usage = Command.Usage({
+		description: "Verify that a Verdaccio plugin can be loaded and passes sanity checks",
+		details: `
+      This command uses the same plugin loader that Verdaccio runs at startup
+      (\`asyncLoadPlugin\` from \`@verdaccio/loaders\`) to verify that a plugin
+      can be resolved, instantiated, and passes the required sanity checks
+      for its category.
+
+      The plugin is identified by its short name (as it appears in \`config.yaml\`),
+      and the loader applies the prefix automatically. For example, \`my-auth\`
+      resolves to \`verdaccio-my-auth\` in the plugins folder or \`node_modules\`.
+
+      Scoped packages (e.g. \`@myorg/my-plugin\`) are used as-is without a prefix.
+
+      Enable debug output with the DEBUG environment variable:
+        DEBUG=verdaccio:plugin:verifier* verdaccio-plugin-verifier my-auth --category authentication
+    `,
+		examples: [
+			["Verify an auth plugin from a plugins folder", "verdaccio-plugin-verifier my-auth --category authentication --plugins-folder ./plugins"],
+			["Verify a storage plugin installed via npm", "verdaccio-plugin-verifier my-storage --category storage"],
+			["Verify a scoped plugin with a custom prefix", "verdaccio-plugin-verifier @myorg/my-plugin --category middleware --prefix mycompany"]
+		]
+	});
+	pluginPath = Option.String({
+		required: true,
+		name: "plugin"
+	});
+	category = Option.String("--category,-c", {
+		required: true,
+		description: `Plugin category: ${VALID_CATEGORIES.join(", ")}`
+	});
+	pluginsFolder = Option.String("--plugins-folder,-d", { description: "Absolute path to the plugins directory (maps to config.plugins)" });
+	prefix = Option.String("--prefix,-p", { description: `Plugin name prefix (default: "${PLUGIN_PREFIX}")` });
+	async execute() {
+		debug("command invoked with plugin=%o category=%o", this.pluginPath, this.category);
+		debug("pluginsFolder=%o prefix=%o", this.pluginsFolder, this.prefix);
+		if (!VALID_CATEGORIES.includes(this.category)) {
+			this.context.stderr.write(`Error: Invalid category "${this.category}". Must be one of: ${VALID_CATEGORIES.join(", ")}\n`);
+			return 1;
+		}
+		const result = await verifyPlugin({
+			pluginPath: this.pluginPath,
+			category: this.category,
+			pluginsFolder: this.pluginsFolder,
+			prefix: this.prefix
+		});
+		if (result.success) {
+			this.context.stdout.write(`Plugin "${result.pluginName}" verified successfully for category "${result.category}" (${result.pluginsLoaded} instance(s) loaded)\n`);
+			return 0;
+		}
+		this.context.stderr.write(`Plugin verification failed: ${result.error}\n`);
+		if (result.diagnostics && result.diagnostics.length > 0) {
+			this.context.stderr.write("\nDiagnostics:\n");
+			for (const step of result.diagnostics) {
+				const icon = step.pass ? "PASS" : "FAIL";
+				this.context.stderr.write(`  [${icon}] ${step.phase}: ${step.message}\n`);
+			}
+		}
+		return 1;
+	}
+};
+//#endregion
+export { VerifyCommand };
+
+//# sourceMappingURL=verify.js.map

package/build/commands/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","names":[],"sources":["../../src/commands/verify.ts"],"sourcesContent":["import { Command, Option } from 'clipanion';\nimport buildDebug from 'debug';\n\nimport { PLUGIN_CATEGORY, PLUGIN_PREFIX } from '@verdaccio/core';\n\nimport { verifyPlugin } from '../verify-plugin';\n\nconst debug = buildDebug('verdaccio:plugin:verifier:cli');\nconst VALID_CATEGORIES = Object.values(PLUGIN_CATEGORY);\n\nexport class VerifyCommand extends Command {\n  public static paths = [Command.Default];\n\n  static usage = Command.Usage({\n    description: 'Verify that a Verdaccio plugin can be loaded and passes sanity checks',\n    details: `\n      This command uses the same plugin loader that Verdaccio runs at startup\n      (\\`asyncLoadPlugin\\` from \\`@verdaccio/loaders\\`) to verify that a plugin\n      can be resolved, instantiated, and passes the required sanity checks\n      for its category.\n\n      The plugin is identified by its short name (as it appears in \\`config.yaml\\`),\n      and the loader applies the prefix automatically. For example, \\`my-auth\\`\n      resolves to \\`verdaccio-my-auth\\` in the plugins folder or \\`node_modules\\`.\n\n      Scoped packages (e.g. \\`@myorg/my-plugin\\`) are used as-is without a prefix.\n\n      Enable debug output with the DEBUG environment variable:\n        DEBUG=verdaccio:plugin:verifier* verdaccio-plugin-verifier my-auth --category authentication\n    `,\n    examples: [\n      [\n        'Verify an auth plugin from a plugins folder',\n        'verdaccio-plugin-verifier my-auth --category authentication --plugins-folder ./plugins',\n      ],\n      [\n        'Verify a storage plugin installed via npm',\n        'verdaccio-plugin-verifier my-storage --category storage',\n      ],\n      [\n        'Verify a scoped plugin with a custom prefix',\n        'verdaccio-plugin-verifier @myorg/my-plugin --category middleware --prefix mycompany',\n      ],\n    ],\n  });\n\n  private pluginPath = Option.String({\n    required: true,\n    name: 'plugin',\n  });\n\n  private category = Option.String('--category,-c', {\n    required: true,\n    description: `Plugin category: ${VALID_CATEGORIES.join(', ')}`,\n  });\n\n  private pluginsFolder = Option.String('--plugins-folder,-d', {\n    description: 'Absolute path to the plugins directory (maps to config.plugins)',\n  });\n\n  private prefix = Option.String('--prefix,-p', {\n    description: `Plugin name prefix (default: \"${PLUGIN_PREFIX}\")`,\n  });\n\n  public async execute(): Promise<number> {\n    debug('command invoked with plugin=%o category=%o', this.pluginPath, this.category);\n    debug('pluginsFolder=%o prefix=%o', this.pluginsFolder, this.prefix);\n\n    if (!VALID_CATEGORIES.includes(this.category)) {\n      this.context.stderr.write(\n        `Error: Invalid category \"${this.category}\". Must be one of: ${VALID_CATEGORIES.join(', ')}\\n`\n      );\n      return 1;\n    }\n\n    const result = await verifyPlugin({\n      pluginPath: this.pluginPath,\n      category: this.category,\n      pluginsFolder: this.pluginsFolder,\n      prefix: this.prefix,\n    });\n\n    if (result.success) {\n      this.context.stdout.write(\n        `Plugin \"${result.pluginName}\" verified successfully for category \"${result.category}\" (${result.pluginsLoaded} instance(s) loaded)\\n`\n      );\n      return 0;\n    }\n\n    this.context.stderr.write(`Plugin verification failed: ${result.error}\\n`);\n    if (result.diagnostics && result.diagnostics.length > 0) {\n      this.context.stderr.write('\\nDiagnostics:\\n');\n      for (const step of result.diagnostics) {\n        const icon = step.pass ? 'PASS' : 'FAIL';\n        this.context.stderr.write(`  [${icon}] ${step.phase}: ${step.message}\\n`);\n      }\n    }\n    return 1;\n  }\n}\n"],"mappings":";;;;;AAOA,IAAM,QAAQ,WAAW,gCAAgC;AACzD,IAAM,mBAAmB,OAAO,OAAO,gBAAgB;AAEvD,IAAa,gBAAb,cAAmC,QAAQ;CACzC,OAAc,QAAQ,CAAC,QAAQ,QAAQ;CAEvC,OAAO,QAAQ,QAAQ,MAAM;EAC3B,aAAa;EACb,SAAS;;;;;;;;;;;;;;;EAeT,UAAU;GACR,CACE,+CACA,yFACD;GACD,CACE,6CACA,0DACD;GACD,CACE,+CACA,sFACD;GACF;EACF,CAAC;CAEF,aAAqB,OAAO,OAAO;EACjC,UAAU;EACV,MAAM;EACP,CAAC;CAEF,WAAmB,OAAO,OAAO,iBAAiB;EAChD,UAAU;EACV,aAAa,oBAAoB,iBAAiB,KAAK,KAAK;EAC7D,CAAC;CAEF,gBAAwB,OAAO,OAAO,uBAAuB,EAC3D,aAAa,mEACd,CAAC;CAEF,SAAiB,OAAO,OAAO,eAAe,EAC5C,aAAa,iCAAiC,cAAc,KAC7D,CAAC;CAEF,MAAa,UAA2B;AACtC,QAAM,8CAA8C,KAAK,YAAY,KAAK,SAAS;AACnF,QAAM,8BAA8B,KAAK,eAAe,KAAK,OAAO;AAEpE,MAAI,CAAC,iBAAiB,SAAS,KAAK,SAAS,EAAE;AAC7C,QAAK,QAAQ,OAAO,MAClB,4BAA4B,KAAK,SAAS,qBAAqB,iBAAiB,KAAK,KAAK,CAAC,IAC5F;AACD,UAAO;;EAGT,MAAM,SAAS,MAAM,aAAa;GAChC,YAAY,KAAK;GACjB,UAAU,KAAK;GACf,eAAe,KAAK;GACpB,QAAQ,KAAK;GACd,CAAC;AAEF,MAAI,OAAO,SAAS;AAClB,QAAK,QAAQ,OAAO,MAClB,WAAW,OAAO,WAAW,wCAAwC,OAAO,SAAS,KAAK,OAAO,cAAc,wBAChH;AACD,UAAO;;AAGT,OAAK,QAAQ,OAAO,MAAM,+BAA+B,OAAO,MAAM,IAAI;AAC1E,MAAI,OAAO,eAAe,OAAO,YAAY,SAAS,GAAG;AACvD,QAAK,QAAQ,OAAO,MAAM,mBAAmB;AAC7C,QAAK,MAAM,QAAQ,OAAO,aAAa;IACrC,MAAM,OAAO,KAAK,OAAO,SAAS;AAClC,SAAK,QAAQ,OAAO,MAAM,MAAM,KAAK,IAAI,KAAK,MAAM,IAAI,KAAK,QAAQ,IAAI;;;AAG7E,SAAO"}