telos-framework 0.1.0

package/lib/generators/tools-md-generator.js

@@ -0,0 +1,204 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function generateToolsMd(levelTools, projectScan, mcpServers, recommendations, outputPath) {
+  let content = `# Discovered Tools & Capabilities
+
+**Generated**: ${new Date().toISOString()}
+
+## Project Context
+
+- **Languages**: ${projectScan.languages.join(', ') || 'None detected'}
+- **Frameworks**: ${projectScan.frameworks.join(', ') || 'None detected'}
+- **Package Managers**: ${projectScan.packageManagers.join(', ') || 'None detected'}
+
+## MCP Servers
+
+${mcpServers.length > 0 ? mcpServers.map(s => `- **${s.name}**: \`${s.command}\``).join('\n') : 'No MCP servers detected'}
+
+## Tools by Agent Level
+
+`;
+
+  for (const [level, data] of Object.entries(levelTools)) {
+    content += `### ${level}: ${data.name}\n\n`;
+    
+    if (data.tools.length > 0) {
+      content += '**Available Tools**:\n\n';
+      for (const tool of data.tools) {
+        content += `- **${tool.name}** (${tool.category}): ${tool.capability}\n`;
+      }
+      content += '\n';
+    } else {
+      content += '*No tools detected for this level*\n\n';
+    }
+  }
+
+  if (recommendations.length > 0) {
+    content += `## Recommendations\n\n`;
+    for (const rec of recommendations) {
+      content += `- **${rec.level}** [${rec.priority}]: ${rec.message}\n`;
+    }
+    content += '\n';
+  }
+
+  content += `## Capability Matrix
+
+| Level | Agent | Detected Capabilities |
+|-------|-------|----------------------|
+`;
+
+  for (const [level, data] of Object.entries(levelTools)) {
+    const caps = data.tools.map(t => t.capability).join(', ') || 'None';
+    content += `| ${level} | ${data.name} | ${caps} |\n`;
+  }
+
+  content += `
+## Usage Instructions by Agent
+
+### L1: Syntax-Linter
+
+**Tools**: ${levelTools.L1.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Run linter before committing code
+2. Fix syntax and style violations automatically when possible
+3. Report unfixable issues for manual review
+
+**Example Commands**:
+- \`eslint --fix .\` - Auto-fix JavaScript/TypeScript issues
+- \`prettier --write .\` - Format code
+- \`ruff check .\` - Lint Python code
+
+### L2: Function-Author
+
+**Tools**: ${levelTools.L2.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Write tests first (TDD)
+2. Implement function to pass tests
+3. Verify with unit test suite
+4. Refactor while keeping tests green
+
+**Example Commands**:
+- \`vitest run\` - Run unit tests
+- \`jest --coverage\` - Run tests with coverage
+- \`npm test\` - Run test script
+
+### L3: Component-Architect
+
+**Tools**: ${levelTools.L3.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Design component interface
+2. Write component tests
+3. Implement component
+4. Verify integration with parent components
+
+**Example Commands**:
+- \`vitest --ui\` - Interactive test UI
+- \`jest --testPathPattern=components\` - Test components only
+
+### L4: Integration-Contractor
+
+**Tools**: ${levelTools.L4.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Define API contracts
+2. Write integration tests
+3. Implement API endpoints
+4. Verify contracts hold
+
+**Example Commands**:
+- \`curl -X POST http://localhost:3000/api/test\` - Manual API test
+- Check integration test suite
+
+### L5: Journey-Validator
+
+**Tools**: ${levelTools.L5.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Define user journeys
+2. Write E2E tests for critical paths
+3. Run tests in multiple browsers
+4. Verify complete user flows
+
+**Example Commands**:
+- \`playwright test\` - Run E2E tests
+- \`cypress run\` - Run Cypress tests
+- \`playwright test --ui\` - Debug tests interactively
+
+### L6: UX-Simulator
+
+**Tools**: ${levelTools.L6.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Create user personas
+2. Simulate persona interactions
+3. Test accessibility
+4. Verify UX principles
+
+**Example Commands**:
+- Use browser MCP for automation
+- Manual testing with personas
+
+### L7: Insight-Synthesizer
+
+**Tools**: ${levelTools.L7.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Collect analytics data
+2. Gather user feedback
+3. Synthesize insights
+4. Report findings to higher levels
+
+**Example Commands**:
+- Query analytics MCP servers
+- Review user feedback channels
+
+### L8: Market-Analyst
+
+**Tools**: ${levelTools.L8.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Define business KPIs
+2. Track metrics
+3. Analyze performance
+4. Report to Telos-Guardian
+
+**Example Commands**:
+- Query business metrics databases
+- Generate reports
+
+### L9: Telos-Guardian
+
+**Tools**: ${levelTools.L9.tools.map(t => t.name).join(', ') || 'None'}
+
+**Workflow**:
+1. Review alignment with Telos
+2. Validate strategic decisions
+3. Guide overall direction
+4. Maintain purpose coherence
+
+**Example Commands**:
+- Review project documentation
+- Validate specs against Telos
+
+## Re-Discovery
+
+To update this file after adding tools or MCP servers, run:
+
+\`\`\`bash
+telos rediscover
+\`\`\`
+
+This will re-scan your project and update agent configurations accordingly.
+`;
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, content, 'utf8');
+  
+  return outputPath;
+}
+
+module.exports = { generateToolsMd };

package/lib/integration/capability-abstraction.js

@@ -0,0 +1,162 @@
+const CAPABILITY_DEFINITIONS = {
+  'static-analysis': {
+    description: 'Analyze code for syntax errors, style violations, and potential bugs',
+    tools: ['eslint', 'ruff', 'pylint', 'rubocop', 'golint'],
+    fallback: 'manual-code-review'
+  },
+  'file-operations': {
+    description: 'Read, write, and manipulate files',
+    tools: ['filesystem-mcp', 'node-fs'],
+    fallback: 'direct-file-access'
+  },
+  'unit-testing': {
+    description: 'Execute and validate unit tests',
+    tools: ['vitest', 'jest', 'pytest', 'mocha', 'jasmine'],
+    fallback: 'manual-testing'
+  },
+  'component-testing': {
+    description: 'Test UI components in isolation',
+    tools: ['vitest', 'jest', 'testing-library', 'enzyme'],
+    fallback: 'unit-testing'
+  },
+  'api-testing': {
+    description: 'Test HTTP APIs and external integrations',
+    tools: ['supertest', 'requests', 'axios', 'fetch-mcp'],
+    fallback: 'manual-api-calls'
+  },
+  'journey-validation': {
+    description: 'End-to-end user journey testing',
+    tools: ['playwright', 'cypress', 'selenium'],
+    fallback: 'manual-ux-testing'
+  },
+  'ux-testing': {
+    description: 'User experience and accessibility testing',
+    tools: ['playwright', 'browser-mcp', 'axe-core'],
+    fallback: 'manual-ux-review'
+  },
+  'analytics': {
+    description: 'Collect and analyze user behavior metrics',
+    tools: ['analytics-mcp', 'posthog', 'mixpanel'],
+    fallback: 'log-analysis'
+  },
+  'business-metrics': {
+    description: 'Track KPIs and business performance',
+    tools: ['analytics-mcp', 'database-mcp'],
+    fallback: 'manual-reporting'
+  },
+  'version-control': {
+    description: 'Interact with Git and version control systems',
+    tools: ['github-mcp', 'git'],
+    fallback: 'manual-git'
+  },
+  'browser-automation': {
+    description: 'Automate browser interactions',
+    tools: ['playwright', 'browser-mcp', 'chrome-mcp'],
+    fallback: 'manual-browser-testing'
+  },
+  'database-access': {
+    description: 'Query and manipulate databases',
+    tools: ['postgres-mcp', 'mysql-mcp', 'database-mcp'],
+    fallback: 'manual-db-queries'
+  },
+  'web-research': {
+    description: 'Fetch and analyze web content',
+    tools: ['fetch-mcp', 'brave-search-mcp', 'http-client'],
+    fallback: 'manual-web-search'
+  },
+  'user-feedback': {
+    description: 'Collect and process user feedback',
+    tools: ['slack-mcp', 'email-mcp'],
+    fallback: 'manual-feedback-review'
+  }
+};
+
+class CapabilityManager {
+  constructor(availableTools = []) {
+    this.availableTools = availableTools;
+    this.capabilityMap = this.buildCapabilityMap();
+  }
+
+  buildCapabilityMap() {
+    const map = {};
+    
+    for (const [capability, definition] of Object.entries(CAPABILITY_DEFINITIONS)) {
+      const matchingTools = this.availableTools.filter(tool => {
+        const toolName = tool.name.toLowerCase();
+        return definition.tools.some(defTool => toolName.includes(defTool.toLowerCase()));
+      });
+
+      map[capability] = {
+        ...definition,
+        available: matchingTools.length > 0,
+        tools: matchingTools,
+        fallback: definition.fallback
+      };
+    }
+
+    return map;
+  }
+
+  hasCapability(capability) {
+    return this.capabilityMap[capability]?.available || false;
+  }
+
+  getToolsForCapability(capability) {
+    return this.capabilityMap[capability]?.tools || [];
+  }
+
+  getFallbackForCapability(capability) {
+    return this.capabilityMap[capability]?.fallback || 'manual-implementation';
+  }
+
+  getCapabilitiesForLevel(level) {
+    const levelCapabilities = {
+      L1: ['static-analysis', 'file-operations'],
+      L2: ['unit-testing', 'file-operations'],
+      L3: ['component-testing', 'file-operations'],
+      L4: ['api-testing', 'database-access', 'version-control'],
+      L5: ['journey-validation', 'browser-automation'],
+      L6: ['ux-testing', 'browser-automation'],
+      L7: ['analytics', 'web-research', 'user-feedback'],
+      L8: ['business-metrics', 'analytics'],
+      L9: ['version-control', 'web-research']
+    };
+
+    return (levelCapabilities[level] || []).map(cap => ({
+      capability: cap,
+      available: this.hasCapability(cap),
+      tools: this.getToolsForCapability(cap),
+      fallback: this.getFallbackForCapability(cap)
+    }));
+  }
+
+  getReport() {
+    const report = {
+      totalCapabilities: Object.keys(CAPABILITY_DEFINITIONS).length,
+      availableCapabilities: 0,
+      missingCapabilities: [],
+      byLevel: {}
+    };
+
+    for (const [cap, data] of Object.entries(this.capabilityMap)) {
+      if (data.available) {
+        report.availableCapabilities++;
+      } else {
+        report.missingCapabilities.push({
+          capability: cap,
+          description: data.description,
+          fallback: data.fallback
+        });
+      }
+    }
+
+    for (let i = 1; i <= 9; i++) {
+      const level = `L${i}`;
+      report.byLevel[level] = this.getCapabilitiesForLevel(level);
+    }
+
+    return report;
+  }
+}
+
+module.exports = { CapabilityManager, CAPABILITY_DEFINITIONS };

package/lib/integration/graceful-degradation.js

@@ -0,0 +1,152 @@
+const DEGRADATION_STRATEGIES = {
+  'manual-code-review': {
+    type: 'manual',
+    instructions: 'Perform manual code review focusing on syntax, style, and common patterns',
+    guidance: 'Check for: indentation consistency, naming conventions, error handling, edge cases'
+  },
+  'direct-file-access': {
+    type: 'native',
+    instructions: 'Use built-in filesystem APIs (fs.readFile, fs.writeFile)',
+    guidance: 'Ensure proper error handling and encoding specifications'
+  },
+  'manual-testing': {
+    type: 'manual',
+    instructions: 'Manually verify function behavior with sample inputs',
+    guidance: 'Test edge cases, error conditions, and expected outputs'
+  },
+  'manual-api-calls': {
+    type: 'manual',
+    instructions: 'Use curl or similar HTTP clients to test API endpoints',
+    guidance: 'Verify status codes, response bodies, and error handling'
+  },
+  'manual-ux-testing': {
+    type: 'manual',
+    instructions: 'Manually test user journeys in browser',
+    guidance: 'Follow user personas through critical flows, noting UX issues'
+  },
+  'manual-ux-review': {
+    type: 'manual',
+    instructions: 'Review UI implementation against design principles',
+    guidance: 'Check accessibility, responsiveness, and usability heuristics'
+  },
+  'log-analysis': {
+    type: 'manual',
+    instructions: 'Analyze application logs for usage patterns',
+    guidance: 'Look for error rates, performance bottlenecks, user behavior patterns'
+  },
+  'manual-reporting': {
+    type: 'manual',
+    instructions: 'Create manual reports from available data sources',
+    guidance: 'Collect metrics from logs, databases, and manual observations'
+  },
+  'manual-git': {
+    type: 'cli',
+    instructions: 'Use git CLI commands directly',
+    guidance: 'Standard git workflow: status, add, commit, push, pull'
+  },
+  'manual-browser-testing': {
+    type: 'manual',
+    instructions: 'Manually interact with application in browser',
+    guidance: 'Test functionality, check console for errors, verify behavior'
+  },
+  'manual-db-queries': {
+    type: 'cli',
+    instructions: 'Use database CLI tools (psql, mysql) directly',
+    guidance: 'Connect to database and execute queries manually'
+  },
+  'manual-web-search': {
+    type: 'manual',
+    instructions: 'Manually search web using browser',
+    guidance: 'Use search engines and visit relevant documentation sites'
+  },
+  'manual-feedback-review': {
+    type: 'manual',
+    instructions: 'Manually review feedback from support channels',
+    guidance: 'Check email, Slack, support tickets for user feedback'
+  },
+  'manual-implementation': {
+    type: 'manual',
+    instructions: 'Implement manually without automated tools',
+    guidance: 'Follow best practices and manual verification procedures'
+  }
+};
+
+function getDegradationStrategy(capability, availableCapabilities) {
+  if (!availableCapabilities[capability] || !availableCapabilities[capability].available) {
+    const fallback = availableCapabilities[capability]?.fallback || 'manual-implementation';
+    return DEGRADATION_STRATEGIES[fallback] || DEGRADATION_STRATEGIES['manual-implementation'];
+  }
+  
+  return null;
+}
+
+function generateDegradationGuidance(level, capabilities) {
+  const guidance = {
+    level,
+    missingCapabilities: [],
+    workflowAdjustments: [],
+    recommendations: []
+  };
+
+  for (const cap of capabilities) {
+    if (!cap.available) {
+      const strategy = DEGRADATION_STRATEGIES[cap.fallback] || DEGRADATION_STRATEGIES['manual-implementation'];
+      
+      guidance.missingCapabilities.push({
+        capability: cap.capability,
+        fallback: cap.fallback,
+        strategy: strategy.type,
+        instructions: strategy.instructions,
+        guidance: strategy.guidance
+      });
+
+      if (strategy.type === 'manual') {
+        guidance.workflowAdjustments.push(
+          `For ${cap.capability}: ${strategy.instructions}`
+        );
+      }
+
+      guidance.recommendations.push(
+        `Consider adding tools for ${cap.capability} to improve automation`
+      );
+    }
+  }
+
+  return guidance;
+}
+
+function createAgentInstructions(level, capabilities) {
+  const missing = capabilities.filter(cap => !cap.available);
+  
+  if (missing.length === 0) {
+    return {
+      hasAllTools: true,
+      message: 'All required tools are available',
+      instructions: []
+    };
+  }
+
+  const instructions = missing.map(cap => {
+    const strategy = DEGRADATION_STRATEGIES[cap.fallback] || DEGRADATION_STRATEGIES['manual-implementation'];
+    return {
+      capability: cap.capability,
+      type: strategy.type,
+      action: strategy.instructions,
+      guidance: strategy.guidance
+    };
+  });
+
+  return {
+    hasAllTools: false,
+    message: `${missing.length} tool(s) missing for ${level}`,
+    instructions,
+    summary: `You will need to use ${instructions.filter(i => i.type === 'manual').length} manual workflow(s)`
+  };
+}
+
+module.exports = {
+  DEGRADATION_STRATEGIES,
+  getDegradationStrategy,
+  generateDegradationGuidance,
+  createAgentInstructions
+};

package/lib/integration/mcp-client.js

@@ -0,0 +1,109 @@
+const { spawn } = require('child_process');
+
+class McpClient {
+  constructor(serverConfig) {
+    this.name = serverConfig.name;
+    this.command = serverConfig.command;
+    this.args = serverConfig.args || [];
+    this.env = serverConfig.env || {};
+    this.process = null;
+  }
+
+  async start() {
+    return new Promise((resolve, reject) => {
+      this.process = spawn(this.command, this.args, {
+        env: { ...process.env, ...this.env },
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      this.process.on('error', (error) => {
+        reject(new Error(`Failed to start MCP server ${this.name}: ${error.message}`));
+      });
+
+      this.process.stdout.once('data', () => {
+        resolve();
+      });
+
+      setTimeout(() => {
+        if (!this.process.killed) {
+          resolve();
+        }
+      }, 1000);
+    });
+  }
+
+  async call(method, params = {}) {
+    if (!this.process) {
+      throw new Error(`MCP server ${this.name} not started`);
+    }
+
+    return new Promise((resolve, reject) => {
+      const request = {
+        jsonrpc: '2.0',
+        id: Date.now(),
+        method,
+        params
+      };
+
+      let responseData = '';
+
+      const timeout = setTimeout(() => {
+        reject(new Error(`MCP call to ${this.name}.${method} timed out`));
+      }, 5000);
+
+      const onData = (data) => {
+        responseData += data.toString();
+        try {
+          const response = JSON.parse(responseData);
+          clearTimeout(timeout);
+          this.process.stdout.off('data', onData);
+          
+          if (response.error) {
+            reject(new Error(`MCP error: ${response.error.message}`));
+          } else {
+            resolve(response.result);
+          }
+        } catch (e) {
+        }
+      };
+
+      this.process.stdout.on('data', onData);
+      this.process.stdin.write(JSON.stringify(request) + '\n');
+    });
+  }
+
+  async stop() {
+    if (this.process && !this.process.killed) {
+      this.process.kill();
+      this.process = null;
+    }
+  }
+
+  async listTools() {
+    try {
+      const result = await this.call('tools/list');
+      return result.tools || [];
+    } catch (error) {
+      return [];
+    }
+  }
+
+  async callTool(toolName, args) {
+    try {
+      return await this.call('tools/call', {
+        name: toolName,
+        arguments: args
+      });
+    } catch (error) {
+      throw new Error(`Tool ${toolName} failed: ${error.message}`);
+    }
+  }
+}
+
+async function createMcpClient(serverConfig) {
+  const client = new McpClient(serverConfig);
+  await client.start();
+  return client;
+}
+
+module.exports = { McpClient, createMcpClient };