scene-capability-engine 3.6.10 → 3.6.13

package/lib/commands/capability.js

@@ -11,7 +11,10 @@ const path = require('path');
 const chalk = require('chalk');
 const TaskClaimer = require('../task/task-claimer');
 const { runStudioSpecGovernance } = require('../studio/spec-intake-governor');
+const { DOMAIN_CHAIN_RELATIVE_PATH } = require('../spec/domain-modeling');
 const { SceStateStore } = require('../state/sce-state-store');
+const TemplateManager = require('../templates/template-manager');
+const { TemplateError } = require('../templates/template-error');
 const packageJson = require('../../package.json');
 
 const DEFAULT_ITERATION_DIR = '.sce/reports/capability-iteration';
@@ -31,6 +34,20 @@ function normalizeStringArray(value) {
   return value.map((item) => normalizeText(item)).filter(Boolean);
 }
 
+function normalizeTokenList(value) {
+  if (Array.isArray(value)) {
+    return normalizeStringArray(value).map((item) => item.toLowerCase());
+  }
+  const text = normalizeText(value);
+  if (!text) {
+    return [];
+  }
+  return text
+    .split(/[^a-zA-Z0-9._-]+/g)
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean);
+}
+
 function normalizeBoolean(value, fallback = false) {
   if (typeof value === 'boolean') {
     return value;
@@ -71,6 +88,12 @@ function buildDefaultTemplatePath(sceneId) {
   return path.join(DEFAULT_ITERATION_DIR, `${safeScene}.template.json`);
 }
 
+function buildDefaultUsePlanPath(specId, templateId) {
+  const safeSpec = normalizeText(specId).replace(/[^\w.-]+/g, '_') || 'spec';
+  const safeTemplate = normalizeText(templateId).replace(/[^\w.-]+/g, '_') || 'template';
+  return path.join(DEFAULT_ITERATION_DIR, 'usage', `${safeSpec}.${safeTemplate}.plan.json`);
+}
+
 function buildDefaultExportDir(templateId) {
   const safeId = normalizeText(templateId).replace(/[^\w.-]+/g, '_') || 'capability';
   return path.join(DEFAULT_EXPORT_ROOT, `capability-${safeId}`);
@@ -80,6 +103,95 @@ function buildSceneIdFromCandidate(candidate) {
   return normalizeText(candidate && candidate.scene_id) || 'scene.unknown';
 }
 
+function parseTemplatePath(templatePath) {
+  const normalized = normalizeText(templatePath);
+  if (!normalized) {
+    return { sourceName: 'official', templateId: '' };
+  }
+  if (normalized.includes(':')) {
+    const [sourceName, templateId] = normalized.split(':', 2);
+    return { sourceName: normalizeText(sourceName) || 'official', templateId: normalizeText(templateId) };
+  }
+  return { sourceName: 'official', templateId: normalized };
+}
+
+function buildOntologyScopeFromChain(domainChain) {
+  const ontology = domainChain && domainChain.ontology ? domainChain.ontology : {};
+  return {
+    domains: normalizeStringArray(domainChain && domainChain.scene_id ? [domainChain.scene_id] : []),
+    entities: normalizeStringArray(ontology.entity),
+    relations: normalizeStringArray(ontology.relation),
+    business_rules: normalizeStringArray(ontology.business_rule),
+    decisions: normalizeStringArray(ontology.decision_policy)
+  };
+}
+
+function buildOntologyOverlap(specScope, templateScope) {
+  const fields = ['domains', 'entities', 'relations', 'business_rules', 'decisions'];
+  const details = {};
+  let weightedTotal = 0;
+  let weightedMatched = 0;
+  let bucketCount = 0;
+
+  fields.forEach((field) => {
+    const expected = normalizeTokenList(specScope && specScope[field]);
+    const provided = normalizeTokenList(templateScope && templateScope[field]);
+    const providedSet = new Set(provided);
+    const matched = expected.filter((item) => providedSet.has(item));
+    const expectedCount = expected.length;
+    const matchedCount = matched.length;
+    const coverage = expectedCount > 0 ? matchedCount / expectedCount : 0;
+    if (expectedCount > 0) {
+      weightedTotal += 1;
+      weightedMatched += coverage;
+      bucketCount += 1;
+    }
+    details[field] = {
+      expected,
+      provided,
+      matched,
+      expected_count: expectedCount,
+      matched_count: matchedCount,
+      coverage_ratio: Number(coverage.toFixed(3))
+    };
+  });
+
+  const score = bucketCount > 0 ? weightedMatched / weightedTotal : 0;
+  return {
+    score,
+    details
+  };
+}
+
+function buildKeywordScore(template, queryTokens) {
+  if (!queryTokens || queryTokens.length === 0) {
+    return 0;
+  }
+  const haystack = [
+    template.id,
+    template.name,
+    template.description,
+    ...(template.tags || []),
+    ...(template.applicable_scenarios || [])
+  ].map((item) => `${item || ''}`.toLowerCase());
+  const hits = queryTokens.filter((token) => haystack.some((value) => value.includes(token))).length;
+  return hits / queryTokens.length;
+}
+
+async function loadSpecDomainChain(projectPath, specId, fileSystem) {
+  const specPath = path.join(projectPath, '.sce', 'specs', specId);
+  const domainChainPath = path.join(specPath, DOMAIN_CHAIN_RELATIVE_PATH);
+  if (!await fileSystem.pathExists(domainChainPath)) {
+    return { exists: false, path: domainChainPath, payload: null };
+  }
+  try {
+    const payload = await fileSystem.readJson(domainChainPath);
+    return { exists: true, path: domainChainPath, payload };
+  } catch (error) {
+    return { exists: true, path: domainChainPath, payload: null, error: error.message };
+  }
+}
+
 async function loadSceneIndexFromFile(projectPath, fileSystem) {
   const indexPath = path.join(projectPath, '.sce', 'spec-governance', 'scene-index.json');
   if (!await fileSystem.pathExists(indexPath)) {
@@ -537,6 +649,249 @@ async function runCapabilityRegisterCommand(options = {}, dependencies = {}) {
   return result;
 }
 
+function displayCapabilityCatalog(templates, options = {}) {
+  const total = Array.isArray(templates) ? templates.length : 0;
+  console.log(chalk.red('🔥') + ' Capability Library');
+  if (total === 0) {
+    console.log(chalk.yellow('No capability templates found.'));
+    if (options.source) {
+      console.log(chalk.gray(`Try removing filters or run ${chalk.cyan('sce templates update')}.`));
+    }
+    return;
+  }
+  templates.forEach((template) => {
+    const sourcePrefix = template.source && template.source !== 'official'
+      ? chalk.gray(`[${template.source}] `)
+      : '';
+    console.log(`${sourcePrefix}${chalk.cyan(template.id)} ${chalk.gray(`(${template.category})`)}`);
+    console.log(`  ${template.name}`);
+    console.log(`  ${chalk.gray(template.description)}`);
+    console.log();
+  });
+  console.log(chalk.gray(`Total: ${total} capability template(s)`));
+}
+
+async function listCapabilityCatalog(options = {}) {
+  const manager = new TemplateManager();
+  const templates = await manager.listTemplates({
+    category: options.category,
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  });
+  if (normalizeBoolean(options.json, false)) {
+    return {
+      mode: 'capability-catalog-list',
+      templates
+    };
+  }
+  displayCapabilityCatalog(templates, options);
+  return { templates };
+}
+
+async function searchCapabilityCatalog(keyword, options = {}) {
+  const manager = new TemplateManager();
+  const templates = await manager.searchTemplates(keyword, {
+    category: options.category,
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  });
+  if (normalizeBoolean(options.json, false)) {
+    return {
+      mode: 'capability-catalog-search',
+      keyword,
+      templates
+    };
+  }
+  displayCapabilityCatalog(templates, options);
+  return { templates };
+}
+
+async function showCapabilityTemplate(templatePath, options = {}) {
+  const manager = new TemplateManager();
+  const template = await manager.showTemplate(templatePath);
+  const { sourceName, templateId } = parseTemplatePath(templatePath);
+  await manager.ensureCached(sourceName);
+  const sourcePath = manager.cacheManager.getSourceCachePath(sourceName);
+  const templateDir = path.join(sourcePath, templateId);
+  const capabilityFile = path.join(templateDir, 'capability-template.json');
+  let templatePayload = null;
+  if (await fs.pathExists(capabilityFile)) {
+    try {
+      templatePayload = await fs.readJson(capabilityFile);
+    } catch (_error) {
+      templatePayload = null;
+    }
+  }
+  const result = {
+    mode: 'capability-catalog-show',
+    template,
+    template_file: await fs.pathExists(capabilityFile) ? capabilityFile : null,
+    payload: templatePayload
+  };
+  if (normalizeBoolean(options.json, false)) {
+    return result;
+  }
+  console.log(chalk.green('✅ Capability template loaded'));
+  console.log(chalk.gray(`  ID: ${template.id}`));
+  console.log(chalk.gray(`  Name: ${template.name}`));
+  if (templatePayload) {
+    console.log(chalk.gray('  Payload: capability-template.json loaded'));
+  }
+  return result;
+}
+
+async function matchCapabilityTemplates(options = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  const fileSystem = options.fileSystem || fs;
+  const specId = normalizeText(options.spec || options.specId);
+  if (!specId) {
+    throw new Error('spec is required for capability match');
+  }
+  const chain = await loadSpecDomainChain(projectPath, specId, fileSystem);
+  if (!chain.exists && normalizeBoolean(options.strict, false)) {
+    throw new Error(`problem-domain-chain missing for spec ${specId}`);
+  }
+  if (chain.error && normalizeBoolean(options.strict, false)) {
+    throw new Error(`problem-domain-chain invalid: ${chain.error}`);
+  }
+  const domainChain = chain.payload || {};
+  const specScope = buildOntologyScopeFromChain(domainChain);
+  const queryTokens = normalizeTokenList(options.query)
+    .concat(normalizeTokenList(domainChain.problem && domainChain.problem.statement))
+    .concat(normalizeTokenList(domainChain.scene_id));
+  const manager = new TemplateManager();
+  const templates = await manager.listTemplates({
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  });
+  const matches = templates.map((template) => {
+    const overlap = buildOntologyOverlap(specScope, template.ontology_scope || {});
+    const scenarioScore = template.applicable_scenarios && domainChain.scene_id
+      ? (template.applicable_scenarios.includes(domainChain.scene_id) ? 1 : 0)
+      : 0;
+    const keywordScore = buildKeywordScore(template, queryTokens);
+    const totalScore = (overlap.score * 0.6) + (scenarioScore * 0.2) + (keywordScore * 0.2);
+    return {
+      template_id: template.id,
+      source: template.source,
+      name: template.name,
+      description: template.description,
+      category: template.category,
+      risk_level: template.risk_level,
+      score: Math.round(totalScore * 100),
+      score_components: {
+        ontology: Number(overlap.score.toFixed(3)),
+        scenario: scenarioScore,
+        keyword: Number(keywordScore.toFixed(3))
+      },
+      overlap
+    };
+  }).sort((a, b) => b.score - a.score);
+
+  const limit = toPositiveInteger(options.limit, 10);
+  const payload = {
+    mode: 'capability-match',
+    spec_id: specId,
+    scene_id: domainChain.scene_id || null,
+    query: normalizeText(options.query) || null,
+    ontology_source: chain.exists ? chain.path : null,
+    match_count: matches.length,
+    matches: matches.slice(0, limit),
+    warnings: chain.exists ? [] : ['problem-domain-chain missing; ontology-based match unavailable']
+  };
+  if (normalizeBoolean(options.json, false)) {
+    return payload;
+  }
+  console.log(chalk.green('✅ Capability match completed'));
+  console.log(chalk.gray(`  Spec: ${specId}`));
+  console.log(chalk.gray(`  Matches: ${payload.matches.length}`));
+  return payload;
+}
+
+async function useCapabilityTemplate(options = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  const fileSystem = options.fileSystem || fs;
+  const templateId = normalizeText(options.template || options.id);
+  if (!templateId) {
+    throw new Error('template is required for capability use');
+  }
+  const specId = normalizeText(options.spec || options.specId) || null;
+  const manager = new TemplateManager();
+  const template = await manager.showTemplate(templateId);
+  const { sourceName, templateId: parsedTemplateId } = parseTemplatePath(templateId);
+  await manager.ensureCached(sourceName);
+  const sourcePath = manager.cacheManager.getSourceCachePath(sourceName);
+  const templateDir = path.join(sourcePath, parsedTemplateId);
+  const capabilityFile = path.join(templateDir, 'capability-template.json');
+  let templatePayload = null;
+  if (await fileSystem.pathExists(capabilityFile)) {
+    try {
+      templatePayload = await fileSystem.readJson(capabilityFile);
+    } catch (_error) {
+      templatePayload = null;
+    }
+  }
+
+  const recommendedTasks = [];
+  if (templatePayload && templatePayload.source_candidate && Array.isArray(templatePayload.source_candidate.specs)) {
+    templatePayload.source_candidate.specs.forEach((spec) => {
+      const sample = Array.isArray(spec.task_sample) ? spec.task_sample : [];
+      sample.forEach((task) => {
+        if (task && task.title) {
+          recommendedTasks.push({
+            title: task.title,
+            source_spec_id: spec.spec_id || null,
+            source_task_id: task.id || null
+          });
+        }
+      });
+    });
+  }
+  if (recommendedTasks.length === 0) {
+    recommendedTasks.push({ title: `Implement capability scope: ${template.name || parsedTemplateId}` });
+  }
+
+  const plan = {
+    mode: 'capability-use-plan',
+    generated_at: new Date().toISOString(),
+    template: {
+      id: template.id,
+      name: template.name,
+      source: template.source,
+      description: template.description,
+      ontology_scope: template.ontology_scope || {}
+    },
+    spec_id: specId,
+    recommended_tasks: recommendedTasks
+  };
+
+  const outputPath = normalizeText(options.out) || buildDefaultUsePlanPath(specId || 'spec', template.id);
+  if (normalizeBoolean(options.write, true)) {
+    await fileSystem.ensureDir(path.dirname(path.join(projectPath, outputPath)));
+    await fileSystem.writeJson(path.join(projectPath, outputPath), plan, { spaces: 2 });
+    plan.output_file = outputPath;
+  }
+
+  if (!normalizeBoolean(options.json, false)) {
+    console.log(chalk.green('✅ Capability use plan generated'));
+    console.log(chalk.gray(`  Template: ${template.id}`));
+    if (specId) {
+      console.log(chalk.gray(`  Spec: ${specId}`));
+    }
+    if (plan.output_file) {
+      console.log(chalk.gray(`  Output: ${plan.output_file}`));
+    }
+  }
+
+  return plan;
+}
+
 function registerCapabilityCommands(program) {
   const capabilityCmd = program
     .command('capability')
@@ -623,6 +978,141 @@ function registerCapabilityCommands(program) {
         tags
       });
     });
+
+  const catalogCmd = capabilityCmd
+    .command('catalog')
+    .description('Browse and reuse capability templates');
+
+  catalogCmd
+    .command('list')
+    .description('List capability templates')
+    .option('--source <name>', 'Template source name')
+    .option('--category <name>', 'Template category filter')
+    .option('--compatible-with <semver>', 'SCE version compatibility')
+    .option('--risk <level>', 'Risk level filter')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      try {
+        const payload = await listCapabilityCatalog({
+          source: options.source,
+          category: options.category,
+          compatibleWith: options.compatibleWith,
+          risk: options.risk,
+          json: options.json
+        });
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        if (error instanceof TemplateError && error.suggestions) {
+          console.log();
+          console.log(chalk.yellow('💡 Suggestions:'));
+          error.suggestions.forEach((suggestion) => console.log(`  • ${suggestion}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  catalogCmd
+    .command('search <keyword>')
+    .description('Search capability templates')
+    .option('--source <name>', 'Template source name')
+    .option('--category <name>', 'Template category filter')
+    .option('--compatible-with <semver>', 'SCE version compatibility')
+    .option('--risk <level>', 'Risk level filter')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (keyword, options) => {
+      try {
+        const payload = await searchCapabilityCatalog(keyword, {
+          source: options.source,
+          category: options.category,
+          compatibleWith: options.compatibleWith,
+          risk: options.risk,
+          json: options.json
+        });
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        if (error instanceof TemplateError && error.suggestions) {
+          console.log();
+          console.log(chalk.yellow('💡 Suggestions:'));
+          error.suggestions.forEach((suggestion) => console.log(`  • ${suggestion}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  catalogCmd
+    .command('show <template-id>')
+    .description('Show capability template details')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (templateId, options) => {
+      try {
+        const payload = await showCapabilityTemplate(templateId, { json: options.json });
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        if (error instanceof TemplateError && error.suggestions) {
+          console.log();
+          console.log(chalk.yellow('💡 Suggestions:'));
+          error.suggestions.forEach((suggestion) => console.log(`  • ${suggestion}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  capabilityCmd
+    .command('match')
+    .description('Match capability templates to a spec using ontology scope')
+    .requiredOption('--spec <spec-id>', 'Spec identifier')
+    .option('--query <text>', 'Additional keyword query')
+    .option('--source <name>', 'Template source name')
+    .option('--compatible-with <semver>', 'SCE version compatibility')
+    .option('--risk <level>', 'Risk level filter')
+    .option('--limit <n>', 'Max match results', '10')
+    .option('--strict', 'Fail if domain-chain missing or invalid')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      try {
+        const payload = await matchCapabilityTemplates(options);
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        process.exit(1);
+      }
+    });
+
+  capabilityCmd
+    .command('use')
+    .description('Generate a capability usage plan for a spec')
+    .requiredOption('--template <template-id>', 'Capability template identifier')
+    .option('--spec <spec-id>', 'Spec identifier')
+    .option('--out <path>', 'Output JSON path')
+    .option('--no-write', 'Skip writing output file')
+    .option('--json', 'Output JSON to stdout')
+    .action(async (options) => {
+      try {
+        const payload = await useCapabilityTemplate(options);
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+        }
+      } catch (error) {
+        console.log();
+        console.log(chalk.red('❌ Error:'), error.message);
+        process.exit(1);
+      }
+    });
 }
 
 module.exports = {