@majkapp/plugin-kit 3.7.3 → 3.7.4

package/docs/KNOWLEDGE.md

@@ -0,0 +1,225 @@
+# Knowledge API
+
+Store and search knowledge nodes organized into trees with reference tracking.
+
+## Quick Start
+
+```typescript
+handler: async (input, ctx) => {
+  // Add knowledge
+  await ctx.majk.knowledge.add({
+    conversationId: 'conv-123',
+    title: 'API Design Decision',
+    content: 'We decided to use REST over GraphQL because...',
+    references: ['file:src/api/routes.ts#L10-50'],
+    tree: 'decisions'
+  });
+
+  // Search knowledge
+  const nodes = await ctx.majk.knowledge.search('REST API', {
+    conversationId: 'conv-123'
+  });
+
+  return { found: nodes.length };
+}
+```
+
+## API Reference
+
+### add(input)
+
+Add a knowledge node.
+
+```typescript
+await ctx.majk.knowledge.add({
+  conversationId: string,   // Conversation to associate with
+  title: string,            // Node title
+  content: string,          // Knowledge content
+  references?: string[],    // Reference links (files, URLs, etc.)
+  tree?: string             // Tree name (default: 'default')
+});
+```
+
+### search(query, options?)
+
+Search knowledge by text.
+
+```typescript
+const nodes = await ctx.majk.knowledge.search(query, {
+  conversationId?: string,  // Filter by conversation
+  tree?: string,            // Filter by tree
+  limit?: number            // Max results
+});
+// Returns: KnowledgeNode[]
+```
+
+### getByReference(ref)
+
+Find nodes that reference a specific resource.
+
+```typescript
+const nodes = await ctx.majk.knowledge.getByReference('file:src/api.ts');
+// Returns: KnowledgeNode[]
+```
+
+### getTree(conversationId, treeName)
+
+Get all nodes in a tree.
+
+```typescript
+const tree = await ctx.majk.knowledge.getTree('conv-123', 'decisions');
+// Returns: { name, conversationId, nodes: KnowledgeNode[] }
+```
+
+### listTrees(conversationId)
+
+List all trees in a conversation.
+
+```typescript
+const trees = await ctx.majk.knowledge.listTrees('conv-123');
+// Returns: string[] (tree names)
+```
+
+## Types
+
+```typescript
+interface KnowledgeNode {
+  id: string;
+  title: string;
+  content: string;
+  references: string[];
+  conversationId: string;
+  tree: string;
+  createdAt: Date;
+}
+
+interface KnowledgeTree {
+  name: string;
+  conversationId: string;
+  nodes: KnowledgeNode[];
+}
+```
+
+## Reference Patterns
+
+Use consistent reference formats:
+
+```typescript
+// File references
+'file:src/api/routes.ts'
+'file:src/api/routes.ts#L10-50'
+
+// URL references
+'url:https://docs.example.com/api'
+
+// Function references
+'function:createUser'
+'function:src/api.ts:createUser'
+
+// Commit references
+'commit:abc123'
+
+// Issue/PR references
+'issue:42'
+'pr:123'
+```
+
+## Common Patterns
+
+### Organize by Topic
+
+```typescript
+// Add to different trees
+await ctx.majk.knowledge.add({
+  conversationId,
+  title: 'Auth Flow Decision',
+  content: 'Using JWT tokens...',
+  tree: 'architecture'
+});
+
+await ctx.majk.knowledge.add({
+  conversationId,
+  title: 'JWT Security Concern',
+  content: 'Token expiry handling...',
+  tree: 'security'
+});
+
+// Query specific tree
+const archNodes = await ctx.majk.knowledge.getTree(conversationId, 'architecture');
+```
+
+### Track Code References
+
+```typescript
+// Add knowledge about code
+await ctx.majk.knowledge.add({
+  conversationId,
+  title: 'Rate Limiter Implementation',
+  content: 'The rate limiter uses a sliding window algorithm...',
+  references: [
+    'file:src/middleware/rateLimiter.ts',
+    'file:src/config/limits.ts#L5-20',
+    'url:https://en.wikipedia.org/wiki/Sliding_window_protocol'
+  ],
+  tree: 'implementation'
+});
+
+// Later, find all knowledge about a file
+const related = await ctx.majk.knowledge.getByReference('file:src/middleware/rateLimiter.ts');
+```
+
+### Build Context for Analysis
+
+```typescript
+async function getProjectContext(conversationId: string) {
+  const trees = await ctx.majk.knowledge.listTrees(conversationId);
+
+  const context = {};
+  for (const treeName of trees) {
+    const tree = await ctx.majk.knowledge.getTree(conversationId, treeName);
+    context[treeName] = tree.nodes.map(n => ({
+      title: n.title,
+      summary: n.content.slice(0, 200)
+    }));
+  }
+
+  return context;
+}
+```
+
+### Search Across Everything
+
+```typescript
+// Broad search
+const results = await ctx.majk.knowledge.search('authentication');
+
+// Filtered search
+const securityResults = await ctx.majk.knowledge.search('authentication', {
+  conversationId,
+  tree: 'security',
+  limit: 5
+});
+```
+
+## Best Practices
+
+1. **Use meaningful titles** - Clear, searchable node titles
+2. **Consistent tree names** - Standardize tree names across conversations
+3. **Rich references** - Link to files, URLs, commits for traceability
+4. **Structured content** - Use markdown for formatted content
+5. **Search-friendly content** - Include keywords that users might search for
+
+## Tree Organization Examples
+
+```
+decisions/       - Architecture and design decisions
+security/        - Security considerations and findings
+implementation/  - How things are implemented
+bugs/           - Known issues and their context
+research/       - Background research and findings
+```
+
+## Next Steps
+
+Run `npx @majkapp/plugin-kit --reports` - Reports and knowledge base
+Run `npx @majkapp/plugin-kit --context` - Context API overview

package/docs/PLUGINS.md

@@ -0,0 +1,356 @@
+# Plugin Management API
+
+The `ctx.majk.plugins` API provides comprehensive plugin lifecycle management, health monitoring, and administration capabilities.
+
+## Overview
+
+```typescript
+// Access the plugin management API
+const pluginAPI = ctx.majk.plugins;
+
+// Install a plugin
+await pluginAPI.install('my-plugin@1.0.0');
+
+// Start/stop plugin lifecycle
+await pluginAPI.start('my-plugin');
+await pluginAPI.stop('my-plugin');
+
+// Monitor health and logs
+const health = await pluginAPI.getHealth('my-plugin');
+const logs = await pluginAPI.getLogs('my-plugin');
+```
+
+## Installation Management
+
+### install(identifier, options?)
+Install a plugin from various sources.
+
+```typescript
+// Install from npm
+await ctx.majk.plugins.install('my-plugin@1.0.0');
+
+// Install from local path
+await ctx.majk.plugins.install('/path/to/plugin');
+
+// Install with options
+await ctx.majk.plugins.install('my-plugin', {
+  force: true,           // Force reinstall
+  dev: true,            // Install as development dependency
+  registry: 'custom'    // Use custom registry
+});
+```
+
+**Returns:** `InstallPluginResult` with installation details and any errors.
+
+### uninstall(pluginId)
+Remove a plugin completely.
+
+```typescript
+const success = await ctx.majk.plugins.uninstall('my-plugin');
+console.log(success ? 'Uninstalled' : 'Failed to uninstall');
+```
+
+**Returns:** `boolean` indicating success.
+
+## Plugin Discovery
+
+### list()
+Get all installed plugins.
+
+```typescript
+const plugins = await ctx.majk.plugins.list();
+plugins.forEach(plugin => {
+  console.log(`${plugin.name} v${plugin.version} - ${plugin.status}`);
+});
+```
+
+**Returns:** `PluginInfo[]` with plugin metadata and status.
+
+### get(pluginId)
+Get detailed information about a specific plugin.
+
+```typescript
+const plugin = await ctx.majk.plugins.get('my-plugin');
+if (plugin) {
+  console.log(`Plugin: ${plugin.name}`);
+  console.log(`Status: ${plugin.status}`);
+  console.log(`Capabilities: ${plugin.capabilities?.length || 0}`);
+}
+```
+
+**Returns:** `PluginInfo | null` if plugin exists.
+
+## Lifecycle Management
+
+### start(pluginId)
+Start a stopped plugin.
+
+```typescript
+await ctx.majk.plugins.start('my-plugin');
+console.log('Plugin started');
+```
+
+### stop(pluginId)
+Stop a running plugin gracefully.
+
+```typescript
+await ctx.majk.plugins.stop('my-plugin');
+console.log('Plugin stopped');
+```
+
+### restart(pluginId)
+Stop and start a plugin.
+
+```typescript
+await ctx.majk.plugins.restart('my-plugin');
+console.log('Plugin restarted');
+```
+
+### reload(pluginId)
+Reload plugin code without stopping (hot reload).
+
+```typescript
+await ctx.majk.plugins.reload('my-plugin');
+console.log('Plugin code reloaded');
+```
+
+### enable(pluginId) / disable(pluginId)
+Enable or disable a plugin.
+
+```typescript
+// Disable plugin (stops and prevents auto-start)
+await ctx.majk.plugins.disable('my-plugin');
+
+// Re-enable plugin
+await ctx.majk.plugins.enable('my-plugin');
+```
+
+### isRunning(pluginId)
+Check if plugin is currently running.
+
+```typescript
+if (ctx.majk.plugins.isRunning('my-plugin')) {
+  console.log('Plugin is active');
+} else {
+  console.log('Plugin is stopped');
+}
+```
+
+**Returns:** `boolean` - synchronous check.
+
+## Health Monitoring
+
+### getHealth(pluginId)
+Get plugin health status and diagnostics.
+
+```typescript
+const health = await ctx.majk.plugins.getHealth('my-plugin');
+if (health) {
+  console.log(`Status: ${health.status}`);
+  console.log(`Memory: ${health.memoryUsage}MB`);
+  console.log(`Uptime: ${health.uptime}ms`);
+
+  if (health.errors?.length > 0) {
+    console.log('Recent errors:', health.errors);
+  }
+}
+```
+
+**Returns:** `PluginHealth | null` with performance metrics and error information.
+
+### getCapabilities(pluginId)
+Get plugin's registered capabilities (functions, screens, services).
+
+```typescript
+const capabilities = await ctx.majk.plugins.getCapabilities('my-plugin');
+capabilities.forEach(cap => {
+  console.log(`${cap.type}: ${cap.name} - ${cap.description}`);
+});
+```
+
+**Returns:** `PluginCapabilityInfo[]` listing all plugin capabilities.
+
+## Logging
+
+### getLogs(pluginId, options?)
+Retrieve plugin logs for debugging.
+
+```typescript
+// Get recent logs
+const logs = await ctx.majk.plugins.getLogs('my-plugin');
+
+// Get logs with filters
+const errorLogs = await ctx.majk.plugins.getLogs('my-plugin', {
+  level: 'error',        // Filter by log level
+  since: Date.now() - 3600000,  // Last hour
+  limit: 100            // Max entries
+});
+
+logs.forEach(log => {
+  console.log(`[${log.timestamp}] ${log.level}: ${log.message}`);
+});
+```
+
+**Returns:** `PluginLog[]` with timestamped log entries.
+
+### clearLogs(pluginId)
+Clear plugin's log history.
+
+```typescript
+await ctx.majk.plugins.clearLogs('my-plugin');
+console.log('Logs cleared');
+```
+
+## Development Tools
+
+### setHotReload(pluginId, enabled)
+Enable/disable hot reload for development.
+
+```typescript
+// Enable hot reload for development
+await ctx.majk.plugins.setHotReload('my-plugin', true);
+
+// Disable for production
+await ctx.majk.plugins.setHotReload('my-plugin', false);
+```
+
+### isHotReloadEnabled(pluginId)
+Check hot reload status.
+
+```typescript
+const hotReloadEnabled = await ctx.majk.plugins.isHotReloadEnabled('my-plugin');
+console.log(`Hot reload: ${hotReloadEnabled ? 'ON' : 'OFF'}`);
+```
+
+## URL Generation
+
+### getPluginExternalUrl(pluginId, options?)
+Get external URL for plugin access.
+
+```typescript
+const url = await ctx.majk.plugins.getPluginExternalUrl('my-plugin');
+console.log(`Plugin accessible at: ${url}`);
+
+// With custom options
+const customUrl = await ctx.majk.plugins.getPluginExternalUrl('my-plugin', {
+  path: '/api/status',
+  port: 8080
+});
+```
+
+**Returns:** `string` - External URL for plugin access.
+
+### getPluginScreenUrl(pluginId, options?)
+Get URL for plugin's UI screens.
+
+```typescript
+const screenUrl = await ctx.majk.plugins.getPluginScreenUrl('my-plugin');
+console.log(`Plugin UI at: ${screenUrl}`);
+
+// For specific screen
+const specificScreen = await ctx.majk.plugins.getPluginScreenUrl('my-plugin', {
+  screen: 'dashboard',
+  params: { view: 'admin' }
+});
+```
+
+**Returns:** `string` - URL for plugin UI screens.
+
+## Common Patterns
+
+### Plugin Health Check
+```typescript
+async function checkPluginHealth(pluginId: string) {
+  if (!ctx.majk.plugins.isRunning(pluginId)) {
+    console.log(`Plugin ${pluginId} is not running`);
+    return;
+  }
+
+  const health = await ctx.majk.plugins.getHealth(pluginId);
+  if (health?.status === 'unhealthy') {
+    console.log(`Plugin ${pluginId} is unhealthy:`, health.errors);
+    // Consider restarting
+    await ctx.majk.plugins.restart(pluginId);
+  }
+}
+```
+
+### Plugin Lifecycle with Error Handling
+```typescript
+async function safePluginOperation(pluginId: string, operation: 'start' | 'stop' | 'restart') {
+  try {
+    await ctx.majk.plugins[operation](pluginId);
+    console.log(`Plugin ${pluginId} ${operation} successful`);
+  } catch (error) {
+    console.error(`Failed to ${operation} plugin ${pluginId}:`, error);
+
+    // Check logs for more details
+    const logs = await ctx.majk.plugins.getLogs(pluginId, {
+      level: 'error',
+      limit: 5
+    });
+    console.log('Recent errors:', logs);
+  }
+}
+```
+
+### Development Workflow
+```typescript
+async function setupDevelopment(pluginId: string) {
+  // Enable hot reload for development
+  await ctx.majk.plugins.setHotReload(pluginId, true);
+
+  // Start the plugin
+  await ctx.majk.plugins.start(pluginId);
+
+  // Get development URLs
+  const externalUrl = await ctx.majk.plugins.getPluginExternalUrl(pluginId);
+  const screenUrl = await ctx.majk.plugins.getPluginScreenUrl(pluginId);
+
+  console.log('Development setup complete:');
+  console.log(`- Plugin API: ${externalUrl}`);
+  console.log(`- Plugin UI: ${screenUrl}`);
+  console.log('- Hot reload: ENABLED');
+}
+```
+
+## Type Definitions
+
+```typescript
+interface PluginInfo {
+  id: string;
+  name: string;
+  version: string;
+  status: 'running' | 'stopped' | 'error' | 'disabled';
+  description?: string;
+  author?: string;
+  capabilities?: PluginCapabilityInfo[];
+}
+
+interface PluginHealth {
+  status: 'healthy' | 'unhealthy' | 'unknown';
+  uptime: number;
+  memoryUsage: number;
+  errors?: string[];
+  lastCheck: number;
+}
+
+interface PluginLog {
+  timestamp: number;
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  context?: any;
+}
+
+interface InstallPluginOptions {
+  force?: boolean;
+  dev?: boolean;
+  registry?: string;
+}
+
+interface GetLogsOptions {
+  level?: 'debug' | 'info' | 'warn' | 'error';
+  since?: number;
+  limit?: number;
+}
+```