npm - @majkapp/plugin-kit - Versions diffs - 1.0.0 - Mend

@majkapp/plugin-kit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,636 @@
+# @majk/plugin-kit
+**Fluent builder framework for creating robust MAJK plugins**
+Build type-safe, production-ready MAJK plugins with excellent developer experience, comprehensive validation, and clear error messages.
+## Features
+✨ **Fluent API** - Chainable builder pattern with full TypeScript support
+🛡️ **Type Safety** - Compile-time checks for routes, IDs, and descriptions
+✅ **Build-Time Validation** - Catches errors before runtime
+📝 **Clear Error Messages** - Actionable suggestions when things go wrong
+🔄 **Auto HTTP Server** - Built-in routing, CORS, error handling
+⚛️ **React & HTML Screens** - Support for both SPA and simple HTML UIs
+🔧 **Tool Management** - Declare tools with schema validation
+💾 **Storage Integration** - Direct access to plugin storage
+📡 **Event Bus** - Subscribe to system events
+🧹 **Auto Cleanup** - Managed lifecycle with automatic resource cleanup
+❤️ **Health Checks** - Built-in health monitoring
+## Installation
+```bash
+npm install @majk/plugin-kit
+```
+## Quick Start
+```typescript
+import { definePlugin } from '@majk/plugin-kit';
+export default definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .ui({ appDir: 'ui/dist' })
+  .topbar('/plugin-screens/my-plugin/dashboard', {
+    icon: '🚀'
+  })
+  .screenReact({
+    id: 'dashboard',
+    name: 'Dashboard',
+    description: 'Main dashboard for my plugin. Shows key metrics and actions.',
+    route: '/plugin-screens/my-plugin/dashboard',
+    reactPath: '/'
+  })
+  .apiRoute({
+    method: 'GET',
+    path: '/api/data',
+    name: 'Get Data',
+    description: 'Retrieves plugin data. Returns formatted response with metadata.',
+    handler: async (req, res, { majk, storage }) => {
+      const data = await storage.get('data') || [];
+      return { data, count: data.length };
+    }
+  })
+  .tool('global', {
+    name: 'myTool',
+    description: 'Does something useful. Processes input and returns results.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        param: { type: 'string' }
+      },
+      required: ['param']
+    }
+  }, async (input, { logger }) => {
+    logger.info(`Tool called with: ${input.param}`);
+    return { success: true, result: input.param.toUpperCase() };
+  })
+  .build();
+```
+## Core Concepts
+### Plugin Definition
+Every plugin starts with `definePlugin(id, name, version)`:
+```typescript
+definePlugin('system-explorer', 'System Explorer', '1.0.0')
+```
+**Rules:**
+- `id` must be unique and URL-safe (kebab-case recommended)
+- `name` is the display name
+- `version` follows semver
+### Screens
+#### React Screens
+For React SPAs, configure UI first:
+```typescript
+.ui({
+  appDir: 'ui/dist',        // Where your built React app is
+  base: '/',                // Base URL for the SPA
+  history: 'browser'        // 'browser' or 'hash' routing
+})
+.screenReact({
+  id: 'dashboard',
+  name: 'Dashboard',
+  description: 'Main dashboard view. Shows metrics and controls.',  // 2-3 sentences
+  route: '/plugin-screens/my-plugin/dashboard',  // Must start with /plugin-screens/{id}/
+  reactPath: '/'  // Path within your React app
+})
+```
+**The React app receives:**
+- `window.__MAJK_BASE_URL__` - Host base URL
+- `window.__MAJK_IFRAME_BASE__` - Plugin base path
+- `window.__MAJK_PLUGIN_ID__` - Your plugin ID
+#### HTML Screens
+For simple HTML pages:
+```typescript
+.screenHtml({
+  id: 'about',
+  name: 'About',
+  description: 'Information about the plugin. Shows version and author.',
+  route: '/plugin-screens/my-plugin/about',
+  html: '<html>...'  // OR htmlFile: 'about.html'
+})
+```
+### API Routes
+Define REST endpoints:
+```typescript
+.apiRoute({
+  method: 'POST',
+  path: '/api/tasks/:id/complete',
+  name: 'Complete Task',
+  description: 'Marks a task as complete. Updates task status and triggers notifications.',
+  handler: async (req, res, { majk, storage, logger }) => {
+    const { id } = req.params;       // Path parameters
+    const { note } = req.body;       // Request body
+    const status = req.query.get('status');  // Query params
+    logger.info(`Completing task ${id}`);
+    // Access MAJK APIs
+    const todos = await majk.todos.list();
+    // Use plugin storage
+    await storage.set(`task:${id}`, { completed: true });
+    return { success: true, taskId: id };
+  }
+})
+```
+**Available Methods:** `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
+**Context Provided:**
+- `majk` - Full MAJK API interface
+- `storage` - Plugin-scoped key-value storage
+- `logger` - Scoped logger (debug, info, warn, error)
+- `http` - HTTP configuration (port, baseUrl, secret)
+### Tools
+Tools are functions that agents can invoke:
+```typescript
+.tool(
+  'conversation',  // Scope: 'global' | 'conversation' | 'teammate' | 'project'
+  {
+    name: 'analyzeSentiment',
+    description: 'Analyzes text sentiment. Returns positive, negative, or neutral classification.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string' }
+      },
+      required: ['text']
+    }
+  },
+  async (input, { majk, logger }) => {
+    logger.info('Analyzing sentiment');
+    // Your implementation
+    const sentiment = analyzeSentiment(input.text);
+    return {
+      success: true,
+      data: { sentiment, confidence: 0.95 }
+    };
+  }
+)
+```
+**Tool Scopes:**
+- `global` - Available everywhere
+- `conversation` - Scoped to conversations
+- `teammate` - Scoped to teammates
+- `project` - Scoped to projects
+### Entities
+Declare entities your plugin provides:
+```typescript
+.entity('teammate', [
+  {
+    id: 'bot-assistant',
+    name: 'Bot Assistant',
+    role: 'bot',
+    capabilities: ['analysis', 'reporting']
+  }
+])
+.entity('mcpServer', [
+  {
+    id: 'custom-server',
+    name: 'Custom MCP Server',
+    transport: { type: 'stdio', command: 'node', args: ['server.js'] }
+  }
+])
+```
+**Supported Entity Types:**
+- `mcpServer` - MCP servers
+- `teammate` - Team members/bots
+- `conversation` - Conversations
+- `todo` - Tasks
+- `project` - Projects
+- `agent` - AI agents
+### Config Wizard & Settings
+#### Config Wizard
+Show a wizard on first run:
+```typescript
+.configWizard({
+  path: '/setup',
+  title: 'Initial Setup',
+  width: 600,
+  height: 400,
+  description: 'Configure plugin settings. Set up API keys and preferences.',
+  shouldShow: async (ctx) => {
+    const config = await ctx.storage.get('config');
+    return !config;  // Show if no config exists
+  }
+})
+```
+#### Settings Screen
+Ongoing settings management:
+```typescript
+.settings({
+  path: '/settings',
+  title: 'Plugin Settings',
+  description: 'Manage plugin configuration. Adjust behavior and display options.'
+})
+```
+### Lifecycle Hooks
+#### onReady
+Called after server starts, before `onLoad` completes:
+```typescript
+.onReady(async (ctx, cleanup) => {
+  // Subscribe to events
+  const sub = ctx.majk.eventBus.conversations().subscribe((event) => {
+    ctx.logger.info(`Conversation event: ${event.type}`);
+  });
+  cleanup(() => sub.unsubscribe());
+  // Set up timers
+  const timer = setInterval(() => {
+    ctx.logger.debug('Periodic check');
+  }, 60000);
+  cleanup(() => clearInterval(timer));
+  // Any other setup
+  await loadData(ctx.storage);
+})
+```
+**Cleanup Registration:**
+All cleanup functions are automatically called on `onUnload()`.
+#### Health Checks
+Define custom health monitoring:
+```typescript
+.health(async ({ majk, storage, logger }) => {
+  try {
+    // Check dependencies
+    await majk.conversations.list();
+    await storage.get('health-check');
+    return {
+      healthy: true,
+      details: { api: 'ok', storage: 'ok' }
+    };
+  } catch (error) {
+    logger.error(`Health check failed: ${error.message}`);
+    return {
+      healthy: false,
+      details: { error: error.message }
+    };
+  }
+})
+```
+## API Reference
+### PluginContext
+Provided to all handlers and hooks:
+```typescript
+interface PluginContext {
+  pluginId: string;        // Your plugin ID
+  pluginRoot: string;      // Plugin directory path
+  dataDir: string;         // Plugin data directory
+  app: {
+    version: string;       // MAJK version
+    name: string;          // App name
+    appDataDir: string;    // App data directory
+  };
+  http: {
+    port: number;          // Assigned HTTP port
+    secret: string;        // Security secret
+    baseUrl: string;       // Base URL for iframe
+  };
+  majk: MajkInterface;     // Full MAJK API
+  storage: PluginStorage;  // Key-value storage
+  logger: PluginLogger;    // Scoped logger
+  timers?: ScopedTimers;   // Managed timers
+  ipc?: ScopedIpcRegistry; // Electron IPC
+}
+```
+### MajkInterface
+The main MAJK API:
+```typescript
+interface MajkInterface {
+  conversations: ConversationAPI;
+  todos: TodoAPI;
+  projects: ProjectAPI;
+  teammates: TeammateAPI;
+  mcpServers: MCPServerAPI;
+  knowledge: KnowledgeAPI;
+  tasks: TaskAPI;
+  eventBus: EventBusAPI;
+  auth: AuthAPI;
+  secrets: SecretsAPI;
+  plugins: PluginManagementAPI;
+}
+```
+### PluginStorage
+Simple key-value storage scoped to your plugin:
+```typescript
+interface PluginStorage {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+  keys(): Promise<string[]>;
+}
+```
+**Example:**
+```typescript
+// Save data
+await storage.set('user-preferences', {
+  theme: 'dark',
+  notifications: true
+});
+// Load data
+const prefs = await storage.get<Preferences>('user-preferences');
+// List all keys
+const keys = await storage.keys();
+// Delete specific key
+await storage.delete('old-data');
+// Clear everything
+await storage.clear();
+```
+### EventBus
+Subscribe to system events:
+```typescript
+// Listen to conversation events
+const sub = majk.eventBus.conversations().subscribe((event) => {
+  console.log(`Event: ${event.type}`, event.entity);
+});
+// Unsubscribe
+sub.unsubscribe();
+// Specific event types
+majk.eventBus.conversations().created().subscribe(...);
+majk.eventBus.conversations().updated().subscribe(...);
+majk.eventBus.conversations().deleted().subscribe(...);
+// Custom channels
+majk.eventBus.channel('my-events').subscribe(...);
+```
+## Validation & Error Handling
+### Build-Time Validation
+The kit validates at build time:
+✅ **Route Prefixes** - Screen routes must match plugin ID
+✅ **File Existence** - React dist and HTML files must exist
+✅ **Uniqueness** - No duplicate routes, tools, or API endpoints
+✅ **Dependencies** - UI must be configured for React screens
+✅ **Descriptions** - Must be 2-3 sentences ending with period
+**Example Error:**
+```
+❌ Plugin Build Failed: React screen route must start with "/plugin-screens/my-plugin/"
+💡 Suggestion: Change route from "/screens/dashboard" to "/plugin-screens/my-plugin/dashboard"
+📋 Context: {
+  "screen": "dashboard",
+  "route": "/screens/dashboard"
+}
+```
+### Runtime Error Handling
+All API route errors are automatically caught and logged:
+```typescript
+.apiRoute({
+  method: 'POST',
+  path: '/api/process',
+  name: 'Process Data',
+  description: 'Processes input data. Validates and transforms the payload.',
+  handler: async (req, res, { logger }) => {
+    // Errors are automatically caught and returned as 500 responses
+    throw new Error('Processing failed');
+    // Returns:
+    // {
+    //   "error": "Processing failed",
+    //   "route": "Process Data",
+    //   "path": "/api/process"
+    // }
+  }
+})
+```
+Logs show:
+```
+❌ POST /api/process - Error: Processing failed
+[stack trace]
+```
+## Best Practices
+### 1. Use Storage for State
+```typescript
+// ❌ Don't use in-memory state
+let cache = {};
+// ✅ Use storage
+await ctx.storage.set('cache', data);
+```
+### 2. Register Cleanups
+```typescript
+.onReady(async (ctx, cleanup) => {
+  // ❌ Don't forget to cleanup
+  const timer = setInterval(...);
+  // ✅ Register cleanup
+  const timer = setInterval(...);
+  cleanup(() => clearInterval(timer));
+  // ✅ Event subscriptions
+  const sub = ctx.majk.eventBus.conversations().subscribe(...);
+  cleanup(() => sub.unsubscribe());
+})
+```
+### 3. Validate Input
+```typescript
+.apiRoute({
+  method: 'POST',
+  path: '/api/create',
+  name: 'Create Item',
+  description: 'Creates a new item. Validates input before processing.',
+  handler: async (req, res) => {
+    // ✅ Validate input
+    if (!req.body?.name) {
+      res.status(400).json({ error: 'Name is required' });
+      return;
+    }
+    // Process...
+  }
+})
+```
+### 4. Use Structured Logging
+```typescript
+// ❌ Basic logging
+logger.info('User action');
+// ✅ Structured logging
+logger.info('User action', { userId, action: 'create', resourceId });
+```
+### 5. Handle Errors Gracefully
+```typescript
+.tool('global', spec, async (input, { logger }) => {
+  try {
+    const result = await processData(input);
+    return { success: true, data: result };
+  } catch (error) {
+    logger.error(`Tool failed: ${error.message}`);
+    return {
+      success: false,
+      error: error.message,
+      code: 'PROCESSING_ERROR'
+    };
+  }
+})
+```
+## Examples
+See `example.ts` for a comprehensive example showing:
+- React and HTML screens
+- API routes with parameters
+- Tools in different scopes
+- Entity declarations
+- Config wizard
+- Event subscriptions
+- Storage usage
+- Health checks
+## TypeScript
+Full TypeScript support with:
+```typescript
+import {
+  definePlugin,
+  FluentBuilder,
+  PluginContext,
+  RequestLike,
+  ResponseLike
+} from '@majk/plugin-kit';
+// Type-safe plugin ID
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0');
+//                           ^ Enforces route prefixes
+// Type-safe routes
+.screenReact({
+  route: '/plugin-screens/my-plugin/dashboard'
+  //                      ^^^^^^^^^ Must match plugin ID
+})
+```
+## Troubleshooting
+### "React app not built"
+```
+❌ Plugin Build Failed: React app not built: /path/to/ui/dist/index.html does not exist
+💡 Suggestion: Run "npm run build" in your UI directory to build the React app
+```
+**Fix:** Build your React app before building the plugin.
+### "Duplicate API route"
+```
+❌ Plugin Build Failed: Duplicate API route: POST /api/data
+```
+**Fix:** Each route (method + path) must be unique.
+### "Description must be 2-3 sentences"
+```
+❌ Plugin Build Failed: Description for "My Screen" must be 2-3 sentences, found 1 sentences
+💡 Suggestion: Rewrite the description to have 2-3 clear sentences.
+```
+**Fix:** Write 2-3 complete sentences ending with periods.
+### "Tool names must be unique"
+```
+❌ Plugin Build Failed: Duplicate tool name: "analyze"
+```
+**Fix:** Each tool name must be unique within the plugin.
+## License
+MIT

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+/**
+ * @majk/plugin-kit
+ *
+ * Fluent builder framework for creating robust MAJK plugins with:
+ * - Type-safe route and tool definitions
+ * - Compile-time and build-time validation
+ * - Clear, actionable error messages
+ * - Automatic HTTP server management
+ * - Built-in CORS, error handling, and logging
+ * - React SPA and HTML screen support
+ * - Entity, tool, and API route declarations
+ * - Lifecycle hooks with cleanup management
+ */
+export { definePlugin, FluentBuilder } from './plugin-kit';
+export type { PluginContext, PluginLogger, PluginStorage, ScopedTimers, ScopedIpcRegistry, PluginCapabilities, PluginCapability, ToolImplementation, InProcessPlugin, PluginHealthStatus, ToolSpec, ToolHandler, ApiMethod, ApiRouteDef, RouteHandler, RequestLike, ResponseLike, UiConfig, HistoryMode, ScreenBase, ReactScreen, HtmlScreen, ConfigWizardDef, SettingsDef, Scope, EntityType, CleanupFn, HealthCheckFn } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE3D,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,WAAW,EACX,UAAU,EACV,eAAe,EACf,WAAW,EACX,KAAK,EACL,UAAU,EACV,SAAS,EACT,aAAa,EACd,MAAM,SAAS,CAAC"}

package/dist/index.js ADDED Viewed

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * @majk/plugin-kit
+ *
+ * Fluent builder framework for creating robust MAJK plugins with:
+ * - Type-safe route and tool definitions
+ * - Compile-time and build-time validation
+ * - Clear, actionable error messages
+ * - Automatic HTTP server management
+ * - Built-in CORS, error handling, and logging
+ * - React SPA and HTML screen support
+ * - Entity, tool, and API route declarations
+ * - Lifecycle hooks with cleanup management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePlugin = void 0;
+var plugin_kit_1 = require("./plugin-kit");
+Object.defineProperty(exports, "definePlugin", { enumerable: true, get: function () { return plugin_kit_1.definePlugin; } });

package/dist/plugin-kit.d.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { PluginContext, InProcessPlugin, ToolSpec, ToolHandler, ApiRouteDef, UiConfig, ReactScreen, HtmlScreen, ConfigWizardDef, SettingsDef, Scope, EntityType, CleanupFn, HealthCheckFn } from './types';
+/**
+ * Fluent Builder Interface
+ */
+export interface FluentBuilder<Id extends string> {
+    /** Add a topbar item that navigates to a screen */
+    topbar(route: `/plugin-screens/${Id}/${string}`, opts?: {
+        icon?: string;
+        id?: string;
+        name?: string;
+    }): this;
+    /** Configure UI settings for React SPA */
+    ui(config?: UiConfig): this;
+    /** Add a React screen */
+    screenReact(screen: ReactScreen<Id>): this;
+    /** Add an HTML screen */
+    screenHtml(screen: HtmlScreen<Id>): this;
+    /** Add an API route */
+    apiRoute(route: ApiRouteDef): this;
+    /** Add a tool */
+    tool(scope: Scope, spec: ToolSpec, handler: ToolHandler): this;
+    /** Declare entities that this plugin provides */
+    entity(entityType: EntityType, entities: any[]): this;
+    /** Add config wizard */
+    configWizard(def: ConfigWizardDef): this;
+    /** Add settings screen */
+    settings(def: SettingsDef): this;
+    /** Hook called after server starts */
+    onReady(fn: (ctx: PluginContext, cleanup: (fn: CleanupFn) => void) => void | Promise<void>): this;
+    /** Custom health check */
+    health(fn: HealthCheckFn): this;
+    /** Build the plugin */
+    build(): InProcessPlugin;
+}
+/**
+ * Create a plugin with fluent builder API
+ */
+export declare function definePlugin<const Id extends string>(id: Id, name: string, version: string): FluentBuilder<Id>;
+//# sourceMappingURL=plugin-kit.d.ts.map