@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/dist/lib/asset-value.js

@@ -0,0 +1,609 @@
+/**
+ * Knowledge Asset Value Calculator
+ *
+ * Calculates the monetary value of knowledge assets (skills, agents, patterns).
+ * Integrates with skill-effectiveness.js and versions.json for comprehensive
+ * asset valuation.
+ *
+ * Formula: Value = usageCount * avgTimeSavedMinutes * (hourlyRate / 60)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, getDateTimeString, getClaudeDir, readFile, findFiles } = require('./utils');
+
+// File paths
+const CONFIG_PATH = path.join(__dirname, '..', '..', 'config', 'asset-value.json');
+const VERSIONS_PATH = path.join(__dirname, '..', '..', 'config', 'versions.json');
+const KNOWLEDGE_DIR = path.join(getClaudeDir(), 'knowledge');
+const EFFECTIVENESS_FILE = path.join(KNOWLEDGE_DIR, 'skill-effectiveness.json');
+const ANTI_PATTERNS_FILE = path.join(KNOWLEDGE_DIR, 'anti-patterns.json');
+const ASSET_CACHE_FILE = path.join(KNOWLEDGE_DIR, 'asset-summary.json');
+
+// Asset categories
+const ASSET_CATEGORIES = {
+  BUNDLED: 'bundled',
+  AGENT: 'agent',
+  LEARNED: 'learned',
+  SHARED: 'shared',
+  PATTERN: 'pattern',
+};
+
+/**
+ * Load asset value configuration
+ */
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const content = fs.readFileSync(CONFIG_PATH, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    console.error(`[AssetValue] Error loading config: ${err.message}`);
+  }
+
+  // Default configuration
+  return {
+    valueCalculation: {
+      hourlyRate: 150,
+      currency: 'USD',
+      avgTimeSavedMinutes: {
+        bundled: 15,
+        agent: 30,
+        learned: 20,
+        shared: 25,
+        pattern: 10,
+      },
+    },
+    confidence: {
+      lowThreshold: 5,
+      mediumThreshold: 15,
+      highThreshold: 30,
+    },
+    decay: {
+      enabled: true,
+      ratePerQuarter: 0.05,
+      minimumValueMultiplier: 0.1,
+    },
+    reporting: {
+      topAssetsCount: 10,
+      deprecationThreshold: 0.4,
+      promotionThreshold: 0.9,
+    },
+  };
+}
+
+/**
+ * Load version registry for asset metadata
+ */
+function loadVersionRegistry() {
+  try {
+    if (fs.existsSync(VERSIONS_PATH)) {
+      const content = fs.readFileSync(VERSIONS_PATH, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    console.error(`[AssetValue] Error loading versions: ${err.message}`);
+  }
+
+  return { skills: {}, agents: {} };
+}
+
+/**
+ * Load skill effectiveness data
+ */
+function loadSkillEffectiveness() {
+  try {
+    if (fs.existsSync(EFFECTIVENESS_FILE)) {
+      const content = fs.readFileSync(EFFECTIVENESS_FILE, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    console.error(`[AssetValue] Error loading effectiveness: ${err.message}`);
+  }
+
+  return { skills: {}, summary: { totalApplications: 0 } };
+}
+
+/**
+ * Load anti-patterns data
+ */
+function loadAntiPatterns() {
+  try {
+    if (fs.existsSync(ANTI_PATTERNS_FILE)) {
+      const content = fs.readFileSync(ANTI_PATTERNS_FILE, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (err) {
+    // Anti-patterns file may not exist yet
+  }
+
+  return { patterns: [] };
+}
+
+/**
+ * Count learned skills in user directory
+ */
+function countLearnedSkills() {
+  const learnedDir = path.join(getClaudeDir(), 'skills', 'learned');
+
+  if (!fs.existsSync(learnedDir)) {
+    return { count: 0, skills: [] };
+  }
+
+  try {
+    const files = fs.readdirSync(learnedDir).filter((f) => f.endsWith('.md'));
+    return {
+      count: files.length,
+      skills: files.map((f) => f.replace('.md', '')),
+    };
+  } catch (err) {
+    return { count: 0, skills: [] };
+  }
+}
+
+/**
+ * Count shared skills in user directory
+ */
+function countSharedSkills() {
+  const sharedDir = path.join(getClaudeDir(), 'skills', 'shared');
+
+  if (!fs.existsSync(sharedDir)) {
+    return { count: 0, skills: [] };
+  }
+
+  try {
+    const files = findFiles(sharedDir, '*.md', { recursive: true });
+    return {
+      count: files.length,
+      skills: files.map((f) => path.basename(f.path, '.md')),
+    };
+  } catch (err) {
+    return { count: 0, skills: [] };
+  }
+}
+
+/**
+ * Calculate the value of a single asset
+ * @param {object} asset - Asset data with usageCount, effectiveness, category
+ * @param {object} config - Configuration object
+ */
+function calculateAssetValue(asset, config) {
+  const { valueCalculation, confidence, decay } = config;
+  const { hourlyRate, avgTimeSavedMinutes } = valueCalculation;
+
+  // Get time saved based on category
+  const timeSaved = avgTimeSavedMinutes[asset.category] || avgTimeSavedMinutes.bundled;
+
+  // Base value calculation: uses * minutes_saved * (hourly_rate / 60)
+  const baseValue = asset.usageCount * timeSaved * (hourlyRate / 60);
+
+  // Apply effectiveness multiplier (0.5 to 1.5 range)
+  const effectivenessMultiplier = 0.5 + (asset.effectiveness || 0.5);
+
+  // Calculate raw value
+  let value = baseValue * effectivenessMultiplier;
+
+  // Apply decay if enabled and asset hasn't been used recently
+  if (decay.enabled && asset.daysSinceLastUse) {
+    const quartersUnused = asset.daysSinceLastUse / 90;
+    const decayMultiplier = Math.max(
+      decay.minimumValueMultiplier,
+      Math.pow(1 - decay.ratePerQuarter, quartersUnused)
+    );
+    value *= decayMultiplier;
+  }
+
+  // Determine confidence level
+  let confidenceLevel = 'low';
+  if (asset.usageCount >= confidence.highThreshold) {
+    confidenceLevel = 'high';
+  } else if (asset.usageCount >= confidence.mediumThreshold) {
+    confidenceLevel = 'medium';
+  }
+
+  return {
+    value: Math.round(value * 100) / 100,
+    baseValue: Math.round(baseValue * 100) / 100,
+    effectivenessMultiplier: Math.round(effectivenessMultiplier * 100) / 100,
+    confidenceLevel,
+    breakdown: {
+      usageCount: asset.usageCount,
+      timeSavedMinutes: timeSaved,
+      hourlyRate,
+      effectiveness: asset.effectiveness || 0.5,
+    },
+  };
+}
+
+/**
+ * Calculate compound value (reuse across projects)
+ * @param {object} asset - Asset with base value calculated
+ * @param {object} config - Configuration object
+ */
+function calculateCompoundValue(asset, config) {
+  const baseValue = asset.estimatedValue || 0;
+
+  // Projects used in (approximate based on context diversity)
+  const projectMultiplier = Math.min(3, 1 + (asset.contextDiversity || 0) * 0.5);
+
+  // Team members using it (for shared skills)
+  const teamMultiplier = asset.category === ASSET_CATEGORIES.SHARED ? 1.5 : 1.0;
+
+  const compoundMultiplier = projectMultiplier * teamMultiplier;
+  const totalValue = baseValue * compoundMultiplier;
+
+  return {
+    baseValue,
+    projectMultiplier: Math.round(projectMultiplier * 100) / 100,
+    teamMultiplier,
+    compoundMultiplier: Math.round(compoundMultiplier * 100) / 100,
+    totalValue: Math.round(totalValue * 100) / 100,
+  };
+}
+
+/**
+ * Get all assets with calculated values
+ * @param {object} customConfig - Optional custom configuration
+ */
+function getAllAssetValues(customConfig = null) {
+  const config = customConfig || loadConfig();
+  const versions = loadVersionRegistry();
+  const effectiveness = loadSkillEffectiveness();
+  const antiPatterns = loadAntiPatterns();
+  const learned = countLearnedSkills();
+  const shared = countSharedSkills();
+
+  const assets = [];
+
+  // Process bundled skills
+  for (const [skillName, skillInfo] of Object.entries(versions.skills || {})) {
+    const effectivenessData = effectiveness.skills?.[skillName] || {};
+
+    const asset = {
+      name: skillName,
+      category: ASSET_CATEGORIES.BUNDLED,
+      version: skillInfo.version,
+      status: skillInfo.status,
+      usageCount: effectivenessData.applications || 0,
+      effectiveness: effectivenessData.effectiveness || 0.5,
+      lastUsed: effectivenessData.lastUsed || null,
+      daysSinceLastUse: calculateDaysSinceLastUse(effectivenessData.lastUsed),
+      trend: effectivenessData.trend || 'new',
+    };
+
+    const valueResult = calculateAssetValue(asset, config);
+    asset.estimatedValue = valueResult.value;
+    asset.confidenceLevel = valueResult.confidenceLevel;
+    asset.valueBreakdown = valueResult.breakdown;
+
+    assets.push(asset);
+  }
+
+  // Process agents
+  for (const [agentName, agentInfo] of Object.entries(versions.agents || {})) {
+    const effectivenessData = effectiveness.skills?.[agentName] || {};
+
+    const asset = {
+      name: agentName,
+      category: ASSET_CATEGORIES.AGENT,
+      version: agentInfo.version,
+      status: agentInfo.status,
+      usageCount: effectivenessData.applications || 0,
+      effectiveness: effectivenessData.effectiveness || 0.5,
+      lastUsed: effectivenessData.lastUsed || null,
+      daysSinceLastUse: calculateDaysSinceLastUse(effectivenessData.lastUsed),
+      trend: effectivenessData.trend || 'new',
+    };
+
+    const valueResult = calculateAssetValue(asset, config);
+    asset.estimatedValue = valueResult.value;
+    asset.confidenceLevel = valueResult.confidenceLevel;
+    asset.valueBreakdown = valueResult.breakdown;
+
+    assets.push(asset);
+  }
+
+  // Process learned skills
+  for (const skillName of learned.skills) {
+    const effectivenessData = effectiveness.skills?.[skillName] || {};
+
+    const asset = {
+      name: skillName,
+      category: ASSET_CATEGORIES.LEARNED,
+      version: '1.0.0',
+      status: 'active',
+      usageCount: effectivenessData.applications || 0,
+      effectiveness: effectivenessData.effectiveness || 0.5,
+      lastUsed: effectivenessData.lastUsed || null,
+      daysSinceLastUse: calculateDaysSinceLastUse(effectivenessData.lastUsed),
+      trend: effectivenessData.trend || 'new',
+    };
+
+    const valueResult = calculateAssetValue(asset, config);
+    asset.estimatedValue = valueResult.value;
+    asset.confidenceLevel = valueResult.confidenceLevel;
+    asset.valueBreakdown = valueResult.breakdown;
+
+    assets.push(asset);
+  }
+
+  // Process shared skills
+  for (const skillName of shared.skills) {
+    const effectivenessData = effectiveness.skills?.[skillName] || {};
+
+    const asset = {
+      name: skillName,
+      category: ASSET_CATEGORIES.SHARED,
+      version: '1.0.0',
+      status: 'active',
+      usageCount: effectivenessData.applications || 0,
+      effectiveness: effectivenessData.effectiveness || 0.5,
+      lastUsed: effectivenessData.lastUsed || null,
+      daysSinceLastUse: calculateDaysSinceLastUse(effectivenessData.lastUsed),
+      trend: effectivenessData.trend || 'new',
+    };
+
+    const valueResult = calculateAssetValue(asset, config);
+    asset.estimatedValue = valueResult.value;
+    asset.confidenceLevel = valueResult.confidenceLevel;
+    asset.valueBreakdown = valueResult.breakdown;
+
+    assets.push(asset);
+  }
+
+  // Process anti-patterns (as prevented mistakes)
+  if (antiPatterns.patterns && antiPatterns.patterns.length > 0) {
+    for (const pattern of antiPatterns.patterns) {
+      const asset = {
+        name: pattern.original || `pattern-${pattern.id || 'unknown'}`,
+        category: ASSET_CATEGORIES.PATTERN,
+        version: '1.0.0',
+        status: 'active',
+        usageCount: pattern.count || pattern.occurrences || 1,
+        effectiveness: 0.8, // Anti-patterns are inherently valuable
+        lastUsed: pattern.lastSeen || null,
+        daysSinceLastUse: calculateDaysSinceLastUse(pattern.lastSeen),
+        trend: 'stable',
+      };
+
+      const valueResult = calculateAssetValue(asset, config);
+      asset.estimatedValue = valueResult.value;
+      asset.confidenceLevel = valueResult.confidenceLevel;
+      asset.valueBreakdown = valueResult.breakdown;
+
+      assets.push(asset);
+    }
+  }
+
+  // Calculate summary
+  const summary = calculateSummary(assets, config);
+
+  // Sort by value descending
+  assets.sort((a, b) => b.estimatedValue - a.estimatedValue);
+
+  return {
+    assets,
+    summary,
+    topValueAssets: assets.slice(0, config.reporting.topAssetsCount),
+    lowValueAssets: assets.filter((a) => a.usageCount > 0).slice(-config.reporting.topAssetsCount),
+    deprecationCandidates: assets.filter(
+      (a) => a.effectiveness < config.reporting.deprecationThreshold && a.usageCount >= 10
+    ),
+    promotionCandidates: assets.filter(
+      (a) =>
+        a.effectiveness >= config.reporting.promotionThreshold &&
+        a.category === ASSET_CATEGORIES.LEARNED
+    ),
+  };
+}
+
+/**
+ * Calculate summary statistics
+ */
+function calculateSummary(assets, config) {
+  const activeAssets = assets.filter((a) => a.status === 'active');
+  const deprecatedAssets = assets.filter((a) => a.status === 'deprecated');
+
+  const totalValue = assets.reduce((sum, a) => sum + (a.estimatedValue || 0), 0);
+  const totalUsage = assets.reduce((sum, a) => sum + (a.usageCount || 0), 0);
+
+  const effectivenessValues = assets
+    .filter((a) => a.usageCount >= config.confidence.lowThreshold)
+    .map((a) => a.effectiveness);
+
+  const avgEffectiveness =
+    effectivenessValues.length > 0
+      ? effectivenessValues.reduce((sum, e) => sum + e, 0) / effectivenessValues.length
+      : 0;
+
+  // Determine overall confidence level
+  let confidenceLevel = 'low';
+  if (totalUsage >= 100) {
+    confidenceLevel = 'high';
+  } else if (totalUsage >= 30) {
+    confidenceLevel = 'medium';
+  }
+
+  // Count by category
+  const byCategory = {};
+  for (const category of Object.values(ASSET_CATEGORIES)) {
+    const categoryAssets = assets.filter((a) => a.category === category);
+    byCategory[category] = {
+      count: categoryAssets.length,
+      totalValue: categoryAssets.reduce((sum, a) => sum + (a.estimatedValue || 0), 0),
+      avgEffectiveness:
+        categoryAssets.length > 0
+          ? categoryAssets.reduce((sum, a) => sum + (a.effectiveness || 0), 0) /
+            categoryAssets.length
+          : 0,
+    };
+  }
+
+  return {
+    totalAssets: assets.length,
+    activeAssets: activeAssets.length,
+    deprecatedAssets: deprecatedAssets.length,
+    totalUsage,
+    avgEffectiveness: Math.round(avgEffectiveness * 100) / 100,
+    totalEstimatedValue: Math.round(totalValue * 100) / 100,
+    confidenceLevel,
+    currency: config.valueCalculation.currency,
+    byCategory,
+  };
+}
+
+/**
+ * Calculate days since last use
+ */
+function calculateDaysSinceLastUse(lastUsedStr) {
+  if (!lastUsedStr) return null;
+
+  try {
+    const lastUsed = new Date(lastUsedStr);
+    const now = new Date();
+    const diffMs = now - lastUsed;
+    return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get value trend over time
+ * @param {number} days - Number of days to analyze
+ */
+function getValueTrend(days = 30) {
+  // This would require historical data stored
+  // For now, return placeholder trend data
+  const trend = [];
+  const now = new Date();
+
+  for (let i = days; i >= 0; i--) {
+    const date = new Date(now);
+    date.setDate(date.getDate() - i);
+
+    trend.push({
+      date: date.toISOString().split('T')[0],
+      value: 0, // Would be calculated from historical data
+    });
+  }
+
+  return {
+    trend,
+    periodDays: days,
+    growth: 0, // Percentage growth over period
+  };
+}
+
+/**
+ * Load asset summary from cache (for dashboard)
+ */
+function loadAssetSummary() {
+  // Try to load from cache first
+  try {
+    if (fs.existsSync(ASSET_CACHE_FILE)) {
+      const content = fs.readFileSync(ASSET_CACHE_FILE, 'utf8');
+      const cached = JSON.parse(content);
+
+      // Check if cache is fresh (less than 1 hour old)
+      const cacheAge = Date.now() - new Date(cached.generatedAt).getTime();
+      if (cacheAge < 60 * 60 * 1000) {
+        return cached;
+      }
+    }
+  } catch (err) {
+    // Cache invalid, regenerate
+  }
+
+  // Generate fresh data
+  const data = getAllAssetValues();
+
+  // Save to cache
+  const cacheData = {
+    generatedAt: getDateTimeString(),
+    summary: data.summary,
+    topValueAssets: data.topValueAssets,
+    valueTrend: getValueTrend(30).trend,
+  };
+
+  try {
+    ensureDir(path.dirname(ASSET_CACHE_FILE));
+    fs.writeFileSync(ASSET_CACHE_FILE, JSON.stringify(cacheData, null, 2), 'utf8');
+  } catch (err) {
+    console.error(`[AssetValue] Error saving cache: ${err.message}`);
+  }
+
+  return cacheData;
+}
+
+/**
+ * Format currency value
+ * @param {number} value - Value to format
+ * @param {string} currency - Currency code (default USD)
+ */
+function formatCurrency(value, currency = 'USD') {
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+  });
+  return formatter.format(value);
+}
+
+/**
+ * Format percentage
+ * @param {number} value - Value between 0 and 1
+ */
+function formatPercent(value) {
+  return `${Math.round(value * 100)}%`;
+}
+
+/**
+ * Generate sparkline for terminal output
+ * @param {Array} values - Array of numeric values
+ */
+function generateSparkline(values) {
+  if (!values || values.length === 0) return '';
+
+  const chars = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+  const numericValues = values.map((v) => (typeof v === 'object' ? v.value : v));
+  const min = Math.min(...numericValues);
+  const max = Math.max(...numericValues);
+  const range = max - min || 1;
+
+  return numericValues
+    .map((v) => {
+      const normalized = (v - min) / range;
+      const index = Math.min(Math.floor(normalized * chars.length), chars.length - 1);
+      return chars[index];
+    })
+    .join('');
+}
+
+module.exports = {
+  // Core functions
+  loadConfig,
+  loadVersionRegistry,
+  loadSkillEffectiveness,
+  calculateAssetValue,
+  calculateCompoundValue,
+  getAllAssetValues,
+  getValueTrend,
+  loadAssetSummary,
+
+  // Helpers
+  formatCurrency,
+  formatPercent,
+  generateSparkline,
+  calculateDaysSinceLastUse,
+
+  // Constants
+  ASSET_CATEGORIES,
+
+  // Paths (for testing)
+  CONFIG_PATH,
+  VERSIONS_PATH,
+  EFFECTIVENESS_FILE,
+};