bun_plugins 1.2.2 → 1.2.5

package/README.md

@@ -182,6 +182,130 @@ export class ConsumerPlugin implements IPlugin {
 
 ---
 
-## 📜 License
+## 🎯 Type Safety & Autocompletion
+
+The plugin system provides **full type safety and autocompletion** for inter-plugin communication using declaration merging.
+
+### 📚 Complete Guide
+
+For detailed documentation on the type system, see [`docs/types-guide.md`](docs/types-guide.md).
+
+### 🚀 Quick Start
+
+#### Step 1: Create a types file
+
+Create a `.d.ts` file in your project (e.g., `plugins/types.d.ts`):
+
+```typescript
+import type { BasePluginApi } from "bun_plugins/src/types/plugin-registry-base";
+
+// Define the API interface for your plugin
+export interface MathPluginApi extends BasePluginApi {
+  add(a: number, b: number): number;
+  multiply(a: number, b: number): number;
+}
+
+// Extend the PluginFactory with your plugin
+declare module "bun_plugins" {
+  export interface PluginFactory {
+    "math-plugin": {
+      name: "math-plugin";
+      version: "1.0.0";
+      class: any;
+      api: MathPluginApi;
+    };
+  }
+}
+```
+
+#### Step 2: Register the API in your plugin
+
+```typescript
+import { Plugin, PluginContext } from "bun_plugins";
+
+export class MathPlugin extends Plugin {
+  name = "math-plugin";
+  version = "1.0.0";
+
+  override onLoad(context: PluginContext) {
+    // Register the API for other plugins to use
+    context.registerApi({
+      add: this.add.bind(this),
+      multiply: this.multiply.bind(this)
+    });
+  }
+
+  add(a: number, b: number): number {
+    return a + b;
+  }
+  
+  multiply(a: number, b: number): number {
+    return a * b;
+  }
+}
+```
+
+#### Step 3: Use with full autocompletion
+
+```typescript
+import { definePlugin } from "bun_plugins";
+
+export default definePlugin({
+  name: "my-app",
+  version: "1.0.0",
+
+  async onLoad(context) {
+    // ✅ Full autocompletion and type safety!
+    const mathPlugin = await context.getPlugin('math-plugin');
+    
+    if (mathPlugin) {
+      const result = mathPlugin.add(1, 2); // ✅ Autocompletion works
+      context.log.info(`Result: ${result}`);
+      
+      // TypeScript will show errors for non-existent methods
+      // mathPlugin.nonExistentMethod(); // ❌ Error!
+    }
+  }
+});
+```
+
+### ✨ Benefits
+
+- 🎯 **Full Autocompletion**: Your IDE shows all available methods
+- 🔒 **Type Safety**: TypeScript catches errors at compile time
+- 📖 **Self-Documenting**: Interfaces serve as API documentation
+- 🔄 **Refactor-Friendly**: Safe method renaming and refactoring
+- 🌐 **Works with External Plugins**: Extend types for npm packages too
+
+### 📖 Examples
+
+- [`plugins/types.d.ts`](plugins/types.d.ts) - Complete example for this project
+- [`plugins/TypedExamplePlugin.ts`](plugins/TypedExamplePlugin.ts) - Plugin using typed access
+- [`examples/types-extension-example.d.ts`](examples/types-extension-example.d.ts) - Standalone example
+
+### 🔧 TypeScript Configuration
+
+Ensure your `tsconfig.json` includes the types file:
+
+```json
+{
+  "include": [
+    "src/**/*",
+    "plugins/**/*",
+    "**/*.d.ts"
+  ]
+}
+```
+
+### 💡 Tips
+
+1. **Match names exactly**: The plugin name in `PluginFactory` must match `plugin.name`
+2. **Register APIs**: Always use `context.registerApi()` to expose your plugin's API
+3. **Extend BasePluginApi**: Your API interfaces should extend `BasePluginApi` for consistency
+4. **External plugins**: You can extend types for third-party plugins the same way
+
+---
+
+##  License
 
 MIT © [memelser](https://github.com/nglmercer)

package/dist/examples/action-registry-declarative.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Declarative Action Registry Example
+ *
+ * This example demonstrates a clean, declarative approach to building
+ * plugins with action registries using shared utilities.
+ */
+declare const createRegistryPlugin: () => import("bun_plugins").IPlugin;
+declare const createMathPlugin: () => import("bun_plugins").IPlugin;
+declare const createTextPlugin: () => import("bun_plugins").IPlugin;
+declare const createUtilityPlugin: () => import("bun_plugins").IPlugin;
+declare const demonstrateDeclarativeActionRegistry: () => Promise<void>;
+declare const demonstrateDynamicLoading: () => Promise<void>;
+export { createRegistryPlugin, createMathPlugin, createTextPlugin, createUtilityPlugin, demonstrateDeclarativeActionRegistry, demonstrateDynamicLoading };
+//# sourceMappingURL=action-registry-declarative.d.ts.map

package/dist/examples/action-registry-declarative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry-declarative.d.ts","sourceRoot":"","sources":["../../examples/action-registry-declarative.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,QAAA,MAAM,oBAAoB,qCAUxB,CAAC;AAGH,QAAA,MAAM,gBAAgB,qCAMpB,CAAC;AAEH,QAAA,MAAM,gBAAgB,qCAMpB,CAAC;AAEH,QAAA,MAAM,mBAAmB,qCAMvB,CAAC;AA4CH,QAAA,MAAM,oCAAoC,qBA2CzC,CAAC;AAGF,QAAA,MAAM,yBAAyB,qBAS9B,CAAC;AAGF,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,oCAAoC,EACpC,yBAAyB,EAC1B,CAAC"}

package/dist/examples/action-registry-declarative.js

@@ -0,0 +1,130 @@
+/**
+ * Declarative Action Registry Example
+ *
+ * This example demonstrates a clean, declarative approach to building
+ * plugins with action registries using shared utilities.
+ */
+import { PluginManager } from "../src/PluginManager";
+import { mathActions, textActions, utilityActions, createActionRegistry } from "./shared/action-registry";
+import { createPlugin, createActionPlugin, runDemo } from "./shared/plugin-builder";
+// Central registry plugin - declarative definition
+const createRegistryPlugin = () => createPlugin({
+    name: "action-registry",
+    version: "1.0.0",
+    description: "Central action registry for all plugins",
+    onLoad: async (context) => {
+        context.log.info("ActionRegistry initialized");
+    },
+    sharedApi: createActionRegistry()
+});
+// Action plugins - declarative definitions
+const createMathPlugin = () => createActionPlugin({
+    name: "math-actions",
+    version: "1.0.0",
+    description: "Mathematical operations",
+    registryName: "action-registry",
+    actionCategories: [mathActions]
+});
+const createTextPlugin = () => createActionPlugin({
+    name: "text-actions",
+    version: "1.0.0",
+    description: "Text transformation operations",
+    registryName: "action-registry",
+    actionCategories: [textActions]
+});
+const createUtilityPlugin = () => createActionPlugin({
+    name: "utility-actions",
+    version: "1.0.0",
+    description: "Utility functions",
+    registryName: "action-registry",
+    actionCategories: [utilityActions]
+});
+// Demo runner with declarative test cases
+const runActionTests = async (registry) => {
+    const testCases = [
+        { category: "Math", tests: [
+                { action: "sum", args: [5, 3], expected: 8 },
+                { action: "multiply", args: [4, 7], expected: 28 },
+                { action: "power", args: [2, 8], expected: 256 }
+            ] },
+        { category: "Text", tests: [
+                { action: "uppercase", args: ["hello world"], expected: "HELLO WORLD" },
+                { action: "reverse", args: ["javascript"], expected: "tpircsavaj" }
+            ] },
+        { category: "Utility", tests: [
+                { action: "timestamp", args: [], validator: (result) => result > 0 }
+            ] }
+    ];
+    for (const { category, tests } of testCases) {
+        console.log(`\n${category} Operations:`);
+        for (const test of tests) {
+            try {
+                const result = registry.execute(test.action, ...test.args);
+                if ('expected' in test && test.expected !== undefined) {
+                    console.log(`  ${test.action}(${test.args.join(', ')}) = ${result}`);
+                }
+                else if ('validator' in test && test.validator) {
+                    console.log(`  ${test.action}() = ${test.validator(result) ? '✓' : '✗'}`);
+                }
+            }
+            catch (error) {
+                console.error(`  ${test.action} failed:`, error);
+            }
+        }
+    }
+};
+// Main demonstration
+const demonstrateDeclarativeActionRegistry = async () => {
+    const manager = new PluginManager();
+    // Create plugin instances
+    const registryPlugin = createRegistryPlugin();
+    const mathPlugin = createMathPlugin();
+    const textPlugin = createTextPlugin();
+    const utilityPlugin = createUtilityPlugin();
+    // Register plugins in dependency order
+    await manager.register(registryPlugin);
+    await manager.register(mathPlugin);
+    await manager.register(textPlugin);
+    await manager.register(utilityPlugin);
+    // Get the registry
+    const registry = manager.getPluginApi("action-registry");
+    if (!registry) {
+        throw new Error("Registry plugin not found");
+    }
+    console.log("\nAvailable Actions:");
+    registry.list().forEach(action => console.log(`  - ${action}`));
+    // Run tests
+    await runActionTests(registry);
+    // Error handling demo
+    console.log("\nError Handling:");
+    try {
+        registry.execute("non-existent-action");
+    }
+    catch (error) {
+        console.log(`  Caught error: ${error.message}`);
+    }
+    // Plugin info
+    console.log("\nPlugin Information:");
+    ["math-actions", "text-actions", "utility-actions"].forEach(pluginName => {
+        const api = manager.getPluginApi(pluginName);
+        if (api?.actions) {
+            console.log(`  ${pluginName}: ${api.actions.join(", ")}`);
+        }
+    });
+};
+// Dynamic loading example
+const demonstrateDynamicLoading = async () => {
+    const { join } = await import("node:path");
+    const manager = new PluginManager();
+    console.log("\nLoading plugins dynamically from directory...");
+    await manager.loadPluginsFromDirectory(join(process.cwd(), "plugins"));
+    const loaded = manager.listPlugins();
+    console.log(`Loaded ${loaded.length} plugins: ${loaded.join(", ")}`);
+};
+// Export for use
+export { createRegistryPlugin, createMathPlugin, createTextPlugin, createUtilityPlugin, demonstrateDeclarativeActionRegistry, demonstrateDynamicLoading };
+// Run if called directly
+if (import.meta.main) {
+    runDemo("Declarative Action Registry Demo", demonstrateDeclarativeActionRegistry);
+}
+//# sourceMappingURL=action-registry-declarative.js.map

package/dist/examples/action-registry-declarative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry-declarative.js","sourceRoot":"","sources":["../../examples/action-registry-declarative.ts"],"names":[],"mappings":"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"}

package/dist/examples/action-registry-example.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Action Registry Example - Simple implementation for testing
+ */
+import type { IPlugin, PluginContext } from "../src/types";
+export declare class ActionRegistryPlugin implements IPlugin {
+    name: string;
+    version: string;
+    private actionRegistry;
+    constructor();
+    onLoad(context: PluginContext): void;
+    onUnload(): void;
+}
+export declare class MathActionsPlugin implements IPlugin {
+    name: string;
+    version: string;
+    dependencies: {
+        "action-registry": string;
+    };
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): void;
+}
+export declare class TextActionsPlugin implements IPlugin {
+    name: string;
+    version: string;
+    dependencies: {
+        "action-registry": string;
+    };
+    onLoad(context: PluginContext): Promise<void>;
+    onUnload(): void;
+}
+//# sourceMappingURL=action-registry-example.d.ts.map

package/dist/examples/action-registry-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry-example.d.ts","sourceRoot":"","sources":["../../examples/action-registry-example.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA4B3D,qBAAa,oBAAqB,YAAW,OAAO;IAClD,IAAI,SAAqB;IACzB,OAAO,SAAW;IAClB,OAAO,CAAC,cAAc,CAAiB;;IAMvC,MAAM,CAAC,OAAO,EAAE,aAAa;IAa7B,QAAQ;CAGT;AAED,qBAAa,iBAAkB,YAAW,OAAO;IAC/C,IAAI,SAAkB;IACtB,OAAO,SAAW;IAClB,YAAY;;MAEV;IAEI,MAAM,CAAC,OAAO,EAAE,aAAa;IAWnC,QAAQ;CAGT;AAED,qBAAa,iBAAkB,YAAW,OAAO;IAC/C,IAAI,SAAkB;IACtB,OAAO,SAAW;IAClB,YAAY;;MAEV;IAEI,MAAM,CAAC,OAAO,EAAE,aAAa;IAYnC,QAAQ;CAGT"}

package/dist/examples/action-registry-example.js

@@ -0,0 +1,84 @@
+/**
+ * Action Registry Example - Simple implementation for testing
+ */
+class ActionRegistry {
+    actionHandlers = new Map();
+    registerAction(type, handler) {
+        this.actionHandlers.set(type, handler);
+    }
+    executeAction(type, ...args) {
+        const handler = this.actionHandlers.get(type);
+        if (!handler) {
+            throw new Error(`Acción no encontrada: ${type}`);
+        }
+        return handler(...args);
+    }
+    listActions() {
+        return Array.from(this.actionHandlers.keys());
+    }
+    hasAction(type) {
+        return this.actionHandlers.has(type);
+    }
+}
+export class ActionRegistryPlugin {
+    name = "action-registry";
+    version = "1.0.0";
+    actionRegistry;
+    constructor() {
+        this.actionRegistry = new ActionRegistry();
+    }
+    onLoad(context) {
+        context.log.info("ActionRegistry initialized");
+        // Register the API manually using the new system
+        context.registerApi({
+            registerAction: this.actionRegistry.registerAction.bind(this.actionRegistry),
+            executeAction: this.actionRegistry.executeAction.bind(this.actionRegistry),
+            listActions: this.actionRegistry.listActions.bind(this.actionRegistry),
+            hasAction: this.actionRegistry.hasAction.bind(this.actionRegistry),
+            actions: this.actionRegistry.listActions()
+        });
+    }
+    onUnload() {
+        // Cleanup is handled by the plugin manager
+    }
+}
+export class MathActionsPlugin {
+    name = "math-actions";
+    version = "1.0.0";
+    dependencies = {
+        "action-registry": "1.0.0"
+    };
+    async onLoad(context) {
+        const actionRegistry = await context.getPlugin("action-registry");
+        if (actionRegistry) {
+            actionRegistry.registerAction("sum", (a, b) => a + b);
+            actionRegistry.registerAction("multiply", (a, b) => a * b);
+            actionRegistry.registerAction("power", (base, exp) => Math.pow(base, exp));
+            context.log.info("Math actions registered");
+        }
+    }
+    onUnload() {
+        // Cleanup is handled by the plugin manager
+    }
+}
+export class TextActionsPlugin {
+    name = "text-actions";
+    version = "1.0.0";
+    dependencies = {
+        "action-registry": "1.0.0"
+    };
+    async onLoad(context) {
+        const actionRegistry = await context.getPlugin("action-registry");
+        if (actionRegistry) {
+            actionRegistry.registerAction("uppercase", (text) => text.toUpperCase());
+            actionRegistry.registerAction("lowercase", (text) => text.toLowerCase());
+            actionRegistry.registerAction("reverse", (text) => text.split('').reverse().join(''));
+            actionRegistry.registerAction("wordCount", (text) => text.trim().split(/\s+/).filter(word => word.length > 0).length);
+            context.log.info("Text actions registered");
+        }
+    }
+    onUnload() {
+        // Cleanup is handled by the plugin manager
+    }
+}
+//# sourceMappingURL=action-registry-example.js.map

package/dist/examples/action-registry-example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry-example.js","sourceRoot":"","sources":["../../examples/action-registry-example.ts"],"names":[],"mappings":"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"}

package/dist/examples/index-declarative.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Declarative Examples Index
+ *
+ * This file serves as the main entry point for all declarative examples,
+ * providing a clean overview and easy access to different use cases.
+ */
+import { demonstrateDeclarativeActionRegistry } from "./action-registry-declarative";
+import { demonstrateDeclarativeStorage } from "./storage-declarative";
+import { demonstrateDeclarativeLogging } from "./logger-declarative";
+import { demonstrateDeclarativeServer } from "./server-declarative";
+declare const exampleCatalog: ({
+    id: string;
+    name: string;
+    description: string;
+    file: string;
+    demo: () => Promise<void>;
+    features: string[];
+} | {
+    id: string;
+    name: string;
+    description: string;
+    file: string;
+    demo: () => Promise<Bun.Server<undefined>>;
+    features: string[];
+})[];
+declare const showMainMenu: () => void;
+declare const runExample: (index: number) => Promise<void>;
+declare const runAllExamples: () => Promise<void>;
+declare const interactiveMenu: () => Promise<void>;
+declare const quickRun: (exampleId: string) => Promise<void>;
+export { exampleCatalog, showMainMenu, runExample, runAllExamples, interactiveMenu, quickRun, demonstrateDeclarativeActionRegistry, demonstrateDeclarativeStorage, demonstrateDeclarativeLogging, demonstrateDeclarativeServer };
+//# sourceMappingURL=index-declarative.d.ts.map

package/dist/examples/index-declarative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-declarative.d.ts","sourceRoot":"","sources":["../../examples/index-declarative.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,oCAAoC,EAAE,MAAM,+BAA+B,CAAC;AACrF,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAGpE,QAAA,MAAM,cAAc;;;;;;;;;;;;;;IAyDnB,CAAC;AAGF,QAAA,MAAM,YAAY,YAejB,CAAC;AAGF,QAAA,MAAM,UAAU,GAAU,OAAO,MAAM,kBAkBtC,CAAC;AAGF,QAAA,MAAM,cAAc,qBAgBnB,CAAC;AAGF,QAAA,MAAM,eAAe,qBAwCpB,CAAC;AAGF,QAAA,MAAM,QAAQ,GAAU,WAAW,MAAM,kBAmBxC,CAAC;AAGF,OAAO,EACL,cAAc,EACd,YAAY,EACZ,UAAU,EACV,cAAc,EACd,eAAe,EACf,QAAQ,EAER,oCAAoC,EACpC,6BAA6B,EAC7B,6BAA6B,EAC7B,4BAA4B,EAC7B,CAAC"}

package/dist/examples/index-declarative.js

@@ -0,0 +1,206 @@
+/**
+ * Declarative Examples Index
+ *
+ * This file serves as the main entry point for all declarative examples,
+ * providing a clean overview and easy access to different use cases.
+ */
+import { runDemo } from "./shared/plugin-builder";
+// Import all declarative examples
+import { demonstrateDeclarativeActionRegistry } from "./action-registry-declarative";
+import { demonstrateDeclarativeStorage } from "./storage-declarative";
+import { demonstrateDeclarativeLogging } from "./logger-declarative";
+import { demonstrateDeclarativeServer } from "./server-declarative";
+// Example catalog with descriptions
+const exampleCatalog = [
+    {
+        id: 'action-registry',
+        name: 'Action Registry',
+        description: 'Declarative plugin system with action registration and execution',
+        file: 'action-registry-declarative.ts',
+        demo: demonstrateDeclarativeActionRegistry,
+        features: [
+            'Declarative action definitions',
+            'Plugin-based architecture',
+            'Dynamic action registration',
+            'Error handling',
+            'Plugin discovery'
+        ]
+    },
+    {
+        id: 'storage',
+        name: 'Storage System',
+        description: 'Clean storage operations with declarative configuration',
+        file: 'storage-declarative.ts',
+        demo: demonstrateDeclarativeStorage,
+        features: [
+            'Declarative storage operations',
+            'CRUD operations',
+            'Configuration management',
+            'Data validation',
+            'Plugin isolation support'
+        ]
+    },
+    {
+        id: 'logging',
+        name: 'Logging System',
+        description: 'Flexible logging with multiple adapters and configurations',
+        file: 'logger-declarative.ts',
+        demo: demonstrateDeclarativeLogging,
+        features: [
+            'Multiple logger adapters',
+            'Hierarchical logging',
+            'Structured logging',
+            'Performance monitoring',
+            'Plugin-specific loggers'
+        ]
+    },
+    {
+        id: 'server',
+        name: 'HTTP Server',
+        description: 'Plugin-powered HTTP server with declarative routing',
+        file: 'server-declarative.ts',
+        demo: demonstrateDeclarativeServer,
+        features: [
+            'Declarative route definitions',
+            'Plugin-based handlers',
+            'Error handling',
+            'JSON API',
+            'Action execution'
+        ]
+    }
+];
+// Main menu system
+const showMainMenu = () => {
+    console.log("\n🎯 Declarative Plugin System Examples");
+    console.log("=====================================\n");
+    exampleCatalog.forEach((example, index) => {
+        console.log(`${index + 1}. ${example.name}`);
+        console.log(`   ${example.description}`);
+        console.log(`   File: ${example.file}`);
+        console.log(`   Features: ${example.features.join(', ')}`);
+        console.log();
+    });
+    console.log("0. Run all examples");
+    console.log("q. Quit");
+    console.log();
+};
+// Run specific example
+const runExample = async (index) => {
+    const example = exampleCatalog[index];
+    if (!example) {
+        console.log("❌ Invalid example number");
+        return;
+    }
+    // Wrap server demo to return void
+    const wrappedDemo = async () => {
+        if (example.id === 'server') {
+            await example.demo();
+            console.log("\n🌐 Server is running. Press Ctrl+C to stop.");
+        }
+        else {
+            await example.demo();
+        }
+    };
+    await runDemo(`${example.name} Example`, wrappedDemo);
+};
+// Run all examples (excluding server which blocks)
+const runAllExamples = async () => {
+    console.log("\n🚀 Running all declarative examples...\n");
+    for (const example of exampleCatalog) {
+        if (example.id === 'server') {
+            console.log(`⏭️  Skipping ${example.name} (server blocks execution)`);
+            continue;
+        }
+        // Wrap demo to ensure it returns void
+        const wrappedDemo = async () => {
+            await example.demo();
+        };
+        await runDemo(example.name, wrappedDemo);
+    }
+    console.log("\n✅ All examples completed!");
+};
+// Interactive menu
+const interactiveMenu = async () => {
+    const readline = await import('readline');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const askQuestion = (question) => {
+        return new Promise(resolve => {
+            rl.question(question, resolve);
+        });
+    };
+    while (true) {
+        showMainMenu();
+        const answer = await askQuestion("Select an example (number) or 'q' to quit: ");
+        if (answer.toLowerCase() === 'q') {
+            break;
+        }
+        if (answer === '0') {
+            await runAllExamples();
+            continue;
+        }
+        const index = parseInt(answer) - 1;
+        if (!isNaN(index)) {
+            await runExample(index);
+        }
+        else {
+            console.log("❌ Invalid input");
+        }
+        const continueAnswer = await askQuestion("\nPress Enter to continue or 'q' to quit: ");
+        if (continueAnswer.toLowerCase() === 'q') {
+            break;
+        }
+    }
+    rl.close();
+};
+// Quick run function
+const quickRun = async (exampleId) => {
+    const example = exampleCatalog.find(e => e.id === exampleId);
+    if (!example) {
+        console.log(`❌ Example '${exampleId}' not found`);
+        console.log("Available examples:", exampleCatalog.map(e => e.id).join(', '));
+        return;
+    }
+    // Wrap server demo to return void
+    const wrappedDemo = async () => {
+        if (example.id === 'server') {
+            await example.demo();
+            console.log("\n🌐 Server is running. Press Ctrl+C to stop.");
+        }
+        else {
+            await example.demo();
+        }
+    };
+    await runDemo(example.name, wrappedDemo);
+};
+// Export everything
+export { exampleCatalog, showMainMenu, runExample, runAllExamples, interactiveMenu, quickRun, 
+// Individual demos
+demonstrateDeclarativeActionRegistry, demonstrateDeclarativeStorage, demonstrateDeclarativeLogging, demonstrateDeclarativeServer };
+// Run if called directly
+if (import.meta.main) {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        // Interactive mode
+        interactiveMenu().catch(console.error);
+    }
+    else if (args[0] === '--all') {
+        // Run all examples
+        runAllExamples().catch(console.error);
+    }
+    else if (args[0] === '--example' && args[1]) {
+        // Run specific example
+        quickRun(args[1]).catch(console.error);
+    }
+    else {
+        console.log("\n🎯 Declarative Plugin System Examples");
+        console.log("Usage:");
+        console.log("  bun run examples/index-declarative.ts          # Interactive menu");
+        console.log("  bun run examples/index-declarative.ts --all    # Run all examples");
+        console.log("  bun run examples/index-declarative.ts --example <id>  # Run specific example");
+        console.log("\nAvailable examples:", exampleCatalog.map(e => e.id).join(', '));
+    }
+}
+//# sourceMappingURL=index-declarative.js.map