@ekkos/cli 0.2.0

package/templates/hooks-node/user-prompt-submit.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * ekkOS_ Hook: UserPromptSubmit (Claude Code) - CAPTURE + RETRIEVE + INJECT
+ * Node.js version - Works on Windows, macOS, Linux without bash dependencies
+ *
+ * ARCHITECTURE: Dumb Hook, Smart Backend
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
+
+const https = require('https');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Load state management
+const state = require('./lib/state');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ANSI Color Codes
+// ═══════════════════════════════════════════════════════════════════════════
+const CYAN = '\x1b[0;36m';
+const GREEN = '\x1b[0;32m';
+const YELLOW = '\x1b[1;33m';
+const MAGENTA = '\x1b[0;35m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HTTP Request Helper (uses built-in https module)
+// ═══════════════════════════════════════════════════════════════════════════
+function httpRequest(url, options, data) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const lib = urlObj.protocol === 'https:' ? https : http;
+    const timeout = options.timeout || 2000;
+
+    const req = lib.request({
+      hostname: urlObj.hostname,
+      port: urlObj.port || (urlObj.protocol === 'https:' ? 443 : 80),
+      path: urlObj.pathname + urlObj.search,
+      method: options.method || 'GET',
+      headers: options.headers || {},
+      timeout: timeout
+    }, (res) => {
+      let body = '';
+      res.on('data', chunk => body += chunk);
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(body));
+        } catch {
+          resolve({ raw: body });
+        }
+      });
+    });
+
+    req.on('error', (e) => resolve({ error: e.message }));
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ error: 'timeout' });
+    });
+
+    if (data) req.write(typeof data === 'string' ? data : JSON.stringify(data));
+    req.end();
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Load Auth Token - PORTABLE: Check 3 sources in priority order
+// ═══════════════════════════════════════════════════════════════════════════
+function loadAuthToken() {
+  const homeDir = os.homedir();
+  const ekkosConfig = path.join(homeDir, '.ekkos', 'config.json');
+  let authToken = '';
+  let userId = '';
+
+  // 1. First try ~/.ekkos/config.json (set by VS Code extension - most portable)
+  //    Prefer hookApiKey (scoped key for hooks) over apiKey (legacy)
+  if (fs.existsSync(ekkosConfig)) {
+    try {
+      const config = JSON.parse(fs.readFileSync(ekkosConfig, 'utf8'));
+      authToken = config.hookApiKey || config.apiKey || '';
+      userId = config.userId || '';
+    } catch {}
+  }
+
+  // 2. Then try project .env.local (for developers with service role key)
+  if (!authToken) {
+    const envLocal = path.join(state.PROJECT_ROOT, '.env.local');
+    if (fs.existsSync(envLocal)) {
+      try {
+        const content = fs.readFileSync(envLocal, 'utf8');
+        const match = content.match(/^SUPABASE_SECRET_KEY=(.+)$/m);
+        if (match) {
+          authToken = match[1].replace(/["']/g, '').trim();
+        }
+      } catch {}
+    }
+  }
+
+  // 3. Finally try environment variable
+  if (!authToken) {
+    authToken = process.env.SUPABASE_SECRET_KEY || '';
+  }
+
+  return { authToken, userId };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Main Hook Logic
+// ═══════════════════════════════════════════════════════════════════════════
+async function main() {
+  // Read JSON input from stdin
+  let inputData = '';
+  for await (const chunk of process.stdin) {
+    inputData += chunk;
+  }
+
+  let input;
+  try {
+    input = JSON.parse(inputData);
+  } catch {
+    process.exit(0);
+  }
+
+  const userQuery = input.query || input.message || input.prompt || '';
+  const sessionId = input.session_id || 'unknown';
+  const modelInfo = input.model || 'claude-sonnet-4-5';
+  const transcriptPath = input.transcript_path || '';
+
+  // Skip if empty
+  if (!userQuery) {
+    process.exit(0);
+  }
+
+  // Load auth
+  const { authToken, userId } = loadAuthToken();
+  const MEMORY_API_URL = 'https://mcp.ekkos.dev';
+
+  // Get current timestamp
+  const now = new Date();
+  const currentTime = now.toLocaleString('en-US', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: true,
+    timeZoneName: 'short'
+  });
+
+  // Visual header
+  console.log('');
+  console.log(`${CYAN}${BOLD}🧠 ekkOS Memory${RESET} ${DIM}| Claude Code (${modelInfo}) | ${currentTime}${RESET}`);
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // [ekkOS_CAPTURE] Capture the PREVIOUS exchange before processing new one
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (state.acquireLock(sessionId)) {
+    if (transcriptPath && fs.existsSync(transcriptPath)) {
+      try {
+        const transcriptContent = fs.readFileSync(transcriptPath, 'utf8');
+        const lines = transcriptContent.split('\n').filter(Boolean).map(l => {
+          try { return JSON.parse(l); } catch { return null; }
+        }).filter(Boolean);
+
+        // Get human messages
+        const humanMsgs = lines.filter(l => l.type === 'human');
+        const assistantMsgs = lines.filter(l => l.type === 'assistant');
+
+        // Get second-to-last human message (the previous query, not current)
+        const prevUser = humanMsgs.length > 1 ? humanMsgs[humanMsgs.length - 2]?.message : null;
+
+        // Get last assistant response
+        const lastAssistant = assistantMsgs[assistantMsgs.length - 1];
+        let prevAssistant = '';
+        if (lastAssistant?.message?.content) {
+          if (Array.isArray(lastAssistant.message.content)) {
+            prevAssistant = lastAssistant.message.content
+              .filter(c => c.type === 'text')
+              .map(c => c.text)
+              .join(' ');
+          } else {
+            prevAssistant = lastAssistant.message.content;
+          }
+        }
+
+        // Capture if we have both
+        if (prevUser && prevAssistant) {
+          const prevHash = state.generateTurnHash(prevUser, prevAssistant);
+
+          if (!state.wasTurnCaptured(sessionId, prevHash)) {
+            // Capture in background (don't wait)
+            httpRequest(`${MEMORY_API_URL}/api/v1/memory/capture`, {
+              method: 'POST',
+              headers: {
+                'Authorization': `Bearer ${authToken}`,
+                'Content-Type': 'application/json'
+              },
+              timeout: 5000
+            }, {
+              user_query: prevUser,
+              assistant_response: prevAssistant,
+              session_id: `claude-code-${sessionId}`,
+              metadata: {
+                source: 'claude-code-hook-node',
+                model_used: modelInfo,
+                captured_at: new Date().toISOString()
+              }
+            }).catch(() => {});
+
+            state.markTurnCaptured(sessionId, prevHash);
+            console.log(`${CYAN}   💾 Capture${RESET} ${DIM}saving previous turn${RESET}`);
+          }
+        }
+      } catch {}
+    }
+    state.releaseLock(sessionId);
+  }
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // [ekkOS_RETRIEVE] Single API call - backend handles ALL the work
+  // ═══════════════════════════════════════════════════════════════════════════
+  console.log(`${MAGENTA}   🔍 Retrieve${RESET} ${DIM}searching memory substrate...${RESET}`);
+
+  let apiResponse;
+  if (!authToken) {
+    console.log(`${DIM}   ⚠️  Retrieve${RESET} ${DIM}skipped (no auth)${RESET}`);
+    apiResponse = { error: 'no_auth', formatted_context: '', layers: { patterns: [], directives: [] } };
+  } else {
+    apiResponse = await httpRequest(`${MEMORY_API_URL}/api/v1/context/retrieve`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${authToken}`,
+        'Content-Type': 'application/json'
+      },
+      timeout: 1500
+    }, {
+      query: userQuery,
+      user_id: userId || 'system',
+      session_id: `claude-code-${sessionId}`,
+      max_per_layer: 5,
+      include_layers: ['working', 'episodic', 'semantic', 'patterns', 'procedural', 'collective', 'codebase', 'directives'],
+      metadata: {
+        source: 'claude-code-node',
+        model_used: modelInfo
+      }
+    });
+
+    if (!apiResponse.layers) {
+      apiResponse = { error: 'timeout', formatted_context: '', layers: { patterns: [], directives: [] } };
+    }
+  }
+
+  // Extract counts
+  const layers = apiResponse.layers || {};
+  const patternCount = (layers.patterns || []).length;
+  const directiveCount = (layers.directives || []).length;
+  const episodicCount = (layers.episodic || []).length;
+  const proceduralCount = (layers.procedural || []).length;
+  const codebaseCount = (layers.codebase || []).length;
+  const totalCount = patternCount + directiveCount + episodicCount + proceduralCount + codebaseCount;
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // [ekkOS_INJECT] Output the formatted context
+  // ═══════════════════════════════════════════════════════════════════════════
+  if (totalCount > 0) {
+    console.log(`${GREEN}   ✨ Inject${RESET}  ${GREEN}${totalCount}${RESET} ${DIM}memories loaded (${patternCount} patterns, ${directiveCount} directives)${RESET}`);
+    console.log('');
+
+    const formatted = apiResponse.formatted_context;
+    if (formatted) {
+      console.log(formatted);
+    } else {
+      // Fallback: structured output
+      if (patternCount > 0) {
+        console.log('## Pattern Memory (Layer 4) - Directive Compliant');
+        console.log('Proven solutions:');
+        for (const p of layers.patterns.slice(0, 5)) {
+          console.log(`${p.title || 'Untitled'}`);
+          console.log(`   Problem: ${(p.problem || 'N/A').substring(0, 200)}`);
+          console.log(`   Solution: ${(p.solution || 'N/A').substring(0, 300)}`);
+          console.log(`   Success Rate: ${p.success_rate || 0}%`);
+          console.log('');
+        }
+      }
+
+      if (directiveCount > 0) {
+        console.log('## Directive Memory (Layer 9) - HIGHEST PRIORITY');
+        console.log('User rules that MUST be followed:');
+        for (const d of layers.directives.slice(0, 5)) {
+          console.log(`   [${d.type || 'PREFER'}] ${d.rule || d.content || 'No rule'}`);
+        }
+        console.log('');
+      }
+
+      if (proceduralCount > 0) {
+        console.log('## Procedural Memory (Layer 5)');
+        console.log('Multi-step workflows:');
+        for (const p of layers.procedural.slice(0, 3)) {
+          console.log(`   • ${p.title || p.name || 'Workflow'}`);
+        }
+        console.log('');
+      }
+
+      if (episodicCount > 0) {
+        console.log('## Episodic Memory (Layer 2)');
+        console.log('Similar past conversations:');
+        for (const e of layers.episodic.slice(0, 3)) {
+          console.log(`   • ${(e.query_preview || e.problem || 'Previous session').substring(0, 100)}...`);
+        }
+        console.log('');
+      }
+
+      if (codebaseCount > 0) {
+        console.log('## Codebase Memory (Layer 8)');
+        console.log('Project-specific knowledge:');
+        for (const c of layers.codebase.slice(0, 3)) {
+          console.log(`   • ${c.file_path || c.title || 'Code pattern'}`);
+        }
+        console.log('');
+      }
+    }
+  } else {
+    console.log(`${DIM}   📭 Inject${RESET}  ${DIM}no matching patterns found${RESET}`);
+    console.log('');
+  }
+
+  // Save patterns for stop.js
+  state.savePatterns(sessionId, layers.patterns || [], modelInfo);
+
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/templates/plan-template.md

@@ -0,0 +1,306 @@
+# Implementation Plan: [Feature Name]
+
+## Overview
+**Technical implementation plan for [Feature Name] based on the specification.**
+
+## Architecture Overview
+
+### System Components
+- **Frontend**: React components and state management
+- **API Layer**: Next.js API routes and middleware
+- **AI Services**: AI provider integration and processing
+- **Database**: Supabase data storage and queries
+- **External APIs**: Third-party service integrations
+
+### Data Flow
+```
+User Input → Frontend → API Route → AI Processing → Database → Response
+```
+
+## Technical Stack
+
+### Frontend
+- **Framework**: Next.js 15.5.2 with React 19
+- **Styling**: Tailwind CSS
+- **State Management**: React hooks and context
+- **Type Safety**: TypeScript
+
+### Backend
+- **Runtime**: Node.js with Next.js API routes
+- **Database**: Supabase (PostgreSQL)
+- **AI Providers**: OpenAI, Gemini (Google AI)
+- **Authentication**: Supabase Auth (planned)
+
+### External Services
+- **YouTube API**: Content extraction
+- **AI APIs**: OpenAI, Google AI (Gemini)
+- **Content Processing**: Custom extraction services
+
+## Implementation Phases
+
+### Phase 1: Foundation Setup
+**Duration**: 1-2 days
+
+#### Tasks
+- [ ] **Database Schema**: Create/modify database tables
+- [ ] **API Contracts**: Define request/response interfaces
+- [ ] **Type Definitions**: Create TypeScript interfaces
+- [ ] **Environment Setup**: Configure required environment variables
+
+#### Deliverables
+- Database migration scripts
+- TypeScript interface definitions
+- API endpoint specifications
+- Environment configuration
+
+### Phase 2: Core Implementation
+**Duration**: 3-5 days
+
+#### Backend Implementation
+- [ ] **API Routes**: Implement Next.js API endpoints
+- [ ] **AI Integration**: Connect to AI providers
+- [ ] **Data Processing**: Implement content processing logic
+- [ ] **Error Handling**: Implement comprehensive error handling
+
+#### Frontend Implementation
+- [ ] **UI Components**: Create React components
+- [ ] **State Management**: Implement data flow
+- [ ] **User Interface**: Design and implement user interactions
+- [ ] **Responsive Design**: Ensure mobile compatibility
+
+#### Deliverables
+- Working API endpoints
+- Functional UI components
+- AI integration working
+- Basic error handling
+
+### Phase 3: Integration and Testing
+**Duration**: 2-3 days
+
+#### Integration Tasks
+- [ ] **End-to-End Testing**: Test complete user workflows
+- [ ] **AI Provider Testing**: Validate AI accuracy and performance
+- [ ] **Error Scenario Testing**: Test failure modes and recovery
+- [ ] **Performance Testing**: Validate response times and throughput
+
+#### Quality Assurance
+- [ ] **Code Review**: Review all implementation code
+- [ ] **Security Review**: Validate security measures
+- [ ] **Accessibility Review**: Ensure accessibility compliance
+- [ ] **Documentation**: Update technical documentation
+
+#### Deliverables
+- Fully tested feature
+- Performance benchmarks
+- Security validation
+- Updated documentation
+
+## Database Schema
+
+### New Tables
+```sql
+-- Example table for new feature
+CREATE TABLE feature_table (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  data JSONB NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+```
+
+### Modified Tables
+- **content_items**: Add new fields if needed
+- **users**: Add new fields if needed
+
+## API Design
+
+### New Endpoints
+- **POST /api/feature**: Create new feature item
+- **GET /api/feature**: List feature items
+- **PUT /api/feature/[id]**: Update feature item
+- **DELETE /api/feature/[id]**: Delete feature item
+
+### Request/Response Examples
+```typescript
+// POST /api/feature
+interface CreateFeatureRequest {
+  title: string;
+  content: string;
+  // ... other fields
+}
+
+interface CreateFeatureResponse {
+  id: string;
+  // ... response fields
+}
+```
+
+## AI Integration
+
+### AI Provider Selection
+- **Primary**: OpenAI (for main processing)
+- **Fallback**: Mock provider (for development)
+- **Future**: Anthropic (for additional capabilities)
+
+### AI Processing Pipeline
+1. **Content Analysis**: Analyze input content
+2. **Feature Extraction**: Extract relevant features
+3. **AI Processing**: Apply AI algorithms
+4. **Result Validation**: Validate AI outputs
+5. **Response Generation**: Format final response
+
+### Cost Considerations
+- **OpenAI API**: ~$0.01-0.10 per request
+- **Gemini API**: ~$0.005-0.05 per request
+- **Expected Volume**: 100-1000 requests/day
+- **Monthly Cost**: $10-100 estimated
+
+## Frontend Components
+
+### New Components
+- **FeatureForm**: Form for creating/editing features
+- **FeatureList**: List view of features
+- **FeatureDetail**: Detailed view of individual feature
+- **FeatureCard**: Card component for feature display
+
+### State Management
+- **Context**: FeatureContext for global state
+- **Hooks**: Custom hooks for data fetching
+- **Local State**: Component-level state management
+
+## Error Handling
+
+### Error Types
+- **Validation Errors**: Input validation failures
+- **AI Errors**: AI provider failures
+- **Network Errors**: API communication failures
+- **Database Errors**: Data persistence failures
+
+### Error Recovery
+- **Retry Logic**: Automatic retry for transient failures
+- **Fallback Strategies**: Alternative approaches when primary fails
+- **User Feedback**: Clear error messages and recovery options
+- **Logging**: Comprehensive error logging and monitoring
+
+## Performance Considerations
+
+### Optimization Strategies
+- **Caching**: Implement appropriate caching strategies
+- **Lazy Loading**: Load components and data on demand
+- **Debouncing**: Prevent excessive API calls
+- **Compression**: Compress API responses
+
+### Monitoring
+- **Response Times**: Track API response times
+- **Error Rates**: Monitor error frequencies
+- **AI Performance**: Track AI accuracy and costs
+- **User Metrics**: Monitor user engagement
+
+## Security Considerations
+
+### Authentication
+- **User Verification**: Verify user identity
+- **Session Management**: Manage user sessions
+- **Token Validation**: Validate authentication tokens
+
+### Authorization
+- **Access Control**: Control feature access
+- **Data Isolation**: Ensure user data isolation
+- **Permission Checks**: Validate user permissions
+
+### Data Protection
+- **Input Validation**: Validate all inputs
+- **Output Sanitization**: Sanitize outputs
+- **Privacy Compliance**: Ensure data privacy
+- **Audit Logging**: Log security-relevant events
+
+## Testing Strategy
+
+### Unit Testing
+- **Component Tests**: Test React components
+- **API Tests**: Test API endpoints
+- **Service Tests**: Test business logic
+- **AI Tests**: Test AI integration
+
+### Integration Testing
+- **End-to-End Tests**: Test complete workflows
+- **API Integration**: Test API interactions
+- **Database Integration**: Test data persistence
+- **External Service Integration**: Test third-party services
+
+### Performance Testing
+- **Load Testing**: Test under expected load
+- **Stress Testing**: Test under high load
+- **AI Performance**: Test AI response times
+- **Database Performance**: Test query performance
+
+## Deployment Plan
+
+### Environment Setup
+- **Development**: Local development environment
+- **Staging**: Pre-production testing environment
+- **Production**: Live production environment
+
+### Deployment Process
+1. **Code Review**: Review all changes
+2. **Testing**: Run comprehensive tests
+3. **Staging Deployment**: Deploy to staging
+4. **Production Deployment**: Deploy to production
+5. **Monitoring**: Monitor deployment health
+
+### Rollback Strategy
+- **Database Rollback**: Rollback database changes
+- **Code Rollback**: Rollback code changes
+- **Configuration Rollback**: Rollback configuration changes
+- **Monitoring**: Monitor rollback success
+
+## Success Metrics
+
+### Technical Metrics
+- **Response Time**: < 2 seconds for API calls
+- **Error Rate**: < 1% error rate
+- **Uptime**: > 99.9% uptime
+- **AI Accuracy**: > 90% accuracy
+
+### User Metrics
+- **Adoption Rate**: % of users using feature
+- **Satisfaction**: User satisfaction scores
+- **Engagement**: Feature usage frequency
+- **Retention**: User retention impact
+
+### Business Metrics
+- **Cost per Operation**: Cost efficiency
+- **Revenue Impact**: Revenue generation
+- **User Growth**: User acquisition impact
+- **Competitive Advantage**: Market positioning
+
+## Risk Mitigation
+
+### Technical Risks
+- **AI Provider Outage**: Implement fallback providers
+- **Database Issues**: Implement backup and recovery
+- **Performance Issues**: Implement monitoring and scaling
+- **Security Vulnerabilities**: Implement security reviews
+
+### Business Risks
+- **User Adoption**: Implement user feedback loops
+- **Cost Overruns**: Implement cost monitoring
+- **Competitive Pressure**: Implement rapid iteration
+- **Regulatory Issues**: Implement compliance monitoring
+
+## Future Enhancements
+
+### Planned Improvements
+- **Advanced AI Features**: Enhanced AI capabilities
+- **Mobile App**: Native mobile application
+- **API Expansion**: Additional API endpoints
+- **Integration**: Third-party integrations
+
+### Research Areas
+- **AI Optimization**: Improve AI accuracy and cost
+- **User Experience**: Enhance user interface
+- **Performance**: Optimize system performance
+- **Scalability**: Improve system scalability
+
+