@majkapp/plugin-kit 3.2.0 → 3.3.0

package/docs/FULL.md

@@ -0,0 +1,848 @@
+# Complete Reference
+
+Comprehensive reference for @majkapp/plugin-kit covering all features and patterns.
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Plugin Definition](#plugin-definition)
+3. [Functions](#functions)
+4. [Screens](#screens)
+5. [Generated Hooks](#generated-hooks)
+6. [Context API](#context-api)
+7. [Services](#services)
+8. [Lifecycle](#lifecycle)
+9. [Testing](#testing)
+10. [Configuration](#configuration)
+11. [Best Practices](#best-practices)
+
+## Quick Start
+
+```typescript
+// src/index.ts
+import { definePlugin } from '@majkapp/plugin-kit';
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+  .function('health', {
+    description: 'Check plugin health',
+    input: { type: 'object', properties: {}, additionalProperties: false },
+    output: {
+      type: 'object',
+      properties: {
+        status: { type: 'string' },
+        timestamp: { type: 'string' }
+      }
+    },
+    handler: async (_, ctx) => ({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    })
+  })
+  .screenReact({
+    id: 'my-plugin-main',
+    name: 'My Plugin',
+    description: 'Main screen',
+    route: '/plugin-screens/my-plugin/main',
+    pluginPath: '/index.html'
+  })
+  .build();
+
+export = plugin;
+```
+
+## Plugin Definition
+
+### definePlugin()
+
+```typescript
+definePlugin(id: string, name: string, version: string)
+```
+
+- **id**: Unique identifier (lowercase, hyphens)
+- **name**: Display name
+- **version**: Semantic version
+
+### .pluginRoot()
+
+**REQUIRED.** Enables resource loading.
+
+```typescript
+.pluginRoot(__dirname)
+```
+
+### .build()
+
+**REQUIRED.** Finalizes plugin definition.
+
+```typescript
+.build()
+```
+
+Always at the end.
+
+## Functions
+
+Define callable operations with typed inputs/outputs.
+
+### Basic Function
+
+```typescript
+.function('functionName', {
+  description: string,          // REQUIRED: 2-3 sentences
+  input: JsonSchema,            // REQUIRED: Input schema
+  output: JsonSchema,           // REQUIRED: Output schema
+  handler: HandlerFn,           // REQUIRED: Implementation
+  tags?: string[],              // Optional: Organization tags
+  deprecated?: boolean          // Optional: Mark deprecated
+})
+```
+
+### Input/Output Schemas
+
+JSON Schema for validation:
+
+```typescript
+// Simple types
+{ type: 'string' }
+{ type: 'number' }
+{ type: 'boolean' }
+
+// Enums
+{ type: 'string', enum: ['value1', 'value2'] }
+
+// Objects
+{
+  type: 'object',
+  properties: {
+    name: { type: 'string' },
+    age: { type: 'number' }
+  },
+  required: ['name'],
+  additionalProperties: false
+}
+
+// Arrays
+{
+  type: 'array',
+  items: { type: 'string' }
+}
+```
+
+### Handler Function
+
+```typescript
+handler: async (input, ctx) => {
+  // ctx.logger - Logging
+  // ctx.storage - Key-value store
+  // ctx.majk - MAJK APIs
+
+  return output; // Must match output schema
+}
+```
+
+### Example: Analytics Function
+
+```typescript
+.function('getAnalytics', {
+  description: 'Get analytics for specified time period',
+  input: {
+    type: 'object',
+    properties: {
+      period: { type: 'string', enum: ['24h', '7d', '30d'] }
+    },
+    required: ['period']
+  },
+  output: {
+    type: 'object',
+    properties: {
+      period: { type: 'string' },
+      metrics: {
+        type: 'object',
+        properties: {
+          activeUsers: { type: 'number' },
+          totalSessions: { type: 'number' }
+        }
+      }
+    }
+  },
+  handler: async (input, ctx) => {
+    const sessions = await ctx.storage.get('sessions') || [];
+    // Calculate metrics...
+    return { period: input.period, metrics: { /* ... */ } };
+  }
+})
+```
+
+## Screens
+
+Define UI screens loaded in MAJK.
+
+### React Screen
+
+```typescript
+.screenReact({
+  id: string,                           // Unique ID
+  name: string,                         // Display name
+  description: string,                  // 2-3 sentences
+  route: `/plugin-screens/${id}/path`, // Must start with prefix
+  pluginPath: string,                   // Path to built app
+  pluginPathHash?: string               // Optional hash route
+})
+```
+
+### Example: Multiple Screens
+
+```typescript
+.screenReact({
+  id: 'my-plugin-dashboard',
+  name: 'Dashboard',
+  description: 'Main dashboard',
+  route: '/plugin-screens/my-plugin/dashboard',
+  pluginPath: '/index.html',
+  pluginPathHash: '#/'
+})
+
+.screenReact({
+  id: 'my-plugin-settings',
+  name: 'Settings',
+  description: 'Plugin settings',
+  route: '/plugin-screens/my-plugin/settings',
+  pluginPath: '/index.html',
+  pluginPathHash: '#/settings'
+})
+```
+
+### React App Setup
+
+```typescript
+// ui/src/App.tsx
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+export function App() {
+  return (
+    <BrowserRouter basename={window.__MAJK_IFRAME_BASE__}>
+      <Routes>
+        <Route path="/" element={<DashboardPage />} />
+        <Route path="/settings" element={<SettingsPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+```
+
+## Generated Hooks
+
+Auto-generated React hooks from functions.
+
+### Query Hooks
+
+Auto-fetch on mount:
+
+```typescript
+const { data, error, loading, refetch } = useHealth(
+  input?,
+  options?: {
+    enabled?: boolean,
+    refetchInterval?: number
+  }
+);
+```
+
+### Mutation Hooks
+
+Call manually:
+
+```typescript
+const { mutate, data, error, loading } = useClearEvents();
+
+await mutate(input);
+```
+
+### Example: Using Hooks
+
+```typescript
+import { useHealth, useGetAnalytics, useClearEvents } from './generated/hooks';
+
+export function DashboardPage() {
+  // Query - auto-fetches
+  const { data: health } = useHealth();
+  const { data: analytics } = useGetAnalytics({ period: '7d' });
+
+  // Mutation - call manually
+  const { mutate: clearEvents } = useClearEvents();
+
+  return (
+    <div>
+      <div data-majk-id="healthStatus">{health?.status}</div>
+      <button onClick={() => clearEvents({})}>Clear</button>
+    </div>
+  );
+}
+```
+
+## Context API
+
+Handler context provides access to MAJK.
+
+### ctx.logger
+
+```typescript
+ctx.logger.debug(message, data);
+ctx.logger.info(message, data);
+ctx.logger.warn(message, data);
+ctx.logger.error(message, data);
+```
+
+### ctx.storage
+
+Plugin-scoped key-value store:
+
+```typescript
+await ctx.storage.get(key);
+await ctx.storage.set(key, value);
+await ctx.storage.has(key);
+await ctx.storage.delete(key);
+await ctx.storage.clear();
+```
+
+### ctx.majk APIs
+
+```typescript
+// Conversations
+await ctx.majk.conversations.list();
+await ctx.majk.conversations.get(id);
+
+// Todos
+await ctx.majk.todos.list();
+await ctx.majk.todos.get(id);
+
+// Projects
+await ctx.majk.projects.list();
+await ctx.majk.projects.get(id);
+
+// Teammates
+await ctx.majk.teammates.list();
+await ctx.majk.teammates.get(id);
+
+// MCP Servers
+await ctx.majk.mcpServers.list();
+await ctx.majk.mcpServers.get(id);
+
+// Event Bus (use in .onReady())
+const subscription = await ctx.majk.eventBus.subscribeAll(handler);
+```
+
+## Services
+
+Group related functions together.
+
+### Service Definition
+
+```typescript
+.service(serviceName, {
+  type: string,
+  metadata: {
+    name: string,
+    description: string,
+    version: string
+  },
+  discoverable?: boolean
+})
+  .withFunction(functionName, {
+    examples?: string[],
+    tags?: string[]
+  })
+.endService()
+```
+
+### Example
+
+```typescript
+.function('health', { /* ... */, tags: ['monitoring'] })
+.function('getStats', { /* ... */, tags: ['monitoring'] })
+
+.service('plugin:my-plugin:monitoring', {
+  type: '@my-plugin/monitoring',
+  metadata: {
+    name: 'Monitoring Service',
+    description: 'Health checks and statistics',
+    version: '1.0.0'
+  }
+})
+  .withFunction('health', {
+    examples: ['Check plugin health']
+  })
+  .withFunction('getStats', {
+    examples: ['Get statistics']
+  })
+.endService()
+```
+
+## Lifecycle
+
+Initialize and clean up resources.
+
+### .onReady()
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  // Initialization
+  const subscription = await ctx.majk.eventBus.subscribeAll(handler);
+
+  // Register cleanup
+  cleanup(() => {
+    subscription.unsubscribe();
+  });
+})
+```
+
+### Example: Event Subscription
+
+```typescript
+const eventLog = [];
+
+.function('getEvents', {
+  /* ... */
+  handler: async () => ({ events: eventLog })
+})
+
+.onReady(async (ctx, cleanup) => {
+  const subscription = await ctx.majk.eventBus.subscribeAll((event) => {
+    eventLog.unshift({
+      id: `${Date.now()}`,
+      type: event.type,
+      entityType: event.entityType,
+      timestamp: new Date().toISOString()
+    });
+
+    if (eventLog.length > 1000) {
+      eventLog.length = 1000;
+    }
+  });
+
+  cleanup(() => {
+    subscription.unsubscribe();
+  });
+})
+```
+
+## Testing
+
+Test functions and UI with @majkapp/plugin-test.
+
+### Function Tests
+
+```typescript
+import { test, invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('function test', async () => {
+  const context = mock()
+    .storage({ key: 'value' })
+    .withMajkData({
+      conversations: [{ id: 'c1', title: 'Test' }]
+    })
+    .build();
+
+  const result = await invoke('functionName', { input }, { context });
+
+  assert.strictEqual(result.expected, 'value');
+});
+```
+
+### UI Tests
+
+```typescript
+import { test, bot, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('ui test', async () => {
+  const context = mock()
+    .withMockHandler('health', async () => ({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    }))
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/main');
+
+  await b.waitForSelector('[data-majk-id="healthStatus"][data-majk-state="populated"]');
+
+  const text = await b.getText('[data-majk-id="healthStatus"]');
+  assert.ok(text.includes('ok'));
+
+  await b.close();
+});
+```
+
+### data-majk-* Attributes
+
+```typescript
+// Identify elements
+<button data-majk-id="saveButton">Save</button>
+
+// Track state
+<div data-majk-id="container" data-majk-state="populated">
+  {/* content */}
+</div>
+```
+
+## Configuration
+
+### vite.config.js (EXACT FORMAT)
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  root: 'ui',
+  base: '',  // IMPORTANT: Empty string
+  server: {
+    port: 3000,
+    strictPort: false,
+  },
+  build: {
+    outDir: '../dist',
+    assetsDir: 'assets',
+    emptyOutDir: true,
+  },
+});
+```
+
+### Project Structure
+
+```
+my-plugin/
+├── src/
+│   ├── index.ts
+│   └── core/
+├── ui/
+│   ├── src/
+│   │   ├── App.tsx
+│   │   ├── components/
+│   │   └── generated/
+│   └── vite.config.js
+├── tests/
+│   └── plugin/
+│       ├── functions/unit/
+│       └── ui/unit/
+├── dist/
+├── package.json
+└── tsconfig.json
+```
+
+## Best Practices
+
+### 1. Decouple Business Logic
+
+```typescript
+// src/core/analytics.ts - Pure logic
+export function calculateAnalytics(sessions, period) {
+  // Pure computation, no plugin dependencies
+}
+
+// src/index.ts - Plugin wrapper
+.function('getAnalytics', {
+  /* ... */
+  handler: async (input, ctx) => {
+    const sessions = await ctx.storage.get('sessions') || [];
+    return calculateAnalytics(sessions, input.period);
+  }
+})
+```
+
+### 2. Always Use data-majk-* Attributes
+
+```typescript
+<button
+  data-majk-id="saveButton"
+  data-majk-state={saving ? 'saving' : 'idle'}
+  onClick={handleSave}
+>
+  Save
+</button>
+```
+
+### 3. Create uiLog Function
+
+```typescript
+.function('uiLog', {
+  description: 'Log from UI',
+  input: {
+    type: 'object',
+    properties: {
+      level: { type: 'string', enum: ['debug', 'info', 'warn', 'error'] },
+      component: { type: 'string' },
+      message: { type: 'string' },
+      data: { type: 'object' }
+    },
+    required: ['level', 'component', 'message']
+  },
+  output: {
+    type: 'object',
+    properties: { success: { type: 'boolean' } }
+  },
+  handler: async (input, ctx) => {
+    ctx.logger[input.level](`[UI:${input.component}] ${input.message}`, input.data);
+    return { success: true };
+  }
+})
+```
+
+### 4. Register Cleanup in onReady
+
+```typescript
+.onReady(async (ctx, cleanup) => {
+  const subscription = await ctx.majk.eventBus.subscribeAll(handler);
+
+  // ALWAYS register cleanup
+  cleanup(() => {
+    subscription.unsubscribe();
+  });
+})
+```
+
+### 5. Service Interfaces for External Dependencies
+
+```typescript
+// src/core/storage-service.ts
+export interface StorageService {
+  save(key: string, data: any): Promise<void>;
+  load(key: string): Promise<any>;
+}
+
+// src/core/aws-storage.ts - Real implementation
+export class AWSStorageService implements StorageService {
+  // AWS SDK implementation
+}
+
+// src/core/mock-storage.ts - Mock for testing
+export class MockStorageService implements StorageService {
+  // In-memory implementation for tests
+}
+```
+
+## Complete Example
+
+```typescript
+// src/index.ts
+import { definePlugin } from '@majkapp/plugin-kit';
+
+const eventLog: any[] = [];
+const maxEvents = 500;
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+
+  // Health function
+  .function('health', {
+    description: 'Check plugin health',
+    input: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    output: {
+      type: 'object',
+      properties: {
+        status: { type: 'string' },
+        timestamp: { type: 'string' }
+      }
+    },
+    handler: async (_, ctx) => ({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    }),
+    tags: ['monitoring']
+  })
+
+  // Analytics function
+  .function('getAnalytics', {
+    description: 'Get analytics',
+    input: {
+      type: 'object',
+      properties: {
+        period: { type: 'string', enum: ['24h', '7d', '30d'] }
+      },
+      required: ['period']
+    },
+    output: {
+      type: 'object',
+      properties: {
+        period: { type: 'string' },
+        metrics: {
+          type: 'object',
+          properties: {
+            activeUsers: { type: 'number' },
+            totalSessions: { type: 'number' }
+          }
+        }
+      }
+    },
+    handler: async (input, ctx) => {
+      const sessions = await ctx.storage.get('sessions') || [];
+      // Calculate...
+      return { period: input.period, metrics: { /* ... */ } };
+    },
+    tags: ['analytics']
+  })
+
+  // Events functions
+  .function('getEvents', {
+    description: 'Get logged events',
+    input: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    output: {
+      type: 'object',
+      properties: {
+        events: { type: 'array' },
+        count: { type: 'number' }
+      }
+    },
+    handler: async () => ({
+      events: eventLog,
+      count: eventLog.length
+    }),
+    tags: ['events']
+  })
+
+  .function('clearEvents', {
+    description: 'Clear event log',
+    input: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    output: {
+      type: 'object',
+      properties: {
+        success: { type: 'boolean' },
+        clearedCount: { type: 'number' }
+      }
+    },
+    handler: async (_, ctx) => {
+      const count = eventLog.length;
+      eventLog.length = 0;
+      ctx.logger.info(`Cleared ${count} events`);
+      return { success: true, clearedCount: count };
+    },
+    tags: ['events']
+  })
+
+  // UI logging
+  .function('uiLog', {
+    description: 'Log from UI',
+    input: {
+      type: 'object',
+      properties: {
+        level: { type: 'string', enum: ['debug', 'info', 'warn', 'error'] },
+        component: { type: 'string' },
+        message: { type: 'string' },
+        data: { type: 'object' }
+      },
+      required: ['level', 'component', 'message']
+    },
+    output: {
+      type: 'object',
+      properties: { success: { type: 'boolean' } }
+    },
+    handler: async (input, ctx) => {
+      ctx.logger[input.level](`[UI:${input.component}] ${input.message}`, input.data);
+      return { success: true };
+    },
+    tags: ['debugging']
+  })
+
+  // Screens
+  .screenReact({
+    id: 'my-plugin-dashboard',
+    name: 'Dashboard',
+    description: 'Main dashboard',
+    route: '/plugin-screens/my-plugin/dashboard',
+    pluginPath: '/index.html',
+    pluginPathHash: '#/'
+  })
+
+  .screenReact({
+    id: 'my-plugin-events',
+    name: 'Events',
+    description: 'Event monitor',
+    route: '/plugin-screens/my-plugin/events',
+    pluginPath: '/index.html',
+    pluginPathHash: '#/events'
+  })
+
+  // Services
+  .service('plugin:my-plugin:monitoring', {
+    type: '@my-plugin/monitoring',
+    metadata: {
+      name: 'Monitoring Service',
+      description: 'Health checks and analytics',
+      version: '1.0.0'
+    }
+  })
+    .withFunction('health')
+    .withFunction('getAnalytics')
+  .endService()
+
+  .service('plugin:my-plugin:events', {
+    type: '@my-plugin/events',
+    metadata: {
+      name: 'Event Management',
+      description: 'Event logging and monitoring',
+      version: '1.0.0'
+    }
+  })
+    .withFunction('getEvents')
+    .withFunction('clearEvents')
+  .endService()
+
+  // Lifecycle
+  .onReady(async (ctx, cleanup) => {
+    ctx.logger.info('My Plugin initializing');
+
+    // Subscribe to events
+    const subscription = await ctx.majk.eventBus.subscribeAll((event) => {
+      eventLog.unshift({
+        id: `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+        timestamp: new Date().toISOString(),
+        entityType: event.entityType,
+        eventType: event.type
+      });
+
+      if (eventLog.length > maxEvents) {
+        eventLog.length = maxEvents;
+      }
+    });
+
+    cleanup(() => {
+      subscription.unsubscribe();
+      ctx.logger.info('Event subscription cleaned up');
+    });
+
+    ctx.logger.info('My Plugin ready');
+  })
+
+  .build();
+
+export = plugin;
+```
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit` - Quick start
+Run `npx @majkapp/plugin-kit --functions` - Function patterns
+Run `npx @majkapp/plugin-kit --screens` - Screen configuration
+Run `npx @majkapp/plugin-kit --hooks` - Generated hooks
+Run `npx @majkapp/plugin-kit --context` - Context API
+Run `npx @majkapp/plugin-kit --services` - Service grouping
+Run `npx @majkapp/plugin-kit --lifecycle` - Lifecycle hooks
+Run `npx @majkapp/plugin-kit --testing` - Testing guide
+Run `npx @majkapp/plugin-kit --config` - Project configuration