@majkapp/plugin-kit 3.2.1 → 3.3.1

package/docs/INDEX.md

@@ -0,0 +1,605 @@
+# @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 below)
+├── package.json              # REQUIRED: majk metadata section
+└── tsconfig.json
+```
+
+## package.json (REQUIRED)
+
+**CRITICAL:** Your package.json MUST include the `majk` metadata section and use an npm organization scope:
+
+```json
+{
+  "name": "@yourorg/my-plugin",
+  "version": "1.0.0",
+  "description": "My awesome MAJK plugin",
+  "main": "index.js",
+  "keywords": ["majk", "plugin"],
+  "majk": {
+    "type": "in-process",
+    "entry": "index.js"
+  },
+  "scripts": {
+    "generate": "npx plugin-kit generate -e ./index.js -o ./ui/src/generated",
+    "dev": "vite",
+    "build": "tsc && npm run generate && vite build",
+    "preview": "vite preview",
+    "test": "npm run test:plugin",
+    "test:plugin": "npm run test:plugin:functions && npm run test:plugin:ui",
+    "test:plugin:functions": "npx majk-test --type functions",
+    "test:plugin:ui": "node tests/plugin/ui/unit/basic-navigation.test.js",
+    "clean": "rm -rf dist index.js index.d.ts ui/src/generated"
+  },
+  "dependencies": {
+    "@majkapp/plugin-kit": "^3.3.0",
+    "@majkapp/plugin-theme": "^1.0.0",
+    "@majkapp/plugin-ui": "^1.4.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@majkapp/plugin-test": "^1.0.2",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.3.3",
+    "vite": "^6.0.3"
+  }
+}
+```
+
+### Package Naming (REQUIRED)
+
+**Your plugin name MUST use an npm organization scope** (format: `@org/plugin-name`).
+
+Replace `@yourorg` with your organization:
+- If you have an npm organization: `@mycompany/my-plugin`
+- If you don't have one: Use `@majkical/my-plugin`
+
+Example: `@majkical/weather-widget`
+
+### majk Metadata Section
+
+The `majk` object tells MAJK how to load your plugin:
+
+**`type`**: `"in-process"` or `"remote"`
+- `"in-process"` - Plugin runs in MAJK's Node.js process (most common)
+- `"remote"` - Plugin runs in separate process (for isolation)
+
+**`entry`**: Path to compiled plugin file (relative to package root)
+- Usually `"index.js"` (compiled from `src/index.ts`)
+- MAJK loads this file to get your plugin definition
+
+### Important Scripts
+
+**`generate`** - Generate TypeScript client from plugin
+```bash
+npm run generate  # Regenerate after adding/changing functions
+```
+
+**`build`** - Complete build pipeline
+```bash
+npm run build     # 1. Compile TS → index.js
+                  # 2. Generate client
+                  # 3. Build React UI → dist/
+```
+
+**`test:plugin:functions`** - Test plugin functions
+```bash
+npm run test:plugin:functions  # Run all function tests
+```
+
+**`test:plugin:ui`** - Test plugin UI with bot
+```bash
+npm run test:plugin:ui        # Run UI tests with browser automation
+```
+
+## vite.config.js (REQUIRED FORMAT)
+
+**CRITICAL:** Use this EXACT format for your vite.config.js:
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  root: 'ui',                    // React source is in ui/ directory
+  base: '',                      // IMPORTANT: Empty string, NOT './'
+  server: {
+    port: 3000,
+    strictPort: false,
+  },
+  build: {
+    outDir: '../dist',           // Build output to dist/ (parent of ui/)
+    assetsDir: 'assets',
+    emptyOutDir: true,
+  },
+});
+```
+
+**Why `base: ''`?**
+- MAJK loads plugins in iframes with dynamic paths
+- Empty base ensures assets load correctly
+- `base: './'` will cause 404 errors for assets
+
+## 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