bun_plugins 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# Bun Plugins
+
+A powerful, secure, and isolated plugin system for Bun applications.
+
+## Features
+
+- **Isolated Workers**: Plugins run in their own Bun Workers, providing security and crashing isolation.
+- **Permission System**: Fine-grained control over network, file system, and environment access.
+- **Hook System**: Intercept and modify resource loading with `onResolve` and `onLoad` hooks (compatible with Bun's plugin API).
+- **Type Safe**: Written in TypeScript with full type definitions and Zod validation.
+- **Communication RPC**: Seamless communication between the host and plugins using a proxy-based RPC.
+- **Automatic Cleanup**: Resources (timers, workers, event listeners) are automatically cleaned up when a plugin is unloaded.
+
+## Installation
+
+```bash
+bun add bun_plugins
+```
+
+## Quick Start
+
+### 1. Define a Plugin
+
+```typescript
+// plugins/MyPlugin.ts
+import type { IPlugin, PluginContext } from "bun_plugins";
+
+export class MyPlugin implements IPlugin {
+  name = "my-plugin";
+  version = "1.0.0";
+
+  async onLoad(context: PluginContext) {
+    context.log.info("Plugin loaded!");
+
+    context.on("hello", (name) => {
+      console.log(`Hello, ${name}!`);
+    });
+  }
+}
+```
+
+### 2. Use the Plugin Manager
+
+```typescript
+import { PluginManager } from "bun_plugins";
+import { join } from "node:path";
+
+const manager = new PluginManager();
+
+// Register a plugin class instance
+await manager.register(new MyPlugin());
+
+// Or load an isolated plugin from a file
+await manager.registerIsolated(
+  join(process.cwd(), "plugins", "OtherPlugin.ts"),
+  "OtherPlugin"
+);
+
+// Emit events to plugins
+manager.emit("hello", "World");
+```
+
+## Security
+
+Plugins run in a restricted environment. By default, they have no permissions. You can grant them in the plugin metadata:
+
+```typescript
+export class SecurePlugin implements IPlugin {
+  name = "secure-plugin";
+  permissions = ["network"];
+  allowedDomains = ["api.example.com"];
+
+  async onLoad(context: PluginContext) {
+    const data = await context.network.fetch("https://api.example.com/data");
+  }
+}
+```
+
+## License
+
+MIT

package/dist/PluginManager.d.ts

@@ -0,0 +1,62 @@
+import { EventEmitter } from "node:events";
+import { type IPlugin, type AppEvents, type BunWorkerOptions as WorkerOptions, type OnResolveArgs, type OnLoadArgs } from "./types";
+import { HooksManager } from "./managers/HooksManager";
+export declare class PluginManager extends EventEmitter {
+    private plugins;
+    private availablePlugins;
+    private resources;
+    private dependencyManager;
+    hooksManager: HooksManager;
+    private storageRoot;
+    private hostVersion;
+    private pluginLoadTimeout;
+    private workerFactory;
+    private workerRunnerPath;
+    constructor(storageRoot?: string, options?: {
+        pluginLoadTimeout?: number;
+        workerFactory?: (url: string | URL, options?: WorkerOptions) => Worker;
+        workerRunnerPath?: string;
+    });
+    getWorkerFactory(): (url: string | URL, options?: WorkerOptions) => Worker;
+    register(plugin: IPlugin): Promise<void>;
+    registerIsolated(pluginPath: string, pluginName: string): Promise<void>;
+    unregister(pluginName: string): Promise<void>;
+    getPlugin(name: string): IPlugin | undefined;
+    listPlugins(): string[];
+    emit<K extends keyof AppEvents>(eventName: K, payload: AppEvents[K]): boolean;
+    emit(eventName: string | symbol, ...args: any[]): boolean;
+    on<K extends keyof AppEvents>(eventName: K, listener: (payload: AppEvents[K]) => void): this;
+    on(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    loadPluginsFromDirectory(directoryPath?: string): Promise<void>;
+    disablePlugin(name: string): Promise<void>;
+    enablePlugin(name: string): Promise<void>;
+    reloadPlugin(name: string): Promise<void>;
+    private updatePluginState;
+    runOnResolve(args: OnResolveArgs): Promise<{
+        path: string;
+        namespace?: string;
+    } | null>;
+    runOnLoad(args: OnLoadArgs): Promise<{
+        contents?: string;
+        loader?: string;
+    } | null>;
+    toBunPlugin(): Bun.BunPlugin;
+    private hotReloadTimer;
+    enableHotReload(pluginDir: string): void;
+    getMetrics(): {
+        totalPlugins: number;
+        activePlugins: string[];
+        resources: {
+            totalWorkers: number;
+            totalTimers: number;
+            totalListeners: number;
+            pluginCount: number;
+        };
+        hooks: {
+            onResolve: number;
+            onLoad: number;
+        };
+    };
+    getPluginStatus(): Record<string, any>;
+}
+//# sourceMappingURL=PluginManager.d.ts.map

package/dist/PluginManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManager.d.ts","sourceRoot":"","sources":["../src/PluginManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAI3C,OAAO,EACH,KAAK,OAAO,EAEZ,KAAK,SAAS,EACd,KAAK,gBAAgB,IAAI,aAAa,EACtC,KAAK,aAAa,EAClB,KAAK,UAAU,EAKlB,MAAM,SAAS,CAAC;AAMjB,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAKvD,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,gBAAgB,CAAmC;IAG3D,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,iBAAiB,CAAoB;IACtC,YAAY,EAAE,YAAY,CAAC;IAElC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,aAAa,CAAyD;IAC9E,OAAO,CAAC,gBAAgB,CAAS;gBACrB,WAAW,GAAE,MAAuC,EAAE,OAAO,CAAC,EAAE;QAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,MAAM,CAAC;QACvE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAC1B;IAwBD,gBAAgB,UA9Ba,MAAM,GAAG,GAAG,YAAY,aAAa,KAAK,MAAM;IAkCvE,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAiFxC,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6MvE,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI5C,WAAW,IAAI,MAAM,EAAE;IAId,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO;IAC7E,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO;IAKzD,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,IAAI;IAC5F,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI;IAK3E,wBAAwB,CAAC,aAAa,GAAE,MAAuC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4F/F,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1C,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBzC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAcjC,iBAAiB;IA2BzB,YAAY,CAAC,IAAI,EAAE,aAAa;;;;IAIhC,SAAS,CAAC,IAAI,EAAE,UAAU;;;;IAIhC,WAAW;IAIX,OAAO,CAAC,cAAc,CAA+B;IACrD,eAAe,CAAC,SAAS,EAAE,MAAM;IAcjC,UAAU;;;;;;;;;;;;;;IAYV,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;CAgBvC"}