@majkapp/plugin-kit 3.2.1 → 3.3.1

package/docs/CONTEXT.md

@@ -0,0 +1,500 @@
+# Context API
+
+Every function handler receives a `ctx` parameter with access to MAJK APIs, storage, and logging.
+
+```typescript
+.function('myFunction', {
+  description: 'Example function',
+  input: { /* ... */ },
+  output: { /* ... */ },
+  handler: async (input, ctx) => {
+    // ctx.majk - Access MAJK data
+    // ctx.storage - Plugin-scoped key-value store
+    // ctx.logger - Scoped logging
+    return { /* ... */ };
+  }
+})
+```
+
+## ctx.logger
+
+Scoped logging automatically includes your plugin name.
+
+```typescript
+handler: async (input, ctx) => {
+  // Debug - verbose information for development
+  ctx.logger.debug('Processing request', { input });
+
+  // Info - normal operational messages
+  ctx.logger.info('Operation started', { userId: input.userId });
+
+  // Warn - warning conditions, non-critical issues
+  ctx.logger.warn('Rate limit approaching', { count: 95, limit: 100 });
+
+  // Error - error conditions, failures
+  ctx.logger.error('Operation failed', {
+    error: error.message,
+    stack: error.stack,
+    input
+  });
+
+  return { /* ... */ };
+}
+```
+
+**Best practice:** Always log errors with context:
+
+```typescript
+handler: async (input, ctx) => {
+  try {
+    const result = await performOperation(input);
+    ctx.logger.info('Operation succeeded', { result });
+    return result;
+  } catch (error) {
+    ctx.logger.error('Operation failed', {
+      error: error.message,
+      stack: error.stack,
+      input,  // Include input for debugging
+      timestamp: new Date().toISOString()
+    });
+    throw error;  // Re-throw or return error response
+  }
+}
+```
+
+## ctx.storage
+
+Plugin-scoped key-value storage. Data persists between function calls.
+
+```typescript
+// Set a value
+await ctx.storage.set('counter', 42);
+await ctx.storage.set('user-settings', { theme: 'dark', notifications: true });
+
+// Get a value (returns undefined if not found)
+const counter = await ctx.storage.get('counter');  // 42
+const settings = await ctx.storage.get('user-settings');  // { theme: 'dark', ... }
+
+// Check if key exists
+const exists = await ctx.storage.has('counter');  // true
+
+// Delete a key
+await ctx.storage.delete('counter');
+
+// Clear all storage (use with caution!)
+await ctx.storage.clear();
+```
+
+### Example: Counter
+
+```typescript
+.function('incrementCounter', {
+  description: 'Increment counter and return new value',
+  input: {
+    type: 'object',
+    properties: {},
+    additionalProperties: false
+  },
+  output: {
+    type: 'object',
+    properties: {
+      counter: { type: 'number' }
+    }
+  },
+  handler: async (input, ctx) => {
+    // Get current counter (default to 0)
+    const current = await ctx.storage.get('counter') || 0;
+
+    // Increment
+    const newValue = current + 1;
+
+    // Save
+    await ctx.storage.set('counter', newValue);
+
+    ctx.logger.info(`Counter incremented to ${newValue}`);
+
+    return { counter: newValue };
+  }
+})
+```
+
+### Example: Session Tracking
+
+```typescript
+.function('trackSession', {
+  description: 'Track user session',
+  input: {
+    type: 'object',
+    properties: {
+      userId: { type: 'string' },
+      duration: { type: 'number' }
+    },
+    required: ['userId', 'duration']
+  },
+  output: {
+    type: 'object',
+    properties: {
+      totalSessions: { type: 'number' }
+    }
+  },
+  handler: async (input, ctx) => {
+    // Get existing sessions
+    const sessions = await ctx.storage.get('sessions') || [];
+
+    // Add new session
+    sessions.push({
+      userId: input.userId,
+      duration: input.duration,
+      timestamp: Date.now()
+    });
+
+    // Save updated sessions
+    await ctx.storage.set('sessions', sessions);
+
+    ctx.logger.info(`Session tracked for user ${input.userId}`, {
+      duration: input.duration,
+      totalSessions: sessions.length
+    });
+
+    return { totalSessions: sessions.length };
+  }
+})
+```
+
+## ctx.majk.conversations
+
+Access MAJK conversations.
+
+```typescript
+handler: async (input, ctx) => {
+  // List all conversations
+  const conversations = await ctx.majk.conversations.list();
+  // Returns: Array<{ id, title, createdAt, updatedAt, ... }>
+
+  // Get specific conversation
+  const conversation = await ctx.majk.conversations.get('conv-id');
+  // Returns: { id, title, messages, ... } or null if not found
+
+  ctx.logger.info(`Found ${conversations.length} conversations`);
+
+  return { count: conversations.length };
+}
+```
+
+### Example: Conversation Summary
+
+```typescript
+.function('getConversationStats', {
+  description: 'Get statistics across all conversations',
+  input: {
+    type: 'object',
+    properties: {},
+    additionalProperties: false
+  },
+  output: {
+    type: 'object',
+    properties: {
+      totalConversations: { type: 'number' },
+      totalMessages: { type: 'number' },
+      mostActive: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          title: { type: 'string' },
+          messageCount: { type: 'number' }
+        }
+      }
+    }
+  },
+  handler: async (input, ctx) => {
+    const conversations = await ctx.majk.conversations.list();
+
+    let totalMessages = 0;
+    let mostActive = null;
+    let maxMessages = 0;
+
+    for (const conv of conversations) {
+      const messageCount = conv.messages?.length || 0;
+      totalMessages += messageCount;
+
+      if (messageCount > maxMessages) {
+        maxMessages = messageCount;
+        mostActive = {
+          id: conv.id,
+          title: conv.title || 'Untitled',
+          messageCount
+        };
+      }
+    }
+
+    ctx.logger.info('Conversation stats calculated', {
+      totalConversations: conversations.length,
+      totalMessages
+    });
+
+    return {
+      totalConversations: conversations.length,
+      totalMessages,
+      mostActive: mostActive || { id: '', title: '', messageCount: 0 }
+    };
+  }
+})
+```
+
+## ctx.majk.todos
+
+Access MAJK todos.
+
+```typescript
+handler: async (input, ctx) => {
+  // List all todos
+  const todos = await ctx.majk.todos.list();
+  // Returns: Array<{ id, title, status, ... }>
+
+  // Get specific todo
+  const todo = await ctx.majk.todos.get('todo-id');
+  // Returns: { id, title, status, ... } or null
+
+  // Filter by status
+  const pending = todos.filter(t => t.status === 'pending');
+  const completed = todos.filter(t => t.status === 'completed');
+
+  return { pending: pending.length, completed: completed.length };
+}
+```
+
+## ctx.majk.projects
+
+Access MAJK projects.
+
+```typescript
+handler: async (input, ctx) => {
+  // List all projects
+  const projects = await ctx.majk.projects.list();
+  // Returns: Array<{ id, name, ... }>
+
+  // Get specific project
+  const project = await ctx.majk.projects.get('project-id');
+  // Returns: { id, name, ... } or null
+
+  return { projectCount: projects.length };
+}
+```
+
+## ctx.majk.teammates
+
+Access MAJK teammates (AI assistants).
+
+```typescript
+handler: async (input, ctx) => {
+  // List all teammates
+  const teammates = await ctx.majk.teammates.list();
+  // Returns: Array<{ id, name, expertise, ... }>
+
+  // Get specific teammate
+  const teammate = await ctx.majk.teammates.get('teammate-id');
+  // Returns: { id, name, expertise, skills, ... } or null
+
+  ctx.logger.info(`Found ${teammates.length} teammates`);
+
+  return { teammates: teammates.map(t => ({ id: t.id, name: t.name })) };
+}
+```
+
+## ctx.majk.mcpServers
+
+Access MCP (Model Context Protocol) servers.
+
+```typescript
+handler: async (input, ctx) => {
+  // List all MCP servers
+  const servers = await ctx.majk.mcpServers.list();
+  // Returns: Array<{ id, name, config, ... }>
+
+  // Get specific server
+  const server = await ctx.majk.mcpServers.get('server-id');
+  // Returns: { id, name, config, ... } or null
+
+  return { serverCount: servers.length };
+}
+```
+
+## ctx.majk.eventBus
+
+Subscribe to MAJK events (conversations, todos, projects, etc.).
+
+**CRITICAL:** Use in `.onReady()` to register cleanup.
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  ctx.logger.info('Subscribing to event bus');
+
+  // Subscribe to ALL events
+  const subscription = await ctx.majk.eventBus.subscribeAll((event) => {
+    ctx.logger.info('Event received', {
+      entityType: event.entityType,   // 'conversation', 'todo', 'project', etc.
+      eventType: event.type,          // 'created', 'updated', 'deleted'
+      entityId: event.entity?.id
+    });
+
+    // Store event for later display
+    // ... (see LIFECYCLE.md for full example)
+  });
+
+  // ALWAYS register cleanup to unsubscribe
+  cleanup(() => {
+    if (subscription && typeof subscription.unsubscribe === 'function') {
+      subscription.unsubscribe();
+      ctx.logger.info('Unsubscribed from event bus');
+    }
+  });
+})
+```
+
+## Complete Example: Dashboard Data
+
+```typescript
+.function('getDashboardData', {
+  description: 'Get comprehensive dashboard data from MAJK APIs',
+
+  input: {
+    type: 'object',
+    properties: {},
+    additionalProperties: false
+  },
+
+  output: {
+    type: 'object',
+    properties: {
+      conversations: {
+        type: 'object',
+        properties: {
+          total: { type: 'number' },
+          recent: { type: 'array' }
+        }
+      },
+      todos: {
+        type: 'object',
+        properties: {
+          total: { type: 'number' },
+          pending: { type: 'number' },
+          completed: { type: 'number' }
+        }
+      },
+      projects: {
+        type: 'object',
+        properties: {
+          total: { type: 'number' }
+        }
+      },
+      timestamp: { type: 'string' }
+    }
+  },
+
+  handler: async (input, ctx) => {
+    ctx.logger.info('Fetching dashboard data');
+
+    try {
+      // Fetch all data in parallel for better performance
+      const [conversations, todos, projects] = await Promise.all([
+        ctx.majk.conversations.list(),
+        ctx.majk.todos.list(),
+        ctx.majk.projects.list()
+      ]);
+
+      // Process todos
+      const pendingTodos = todos.filter(t => t.status === 'pending');
+      const completedTodos = todos.filter(t => t.status === 'completed');
+
+      // Get recent conversations (last 5)
+      const recentConversations = conversations
+        .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
+        .slice(0, 5)
+        .map(c => ({
+          id: c.id,
+          title: c.title || 'Untitled',
+          updatedAt: c.updatedAt
+        }));
+
+      const result = {
+        conversations: {
+          total: conversations.length,
+          recent: recentConversations
+        },
+        todos: {
+          total: todos.length,
+          pending: pendingTodos.length,
+          completed: completedTodos.length
+        },
+        projects: {
+          total: projects.length
+        },
+        timestamp: new Date().toISOString()
+      };
+
+      ctx.logger.info('Dashboard data fetched successfully', {
+        conversationCount: conversations.length,
+        todoCount: todos.length,
+        projectCount: projects.length
+      });
+
+      return result;
+
+    } catch (error) {
+      ctx.logger.error('Failed to fetch dashboard data', {
+        error: error.message,
+        stack: error.stack
+      });
+      throw new Error(`Dashboard data fetch failed: ${error.message}`);
+    }
+  },
+
+  tags: ['dashboard', 'aggregation']
+})
+```
+
+## Context in Tests
+
+Mock context for testing:
+
+```typescript
+// tests/plugin/functions/unit/dashboard.test.js
+import { test, invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('getDashboardData aggregates MAJK data', async () => {
+  // Create mock context with storage and MAJK data
+  const context = mock()
+    .storage({
+      'user-settings': { theme: 'dark' }
+    })
+    .withMajkData({
+      conversations: [
+        { id: 'conv1', title: 'Test 1', updatedAt: '2024-01-01T00:00:00Z', messages: [] },
+        { id: 'conv2', title: 'Test 2', updatedAt: '2024-01-02T00:00:00Z', messages: [] }
+      ],
+      todos: [
+        { id: 'todo1', status: 'pending' },
+        { id: 'todo2', status: 'completed' }
+      ],
+      projects: [
+        { id: 'proj1', name: 'Project 1' }
+      ]
+    })
+    .build();
+
+  const result = await invoke('getDashboardData', {}, { context });
+
+  assert.strictEqual(result.conversations.total, 2);
+  assert.strictEqual(result.todos.total, 2);
+  assert.strictEqual(result.todos.pending, 1);
+  assert.strictEqual(result.todos.completed, 1);
+  assert.strictEqual(result.projects.total, 1);
+});
+```
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --lifecycle` - onReady and event subscriptions
+Run `npx @majkapp/plugin-kit --services` - Group functions into services
+Run `npx @majkapp/plugin-kit --testing` - Test functions with mock context