@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/src/commands/templates/template-customize.js

@@ -0,0 +1,101 @@
+/**
+ * Template Customize Command - Copy a framework template to project for customization
+ */
+
+import { copyFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { getTemplateById, resolveTemplatePathById } from '../../core/templates/template-registry.js';
+
+/**
+ * Customize template command - copies framework template to project .morph/templates/
+ */
+export async function templateCustomizeCommand(templateId, options) {
+  logger.header(`Customizing Template: ${templateId}`);
+  logger.blank();
+
+  try {
+    // 1. Validate template exists
+    const template = getTemplateById(templateId);
+
+    if (!template) {
+      logger.error(`Template not found: ${templateId}`);
+      logger.dim('\n💡 Use `morph-spec template list` to see available templates');
+      process.exit(1);
+    }
+
+    // 2. Check if template is framework (universal)
+    if (template.location !== 'framework') {
+      logger.warn(`Template "${templateId}" is already stack-specific`);
+      logger.dim(`  Located at: stacks/${template.stacks?.[0]}/.morph/templates/${template.path}`);
+      logger.dim('\n  You can edit it directly or copy to another stack.');
+      process.exit(0);
+    }
+
+    // 3. Resolve source path (framework template)
+    const projectPath = options.projectPath || process.cwd();
+    const sourcePath = resolveTemplatePathById(templateId, projectPath);
+
+    if (!sourcePath) {
+      logger.error(`Framework template file not found for ${templateId}`);
+      process.exit(1);
+    }
+
+    // 4. Determine destination (stack-specific or project-local)
+    const stackId = options.stack || 'blazor-azure';
+    const destDir = options.local
+      ? join(projectPath, '.morph/templates', dirname(template.path))
+      : join(projectPath, 'stacks', stackId, '.morph/templates', dirname(template.path));
+
+    const destPath = options.local
+      ? join(projectPath, '.morph/templates', template.path)
+      : join(projectPath, 'stacks', stackId, '.morph/templates', template.path);
+
+    // 5. Check if already exists
+    if (existsSync(destPath) && !options.force) {
+      logger.warn('Template already customized at this location');
+      logger.dim(`  ${destPath}`);
+      logger.dim('\n  Use --force to overwrite');
+      process.exit(1);
+    }
+
+    // 6. Copy template
+    logger.dim(`Source: ${sourcePath}`);
+    logger.dim(`Destination: ${destPath}`);
+    logger.blank();
+
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(sourcePath, destPath);
+
+    logger.success('✅ Template copied for customization');
+    logger.blank();
+
+    // 7. Show next steps
+    logger.info(chalk.bold('📝 Next Steps'));
+    console.log(chalk.dim('  1. Edit the template file:'));
+    console.log(chalk.cyan(`     ${destPath}`));
+    console.log(chalk.dim('\n  2. Template will now be used instead of framework version'));
+    console.log(chalk.dim('     (Stack-specific templates take precedence)'));
+    console.log(chalk.dim('\n  3. Test rendering:'));
+    console.log(chalk.cyan(`     morph-spec template render ${templateId} output.md '{"FEATURE_NAME":"test"}'`));
+
+    if (!options.local) {
+      console.log(chalk.dim('\n  4. To share across stacks, use --local flag'));
+    }
+
+    logger.blank();
+
+    // 8. Show warning about updates
+    logger.warn('⚠️  Customized templates won\'t receive framework updates');
+    logger.dim('   To get updates: delete customized version and re-run this command');
+    logger.blank();
+
+  } catch (error) {
+    logger.error(`Failed to customize template: ${error.message}`);
+    if (options.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}

package/src/commands/templates/template-list.js

@@ -0,0 +1,128 @@
+/**
+ * Template List Command - List all available templates with filtering
+ */
+
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import {
+  getAllTemplates,
+  getTemplatesByCategory,
+  getTemplatesByPhase,
+  getTemplatesByStack,
+  getRequiredTemplates,
+  getRegistryStats
+} from '../../core/templates/template-registry.js';
+
+/**
+ * Format template for display
+ */
+function formatTemplate(template) {
+  const { id, name, category, phase, required, stackSpecific, location, engine, deprecated } = template;
+
+  const badges = [];
+  if (required) badges.push(chalk.green('[REQUIRED]'));
+  if (deprecated) badges.push(chalk.red('[DEPRECATED]'));
+  if (stackSpecific) badges.push(chalk.yellow('[STACK-SPECIFIC]'));
+  else badges.push(chalk.cyan('[UNIVERSAL]'));
+  if (engine === 'handlebars') badges.push(chalk.blue('[HBS]'));
+
+  const badgeStr = badges.join(' ');
+
+  return {
+    id: chalk.bold(id),
+    name,
+    location: location === 'framework' ? chalk.cyan('framework') : chalk.yellow('stack'),
+    category: chalk.dim(category),
+    phase: chalk.dim(phase || 'N/A'),
+    badges: badgeStr
+  };
+}
+
+/**
+ * List templates command
+ */
+export async function templateListCommand(options) {
+  logger.header('MORPH-SPEC Templates');
+  logger.blank();
+
+  try {
+    let templates;
+
+    // Apply filters
+    if (options.category) {
+      templates = getTemplatesByCategory(options.category);
+      logger.dim(`Category: ${options.category}`);
+    } else if (options.phase) {
+      templates = getTemplatesByPhase(options.phase);
+      logger.dim(`Phase: ${options.phase}`);
+    } else if (options.stack) {
+      templates = getTemplatesByStack(options.stack);
+      logger.dim(`Stack: ${options.stack}`);
+    } else if (options.required) {
+      templates = getRequiredTemplates(options.stack);
+      logger.dim('Required templates only');
+    } else {
+      templates = getAllTemplates();
+      logger.dim('All templates');
+    }
+
+    logger.blank();
+
+    if (templates.length === 0) {
+      logger.warn('No templates found matching criteria');
+      return;
+    }
+
+    // Group by location if not filtered
+    if (!options.category && !options.phase) {
+      const frameworkTemplates = templates.filter(t => t.location === 'framework');
+      const stackTemplates = templates.filter(t => t.location === 'stack');
+
+      if (frameworkTemplates.length > 0) {
+        logger.info(chalk.bold.cyan(`\n📦 Universal Templates (${frameworkTemplates.length})`));
+        frameworkTemplates.forEach(t => {
+          const formatted = formatTemplate(t);
+          console.log(`  ${formatted.id.padEnd(30)} ${formatted.name.padEnd(40)} ${formatted.badges}`);
+        });
+      }
+
+      if (stackTemplates.length > 0) {
+        logger.info(chalk.bold.yellow(`\n📦 Stack-Specific Templates (${stackTemplates.length})`));
+        stackTemplates.forEach(t => {
+          const formatted = formatTemplate(t);
+          const stacks = t.stacks ? chalk.dim(`(${t.stacks.join(', ')})`) : '';
+          console.log(`  ${formatted.id.padEnd(30)} ${formatted.name.padEnd(40)} ${stacks} ${formatted.badges}`);
+        });
+      }
+    } else {
+      // Flat list
+      templates.forEach(t => {
+        const formatted = formatTemplate(t);
+        console.log(`  ${formatted.id.padEnd(30)} ${formatted.name.padEnd(40)} ${formatted.location.padEnd(15)} ${formatted.badges}`);
+      });
+    }
+
+    // Show statistics
+    if (!options.category && !options.phase && !options.stack && !options.required) {
+      logger.blank();
+      const stats = getRegistryStats();
+      logger.info(chalk.bold('\n📊 Statistics'));
+      console.log(`  Total Templates: ${chalk.green(stats.total)}`);
+      console.log(`  Framework: ${chalk.cyan(stats.framework)}`);
+      console.log(`  Blazor-Azure: ${chalk.yellow(stats.blazorAzure)}`);
+      console.log(`  Next.js-Supabase: ${chalk.yellow(stats.nextjsSupabase)}`);
+      console.log(`  Required: ${chalk.green(stats.required)}`);
+      console.log(`  Optional: ${chalk.dim(stats.optional)}`);
+    }
+
+    logger.blank();
+
+    // Show usage hint
+    logger.dim('💡 Use `morph-spec template show <id>` to see template details');
+    logger.blank();
+
+  } catch (error) {
+    logger.error(`Failed to list templates: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/templates/template-render.js

@@ -0,0 +1,95 @@
+/**
+ * Template Render Command - Render a template by ID with variables
+ */
+
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { getTemplateById, resolveTemplatePathById } from '../../core/templates/template-registry.js';
+import { renderTemplate } from '../../core/templates/template-renderer.js';
+
+/**
+ * Render template command
+ */
+export async function templateRenderCommand(templateId, outputPath, variablesJson, options) {
+  logger.header(`Rendering Template: ${templateId}`);
+  logger.blank();
+
+  try {
+    // 1. Validate template exists
+    const template = getTemplateById(templateId);
+
+    if (!template) {
+      logger.error(`Template not found: ${templateId}`);
+      logger.dim('\n💡 Use `morph-spec template list` to see available templates');
+      process.exit(1);
+    }
+
+    // 2. Resolve template path
+    const projectPath = options.projectPath || process.cwd();
+    const stackId = options.stack || 'blazor-azure';
+    const templatePath = resolveTemplatePathById(templateId, projectPath, stackId);
+
+    if (!templatePath) {
+      logger.error(`Template file not found for ${templateId}`);
+      logger.dim('  Searched in: framework/templates/ and stack templates');
+      process.exit(1);
+    }
+
+    logger.dim(`Template: ${templatePath}`);
+
+    // 3. Parse variables
+    let variables = {};
+    try {
+      variables = JSON.parse(variablesJson);
+    } catch (error) {
+      logger.error('Invalid JSON in variables argument');
+      logger.dim(`  ${error.message}`);
+      process.exit(1);
+    }
+
+    // 4. Add default variables
+    const defaults = {
+      DATE: new Date().toISOString().split('T')[0],
+      YEAR: new Date().getFullYear().toString(),
+      TIMESTAMP: new Date().toISOString()
+    };
+
+    const allVariables = { ...defaults, ...variables };
+
+    logger.dim(`Variables: ${Object.keys(allVariables).length} provided`);
+    logger.blank();
+
+    // 5. Render template
+    const renderedContent = renderTemplate(templatePath, allVariables);
+
+    // 6. Output
+    if (options.dryRun) {
+      logger.info(chalk.cyan('📋 DRY RUN - Preview (file will NOT be written)'));
+      logger.blank();
+      console.log(renderedContent);
+      logger.blank();
+      logger.dim(`Would be written to: ${outputPath}`);
+    } else {
+      // Create output directory if needed
+      const outputDir = dirname(outputPath);
+      mkdirSync(outputDir, { recursive: true });
+
+      // Write file
+      writeFileSync(outputPath, renderedContent, 'utf-8');
+
+      logger.success(`✅ Template rendered successfully`);
+      logger.dim(`  Output: ${chalk.cyan(outputPath)}`);
+    }
+
+    logger.blank();
+
+  } catch (error) {
+    logger.error(`Failed to render template: ${error.message}`);
+    if (options.verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}

package/src/commands/templates/template-show.js

@@ -0,0 +1,131 @@
+/**
+ * Template Show Command - Display detailed information about a template
+ */
+
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { getTemplateById, resolveTemplatePathById } from '../../core/templates/template-registry.js';
+import { readFileSync, existsSync } from 'fs';
+
+/**
+ * Show template details command
+ */
+export async function templateShowCommand(templateId, options) {
+  logger.header(`Template: ${templateId}`);
+  logger.blank();
+
+  try {
+    const template = getTemplateById(templateId);
+
+    if (!template) {
+      logger.error(`Template not found: ${templateId}`);
+      logger.dim('\n💡 Use `morph-spec template list` to see available templates');
+      process.exit(1);
+    }
+
+    // Display template metadata
+    logger.info(chalk.bold('📋 Metadata'));
+    console.log(`  ID: ${chalk.cyan(template.id)}`);
+    console.log(`  Name: ${chalk.green(template.name)}`);
+    console.log(`  Path: ${chalk.dim(template.path)}`);
+    console.log(`  Location: ${template.location === 'framework' ? chalk.cyan('framework') : chalk.yellow('stack')}`);
+    console.log(`  Category: ${template.category}`);
+    console.log(`  Phase: ${template.phase || 'N/A'}`);
+    console.log(`  Required: ${template.required ? chalk.green('Yes') : chalk.dim('No')}`);
+    console.log(`  Stack-Specific: ${template.stackSpecific ? chalk.yellow('Yes') : chalk.cyan('No (universal)')}`);
+
+    if (template.stackSpecific && template.stacks) {
+      console.log(`  Stacks: ${chalk.yellow(template.stacks.join(', '))}`);
+    }
+
+    console.log(`  Engine: ${template.engine === 'handlebars' ? chalk.blue('Handlebars') : chalk.dim('Custom')}`);
+
+    if (template.deprecated) {
+      console.log(`  ${chalk.red.bold('⚠️  DEPRECATED')}`);
+    }
+
+    if (template.autoGenerated) {
+      console.log(`  ${chalk.dim('Auto-generated (not user-facing)')}`);
+    }
+
+    logger.blank();
+
+    // Description
+    if (template.description) {
+      logger.info(chalk.bold('📝 Description'));
+      console.log(`  ${template.description}`);
+      logger.blank();
+    }
+
+    // Placeholders
+    if (template.placeholders && template.placeholders.length > 0) {
+      logger.info(chalk.bold('🔑 Variables'));
+      template.placeholders.forEach(p => {
+        console.log(`  ${chalk.cyan(`{{${p}}}`)}`);
+      });
+      logger.blank();
+    }
+
+    // Output name
+    if (template.outputName) {
+      logger.info(chalk.bold('📄 Output Name'));
+      console.log(`  ${chalk.dim(template.outputName)}`);
+      logger.blank();
+    }
+
+    // Resolve actual path
+    if (options.showPath) {
+      const projectPath = options.projectPath || process.cwd();
+      const stackId = options.stack || 'blazor-azure';
+      const resolvedPath = resolveTemplatePathById(templateId, projectPath, stackId);
+
+      logger.info(chalk.bold('📂 Resolved Path'));
+      if (resolvedPath) {
+        console.log(`  ${chalk.green(resolvedPath)}`);
+        console.log(`  ${chalk.dim(`(${existsSync(resolvedPath) ? 'exists' : 'not found'})`)}`);
+      } else {
+        console.log(`  ${chalk.red('Not found in framework/ or stack/')}`);
+      }
+      logger.blank();
+    }
+
+    // Show template preview
+    if (options.preview) {
+      const projectPath = options.projectPath || process.cwd();
+      const stackId = options.stack || 'blazor-azure';
+      const resolvedPath = resolveTemplatePathById(templateId, projectPath, stackId);
+
+      if (resolvedPath && existsSync(resolvedPath)) {
+        logger.info(chalk.bold('👁️  Preview (first 20 lines)'));
+        logger.blank();
+
+        const content = readFileSync(resolvedPath, 'utf-8');
+        const lines = content.split('\n').slice(0, 20);
+
+        lines.forEach((line, i) => {
+          console.log(chalk.dim(`${String(i + 1).padStart(3)}  ${line}`));
+        });
+
+        if (content.split('\n').length > 20) {
+          logger.blank();
+          logger.dim(`  ... (${content.split('\n').length - 20} more lines)`);
+        }
+
+        logger.blank();
+      } else {
+        logger.warn('Template file not found - cannot preview');
+      }
+    }
+
+    // Show usage hint
+    if (template.engine === 'handlebars') {
+      logger.info(chalk.bold('💡 Usage Hint'));
+      console.log(chalk.dim(`  morph-spec template render ${templateId} output.md '{"FEATURE_NAME":"my-feature"}'`));
+      logger.blank();
+    }
+
+  } catch (error) {
+    logger.error(`Failed to show template: ${error.message}`);
+    process.exit(1);
+  }
+}

package/src/commands/templates/template-validate.js

@@ -0,0 +1,91 @@
+/**
+ * Template Validate Command - Validate Handlebars templates
+ */
+
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { validateTemplate, validateAllTemplates, formatValidationResults, summarizeValidation } from '../../core/templates/template-validator.js';
+
+/**
+ * Validate template(s) command
+ */
+export async function templateValidateCommand(templateId, options) {
+  const projectPath = options.projectPath || process.cwd();
+
+  if (templateId) {
+    // Validate single template
+    logger.header(`Validating Template: ${templateId}`);
+    logger.blank();
+
+    const result = validateTemplate(templateId, projectPath);
+
+    // Display results
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+      logger.success(`✅ Template is valid`);
+      logger.blank();
+
+      if (result.info.length > 0 && options.verbose) {
+        logger.info(chalk.bold('ℹ️  Information'));
+        result.info.forEach(info => console.log(chalk.dim(`  ${info}`)));
+        logger.blank();
+      }
+    } else {
+      if (result.errors.length > 0) {
+        logger.error(chalk.bold('❌ Errors'));
+        result.errors.forEach(error => console.log(chalk.red(`  - ${error}`)));
+        logger.blank();
+      }
+
+      if (result.warnings.length > 0) {
+        logger.warn(chalk.bold('⚠️  Warnings'));
+        result.warnings.forEach(warning => console.log(chalk.yellow(`  - ${warning}`)));
+        logger.blank();
+      }
+
+      if (result.info.length > 0 && options.verbose) {
+        logger.info(chalk.bold('ℹ️  Information'));
+        result.info.forEach(info => console.log(chalk.dim(`  ${info}`)));
+        logger.blank();
+      }
+
+      if (result.errors.length > 0) {
+        process.exit(1);
+      }
+    }
+  } else {
+    // Validate all templates
+    logger.header('Validating All Templates');
+    logger.blank();
+
+    const validationOptions = {
+      skipDeprecated: !options.includeDeprecated,
+      category: options.category,
+      technology: options.technology,
+    };
+
+    const results = validateAllTemplates(projectPath, validationOptions);
+    const summary = summarizeValidation(results);
+
+    // Display results
+    const formatted = formatValidationResults(results, {
+      showInfo: options.verbose,
+      showValid: options.showValid,
+    });
+
+    console.log(formatted);
+    logger.blank();
+
+    // Exit with error if any templates have errors
+    if (summary.hasErrors > 0) {
+      logger.error(`${summary.hasErrors} template(s) failed validation`);
+      process.exit(1);
+    } else if (summary.hasWarnings > 0) {
+      logger.warn(`${summary.hasWarnings} template(s) have warnings`);
+      if (options.strict) {
+        process.exit(1);
+      }
+    } else {
+      logger.success(`All templates are valid! ✅`);
+    }
+  }
+}

package/src/commands/utils/index.js

@@ -0,0 +1,7 @@
+/**
+ * Utility Commands
+ */
+export { troubleshootCommand } from './troubleshoot.js';
+export { sessionSummaryCommand } from './session-summary.js';
+export { migrateStateCommand } from './migrate-state.js';
+export { upgradeCommand } from './upgrade.js';