scene-capability-engine 3.3.13 → 3.3.14

package/lib/templates/registry-parser.js

@@ -5,12 +5,19 @@
  */
 
 const fs = require('fs-extra');
-const path = require('path');
+const semver = require('semver');
 const { ValidationError } = require('./template-error');
 
 class RegistryParser {
   constructor() {
     this.registryCache = new Map();
+    this.templateTypes = [
+      'spec-scaffold',
+      'capability-template',
+      'runtime-playbook'
+    ];
+    this.validDifficulties = ['beginner', 'intermediate', 'advanced'];
+    this.validRiskLevels = ['low', 'medium', 'high', 'critical'];
   }
 
   /**
@@ -46,13 +53,14 @@ class RegistryParser {
       );
     }
 
-    // Validate schema
+    // Validate schema and normalize metadata contract
     this.validateRegistrySchema(registry);
+    const normalized = this.normalizeRegistry(registry);
 
     // Cache parsed registry
-    this.registryCache.set(registryPath, registry);
+    this.registryCache.set(registryPath, normalized);
 
-    return registry;
+    return normalized;
   }
 
   /**
@@ -93,6 +101,45 @@ class RegistryParser {
     }
   }
 
+  /**
+   * Normalizes registry entries to the typed template contract
+   *
+   * @param {Object} registry - Registry object
+   * @returns {Object} Normalized registry
+   */
+  normalizeRegistry(registry) {
+    const templates = Array.isArray(registry.templates) ? registry.templates : [];
+
+    return {
+      ...registry,
+      templates: templates.map((template) => this.normalizeTemplateEntry(template))
+    };
+  }
+
+  /**
+   * Normalizes a single template entry
+   *
+   * @param {Object} template - Template entry
+   * @returns {Object} Normalized template
+   */
+  normalizeTemplateEntry(template = {}) {
+    const templateType = this._resolveTemplateType(template);
+    const normalized = {
+      ...template,
+      template_type: templateType,
+      min_sce_version: template.min_sce_version ?? null,
+      max_sce_version: template.max_sce_version ?? null,
+      ontology_scope: this._normalizeOntologyScope(template.ontology_scope),
+      risk_level: template.risk_level ?? null,
+      rollback_contract: this._normalizeRollbackContract(template.rollback_contract),
+      applicable_scenarios: Array.isArray(template.applicable_scenarios) ? template.applicable_scenarios : [],
+      tags: Array.isArray(template.tags) ? template.tags : [],
+      files: Array.isArray(template.files) ? template.files : []
+    };
+
+    return normalized;
+  }
+
   /**
    * Validates a single template entry
    * 
@@ -103,11 +150,12 @@ class RegistryParser {
   validateTemplateEntry(template, index) {
     const errors = [];
     const prefix = `Template[${index}]`;
+    const templateType = this._resolveTemplateType(template);
 
     // Required fields
     const requiredFields = [
-      'id', 'name', 'category', 'description', 
-      'difficulty', 'tags', 'applicable_scenarios', 'files'
+      'id', 'name', 'category', 'description',
+      'difficulty', 'tags', 'files'
     ];
 
     for (const field of requiredFields) {
@@ -129,18 +177,74 @@ class RegistryParser {
       errors.push(`${prefix}: Field "files" must be an array`);
     }
 
+    if (template.template_type && !this.templateTypes.includes(template.template_type)) {
+      errors.push(`${prefix}: Invalid template_type "${template.template_type}". Must be one of: ${this.templateTypes.join(', ')}`);
+    }
+
+    if (template.min_sce_version !== undefined && template.min_sce_version !== null) {
+      if (typeof template.min_sce_version !== 'string' || !semver.valid(template.min_sce_version)) {
+        errors.push(`${prefix}: Field "min_sce_version" must be a valid semver version (e.g. 3.3.13)`);
+      }
+    }
+
+    if (template.max_sce_version !== undefined && template.max_sce_version !== null) {
+      if (typeof template.max_sce_version !== 'string' || !semver.valid(template.max_sce_version)) {
+        errors.push(`${prefix}: Field "max_sce_version" must be a valid semver version (e.g. 3.3.13)`);
+      }
+    }
+
+    if (template.min_sce_version && template.max_sce_version) {
+      if (semver.gt(template.min_sce_version, template.max_sce_version)) {
+        errors.push(`${prefix}: Field "min_sce_version" must be less than or equal to "max_sce_version"`);
+      }
+    }
+
+    if (template.ontology_scope !== undefined && template.ontology_scope !== null) {
+      if (!this._isPlainObject(template.ontology_scope)) {
+        errors.push(`${prefix}: Field "ontology_scope" must be an object`);
+      } else {
+        const ontologyArrayFields = ['domains', 'entities', 'relations', 'business_rules', 'decisions'];
+        for (const fieldName of ontologyArrayFields) {
+          if (template.ontology_scope[fieldName] !== undefined &&
+            !Array.isArray(template.ontology_scope[fieldName])) {
+            errors.push(`${prefix}: Field "ontology_scope.${fieldName}" must be an array when present`);
+          }
+        }
+      }
+    }
+
+    if (template.risk_level !== undefined && template.risk_level !== null) {
+      if (!this.validRiskLevels.includes(template.risk_level)) {
+        errors.push(`${prefix}: Invalid risk_level "${template.risk_level}". Must be one of: ${this.validRiskLevels.join(', ')}`);
+      }
+    }
+
+    if (template.rollback_contract !== undefined && template.rollback_contract !== null) {
+      if (!this._isPlainObject(template.rollback_contract)) {
+        errors.push(`${prefix}: Field "rollback_contract" must be an object`);
+      } else {
+        if (typeof template.rollback_contract.supported !== 'boolean') {
+          errors.push(`${prefix}: Field "rollback_contract.supported" must be boolean`);
+        }
+        if (template.rollback_contract.strategy !== undefined &&
+          template.rollback_contract.strategy !== null &&
+          typeof template.rollback_contract.strategy !== 'string') {
+          errors.push(`${prefix}: Field "rollback_contract.strategy" must be a string when present`);
+        }
+      }
+    }
+
     // Validate difficulty
-    const validDifficulties = ['beginner', 'intermediate', 'advanced'];
-    if (template.difficulty && !validDifficulties.includes(template.difficulty)) {
-      errors.push(`${prefix}: Invalid difficulty "${template.difficulty}". Must be one of: ${validDifficulties.join(', ')}`);
+    if (template.difficulty && !this.validDifficulties.includes(template.difficulty)) {
+      errors.push(`${prefix}: Invalid difficulty "${template.difficulty}". Must be one of: ${this.validDifficulties.join(', ')}`);
     }
 
-    // Validate files array
-    if (template.files && Array.isArray(template.files)) {
+    // Validate files array (legacy requirement only for spec scaffolds)
+    if (templateType === 'spec-scaffold' && template.files && Array.isArray(template.files)) {
       const requiredFiles = ['requirements.md', 'design.md', 'tasks.md'];
       for (const file of requiredFiles) {
         if (!template.files.includes(file)) {
-          errors.push(`${prefix}: Missing required file "${file}" in files array`);
+          errors.push(`${prefix}: spec-scaffold missing required file "${file}" in files array`);
         }
       }
     }
@@ -160,6 +264,8 @@ class RegistryParser {
       byCategory: {},
       byTag: {},
       byDifficulty: {},
+      byTemplateType: {},
+      byRiskLevel: {},
       all: []
     };
 
@@ -187,6 +293,20 @@ class RegistryParser {
       }
       index.byDifficulty[template.difficulty].push(template);
 
+      // Index by template type
+      const templateType = this._resolveTemplateType(template);
+      if (!index.byTemplateType[templateType]) {
+        index.byTemplateType[templateType] = [];
+      }
+      index.byTemplateType[templateType].push(template);
+
+      // Index by risk level
+      const riskLevel = template.risk_level || 'unspecified';
+      if (!index.byRiskLevel[riskLevel]) {
+        index.byRiskLevel[riskLevel] = [];
+      }
+      index.byRiskLevel[riskLevel].push(template);
+
       // Add to all templates
       index.all.push(template);
     }
@@ -216,7 +336,7 @@ class RegistryParser {
         }
 
         seenIds.add(template.id);
-        merged.templates.push(template);
+        merged.templates.push(this.normalizeTemplateEntry(template));
       }
     }
 
@@ -274,6 +394,17 @@ class RegistryParser {
     return index.byDifficulty[difficulty] || [];
   }
 
+  /**
+   * Gets templates by template type
+   *
+   * @param {Object} index - Registry index
+   * @param {string} templateType - Template type
+   * @returns {Object[]} Array of templates
+   */
+  getTemplatesByTemplateType(index, templateType) {
+    return index.byTemplateType[templateType] || [];
+  }
+
   /**
    * Gets all categories
    * 
@@ -302,6 +433,8 @@ class RegistryParser {
    * @param {Object} filters - Optional filters
    * @param {string} filters.category - Filter by category
    * @param {string} filters.difficulty - Filter by difficulty
+   * @param {string} filters.templateType - Filter by template type
+   * @param {string} filters.riskLevel - Filter by risk level
    * @param {string[]} filters.tags - Filter by tags (any match)
    * @returns {Object[]} Array of matching templates
    */
@@ -327,6 +460,17 @@ class RegistryParser {
         continue;
       }
 
+      if (filters.templateType && this._resolveTemplateType(template) !== filters.templateType) {
+        continue;
+      }
+
+      if (filters.riskLevel) {
+        const riskLevel = template.risk_level || 'unspecified';
+        if (riskLevel !== filters.riskLevel) {
+          continue;
+        }
+      }
+
       if (filters.tags && filters.tags.length > 0) {
         const hasMatchingTag = filters.tags.some(tag => 
           template.tags.includes(tag)
@@ -375,6 +519,21 @@ class RegistryParser {
       }
     }
 
+    // Search in template type
+    if (this._resolveTemplateType(template).includes(keywordLower)) {
+      return true;
+    }
+
+    // Search in ontology scope values
+    const ontologyScope = template.ontology_scope || {};
+    for (const field of ['domains', 'entities', 'relations', 'business_rules', 'decisions']) {
+      for (const value of ontologyScope[field] || []) {
+        if (String(value).toLowerCase().includes(keywordLower)) {
+          return true;
+        }
+      }
+    }
+
     return false;
   }
 
@@ -385,6 +544,8 @@ class RegistryParser {
    * @param {Object} filters - Filters
    * @param {string} filters.category - Filter by category
    * @param {string} filters.difficulty - Filter by difficulty
+   * @param {string} filters.templateType - Filter by template type
+   * @param {string} filters.riskLevel - Filter by risk level
    * @param {string[]} filters.tags - Filter by tags (any match)
    * @returns {Object[]} Array of matching templates
    */
@@ -401,6 +562,16 @@ class RegistryParser {
       results = results.filter(t => t.difficulty === filters.difficulty);
     }
 
+    // Filter by template type
+    if (filters.templateType) {
+      results = results.filter(t => this._resolveTemplateType(t) === filters.templateType);
+    }
+
+    // Filter by risk level
+    if (filters.riskLevel) {
+      results = results.filter((t) => (t.risk_level || 'unspecified') === filters.riskLevel);
+    }
+
     // Filter by tags (any match)
     if (filters.tags && filters.tags.length > 0) {
       results = results.filter(t => 
@@ -411,6 +582,106 @@ class RegistryParser {
     return results;
   }
 
+  /**
+   * Evaluates whether a template is compatible with a target SCE version
+   *
+   * @param {Object} template - Template object
+   * @param {string} sceVersion - Target SCE version
+   * @returns {boolean} Compatibility result
+   */
+  isTemplateCompatible(template, sceVersion) {
+    if (!sceVersion) {
+      return true;
+    }
+
+    if (!semver.valid(sceVersion)) {
+      return false;
+    }
+
+    const minVersion = template.min_sce_version;
+    const maxVersion = template.max_sce_version;
+
+    if (minVersion && semver.valid(minVersion) && semver.lt(sceVersion, minVersion)) {
+      return false;
+    }
+
+    if (maxVersion && semver.valid(maxVersion) && semver.gt(sceVersion, maxVersion)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Resolves template type with backward-compatible default
+   *
+   * @param {Object} template - Template object
+   * @returns {string} Template type
+   * @private
+   */
+  _resolveTemplateType(template = {}) {
+    const candidate = String(template.template_type || '').trim();
+    return this.templateTypes.includes(candidate) ? candidate : 'spec-scaffold';
+  }
+
+  /**
+   * Normalizes ontology scope structure
+   *
+   * @param {Object|null|undefined} ontologyScope - Ontology scope
+   * @returns {Object|null} Normalized ontology scope
+   * @private
+   */
+  _normalizeOntologyScope(ontologyScope) {
+    if (!this._isPlainObject(ontologyScope)) {
+      return null;
+    }
+
+    const normalized = {};
+    for (const field of ['domains', 'entities', 'relations', 'business_rules', 'decisions']) {
+      if (Array.isArray(ontologyScope[field])) {
+        normalized[field] = ontologyScope[field];
+      }
+    }
+
+    return Object.keys(normalized).length > 0 ? normalized : null;
+  }
+
+  /**
+   * Normalizes rollback contract
+   *
+   * @param {Object|null|undefined} rollbackContract - rollback contract
+   * @returns {Object|null} Normalized rollback contract
+   * @private
+   */
+  _normalizeRollbackContract(rollbackContract) {
+    if (!this._isPlainObject(rollbackContract)) {
+      return null;
+    }
+
+    const supported = rollbackContract.supported;
+    if (typeof supported !== 'boolean') {
+      return null;
+    }
+
+    const normalized = { supported };
+    if (typeof rollbackContract.strategy === 'string' && rollbackContract.strategy.trim().length > 0) {
+      normalized.strategy = rollbackContract.strategy.trim();
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Checks if value is a plain object
+   *
+   * @param {*} value - Value to check
+   * @returns {boolean} Is plain object
+   * @private
+   */
+  _isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+  }
+
   /**
    * Sorts templates
    * 
@@ -497,6 +768,14 @@ class RegistryParser {
       byDifficulty: Object.keys(index.byDifficulty).reduce((acc, diff) => {
         acc[diff] = index.byDifficulty[diff].length;
         return acc;
+      }, {}),
+      byTemplateType: Object.keys(index.byTemplateType).reduce((acc, templateType) => {
+        acc[templateType] = index.byTemplateType[templateType].length;
+        return acc;
+      }, {}),
+      byRiskLevel: Object.keys(index.byRiskLevel).reduce((acc, riskLevel) => {
+        acc[riskLevel] = index.byRiskLevel[riskLevel].length;
+        return acc;
       }, {})
     };
   }

package/lib/templates/template-exporter.js

@@ -8,6 +8,12 @@ const path = require('path');
 class TemplateExporter {
   constructor() {
     this.defaultOutputDir = '.sce/templates/exports';
+    this.templateRepositoryUrl =
+      process.env.SCE_TEMPLATE_REPOSITORY_URL ||
+      'https://github.com/heguangyong/scene-capability-engine-templates';
+    this.templateRepositoryName = this.templateRepositoryUrl
+      .replace(/^https?:\/\/github\.com\//, '')
+      .replace(/\.git$/, '');
   }
 
   /**
@@ -134,14 +140,28 @@ class TemplateExporter {
    * @returns {Object} Registry entry
    */
   generateRegistryEntry(metadata) {
+    const templateType = metadata.template_type || 'spec-scaffold';
+    const files = Array.isArray(metadata.files) && metadata.files.length > 0
+      ? metadata.files
+      : ['requirements.md', 'design.md', 'tasks.md'];
+
     return {
+      id: `${metadata.category}/${metadata.name}`,
       name: metadata.name,
+      template_type: templateType,
       category: metadata.category,
       description: metadata.description,
+      difficulty: metadata.difficulty || 'intermediate',
       tags: metadata.tags || [],
+      applicable_scenarios: metadata.applicable_scenarios || [],
+      files,
+      min_sce_version: metadata.min_sce_version,
+      max_sce_version: metadata.max_sce_version || null,
+      ontology_scope: metadata.ontology_scope || null,
+      risk_level: metadata.risk_level || null,
+      rollback_contract: metadata.rollback_contract || null,
       author: metadata.author,
       version: metadata.version,
-      kse_version: metadata.kse_version,
       created_at: metadata.created_at,
       updated_at: metadata.updated_at,
       path: `${metadata.category}/${metadata.name}`
@@ -158,7 +178,7 @@ class TemplateExporter {
 
 ## Template: ${metadata.name}
 
-Congratulations! Your template has been generated successfully. Follow these steps to submit it to the scene-capability-engine-templates repository.
+Congratulations! Your template has been generated successfully. Follow these steps to submit it to the ${this.templateRepositoryName} repository.
 
 ## Next Steps
 
@@ -186,10 +206,10 @@ cd .sce/specs/test-spec
 **Option A: Fork + Pull Request (Recommended)**
 
 \`\`\`bash
-# 1. Fork the scene-capability-engine-templates repository on GitHub
+# 1. Fork the ${this.templateRepositoryName} repository on GitHub
 # 2. Clone your fork
-git clone https://github.com/YOUR_USERNAME/scene-capability-engine-templates.git
-cd scene-capability-engine-templates
+git clone https://github.com/YOUR_USERNAME/${this.templateRepositoryName.split('/').pop()}.git
+cd ${this.templateRepositoryName.split('/').pop()}
 
 # 3. Create a branch
 git checkout -b add-${metadata.name}
@@ -214,7 +234,7 @@ git push origin add-${metadata.name}
 
 If you're not familiar with Git:
 
-1. Go to https://github.com/heguangyong/scene-capability-engine-templates/issues
+1. Go to ${this.templateRepositoryUrl.replace(/\.git$/, '')}/issues
 2. Create a new issue with title: \`[Template Submission] ${metadata.name}\`
 3. Attach the template files or paste their contents
 4. A maintainer will review and add your template
@@ -234,7 +254,7 @@ If you're not familiar with Git:
 ## Questions?
 
 If you have questions about the submission process, please:
-- Check the scene-capability-engine-templates repository README
+- Check the ${this.templateRepositoryName} repository README
 - Open an issue in the repository
 - Contact the maintainers
 
@@ -261,7 +281,7 @@ ${metadata.description}
 - **Tags**: ${metadata.tags.join(', ')}
 - **Author**: ${metadata.author}
 - **Version**: ${metadata.version}
-- **Minimum SCE Version**: ${metadata.kse_version}
+- **Minimum SCE Version**: ${metadata.min_sce_version}
 
 ## Files Included
 
@@ -427,7 +447,7 @@ ${metadata.description}
 
 ## Prerequisites
 
-- sce version ${metadata.kse_version} or higher
+- sce version ${metadata.min_sce_version} or higher
 - Basic understanding of Spec-driven development
 
 ## Tags
@@ -443,7 +463,7 @@ After applying this template, you'll have a complete Spec structure ready to cus
 If you have questions about using this template:
 - Check the sce documentation
 - Review the generated Spec files
-- Open an issue in the scene-capability-engine-templates repository
+- Open an issue in the ${this.templateRepositoryName} repository
 `;
   }
 

package/lib/templates/template-manager.js

@@ -7,6 +7,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const os = require('os');
+const semver = require('semver');
 const GitHandler = require('./git-handler');
 const CacheManager = require('./cache-manager');
 const RegistryParser = require('./registry-parser');
@@ -16,7 +17,7 @@ const { ValidationError, NetworkError } = require('./template-error');
 
 class TemplateManager {
   constructor(options = {}) {
-    this.cacheDir = options.cacheDir || path.join(os.homedir(), '.kse', 'templates');
+    this.cacheDir = options.cacheDir || path.join(os.homedir(), '.sce', 'templates');
     
     // Initialize components
     this.gitHandler = new GitHandler();
@@ -222,10 +223,26 @@ class TemplateManager {
    * @param {Object} options - List options
    * @param {string} options.category - Filter by category
    * @param {string} options.source - Filter by source
+   * @param {string} options.templateType - Filter by template type
+   * @param {string} options.compatibleWith - Filter by SCE version compatibility
+   * @param {string} options.riskLevel - Filter by risk level
    * @returns {Promise<Object[]>} Array of templates
    */
   async listTemplates(options = {}) {
-    const { category = null, source = null } = options;
+    const {
+      category = null,
+      source = null,
+      templateType = null,
+      compatibleWith = null,
+      riskLevel = null
+    } = options;
+
+    if (compatibleWith && !semver.valid(compatibleWith)) {
+      throw new ValidationError(
+        'Invalid --compatible-with version. Expected semver like 3.3.13.',
+        { compatibleWith }
+      );
+    }
 
     const sources = await this.getSources();
     const enabledSources = sources.filter(s => s.enabled);
@@ -257,10 +274,18 @@ class TemplateManager {
         const registry = await this.registryParser.parseRegistry(registryPath);
         const index = this.registryParser.buildIndex(registry);
 
-        // Get templates
-        let templates = category
-          ? this.registryParser.getTemplatesByCategory(index, category)
-          : index.all;
+        // Apply filters
+        let templates = this.registryParser.filterTemplates(index, {
+          category,
+          templateType,
+          riskLevel
+        });
+
+        if (compatibleWith) {
+          templates = templates.filter((template) =>
+            this.registryParser.isTemplateCompatible(template, compatibleWith)
+          );
+        }
 
         // Add source information
         templates = templates.map(t => ({
@@ -283,15 +308,36 @@ class TemplateManager {
    * 
    * @param {string} keyword - Search keyword
    * @param {Object} filters - Search filters
+   * @param {string} filters.source - Filter by source
+   * @param {string} filters.category - Filter by category
+   * @param {string} filters.templateType - Filter by template type
+   * @param {string} filters.compatibleWith - Filter by SCE version compatibility
+   * @param {string} filters.riskLevel - Filter by risk level
    * @returns {Promise<Object[]>} Array of matching templates
    */
   async searchTemplates(keyword, filters = {}) {
+    const {
+      source = null,
+      compatibleWith = null,
+      ...searchFilters
+    } = filters;
+
+    if (compatibleWith && !semver.valid(compatibleWith)) {
+      throw new ValidationError(
+        'Invalid --compatible-with version. Expected semver like 3.3.13.',
+        { compatibleWith }
+      );
+    }
+
     const sources = await this.getSources();
     const enabledSources = sources.filter(s => s.enabled);
+    const targetSources = source
+      ? enabledSources.filter((entry) => entry.name === source)
+      : enabledSources;
 
     const allResults = [];
 
-    for (const src of enabledSources) {
+    for (const src of targetSources) {
       if (!await this.cacheManager.cacheExists(src.name)) {
         continue;
       }
@@ -309,7 +355,12 @@ class TemplateManager {
         const registry = await this.registryParser.parseRegistry(registryPath);
         const index = this.registryParser.buildIndex(registry);
 
-        const results = this.registryParser.searchTemplates(index, keyword, filters);
+        let results = this.registryParser.searchTemplates(index, keyword, searchFilters);
+        if (compatibleWith) {
+          results = results.filter((template) =>
+            this.registryParser.isTemplateCompatible(template, compatibleWith)
+          );
+        }
 
         // Add source information
         const resultsWithSource = results.map(t => ({
@@ -577,6 +628,9 @@ class TemplateManager {
       );
     }
 
+    // Registry file may have changed after pull/checkout; refresh parser cache.
+    this.registryParser.clearCache();
+
     // Get new template list
     const newRegistry = await this.registryParser.parseRegistry(oldRegistryPath);
     const newTemplates = new Map(