pi-harness-runtime 0.5.0 → 0.6.3-beta.13

package/packages/framework-plugin-sdk/README.md

@@ -0,0 +1,399 @@
+# @pi/framework-plugin-sdk
+
+Extensible plugin SDK for framework integrations, custom providers, and tooling.
+
+## Features
+
+- **Plugin Lifecycle** - Register, load, initialize, activate, deactivate, unload
+- **Hook System** - Register and execute hooks across plugins
+- **Capability Registry** - Manage plugin capabilities centrally
+- **Lifecycle Events** - Subscribe to plugin lifecycle changes
+- **Manifest Validation** - Validate plugin manifests before loading
+- **Sandbox Support** - Optional sandboxing for untrusted plugins
+- **Error Handling** - Comprehensive error codes and handling
+
+## Installation
+
+```bash
+npm install @pi/framework-plugin-sdk
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { createPluginManager } from "@pi/framework-plugin-sdk";
+
+const manager = createPluginManager({
+  pluginDir: "./plugins",
+  autoActivate: true,
+});
+
+// Register a plugin
+const plugin = await manager.register({
+  id: "my-plugin",
+  name: "My Plugin",
+  version: "1.0.0",
+  description: "A custom plugin",
+  capabilities: ["provider", "framework"],
+});
+
+// Load and activate
+await manager.load({ plugin: "my-plugin" });
+await manager.initialize("my-plugin");
+await manager.activate("my-plugin");
+
+// Get plugin info
+const info = manager.getPlugin("my-plugin");
+console.log(info.status); // "active"
+```
+
+### Plugin Manifest
+
+```json
+{
+  "id": "my-frappe-plugin",
+  "name": "Frappe Plugin",
+  "version": "1.0.0",
+  "description": "Frappe framework integration",
+  "capabilities": ["framework", "provider"],
+  "dependencies": {
+    "@pi/core": "^1.0.0"
+  },
+  "entryPoint": "./dist/index.js",
+  "configuration": {
+    "schema": {
+      "apiUrl": {
+        "type": "string",
+        "required": true
+      }
+    },
+    "defaults": {
+      "apiUrl": "https://frappe.example.com/api"
+    }
+  },
+  "hooks": [
+    {
+      "name": "onTaskComplete",
+      "description": "Called when a task completes"
+    }
+  ],
+  "permissions": [
+    {
+      "action": "network",
+      "scope": "all"
+    }
+  ]
+}
+```
+
+### Hooks
+
+```typescript
+// Register a hook handler
+manager.registerHook({
+  id: "my-hook",
+  name: "onTaskComplete",
+  pluginId: "my-plugin",
+  priority: 10,
+  handler: async (context) => {
+    console.log("Task completed:", context);
+    return { handled: true };
+  },
+});
+
+// Execute hooks
+const result = await manager.executeHooks("onTaskComplete", { taskId: "123" });
+console.log(result.results); // [{ handled: true }]
+```
+
+### Lifecycle Events
+
+```typescript
+manager.onLifecycle("afterActivate", (ctx) => {
+  console.log(`Plugin ${ctx.pluginId} activated`);
+});
+
+manager.onLifecycle("beforeUnload", (ctx) => {
+  console.log(`Plugin ${ctx.pluginId} about to unload`);
+});
+```
+
+### Capabilities
+
+```typescript
+// Register a capability
+manager.registerCapability("my-plugin", "provider", {
+  complete: async (prompt) => {
+    return "Generated response";
+  },
+});
+
+// Get capabilities
+const providers = manager.getCapabilities("provider");
+console.log(providers); // [{ id: "my-plugin:provider", ... }]
+```
+
+### Capabilities Reference
+
+| Capability | Description |
+| ------------ | ------------- |
+| `provider` | Custom AI provider implementation |
+| `framework` | Framework detection extension |
+| `generator` | Code generator |
+| `linter` | Custom linter rules |
+| `template` | Code templates |
+| `validator` | Custom validators |
+| `tool` | Custom tools |
+| `hook` | Hook handler |
+
+## Plugin Capabilities
+
+### Provider Extension
+
+```typescript
+manager.registerCapability("my-plugin", "provider", {
+  capability: "provider",
+  name: "My Provider",
+  provider: {
+    complete: async (prompt, options) => {
+      // Custom completion logic
+      return { content: "Response" };
+    },
+    stream: async function* (prompt, options) {
+      // Streaming support
+      yield { content: "Partial " };
+      yield { content: "response" };
+    },
+    embed: async (input) => {
+      // Embeddings
+      return [0.1, 0.2, 0.3];
+    },
+  },
+});
+```
+
+### Framework Extension
+
+```typescript
+manager.registerCapability("frappe-plugin", "framework", {
+  capability: "framework",
+  name: "Frappe Detector",
+  detector: {
+    detect: async (context) => {
+      // Return detected framework info
+      return { id: "frappe", confidence: 0.9 };
+    },
+    signals: [
+      { type: "file", pattern: "sites", weight: 0.3 },
+      { type: "file", pattern: "bench", weight: 0.3 },
+    ],
+  },
+});
+```
+
+### Tool Extension
+
+```typescript
+manager.registerCapability("my-plugin", "tool", {
+  capability: "tool",
+  name: "Custom Tools",
+  tools: [
+    {
+      name: "fetchData",
+      description: "Fetch data from an API",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string" },
+        },
+        required: ["url"],
+      },
+      execute: async (params) => {
+        const { url } = params as { url: string };
+        return { data: await fetch(url) };
+      },
+    },
+  ],
+});
+```
+
+## API Reference
+
+### PluginManager
+
+```typescript
+const manager = createPluginManager({
+  pluginDir?: string;        // Plugin directory
+  autoLoad?: boolean;         // Auto-load plugins
+  autoActivate?: boolean;     // Auto-activate plugins
+  patterns?: string[];         // Plugin search patterns
+  sandbox?: SandboxConfig;     // Sandbox configuration
+  hooks?: boolean;            // Enable hooks
+  logLevel?: "debug" | "info" | "warn" | "error";
+});
+```
+
+### Methods
+
+```typescript
+// Register a plugin
+manager.register(manifest: PluginManifest): Promise<Plugin>;
+
+// Load a plugin
+manager.load(options: LoadOptions): Promise<Plugin>;
+
+// Initialize a plugin
+manager.initialize(pluginId: string): Promise<void>;
+
+// Activate a plugin
+manager.activate(pluginId: string): Promise<void>;
+
+// Deactivate a plugin
+manager.deactivate(pluginId: string): Promise<void>;
+
+// Unload a plugin
+manager.unload(pluginId: string): Promise<void>;
+
+// Get plugin
+manager.getPlugin(pluginId: string): Plugin | undefined;
+
+// List all plugins
+manager.listPlugins(): Plugin[];
+
+// List plugins by status
+manager.listByStatus(status: PluginStatus): Plugin[];
+
+// Register a hook
+manager.registerHook(handler: HookHandler): void;
+
+// Unregister a hook
+manager.unregisterHook(handlerId: string): boolean;
+
+// Execute hooks
+manager.executeHooks(hookName: string, context: unknown): Promise<HookResult>;
+
+// Get capabilities by type
+manager.getCapabilities(capability: PluginCapability): RegistryEntry[];
+
+// Get capability instance
+manager.getCapability(pluginId: string, capability: PluginCapability): unknown | undefined;
+
+// Register capability
+manager.registerCapability(pluginId: string, capability: PluginCapability, instance: unknown): void;
+
+// Lifecycle events
+manager.onLifecycle(event: PluginLifecycleEvent, listener: (ctx) => void): void;
+manager.offLifecycle(event: PluginLifecycleEvent, listener: (ctx) => void): void;
+```
+
+### Plugin Status
+
+```typescript
+type PluginStatus =
+  | "registered"  // Manifest registered
+  | "loaded"      // Code loaded
+  | "initialized" // Initialized
+  | "active"      // Running
+  | "inactive"    // Paused
+  | "error"       // Error state
+  | "unloaded";   // Unloaded
+```
+
+### Lifecycle Events
+
+```typescript
+type PluginLifecycleEvent =
+  | "beforeLoad"
+  | "afterLoad"
+  | "beforeInitialize"
+  | "afterInitialize"
+  | "beforeActivate"
+  | "afterActivate"
+  | "beforeDeactivate"
+  | "afterDeactivate"
+  | "beforeUnload"
+  | "afterUnload";
+```
+
+### Error Codes
+
+```typescript
+const PluginErrorCode = {
+  MANIFEST_NOT_FOUND: "MANIFEST_NOT_FOUND",
+  MANIFEST_INVALID: "MANIFEST_INVALID",
+  ENTRY_NOT_FOUND: "ENTRY_NOT_FOUND",
+  LOAD_FAILED: "LOAD_FAILED",
+  INIT_FAILED: "INIT_FAILED",
+  ACTIVATE_FAILED: "ACTIVATE_FAILED",
+  DEACTIVATE_FAILED: "DEACTIVATE_FAILED",
+  PERMISSION_DENIED: "PERMISSION_DENIED",
+  CAPABILITY_NOT_FOUND: "CAPABILITY_NOT_FOUND",
+  DEPENDENCY_MISSING: "DEPENDENCY_MISSING",
+  DEPENDENCY_CONFLICT: "DEPENDENCY_CONFLICT",
+  INCOMPATIBLE_VERSION: "INCOMPATIBLE_VERSION",
+  HOOK_FAILED: "HOOK_FAILED",
+  SANDBOX_ERROR: "SANDBOX_ERROR",
+  ALREADY_LOADED: "ALREADY_LOADED",
+  NOT_LOADED: "NOT_LOADED",
+  NOT_ACTIVE: "NOT_ACTIVE",
+};
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    PluginManager                            │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
+│  │   Lifecycle │  │   Hooks    │  │   Registry     │  │
+│  │   Manager  │──│   System   │──│                 │  │
+│  └─────────────┘  └─────────────┘  └─────────────────┘  │
+│         │                                      │        │
+│         ▼                                      ▼        │
+│  ┌─────────────┐                       ┌─────────────────┐│
+│  │  Event     │                       │  Capabilities  ││
+│  │  Listeners │                       │  [provider]   ││
+│  └─────────────┘                       │  [framework]   ││
+│                                        │  [generator]  ││
+│                                        └─────────────────┘│
+└─────────────────────────────────────────────────────────┘
+        │
+        ▼
+┌─────────────────────────────────────────────────────────┐
+│                    Plugins                                │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐ │
+│  │ Frappe  │  │ Next.js │  │ Django  │  │ Custom  │ │
+│  │ Plugin  │  │ Plugin  │  │ Plugin  │  │ Plugin  │ │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Security
+
+### Sandbox Configuration
+
+```typescript
+const manager = createPluginManager({
+  sandbox: {
+    timeout: 30000,        // 30 second timeout
+    memoryLimit: 128 * 1024 * 1024,  // 128MB
+    networkAccess: false,   // Block network
+    filesystemAccess: "own", // Only own directory
+    allowEval: false,      // No eval
+  },
+});
+```
+
+### Permissions
+
+```json
+{
+  "permissions": [
+    { "action": "network" },
+    { "action": "filesystem", "scope": "own" },
+    { "action": "execute" }
+  ]
+}
+```

package/packages/framework-plugin-sdk/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Framework Plugin SDK
+ *
+ * Extensible plugin system for framework integrations.
+ */
+export { PluginManager, createPluginManager, } from "./manager.js";
+export { SDK_VERSION, type PluginCapability, type PluginStatus, type PluginManifest, type PluginConfiguration, type ConfigSchemaEntry, type HookDefinition, type PluginPermission, type Plugin, type PluginLifecycleEvent, type LifecycleContext, type HookHandler, type HookFunction, type HookResult, type ProviderExtension, type FrameworkExtension, type GeneratorExtension, type LinterExtension, type TemplateExtension, type ValidatorExtension, type ToolExtension, type SandboxConfig, type SandboxResult, type RegistryEntry, type PluginManagerConfig, type LoadOptions, PluginError, PluginErrorCode, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/framework-plugin-sdk/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EACN,aAAa,EACb,mBAAmB,GACnB,MAAM,cAAc,CAAC;AAItB,OAAO,EACN,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,MAAM,EACX,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,WAAW,EACX,eAAe,GACf,MAAM,YAAY,CAAC"}

package/packages/framework-plugin-sdk/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Framework Plugin SDK
+ *
+ * Extensible plugin system for framework integrations.
+ */
+// ─── Manager ──────────────────────────────────────────────────────────
+export { PluginManager, createPluginManager, } from "./manager.js";
+// ─── Types ────────────────────────────────────────────────────────────
+export { SDK_VERSION, PluginError, PluginErrorCode, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/packages/framework-plugin-sdk/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,yEAAyE;AAEzE,OAAO,EACN,aAAa,EACb,mBAAmB,GACnB,MAAM,cAAc,CAAC;AAEtB,yEAAyE;AAEzE,OAAO,EACN,WAAW,EA0BX,WAAW,EACX,eAAe,GACf,MAAM,YAAY,CAAC"}

package/packages/framework-plugin-sdk/dist/manager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Framework Plugin SDK - Plugin Manager
+ *
+ * Main plugin management system.
+ */
+import type { HookHandler, HookResult, LifecycleContext, LoadOptions, Plugin, PluginCapability, PluginLifecycleEvent, PluginManagerConfig, PluginManifest, PluginStatus, RegistryEntry } from "./types.js";
+export declare class PluginManager {
+    private readonly config;
+    private readonly plugins;
+    private readonly hooks;
+    private readonly registry;
+    private lifecycleListeners;
+    constructor(config?: PluginManagerConfig);
+    /**
+     * Register a plugin from manifest
+     */
+    register(manifest: PluginManifest): Promise<Plugin>;
+    /**
+     * Load a plugin
+     */
+    load(options: LoadOptions): Promise<Plugin>;
+    /**
+     * Initialize a plugin
+     */
+    initialize(pluginId: string): Promise<void>;
+    /**
+     * Activate a plugin
+     */
+    activate(pluginId: string): Promise<void>;
+    /**
+     * Deactivate a plugin
+     */
+    deactivate(pluginId: string): Promise<void>;
+    /**
+     * Unload a plugin
+     */
+    unload(pluginId: string): Promise<void>;
+    /**
+     * Get a plugin
+     */
+    getPlugin(pluginId: string): Plugin | undefined;
+    /**
+     * List all plugins
+     */
+    listPlugins(): Plugin[];
+    /**
+     * List plugins by status
+     */
+    listByStatus(status: PluginStatus): Plugin[];
+    /**
+     * Register a hook handler
+     */
+    registerHook(handler: HookHandler): void;
+    /**
+     * Unregister a hook handler
+     */
+    unregisterHook(handlerId: string): boolean;
+    /**
+     * Execute hooks for a name
+     */
+    executeHooks(hookName: string, context: unknown): Promise<HookResult>;
+    /**
+     * Get capabilities by type
+     */
+    getCapabilities(capability: PluginCapability): RegistryEntry[];
+    /**
+     * Get capability instance
+     */
+    getCapability(pluginId: string, capability: PluginCapability): unknown | undefined;
+    /**
+     * Register capability
+     */
+    registerCapability(pluginId: string, capability: PluginCapability, instance: unknown): void;
+    /**
+     * Add lifecycle event listener
+     */
+    onLifecycle(event: PluginLifecycleEvent, listener: (ctx: LifecycleContext) => void): void;
+    /**
+     * Remove lifecycle event listener
+     */
+    offLifecycle(event: PluginLifecycleEvent, listener: (ctx: LifecycleContext) => void): void;
+    /**
+     * Emit lifecycle event
+     */
+    private emitLifecycle;
+    /**
+     * Load manifest from file
+     */
+    private loadManifest;
+    /**
+     * Validate manifest
+     */
+    private validateManifest;
+    /**
+     * Log message
+     */
+    private log;
+}
+/**
+ * Create a plugin manager
+ */
+export declare function createPluginManager(config?: PluginManagerConfig): PluginManager;
+//# sourceMappingURL=manager.d.ts.map

package/packages/framework-plugin-sdk/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACX,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,MAAM,YAAY,CAAC;AAuBpB,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4C;IAClE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;IAClE,OAAO,CAAC,kBAAkB,CAGZ;gBAEF,MAAM,GAAE,mBAAwB;IAI5C;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAuCzD;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IA6CjD;;OAEG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjD;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC/C;;OAEG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BjD;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B7C;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI/C;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE;IAI5C;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAaxC;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAW1C;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAkC3E;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,gBAAgB,GAAG,aAAa,EAAE;IAY9D;;OAEG;IACH,aAAa,CACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,gBAAgB,GAC1B,OAAO,GAAG,SAAS;IAStB;;OAEG;IACH,kBAAkB,CACjB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,OAAO,GACf,IAAI;IAaP;;OAEG;IACH,WAAW,CACV,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GACvC,IAAI;IAOP;;OAEG;IACH,YAAY,CACX,KAAK,EAAE,oBAAoB,EAC3B,QAAQ,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GACvC,IAAI;IAIP;;OAEG;YACW,aAAa;IAsB3B;;OAEG;YACW,YAAY;IAS1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA8BxB;;OAEG;IACH,OAAO,CAAC,GAAG;CAYX;AAID;;GAEG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,CAAC,EAAE,mBAAmB,GAC1B,aAAa,CAEf"}