@libria/plugin-loader 0.1.0

package/.clean-publish.hash

@@ -0,0 +1 @@
+2c5f1c5099692fedf676cdc07ff278087d4924891f85b79c5b08647b51e7ed06

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CinemaCove
+
+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,228 @@
+# @libria/plugin-loader
+
+A simple, type-safe plugin loader for Node.js applications. Supports both ESM and CommonJS plugins with glob pattern discovery.
+
+## Installation
+
+```bash
+npm install @libria/plugin-loader
+```
+
+## Quick Start
+
+### 1. Create a Plugin
+
+Create a `plugin.json` manifest in your plugin directory:
+
+```json
+{
+  "name": "my-plugin",
+  "pluginType": "greeting",
+  "module": "./dist/index.mjs"
+}
+```
+
+Create the plugin module:
+
+```typescript
+// src/index.ts
+import { definePlugin } from '@libria/plugin-loader';
+
+export default definePlugin('greeting', {
+  sayHello(name: string) {
+    return `Hello, ${name}!`;
+  }
+});
+```
+
+### 2. Load Plugins
+
+```typescript
+import { findPlugins, loadPlugin, loadAllPlugins } from '@libria/plugin-loader';
+
+// Load all plugins from a directory
+const plugins = await loadAllPlugins('./plugins', 'greeting');
+
+for (const plugin of plugins) {
+  console.log(plugin.api.sayHello('World'));
+}
+```
+
+## API
+
+### `definePlugin<T>(pluginType, api, name?)`
+
+Helper function to create a type-safe plugin export.
+
+```typescript
+import { definePlugin } from '@libria/plugin-loader';
+
+export default definePlugin('my-type', {
+  myMethod() {
+    return 'Hello!';
+  }
+});
+```
+
+### `findPlugins(pattern, pluginType?)`
+
+Discovers plugins by scanning directories for `plugin.json` manifests.
+
+```typescript
+import { findPlugins } from '@libria/plugin-loader';
+
+// Simple directory path (scans one level deep)
+const manifests = await findPlugins('./plugins');
+
+// Glob pattern
+const manifests = await findPlugins('./plugins/*-plugin');
+
+// Recursive glob
+const manifests = await findPlugins('./plugins/**/dist');
+
+// Filter by plugin type
+const manifests = await findPlugins('./plugins', 'greeting');
+```
+
+### `loadPlugin<T>(manifest)`
+
+Loads a single plugin from its manifest. Supports both ESM (`module`) and CommonJS (`main`) entry points.
+
+```typescript
+import { findPlugins, loadPlugin } from '@libria/plugin-loader';
+
+const [manifest] = await findPlugins('./plugins/my-plugin');
+const plugin = await loadPlugin<{ sayHello: (name: string) => string }>(manifest);
+
+console.log(plugin.api.sayHello('World'));
+```
+
+### `loadAllPlugins<T>(pattern, pluginType?)`
+
+Convenience function that combines `findPlugins` and `loadPlugin`. Discovers and loads all matching plugins.
+
+```typescript
+import { loadAllPlugins } from '@libria/plugin-loader';
+
+const plugins = await loadAllPlugins<{ greet: () => string }>(
+  './plugins/*-plugin',
+  'greeting'
+);
+
+for (const plugin of plugins) {
+  console.log(plugin.api.greet());
+}
+```
+
+## Plugin Manifest
+
+The `plugin.json` file defines plugin metadata:
+
+| Field        | Type   | Required | Description                          |
+|--------------|--------|----------|--------------------------------------|
+| `name`       | string | Yes      | Unique plugin identifier             |
+| `pluginType` | string | Yes      | Plugin category/type for filtering   |
+| `module`     | string | No       | ESM entry point (relative path)      |
+| `main`       | string | No       | CommonJS entry point (relative path) |
+| `types`      | string | No       | TypeScript declaration file          |
+
+At least one of `module` or `main` must be specified.
+
+### ESM Plugin Example
+
+```
+my-plugin/
+  plugin.json
+  dist/
+    index.mjs
+```
+
+```json
+{
+  "name": "my-plugin",
+  "pluginType": "feature",
+  "module": "./dist/index.mjs"
+}
+```
+
+### CommonJS Plugin Example
+
+```
+my-plugin/
+  plugin.json
+  dist/
+    index.cjs
+```
+
+```json
+{
+  "name": "my-plugin",
+  "pluginType": "feature",
+  "main": "./dist/index.cjs"
+}
+```
+
+### Nested Manifest (dist folder)
+
+You can place `plugin.json` inside the `dist` folder and use glob patterns to discover it:
+
+```
+my-plugin/
+  dist/
+    plugin.json
+    index.mjs
+```
+
+```typescript
+// Discover plugins with manifest in dist/
+const plugins = await loadAllPlugins('./plugins/*/dist');
+```
+
+## Types
+
+### `LibriaPlugin<T>`
+
+```typescript
+interface LibriaPlugin<T = unknown> {
+  readonly pluginType: string;
+  readonly name?: string;
+  readonly api: T;
+}
+```
+
+### `PluginManifest`
+
+```typescript
+interface PluginManifest {
+  readonly name: string;
+  readonly pluginType: string;
+  readonly main?: string;
+  readonly module?: string;
+  readonly types?: string;
+  readonly __dir: string; // Resolved absolute path
+}
+```
+
+## Error Handling
+
+The library throws specific errors for common issues:
+
+- **`PluginLoadError`** - Failed to load the plugin module
+- **`PluginInvalidExportError`** - Plugin export is not a valid object
+- **`PluginTypeMismatchError`** - Plugin type doesn't match manifest
+
+```typescript
+import { loadPlugin, PluginTypeMismatchError } from '@libria/plugin-loader';
+
+try {
+  const plugin = await loadPlugin(manifest);
+} catch (error) {
+  if (error instanceof PluginTypeMismatchError) {
+    console.error(`Type mismatch: expected ${error.expected}, got ${error.actual}`);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,2 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`fs-extra`);c=s(c);let l=require(`fast-glob`);l=s(l);let u=require(`path`);u=s(u);let d=require(`url`),f=require(`node:module`);function p(e,t,n){return{pluginType:e,name:n,api:t}}async function m(e,t){let n=[];if(e.includes(`*`)||e.includes(`{`)||e.includes(`?`)){let r=await(0,l.default)(e.replace(/\\/g,`/`),{onlyDirectories:!0,absolute:!0});for(let e of r){let r=u.default.join(e,`plugin.json`);if(!await c.default.pathExists(r))continue;let i=await c.default.readJson(r);t&&i.pluginType!==t||n.push({...i,__dir:e})}}else{if(!await c.default.pathExists(e))return[];let r=await c.default.readdir(e);for(let i of r){let r=u.default.join(e,i);if(!(await c.default.stat(r)).isDirectory())continue;let a=u.default.join(r,`plugin.json`);if(!await c.default.pathExists(a))continue;let o=await c.default.readJson(a);t&&o.pluginType!==t||n.push({...o,__dir:r})}}return n}var h=class extends Error{constructor(e,t){super(`Failed to load plugin "${e}".\n${String(t)}`),this.name=`PluginLoadError`,this.pluginName=e,this.cause=t}},g=class extends Error{constructor(e){super(`Plugin "${e}" has invalid export`),this.name=`PluginInvalidExportError`,this.pluginName=e}},_=class extends Error{constructor(e,t,n){super(`Plugin type mismatch for "${e}": "${n}" !== "${t}"`),this.name=`PluginTypeMismatchError`,this.pluginName=e,this.expected=t,this.actual=n}};const v=(0,f.createRequire)(require(`url`).pathToFileURL(__filename).href);async function y(e){let t,n;if(e.module)try{t=await import((0,d.pathToFileURL)(u.default.resolve(e.__dir,e.module)).href)}catch(e){n=e}if(!t&&e.main)try{t=v(u.default.resolve(e.__dir,e.main))}catch(e){n=e}if(!t)throw new h(e.name,n);let r=t.default??t;if(!r||typeof r!=`object`)throw new g(e.name);if(r.pluginType!==e.pluginType)throw new _(e.name,e.pluginType,r.pluginType);return r}async function b(e,t){let n=await m(e,t),r=[];for(let e of n){let t=await y(e);r.push(t)}return r}exports.PluginInvalidExportError=g,exports.PluginLoadError=h,exports.PluginTypeMismatchError=_,exports.definePlugin=p,exports.findPlugins=m,exports.loadAllPlugins=b,exports.loadPlugin=y;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["fs","require"],"sources":["../src/define-plugin.ts","../src/find-plugins.ts","../src/types.ts","../src/load-plugin.ts","../src/load-all-plugins.ts"],"sourcesContent":["import {LibriaPlugin} from \"./types\";\r\n\r\nexport function definePlugin<T>(\r\n    pluginType: string,\r\n    api: T,\r\n    name: string\r\n): LibriaPlugin<T> {\r\n    return {\r\n        pluginType: pluginType,\r\n        name,\r\n        api\r\n    };\r\n}","import {PluginManifest} from \"./types\";\r\nimport fs from \"fs-extra\";\r\nimport fg from \"fast-glob\";\r\nimport path from \"path\";\r\n\r\nexport async function findPlugins(\r\n    pattern: string,\r\n    pluginType?: string\r\n): Promise<PluginManifest[]> {\r\n    const manifests: PluginManifest[] = [];\r\n\r\n    // Check if pattern is a glob pattern or a simple path\r\n    const isGlob = pattern.includes('*') || pattern.includes('{') || pattern.includes('?');\r\n\r\n    if (isGlob) {\r\n        // Normalize path separators for fast-glob (it expects forward slashes)\r\n        const normalizedPattern = pattern.replace(/\\\\/g, '/');\r\n\r\n        // Use fast-glob to find all matching directories\r\n        const pluginDirs = await fg(normalizedPattern, {\r\n            onlyDirectories: true,\r\n            absolute: true,\r\n        });\r\n\r\n        for (const dir of pluginDirs) {\r\n            const manifestPath = path.join(dir, 'plugin.json');\r\n            if (!(await fs.pathExists(manifestPath))) continue;\r\n\r\n            const raw = await fs.readJson(manifestPath);\r\n\r\n            if (pluginType && raw.pluginType !== pluginType) continue;\r\n\r\n            manifests.push({\r\n                ...raw,\r\n                __dir: dir\r\n            });\r\n        }\r\n    } else {\r\n        // Original behavior for simple directory paths\r\n        if (!(await fs.pathExists(pattern))) return [];\r\n\r\n        const entries = await fs.readdir(pattern);\r\n\r\n        for (const entry of entries) {\r\n            const fullPath = path.join(pattern, entry);\r\n            const stat = await fs.stat(fullPath);\r\n\r\n            if (!stat.isDirectory()) continue;\r\n\r\n            const manifestPath = path.join(fullPath, 'plugin.json');\r\n            if (!(await fs.pathExists(manifestPath))) continue;\r\n\r\n            const raw = await fs.readJson(manifestPath);\r\n\r\n            if (pluginType && raw.pluginType !== pluginType) continue;\r\n\r\n            manifests.push({\r\n                ...raw,\r\n                __dir: fullPath\r\n            });\r\n        }\r\n    }\r\n\r\n    return manifests;\r\n}","export interface LibriaPlugin<T = unknown> {\r\n    readonly pluginType: string;\r\n    readonly name?: string;\r\n    readonly api: T;\r\n}\r\n\r\nexport interface PluginManifest {\r\n    readonly name: string;\r\n    readonly pluginType: string;\r\n\r\n    readonly main?: string;    // cjs\r\n    readonly module?: string;  // esm\r\n    readonly types?: string;\r\n\r\n    // resolved absolute path to the plugin folder\r\n    readonly __dir: string;\r\n}\r\n\r\n// Plugin Errors\r\n\r\nexport class PluginLoadError extends Error {\r\n    readonly pluginName: string;\r\n    readonly cause: unknown;\r\n\r\n    constructor(pluginName: string, cause: unknown) {\r\n        super(`Failed to load plugin \"${pluginName}\".\\n${String(cause)}`);\r\n        this.name = 'PluginLoadError';\r\n        this.pluginName = pluginName;\r\n        this.cause = cause;\r\n    }\r\n}\r\n\r\nexport class PluginInvalidExportError extends Error {\r\n    readonly pluginName: string;\r\n\r\n    constructor(pluginName: string) {\r\n        super(`Plugin \"${pluginName}\" has invalid export`);\r\n        this.name = 'PluginInvalidExportError';\r\n        this.pluginName = pluginName;\r\n    }\r\n}\r\n\r\nexport class PluginTypeMismatchError extends Error {\r\n    readonly pluginName: string;\r\n    readonly expected: string;\r\n    readonly actual: string;\r\n\r\n    constructor(pluginName: string, expected: string, actual: string) {\r\n        super(\r\n            `Plugin type mismatch for \"${pluginName}\": ` +\r\n            `\"${actual}\" !== \"${expected}\"`\r\n        );\r\n        this.name = 'PluginTypeMismatchError';\r\n        this.pluginName = pluginName;\r\n        this.expected = expected;\r\n        this.actual = actual;\r\n    }\r\n}","import {\r\n    LibriaPlugin,\r\n    PluginManifest,\r\n    PluginLoadError,\r\n    PluginInvalidExportError,\r\n    PluginTypeMismatchError\r\n} from \"./types\";\r\nimport path from \"path\";\r\nimport {pathToFileURL} from \"url\";\r\nimport {createRequire} from \"node:module\";\r\n\r\nconst require = createRequire(import.meta.url);\r\n\r\nexport async function loadPlugin<T = unknown>(\r\n    manifest: PluginManifest\r\n): Promise<LibriaPlugin<T>> {\r\n    let mod: any;\r\n    let lastError: unknown;\r\n\r\n    // 1 Try ESM first\r\n    if (manifest.module) {\r\n        try {\r\n            const esmPath = path.resolve(manifest.__dir, manifest.module);\r\n            mod = await import(pathToFileURL(esmPath).href);\r\n        } catch (err) {\r\n            lastError = err;\r\n        }\r\n    }\r\n\r\n    // 2 Fallback to CJS\r\n    if (!mod && manifest.main) {\r\n        try {\r\n            const cjsPath = path.resolve(manifest.__dir, manifest.main);\r\n            mod = require(cjsPath);\r\n        } catch (err) {\r\n            lastError = err;\r\n        }\r\n    }\r\n\r\n    if (!mod) {\r\n        throw new PluginLoadError(manifest.name, lastError);\r\n    }\r\n\r\n    // 3️⃣ Normalize export\r\n    const plugin = (mod.default ?? mod) as LibriaPlugin<T>;\r\n\r\n    if (!plugin || typeof plugin !== 'object') {\r\n        throw new PluginInvalidExportError(manifest.name);\r\n    }\r\n\r\n    if (plugin.pluginType !== manifest.pluginType) {\r\n        throw new PluginTypeMismatchError(\r\n            manifest.name,\r\n            manifest.pluginType,\r\n            plugin.pluginType\r\n        );\r\n    }\r\n\r\n    return plugin;\r\n}","import {LibriaPlugin} from \"./types\";\r\nimport {findPlugins} from \"./find-plugins\";\r\nimport {loadPlugin} from \"./load-plugin\";\r\n\r\nexport async function loadAllPlugins<T = unknown>(\r\n    pattern: string,\r\n    pluginType?: string\r\n): Promise<LibriaPlugin<T>[]> {\r\n    const manifests = await findPlugins(pattern, pluginType);\r\n    const plugins: LibriaPlugin<T>[] = [];\r\n\r\n    for (const manifest of manifests) {\r\n        const plugin = await loadPlugin<T>(manifest);\r\n        plugins.push(plugin);\r\n    }\r\n\r\n    return plugins;\r\n}\r\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+//#region src/types.d.ts
+interface LibriaPlugin<T = unknown> {
+  readonly pluginType: string;
+  readonly name?: string;
+  readonly api: T;
+}
+interface PluginManifest {
+  readonly name: string;
+  readonly pluginType: string;
+  readonly main?: string;
+  readonly module?: string;
+  readonly types?: string;
+  readonly __dir: string;
+}
+declare class PluginLoadError extends Error {
+  readonly pluginName: string;
+  readonly cause: unknown;
+  constructor(pluginName: string, cause: unknown);
+}
+declare class PluginInvalidExportError extends Error {
+  readonly pluginName: string;
+  constructor(pluginName: string);
+}
+declare class PluginTypeMismatchError extends Error {
+  readonly pluginName: string;
+  readonly expected: string;
+  readonly actual: string;
+  constructor(pluginName: string, expected: string, actual: string);
+}
+//#endregion
+//#region src/define-plugin.d.ts
+declare function definePlugin<T>(pluginType: string, api: T, name: string): LibriaPlugin<T>;
+//#endregion
+//#region src/find-plugins.d.ts
+declare function findPlugins(pattern: string, pluginType?: string): Promise<PluginManifest[]>;
+//#endregion
+//#region src/load-plugin.d.ts
+declare function loadPlugin<T = unknown>(manifest: PluginManifest): Promise<LibriaPlugin<T>>;
+//#endregion
+//#region src/load-all-plugins.d.ts
+declare function loadAllPlugins<T = unknown>(pattern: string, pluginType?: string): Promise<LibriaPlugin<T>[]>;
+//#endregion
+export { LibriaPlugin, PluginInvalidExportError, PluginLoadError, PluginManifest, PluginTypeMismatchError, definePlugin, findPlugins, loadAllPlugins, loadPlugin };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,44 @@
+//#region src/types.d.ts
+interface LibriaPlugin<T = unknown> {
+  readonly pluginType: string;
+  readonly name?: string;
+  readonly api: T;
+}
+interface PluginManifest {
+  readonly name: string;
+  readonly pluginType: string;
+  readonly main?: string;
+  readonly module?: string;
+  readonly types?: string;
+  readonly __dir: string;
+}
+declare class PluginLoadError extends Error {
+  readonly pluginName: string;
+  readonly cause: unknown;
+  constructor(pluginName: string, cause: unknown);
+}
+declare class PluginInvalidExportError extends Error {
+  readonly pluginName: string;
+  constructor(pluginName: string);
+}
+declare class PluginTypeMismatchError extends Error {
+  readonly pluginName: string;
+  readonly expected: string;
+  readonly actual: string;
+  constructor(pluginName: string, expected: string, actual: string);
+}
+//#endregion
+//#region src/define-plugin.d.ts
+declare function definePlugin<T>(pluginType: string, api: T, name: string): LibriaPlugin<T>;
+//#endregion
+//#region src/find-plugins.d.ts
+declare function findPlugins(pattern: string, pluginType?: string): Promise<PluginManifest[]>;
+//#endregion
+//#region src/load-plugin.d.ts
+declare function loadPlugin<T = unknown>(manifest: PluginManifest): Promise<LibriaPlugin<T>>;
+//#endregion
+//#region src/load-all-plugins.d.ts
+declare function loadAllPlugins<T = unknown>(pattern: string, pluginType?: string): Promise<LibriaPlugin<T>[]>;
+//#endregion
+export { LibriaPlugin, PluginInvalidExportError, PluginLoadError, PluginManifest, PluginTypeMismatchError, definePlugin, findPlugins, loadAllPlugins, loadPlugin };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import{createRequire as e}from"node:module";import t from"fs-extra";import n from"fast-glob";import r from"path";import{pathToFileURL as i}from"url";function a(e,t,n){return{pluginType:e,name:n,api:t}}async function o(e,i){let a=[];if(e.includes(`*`)||e.includes(`{`)||e.includes(`?`)){let o=await n(e.replace(/\\/g,`/`),{onlyDirectories:!0,absolute:!0});for(let e of o){let n=r.join(e,`plugin.json`);if(!await t.pathExists(n))continue;let o=await t.readJson(n);i&&o.pluginType!==i||a.push({...o,__dir:e})}}else{if(!await t.pathExists(e))return[];let n=await t.readdir(e);for(let o of n){let n=r.join(e,o);if(!(await t.stat(n)).isDirectory())continue;let s=r.join(n,`plugin.json`);if(!await t.pathExists(s))continue;let c=await t.readJson(s);i&&c.pluginType!==i||a.push({...c,__dir:n})}}return a}var s=class extends Error{constructor(e,t){super(`Failed to load plugin "${e}".\n${String(t)}`),this.name=`PluginLoadError`,this.pluginName=e,this.cause=t}},c=class extends Error{constructor(e){super(`Plugin "${e}" has invalid export`),this.name=`PluginInvalidExportError`,this.pluginName=e}},l=class extends Error{constructor(e,t,n){super(`Plugin type mismatch for "${e}": "${n}" !== "${t}"`),this.name=`PluginTypeMismatchError`,this.pluginName=e,this.expected=t,this.actual=n}};const u=e(import.meta.url);async function d(e){let t,n;if(e.module)try{t=await import(i(r.resolve(e.__dir,e.module)).href)}catch(e){n=e}if(!t&&e.main)try{t=u(r.resolve(e.__dir,e.main))}catch(e){n=e}if(!t)throw new s(e.name,n);let a=t.default??t;if(!a||typeof a!=`object`)throw new c(e.name);if(a.pluginType!==e.pluginType)throw new l(e.name,e.pluginType,a.pluginType);return a}async function f(e,t){let n=await o(e,t),r=[];for(let e of n){let t=await d(e);r.push(t)}return r}export{c as PluginInvalidExportError,s as PluginLoadError,l as PluginTypeMismatchError,a as definePlugin,o as findPlugins,f as loadAllPlugins,d as loadPlugin};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/define-plugin.ts","../src/find-plugins.ts","../src/types.ts","../src/load-plugin.ts","../src/load-all-plugins.ts"],"sourcesContent":["import {LibriaPlugin} from \"./types\";\r\n\r\nexport function definePlugin<T>(\r\n    pluginType: string,\r\n    api: T,\r\n    name: string\r\n): LibriaPlugin<T> {\r\n    return {\r\n        pluginType: pluginType,\r\n        name,\r\n        api\r\n    };\r\n}","import {PluginManifest} from \"./types\";\r\nimport fs from \"fs-extra\";\r\nimport fg from \"fast-glob\";\r\nimport path from \"path\";\r\n\r\nexport async function findPlugins(\r\n    pattern: string,\r\n    pluginType?: string\r\n): Promise<PluginManifest[]> {\r\n    const manifests: PluginManifest[] = [];\r\n\r\n    // Check if pattern is a glob pattern or a simple path\r\n    const isGlob = pattern.includes('*') || pattern.includes('{') || pattern.includes('?');\r\n\r\n    if (isGlob) {\r\n        // Normalize path separators for fast-glob (it expects forward slashes)\r\n        const normalizedPattern = pattern.replace(/\\\\/g, '/');\r\n\r\n        // Use fast-glob to find all matching directories\r\n        const pluginDirs = await fg(normalizedPattern, {\r\n            onlyDirectories: true,\r\n            absolute: true,\r\n        });\r\n\r\n        for (const dir of pluginDirs) {\r\n            const manifestPath = path.join(dir, 'plugin.json');\r\n            if (!(await fs.pathExists(manifestPath))) continue;\r\n\r\n            const raw = await fs.readJson(manifestPath);\r\n\r\n            if (pluginType && raw.pluginType !== pluginType) continue;\r\n\r\n            manifests.push({\r\n                ...raw,\r\n                __dir: dir\r\n            });\r\n        }\r\n    } else {\r\n        // Original behavior for simple directory paths\r\n        if (!(await fs.pathExists(pattern))) return [];\r\n\r\n        const entries = await fs.readdir(pattern);\r\n\r\n        for (const entry of entries) {\r\n            const fullPath = path.join(pattern, entry);\r\n            const stat = await fs.stat(fullPath);\r\n\r\n            if (!stat.isDirectory()) continue;\r\n\r\n            const manifestPath = path.join(fullPath, 'plugin.json');\r\n            if (!(await fs.pathExists(manifestPath))) continue;\r\n\r\n            const raw = await fs.readJson(manifestPath);\r\n\r\n            if (pluginType && raw.pluginType !== pluginType) continue;\r\n\r\n            manifests.push({\r\n                ...raw,\r\n                __dir: fullPath\r\n            });\r\n        }\r\n    }\r\n\r\n    return manifests;\r\n}","export interface LibriaPlugin<T = unknown> {\r\n    readonly pluginType: string;\r\n    readonly name?: string;\r\n    readonly api: T;\r\n}\r\n\r\nexport interface PluginManifest {\r\n    readonly name: string;\r\n    readonly pluginType: string;\r\n\r\n    readonly main?: string;    // cjs\r\n    readonly module?: string;  // esm\r\n    readonly types?: string;\r\n\r\n    // resolved absolute path to the plugin folder\r\n    readonly __dir: string;\r\n}\r\n\r\n// Plugin Errors\r\n\r\nexport class PluginLoadError extends Error {\r\n    readonly pluginName: string;\r\n    readonly cause: unknown;\r\n\r\n    constructor(pluginName: string, cause: unknown) {\r\n        super(`Failed to load plugin \"${pluginName}\".\\n${String(cause)}`);\r\n        this.name = 'PluginLoadError';\r\n        this.pluginName = pluginName;\r\n        this.cause = cause;\r\n    }\r\n}\r\n\r\nexport class PluginInvalidExportError extends Error {\r\n    readonly pluginName: string;\r\n\r\n    constructor(pluginName: string) {\r\n        super(`Plugin \"${pluginName}\" has invalid export`);\r\n        this.name = 'PluginInvalidExportError';\r\n        this.pluginName = pluginName;\r\n    }\r\n}\r\n\r\nexport class PluginTypeMismatchError extends Error {\r\n    readonly pluginName: string;\r\n    readonly expected: string;\r\n    readonly actual: string;\r\n\r\n    constructor(pluginName: string, expected: string, actual: string) {\r\n        super(\r\n            `Plugin type mismatch for \"${pluginName}\": ` +\r\n            `\"${actual}\" !== \"${expected}\"`\r\n        );\r\n        this.name = 'PluginTypeMismatchError';\r\n        this.pluginName = pluginName;\r\n        this.expected = expected;\r\n        this.actual = actual;\r\n    }\r\n}","import {\r\n    LibriaPlugin,\r\n    PluginManifest,\r\n    PluginLoadError,\r\n    PluginInvalidExportError,\r\n    PluginTypeMismatchError\r\n} from \"./types\";\r\nimport path from \"path\";\r\nimport {pathToFileURL} from \"url\";\r\nimport {createRequire} from \"node:module\";\r\n\r\nconst require = createRequire(import.meta.url);\r\n\r\nexport async function loadPlugin<T = unknown>(\r\n    manifest: PluginManifest\r\n): Promise<LibriaPlugin<T>> {\r\n    let mod: any;\r\n    let lastError: unknown;\r\n\r\n    // 1 Try ESM first\r\n    if (manifest.module) {\r\n        try {\r\n            const esmPath = path.resolve(manifest.__dir, manifest.module);\r\n            mod = await import(pathToFileURL(esmPath).href);\r\n        } catch (err) {\r\n            lastError = err;\r\n        }\r\n    }\r\n\r\n    // 2 Fallback to CJS\r\n    if (!mod && manifest.main) {\r\n        try {\r\n            const cjsPath = path.resolve(manifest.__dir, manifest.main);\r\n            mod = require(cjsPath);\r\n        } catch (err) {\r\n            lastError = err;\r\n        }\r\n    }\r\n\r\n    if (!mod) {\r\n        throw new PluginLoadError(manifest.name, lastError);\r\n    }\r\n\r\n    // 3️⃣ Normalize export\r\n    const plugin = (mod.default ?? mod) as LibriaPlugin<T>;\r\n\r\n    if (!plugin || typeof plugin !== 'object') {\r\n        throw new PluginInvalidExportError(manifest.name);\r\n    }\r\n\r\n    if (plugin.pluginType !== manifest.pluginType) {\r\n        throw new PluginTypeMismatchError(\r\n            manifest.name,\r\n            manifest.pluginType,\r\n            plugin.pluginType\r\n        );\r\n    }\r\n\r\n    return plugin;\r\n}","import {LibriaPlugin} from \"./types\";\r\nimport {findPlugins} from \"./find-plugins\";\r\nimport {loadPlugin} from \"./load-plugin\";\r\n\r\nexport async function loadAllPlugins<T = unknown>(\r\n    pattern: string,\r\n    pluginType?: string\r\n): Promise<LibriaPlugin<T>[]> {\r\n    const manifests = await findPlugins(pattern, pluginType);\r\n    const plugins: LibriaPlugin<T>[] = [];\r\n\r\n    for (const manifest of manifests) {\r\n        const plugin = await loadPlugin<T>(manifest);\r\n        plugins.push(plugin);\r\n    }\r\n\r\n    return plugins;\r\n}\r\n"],"mappings":"qJAEA,SAAgB,EACZ,EACA,EACA,EACe,CACf,MAAO,CACS,aACZ,OACA,MACH,CCNL,eAAsB,EAClB,EACA,EACyB,CACzB,IAAM,EAA8B,EAAE,CAKtC,GAFe,EAAQ,SAAS,IAAI,EAAI,EAAQ,SAAS,IAAI,EAAI,EAAQ,SAAS,IAAI,CAE1E,CAKR,IAAM,EAAa,MAAM,EAHC,EAAQ,QAAQ,MAAO,IAAI,CAGN,CAC3C,gBAAiB,GACjB,SAAU,GACb,CAAC,CAEF,IAAK,IAAM,KAAO,EAAY,CAC1B,IAAM,EAAe,EAAK,KAAK,EAAK,cAAc,CAClD,GAAI,CAAE,MAAM,EAAG,WAAW,EAAa,CAAG,SAE1C,IAAM,EAAM,MAAM,EAAG,SAAS,EAAa,CAEvC,GAAc,EAAI,aAAe,GAErC,EAAU,KAAK,CACX,GAAG,EACH,MAAO,EACV,CAAC,MAEH,CAEH,GAAI,CAAE,MAAM,EAAG,WAAW,EAAQ,CAAG,MAAO,EAAE,CAE9C,IAAM,EAAU,MAAM,EAAG,QAAQ,EAAQ,CAEzC,IAAK,IAAM,KAAS,EAAS,CACzB,IAAM,EAAW,EAAK,KAAK,EAAS,EAAM,CAG1C,GAAI,EAFS,MAAM,EAAG,KAAK,EAAS,EAE1B,aAAa,CAAE,SAEzB,IAAM,EAAe,EAAK,KAAK,EAAU,cAAc,CACvD,GAAI,CAAE,MAAM,EAAG,WAAW,EAAa,CAAG,SAE1C,IAAM,EAAM,MAAM,EAAG,SAAS,EAAa,CAEvC,GAAc,EAAI,aAAe,GAErC,EAAU,KAAK,CACX,GAAG,EACH,MAAO,EACV,CAAC,EAIV,OAAO,EC3CX,IAAa,EAAb,cAAqC,KAAM,CAIvC,YAAY,EAAoB,EAAgB,CAC5C,MAAM,0BAA0B,EAAW,MAAM,OAAO,EAAM,GAAG,CACjE,KAAK,KAAO,kBACZ,KAAK,WAAa,EAClB,KAAK,MAAQ,IAIR,EAAb,cAA8C,KAAM,CAGhD,YAAY,EAAoB,CAC5B,MAAM,WAAW,EAAW,sBAAsB,CAClD,KAAK,KAAO,2BACZ,KAAK,WAAa,IAIb,EAAb,cAA6C,KAAM,CAK/C,YAAY,EAAoB,EAAkB,EAAgB,CAC9D,MACI,6BAA6B,EAAW,MACpC,EAAO,SAAS,EAAS,GAChC,CACD,KAAK,KAAO,0BACZ,KAAK,WAAa,EAClB,KAAK,SAAW,EAChB,KAAK,OAAS,IC5CtB,MAAM,EAAU,EAAc,OAAO,KAAK,IAAI,CAE9C,eAAsB,EAClB,EACwB,CACxB,IAAI,EACA,EAGJ,GAAI,EAAS,OACT,GAAI,CAEA,EAAM,MAAM,OAAO,EADH,EAAK,QAAQ,EAAS,MAAO,EAAS,OAAO,CACpB,CAAC,YACrC,EAAK,CACV,EAAY,EAKpB,GAAI,CAAC,GAAO,EAAS,KACjB,GAAI,CAEA,EAAM,EADU,EAAK,QAAQ,EAAS,MAAO,EAAS,KAAK,CACrC,OACjB,EAAK,CACV,EAAY,EAIpB,GAAI,CAAC,EACD,MAAM,IAAI,EAAgB,EAAS,KAAM,EAAU,CAIvD,IAAM,EAAU,EAAI,SAAW,EAE/B,GAAI,CAAC,GAAU,OAAO,GAAW,SAC7B,MAAM,IAAI,EAAyB,EAAS,KAAK,CAGrD,GAAI,EAAO,aAAe,EAAS,WAC/B,MAAM,IAAI,EACN,EAAS,KACT,EAAS,WACT,EAAO,WACV,CAGL,OAAO,ECtDX,eAAsB,EAClB,EACA,EAC0B,CAC1B,IAAM,EAAY,MAAM,EAAY,EAAS,EAAW,CAClD,EAA6B,EAAE,CAErC,IAAK,IAAM,KAAY,EAAW,CAC9B,IAAM,EAAS,MAAM,EAAc,EAAS,CAC5C,EAAQ,KAAK,EAAO,CAGxB,OAAO"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@libria/plugin-loader",
+  "version": "0.1.0",
+  "description": "Simple plugin loader for Node.js applications",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LibriaForge/plugin-loader.git"
+  },
+  "keywords": [
+    "plugin",
+    "loader",
+    "plugin loader",
+    "typescript"
+  ],
+  "author": "LibriaForge",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/LibriaForge/plugin-loader/issues"
+  },
+  "homepage": "https://github.com/LibriaForge/plugin-loader#readme",
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "fs-extra": "^11.3.3"
+  }
+}