@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/lib/skill-matcher.js

@@ -0,0 +1,595 @@
+/**
+ * Skill Matcher - Context-Aware Skill Matching Engine
+ *
+ * Matches current task context to relevant skills from:
+ * 1. Built-in skills (skills/ directory)
+ * 2. Learned skills (~/.claude/skills/learned/)
+ * 3. Session-specific effective patterns
+ *
+ * Used by skill-injector hook to auto-apply relevant knowledge.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getLearnedSkillsDir, ensureDir, readFile } = require('./utils');
+
+// Skill directories
+const PLUGIN_ROOT = path.join(__dirname, '..', '..');
+const BUILTIN_SKILLS_DIR = path.join(PLUGIN_ROOT, 'skills');
+const LEARNED_SKILLS_DIR = getLearnedSkillsDir();
+const VERSIONS_FILE = path.join(PLUGIN_ROOT, 'config', 'versions.json');
+
+// Confidence threshold for matching
+const CONFIDENCE_THRESHOLD = 0.5;
+
+// Cache for version registry
+let versionRegistryCache = null;
+let versionRegistryCacheTime = 0;
+const VERSION_CACHE_TTL = 60000; // 1 minute
+
+// Maximum skills to return
+const MAX_MATCHED_SKILLS = 3;
+
+/**
+ * Skill activation patterns
+ * Maps skill names to trigger patterns
+ */
+/**
+ * Load version registry from config
+ * Cached for performance
+ */
+function loadVersionRegistry() {
+  const now = Date.now();
+
+  // Return cached if still valid
+  if (versionRegistryCache && now - versionRegistryCacheTime < VERSION_CACHE_TTL) {
+    return versionRegistryCache;
+  }
+
+  try {
+    if (fs.existsSync(VERSIONS_FILE)) {
+      const content = fs.readFileSync(VERSIONS_FILE, 'utf8');
+      versionRegistryCache = JSON.parse(content);
+      versionRegistryCacheTime = now;
+      return versionRegistryCache;
+    }
+  } catch (err) {
+    // Ignore parse errors
+  }
+
+  return { skills: {}, agents: {} };
+}
+
+/**
+ * Get deprecation info for a skill
+ * @param {string} skillName - Name of the skill
+ * @returns {object|null} - Deprecation info or null if not deprecated
+ */
+function getDeprecationInfo(skillName) {
+  const registry = loadVersionRegistry();
+  const skillInfo = registry.skills?.[skillName];
+
+  if (!skillInfo) return null;
+
+  if (skillInfo.status === 'deprecated' || skillInfo.deprecationInfo) {
+    return {
+      deprecated: true,
+      version: skillInfo.version || '0.0.0',
+      status: skillInfo.status,
+      deprecatedIn: skillInfo.deprecationInfo?.deprecatedIn || skillInfo.deprecatedIn,
+      supersededBy: skillInfo.deprecationInfo?.supersededBy || skillInfo.supersededBy,
+      migrationGuide: skillInfo.deprecationInfo?.migrationGuide || skillInfo.migrationGuide,
+      removalTarget: skillInfo.deprecationInfo?.removalTarget || skillInfo.removalTarget,
+      reason: skillInfo.deprecationInfo?.reason,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Get version info for a skill
+ * @param {string} skillName - Name of the skill
+ * @returns {object} - Version info
+ */
+function getSkillVersionInfo(skillName) {
+  const registry = loadVersionRegistry();
+  const skillInfo = registry.skills?.[skillName];
+
+  if (!skillInfo) {
+    return { version: '1.0.0', status: 'active' };
+  }
+
+  return {
+    version: skillInfo.version || '1.0.0',
+    status: skillInfo.status || 'active',
+    introduced: skillInfo.introduced,
+    lastUpdated: skillInfo.lastUpdated,
+  };
+}
+
+/**
+ * Skill activation patterns
+ * Maps skill names to trigger patterns
+ */
+const SKILL_TRIGGERS = {
+  // Platform skills
+  'zoho-patterns': {
+    patterns: [/zoho/i, /creator/i, /catalyst/i, /deluge/i, /crm/i, /books/i, /analytics/i],
+    filePatterns: [/\.ds$/],
+    priority: 3,
+  },
+  'gcp-data-engineering': {
+    patterns: [
+      /bigquery/i,
+      /dataflow/i,
+      /gcp/i,
+      /google cloud/i,
+      /medallion/i,
+      /bronze|silver|gold/i,
+    ],
+    filePatterns: [/\.sql$/, /dbt/],
+    priority: 2,
+  },
+  'bigquery-patterns': {
+    patterns: [/bigquery/i, /bq\b/i, /partition/i, /cluster/i, /query optim/i],
+    filePatterns: [/\.sql$/],
+    priority: 2,
+  },
+
+  // Compliance skills
+  'compliance-patterns': {
+    patterns: [/hipaa/i, /soc2/i, /pci/i, /compliance/i, /audit/i, /phi\b/i, /ephi/i],
+    complianceModes: ['hipaa', 'soc2', 'pci-dss'],
+    priority: 4,
+  },
+
+  // Development workflow skills
+  'tdd-workflow': {
+    patterns: [/test/i, /tdd/i, /coverage/i, /jest/i, /vitest/i, /mocha/i],
+    filePatterns: [/\.test\.(ts|tsx|js|jsx)$/, /\.spec\.(ts|tsx|js|jsx)$/],
+    priority: 2,
+  },
+  'security-review': {
+    patterns: [/security/i, /auth/i, /password/i, /credential/i, /owasp/i, /xss/i, /injection/i],
+    priority: 3,
+  },
+
+  // Frontend skills
+  'frontend-patterns': {
+    patterns: [/react/i, /component/i, /hook/i, /state/i, /redux/i, /context/i],
+    filePatterns: [/\.(tsx|jsx)$/],
+    priority: 2,
+  },
+
+  // Backend skills
+  'backend-patterns': {
+    patterns: [/api/i, /endpoint/i, /server/i, /express/i, /node/i, /rest/i],
+    filePatterns: [/server|api|route/i],
+    priority: 2,
+  },
+
+  // Standards skills
+  'coding-standards': {
+    patterns: [/standard/i, /convention/i, /style/i, /lint/i, /format/i],
+    priority: 1,
+  },
+
+  // Consultancy skills
+  'consultancy-workflows': {
+    patterns: [/client/i, /handoff/i, /billing/i, /time track/i, /documentation/i],
+    priority: 1,
+  },
+
+  // System/utility skills
+  'cloudstream-project-template': {
+    patterns: [/project template/i, /scaffold/i, /new project/i, /client setup/i, /project structure/i],
+    priority: 1,
+  },
+  'continuous-learning': {
+    patterns: [/learn/i, /pattern/i, /extract/i, /capture/i, /reusable/i],
+    priority: 1,
+  },
+  'continuous-learning-v2': {
+    patterns: [/instinct/i, /evolve/i, /homunculus/i, /observation/i],
+    priority: 1,
+  },
+  'strategic-compact': {
+    patterns: [/compact/i, /context window/i, /token/i, /summarize context/i],
+    priority: 1,
+  },
+  'tutorial': {
+    patterns: [/tutorial/i, /lesson/i, /onboard/i, /learn system/i, /getting started/i],
+    priority: 1,
+  },
+};
+
+/**
+ * Build context from file path and content
+ */
+function buildContext(filePath, content = '', additionalContext = {}) {
+  const context = {
+    filePath: filePath || '',
+    fileExtension: filePath ? path.extname(filePath) : '',
+    fileName: filePath ? path.basename(filePath) : '',
+    directory: filePath ? path.dirname(filePath) : '',
+    content: content || '',
+    technologies: new Set(),
+    complianceMode: additionalContext.complianceMode || null,
+    keywords: new Set(),
+    ...additionalContext,
+  };
+
+  // Extract technologies from file path
+  if (/\.ds$/.test(filePath)) context.technologies.add('deluge');
+  if (/\.(ts|tsx)$/.test(filePath)) context.technologies.add('typescript');
+  if (/\.(js|jsx)$/.test(filePath)) context.technologies.add('javascript');
+  if (/\.sql$/.test(filePath)) context.technologies.add('sql');
+  if (/\.py$/.test(filePath)) context.technologies.add('python');
+
+  // Extract technologies from directory path
+  if (/catalyst/i.test(filePath)) context.technologies.add('catalyst');
+  if (/creator/i.test(filePath)) context.technologies.add('creator');
+  if (/zoho/i.test(filePath)) context.technologies.add('zoho');
+  if (/bigquery|bq/i.test(filePath)) context.technologies.add('bigquery');
+
+  // Extract keywords from content
+  if (content) {
+    const contentSample = content.substring(0, 2000); // First 2000 chars
+
+    // Technology keywords
+    if (/invokeurl/i.test(contentSample)) context.technologies.add('zoho');
+    if (/zoho\./i.test(contentSample)) context.technologies.add('zoho');
+    if (/BigQuery|BIGQUERY/i.test(contentSample)) context.technologies.add('bigquery');
+    if (/useState|useEffect|React/i.test(contentSample)) context.technologies.add('react');
+    if (/express|app\.(get|post|put|delete)/i.test(contentSample))
+      context.technologies.add('express');
+
+    // Compliance keywords
+    if (/hipaa|phi|patient/i.test(contentSample))
+      context.complianceMode = context.complianceMode || 'hipaa';
+    if (/audit.*log|soc2/i.test(contentSample))
+      context.complianceMode = context.complianceMode || 'soc2';
+    if (/payment|card|pci/i.test(contentSample))
+      context.complianceMode = context.complianceMode || 'pci-dss';
+  }
+
+  return context;
+}
+
+/**
+ * Calculate match score for a skill against context
+ */
+function calculateMatchScore(skillName, skillConfig, context) {
+  let score = 0;
+  let matchReasons = [];
+
+  // Check pattern matches
+  if (skillConfig.patterns) {
+    for (const pattern of skillConfig.patterns) {
+      // Check against file path
+      if (pattern.test(context.filePath)) {
+        score += 0.3;
+        matchReasons.push(`path:${pattern}`);
+      }
+
+      // Check against content
+      if (pattern.test(context.content)) {
+        score += 0.4;
+        matchReasons.push(`content:${pattern}`);
+      }
+
+      // Check against technologies
+      for (const tech of context.technologies) {
+        if (pattern.test(tech)) {
+          score += 0.3;
+          matchReasons.push(`tech:${tech}`);
+        }
+      }
+    }
+  }
+
+  // Check file pattern matches
+  if (skillConfig.filePatterns) {
+    for (const pattern of skillConfig.filePatterns) {
+      if (pattern.test(context.filePath)) {
+        score += 0.5;
+        matchReasons.push(`file:${pattern}`);
+      }
+    }
+  }
+
+  // Check compliance mode match
+  if (skillConfig.complianceModes && context.complianceMode) {
+    if (skillConfig.complianceModes.includes(context.complianceMode)) {
+      score += 0.6;
+      matchReasons.push(`compliance:${context.complianceMode}`);
+    }
+  }
+
+  // Apply priority weight
+  const priority = skillConfig.priority || 1;
+  score *= priority;
+
+  // Normalize score to 0-1 range
+  const normalizedScore = Math.min(score / 3, 1);
+
+  return {
+    skill: skillName,
+    score: normalizedScore,
+    reasons: matchReasons,
+    priority,
+  };
+}
+
+/**
+ * Load learned skills from disk
+ */
+function loadLearnedSkills() {
+  ensureDir(LEARNED_SKILLS_DIR);
+
+  const skills = [];
+
+  try {
+    const files = fs.readdirSync(LEARNED_SKILLS_DIR);
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+
+      const filePath = path.join(LEARNED_SKILLS_DIR, file);
+      const content = readFile(filePath);
+
+      if (!content) continue;
+
+      // Extract metadata from frontmatter
+      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      let metadata = {};
+
+      if (frontmatterMatch) {
+        // Simple YAML-like parsing
+        const lines = frontmatterMatch[1].split('\n');
+        for (const line of lines) {
+          const [key, ...valueParts] = line.split(':');
+          if (key && valueParts.length) {
+            metadata[key.trim()] = valueParts
+              .join(':')
+              .trim()
+              .replace(/^["']|["']$/g, '');
+          }
+        }
+      }
+
+      skills.push({
+        name: file.replace('.md', ''),
+        path: filePath,
+        content: content.substring(0, 500), // Preview
+        metadata,
+        type: 'learned',
+      });
+    }
+  } catch (err) {
+    // Ignore errors
+  }
+
+  return skills;
+}
+
+/**
+ * Load builtin skill summaries
+ */
+function loadBuiltinSkillSummaries() {
+  const skills = [];
+
+  try {
+    const skillDirs = fs
+      .readdirSync(BUILTIN_SKILLS_DIR, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+
+    for (const skillName of skillDirs) {
+      const skillPath = path.join(BUILTIN_SKILLS_DIR, skillName, 'SKILL.md');
+
+      if (!fs.existsSync(skillPath)) continue;
+
+      const content = readFile(skillPath);
+      if (!content) continue;
+
+      // Extract description from frontmatter
+      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      let description = '';
+
+      if (frontmatterMatch) {
+        const descMatch = frontmatterMatch[1].match(/description:\s*(.+)/);
+        if (descMatch) {
+          description = descMatch[1].trim();
+        }
+      }
+
+      skills.push({
+        name: skillName,
+        path: skillPath,
+        description,
+        type: 'builtin',
+      });
+    }
+  } catch (err) {
+    // Ignore errors
+  }
+
+  return skills;
+}
+
+/**
+ * Match skills to context
+ * @param {object} context - Context from buildContext
+ * @returns {array} Matched skills sorted by relevance
+ */
+function matchSkills(context) {
+  const matches = [];
+
+  // Match against builtin skill triggers
+  for (const [skillName, skillConfig] of Object.entries(SKILL_TRIGGERS)) {
+    const match = calculateMatchScore(skillName, skillConfig, context);
+
+    if (match.score >= CONFIDENCE_THRESHOLD) {
+      match.type = 'builtin';
+      match.path = path.join(BUILTIN_SKILLS_DIR, skillName, 'SKILL.md');
+
+      // Add version and deprecation info
+      const versionInfo = getSkillVersionInfo(skillName);
+      match.version = versionInfo.version;
+      match.status = versionInfo.status;
+      match.deprecation = getDeprecationInfo(skillName);
+
+      matches.push(match);
+    }
+  }
+
+  // Match against learned skills (simpler matching)
+  const learnedSkills = loadLearnedSkills();
+
+  for (const learned of learnedSkills) {
+    let score = 0;
+    const reasons = [];
+
+    // Check if any technology in context matches skill metadata
+    if (learned.metadata.activation) {
+      const activationKeywords = learned.metadata.activation.split(',').map((s) => s.trim());
+
+      for (const keyword of activationKeywords) {
+        const regex = new RegExp(keyword, 'i');
+
+        if (regex.test(context.filePath)) {
+          score += 0.4;
+          reasons.push(`learned:path:${keyword}`);
+        }
+
+        if (regex.test(context.content)) {
+          score += 0.5;
+          reasons.push(`learned:content:${keyword}`);
+        }
+
+        for (const tech of context.technologies) {
+          if (regex.test(tech)) {
+            score += 0.3;
+            reasons.push(`learned:tech:${tech}`);
+          }
+        }
+      }
+    }
+
+    // Check skill name against context
+    const nameRegex = new RegExp(learned.name.replace(/-/g, '[ -]'), 'i');
+    if (nameRegex.test(context.content)) {
+      score += 0.3;
+      reasons.push('learned:name-match');
+    }
+
+    if (score >= CONFIDENCE_THRESHOLD) {
+      // Learned skills can also be in version registry
+      const versionInfo = getSkillVersionInfo(learned.name);
+
+      matches.push({
+        skill: learned.name,
+        score,
+        reasons,
+        type: 'learned',
+        path: learned.path,
+        priority: 2,
+        version: learned.metadata.version || versionInfo.version,
+        status: learned.metadata.status || versionInfo.status,
+        deprecation: getDeprecationInfo(learned.name),
+      });
+    }
+  }
+
+  // Sort by score (descending)
+  matches.sort((a, b) => b.score - a.score);
+
+  // Return top matches
+  return matches.slice(0, MAX_MATCHED_SKILLS);
+}
+
+/**
+ * Get skill content for injection
+ */
+function getSkillContent(skillMatch) {
+  if (!skillMatch.path || !fs.existsSync(skillMatch.path)) {
+    return null;
+  }
+
+  const content = readFile(skillMatch.path);
+  if (!content) return null;
+
+  // Remove frontmatter for injection
+  const cleaned = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+
+  // Truncate if too long (for context efficiency)
+  const MAX_SKILL_LENGTH = 2000;
+  if (cleaned.length > MAX_SKILL_LENGTH) {
+    return cleaned.substring(0, MAX_SKILL_LENGTH) + '\n\n[... truncated for context efficiency]';
+  }
+
+  return cleaned;
+}
+
+/**
+ * Format matched skills for injection
+ */
+function formatMatchedSkills(matches) {
+  if (matches.length === 0) return null;
+
+  let output = '[Skill Match] Relevant skills detected:\n';
+
+  for (const match of matches) {
+    output += `  - ${match.skill} (${Math.round(match.score * 100)}% match, ${match.type})\n`;
+    output += `    Reasons: ${match.reasons.slice(0, 3).join(', ')}\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Get matched skills with content for full injection
+ */
+function getMatchedSkillsWithContent(context) {
+  const matches = matchSkills(context);
+
+  return matches
+    .map((match) => ({
+      ...match,
+      content: getSkillContent(match),
+    }))
+    .filter((m) => m.content !== null);
+}
+
+module.exports = {
+  // Core functions
+  buildContext,
+  matchSkills,
+  calculateMatchScore,
+
+  // Version and deprecation
+  loadVersionRegistry,
+  getDeprecationInfo,
+  getSkillVersionInfo,
+
+  // Content retrieval
+  getSkillContent,
+  getMatchedSkillsWithContent,
+
+  // Formatting
+  formatMatchedSkills,
+
+  // Skill loading
+  loadLearnedSkills,
+  loadBuiltinSkillSummaries,
+
+  // Configuration
+  SKILL_TRIGGERS,
+  CONFIDENCE_THRESHOLD,
+  MAX_MATCHED_SKILLS,
+  BUILTIN_SKILLS_DIR,
+  LEARNED_SKILLS_DIR,
+  VERSIONS_FILE,
+};