aios-core 2.1.0

package/.aios-core/product/templates/engine/loader.js

@@ -0,0 +1,231 @@
+/**
+ * Template Loader Module
+ * Responsible for loading and parsing Handlebars templates with YAML frontmatter
+ *
+ * @module loader
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const fs = require('fs').promises;
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Parse template content separating frontmatter from body
+ * @param {string} content - Raw template content
+ * @returns {Object} Parsed template with metadata and body
+ */
+function parseTemplate(content) {
+  // Normalize line endings to Unix-style for consistent parsing
+  const normalizedContent = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+  const match = normalizedContent.match(frontmatterRegex);
+
+  if (!match) {
+    throw new Error('Invalid template format: missing YAML frontmatter');
+  }
+
+  const [, frontmatter, body] = match;
+  let metadata;
+
+  try {
+    metadata = yaml.load(frontmatter);
+  } catch (error) {
+    throw new Error(`Failed to parse template frontmatter: ${error.message}`);
+  }
+
+  return {
+    metadata,
+    body: body.trim(),
+  };
+}
+
+/**
+ * Validate template metadata structure
+ * @param {Object} metadata - Template metadata from frontmatter
+ * @throws {Error} If required fields are missing or metadata is invalid
+ */
+function validateMetadata(metadata) {
+  // Guard against non-object metadata (null, undefined, scalar values)
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    throw new Error('Template metadata must be a valid object');
+  }
+
+  const requiredFields = ['template_id', 'template_name', 'version'];
+  const missingFields = requiredFields.filter(field => !metadata[field]);
+
+  if (missingFields.length > 0) {
+    throw new Error(`Template missing required fields: ${missingFields.join(', ')}`);
+  }
+
+  if (metadata.variables && !Array.isArray(metadata.variables)) {
+    throw new Error('Template variables must be an array');
+  }
+}
+
+/**
+ * TemplateLoader class for loading and managing templates
+ */
+class TemplateLoader {
+  /**
+   * Create a TemplateLoader instance
+   * @param {Object} options - Configuration options
+   * @param {string} options.templatesDir - Path to templates directory
+   */
+  constructor(options = {}) {
+    this.templatesDir = options.templatesDir ||
+      path.join(process.cwd(), '.aios-core', 'product', 'templates');
+    this.cache = new Map();
+  }
+
+  /**
+   * Load a template by type
+   * @param {string} templateType - Template type (prd, adr, pmdr, dbdr, story, epic, task)
+   * @param {Object} options - Load options
+   * @param {boolean} options.useCache - Whether to use cached template (default: true)
+   * @returns {Promise<Object>} Loaded template object
+   */
+  async load(templateType, options = {}) {
+    const { useCache = true } = options;
+
+    if (useCache && this.cache.has(templateType)) {
+      return this.cache.get(templateType);
+    }
+
+    const templatePath = this.resolveTemplatePath(templateType);
+
+    let content;
+    try {
+      content = await fs.readFile(templatePath, 'utf-8');
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`Template not found: ${templateType} (${templatePath})`);
+      }
+      throw new Error(`Failed to read template ${templateType}: ${error.message}`);
+    }
+
+    const { metadata, body } = parseTemplate(content);
+    validateMetadata(metadata);
+
+    const template = {
+      type: templateType,
+      path: templatePath,
+      metadata,
+      body,
+      variables: this.normalizeVariables(metadata.variables || []),
+    };
+
+    if (useCache) {
+      this.cache.set(templateType, template);
+    }
+
+    return template;
+  }
+
+  /**
+   * Resolve the file path for a template type
+   * @param {string} templateType - Template type identifier
+   * @returns {string} Full path to template file
+   */
+  resolveTemplatePath(templateType) {
+    const extensions = ['.hbs', '.handlebars', '.md'];
+
+    // Handle versioned templates (e.g., prd-v2 -> prd-v2.0.hbs)
+    const templateAliases = {
+      'prd-v2': 'prd-v2.0',
+    };
+
+    const templateName = templateAliases[templateType] || templateType;
+    const basePath = path.join(this.templatesDir, templateName);
+
+    // Try each extension
+    for (const ext of extensions) {
+      const fullPath = basePath + ext;
+      try {
+        require('fs').accessSync(fullPath);
+        return fullPath;
+      } catch {
+        // Continue to next extension
+      }
+    }
+
+    // Default to .hbs if none found
+    return basePath + '.hbs';
+  }
+
+  /**
+   * Normalize variable definitions to consistent format
+   * @param {Array} variables - Raw variable definitions
+   * @returns {Array} Normalized variable definitions
+   */
+  normalizeVariables(variables) {
+    return variables.map(variable => ({
+      name: variable.name,
+      type: variable.type || 'string',
+      // Variables with requiredIf are NOT required by default - they're conditionally required
+      required: variable.requiredIf ? false : (variable.required !== false),
+      requiredIf: variable.requiredIf,
+      default: variable.default,
+      prompt: variable.prompt || `Enter ${variable.name}:`,
+      choices: variable.choices,
+      auto: variable.auto,
+      validation: variable.validation,
+    }));
+  }
+
+  /**
+   * List all available templates
+   * @returns {Promise<Array>} List of template types
+   */
+  async listTemplates() {
+    try {
+      const files = await fs.readdir(this.templatesDir);
+      const templates = [];
+
+      for (const file of files) {
+        if (file.endsWith('.hbs') || file.endsWith('.handlebars')) {
+          const type = path.basename(file, path.extname(file));
+          templates.push(type);
+        }
+      }
+
+      return templates;
+    } catch (error) {
+      throw new Error(`Failed to list templates: ${error.message}`);
+    }
+  }
+
+  /**
+   * Clear the template cache
+   * @param {string} templateType - Specific template to clear, or all if not provided
+   */
+  clearCache(templateType) {
+    if (templateType) {
+      this.cache.delete(templateType);
+    } else {
+      this.cache.clear();
+    }
+  }
+
+  /**
+   * Check if a template exists
+   * @param {string} templateType - Template type to check
+   * @returns {Promise<boolean>} True if template exists
+   */
+  async exists(templateType) {
+    try {
+      await this.load(templateType, { useCache: false });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+module.exports = {
+  TemplateLoader,
+  parseTemplate,
+  validateMetadata,
+};

package/.aios-core/product/templates/engine/renderer.js

@@ -0,0 +1,343 @@
+/**
+ * Handlebars Renderer Module
+ * Handles template rendering with custom helpers
+ *
+ * @module renderer
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const Handlebars = require('handlebars');
+
+/**
+ * Register default Handlebars helpers
+ * @param {Object} handlebars - Handlebars instance
+ */
+function registerDefaultHelpers(handlebars) {
+  // Pad number with leading zeros
+  handlebars.registerHelper('padNumber', (num, length) => {
+    return String(num).padStart(length, '0');
+  });
+
+  // Format date with pattern
+  handlebars.registerHelper('formatDate', (date, format) => {
+    const d = date instanceof Date ? date : new Date(date);
+
+    const patterns = {
+      'YYYY': d.getFullYear(),
+      'MM': String(d.getMonth() + 1).padStart(2, '0'),
+      'DD': String(d.getDate()).padStart(2, '0'),
+      'HH': String(d.getHours()).padStart(2, '0'),
+      'mm': String(d.getMinutes()).padStart(2, '0'),
+      'ss': String(d.getSeconds()).padStart(2, '0'),
+    };
+
+    let result = format;
+    for (const [pattern, value] of Object.entries(patterns)) {
+      result = result.replace(pattern, value);
+    }
+    return result;
+  });
+
+  // Add numbers
+  handlebars.registerHelper('add', (a, b) => a + b);
+
+  // Subtract numbers
+  handlebars.registerHelper('subtract', (a, b) => a - b);
+
+  // Multiply numbers
+  handlebars.registerHelper('multiply', (a, b) => a * b);
+
+  // Divide numbers
+  handlebars.registerHelper('divide', (a, b) => a / b);
+
+  // Check equality
+  handlebars.registerHelper('eq', (a, b) => a === b);
+
+  // Check not equal
+  handlebars.registerHelper('ne', (a, b) => a !== b);
+
+  // Greater than
+  handlebars.registerHelper('gt', (a, b) => a > b);
+
+  // Greater than or equal
+  handlebars.registerHelper('gte', (a, b) => a >= b);
+
+  // Less than
+  handlebars.registerHelper('lt', (a, b) => a < b);
+
+  // Less than or equal
+  handlebars.registerHelper('lte', (a, b) => a <= b);
+
+  // Logical AND
+  handlebars.registerHelper('and', (...args) => {
+    args.pop(); // Remove options object
+    return args.every(Boolean);
+  });
+
+  // Logical OR
+  handlebars.registerHelper('or', (...args) => {
+    args.pop(); // Remove options object
+    return args.some(Boolean);
+  });
+
+  // Logical NOT
+  handlebars.registerHelper('not', (value) => !value);
+
+  // Uppercase string
+  handlebars.registerHelper('uppercase', (str) => {
+    return str ? String(str).toUpperCase() : '';
+  });
+
+  // Lowercase string
+  handlebars.registerHelper('lowercase', (str) => {
+    return str ? String(str).toLowerCase() : '';
+  });
+
+  // Capitalize first letter
+  handlebars.registerHelper('capitalize', (str) => {
+    if (!str) return '';
+    const s = String(str);
+    return s.charAt(0).toUpperCase() + s.slice(1);
+  });
+
+  // Title case string
+  handlebars.registerHelper('titlecase', (str) => {
+    if (!str) return '';
+    return String(str)
+      .split(' ')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join(' ');
+  });
+
+  // Join array with separator
+  handlebars.registerHelper('join', (array, separator) => {
+    if (!Array.isArray(array)) return '';
+    return array.join(typeof separator === 'string' ? separator : ', ');
+  });
+
+  // Get array length
+  handlebars.registerHelper('length', (array) => {
+    return Array.isArray(array) ? array.length : 0;
+  });
+
+  // Check if array includes value
+  handlebars.registerHelper('includes', (array, value) => {
+    return Array.isArray(array) && array.includes(value);
+  });
+
+  // First element of array
+  handlebars.registerHelper('first', (array) => {
+    return Array.isArray(array) && array.length > 0 ? array[0] : null;
+  });
+
+  // Last element of array
+  handlebars.registerHelper('last', (array) => {
+    return Array.isArray(array) && array.length > 0 ? array[array.length - 1] : null;
+  });
+
+  // Default value if undefined/null
+  handlebars.registerHelper('default', (value, defaultValue) => {
+    return value ?? defaultValue;
+  });
+
+  // JSON stringify
+  handlebars.registerHelper('json', (value, indent) => {
+    return JSON.stringify(value, null, typeof indent === 'number' ? indent : 2);
+  });
+
+  // Repeat block n times (with @index, @first, @last data variables)
+  handlebars.registerHelper('times', (n, options) => {
+    let result = '';
+    for (let i = 0; i < n; i++) {
+      // Create data frame to expose @index, @first, @last like built-in each
+      const data = options.data ? Handlebars.createFrame(options.data) : {};
+      data.index = i;
+      data.first = i === 0;
+      data.last = i === n - 1;
+      result += options.fn({ index: i, first: i === 0, last: i === n - 1 }, { data });
+    }
+    return result;
+  });
+
+  // Conditional block based on equality
+  handlebars.registerHelper('ifEqual', function(a, b, options) {
+    return a === b ? options.fn(this) : options.inverse(this);
+  });
+
+  // Conditional block based on inequality
+  handlebars.registerHelper('unlessEqual', function(a, b, options) {
+    return a !== b ? options.fn(this) : options.inverse(this);
+  });
+
+  // Slug helper (URL-safe string)
+  handlebars.registerHelper('slug', (str) => {
+    if (!str) return '';
+    return String(str)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+  });
+
+  // Truncate string
+  handlebars.registerHelper('truncate', (str, length, suffix) => {
+    if (!str) return '';
+    const s = String(str);
+    if (s.length <= length) return s;
+    return s.slice(0, length) + (typeof suffix === 'string' ? suffix : '...');
+  });
+
+  // Now helper for current date
+  handlebars.registerHelper('now', () => new Date());
+}
+
+/**
+ * TemplateRenderer class for rendering Handlebars templates
+ */
+class TemplateRenderer {
+  /**
+   * Create a TemplateRenderer instance
+   * @param {Object} options - Configuration options
+   */
+  constructor(options = {}) {
+    this.handlebars = Handlebars.create();
+    this.customHelpers = new Map();
+    registerDefaultHelpers(this.handlebars);
+
+    // Register any custom helpers from options
+    if (options.helpers) {
+      for (const [name, fn] of Object.entries(options.helpers)) {
+        this.registerHelper(name, fn);
+      }
+    }
+  }
+
+  /**
+   * Register a custom Handlebars helper
+   * @param {string} name - Helper name
+   * @param {Function} fn - Helper function
+   */
+  registerHelper(name, fn) {
+    this.handlebars.registerHelper(name, fn);
+    this.customHelpers.set(name, fn);
+  }
+
+  /**
+   * Register a partial template
+   * @param {string} name - Partial name
+   * @param {string} content - Partial content
+   */
+  registerPartial(name, content) {
+    this.handlebars.registerPartial(name, content);
+  }
+
+  /**
+   * Render a template with context
+   * @param {Object} template - Template object with body
+   * @param {Object} context - Variable values for rendering
+   * @returns {string} Rendered content
+   */
+  render(template, context = {}) {
+    const templateBody = typeof template === 'string' ? template : template.body;
+
+    try {
+      const compiledTemplate = this.handlebars.compile(templateBody, {
+        strict: false,
+        noEscape: true,
+      });
+
+      // Add metadata to context if available
+      const fullContext = {
+        ...context,
+        _template: template.metadata || {},
+        now: new Date(),
+      };
+
+      return compiledTemplate(fullContext);
+    } catch (error) {
+      throw new Error(`Template rendering failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Render a template string directly
+   * @param {string} templateString - Template string
+   * @param {Object} context - Variable values for rendering
+   * @returns {string} Rendered content
+   */
+  renderString(templateString, context = {}) {
+    return this.render(templateString, context);
+  }
+
+  /**
+   * Validate template syntax
+   * @param {string} templateBody - Template content to validate
+   * @returns {Object} Validation result with isValid and errors
+   */
+  validateSyntax(templateBody) {
+    try {
+      const compiled = this.handlebars.compile(templateBody);
+      // Also try to execute with empty context to catch parse errors
+      // that only manifest at execution time (e.g., incomplete expressions)
+      compiled({});
+      return { isValid: true, errors: [] };
+    } catch (error) {
+      return {
+        isValid: false,
+        errors: [error.message],
+      };
+    }
+  }
+
+  /**
+   * Extract variable references from template
+   * @param {string} templateBody - Template content
+   * @returns {Array<string>} List of variable names used in template
+   */
+  extractVariables(templateBody) {
+    const variables = new Set();
+
+    // Match {{variable}}, {{variable.property}}, {{#each variable}}, etc.
+    const regex = /\{\{[#/]?(?:each|if|unless|with)?\s*([a-zA-Z_][a-zA-Z0-9_.]*)/g;
+    let match;
+
+    while ((match = regex.exec(templateBody)) !== null) {
+      const variable = match[1].split('.')[0];
+      // Exclude helpers and special keywords
+      if (!this.isHelper(variable) && !this.isKeyword(variable)) {
+        variables.add(variable);
+      }
+    }
+
+    return Array.from(variables);
+  }
+
+  /**
+   * Check if name is a registered helper
+   * @param {string} name - Name to check
+   * @returns {boolean} True if helper exists
+   */
+  isHelper(name) {
+    return this.customHelpers.has(name) ||
+      ['padNumber', 'formatDate', 'add', 'subtract', 'eq', 'ne', 'gt', 'lt',
+        'gte', 'lte', 'and', 'or', 'not', 'uppercase', 'lowercase', 'capitalize',
+        'titlecase', 'join', 'length', 'includes', 'first', 'last', 'default',
+        'json', 'times', 'ifEqual', 'unlessEqual', 'slug', 'truncate', 'now',
+        'multiply', 'divide'].includes(name);
+  }
+
+  /**
+   * Check if name is a Handlebars keyword
+   * @param {string} name - Name to check
+   * @returns {boolean} True if keyword
+   */
+  isKeyword(name) {
+    return ['this', '@index', '@key', '@first', '@last', '@root'].includes(name);
+  }
+}
+
+module.exports = {
+  TemplateRenderer,
+  registerDefaultHelpers,
+};

package/.aios-core/product/templates/engine/schemas/adr.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ADR Template Variables",
+  "description": "Schema for Architecture Decision Record template variables",
+  "type": "object",
+  "required": ["number", "title", "status", "deciders", "context", "decision", "positiveConsequences"],
+  "properties": {
+    "number": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "ADR number for ordering and reference"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 5,
+      "maxLength": 100,
+      "description": "Short title describing the decision"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Proposed", "Accepted", "Deprecated", "Superseded"],
+      "description": "Current status of the decision"
+    },
+    "deciders": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Names of people involved in the decision"
+    },
+    "context": {
+      "type": "string",
+      "minLength": 20,
+      "description": "Context and background that led to this decision"
+    },
+    "decision": {
+      "type": "string",
+      "minLength": 20,
+      "description": "The decision being made"
+    },
+    "positiveConsequences": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "Positive outcomes of the decision"
+    },
+    "negativeConsequences": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Negative outcomes or trade-offs"
+    },
+    "alternatives": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "description"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Alternative option name"
+          },
+          "description": {
+            "type": "string",
+            "description": "Description of the alternative"
+          },
+          "pros": {
+            "type": "string",
+            "description": "Advantages of this alternative"
+          },
+          "cons": {
+            "type": "string",
+            "description": "Disadvantages of this alternative"
+          },
+          "whyNot": {
+            "type": "string",
+            "description": "Why this alternative was not chosen"
+          }
+        }
+      },
+      "description": "Alternative options considered"
+    },
+    "relatedADRs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["number", "title"],
+        "properties": {
+          "number": { "type": "integer" },
+          "title": { "type": "string" }
+        }
+      },
+      "description": "Related ADR references"
+    },
+    "references": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "External references and links"
+    },
+    "supersededBy": {
+      "type": "integer",
+      "description": "ADR number that supersedes this one"
+    }
+  }
+}