@majkapp/plugin-kit 3.2.0 → 3.3.0

package/docs/INDEX.md

@@ -0,0 +1,486 @@
+# @majkapp/plugin-kit
+
+Build MAJK plugins with functions, UI screens, and services. Test with `@majkapp/plugin-test`.
+
+## Quick Start
+
+```typescript
+// src/index.ts
+import { definePlugin } from '@majkapp/plugin-kit';
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)  // REQUIRED FIRST - enables resource loading
+
+  .function('health', {
+    description: 'Check plugin health status',
+    input: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    output: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', enum: ['ok', 'error'] },
+        timestamp: { type: 'string', format: 'date-time' }
+      },
+      required: ['status', 'timestamp']
+    },
+    handler: async (input, ctx) => {
+      // ctx.logger - scoped logging (debug, info, warn, error)
+      ctx.logger.info('Health check requested');
+
+      return {
+        status: 'ok',
+        timestamp: new Date().toISOString()
+      };
+    },
+    tags: ['monitoring']
+  })
+
+  .screenReact({
+    id: 'my-plugin-main',
+    name: 'My Plugin',
+    description: 'Main plugin screen',
+    route: '/plugin-screens/my-plugin/main',
+    pluginPath: '/index.html'  // Path to built React app
+  })
+
+  .build();
+
+export = plugin;
+```
+
+## Testing Your Function
+
+```typescript
+// tests/plugin/functions/unit/health.test.js
+import { test } from '@majkapp/plugin-test';
+import { invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('health check returns ok status', async () => {
+  // Create mock context - no real MAJK instance needed
+  const context = mock().build();
+
+  // Invoke function with mock context
+  const result = await invoke('health', {}, { context });
+
+  // Verify output matches schema
+  assert.strictEqual(result.status, 'ok');
+  assert.ok(result.timestamp);
+  assert.ok(new Date(result.timestamp).getTime() > 0);
+});
+```
+
+Run test:
+```bash
+cd my-plugin
+npx majk-test tests/plugin/functions/unit/health.test.js
+```
+
+Output:
+```
+✓ health check returns ok status (2ms)
+```
+
+## Project Structure
+
+```
+my-plugin/
+├── src/
+│   ├── index.ts              # Plugin definition
+│   └── core/                 # Business logic (no plugin deps)
+│       └── analytics.ts      # Pure functions, easy to test
+├── ui/
+│   ├── src/
+│   │   ├── App.tsx           # React app
+│   │   ├── components/       # UI components
+│   │   └── generated/        # Auto-generated hooks
+│   │       ├── hooks.ts      # useHealth(), etc.
+│   │       └── client.ts     # RPC client
+│   └── index.html
+├── tests/
+│   └── plugin/
+│       ├── functions/unit/   # Function tests
+│       └── ui/unit/          # UI tests with bot
+├── vite.config.js            # EXACT format required (see CONFIG.md)
+├── package.json
+└── tsconfig.json
+```
+
+## Best Practice: Decoupled Business Logic
+
+**ALWAYS separate business logic from plugin code.** This makes testing easier and allows logic reuse.
+
+```typescript
+// src/core/analytics.ts - Pure business logic, NO plugin dependencies
+export interface AnalyticsData {
+  period: '24h' | '7d' | '30d';
+  metrics: {
+    activeUsers: number;
+    totalSessions: number;
+    avgDuration: number;
+  };
+}
+
+export function calculateAnalytics(
+  sessions: Array<{ userId: string; duration: number; timestamp: Date }>,
+  period: '24h' | '7d' | '30d'
+): AnalyticsData {
+  const now = Date.now();
+  const periodMs = period === '24h' ? 86400000 : period === '7d' ? 604800000 : 2592000000;
+
+  const recentSessions = sessions.filter(s =>
+    now - s.timestamp.getTime() < periodMs
+  );
+
+  const uniqueUsers = new Set(recentSessions.map(s => s.userId)).size;
+  const totalDuration = recentSessions.reduce((sum, s) => sum + s.duration, 0);
+
+  return {
+    period,
+    metrics: {
+      activeUsers: uniqueUsers,
+      totalSessions: recentSessions.length,
+      avgDuration: recentSessions.length > 0
+        ? Math.round(totalDuration / recentSessions.length)
+        : 0
+    }
+  };
+}
+
+// Test this with pure Jest/Vitest - NO plugin-test needed
+```
+
+```typescript
+// src/index.ts - Plugin function wraps business logic
+import { calculateAnalytics } from './core/analytics';
+
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+
+  .function('getAnalytics', {
+    description: 'Get analytics for specified time period',
+    input: {
+      type: 'object',
+      properties: {
+        period: { type: 'string', enum: ['24h', '7d', '30d'] }
+      },
+      required: ['period'],
+      additionalProperties: false
+    },
+    output: {
+      type: 'object',
+      properties: {
+        period: { type: 'string' },
+        metrics: {
+          type: 'object',
+          properties: {
+            activeUsers: { type: 'number' },
+            totalSessions: { type: 'number' },
+            avgDuration: { type: 'number' }
+          },
+          required: ['activeUsers', 'totalSessions', 'avgDuration']
+        }
+      },
+      required: ['period', 'metrics']
+    },
+    handler: async (input, ctx) => {
+      // Get data from storage (plugin layer)
+      const sessions = await ctx.storage.get('sessions') || [];
+
+      // Pure business logic (easy to test)
+      const analytics = calculateAnalytics(sessions, input.period);
+
+      ctx.logger.info(`Analytics calculated for ${input.period}`, analytics);
+
+      return analytics;
+    },
+    tags: ['analytics']
+  });
+```
+
+## Best Practice: Service Interfaces for External Dependencies
+
+When using 3rd party services (AWS, databases, APIs), create interfaces for easy mocking.
+
+```typescript
+// src/core/storage-service.ts - Interface for abstraction
+export interface StorageService {
+  save(key: string, data: any): Promise<void>;
+  load(key: string): Promise<any>;
+  delete(key: string): Promise<void>;
+}
+
+// src/core/aws-storage.ts - Real implementation
+import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+
+export class AWSStorageService implements StorageService {
+  constructor(private s3: S3Client, private bucket: string) {}
+
+  async save(key: string, data: any): Promise<void> {
+    await this.s3.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      Body: JSON.stringify(data)
+    }));
+  }
+
+  async load(key: string): Promise<any> {
+    const result = await this.s3.send(new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: key
+    }));
+    const body = await result.Body?.transformToString();
+    return body ? JSON.parse(body) : null;
+  }
+
+  async delete(key: string): Promise<void> {
+    // Implementation...
+  }
+}
+
+// src/core/mock-storage.ts - Mock for testing
+export class MockStorageService implements StorageService {
+  private data = new Map<string, any>();
+
+  async save(key: string, data: any): Promise<void> {
+    this.data.set(key, data);
+  }
+
+  async load(key: string): Promise<any> {
+    return this.data.get(key);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.data.delete(key);
+  }
+}
+```
+
+## React UI with Generated Hooks
+
+The plugin-kit auto-generates React hooks from your functions.
+
+```typescript
+// ui/src/DashboardPage.tsx
+import { useHealth, useGetAnalytics, useUiLog } from './generated/hooks';
+import { PluginStatGrid, PluginActionPanel } from '@majkapp/plugin-ui';
+import { useEffect } from 'react';
+
+export function DashboardPage() {
+  // Auto-generated hooks - query hooks auto-fetch on mount
+  const { data: health, loading: healthLoading, refetch: refetchHealth } = useHealth();
+  const { data: analytics, loading: analyticsLoading } = useGetAnalytics(
+    { period: '7d' },
+    { refetchInterval: 30000 }  // Auto-refresh every 30s
+  );
+
+  // Mutation hook for logging - call .mutate() manually
+  const { mutate: uiLog } = useUiLog();
+
+  // Log UI lifecycle events for debugging
+  useEffect(() => {
+    uiLog({
+      level: 'info',
+      component: 'DashboardPage',
+      message: 'Dashboard mounted',
+      data: { timestamp: new Date().toISOString() }
+    });
+  }, [uiLog]);
+
+  // data-majk-id: Enables bot testing - identifies clickable elements
+  // data-majk-state: Tracks UI state for testing - empty/loading/populated
+  return (
+    <div data-majk-id="dashboardContainer">
+      <PluginActionPanel
+        actions={[
+          {
+            label: '🔄 Refresh Health',
+            onClick: () => {
+              uiLog({
+                level: 'info',
+                component: 'DashboardPage',
+                message: 'Health refresh triggered by user'
+              });
+              refetchHealth();
+            },
+            'data-majk-id': 'refreshHealthButton',
+            'data-majk-state': healthLoading ? 'loading' : 'idle'
+          }
+        ]}
+      />
+
+      <PluginStatGrid
+        stats={[
+          {
+            label: 'Health Status',
+            value: health?.status || 'unknown',
+            'data-majk-id': 'healthStatus',
+            'data-majk-state': healthLoading ? 'loading' : health ? 'populated' : 'empty'
+          },
+          {
+            label: 'Active Users (7d)',
+            value: analytics?.metrics.activeUsers || 0,
+            'data-majk-id': 'activeUsersCount',
+            'data-majk-state': analyticsLoading ? 'loading' : analytics ? 'populated' : 'empty'
+          },
+          {
+            label: 'Total Sessions',
+            value: analytics?.metrics.totalSessions || 0,
+            'data-majk-id': 'totalSessionsCount'
+          }
+        ]}
+      />
+    </div>
+  );
+}
+```
+
+## Testing Your UI
+
+```typescript
+// tests/plugin/ui/unit/dashboard.test.js
+import { test } from '@majkapp/plugin-test';
+import { bot, invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('dashboard displays health status', async () => {
+  // Create mock context with handlers for functions
+  const context = mock()
+    .withMockHandler('health', async () => ({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    }))
+    .withMockHandler('getAnalytics', async () => ({
+      period: '7d',
+      metrics: {
+        activeUsers: 42,
+        totalSessions: 150,
+        avgDuration: 320
+      }
+    }))
+    .build();
+
+  // Start browser bot
+  const b = await bot(context);
+
+  // Navigate to screen
+  await b.goto('/plugin-screens/my-plugin/main');
+
+  // Wait for data to load - check data-majk-state
+  await b.waitForSelector('[data-majk-id="healthStatus"][data-majk-state="populated"]');
+
+  // Verify displayed values
+  const healthText = await b.getText('[data-majk-id="healthStatus"]');
+  assert.ok(healthText.includes('ok'));
+
+  const usersText = await b.getText('[data-majk-id="activeUsersCount"]');
+  assert.ok(usersText.includes('42'));
+
+  // Test interaction - click refresh button
+  await b.click('[data-majk-id="refreshHealthButton"]');
+
+  // Verify loading state
+  const buttonState = await b.getAttribute('[data-majk-id="refreshHealthButton"]', 'data-majk-state');
+  assert.strictEqual(buttonState, 'loading');
+
+  await b.close();
+});
+```
+
+## Key Concepts
+
+### Query vs Mutation Hooks
+
+Generated hooks follow React Query patterns:
+
+**Query Hooks** - Auto-fetch data on mount:
+- `useHealth()` - fetches immediately
+- `useGetAnalytics({ period: '7d' })` - fetches immediately with params
+- Returns: `{ data, error, loading, refetch }`
+
+**Mutation Hooks** - Call manually:
+- `useUiLog()` - call `.mutate(input)` when needed
+- `useClearEvents()` - call `.mutate({})` on button click
+- Returns: `{ mutate, data, error, loading }`
+
+### data-majk-* Attributes
+
+**Critical for testing.** The bot uses these to find and verify elements.
+
+- `data-majk-id="uniqueId"` - Identifies clickable elements, key stats
+- `data-majk-state="loading|empty|populated|error"` - Tracks UI state for assertions
+
+### uiLog Function
+
+**Best practice:** Create a `uiLog` function in your plugin for frontend debugging.
+
+```typescript
+.function('uiLog', {
+  description: 'Log messages from UI for debugging',
+  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'],
+    additionalProperties: false
+  },
+  output: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean' }
+    }
+  },
+  handler: async (input, ctx) => {
+    const prefix = `[UI:${input.component}]`;
+    ctx.logger[input.level](`${prefix} ${input.message}`, input.data);
+    return { success: true };
+  },
+  tags: ['debugging']
+})
+```
+
+Then use in React:
+
+```typescript
+// Log errors
+try {
+  await someAsyncOperation();
+} catch (error) {
+  uiLog({
+    level: 'error',
+    component: 'DashboardPage',
+    message: 'Failed to load data',
+    data: { error: error.message }
+  });
+}
+
+// Log user actions
+onClick={() => {
+  uiLog({
+    level: 'info',
+    component: 'SettingsPage',
+    message: 'User clicked save button',
+    data: { settingsChanged: ['theme', 'notifications'] }
+  });
+  handleSave();
+}}
+```
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --functions` - Deep dive into function patterns
+Run `npx @majkapp/plugin-kit --screens` - Screen configuration details
+Run `npx @majkapp/plugin-kit --hooks` - Generated hooks reference
+Run `npx @majkapp/plugin-kit --context` - ctx.majk and ctx.logger APIs
+Run `npx @majkapp/plugin-kit --services` - Service grouping patterns
+Run `npx @majkapp/plugin-kit --lifecycle` - onReady and cleanup
+Run `npx @majkapp/plugin-kit --testing` - Complete testing guide
+Run `npx @majkapp/plugin-kit --config` - vite.config.js and project setup
+Run `npx @majkapp/plugin-kit --full` - Complete reference