@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

package/src/core/templates/template-registry.js

@@ -1,256 +1,289 @@
-/**
- * Template Registry - Discovery and metadata API for all framework templates.
- *
- * Provides programmatic access to REGISTRY.json for:
- * - Template discovery by category, phase, stack
- * - Template metadata lookup
- * - Path resolution with fallback logic
- * - Validation of template existence
- *
- * @module template-registry
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Cache for loaded registry
-let _cachedRegistry = null;
-
-/**
- * Load the template registry from REGISTRY.json.
- *
- * @param {string} [projectPath] - Optional project path (defaults to framework root)
- * @returns {Object} Parsed registry object
- * @throws {Error} If registry file not found or invalid JSON
- */
-export function loadTemplateRegistry(projectPath = null) {
-  // Return cached if already loaded
-  if (_cachedRegistry) {
-    return _cachedRegistry;
-  }
-
-  // Default to framework registry
-  const registryPath = projectPath
-    ? join(projectPath, 'framework/templates/REGISTRY.json')
-    : join(__dirname, '../../../framework/templates/REGISTRY.json');
-
-  if (!existsSync(registryPath)) {
-    throw new Error(`Template registry not found: ${registryPath}`);
-  }
-
-  try {
-    const content = readFileSync(registryPath, 'utf-8');
-    _cachedRegistry = JSON.parse(content);
-    return _cachedRegistry;
-  } catch (error) {
-    throw new Error(`Failed to parse template registry: ${error.message}`);
-  }
-}
-
-/**
- * Clear cached registry (useful for testing).
- */
-export function clearRegistryCache() {
-  _cachedRegistry = null;
-}
-
-/**
- * Get all templates from registry.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Array of template objects
- */
-export function getAllTemplates(projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.templates || [];
-}
-
-/**
- * Get template by ID.
- *
- * @param {string} templateId - Template identifier (e.g., 'proposal', 'spec')
- * @param {string} [projectPath] - Optional project path
- * @returns {Object|null} Template object or null if not found
- */
-export function getTemplateById(templateId, projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.find(t => t.id === templateId) || null;
-}
-
-/**
- * Get templates by category.
- *
- * @param {string} category - Category ('documentation', 'code', 'infrastructure', 'context', 'examples')
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Filtered template array
- */
-export function getTemplatesByCategory(category, projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.filter(t => t.category === category);
-}
-
-/**
- * Get templates by phase.
- *
- * @param {string} phase - Phase name (e.g., 'proposal', 'design', 'implement')
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Filtered template array
- */
-export function getTemplatesByPhase(phase, projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.filter(t => t.phase === phase);
-}
-
-/**
- * Get templates by stack.
- *
- * @param {string} stackId - Stack identifier ('blazor-azure', 'nextjs-neon')
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Filtered template array (includes universal + stack-specific)
- */
-export function getTemplatesByStack(stackId, projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  return templates.filter(t => {
-    // Include universal templates (stackSpecific: false)
-    if (!t.stackSpecific) return true;
-
-    // Include stack-specific if matches
-    return t.stacks && t.stacks.includes(stackId);
-  });
-}
-
-/**
- * Get required templates only.
- *
- * @param {string} [stackId] - Optional stack filter
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Filtered template array
- */
-export function getRequiredTemplates(stackId = null, projectPath = null) {
-  let templates = getAllTemplates(projectPath);
-
-  // Filter by required flag
-  templates = templates.filter(t => t.required === true);
-
-  // Optional: filter by stack
-  if (stackId) {
-    templates = templates.filter(t => {
-      if (!t.stackSpecific) return true;
-      return t.stacks && t.stacks.includes(stackId);
-    });
-  }
-
-  return templates;
-}
-
-/**
- * Get infrastructure templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Infrastructure template array
- */
-export function getInfrastructureTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.infrastructureTemplates?.[stackId] || [];
-}
-
-/**
- * Get contract templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Contract template array
- */
-export function getContractTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.contractTemplates?.[stackId] || [];
-}
-
-/**
- * Get integration templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Integration template array
- */
-export function getIntegrationTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.integrationTemplates?.[stackId] || [];
-}
-
-/**
- * Get SaaS templates for a specific stack.
- *
- * @param {string} stackId - Stack identifier
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} SaaS template array
- */
-export function getSaasTemplates(stackId, projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.saasTemplates?.[stackId] || [];
-}
-
-/**
- * Get example templates.
- *
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Example template array
- */
-export function getExampleTemplates(projectPath = null) {
-  const registry = loadTemplateRegistry(projectPath);
-  return registry.exampleTemplates || [];
-}
-
-/**
- * Search templates by keyword (searches id, name, description).
- *
- * @param {string} keyword - Search term
- * @param {string} [projectPath] - Optional project path
- * @returns {Array} Matching templates
- */
-export function searchTemplates(keyword, projectPath = null) {
-  const templates = getAllTemplates(projectPath);
-  const lowerKeyword = keyword.toLowerCase();
-
-  return templates.filter(t => {
-    return (
-      t.id.toLowerCase().includes(lowerKeyword) ||
-      t.name.toLowerCase().includes(lowerKeyword) ||
-      (t.description && t.description.toLowerCase().includes(lowerKeyword))
-    );
-  });
-}
-
-/**
- * Get template absolute path with fallback logic.
- *
- * Resolution order:
- *   1. Project-local override (.morph/framework/templates/{path})
- *   2. Framework universal template (framework/templates/{path})
- *
- * @param {string} templateId - Template identifier
- * @param {string} projectPath - Project root path
- * @returns {string|null} Absolute template path or null if not found
- */
-export function resolveTemplatePathById(templateId, projectPath) {
-  const template = getTemplateById(templateId, projectPath);
-  if (!template) {
-    return null;
-  }
-
-  // 1. Project-local override
-  const projectLocalPath = join(projectPath, '.morph/framework/templates', template.path);
-  if (existsSync(projectLocalPath)) {
-    return projectLocalPath;
-  }
-
-  // 2. Framework universal template
-  const frameworkPath = join(projectPath, 'framework/templates', template.path);
-  return existsSync(frameworkPath) ? frameworkPath : null;
-}
-
+/**
+ * Template Registry - Discovery and metadata API for all framework templates.
+ *
+ * Provides programmatic access to REGISTRY.json for:
+ * - Template discovery by category, phase, stack
+ * - Template metadata lookup
+ * - Path resolution with fallback logic
+ * - Validation of template existence
+ *
+ * @module template-registry
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Parsed registries cached by resolved REGISTRY.json path. Keyed on the path —
+// NOT a single global slot — so a process that loads the framework registry
+// and a project's registry gets each one correctly, instead of whichever
+// loaded first.
+const _registryCache = new Map();
+
+/**
+ * Load the template registry from REGISTRY.json.
+ *
+ * @param {string} [projectPath] - Optional project path (defaults to framework root)
+ * @returns {Object} Parsed registry object
+ * @throws {Error} If registry file not found or invalid JSON
+ */
+export function loadTemplateRegistry(projectPath = null) {
+  // Resolve the path first — it is the cache key.
+  const registryPath = projectPath
+    ? join(projectPath, 'framework/templates/REGISTRY.json')
+    : join(__dirname, '../../../framework/templates/REGISTRY.json');
+
+  const cached = _registryCache.get(registryPath);
+  if (cached) {
+    return cached;
+  }
+
+  if (!existsSync(registryPath)) {
+    throw new Error(`Template registry not found: ${registryPath}`);
+  }
+
+  try {
+    const content = readFileSync(registryPath, 'utf-8');
+    const parsed = JSON.parse(content);
+    _registryCache.set(registryPath, parsed);
+    return parsed;
+  } catch (error) {
+    throw new Error(`Failed to parse template registry: ${error.message}`);
+  }
+}
+
+/**
+ * Clear all cached registries (useful for testing).
+ */
+export function clearRegistryCache() {
+  _registryCache.clear();
+}
+
+/**
+ * Get all templates from registry.
+ *
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Array of template objects
+ */
+export function getAllTemplates(projectPath = null) {
+  const registry = loadTemplateRegistry(projectPath);
+  return registry.templates || [];
+}
+
+/**
+ * Get template by ID.
+ *
+ * @param {string} templateId - Template identifier (e.g., 'proposal', 'spec')
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Object|null} Template object or null if not found
+ */
+export function getTemplateById(templateId, projectPath = null) {
+  const templates = getAllTemplates(projectPath);
+  return templates.find(t => t.id === templateId) || null;
+}
+
+/**
+ * Get templates by category.
+ *
+ * @param {string} category - Category ('documentation', 'code', 'infrastructure', 'context', 'examples')
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Filtered template array
+ */
+export function getTemplatesByCategory(category, projectPath = null) {
+  const templates = getAllTemplates(projectPath);
+  return templates.filter(t => t.category === category);
+}
+
+/**
+ * Get templates by phase.
+ *
+ * @param {string} phase - Phase name (e.g., 'proposal', 'design', 'implement')
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Filtered template array
+ */
+export function getTemplatesByPhase(phase, projectPath = null) {
+  const templates = getAllTemplates(projectPath);
+  return templates.filter(t => t.phase === phase);
+}
+
+/**
+ * Get templates by stack.
+ *
+ * @param {string} stackId - Stack identifier ('blazor-azure', 'nextjs-neon')
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Filtered template array (includes universal + stack-specific)
+ */
+export function getTemplatesByStack(stackId, projectPath = null) {
+  const templates = getAllTemplates(projectPath);
+  return templates.filter(t => {
+    // Include universal templates (stackSpecific: false)
+    if (!t.stackSpecific) return true;
+
+    // Include stack-specific if matches
+    return t.stacks && t.stacks.includes(stackId);
+  });
+}
+
+/**
+ * Get required templates only.
+ *
+ * @param {string} [stackId] - Optional stack filter
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Filtered template array
+ */
+export function getRequiredTemplates(stackId = null, projectPath = null) {
+  let templates = getAllTemplates(projectPath);
+
+  // Filter by required flag
+  templates = templates.filter(t => t.required === true);
+
+  // Optional: filter by stack
+  if (stackId) {
+    templates = templates.filter(t => {
+      if (!t.stackSpecific) return true;
+      return t.stacks && t.stacks.includes(stackId);
+    });
+  }
+
+  return templates;
+}
+
+/**
+ * Get infrastructure templates for a specific stack.
+ *
+ * @param {string} stackId - Stack identifier
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Infrastructure template array
+ */
+export function getInfrastructureTemplates(stackId, projectPath = null) {
+  const registry = loadTemplateRegistry(projectPath);
+  return registry.infrastructureTemplates?.[stackId] || [];
+}
+
+/**
+ * Get contract templates for a specific stack.
+ *
+ * @param {string} stackId - Stack identifier
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Contract template array
+ */
+export function getContractTemplates(stackId, projectPath = null) {
+  const registry = loadTemplateRegistry(projectPath);
+  return registry.contractTemplates?.[stackId] || [];
+}
+
+/**
+ * Get integration templates for a specific stack.
+ *
+ * @param {string} stackId - Stack identifier
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Integration template array
+ */
+export function getIntegrationTemplates(stackId, projectPath = null) {
+  const registry = loadTemplateRegistry(projectPath);
+  return registry.integrationTemplates?.[stackId] || [];
+}
+
+/**
+ * Get SaaS templates for a specific stack.
+ *
+ * @param {string} stackId - Stack identifier
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} SaaS template array
+ */
+export function getSaasTemplates(stackId, projectPath = null) {
+  const registry = loadTemplateRegistry(projectPath);
+  return registry.saasTemplates?.[stackId] || [];
+}
+
+/**
+ * Get example templates.
+ *
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Example template array
+ */
+export function getExampleTemplates(projectPath = null) {
+  const registry = loadTemplateRegistry(projectPath);
+  return registry.exampleTemplates || [];
+}
+
+/**
+ * Search templates by keyword (searches id, name, description).
+ *
+ * @param {string} keyword - Search term
+ * @param {string} [projectPath] - Optional project path
+ * @returns {Array} Matching templates
+ */
+export function searchTemplates(keyword, projectPath = null) {
+  const templates = getAllTemplates(projectPath);
+  const lowerKeyword = keyword.toLowerCase();
+
+  return templates.filter(t => {
+    return (
+      t.id.toLowerCase().includes(lowerKeyword) ||
+      t.name.toLowerCase().includes(lowerKeyword) ||
+      (t.description && t.description.toLowerCase().includes(lowerKeyword))
+    );
+  });
+}
+
+/**
+ * Get template absolute path with fallback logic.
+ *
+ * Resolution order:
+ *   1. Project-local override (.morph/framework/templates/{path})
+ *   2. Framework universal template (framework/templates/{path})
+ *
+ * @param {string} templateId - Template identifier
+ * @param {string} projectPath - Project root path
+ * @returns {string|null} Absolute template path or null if not found
+ */
+export function resolveTemplatePathById(templateId, projectPath) {
+  const template = getTemplateById(templateId, projectPath);
+  if (!template) {
+    return null;
+  }
+
+  // 1. Project-local override
+  const projectLocalPath = join(projectPath, '.morph/framework/templates', template.path);
+  if (existsSync(projectLocalPath)) {
+    return projectLocalPath;
+  }
+
+  // 2. Framework universal template
+  const frameworkPath = join(projectPath, 'framework/templates', template.path);
+  return existsSync(frameworkPath) ? frameworkPath : null;
+}
+
+/** Absolute path of this repo's own framework/templates/ directory. */
+const FRAMEWORK_TEMPLATES_DIR = join(__dirname, '../../../framework/templates');
+
+/**
+ * Resolve a template id to its absolute path inside THIS framework repo's
+ * `framework/templates/` directory — for generators running against the
+ * framework itself (scaffold-generator, context-generator), not against an
+ * installed `.morph/`. Use resolveTemplatePathById() when a project root and
+ * its project-local overrides are in play.
+ *
+ * @param {string} templateId - Template identifier (REGISTRY.json `id`)
+ * @returns {string} Absolute path to the template file
+ * @throws {Error} If the id is not in REGISTRY.json or the file is missing —
+ *   a missing template is a framework bug, not a recoverable condition.
+ */
+export function resolveFrameworkTemplatePath(templateId) {
+  const template = getTemplateById(templateId);
+  if (!template) {
+    throw new Error(`Template id "${templateId}" not found in REGISTRY.json`);
+  }
+  const abs = join(FRAMEWORK_TEMPLATES_DIR, template.path);
+  if (!existsSync(abs)) {
+    throw new Error(
+      `Template "${templateId}" path "${template.path}" does not resolve to a file`
+    );
+  }
+  return abs;
+}
+