create-universal-ai-context 2.0.0

package/lib/template-renderer.js

@@ -0,0 +1,382 @@
+/**
+ * AI Context Engineering - Template Renderer
+ *
+ * Handlebars-based template rendering engine for generating
+ * context files for multiple AI tools.
+ */
+
+const Handlebars = require('handlebars');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Templates directory
+ */
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates', 'handlebars');
+
+/**
+ * Multi-file markers for Antigravity templates
+ */
+const FILE_START_MARKER = /\{\{\{fileStart\s+"([^"]+)"\}\}\}/g;
+const FILE_END_MARKER = /\{\{\{fileEnd\}\}\}/g;
+
+/**
+ * Register custom Handlebars helpers
+ */
+function registerHelpers() {
+  // Join array with delimiter
+  Handlebars.registerHelper('join', function(array, delimiter) {
+    if (!Array.isArray(array)) return '';
+    return array.join(delimiter || ', ');
+  });
+
+  // Get first N items from array
+  Handlebars.registerHelper('first', function(array, n) {
+    if (!Array.isArray(array)) return [];
+    return array.slice(0, n);
+  });
+
+  // Get length of array
+  Handlebars.registerHelper('length', function(array) {
+    if (!Array.isArray(array)) return 0;
+    return array.length;
+  });
+
+  // Truncate string to max length
+  Handlebars.registerHelper('truncate', function(str, maxLength) {
+    if (typeof str !== 'string') return '';
+    if (str.length <= maxLength) return str;
+    return str.substring(0, maxLength) + '...';
+  });
+
+  // Slugify string for filenames
+  Handlebars.registerHelper('slugify', function(str) {
+    if (typeof str !== 'string') return '';
+    return str
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+  });
+
+  // Concat strings
+  Handlebars.registerHelper('concat', function(...args) {
+    // Remove the Handlebars options object from args
+    args.pop();
+    return args.join('');
+  });
+
+  // Uppercase string
+  Handlebars.registerHelper('uppercase', function(str) {
+    if (typeof str !== 'string') return '';
+    return str.toUpperCase();
+  });
+
+  // Lowercase string
+  Handlebars.registerHelper('lowercase', function(str) {
+    if (typeof str !== 'string') return '';
+    return str.toLowerCase();
+  });
+
+  // Check if equal
+  Handlebars.registerHelper('ifEquals', function(arg1, arg2, options) {
+    return (arg1 === arg2) ? options.fn(this) : options.inverse(this);
+  });
+
+  // Check if not equal
+  Handlebars.registerHelper('ifNotEquals', function(arg1, arg2, options) {
+    return (arg1 !== arg2) ? options.fn(this) : options.inverse(this);
+  });
+
+  // Date formatting
+  Handlebars.registerHelper('formatDate', function(date) {
+    if (!date) return new Date().toISOString();
+    return new Date(date).toISOString();
+  });
+
+  // File markers for multi-file templates (Antigravity)
+  Handlebars.registerHelper('fileStart', function(filename) {
+    return new Handlebars.SafeString(`<<<FILE_START:${filename}>>>`);
+  });
+
+  Handlebars.registerHelper('fileEnd', function() {
+    return new Handlebars.SafeString('<<<FILE_END>>>');
+  });
+}
+
+/**
+ * Register partials from the partials directory
+ * @param {string} partialsDir - Path to partials directory
+ */
+function registerPartials(partialsDir) {
+  const defaultPartialsDir = partialsDir || path.join(TEMPLATES_DIR, 'partials');
+
+  if (!fs.existsSync(defaultPartialsDir)) {
+    return;
+  }
+
+  const files = fs.readdirSync(defaultPartialsDir)
+    .filter(f => f.endsWith('.hbs'));
+
+  for (const file of files) {
+    const name = path.basename(file, '.hbs');
+    const content = fs.readFileSync(path.join(defaultPartialsDir, file), 'utf-8');
+    Handlebars.registerPartial(name, content);
+  }
+}
+
+/**
+ * Initialize the template engine
+ */
+function initialize() {
+  registerHelpers();
+  registerPartials();
+}
+
+/**
+ * Compile and render a template
+ * @param {string} templatePath - Path to the template file
+ * @param {object} context - Context data for rendering
+ * @returns {string} Rendered content
+ */
+function renderTemplate(templatePath, context) {
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Template not found: ${templatePath}`);
+  }
+
+  const source = fs.readFileSync(templatePath, 'utf-8');
+  const template = Handlebars.compile(source, { noEscape: false });
+  return template(context);
+}
+
+/**
+ * Render a template by name (looks in templates/handlebars/)
+ * @param {string} templateName - Template name (without .hbs extension)
+ * @param {object} context - Context data for rendering
+ * @returns {string} Rendered content
+ */
+function renderTemplateByName(templateName, context) {
+  const templatePath = path.join(TEMPLATES_DIR, `${templateName}.hbs`);
+  return renderTemplate(templatePath, context);
+}
+
+/**
+ * Parse multi-file output from rendered template (for Antigravity)
+ * @param {string} rendered - Rendered template content with file markers
+ * @returns {object[]} Array of { filename, content } objects
+ */
+function parseMultiFileOutput(rendered) {
+  const files = [];
+  const parts = rendered.split('<<<FILE_START:');
+
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    const endMarkerIndex = part.indexOf('>>>');
+
+    if (endMarkerIndex === -1) continue;
+
+    const filename = part.substring(0, endMarkerIndex);
+    const rest = part.substring(endMarkerIndex + 3);
+
+    const fileEndIndex = rest.indexOf('<<<FILE_END>>>');
+    const content = fileEndIndex !== -1
+      ? rest.substring(0, fileEndIndex).trim()
+      : rest.trim();
+
+    files.push({ filename, content });
+  }
+
+  return files;
+}
+
+/**
+ * Render a multi-file template (for Antigravity)
+ * @param {string} templatePath - Path to the template file
+ * @param {object} context - Context data for rendering
+ * @returns {object[]} Array of { filename, content } objects
+ */
+function renderMultiFileTemplate(templatePath, context) {
+  const rendered = renderTemplate(templatePath, context);
+  return parseMultiFileOutput(rendered);
+}
+
+/**
+ * Get available template names
+ * @returns {string[]} Array of template names
+ */
+function getAvailableTemplates() {
+  if (!fs.existsSync(TEMPLATES_DIR)) {
+    return [];
+  }
+
+  return fs.readdirSync(TEMPLATES_DIR)
+    .filter(f => f.endsWith('.hbs') && !fs.statSync(path.join(TEMPLATES_DIR, f)).isDirectory())
+    .map(f => path.basename(f, '.hbs'));
+}
+
+/**
+ * Build default context from analysis results
+ * @param {object} analysis - Analysis results from static analyzer
+ * @param {object} config - Configuration from CLI
+ * @returns {object} Context object for templates
+ */
+function buildContext(analysis, config) {
+  const projectName = config.projectName || 'project';
+  const techStack = analysis.techStack || config.techStack || {};
+
+  return {
+    // Project identity
+    project: {
+      name: projectName,
+      description: config.description || `${projectName} application`,
+      tech_stack: techStack.languages || [],
+      primary_language: techStack.languages?.[0] || 'unknown'
+    },
+
+    // Architecture (from analysis)
+    architecture: {
+      pattern: analysis.architecture?.pattern || 'layered',
+      layers: (analysis.architecture?.layers || []).map(l => ({
+        name: l.name,
+        path: l.directories?.[0] || l.name + '/',
+        purpose: l.purpose || l.name
+      }))
+    },
+
+    // Workflows (from analysis)
+    workflows: (analysis.workflows || []).map(wf => ({
+      name: wf.name,
+      category: wf.category || 'general',
+      complexity: wf.complexity || 'MEDIUM',
+      description: wf.description || `Handles ${wf.name} functionality`,
+      files: wf.files || [],
+      entry_points: (wf.entryPoints || []).map(ep => ({
+        endpoint: ep.route || ep.name || 'unknown',
+        file: ep.file,
+        line: ep.line,
+        method: ep.method || 'GET',
+        purpose: ep.purpose || 'Entry point'
+      }))
+    })),
+
+    // Gotchas (empty by default, filled by AI or manual)
+    gotchas: [],
+
+    // Key files (from analysis)
+    key_files: {
+      entry_points: (analysis.entryPoints || []).map(ep => ep.file),
+      api_routes: [],
+      config: [],
+      models: []
+    },
+
+    // Commands (from tech stack)
+    commands: {
+      install: techStack.commands?.install || 'npm install',
+      dev: techStack.commands?.dev || 'npm run dev',
+      test: techStack.commands?.test || 'npm test',
+      build: techStack.commands?.build || 'npm run build'
+    },
+
+    // Environment
+    environment: {
+      required: [],
+      optional: []
+    },
+
+    // Critical constraints
+    critical_constraints: [],
+
+    // Metadata
+    metadata: {
+      header: '<!-- Auto-generated by AI Context Engineering. Do not edit manually. -->',
+      timestamp: new Date().toISOString(),
+      generator_version: getPackageVersion(),
+      source_ref: projectName
+    },
+
+    // Registry (for federation compatibility)
+    registry: {
+      name: projectName,
+      submodule: projectName,
+      description: config.description || `${projectName} application`,
+      tech_stack: techStack.languages || [],
+      primary_language: techStack.languages?.[0] || 'unknown',
+      architecture: {
+        pattern: analysis.architecture?.pattern || 'layered',
+        layers: (analysis.architecture?.layers || []).map(l => l.name || l),
+        dependencies: {}
+      },
+      key_files: {
+        entry_points: (analysis.entryPoints || []).map(ep => ep.file),
+        api_routes: [],
+        core: [],
+        config: []
+      },
+      commands: {
+        install: techStack.commands?.install || 'npm install',
+        run: techStack.commands?.dev || 'npm run dev',
+        test: techStack.commands?.test || 'npm test',
+        build: techStack.commands?.build || 'npm run build'
+      },
+      environment: {
+        required: [],
+        optional: []
+      },
+      critical_constraints: [],
+      integrations: {
+        external: {},
+        internal: {}
+      }
+    },
+
+    // Submodule (for federation compatibility)
+    submodule: {
+      ports: {
+        default: 3000
+      }
+    },
+
+    // Cross-repo references (for federation)
+    cross_repos: [],
+
+    // Active task (for task dispatch)
+    active_task: null,
+
+    // Federation info
+    federation: {
+      is_federated: false,
+      subproject: null,
+      cross_repos: []
+    }
+  };
+}
+
+/**
+ * Get package version
+ * @returns {string} Package version
+ */
+function getPackageVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version || '2.0.0';
+  } catch {
+    return '2.0.0';
+  }
+}
+
+// Initialize on module load
+initialize();
+
+module.exports = {
+  renderTemplate,
+  renderTemplateByName,
+  renderMultiFileTemplate,
+  parseMultiFileOutput,
+  buildContext,
+  registerPartials,
+  registerHelpers,
+  initialize,
+  getAvailableTemplates,
+  TEMPLATES_DIR
+};

package/lib/validate.js

@@ -0,0 +1,155 @@
+/**
+ * AI Context Engineering - Installation Validator
+ *
+ * Validates the installation was successful.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Context directory and file names
+ */
+const AI_CONTEXT_DIR = '.ai-context';
+const AI_CONTEXT_FILE = 'AI_CONTEXT.md';
+
+/**
+ * Required files and directories for a valid installation
+ */
+const REQUIRED_STRUCTURE = {
+  directories: [
+    AI_CONTEXT_DIR,
+    `${AI_CONTEXT_DIR}/context`,
+    `${AI_CONTEXT_DIR}/research`,
+    `${AI_CONTEXT_DIR}/plans`,
+  ],
+  files: [
+    AI_CONTEXT_FILE,
+    `${AI_CONTEXT_DIR}/README.md`,
+    `${AI_CONTEXT_DIR}/settings.json`,
+    `${AI_CONTEXT_DIR}/context/WORKFLOW_INDEX.md`,
+  ],
+};
+
+/**
+ * Validate the installation
+ */
+async function validateInstallation(targetDir) {
+  const result = {
+    passed: true,
+    warnings: 0,
+    errors: 0,
+    checks: [],
+  };
+
+  // Check required directories
+  for (const dir of REQUIRED_STRUCTURE.directories) {
+    const fullPath = path.join(targetDir, dir);
+    const exists = fs.existsSync(fullPath);
+
+    result.checks.push({
+      type: 'directory',
+      path: dir,
+      status: exists ? 'PASS' : 'FAIL',
+    });
+
+    if (!exists) {
+      result.errors++;
+      result.passed = false;
+    }
+  }
+
+  // Check required files
+  for (const file of REQUIRED_STRUCTURE.files) {
+    const fullPath = path.join(targetDir, file);
+    const exists = fs.existsSync(fullPath);
+
+    result.checks.push({
+      type: 'file',
+      path: file,
+      status: exists ? 'PASS' : 'FAIL',
+    });
+
+    if (!exists) {
+      result.errors++;
+      result.passed = false;
+    }
+  }
+
+  // Check for remaining placeholders in key files
+  const filesToCheck = [
+    AI_CONTEXT_FILE,
+    `${AI_CONTEXT_DIR}/README.md`,
+    `${AI_CONTEXT_DIR}/settings.json`,
+  ];
+
+  for (const file of filesToCheck) {
+    const fullPath = path.join(targetDir, file);
+    if (fs.existsSync(fullPath)) {
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const placeholders = content.match(/\{\{[A-Z_]+\}\}/g) || [];
+
+      if (placeholders.length > 0) {
+        result.checks.push({
+          type: 'placeholders',
+          path: file,
+          status: 'WARN',
+          details: `${placeholders.length} placeholders remaining`,
+        });
+        result.warnings++;
+      }
+    }
+  }
+
+  // Validate settings.json is valid JSON
+  const settingsPath = path.join(targetDir, AI_CONTEXT_DIR, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      result.checks.push({
+        type: 'json',
+        path: `${AI_CONTEXT_DIR}/settings.json`,
+        status: 'PASS',
+      });
+    } catch (e) {
+      result.checks.push({
+        type: 'json',
+        path: `${AI_CONTEXT_DIR}/settings.json`,
+        status: 'FAIL',
+        details: 'Invalid JSON',
+      });
+      result.errors++;
+      result.passed = false;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Count files in a directory
+ */
+function countFiles(dir, pattern = '*') {
+  if (!fs.existsSync(dir)) return 0;
+
+  let count = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isFile()) {
+      count++;
+    } else if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name), pattern);
+    }
+  }
+
+  return count;
+}
+
+module.exports = {
+  validateInstallation,
+  countFiles,
+  REQUIRED_STRUCTURE,
+  AI_CONTEXT_DIR,
+  AI_CONTEXT_FILE,
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "create-universal-ai-context",
+  "version": "2.0.0",
+  "description": "Universal AI Context Engineering - Set up context for Claude, Copilot, Cline, Antigravity, and more",
+  "main": "lib/index.js",
+  "bin": {
+    "create-ai-context": "./bin/create-ai-context.js"
+  },
+  "type": "commonjs",
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "schemas/"
+  ],
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint lib/",
+    "cli:help": "node bin/create-ai-context.js --help"
+  },
+  "keywords": [
+    "ai-context",
+    "context-engineering",
+    "claude",
+    "claude-code",
+    "copilot",
+    "github-copilot",
+    "cline",
+    "antigravity",
+    "cursor",
+    "windsurf",
+    "aider",
+    "ai",
+    "llm",
+    "documentation",
+    "cli",
+    "scaffolding",
+    "monorepo",
+    "federation"
+  ],
+  "author": "SireJeff",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SireJeff/claude-context-engineering-template.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SireJeff/claude-context-engineering-template/issues"
+  },
+  "homepage": "https://github.com/SireJeff/claude-context-engineering-template#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "enquirer": "^2.4.1",
+    "ora": "^5.4.1",
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "glob": "^10.3.10",
+    "yaml": "^2.3.4",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "handlebars": "^4.7.8"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}