@majkapp/plugin-kit 3.2.0 → 3.3.0

package/docs/LIFECYCLE.md

@@ -0,0 +1,490 @@
+# Lifecycle
+
+Plugins have a lifecycle with setup and teardown phases. Use `.onReady()` for initialization.
+
+## onReady
+
+Called once when the plugin is loaded. Use for subscriptions, timers, and async setup.
+
+```typescript
+// src/index.ts
+import { definePlugin } from '@majkapp/plugin-kit';
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+
+  // Define functions first
+  .function('getEvents', { /* ... */ })
+  .function('clearEvents', { /* ... */ })
+
+  // Lifecycle hook - called when plugin loads
+  .onReady(async (ctx, cleanup) => {
+    ctx.logger.info('Plugin initializing...');
+
+    // Perform async setup
+    await initializePluginData(ctx);
+
+    // Register cleanup (called when plugin unloads/reloads)
+    cleanup(() => {
+      ctx.logger.info('Plugin cleaning up');
+      // Cleanup code here
+    });
+
+    ctx.logger.info('Plugin ready');
+  })
+
+  .build();
+```
+
+## Event Bus Subscription (Real Example)
+
+From `samples/full-featured/src/index.ts`:
+
+```typescript
+// In-memory event log (scoped to plugin instance)
+const eventLog: any[] = [];
+const maxEvents = 1000;
+
+const plugin = definePlugin('full-featured', 'Full Featured', '1.0.0')
+  .pluginRoot(__dirname)
+
+  // Functions that access eventLog
+  .function('getEvents', {
+    description: 'Get all logged events from the event bus',
+    input: { /* ... */ },
+    output: { /* ... */ },
+    handler: async (input, ctx) => {
+      return {
+        events: eventLog,
+        count: eventLog.length
+      };
+    }
+  })
+
+  .function('clearEvents', {
+    description: 'Clear the event log',
+    input: { /* ... */ },
+    output: { /* ... */ },
+    handler: async (input, ctx) => {
+      const count = eventLog.length;
+      eventLog.length = 0;  // Clear array
+      ctx.logger.info(`Cleared ${count} events`);
+      return {
+        success: true,
+        clearedCount: count
+      };
+    }
+  })
+
+  // Subscribe to events when plugin loads
+  .onReady(async (ctx, cleanup) => {
+    ctx.logger.info('Full Featured plugin ready - subscribing to all events');
+
+    // Subscribe to ALL events from MAJK event bus
+    // CRITICAL: Must await the subscription (returns Promise<Subscription>)
+    const subscription = await ctx.majk.eventBus.subscribeAll((event: any) => {
+      // Build a log entry for each event
+      const logEntry = {
+        id: `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+        timestamp: new Date().toISOString(),
+        entityType: event.entityType,  // 'conversation', 'todo', 'project', etc.
+        eventType: event.type,         // 'created', 'updated', 'deleted'
+        entityId: event.entity?.id || 'unknown',
+        entitySummary: event.entity ? {
+          ...( event.entity.name && { name: event.entity.name }),
+          ...( event.entity.title && { title: event.entity.title }),
+          ...( event.entity.status && { status: event.entity.status })
+        } : {},
+        metadata: event.metadata || {},
+        fullEntity: event.entity
+      };
+
+      // Add to front of array (newest first), enforce max size
+      eventLog.unshift(logEntry);
+      if (eventLog.length > maxEvents) {
+        eventLog.length = maxEvents;  // Truncate old events
+      }
+
+      ctx.logger.info(`Event logged: ${event.entityType}.${event.type} - Total: ${eventLog.length}`);
+    });
+
+    // ALWAYS register cleanup for subscriptions, timers, etc.
+    // This runs when plugin is disabled or reloaded
+    cleanup(() => {
+      if (subscription && typeof subscription.unsubscribe === 'function') {
+        subscription.unsubscribe();
+        ctx.logger.info('Unsubscribed from EventBus');
+      }
+    });
+  })
+
+  .build();
+```
+
+## Timer Example
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  ctx.logger.info('Starting periodic task');
+
+  // Start interval timer
+  const intervalId = setInterval(async () => {
+    try {
+      // Perform periodic task
+      const stats = await calculateStats(ctx);
+      await ctx.storage.set('last-stats', stats);
+      ctx.logger.info('Stats updated', stats);
+    } catch (error) {
+      ctx.logger.error('Periodic task failed', { error: error.message });
+    }
+  }, 60000);  // Every 60 seconds
+
+  // Clean up timer on unload
+  cleanup(() => {
+    clearInterval(intervalId);
+    ctx.logger.info('Stopped periodic task');
+  });
+})
+```
+
+## Initialize Storage
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  ctx.logger.info('Initializing plugin storage');
+
+  // Check if first run
+  const initialized = await ctx.storage.get('initialized');
+
+  if (!initialized) {
+    // First-time setup
+    await ctx.storage.set('initialized', true);
+    await ctx.storage.set('sessions', []);
+    await ctx.storage.set('settings', {
+      theme: 'light',
+      notifications: true
+    });
+
+    ctx.logger.info('Plugin storage initialized');
+  } else {
+    ctx.logger.info('Plugin storage already initialized');
+  }
+
+  // No cleanup needed for storage initialization
+})
+```
+
+## Multiple Cleanups
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  // Setup 1: Event subscription
+  const subscription = await ctx.majk.eventBus.subscribeAll((event) => {
+    // Handle event
+  });
+
+  cleanup(() => {
+    subscription.unsubscribe();
+    ctx.logger.info('Unsubscribed from events');
+  });
+
+  // Setup 2: Timer
+  const timerId = setInterval(() => {
+    // Periodic task
+  }, 30000);
+
+  cleanup(() => {
+    clearInterval(timerId);
+    ctx.logger.info('Stopped timer');
+  });
+
+  // Setup 3: External connection
+  const connection = await connectToExternalService();
+
+  cleanup(async () => {
+    await connection.disconnect();
+    ctx.logger.info('Disconnected from external service');
+  });
+
+  ctx.logger.info('Plugin fully initialized');
+})
+```
+
+## Error Handling in onReady
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  try {
+    ctx.logger.info('Plugin initializing...');
+
+    // Attempt initialization
+    const subscription = await ctx.majk.eventBus.subscribeAll((event) => {
+      // Handle event
+    });
+
+    cleanup(() => {
+      subscription.unsubscribe();
+    });
+
+    ctx.logger.info('Plugin initialized successfully');
+
+  } catch (error) {
+    ctx.logger.error('Plugin initialization failed', {
+      error: error.message,
+      stack: error.stack
+    });
+
+    // Plugin will still load, but initialization failed
+    // Consider storing error state for functions to check
+    await ctx.storage.set('init-error', error.message);
+  }
+})
+```
+
+## When to Use onReady
+
+**Use onReady for:**
+- Event bus subscriptions
+- Timers and intervals
+- External service connections
+- Background workers
+- Initial data loading
+- Storage initialization
+
+**Don't use onReady for:**
+- Simple function definitions (no setup needed)
+- Synchronous operations (use functions instead)
+- Operations that should run per-request (use function handlers)
+
+## Cleanup Patterns
+
+### Pattern 1: Subscription Cleanup
+
+```typescript
+cleanup(() => {
+  if (subscription && typeof subscription.unsubscribe === 'function') {
+    subscription.unsubscribe();
+    ctx.logger.info('Unsubscribed');
+  }
+});
+```
+
+### Pattern 2: Timer Cleanup
+
+```typescript
+cleanup(() => {
+  clearInterval(intervalId);
+  clearTimeout(timeoutId);
+  ctx.logger.info('Timers cleared');
+});
+```
+
+### Pattern 3: Async Cleanup
+
+```typescript
+cleanup(async () => {
+  await connection.close();
+  await saveState(ctx);
+  ctx.logger.info('Async cleanup complete');
+});
+```
+
+### Pattern 4: Resource Cleanup
+
+```typescript
+cleanup(() => {
+  try {
+    resource.release();
+    ctx.logger.info('Resource released');
+  } catch (error) {
+    ctx.logger.error('Cleanup failed', { error: error.message });
+  }
+});
+```
+
+## Testing with onReady
+
+onReady is tested through integration tests:
+
+```typescript
+// tests/plugin/integration/lifecycle.test.js
+import { test } from '@majkapp/plugin-test';
+import { loadPlugin, unloadPlugin } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('plugin initializes event subscription', async () => {
+  const plugin = await loadPlugin();
+
+  // Trigger an event
+  await triggerTestEvent({ type: 'test', data: {} });
+
+  // Wait briefly for event to be processed
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  // Verify event was logged
+  const result = await invoke('getEvents', {}, { context: plugin.context });
+  assert.ok(result.events.length > 0);
+
+  // Cleanup
+  await unloadPlugin(plugin);
+});
+```
+
+## Best Practices
+
+### 1. Always Register Cleanup
+
+```typescript
+// Good: Cleanup registered
+.onReady(async (ctx, cleanup) => {
+  const subscription = await ctx.majk.eventBus.subscribeAll(handler);
+
+  cleanup(() => {
+    subscription.unsubscribe();
+  });
+})
+
+// Bad: No cleanup - memory leak!
+.onReady(async (ctx, cleanup) => {
+  const subscription = await ctx.majk.eventBus.subscribeAll(handler);
+  // Missing cleanup!
+})
+```
+
+### 2. Log Initialization Steps
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  ctx.logger.info('Plugin initializing...');
+
+  const subscription = await ctx.majk.eventBus.subscribeAll(handler);
+  ctx.logger.info('Event subscription created');
+
+  cleanup(() => {
+    subscription.unsubscribe();
+    ctx.logger.info('Event subscription cleaned up');
+  });
+
+  ctx.logger.info('Plugin initialization complete');
+})
+```
+
+### 3. Handle Errors Gracefully
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  try {
+    const subscription = await ctx.majk.eventBus.subscribeAll(handler);
+
+    cleanup(() => {
+      try {
+        subscription.unsubscribe();
+      } catch (error) {
+        ctx.logger.error('Cleanup error', { error: error.message });
+      }
+    });
+  } catch (error) {
+    ctx.logger.error('Initialization error', { error: error.message });
+    // Store error state for functions to check
+    await ctx.storage.set('init-error', error.message);
+  }
+})
+```
+
+## Complete Example
+
+```typescript
+// src/index.ts
+import { definePlugin } from '@majkapp/plugin-kit';
+
+const eventLog: any[] = [];
+const maxEvents = 500;
+let statsTimer: NodeJS.Timeout;
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+
+  .function('getEvents', {
+    description: 'Get logged events',
+    input: { /* ... */ },
+    output: { /* ... */ },
+    handler: async () => ({ events: eventLog })
+  })
+
+  .function('getStats', {
+    description: 'Get cached statistics',
+    input: { /* ... */ },
+    output: { /* ... */ },
+    handler: async (input, ctx) => {
+      return await ctx.storage.get('cached-stats') || { count: 0 };
+    }
+  })
+
+  .onReady(async (ctx, cleanup) => {
+    ctx.logger.info('My Plugin initializing...');
+
+    // 1. Initialize storage
+    const initialized = await ctx.storage.get('initialized');
+    if (!initialized) {
+      await ctx.storage.set('initialized', true);
+      await ctx.storage.set('cached-stats', { count: 0, timestamp: Date.now() });
+      ctx.logger.info('Storage initialized');
+    }
+
+    // 2. Subscribe to events
+    try {
+      const subscription = await ctx.majk.eventBus.subscribeAll((event) => {
+        eventLog.unshift({
+          id: `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+          timestamp: new Date().toISOString(),
+          type: event.type,
+          entityType: event.entityType
+        });
+
+        if (eventLog.length > maxEvents) {
+          eventLog.length = maxEvents;
+        }
+      });
+
+      cleanup(() => {
+        subscription.unsubscribe();
+        ctx.logger.info('Event subscription cleaned up');
+      });
+
+      ctx.logger.info('Event subscription active');
+    } catch (error) {
+      ctx.logger.error('Event subscription failed', { error: error.message });
+    }
+
+    // 3. Start periodic stats update
+    statsTimer = setInterval(async () => {
+      try {
+        const stats = {
+          count: eventLog.length,
+          timestamp: Date.now()
+        };
+        await ctx.storage.set('cached-stats', stats);
+        ctx.logger.debug('Stats updated', stats);
+      } catch (error) {
+        ctx.logger.error('Stats update failed', { error: error.message });
+      }
+    }, 60000);  // Every 60 seconds
+
+    cleanup(() => {
+      clearInterval(statsTimer);
+      ctx.logger.info('Stats timer stopped');
+    });
+
+    ctx.logger.info('My Plugin ready');
+  })
+
+  .build();
+
+export = plugin;
+```
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --context` - ctx API for onReady
+Run `npx @majkapp/plugin-kit --testing` - Test plugin lifecycle
+Run `npx @majkapp/plugin-kit --services` - Organize functions into services