k0ntext 3.0.0

package/templates/base/tools/lib/validate.js

@@ -0,0 +1,521 @@
+/**
+ * Claude Context Engineering - Validation Module
+ *
+ * Comprehensive validation of the context engineering setup:
+ * - Schema validation for JSON files
+ * - Markdown link validation
+ * - Placeholder detection
+ * - Line number accuracy checking
+ * - Structure validation
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const { glob } = require('glob');
+const { configLoader, findClaudeDir, loadJsonFile } = require('./config-loader');
+const { logger } = require('./logger');
+const { ValidationError } = require('./errors');
+
+/**
+ * Main validation function
+ */
+async function validate(options = {}) {
+  const {
+    all = false,
+    links = false,
+    lines = false,
+    placeholders = false,
+    schema = false,
+    structure = false,
+    threshold = 60,
+    output = 'console',
+    file = null,
+  } = options;
+
+  const op = logger.startOperation('validate');
+  const claudeDir = options.claudeDir || findClaudeDir();
+  const projectRoot = path.dirname(claudeDir);
+
+  const results = {
+    timestamp: new Date().toISOString(),
+    claudeDir,
+    checks: {},
+    summary: {
+      total: 0,
+      passed: 0,
+      failed: 0,
+      warnings: 0,
+    },
+  };
+
+  try {
+    console.log(chalk.cyan('\n🔍 Running Validation Suite...\n'));
+
+    // Schema validation
+    if (all || schema) {
+      console.log(chalk.white('Schema Validation'));
+      console.log(chalk.gray('─'.repeat(50)));
+      results.checks.schema = await validateSchemas(claudeDir);
+      printCheckResult(results.checks.schema);
+    }
+
+    // Link validation
+    if (all || links) {
+      console.log(chalk.white('\nLink Validation'));
+      console.log(chalk.gray('─'.repeat(50)));
+      results.checks.links = await validateLinks(claudeDir, projectRoot);
+      printCheckResult(results.checks.links);
+    }
+
+    // Placeholder detection
+    if (all || placeholders) {
+      console.log(chalk.white('\nPlaceholder Detection'));
+      console.log(chalk.gray('─'.repeat(50)));
+      results.checks.placeholders = await detectPlaceholders(claudeDir, projectRoot);
+      printCheckResult(results.checks.placeholders);
+    }
+
+    // Line number accuracy
+    if (all || lines) {
+      console.log(chalk.white('\nLine Number Accuracy'));
+      console.log(chalk.gray('─'.repeat(50)));
+      results.checks.lineNumbers = await validateLineNumbers(claudeDir, projectRoot, parseInt(threshold));
+      printCheckResult(results.checks.lineNumbers);
+    }
+
+    // Structure validation
+    if (all || structure) {
+      console.log(chalk.white('\nStructure Validation'));
+      console.log(chalk.gray('─'.repeat(50)));
+      results.checks.structure = await validateStructure(claudeDir);
+      printCheckResult(results.checks.structure);
+    }
+
+    // Calculate summary
+    for (const check of Object.values(results.checks)) {
+      results.summary.total++;
+      if (check.status === 'PASS') results.summary.passed++;
+      else if (check.status === 'FAIL') results.summary.failed++;
+      else if (check.status === 'WARN') results.summary.warnings++;
+    }
+
+    // Print summary
+    printSummary(results.summary);
+
+    // Output results
+    if (output === 'json') {
+      console.log(JSON.stringify(results, null, 2));
+    } else if (output === 'markdown') {
+      console.log(formatMarkdown(results));
+    }
+
+    op.success();
+    return results;
+
+  } catch (error) {
+    op.fail(error);
+    throw error;
+  }
+}
+
+/**
+ * Validate JSON files against their schemas
+ */
+async function validateSchemas(claudeDir) {
+  const result = {
+    name: 'Schema Validation',
+    status: 'PASS',
+    checked: 0,
+    passed: 0,
+    failed: 0,
+    issues: [],
+  };
+
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  addFormats(ajv);
+
+  // Load all schemas
+  const schemaDir = path.join(claudeDir, 'schemas');
+  if (!fs.existsSync(schemaDir)) {
+    result.status = 'WARN';
+    result.issues.push({ file: schemaDir, message: 'Schemas directory not found' });
+    return result;
+  }
+
+  // Validate settings.json
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  const settingsSchemaPath = path.join(schemaDir, 'settings.schema.json');
+
+  if (fs.existsSync(settingsPath) && fs.existsSync(settingsSchemaPath)) {
+    result.checked++;
+    try {
+      const settings = loadJsonFile(settingsPath);
+      const schema = loadJsonFile(settingsSchemaPath);
+      const validate = ajv.compile(schema);
+
+      if (validate(settings)) {
+        result.passed++;
+        console.log(chalk.green('  ✓ settings.json'));
+      } else {
+        result.failed++;
+        result.status = 'FAIL';
+        const errors = validate.errors.map(e => `${e.instancePath} ${e.message}`);
+        result.issues.push({ file: 'settings.json', errors });
+        console.log(chalk.red('  ✗ settings.json'));
+        errors.forEach(e => console.log(chalk.gray(`    - ${e}`)));
+      }
+    } catch (error) {
+      result.failed++;
+      result.status = 'FAIL';
+      result.issues.push({ file: 'settings.json', message: error.message });
+      console.log(chalk.red(`  ✗ settings.json: ${error.message}`));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Validate markdown links
+ */
+async function validateLinks(claudeDir, projectRoot) {
+  const result = {
+    name: 'Link Validation',
+    status: 'PASS',
+    checked: 0,
+    valid: 0,
+    broken: 0,
+    issues: [],
+  };
+
+  // Find all markdown files
+  const mdFiles = await glob('**/*.md', {
+    cwd: claudeDir,
+    ignore: ['node_modules/**'],
+  });
+
+  const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+
+  for (const mdFile of mdFiles) {
+    const filePath = path.join(claudeDir, mdFile);
+    const content = fs.readFileSync(filePath, 'utf8');
+    let match;
+
+    while ((match = linkPattern.exec(content)) !== null) {
+      const [, text, link] = match;
+
+      // Skip external links and anchors
+      if (link.startsWith('http') || link.startsWith('#') || link.startsWith('mailto:')) {
+        continue;
+      }
+
+      result.checked++;
+
+      // Resolve the link path
+      const linkPath = path.resolve(path.dirname(filePath), link.split('#')[0]);
+
+      if (fs.existsSync(linkPath)) {
+        result.valid++;
+      } else {
+        result.broken++;
+        result.issues.push({
+          file: mdFile,
+          link,
+          text,
+        });
+        console.log(chalk.red(`  ✗ ${mdFile}: broken link "${link}"`));
+      }
+    }
+  }
+
+  if (result.broken > 0) {
+    result.status = 'FAIL';
+  }
+
+  console.log(chalk.gray(`  Checked ${result.checked} links, ${result.valid} valid, ${result.broken} broken`));
+
+  return result;
+}
+
+/**
+ * Detect remaining placeholders
+ */
+async function detectPlaceholders(claudeDir, projectRoot) {
+  const result = {
+    name: 'Placeholder Detection',
+    status: 'PASS',
+    checked: 0,
+    found: 0,
+    issues: [],
+  };
+
+  const placeholderPattern = /\{\{([A-Z_]+)\}\}/g;
+
+  // Check AI_CONTEXT.md in project root
+  const claudeMdPath = path.join(projectRoot, 'AI_CONTEXT.md');
+  if (fs.existsSync(claudeMdPath)) {
+    const content = fs.readFileSync(claudeMdPath, 'utf8');
+    let match;
+
+    while ((match = placeholderPattern.exec(content)) !== null) {
+      result.found++;
+      result.issues.push({
+        file: 'AI_CONTEXT.md',
+        placeholder: match[0],
+        name: match[1],
+      });
+    }
+    result.checked++;
+  }
+
+  // Check files in .claude directory
+  const mdFiles = await glob('**/*.md', {
+    cwd: claudeDir,
+    ignore: ['node_modules/**'],
+  });
+
+  for (const mdFile of mdFiles) {
+    const filePath = path.join(claudeDir, mdFile);
+    const content = fs.readFileSync(filePath, 'utf8');
+    let match;
+
+    while ((match = placeholderPattern.exec(content)) !== null) {
+      result.found++;
+      result.issues.push({
+        file: `.ai-context/${mdFile}`,
+        placeholder: match[0],
+        name: match[1],
+      });
+    }
+    result.checked++;
+  }
+
+  if (result.found > 0) {
+    result.status = 'WARN';
+    console.log(chalk.yellow(`  ⚠️  Found ${result.found} unresolved placeholders:`));
+    result.issues.forEach(issue => {
+      console.log(chalk.gray(`    - ${issue.file}: ${issue.placeholder}`));
+    });
+  } else {
+    console.log(chalk.green('  ✓ No unresolved placeholders'));
+  }
+
+  return result;
+}
+
+/**
+ * Validate line number references
+ */
+async function validateLineNumbers(claudeDir, projectRoot, threshold) {
+  const result = {
+    name: 'Line Number Accuracy',
+    status: 'PASS',
+    checked: 0,
+    valid: 0,
+    invalid: 0,
+    accuracy: 0,
+    issues: [],
+  };
+
+  const lineRefPattern = /\[Line[s]?\s*(\d+)(?:-(\d+))?\]/gi;
+  const fileLinePattern = /([^\s:]+):(\d+)/g;
+
+  // Sample workflow files
+  const workflowDir = path.join(claudeDir, 'context', 'workflows');
+  if (!fs.existsSync(workflowDir)) {
+    result.status = 'WARN';
+    result.issues.push({ message: 'No workflow files found to validate' });
+    console.log(chalk.yellow('  ⚠️  No workflow files found'));
+    return result;
+  }
+
+  const workflowFiles = await glob('*.md', { cwd: workflowDir });
+
+  // Sample up to 5 random references
+  const samples = [];
+
+  for (const wfFile of workflowFiles.slice(0, 3)) {
+    const content = fs.readFileSync(path.join(workflowDir, wfFile), 'utf8');
+    let match;
+
+    while ((match = fileLinePattern.exec(content)) !== null) {
+      const [, filePath, lineNum] = match;
+      // Skip if it looks like a URL or example
+      if (filePath.includes('http') || filePath.includes('example')) continue;
+
+      samples.push({
+        workflow: wfFile,
+        file: filePath,
+        line: parseInt(lineNum),
+      });
+    }
+  }
+
+  // Check samples (max 10)
+  for (const sample of samples.slice(0, 10)) {
+    result.checked++;
+
+    const fullPath = path.join(projectRoot, sample.file);
+    if (!fs.existsSync(fullPath)) {
+      result.invalid++;
+      result.issues.push({
+        workflow: sample.workflow,
+        file: sample.file,
+        line: sample.line,
+        error: 'File not found',
+      });
+      continue;
+    }
+
+    const lines = fs.readFileSync(fullPath, 'utf8').split('\n');
+    if (sample.line <= lines.length) {
+      result.valid++;
+    } else {
+      result.invalid++;
+      result.issues.push({
+        workflow: sample.workflow,
+        file: sample.file,
+        line: sample.line,
+        error: `Line ${sample.line} exceeds file length (${lines.length})`,
+      });
+    }
+  }
+
+  // Calculate accuracy
+  result.accuracy = result.checked > 0 ? Math.round((result.valid / result.checked) * 100) : 100;
+
+  if (result.accuracy < threshold) {
+    result.status = 'FAIL';
+    console.log(chalk.red(`  ✗ Accuracy: ${result.accuracy}% (threshold: ${threshold}%)`));
+  } else {
+    console.log(chalk.green(`  ✓ Accuracy: ${result.accuracy}% (threshold: ${threshold}%)`));
+  }
+
+  console.log(chalk.gray(`  Checked ${result.checked} references`));
+
+  return result;
+}
+
+/**
+ * Validate directory structure
+ */
+async function validateStructure(claudeDir) {
+  const result = {
+    name: 'Structure Validation',
+    status: 'PASS',
+    required: 0,
+    found: 0,
+    missing: [],
+  };
+
+  const requiredPaths = [
+    'settings.json',
+    'README.md',
+    'agents',
+    'commands',
+    'context',
+    'indexes',
+  ];
+
+  const recommendedPaths = [
+    'research',
+    'plans',
+    'schemas',
+  ];
+
+  for (const reqPath of requiredPaths) {
+    result.required++;
+    const fullPath = path.join(claudeDir, reqPath);
+
+    if (fs.existsSync(fullPath)) {
+      result.found++;
+      console.log(chalk.green(`  ✓ ${reqPath}`));
+    } else {
+      result.missing.push(reqPath);
+      console.log(chalk.red(`  ✗ ${reqPath} (required)`));
+    }
+  }
+
+  for (const recPath of recommendedPaths) {
+    const fullPath = path.join(claudeDir, recPath);
+
+    if (fs.existsSync(fullPath)) {
+      console.log(chalk.green(`  ✓ ${recPath}`));
+    } else {
+      console.log(chalk.yellow(`  ⚠️ ${recPath} (recommended)`));
+    }
+  }
+
+  if (result.missing.length > 0) {
+    result.status = 'FAIL';
+  }
+
+  return result;
+}
+
+/**
+ * Print check result
+ */
+function printCheckResult(check) {
+  const statusIcon = check.status === 'PASS' ? chalk.green('✓') :
+                     check.status === 'WARN' ? chalk.yellow('⚠️') :
+                     chalk.red('✗');
+  // Status already printed by individual checks
+}
+
+/**
+ * Print summary
+ */
+function printSummary(summary) {
+  console.log(chalk.white('\n📊 Validation Summary'));
+  console.log(chalk.gray('─'.repeat(50)));
+
+  const statusColor = summary.failed > 0 ? chalk.red :
+                      summary.warnings > 0 ? chalk.yellow :
+                      chalk.green;
+
+  console.log(`  Total checks: ${summary.total}`);
+  console.log(chalk.green(`  Passed: ${summary.passed}`));
+  if (summary.warnings > 0) console.log(chalk.yellow(`  Warnings: ${summary.warnings}`));
+  if (summary.failed > 0) console.log(chalk.red(`  Failed: ${summary.failed}`));
+
+  const overallStatus = summary.failed > 0 ? 'FAIL' :
+                        summary.warnings > 0 ? 'WARN' : 'PASS';
+
+  console.log(statusColor(`\n  Overall: ${overallStatus}`));
+}
+
+/**
+ * Format results as markdown
+ */
+function formatMarkdown(results) {
+  let md = `# Validation Report\n\n`;
+  md += `**Date:** ${results.timestamp}\n\n`;
+
+  for (const [name, check] of Object.entries(results.checks)) {
+    md += `## ${check.name}\n\n`;
+    md += `**Status:** ${check.status}\n\n`;
+
+    if (check.issues && check.issues.length > 0) {
+      md += `### Issues\n\n`;
+      for (const issue of check.issues) {
+        md += `- ${JSON.stringify(issue)}\n`;
+      }
+      md += '\n';
+    }
+  }
+
+  return md;
+}
+
+module.exports = {
+  validate,
+  validateSchemas,
+  validateLinks,
+  detectPlaceholders,
+  validateLineNumbers,
+  validateStructure,
+};

package/templates/base/tools/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@k0ntext/tools",
+  "version": "1.0.0",
+  "description": "CLI tools for Claude Context Engineering template",
+  "main": "lib/index.js",
+  "bin": {
+    "k0ntext-tools": "./bin/k0ntext-tools.js"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint lib/",
+    "validate": "node bin/claude-context.js validate"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "context-engineering",
+    "ai-development",
+    "documentation"
+  ],
+  "author": "Claude Context Engineering Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/claude-code-context-engineering-template"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "glob": "^10.3.10",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "eslint": "^8.55.0",
+    "jest": "^29.7.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "schemas/"
+  ]
+}

package/templates/handlebars/aider-config.hbs

@@ -0,0 +1,146 @@
+{{!-- Aider Configuration Template --}}
+# {{project.name}} - Aider Configuration
+# Generated: {{metadata.timestamp}}
+# Documentation: https://aider.chat/docs/config.html
+
+#=============================================================================
+# MODEL CONFIGURATION
+#=============================================================================
+# Recommended: Claude Sonnet for best code understanding
+# Uncomment ONE of the following based on your API access:
+
+# model: claude-3-5-sonnet-20241022   # Best overall (Anthropic API)
+# model: gpt-4o                        # Good alternative (OpenAI API)
+# model: deepseek-coder                # Budget option
+
+#=============================================================================
+# GIT & AUTO-COMMIT SETTINGS
+#=============================================================================
+# Auto-commit is disabled by default for safety
+# This prevents accidental commits - you review changes first
+# Note: Both 'auto-commits' (plural) and 'auto-commit' (singular) are 
+# included for compatibility with different Aider versions
+auto-commits: false
+auto-commit: false
+
+# Commit message format when auto-commit is enabled
+commit-prompt: "feat({{project.name}}): {{message}}"
+
+# Git integration
+gitignore: true
+git: true
+
+#=============================================================================
+# CONTEXT OPTIMIZATION
+#=============================================================================
+# Map tokens control how much context Aider uses for file mapping
+# Higher = more context awareness, but uses more tokens
+map-tokens: 2048
+map-refresh: auto
+
+# Subtree mode - only work with files in current directory tree
+subtree-only: false
+
+#=============================================================================
+# FILE HANDLING
+#=============================================================================
+{{#if key_files.entry_points}}
+# Auto-add entry point files to context
+read:
+{{#each key_files.entry_points}}
+  - {{this}}
+{{/each}}
+{{/if}}
+
+# Exclude patterns (sensible defaults for most projects)
+# These files/directories are never added to context
+# Note: Uses .gitignore patterns
+{{#if project.type}}
+{{#if (eq project.type "python")}}
+# Python-specific excludes
+# exclude patterns handled by .gitignore
+{{else if (eq project.type "node")}}
+# Node.js-specific excludes
+# exclude patterns handled by .gitignore
+{{/if}}
+{{/if}}
+
+#=============================================================================
+# LANGUAGE & FRAMEWORK
+#=============================================================================
+{{#if project.primary_language}}
+# Detected primary language
+# language: {{project.primary_language}}
+{{/if}}
+
+#=============================================================================
+# EDITOR INTEGRATION
+#=============================================================================
+# Your preferred editor for file viewing
+editor: vscode
+
+#=============================================================================
+# TESTING INTEGRATION
+#=============================================================================
+{{#if commands.test}}
+# Run tests automatically after changes
+test-cmd: {{commands.test}}
+auto-test: false
+{{else}}
+# Configure your test command
+# test-cmd: npm test
+# auto-test: false
+{{/if}}
+
+#=============================================================================
+# LINTING INTEGRATION
+#=============================================================================
+{{#if commands.lint}}
+# Run linter automatically after changes
+lint-cmd: {{commands.lint}}
+auto-lint: false
+{{else}}
+# Configure your lint command
+# lint-cmd: npm run lint
+# auto-lint: false
+{{/if}}
+
+#=============================================================================
+# DISPLAY & OUTPUT
+#=============================================================================
+# Stream output for real-time feedback
+stream: true
+
+# Pretty formatting
+pretty: true
+
+# Dark mode for terminals with dark backgrounds
+# dark-mode: auto
+
+#=============================================================================
+# CHAT HISTORY
+#=============================================================================
+# Save chat history for reference
+chat-history-file: .aider.chat.history.md
+
+#=============================================================================
+# SAFETY SETTINGS
+#=============================================================================
+# Suggest shell commands instead of running automatically
+suggest-shell-commands: true
+
+# Require confirmation for pip installs
+# unsafe-install: false
+
+#=============================================================================
+# ADVANCED SETTINGS
+#=============================================================================
+# Git author attribution
+# attribute-author: true
+# attribute-committer: true
+
+# Voice input (experimental)
+# voice-input: false
+
+---
+{{{coordination.footer}}}