@sparkleideas/plugins 3.0.0-alpha.8

package/examples/plugin-creator/plugin-creator.test.ts

@@ -0,0 +1,312 @@
+/**
+ * Plugin Creator Tests
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  pluginCreatorPlugin,
+  generatePlugin,
+  generateToolCode,
+  generateHookCode,
+  generateWorkerCode,
+  generateAgentTypeCode,
+  PLUGIN_TEMPLATES,
+  type CreatePluginOptions,
+} from './index.js';
+import { HookEvent } from '../../src/types/index.js';
+
+describe('Plugin Creator Plugin', () => {
+  describe('pluginCreatorPlugin', () => {
+    it('should have correct metadata', () => {
+      expect(pluginCreatorPlugin.metadata.name).toBe('plugin-creator');
+      expect(pluginCreatorPlugin.metadata.version).toBe('1.0.0');
+      expect(pluginCreatorPlugin.metadata.tags).toContain('meta');
+    });
+
+    it('should register MCP tools', () => {
+      const tools = pluginCreatorPlugin.registerMCPTools?.() ?? [];
+      expect(tools.length).toBeGreaterThan(0);
+
+      const toolNames = tools.map(t => t.name);
+      expect(toolNames).toContain('create-plugin');
+      expect(toolNames).toContain('list-plugin-templates');
+      expect(toolNames).toContain('generate-tool');
+      expect(toolNames).toContain('generate-hook');
+      expect(toolNames).toContain('generate-worker');
+    });
+
+    it('should register hooks', () => {
+      const hooks = pluginCreatorPlugin.registerHooks?.() ?? [];
+      expect(hooks.length).toBeGreaterThan(0);
+      expect(hooks[0].name).toBe('plugin-creator-logger');
+    });
+
+    it('should register workers', () => {
+      const workers = pluginCreatorPlugin.registerWorkers?.() ?? [];
+      expect(workers.length).toBeGreaterThan(0);
+      expect(workers[0].name).toBe('plugin-code-generator');
+    });
+  });
+
+  describe('PLUGIN_TEMPLATES', () => {
+    it('should have all expected templates', () => {
+      const templateNames = Object.keys(PLUGIN_TEMPLATES);
+      expect(templateNames).toContain('minimal');
+      expect(templateNames).toContain('tool-plugin');
+      expect(templateNames).toContain('hooks-plugin');
+      expect(templateNames).toContain('worker-plugin');
+      expect(templateNames).toContain('swarm-plugin');
+      expect(templateNames).toContain('full-featured');
+      expect(templateNames).toContain('security-focused');
+    });
+
+    it('should have valid template structures', () => {
+      for (const [name, template] of Object.entries(PLUGIN_TEMPLATES)) {
+        expect(template.name).toBeDefined();
+        expect(template.description).toBeDefined();
+        expect(template.category).toMatch(/^(tools|hooks|workers|swarm|full)$/);
+        expect(Array.isArray(template.features)).toBe(true);
+      }
+    });
+  });
+
+  describe('generatePlugin', () => {
+    it('should generate a minimal plugin', () => {
+      const result = generatePlugin({
+        name: 'test-plugin',
+        version: '1.0.0',
+      });
+
+      expect(result.plugin).toBeDefined();
+      expect(result.metadata.name).toBe('test-plugin');
+      expect(result.metadata.version).toBe('1.0.0');
+      expect(result.code).toContain("PluginBuilder('test-plugin'");
+    });
+
+    it('should generate a plugin with tools', () => {
+      const result = generatePlugin({
+        name: 'tools-test',
+        features: { tools: true },
+        toolNames: ['my-tool', 'another-tool'],
+      });
+
+      const tools = result.plugin.registerMCPTools?.() ?? [];
+      expect(tools.length).toBe(2);
+      expect(tools[0].name).toBe('my-tool');
+      expect(tools[1].name).toBe('another-tool');
+      expect(result.code).toContain('MCPToolBuilder');
+    });
+
+    it('should generate a plugin with hooks', () => {
+      const result = generatePlugin({
+        name: 'hooks-test',
+        features: { hooks: true },
+        hookEvents: [HookEvent.SessionStart, HookEvent.PostTaskComplete],
+      });
+
+      const hooks = result.plugin.registerHooks?.() ?? [];
+      expect(hooks.length).toBe(2);
+      expect(result.code).toContain('HookBuilder');
+    });
+
+    it('should generate a plugin with workers', () => {
+      const result = generatePlugin({
+        name: 'workers-test',
+        features: { workers: true },
+        workerTypes: ['coder', 'reviewer'],
+      });
+
+      const workers = result.plugin.registerWorkers?.() ?? [];
+      expect(workers.length).toBe(2);
+      expect(result.code).toContain('WorkerFactory');
+    });
+
+    it('should generate a plugin with swarm capabilities', () => {
+      const result = generatePlugin({
+        name: 'swarm-test',
+        features: { swarm: true },
+        agentTypes: ['coordinator', 'worker-agent'],
+      });
+
+      const agents = result.plugin.registerAgentTypes?.() ?? [];
+      expect(agents.length).toBe(2);
+      expect(result.code).toContain('AgentTypeDefinition');
+    });
+
+    it('should apply template features', () => {
+      const result = generatePlugin({
+        name: 'full-test',
+        template: 'full-featured',
+      });
+
+      const tools = result.plugin.registerMCPTools?.() ?? [];
+      const hooks = result.plugin.registerHooks?.() ?? [];
+      const workers = result.plugin.registerWorkers?.() ?? [];
+      const agents = result.plugin.registerAgentTypes?.() ?? [];
+
+      expect(tools.length).toBeGreaterThan(0);
+      expect(hooks.length).toBeGreaterThan(0);
+      expect(workers.length).toBeGreaterThan(0);
+      expect(agents.length).toBeGreaterThan(0);
+    });
+
+    it('should reject invalid plugin names', () => {
+      expect(() => generatePlugin({ name: 'Invalid Name' })).toThrow();
+      expect(() => generatePlugin({ name: '123-start' })).toThrow();
+      expect(() => generatePlugin({ name: 'ab' })).toThrow(); // Too short
+    });
+  });
+
+  describe('generateToolCode', () => {
+    it('should generate valid tool definition', () => {
+      const { definition, code } = generateToolCode('my-tool');
+
+      expect(definition.name).toBe('my-tool');
+      expect(definition.handler).toBeDefined();
+      expect(code).toContain('MCPToolBuilder');
+      expect(code).toContain('my-tool');
+    });
+
+    it('should sanitize invalid tool names', () => {
+      const { definition } = generateToolCode('Invalid Tool Name!');
+      expect(definition.name).toBe('custom-tool');
+    });
+
+    it('should create working handler', async () => {
+      const { definition } = generateToolCode('test-tool');
+      const result = await definition.handler({ input: 'test' });
+
+      expect(result.content).toBeDefined();
+      expect(result.content[0].type).toBe('text');
+      expect(result.content[0].text).toContain('test-tool');
+    });
+  });
+
+  describe('generateHookCode', () => {
+    it('should generate valid hook definition', () => {
+      const { definition, code } = generateHookCode(HookEvent.SessionStart);
+
+      expect(definition.event).toBe(HookEvent.SessionStart);
+      expect(definition.handler).toBeDefined();
+      expect(code).toContain('HookBuilder');
+      expect(code).toContain('SessionStart');
+    });
+
+    it('should create working handler', async () => {
+      const { definition } = generateHookCode(HookEvent.PostTaskComplete);
+      const result = await definition.handler({
+        event: HookEvent.PostTaskComplete,
+        data: { taskId: '123' },
+        timestamp: new Date(),
+      });
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('generateWorkerCode', () => {
+    it('should generate valid worker definitions for known types', () => {
+      const types = ['coder', 'reviewer', 'tester', 'researcher', 'planner', 'coordinator', 'security', 'performance'];
+
+      for (const type of types) {
+        const { definition, code } = generateWorkerCode(type);
+
+        expect(definition.type).toBe(type);
+        expect(definition.name).toBe(`${type}-worker`);
+        expect(definition.capabilities.length).toBeGreaterThan(0);
+        expect(code).toContain('WorkerFactory');
+      }
+    });
+
+    it('should fallback to specialized for unknown types', () => {
+      const { definition, code } = generateWorkerCode('custom-type');
+
+      expect(definition.type).toBe('specialized');
+      expect(code).toContain('createSpecialized');
+    });
+  });
+
+  describe('generateAgentTypeCode', () => {
+    it('should generate valid agent type definition', () => {
+      const { definition, code } = generateAgentTypeCode('coordinator');
+
+      expect(definition.type).toBe('coordinator');
+      expect(definition.name).toBe('coordinator Agent');
+      expect(definition.model).toBe('claude-sonnet-4-20250514');
+      expect(code).toContain('AgentTypeDefinition');
+    });
+
+    it('should sanitize invalid agent type names', () => {
+      const { definition } = generateAgentTypeCode('Invalid Agent!');
+      expect(definition.type).toBe('custom-agent');
+    });
+  });
+});
+
+describe('MCP Tool Handlers', () => {
+  it('create-plugin tool should work', async () => {
+    const tools = pluginCreatorPlugin.registerMCPTools?.() ?? [];
+    const createTool = tools.find(t => t.name === 'create-plugin');
+
+    expect(createTool).toBeDefined();
+
+    const result = await createTool!.handler({
+      name: 'test-created-plugin',
+      version: '1.0.0',
+      template: 'tool-plugin',
+    });
+
+    expect(result.content[0].text).toContain('test-created-plugin');
+    expect(result.content[0].text).toContain('created successfully');
+  });
+
+  it('list-plugin-templates tool should work', async () => {
+    const tools = pluginCreatorPlugin.registerMCPTools?.() ?? [];
+    const listTool = tools.find(t => t.name === 'list-plugin-templates');
+
+    expect(listTool).toBeDefined();
+
+    const result = await listTool!.handler({});
+
+    expect(result.content[0].text).toContain('Available Plugin Templates');
+    expect(result.content[0].text).toContain('minimal');
+    expect(result.content[0].text).toContain('full-featured');
+  });
+
+  it('generate-tool tool should work', async () => {
+    const tools = pluginCreatorPlugin.registerMCPTools?.() ?? [];
+    const genTool = tools.find(t => t.name === 'generate-tool');
+
+    expect(genTool).toBeDefined();
+
+    const result = await genTool!.handler({ name: 'my-custom-tool' });
+
+    expect(result.content[0].text).toContain('Generated Tool');
+    expect(result.content[0].text).toContain('my-custom-tool');
+    expect(result.content[0].text).toContain('MCPToolBuilder');
+  });
+
+  it('generate-hook tool should work', async () => {
+    const tools = pluginCreatorPlugin.registerMCPTools?.() ?? [];
+    const genHook = tools.find(t => t.name === 'generate-hook');
+
+    expect(genHook).toBeDefined();
+
+    const result = await genHook!.handler({ event: HookEvent.SessionStart });
+
+    expect(result.content[0].text).toContain('Generated Hook');
+    expect(result.content[0].text).toContain('HookBuilder');
+  });
+
+  it('generate-worker tool should work', async () => {
+    const tools = pluginCreatorPlugin.registerMCPTools?.() ?? [];
+    const genWorker = tools.find(t => t.name === 'generate-worker');
+
+    expect(genWorker).toBeDefined();
+
+    const result = await genWorker!.handler({ type: 'coder' });
+
+    expect(result.content[0].text).toContain('Generated Worker');
+    expect(result.content[0].text).toContain('WorkerFactory');
+  });
+});

package/examples/ruvector/README.md

@@ -0,0 +1,288 @@
+# RuVector PostgreSQL Bridge Examples
+
+Comprehensive examples demonstrating the RuVector PostgreSQL Bridge plugin features.
+
+## Prerequisites
+
+- Node.js 18+
+- Docker and Docker Compose
+- TypeScript / ts-node
+
+## Quick Start
+
+### 1. Start PostgreSQL with pgvector
+
+```bash
+cd examples/ruvector
+docker compose up -d
+```
+
+This starts:
+- PostgreSQL 16 with pgvector extension on port 5432
+- Adminer (database UI) on port 8080
+
+### 2. Install Dependencies
+
+```bash
+# From the plugins root directory
+npm install
+npm run build
+```
+
+### 3. Run Examples
+
+```bash
+# Basic vector operations
+npx ts-node examples/ruvector/basic-usage.ts
+
+# Semantic code search
+npx ts-node examples/ruvector/semantic-search.ts
+
+# Attention mechanisms
+npx ts-node examples/ruvector/attention-patterns.ts
+
+# Graph neural networks
+npx ts-node examples/ruvector/gnn-analysis.ts
+
+# Hyperbolic embeddings
+npx ts-node examples/ruvector/hyperbolic-hierarchies.ts
+
+# Self-learning optimization
+npx ts-node examples/ruvector/self-learning.ts
+
+# Large-scale streaming
+npx ts-node examples/ruvector/streaming-large-data.ts
+
+# Quantization methods
+npx ts-node examples/ruvector/quantization.ts
+
+# Transaction patterns
+npx ts-node examples/ruvector/transactions.ts
+```
+
+## Examples Overview
+
+### 1. basic-usage.ts
+
+Getting started with RuVector PostgreSQL Bridge:
+- Connecting to PostgreSQL
+- Creating collections with HNSW indexes
+- Inserting and searching vectors
+- Batch operations
+- Update and delete operations
+
+**Expected output:**
+```
+RuVector PostgreSQL Bridge - Basic Usage Example
+================================================
+
+1. Connecting to PostgreSQL...
+   Connected successfully!
+
+2. Creating collection "documents"...
+   Collection created!
+
+3. Inserting vectors...
+   Inserted: doc-1
+   ...
+```
+
+### 2. semantic-search.ts
+
+Semantic code search implementation:
+- Embedding code snippets
+- Natural language queries
+- Hybrid search (semantic + keyword)
+- Relevance feedback / re-ranking
+
+**Key concepts:**
+- Code embeddings capture semantic meaning
+- Natural language queries find relevant code
+- Hybrid scoring combines multiple signals
+
+### 3. attention-patterns.ts
+
+Using attention mechanisms:
+- Multi-head attention
+- Self-attention
+- Cross-attention (encoder-decoder)
+- Causal attention (autoregressive)
+- Flash attention simulation
+- KV cache for inference
+
+**Key concepts:**
+- Different attention patterns for different use cases
+- Memory and compute optimizations
+- SQL generation for PostgreSQL execution
+
+### 4. gnn-analysis.ts
+
+Graph Neural Network analysis:
+- Building code dependency graphs
+- GCN (Graph Convolutional Network)
+- GAT (Graph Attention Network)
+- GraphSAGE for inductive learning
+- Finding structurally similar modules
+
+**Key concepts:**
+- Code structure as a graph
+- Learning from dependencies
+- Structural similarity detection
+
+### 5. hyperbolic-hierarchies.ts
+
+Hyperbolic embeddings for hierarchies:
+- File tree embeddings
+- Class inheritance hierarchies
+- Poincare ball model
+- Hierarchy-aware distances
+
+**Key concepts:**
+- Hyperbolic space captures hierarchies better
+- Nodes closer to origin = higher in hierarchy
+- Distance reflects tree structure
+
+### 6. self-learning.ts
+
+Self-optimization features:
+- Enabling the learning loop
+- Query pattern recognition
+- Auto-tuning HNSW parameters
+- Anomaly detection
+- EWC++ for preventing forgetting
+
+**Key concepts:**
+- Continuous learning from query patterns
+- Automatic index optimization
+- Pattern-based query prediction
+
+### 7. streaming-large-data.ts
+
+Handling large datasets:
+- Streaming millions of vectors
+- Backpressure handling
+- Progress monitoring
+- Memory-efficient processing
+
+**Key concepts:**
+- Async generators for streaming
+- Semaphore-based backpressure
+- Concurrent batch processing
+
+### 8. quantization.ts
+
+Memory optimization:
+- Int8 scalar quantization (4x compression)
+- Int4 scalar quantization (8x compression)
+- Binary quantization (32x compression)
+- Product Quantization (PQ)
+- Recall vs compression trade-offs
+
+**Key concepts:**
+- Quantization reduces memory significantly
+- Trade-off between compression and recall
+- Different methods for different use cases
+
+### 9. transactions.ts
+
+ACID operations:
+- Multi-vector atomic updates
+- Savepoint usage
+- Error recovery patterns
+- Optimistic locking
+
+**Key concepts:**
+- Transactions ensure consistency
+- Savepoints for partial rollbacks
+- Retry with exponential backoff
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# PostgreSQL connection
+export POSTGRES_HOST=localhost
+export POSTGRES_PORT=5432
+export POSTGRES_DB=vectors
+export POSTGRES_USER=postgres
+export POSTGRES_PASSWORD=postgres
+```
+
+### Docker Compose Services
+
+| Service | Port | Description |
+|---------|------|-------------|
+| postgres | 5432 | PostgreSQL 16 with pgvector |
+| adminer | 8080 | Database management UI |
+
+Access Adminer at http://localhost:8080:
+- System: PostgreSQL
+- Server: postgres
+- Username: postgres
+- Password: postgres
+- Database: vectors
+
+## Troubleshooting
+
+### Connection Refused
+
+Ensure PostgreSQL is running:
+```bash
+docker compose ps
+docker compose logs postgres
+```
+
+### Extension Not Found
+
+The pgvector extension should be auto-created. Verify:
+```sql
+SELECT * FROM pg_extension WHERE extname = 'vector';
+```
+
+### Out of Memory
+
+For large datasets, adjust PostgreSQL memory settings in docker-compose.yml:
+```yaml
+command: >
+  postgres
+  -c shared_buffers=512MB
+  -c work_mem=32MB
+```
+
+### Slow Searches
+
+Ensure HNSW index exists:
+```sql
+SELECT indexname FROM pg_indexes WHERE tablename = 'your_table';
+```
+
+Tune search parameters:
+```sql
+SET hnsw.ef_search = 100;  -- Increase for better recall
+```
+
+## Performance Tips
+
+1. **Batch inserts** for bulk loading (1000+ vectors at a time)
+2. **Use HNSW indexes** for approximate nearest neighbor search
+3. **Tune ef_search** based on recall requirements
+4. **Consider quantization** for large datasets
+5. **Use connection pooling** for concurrent access
+
+## Cleanup
+
+Stop and remove containers:
+```bash
+docker compose down
+
+# Remove data volumes too:
+docker compose down -v
+```
+
+## Resources
+
+- [pgvector Documentation](https://github.com/pgvector/pgvector)
+- [RuVector Plugin Documentation](../../src/integrations/ruvector/README.md)
+- [HNSW Algorithm Paper](https://arxiv.org/abs/1603.09320)
+- [Poincare Embeddings Paper](https://arxiv.org/abs/1705.08039)