@claude-flow/shared 3.0.0-alpha.1

package/.agentic-flow/intelligence.json

@@ -0,0 +1,16 @@
+{
+  "patterns": {
+    "command:": {
+      "success": 0.1
+    }
+  },
+  "sequences": {},
+  "memories": [],
+  "dirPatterns": {},
+  "errorPatterns": [],
+  "metrics": {
+    "totalRoutes": 1,
+    "successfulRoutes": 1,
+    "routingHistory": []
+  }
+}

package/README.md

@@ -0,0 +1,323 @@
+# @claude-flow/shared
+
+[![npm version](https://img.shields.io/npm/v/@claude-flow/shared.svg)](https://www.npmjs.com/package/@claude-flow/shared)
+[![npm downloads](https://img.shields.io/npm/dm/@claude-flow/shared.svg)](https://www.npmjs.com/package/@claude-flow/shared)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![Core](https://img.shields.io/badge/Module-Core-blue.svg)](https://github.com/ruvnet/claude-flow)
+
+> Shared utilities, types, and core infrastructure for Claude Flow V3 - the foundation module used by all other @claude-flow packages.
+
+## Features
+
+- **Core Types** - Agent, Task, Memory, MCP, and Swarm type definitions
+- **Core Interfaces** - Agent, Task, Memory, Event, and Coordinator interfaces
+- **Configuration** - Schema validation, loading, and default values
+- **Event System** - Event bus, coordinator, and handler utilities
+- **Hooks System** - Pre/post execution hooks for extensibility
+- **MCP Infrastructure** - Server, transport, connection pool, and tool registry
+- **Health Monitoring** - Health checks and monitoring utilities
+
+## Installation
+
+```bash
+npm install @claude-flow/shared
+```
+
+## Quick Start
+
+```typescript
+import {
+  AgentState,
+  TaskDefinition,
+  MemoryEntry,
+  EventBus,
+  ConfigLoader
+} from '@claude-flow/shared';
+
+// Use shared types
+const agent: AgentState = {
+  id: { id: 'agent-1', swarmId: 'swarm-1', type: 'coder' },
+  name: 'Code Agent',
+  type: 'coder',
+  status: 'idle'
+};
+
+// Use configuration
+const config = await ConfigLoader.load('./config.json');
+
+// Use event system
+const eventBus = new EventBus();
+eventBus.on('task.completed', (event) => {
+  console.log(`Task ${event.taskId} completed`);
+});
+```
+
+## Package Exports
+
+```typescript
+// Main entry (recommended - includes all modules)
+import { ... } from '@claude-flow/shared';
+
+// Submodule exports (for tree-shaking or specific imports)
+import { ... } from '@claude-flow/shared/types';      // Type definitions
+import { ... } from '@claude-flow/shared/core';       // Config, interfaces, orchestrator
+import { ... } from '@claude-flow/shared/events';     // Event sourcing (ADR-007)
+import { ... } from '@claude-flow/shared/hooks';      // Hooks system
+import { ... } from '@claude-flow/shared/mcp';        // MCP server infrastructure
+import { ... } from '@claude-flow/shared/security';   // Security utilities
+import { ... } from '@claude-flow/shared/resilience'; // Retry, circuit breaker, rate limiter
+```
+
+## API Reference
+
+### Types
+
+```typescript
+import type {
+  // Agent types
+  AgentId,
+  AgentState,
+  AgentType,
+  AgentStatus,
+  AgentCapabilities,
+  AgentMetrics,
+
+  // Task types
+  TaskId,
+  TaskDefinition,
+  TaskType,
+  TaskStatus,
+  TaskPriority,
+
+  // Memory types
+  MemoryEntry,
+  MemoryType,
+  SearchResult,
+
+  // Swarm types
+  SwarmId,
+  SwarmStatus,
+  SwarmEvent,
+  CoordinatorConfig,
+
+  // MCP types
+  MCPTool,
+  MCPRequest,
+  MCPResponse
+} from '@claude-flow/shared/types';
+```
+
+### Core Interfaces
+
+```typescript
+import type {
+  IAgent,
+  ITask,
+  IMemory,
+  ICoordinator,
+  IEventHandler
+} from '@claude-flow/shared/core';
+
+// Agent interface
+interface IAgent {
+  getId(): AgentId;
+  getState(): AgentState;
+  execute(task: TaskDefinition): Promise<TaskResult>;
+  handleMessage(message: Message): Promise<void>;
+}
+
+// Memory interface
+interface IMemory {
+  store(entry: MemoryEntry): Promise<string>;
+  retrieve(id: string): Promise<MemoryEntry | null>;
+  search(query: SearchQuery): Promise<SearchResult[]>;
+  delete(id: string): Promise<boolean>;
+}
+
+// Coordinator interface
+interface ICoordinator {
+  initialize(): Promise<void>;
+  shutdown(): Promise<void>;
+  registerAgent(agent: IAgent): Promise<string>;
+  submitTask(task: TaskDefinition): Promise<string>;
+}
+```
+
+### Configuration
+
+```typescript
+import {
+  ConfigLoader,
+  ConfigValidator,
+  defaultConfig,
+  ConfigSchema
+} from '@claude-flow/shared/core';
+
+// Load configuration
+const config = await ConfigLoader.load('./config.json');
+const config2 = await ConfigLoader.loadFromEnv();
+
+// Validate configuration
+const errors = ConfigValidator.validate(config);
+if (errors.length > 0) {
+  console.error('Invalid config:', errors);
+}
+
+// Default configuration
+const defaults = defaultConfig();
+```
+
+### Event System
+
+```typescript
+import { EventBus, EventCoordinator } from '@claude-flow/shared/events';
+
+const eventBus = new EventBus();
+
+// Subscribe to events
+eventBus.on('agent.joined', (event) => {
+  console.log(`Agent ${event.agentId} joined`);
+});
+
+eventBus.on('task.*', (event) => {
+  console.log(`Task event: ${event.type}`);
+});
+
+// Emit events
+eventBus.emit({
+  type: 'task.completed',
+  taskId: 'task-1',
+  result: { success: true }
+});
+
+// Event coordinator for complex workflows
+const coordinator = new EventCoordinator();
+coordinator.orchestrate([
+  { event: 'step1.done', handler: () => startStep2() },
+  { event: 'step2.done', handler: () => startStep3() }
+]);
+```
+
+### Hooks System
+
+```typescript
+import { HooksManager, Hook } from '@claude-flow/shared/hooks';
+
+const hooks = new HooksManager();
+
+// Register pre-execution hook
+hooks.register('pre:task', async (context) => {
+  console.log(`Starting task: ${context.taskId}`);
+  return { ...context, startTime: Date.now() };
+});
+
+// Register post-execution hook
+hooks.register('post:task', async (context, result) => {
+  const duration = Date.now() - context.startTime;
+  console.log(`Task completed in ${duration}ms`);
+});
+
+// Execute with hooks
+const result = await hooks.execute('task', context, async (ctx) => {
+  return await runTask(ctx);
+});
+```
+
+### MCP Infrastructure
+
+```typescript
+import {
+  createMCPServer,
+  createToolRegistry,
+  createConnectionPool,
+  createSessionManager,
+  defineTool,
+  quickStart,
+} from '@claude-flow/shared/mcp';
+
+// Quick start - simplest way to create an MCP server
+const server = await quickStart({
+  transport: 'stdio',
+  name: 'My MCP Server',
+});
+
+// Tool registry
+const registry = createToolRegistry();
+registry.register(defineTool({
+  name: 'swarm_init',
+  description: 'Initialize a swarm',
+  inputSchema: { type: 'object', properties: { topology: { type: 'string' } } },
+  handler: async (params) => ({ result: 'initialized' }),
+}));
+
+// Connection pool
+const pool = createConnectionPool({
+  maxConnections: 10,
+  acquireTimeoutMs: 30000,
+});
+
+// Session manager
+const sessions = createSessionManager({ timeoutMs: 3600000 });
+const session = await sessions.create({ clientInfo: { name: 'client' } });
+```
+
+### Health Monitor
+
+```typescript
+import { HealthMonitor, HealthCheck } from '@claude-flow/shared/core';
+
+const monitor = new HealthMonitor();
+
+// Register health checks
+monitor.register('database', async () => {
+  const connected = await db.ping();
+  return { healthy: connected, latency: pingTime };
+});
+
+monitor.register('memory', async () => {
+  const usage = process.memoryUsage();
+  return { healthy: usage.heapUsed < MAX_HEAP, usage };
+});
+
+// Run health checks
+const report = await monitor.check();
+// { overall: 'healthy', checks: { database: {...}, memory: {...} } }
+```
+
+## TypeScript Types
+
+All types are fully exported and documented:
+
+```typescript
+// Re-export all types
+export * from './types/agent.types';
+export * from './types/task.types';
+export * from './types/memory.types';
+export * from './types/swarm.types';
+export * from './types/mcp.types';
+```
+
+## Dependencies
+
+- `sql.js` - SQLite WASM for cross-platform persistence
+
+## Used By
+
+This package is a dependency of all other @claude-flow modules:
+
+- [@claude-flow/cli](../cli) - CLI module
+- [@claude-flow/security](../security) - Security & validation
+- [@claude-flow/memory](../memory) - AgentDB & HNSW indexing
+- [@claude-flow/neural](../neural) - SONA learning & RL algorithms
+- [@claude-flow/performance](../performance) - Benchmarking & optimization
+- [@claude-flow/swarm](../swarm) - 15-agent coordination
+- [@claude-flow/integration](../integration) - agentic-flow@alpha bridge
+- [@claude-flow/testing](../testing) - TDD framework & fixtures
+- [@claude-flow/deployment](../deployment) - Release management
+- [@claude-flow/embeddings](../embeddings) - Embedding service
+- [@claude-flow/hooks](../hooks) - Hooks system
+
+## License
+
+MIT

package/__tests__/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}

package/__tests__/coverage/block-navigation.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+var jumpToCode = (function init() {
+    // Classes of code we would like to highlight in the file view
+    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
+
+    // Elements to highlight in the file listing view
+    var fileListingElements = ['td.pct.low'];
+
+    // We don't want to select elements that are direct descendants of another match
+    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
+
+    // Selector that finds elements on the page to which we can jump
+    var selector =
+        fileListingElements.join(', ') +
+        ', ' +
+        notSelector +
+        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
+
+    // The NodeList of matching elements
+    var missingCoverageElements = document.querySelectorAll(selector);
+
+    var currentIndex;
+
+    function toggleClass(index) {
+        missingCoverageElements
+            .item(currentIndex)
+            .classList.remove('highlighted');
+        missingCoverageElements.item(index).classList.add('highlighted');
+    }
+
+    function makeCurrent(index) {
+        toggleClass(index);
+        currentIndex = index;
+        missingCoverageElements.item(index).scrollIntoView({
+            behavior: 'smooth',
+            block: 'center',
+            inline: 'center'
+        });
+    }
+
+    function goToPrevious() {
+        var nextIndex = 0;
+        if (typeof currentIndex !== 'number' || currentIndex === 0) {
+            nextIndex = missingCoverageElements.length - 1;
+        } else if (missingCoverageElements.length > 1) {
+            nextIndex = currentIndex - 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    function goToNext() {
+        var nextIndex = 0;
+
+        if (
+            typeof currentIndex === 'number' &&
+            currentIndex < missingCoverageElements.length - 1
+        ) {
+            nextIndex = currentIndex + 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    return function jump(event) {
+        if (
+            document.getElementById('fileSearch') === document.activeElement &&
+            document.activeElement != null
+        ) {
+            // if we're currently focused on the search input, we don't want to navigate
+            return;
+        }
+
+        switch (event.which) {
+            case 78: // n
+            case 74: // j
+                goToNext();
+                break;
+            case 66: // b
+            case 75: // k
+            case 80: // p
+                goToPrevious();
+                break;
+        }
+    };
+})();
+window.addEventListener('keydown', jumpToCode);