aios-core 2.1.0

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

@@ -0,0 +1,298 @@
+/**
+ * Variable Elicitation Module
+ * Handles interactive prompting for template variables using inquirer.js
+ *
+ * @module elicitation
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const inquirer = require('inquirer');
+
+/**
+ * Map template variable types to inquirer question types
+ * @param {string} type - Template variable type
+ * @returns {string} Inquirer question type
+ */
+function mapQuestionType(type) {
+  const typeMap = {
+    string: 'input',
+    text: 'editor',
+    number: 'number',
+    boolean: 'confirm',
+    choice: 'list',
+    multichoice: 'checkbox',
+    password: 'password',
+    array: 'input',
+  };
+
+  return typeMap[type] || 'input';
+}
+
+/**
+ * Create an inquirer question from a template variable
+ * @param {Object} variable - Template variable definition
+ * @param {Object} context - Existing context values
+ * @returns {Object} Inquirer question configuration
+ */
+function createQuestion(variable, context = {}) {
+  const question = {
+    type: mapQuestionType(variable.type),
+    name: variable.name,
+    message: variable.prompt,
+    default: context[variable.name] ?? variable.default,
+  };
+
+  // Add choices for choice/multichoice types
+  if (variable.choices) {
+    question.choices = variable.choices;
+  }
+
+  // Add validation
+  if (variable.required && variable.type !== 'boolean') {
+    question.validate = (input) => {
+      if (variable.type === 'array') {
+        return input && input.trim().length > 0 ? true : `${variable.name} is required`;
+      }
+      if (input === undefined || input === null || input === '') {
+        return `${variable.name} is required`;
+      }
+      return true;
+    };
+  }
+
+  // Add custom validation
+  if (variable.validation) {
+    const baseValidate = question.validate;
+    question.validate = (input) => {
+      if (baseValidate) {
+        const baseResult = baseValidate(input);
+        if (baseResult !== true) return baseResult;
+      }
+
+      if (variable.validation.minLength && input.length < variable.validation.minLength) {
+        return `${variable.name} must be at least ${variable.validation.minLength} characters`;
+      }
+      if (variable.validation.maxLength && input.length > variable.validation.maxLength) {
+        return `${variable.name} must be at most ${variable.validation.maxLength} characters`;
+      }
+      if (variable.validation.pattern) {
+        const regex = new RegExp(variable.validation.pattern);
+        if (!regex.test(input)) {
+          return variable.validation.message || `${variable.name} format is invalid`;
+        }
+      }
+
+      return true;
+    };
+  }
+
+  // Transform array input
+  if (variable.type === 'array') {
+    question.filter = (input) => {
+      if (typeof input === 'string') {
+        return input.split(',').map(s => s.trim()).filter(Boolean);
+      }
+      return input;
+    };
+  }
+
+  return question;
+}
+
+/**
+ * VariableElicitation class for handling interactive prompts
+ */
+class VariableElicitation {
+  /**
+   * Create a VariableElicitation instance
+   * @param {Object} options - Configuration options
+   * @param {boolean} options.interactive - Enable interactive mode (default: true)
+   */
+  constructor(options = {}) {
+    this.interactive = options.interactive !== false;
+    this.autoResolvers = new Map();
+    this.registerDefaultAutoResolvers();
+  }
+
+  /**
+   * Register default auto-resolvers for common auto values
+   */
+  registerDefaultAutoResolvers() {
+    // Next number resolvers
+    this.autoResolvers.set('next_adr_number', async () => this.getNextNumber('adr'));
+    this.autoResolvers.set('next_pmdr_number', async () => this.getNextNumber('pmdr'));
+    this.autoResolvers.set('next_dbdr_number', async () => this.getNextNumber('dbdr'));
+    this.autoResolvers.set('next_story_number', async () => this.getNextNumber('story'));
+    this.autoResolvers.set('next_epic_number', async () => this.getNextNumber('epic'));
+    this.autoResolvers.set('next_task_number', async () => this.getNextNumber('task'));
+
+    // Current date/time
+    this.autoResolvers.set('current_date', async () => new Date().toISOString().split('T')[0]);
+    this.autoResolvers.set('current_datetime', async () => new Date().toISOString());
+    this.autoResolvers.set('now', async () => new Date());
+  }
+
+  /**
+   * Get next number for a document type by scanning existing files
+   * @param {string} docType - Document type (adr, pmdr, etc.)
+   * @returns {Promise<number>} Next available number
+   */
+  async getNextNumber(docType) {
+    const fs = require('fs').promises;
+    const path = require('path');
+    const glob = require('glob');
+
+    const patterns = {
+      adr: 'docs/architecture/decisions/adr-*.md',
+      pmdr: 'docs/decisions/pmdr-*.md',
+      dbdr: 'docs/decisions/dbdr-*.md',
+      story: 'docs/stories/**/story-*.md',
+      epic: 'docs/epics/epic-*.md',
+      task: 'docs/tasks/task-*.md',
+    };
+
+    const pattern = patterns[docType] || `**/${docType}-*.md`;
+
+    try {
+      const files = glob.sync(pattern, { cwd: process.cwd() });
+      const numbers = files.map(f => {
+        const match = path.basename(f).match(new RegExp(`${docType}-(\\d+)`));
+        return match ? parseInt(match[1], 10) : 0;
+      });
+      return Math.max(...numbers, 0) + 1;
+    } catch {
+      return 1;
+    }
+  }
+
+  /**
+   * Register a custom auto-resolver
+   * @param {string} name - Resolver name (matches variable.auto value)
+   * @param {Function} resolver - Async function that returns the value
+   */
+  registerAutoResolver(name, resolver) {
+    this.autoResolvers.set(name, resolver);
+  }
+
+  /**
+   * Check if a variable's requiredIf condition is met
+   * @param {Object} variable - Variable with potential requiredIf condition
+   * @param {Object} values - Current values to check condition against
+   * @returns {boolean} True if variable should be required (condition met or no condition)
+   */
+  isConditionallyRequired(variable, values) {
+    if (!variable.requiredIf) {
+      return variable.required;
+    }
+    // requiredIf is the name of another variable that must be truthy
+    return !!values[variable.requiredIf];
+  }
+
+  /**
+   * Elicit values for template variables
+   * @param {Array} variables - Template variable definitions
+   * @param {Object} context - Pre-provided context values
+   * @returns {Promise<Object>} Collected variable values
+   */
+  async elicit(variables, context = {}) {
+    const values = { ...context };
+    const questions = [];
+
+    for (const variable of variables) {
+      // Skip if value already provided in context
+      if (context[variable.name] !== undefined) {
+        continue;
+      }
+
+      // Handle auto-resolved values
+      if (variable.auto && this.autoResolvers.has(variable.auto)) {
+        try {
+          values[variable.name] = await this.autoResolvers.get(variable.auto)();
+          continue;
+        } catch (error) {
+          console.warn(`Auto-resolver ${variable.auto} failed: ${error.message}`);
+        }
+      }
+
+      // Check if this is a conditionally required variable that should be skipped
+      // (e.g., userFlows is only needed when includeUIUX=true)
+      if (variable.requiredIf) {
+        const conditionMet = this.isConditionallyRequired(variable, values);
+        if (!conditionMet) {
+          // Skip this variable - its condition is not met
+          continue;
+        }
+      }
+
+      // Add to questions for interactive prompt
+      if (this.interactive) {
+        questions.push(createQuestion(variable, context));
+      } else if (variable.required && variable.default === undefined) {
+        throw new Error(`Required variable ${variable.name} has no default and interactive mode is disabled`);
+      } else {
+        values[variable.name] = variable.default;
+      }
+    }
+
+    // Prompt for remaining values
+    if (questions.length > 0 && this.interactive) {
+      const answers = await inquirer.prompt(questions);
+      Object.assign(values, answers);
+    }
+
+    return values;
+  }
+
+  /**
+   * Validate that all required variables have values
+   * @param {Array} variables - Template variable definitions
+   * @param {Object} values - Collected values
+   * @returns {Object} Validation result with isValid and errors
+   */
+  validate(variables, values) {
+    const errors = [];
+
+    for (const variable of variables) {
+      // Check if variable is required (either always or conditionally)
+      const isRequired = this.isConditionallyRequired(variable, values);
+
+      if (isRequired) {
+        const value = values[variable.name];
+        if (value === undefined || value === null || value === '') {
+          errors.push(`Missing required variable: ${variable.name}`);
+        }
+      }
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Merge context with defaults for non-interactive mode
+   * @param {Array} variables - Template variable definitions
+   * @param {Object} context - Provided context
+   * @returns {Object} Merged values with defaults
+   */
+  mergeDefaults(variables, context = {}) {
+    const values = { ...context };
+
+    for (const variable of variables) {
+      if (values[variable.name] === undefined && variable.default !== undefined) {
+        values[variable.name] = variable.default;
+      }
+    }
+
+    return values;
+  }
+}
+
+module.exports = {
+  VariableElicitation,
+  createQuestion,
+  mapQuestionType,
+};

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

@@ -0,0 +1,308 @@
+/**
+ * Template Engine v2.0
+ * Main entry point for the AIOS Template Engine
+ *
+ * @module TemplateEngine
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs').promises;
+const { TemplateLoader } = require('./loader');
+const { VariableElicitation } = require('./elicitation');
+const { TemplateRenderer } = require('./renderer');
+const { TemplateValidator } = require('./validator');
+
+/**
+ * Supported template types
+ * @constant {Array<string>}
+ */
+const SUPPORTED_TYPES = ['prd', 'prd-v2', 'adr', 'pmdr', 'dbdr', 'story', 'epic', 'task'];
+
+/**
+ * TemplateEngine class - Main orchestrator for template generation
+ */
+class TemplateEngine {
+  /**
+   * Create a TemplateEngine instance
+   * @param {Object} options - Configuration options
+   * @param {string} options.templatesDir - Path to templates directory
+   * @param {string} options.schemasDir - Path to schemas directory
+   * @param {boolean} options.interactive - Enable interactive mode (default: true)
+   * @param {Object} options.helpers - Custom Handlebars helpers
+   */
+  constructor(options = {}) {
+    // Store baseDir as instance property for predictable path resolution
+    this.baseDir = options.baseDir || process.cwd();
+
+    this.templatesDir = options.templatesDir ||
+      path.join(this.baseDir, '.aios-core', 'product', 'templates');
+
+    this.schemasDir = options.schemasDir ||
+      path.join(this.templatesDir, 'engine', 'schemas');
+
+    this.outputDir = options.outputDir ||
+      path.join(this.baseDir, 'docs');
+
+    this.interactive = options.interactive !== false;
+
+    // Initialize components
+    this.loader = new TemplateLoader({ templatesDir: this.templatesDir });
+    this.elicitation = new VariableElicitation({ interactive: this.interactive });
+    this.renderer = new TemplateRenderer({ helpers: options.helpers });
+    this.validator = new TemplateValidator({ schemasDir: this.schemasDir });
+  }
+
+  /**
+   * Get list of supported template types
+   * @returns {Array<string>} Supported template types
+   */
+  get supportedTypes() {
+    return [...SUPPORTED_TYPES];
+  }
+
+  /**
+   * Generate a document from a template
+   * @param {string} templateType - Template type (prd, adr, etc.)
+   * @param {Object} context - Pre-provided context values
+   * @param {Object} options - Generation options
+   * @param {boolean} options.validate - Validate output (default: true)
+   * @param {boolean} options.save - Save to file (default: false)
+   * @param {string} options.outputPath - Custom output path
+   * @returns {Promise<Object>} Generation result with content and metadata
+   */
+  async generate(templateType, context = {}, options = {}) {
+    const { validate = true, save = false, outputPath } = options;
+
+    // Validate template type
+    if (!SUPPORTED_TYPES.includes(templateType)) {
+      throw new Error(
+        `Unsupported template type: ${templateType}. ` +
+        `Supported types: ${SUPPORTED_TYPES.join(', ')}`,
+      );
+    }
+
+    // Load template
+    const template = await this.loader.load(templateType);
+
+    // Elicit variables
+    const variables = await this.elicitation.elicit(template.variables, context);
+
+    // Validate required variables
+    const elicitValidation = this.elicitation.validate(template.variables, variables);
+    if (!elicitValidation.isValid) {
+      throw new Error(`Missing required variables: ${elicitValidation.errors.join(', ')}`);
+    }
+
+    // Render template
+    const content = this.renderer.render(template, variables);
+
+    // Validate output if schema exists
+    let validation = { isValid: true, errors: [] };
+    if (validate) {
+      try {
+        validation = await this.validator.validate(variables, templateType);
+        if (!validation.isValid) {
+          console.warn('Template validation warnings:', validation.errors);
+        }
+      } catch (error) {
+        // Schema may not exist yet for all template types
+        if (!error.message.includes('Schema not found')) {
+          throw error;
+        }
+      }
+
+      // Also validate structure
+      const structureValidation = this.validator.validateStructure(content, template);
+      if (!structureValidation.isValid) {
+        validation.errors.push(...structureValidation.errors);
+        validation.isValid = validation.isValid && structureValidation.isValid;
+      }
+    }
+
+    const result = {
+      templateType,
+      content,
+      variables,
+      metadata: template.metadata,
+      validation,
+      generatedAt: new Date().toISOString(),
+    };
+
+    // Save to file if requested
+    if (save) {
+      const filePath = outputPath || this.resolveOutputPath(templateType, variables);
+      await this.saveOutput(content, filePath);
+      result.savedTo = filePath;
+    }
+
+    return result;
+  }
+
+  /**
+   * Resolve output path for generated document
+   * @param {string} templateType - Template type
+   * @param {Object} variables - Template variables
+   * @returns {string} Output file path
+   */
+  resolveOutputPath(templateType, variables) {
+    const outputDirs = {
+      prd: 'docs/prd',
+      'prd-v2': 'docs/prd',
+      adr: 'docs/architecture/decisions',
+      pmdr: 'docs/decisions',
+      dbdr: 'docs/decisions',
+      story: 'docs/stories',
+      epic: 'docs/epics',
+      task: 'docs/tasks',
+    };
+
+    const dir = outputDirs[templateType] || 'docs';
+    const number = variables.number ? `-${String(variables.number).padStart(3, '0')}` : '';
+    const slug = variables.title
+      ? `-${variables.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50)}`
+      : '';
+
+    // Use baseDir for predictable path resolution instead of fragile '..' navigation
+    return path.join(this.baseDir, dir, `${templateType}${number}${slug}.md`);
+  }
+
+  /**
+   * Save generated content to file
+   * @param {string} content - Content to save
+   * @param {string} filePath - Output file path
+   */
+  async saveOutput(content, filePath) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+  }
+
+  /**
+   * Preview template rendering without saving
+   * @param {string} templateType - Template type
+   * @param {Object} context - Context values
+   * @returns {Promise<string>} Rendered content preview
+   */
+  async preview(templateType, context = {}) {
+    const result = await this.generate(templateType, context, {
+      validate: false,
+      save: false,
+    });
+    return result.content;
+  }
+
+  /**
+   * Load and display template information
+   * @param {string} templateType - Template type
+   * @returns {Promise<Object>} Template information
+   */
+  async getTemplateInfo(templateType) {
+    const template = await this.loader.load(templateType);
+
+    return {
+      type: templateType,
+      name: template.metadata.template_name,
+      version: template.metadata.version,
+      variables: template.variables.map(v => ({
+        name: v.name,
+        type: v.type,
+        required: v.required,
+        description: v.prompt,
+      })),
+    };
+  }
+
+  /**
+   * List all available templates
+   * @returns {Promise<Array>} List of template information
+   */
+  async listTemplates() {
+    const templates = [];
+
+    for (const type of SUPPORTED_TYPES) {
+      try {
+        const info = await this.getTemplateInfo(type);
+        templates.push(info);
+      } catch {
+        // Template may not exist yet
+        templates.push({
+          type,
+          name: type.toUpperCase(),
+          version: 'N/A',
+          variables: [],
+          status: 'missing',
+        });
+      }
+    }
+
+    return templates;
+  }
+
+  /**
+   * Register a custom Handlebars helper
+   * @param {string} name - Helper name
+   * @param {Function} fn - Helper function
+   */
+  registerHelper(name, fn) {
+    this.renderer.registerHelper(name, fn);
+  }
+
+  /**
+   * Register a custom auto-resolver for elicitation
+   * @param {string} name - Resolver name
+   * @param {Function} resolver - Async resolver function
+   */
+  registerAutoResolver(name, resolver) {
+    this.elicitation.registerAutoResolver(name, resolver);
+  }
+
+  /**
+   * Validate an existing document against its schema
+   * @param {string} content - Document content
+   * @param {string} templateType - Template type
+   * @returns {Promise<Object>} Validation result
+   */
+  async validateDocument(content, templateType) {
+    const template = await this.loader.load(templateType);
+    const structureResult = this.validator.validateStructure(content, template);
+
+    // Extract data for schema validation
+    const data = this.validator.extractDataFromMarkdown(content, template);
+    let schemaResult = { isValid: true, errors: [] };
+
+    try {
+      schemaResult = await this.validator.validate(data, templateType);
+    } catch (error) {
+      if (!error.message.includes('Schema not found')) {
+        throw error;
+      }
+    }
+
+    return {
+      isValid: structureResult.isValid && schemaResult.isValid,
+      structureErrors: structureResult.errors,
+      schemaErrors: schemaResult.errors,
+    };
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache() {
+    this.loader.clearCache();
+    this.validator.clearCache();
+  }
+}
+
+// Export main class and components
+module.exports = {
+  TemplateEngine,
+  TemplateLoader,
+  VariableElicitation,
+  TemplateRenderer,
+  TemplateValidator,
+  SUPPORTED_TYPES,
+};