telos-framework 0.1.0

package/lib/integration/tool-config-writers.js

@@ -0,0 +1,142 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+const CONFIG_TEMPLATES = {
+  eslint: {
+    filename: '.eslintrc.json',
+    content: {
+      env: {
+        browser: true,
+        es2021: true,
+        node: true
+      },
+      extends: ['eslint:recommended'],
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module'
+      },
+      rules: {}
+    }
+  },
+  
+  prettier: {
+    filename: '.prettierrc.json',
+    content: {
+      semi: true,
+      trailingComma: 'es5',
+      singleQuote: true,
+      printWidth: 100,
+      tabWidth: 2
+    }
+  },
+  
+  vitest: {
+    filename: 'vitest.config.js',
+    content: `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html']
+    }
+  }
+});
+`
+  },
+  
+  playwright: {
+    filename: 'playwright.config.js',
+    content: `import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    trace: 'on-first-retry',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { browserName: 'chromium' },
+    },
+  ],
+});
+`
+  }
+};
+
+async function writeToolConfig(tool, projectRoot, options = {}) {
+  const template = CONFIG_TEMPLATES[tool.toLowerCase()];
+  
+  if (!template) {
+    throw new Error(`No configuration template for tool: ${tool}`);
+  }
+
+  const configPath = path.join(projectRoot, template.filename);
+  
+  try {
+    await fs.access(configPath);
+    if (!options.overwrite) {
+      return {
+        written: false,
+        path: configPath,
+        reason: 'Config already exists'
+      };
+    }
+  } catch (error) {
+  }
+
+  const content = typeof template.content === 'string'
+    ? template.content
+    : JSON.stringify(template.content, null, 2);
+
+  await fs.writeFile(configPath, content, 'utf8');
+  
+  return {
+    written: true,
+    path: configPath,
+    tool
+  };
+}
+
+async function writeAllConfigs(tools, projectRoot, options = {}) {
+  const results = [];
+  
+  for (const tool of tools) {
+    try {
+      const result = await writeToolConfig(tool, projectRoot, options);
+      results.push(result);
+    } catch (error) {
+      results.push({
+        written: false,
+        tool,
+        error: error.message
+      });
+    }
+  }
+  
+  return results;
+}
+
+function getConfigTemplate(tool) {
+  return CONFIG_TEMPLATES[tool.toLowerCase()] || null;
+}
+
+function hasConfigTemplate(tool) {
+  return tool.toLowerCase() in CONFIG_TEMPLATES;
+}
+
+module.exports = {
+  writeToolConfig,
+  writeAllConfigs,
+  getConfigTemplate,
+  hasConfigTemplate,
+  CONFIG_TEMPLATES
+};

package/lib/integration/tool-invoker.js

@@ -0,0 +1,166 @@
+const { exec } = require('child_process');
+const { promisify } = require('util');
+const execAsync = promisify(exec);
+
+const TOOL_COMMANDS = {
+  eslint: {
+    lint: (files = '.') => `eslint ${files}`,
+    fix: (files = '.') => `eslint --fix ${files}`,
+    check: (file) => `eslint ${file}`
+  },
+  
+  prettier: {
+    format: (files = '.') => `prettier --write ${files}`,
+    check: (files = '.') => `prettier --check ${files}`
+  },
+  
+  vitest: {
+    run: (args = '') => `vitest run ${args}`,
+    watch: () => 'vitest',
+    coverage: () => 'vitest run --coverage'
+  },
+  
+  jest: {
+    run: (args = '') => `jest ${args}`,
+    watch: () => 'jest --watch',
+    coverage: () => 'jest --coverage'
+  },
+  
+  playwright: {
+    test: (args = '') => `playwright test ${args}`,
+    ui: () => 'playwright test --ui',
+    debug: (test) => `playwright test --debug ${test || ''}`
+  },
+  
+  git: {
+    status: () => 'git status',
+    add: (files = '.') => `git add ${files}`,
+    commit: (message) => `git commit -m "${message}"`,
+    push: () => 'git push',
+    diff: () => 'git diff'
+  }
+};
+
+class ToolInvoker {
+  constructor(availableTools = []) {
+    this.availableTools = availableTools.map(t => t.name.toLowerCase());
+  }
+
+  hasTool(toolName) {
+    const name = toolName.toLowerCase();
+    return this.availableTools.includes(name) || 
+           this.availableTools.some(t => t.includes(name));
+  }
+
+  async invoke(tool, action, ...args) {
+    const toolName = tool.toLowerCase();
+    
+    if (!this.hasTool(toolName)) {
+      throw new Error(`Tool ${tool} not available`);
+    }
+
+    const commands = TOOL_COMMANDS[toolName];
+    if (!commands || !commands[action]) {
+      throw new Error(`Action ${action} not supported for tool ${tool}`);
+    }
+
+    const command = commands[action](...args);
+    
+    try {
+      const { stdout, stderr } = await execAsync(command);
+      return {
+        success: true,
+        tool,
+        action,
+        command,
+        stdout,
+        stderr
+      };
+    } catch (error) {
+      return {
+        success: false,
+        tool,
+        action,
+        command,
+        error: error.message,
+        stdout: error.stdout,
+        stderr: error.stderr
+      };
+    }
+  }
+
+  async runLinter(files = '.') {
+    if (this.hasTool('eslint')) {
+      return await this.invoke('eslint', 'lint', files);
+    } else if (this.hasTool('prettier')) {
+      return await this.invoke('prettier', 'check', files);
+    } else {
+      return {
+        success: false,
+        tool: 'none',
+        action: 'lint',
+        error: 'No linter available'
+      };
+    }
+  }
+
+  async runTests(args = '') {
+    if (this.hasTool('vitest')) {
+      return await this.invoke('vitest', 'run', args);
+    } else if (this.hasTool('jest')) {
+      return await this.invoke('jest', 'run', args);
+    } else {
+      return {
+        success: false,
+        tool: 'none',
+        action: 'test',
+        error: 'No test framework available'
+      };
+    }
+  }
+
+  async runE2ETests(args = '') {
+    if (this.hasTool('playwright')) {
+      return await this.invoke('playwright', 'test', args);
+    } else {
+      return {
+        success: false,
+        tool: 'none',
+        action: 'e2e',
+        error: 'No E2E framework available'
+      };
+    }
+  }
+
+  async format(files = '.') {
+    if (this.hasTool('prettier')) {
+      return await this.invoke('prettier', 'format', files);
+    } else if (this.hasTool('eslint')) {
+      return await this.invoke('eslint', 'fix', files);
+    } else {
+      return {
+        success: false,
+        tool: 'none',
+        action: 'format',
+        error: 'No formatter available'
+      };
+    }
+  }
+
+  getAvailableActions(tool) {
+    const toolName = tool.toLowerCase();
+    const commands = TOOL_COMMANDS[toolName];
+    
+    if (!commands) {
+      return [];
+    }
+    
+    return Object.keys(commands);
+  }
+
+  getSupportedTools() {
+    return Object.keys(TOOL_COMMANDS);
+  }
+}
+
+module.exports = { ToolInvoker, TOOL_COMMANDS };

package/lib/platform/platform-detector.js

@@ -0,0 +1,74 @@
+const fs = require('fs').promises;
+const path = require('path');
+
+async function detectPlatforms(projectRoot) {
+  const platforms = [];
+
+  if (await fileExists(path.join(projectRoot, 'CLAUDE.md'))) {
+    platforms.push({ name: 'claude', configFile: 'CLAUDE.md' });
+  }
+
+  if (await fileExists(path.join(projectRoot, '.cursor'))) {
+    platforms.push({ name: 'cursor', configFile: '.cursor/rules/agents.md' });
+  }
+
+  if (await fileExists(path.join(projectRoot, '.github', 'copilot-instructions.md'))) {
+    platforms.push({ name: 'copilot', configFile: '.github/copilot-instructions.md' });
+  }
+
+  if (await fileExists(path.join(projectRoot, '.gemini'))) {
+    platforms.push({ name: 'gemini', configFile: '.gemini/instructions.md' });
+  }
+
+  if (platforms.length === 0) {
+    platforms.push({ name: 'claude', configFile: 'CLAUDE.md' });
+  }
+
+  return platforms;
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getPlatformConfig(platformName) {
+  const configs = {
+    claude: {
+      name: 'Claude',
+      targets: [
+        { source: 'telos/content/AGENTS.md', target: 'CLAUDE.md' },
+        { source: 'telos/content/TELOS.md', target: 'TELOS.md' },
+        { source: 'telos/content/LOGOS.md', target: 'LOGOS.md' }
+      ]
+    },
+    cursor: {
+      name: 'Cursor',
+      targets: [
+        { source: 'telos/content/AGENTS.md', target: '.cursor/rules/agents.md' },
+        { source: 'telos/content/TELOS.md', target: '.cursor/rules/telos.md' },
+        { source: 'telos/content/LOGOS.md', target: '.cursor/rules/logos.md' }
+      ]
+    },
+    copilot: {
+      name: 'GitHub Copilot',
+      targets: [
+        { source: 'telos/content/AGENTS.md', target: '.github/copilot-instructions.md' }
+      ]
+    },
+    gemini: {
+      name: 'Gemini',
+      targets: [
+        { source: 'telos/content/AGENTS.md', target: '.gemini/instructions.md' }
+      ]
+    }
+  };
+
+  return configs[platformName] || configs.claude;
+}
+
+module.exports = { detectPlatforms, getPlatformConfig };

package/lib/platform/symlink-creator.js

@@ -0,0 +1,103 @@
+const fs = require('fs').promises;
+const path = require('path');
+const os = require('os');
+
+async function createSymlinks(projectRoot, platformConfig) {
+  const results = [];
+  const isWindows = os.platform() === 'win32';
+
+  for (const target of platformConfig.targets) {
+    const sourcePath = path.join(projectRoot, target.source);
+    const targetPath = path.join(projectRoot, target.target);
+
+    try {
+      await ensureDirectoryExists(path.dirname(targetPath));
+      
+      await removeIfExists(targetPath);
+
+      if (isWindows) {
+        await createWindowsSymlink(sourcePath, targetPath);
+      } else {
+        await createUnixSymlink(sourcePath, targetPath, projectRoot);
+      }
+
+      results.push({
+        source: target.source,
+        target: target.target,
+        success: true,
+        type: isWindows ? 'junction' : 'symlink'
+      });
+    } catch (error) {
+      results.push({
+        source: target.source,
+        target: target.target,
+        success: false,
+        error: error.message
+      });
+    }
+  }
+
+  return results;
+}
+
+async function ensureDirectoryExists(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+async function removeIfExists(filePath) {
+  try {
+    const stats = await fs.lstat(filePath);
+    if (stats.isSymbolicLink() || stats.isFile()) {
+      await fs.unlink(filePath);
+    } else if (stats.isDirectory()) {
+      await fs.rmdir(filePath, { recursive: true });
+    }
+  } catch (error) {
+  }
+}
+
+async function createUnixSymlink(sourcePath, targetPath, projectRoot) {
+  const targetDir = path.dirname(targetPath);
+  const relativeSource = path.relative(targetDir, sourcePath);
+  
+  await fs.symlink(relativeSource, targetPath, 'file');
+}
+
+async function createWindowsSymlink(sourcePath, targetPath) {
+  const { execSync } = require('child_process');
+  
+  try {
+    execSync(`mklink "${targetPath}" "${sourcePath}"`, { stdio: 'ignore' });
+  } catch (error) {
+    await fs.copyFile(sourcePath, targetPath);
+  }
+}
+
+async function verifySymlinks(projectRoot, platformConfig) {
+  const results = [];
+
+  for (const target of platformConfig.targets) {
+    const targetPath = path.join(projectRoot, target.target);
+    
+    try {
+      const stats = await fs.lstat(targetPath);
+      const exists = stats.isSymbolicLink() || stats.isFile();
+      
+      results.push({
+        target: target.target,
+        exists,
+        isSymlink: stats.isSymbolicLink()
+      });
+    } catch {
+      results.push({
+        target: target.target,
+        exists: false,
+        isSymlink: false
+      });
+    }
+  }
+
+  return results;
+}
+
+module.exports = { createSymlinks, verifySymlinks };

package/lib/spec/spec-formatter.js

@@ -0,0 +1,79 @@
+function formatTelosSpec(spec) {
+  const { telos, via, requirements, tools } = spec;
+  
+  let content = `## TELOS ALIGNMENT\n\n`;
+  content += `**Contributes to**: ${telos}\n\n`;
+  
+  if (via && via.length > 0) {
+    content += `**Via**:\n`;
+    for (const step of via) {
+      content += `- ${step.level}: ${step.purpose}\n`;
+    }
+    content += `\n`;
+  }
+  
+  content += `## ADDED Requirements\n\n`;
+  
+  for (const req of requirements) {
+    content += `### Requirement: ${req.name}\n\n`;
+    content += `${req.statement}\n\n`;
+    
+    if (req.scenarios && req.scenarios.length > 0) {
+      for (const scenario of req.scenarios) {
+        content += `#### Scenario: ${scenario.name}\n\n`;
+        content += `- **WHEN** ${scenario.when}\n`;
+        content += `- **THEN** ${scenario.then}\n\n`;
+      }
+    }
+  }
+  
+  if (tools && Object.keys(tools).length > 0) {
+    content += `## TOOLS REQUIRED\n\n`;
+    for (const [level, levelTools] of Object.entries(tools)) {
+      if (levelTools.length > 0) {
+        content += `- **${level}**: ${levelTools.join(', ')}\n`;
+      }
+    }
+    content += `\n`;
+  }
+  
+  return content;
+}
+
+function parseTelosSpec(content) {
+  const spec = {
+    telos: null,
+    via: [],
+    requirements: [],
+    tools: {}
+  };
+  
+  const telosMatch = content.match(/\*\*Contributes to\*\*:\s*(.+)/);
+  if (telosMatch) {
+    spec.telos = telosMatch[1].trim();
+  }
+  
+  const viaSection = content.match(/\*\*Via\*\*:\n((?:- .+\n?)+)/);
+  if (viaSection) {
+    const lines = viaSection[1].split('\n').filter(l => l.trim());
+    spec.via = lines.map(line => {
+      const match = line.match(/- (L\d+):\s*(.+)/);
+      if (match) {
+        return { level: match[1], purpose: match[2].trim() };
+      }
+      return null;
+    }).filter(Boolean);
+  }
+  
+  const reqMatches = content.matchAll(/### Requirement: (.+)\n\n([^#]+)/g);
+  for (const match of reqMatches) {
+    spec.requirements.push({
+      name: match[1].trim(),
+      statement: match[2].trim()
+    });
+  }
+  
+  return spec;
+}
+
+module.exports = { formatTelosSpec, parseTelosSpec };

package/lib/spec/spec-translator.js

@@ -0,0 +1,150 @@
+async function decomposeToLevels(l9Goal, hierarchy) {
+  const decomposition = {
+    L9: {
+      level: 'L9',
+      goal: l9Goal,
+      purpose: hierarchy.L9.purpose
+    }
+  };
+
+  decomposition.L8 = {
+    level: 'L8',
+    purpose: hierarchy.L8.purpose,
+    parentGoal: l9Goal,
+    question: 'What business metrics validate this serves our Telos?'
+  };
+
+  decomposition.L7 = {
+    level: 'L7',
+    purpose: hierarchy.L7.purpose,
+    parentGoal: decomposition.L8.purpose,
+    question: 'What user insights do we need to track these metrics?'
+  };
+
+  decomposition.L6 = {
+    level: 'L6',
+    purpose: hierarchy.L6.purpose,
+    parentGoal: decomposition.L7.purpose,
+    question: 'What UX enables users to provide these insights?'
+  };
+
+  decomposition.L5 = {
+    level: 'L5',
+    purpose: hierarchy.L5.purpose,
+    parentGoal: decomposition.L6.purpose,
+    question: 'What workflows must function end-to-end?'
+  };
+
+  decomposition.L4 = {
+    level: 'L4',
+    purpose: hierarchy.L4.purpose,
+    parentGoal: decomposition.L5.purpose,
+    question: 'What API contracts enable these workflows?'
+  };
+
+  decomposition.L3 = {
+    level: 'L3',
+    purpose: hierarchy.L3.purpose,
+    parentGoal: decomposition.L4.purpose,
+    question: 'What components implement these contracts?'
+  };
+
+  decomposition.L2 = {
+    level: 'L2',
+    purpose: hierarchy.L2.purpose,
+    parentGoal: decomposition.L3.purpose,
+    question: 'What functions compose these components?'
+  };
+
+  decomposition.L1 = {
+    level: 'L1',
+    purpose: hierarchy.L1.purpose,
+    parentGoal: decomposition.L2.purpose,
+    question: 'What code quality standards must be met?'
+  };
+
+  return decomposition;
+}
+
+function buildLineage(requirement, decomposition) {
+  const lineage = {
+    requirement,
+    chain: []
+  };
+
+  const levels = ['L9', 'L8', 'L7', 'L6', 'L5', 'L4', 'L3', 'L2', 'L1'];
+  
+  for (const level of levels) {
+    if (decomposition[level]) {
+      lineage.chain.push({
+        level,
+        purpose: decomposition[level].purpose,
+        question: decomposition[level].question
+      });
+    }
+  }
+
+  return lineage;
+}
+
+function generateTasksFromDecomposition(decomposition, tools) {
+  const tasks = [];
+
+  if (decomposition.L1) {
+    tasks.push({
+      level: 'L1',
+      title: 'Code Quality Validation',
+      description: `Ensure code meets quality standards: ${decomposition.L1.purpose}`,
+      tools: tools.L1 || [],
+      acceptance: 'All linters pass, no critical issues'
+    });
+  }
+
+  if (decomposition.L2) {
+    tasks.push({
+      level: 'L2',
+      title: 'Function Implementation',
+      description: `Implement tested functions: ${decomposition.L2.purpose}`,
+      tools: tools.L2 || [],
+      acceptance: 'All unit tests pass, >80% coverage'
+    });
+  }
+
+  if (decomposition.L3) {
+    tasks.push({
+      level: 'L3',
+      title: 'Component Development',
+      description: `Build components: ${decomposition.L3.purpose}`,
+      tools: tools.L3 || [],
+      acceptance: 'Component tests pass, renders correctly'
+    });
+  }
+
+  if (decomposition.L5) {
+    tasks.push({
+      level: 'L5',
+      title: 'E2E Workflow Validation',
+      description: `Validate workflows: ${decomposition.L5.purpose}`,
+      tools: tools.L5 || [],
+      acceptance: 'All E2E tests pass, workflows complete successfully'
+    });
+  }
+
+  if (decomposition.L9) {
+    tasks.push({
+      level: 'L9',
+      title: 'Telos Alignment Check',
+      description: `Verify alignment with ultimate purpose: ${decomposition.L9.purpose}`,
+      tools: [],
+      acceptance: 'Telos-Guardian approves alignment'
+    });
+  }
+
+  return tasks;
+}
+
+module.exports = { 
+  decomposeToLevels, 
+  buildLineage, 
+  generateTasksFromDecomposition 
+};