@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/scripts/aggregate-sessions.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+/**
+ * Cross-Session Aggregator
+ *
+ * Main entry point for aggregating session data across multiple sessions.
+ * Detects patterns, analyzes trends, and generates recommendations.
+ *
+ * Usage:
+ *   node scripts/aggregate-sessions.js [--days=30] [--output=json|md]
+ *
+ * Options:
+ *   --days    Analysis window in days (default: 30)
+ *   --output  Output format: json or md (default: json)
+ *   --force   Run even if recently run
+ */
+
+const path = require('path');
+const fs = require('fs');
+const {
+  getClaudeDir,
+  ensureDir,
+  writeFile,
+  getDateString,
+  getDateTimeString,
+  log,
+} = require('./lib/utils');
+
+const {
+  analyzeAllSessions,
+  detectCrossSessionPatterns,
+  analyzeByTechnology,
+  analyzeByComplianceMode,
+  analyzeTrends,
+  buildSkillCorrectionMatrix,
+  saveAggregatedData,
+  getAggregationStatus,
+  THRESHOLDS,
+} = require('./lib/cross-session-patterns');
+
+const {
+  generateRecommendations,
+  clearExpiredRecommendations,
+  formatRecommendations,
+} = require('./lib/recommendation-engine');
+
+// Parse command line arguments
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    days: 30,
+    output: 'json',
+    force: false,
+  };
+
+  for (const arg of args) {
+    if (arg.startsWith('--days=')) {
+      options.days = parseInt(arg.split('=')[1], 10) || 30;
+    } else if (arg.startsWith('--output=')) {
+      options.output = arg.split('=')[1] || 'json';
+    } else if (arg === '--force') {
+      options.force = true;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Generate markdown report from aggregated data
+ */
+function generateMarkdownReport(data, options) {
+  const reportsDir = path.join(getClaudeDir(), 'knowledge', 'reports');
+  ensureDir(reportsDir);
+
+  const date = getDateString();
+  const reportPath = path.join(reportsDir, `aggregation-${date}.md`);
+
+  let md = `# Cross-Session Aggregation Report\n\n`;
+  md += `**Generated:** ${getDateTimeString()}\n`;
+  md += `**Analysis Window:** ${options.days} days\n\n`;
+
+  // Summary
+  md += `## Summary\n\n`;
+  md += `- Sessions analyzed: ${data.summary.sessionCount}\n`;
+  md += `- Total corrections: ${data.summary.correctionCount}\n`;
+  md += `- High-confidence patterns: ${data.patterns.highConfidence.length}\n`;
+  md += `- Recommendations generated: ${data.recommendations.length}\n\n`;
+
+  // High-confidence patterns
+  if (data.patterns.highConfidence.length > 0) {
+    md += `## High-Confidence Patterns\n\n`;
+    md += `| Pattern | Category | Sessions | Confidence |\n`;
+    md += `|---------|----------|----------|------------|\n`;
+
+    for (const p of data.patterns.highConfidence.slice(0, 10)) {
+      md += `| ${truncate(p.original, 40)} | ${p.category} | ${p.sessionCount} | ${Math.round(p.confidence * 100)}% |\n`;
+    }
+    md += '\n';
+  }
+
+  // Trends
+  if (data.trends.improving.length > 0 || data.trends.worsening.length > 0) {
+    md += `## Trends\n\n`;
+
+    if (data.trends.improving.length > 0) {
+      md += `### Improving\n\n`;
+      for (const t of data.trends.improving.slice(0, 5)) {
+        md += `- ${truncate(t.original, 50)}: ${t.percentChange}%\n`;
+      }
+      md += '\n';
+    }
+
+    if (data.trends.worsening.length > 0) {
+      md += `### Worsening\n\n`;
+      for (const t of data.trends.worsening.slice(0, 5)) {
+        md += `- ${truncate(t.original, 50)}: +${t.percentChange}%\n`;
+      }
+      md += '\n';
+    }
+  }
+
+  // Technology patterns
+  if (Object.keys(data.techPatterns).length > 0) {
+    md += `## Technology-Specific Patterns\n\n`;
+
+    for (const [tech, techData] of Object.entries(data.techPatterns)) {
+      md += `### ${tech}\n\n`;
+      md += `- Sessions: ${techData.sessionCount}\n`;
+      md += `- Correction rate: ${techData.correctionRate.toFixed(1)}/session\n`;
+
+      if (techData.topIssues.length > 0) {
+        md += `- Top issue: ${truncate(techData.topIssues[0].original, 40)} (${techData.topIssues[0].count}x)\n`;
+      }
+      md += '\n';
+    }
+  }
+
+  // Recommendations
+  if (data.recommendations.length > 0) {
+    md += `## Recommendations\n\n`;
+    md += formatRecommendations(data.recommendations.slice(0, 5));
+  }
+
+  writeFile(reportPath, md);
+  log(`[Aggregator] Report saved to: ${reportPath}`);
+
+  return reportPath;
+}
+
+/**
+ * Truncate string for display
+ */
+function truncate(str, length) {
+  if (!str) return '';
+  if (str.length <= length) return str;
+  return str.substring(0, length - 3) + '...';
+}
+
+/**
+ * Main aggregation function
+ */
+async function main() {
+  const options = parseArgs();
+
+  log('[Aggregator] Starting cross-session analysis...');
+
+  // Check if we need to run
+  if (!options.force) {
+    const status = getAggregationStatus();
+    if (!status.needsUpdate) {
+      log(`[Aggregator] Already up to date (last run: ${status.lastRun})`);
+      log(`[Aggregator] Use --force to run anyway`);
+      return;
+    }
+  }
+
+  // 1. Load and analyze all sessions
+  const { sessions, corrections, summary } = analyzeAllSessions();
+
+  if (summary.insufficient) {
+    log(
+      `[Aggregator] Insufficient sessions (${summary.sessionCount}). Need at least ${THRESHOLDS.MIN_SESSIONS_FOR_ANALYSIS}.`
+    );
+    return;
+  }
+
+  log(`[Aggregator] Loaded ${sessions.length} sessions with ${corrections.length} corrections`);
+
+  // 2. Detect cross-session patterns
+  const patterns = detectCrossSessionPatterns(THRESHOLDS.MIN_SESSIONS_FOR_PATTERN);
+  log(`[Aggregator] Found ${patterns.highConfidence.length} high-confidence patterns`);
+  log(`[Aggregator] Found ${patterns.emerging.length} emerging patterns`);
+
+  // 3. Analyze by context
+  const techPatterns = analyzeByTechnology();
+  const compliancePatterns = analyzeByComplianceMode();
+  log(`[Aggregator] Analyzed ${Object.keys(techPatterns).length} technologies`);
+
+  // 4. Analyze trends
+  const trends = analyzeTrends(options.days);
+  log(
+    `[Aggregator] Trends: ${trends.improving.length} improving, ${trends.worsening.length} worsening`
+  );
+
+  // 5. Build skill-correction matrix
+  const skillMatrix = buildSkillCorrectionMatrix();
+  log(`[Aggregator] Built skill matrix with ${Object.keys(skillMatrix).length} skills`);
+
+  // 6. Clear expired recommendations first
+  const expiredCount = clearExpiredRecommendations();
+  if (expiredCount > 0) {
+    log(`[Aggregator] Cleared ${expiredCount} expired recommendations`);
+  }
+
+  // 7. Generate recommendations
+  const { recommendations, summary: recSummary } = generateRecommendations({
+    patterns,
+    trends,
+    skillMatrix,
+    techPatterns,
+  });
+  log(
+    `[Aggregator] Generated ${recSummary.total} recommendations (${recSummary.high} high, ${recSummary.medium} medium)`
+  );
+
+  // 8. Prepare aggregated data
+  const aggregatedData = {
+    summary,
+    patterns,
+    techPatterns,
+    compliancePatterns,
+    trends,
+    skillMatrix,
+    recommendations,
+  };
+
+  // 9. Save results
+  saveAggregatedData({
+    patternLibrary: patterns,
+    contextPatterns: { techPatterns, compliancePatterns },
+    trendAnalysis: trends,
+    skillCorrectionMatrix: skillMatrix,
+    recommendations,
+  });
+
+  log('[Aggregator] Saved aggregated data');
+
+  // 10. Generate report if requested
+  if (options.output === 'md') {
+    generateMarkdownReport(aggregatedData, options);
+  }
+
+  // 11. Output summary
+  log('\n[Aggregator] === AGGREGATION COMPLETE ===\n');
+  log(`Sessions analyzed: ${sessions.length}`);
+  log(`High-confidence patterns: ${patterns.highConfidence.length}`);
+  log(`Emerging patterns: ${patterns.emerging.length}`);
+  log(`Trends improving: ${trends.improving.length}`);
+  log(`Trends worsening: ${trends.worsening.length}`);
+  log(`Recommendations: ${recommendations.length}`);
+
+  if (patterns.highConfidence.length > 0) {
+    log('\nTop patterns:');
+    for (const p of patterns.highConfidence.slice(0, 3)) {
+      log(
+        `  - ${truncate(p.original, 50)} (${p.sessionCount} sessions, ${Math.round(p.confidence * 100)}%)`
+      );
+    }
+  }
+
+  if (recommendations.length > 0) {
+    log('\nTop recommendations:');
+    for (const r of recommendations.slice(0, 3)) {
+      const emoji = r.priority === 'high' ? '🔴' : r.priority === 'medium' ? '🟠' : '🟡';
+      log(`  ${emoji} ${r.title}`);
+    }
+  }
+
+  log('\n[Aggregator] Done');
+}
+
+// Run if called directly
+if (require.main === module) {
+  main().catch((err) => {
+    log(`[Aggregator] Error: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { main };

package/scripts/branch-name-validator.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/**
+ * Branch Name Validator (Phase 7)
+ *
+ * Validates and creates branch names following CloudStream conventions:
+ * - feature/[CLIENT]/[description]
+ * - fix/[CLIENT]/[description]
+ * - hotfix/[CLIENT]/[description]
+ * - docs/[description]
+ * - chore/[description]
+ *
+ * Usage:
+ *   node branch-name-validator.js [branch-name]
+ *   node branch-name-validator.js --current
+ */
+
+const { execSync } = require('child_process');
+
+/**
+ * Valid branch name patterns.
+ * @type {RegExp[]}
+ */
+const VALID_PATTERNS = [
+  /^feature\/[A-Z]{2,5}\/[a-z0-9-]+$/,
+  /^fix\/[A-Z]{2,5}\/[a-z0-9-]+$/,
+  /^hotfix\/[A-Z]{2,5}\/[a-z0-9-]+$/,
+  /^docs\/[a-z0-9-]+$/,
+  /^chore\/[a-z0-9-]+$/,
+  /^main$/,
+  /^develop$/,
+];
+
+/**
+ * Branch types that require a client ID.
+ * @type {string[]}
+ */
+const CLIENT_REQUIRED_TYPES = ['feature', 'fix', 'hotfix'];
+
+/**
+ * Valid branch types.
+ * @type {string[]}
+ */
+const VALID_TYPES = ['feature', 'fix', 'hotfix', 'docs', 'chore'];
+
+/**
+ * Check if a branch name is valid.
+ * @param {string} branchName - The branch name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidBranchName(branchName) {
+  if (!branchName || typeof branchName !== 'string') {
+    return false;
+  }
+
+  return VALID_PATTERNS.some((pattern) => pattern.test(branchName));
+}
+
+/**
+ * Validate a branch name and return detailed result.
+ * @param {string} branchName - The branch name to validate
+ * @returns {object} Validation result with valid, error, suggestion, type, client, description
+ */
+function validateBranchName(branchName) {
+  if (!branchName || typeof branchName !== 'string') {
+    return {
+      valid: false,
+      error: 'Branch name is required',
+      suggestion:
+        'Use: feature/CLIENT/description, fix/CLIENT/description, docs/description, or chore/description',
+      type: null,
+      client: null,
+      description: null,
+    };
+  }
+
+  // Check if valid
+  if (isValidBranchName(branchName)) {
+    // Parse the branch name to extract components
+    const parsed = parseBranchName(branchName);
+    return {
+      valid: true,
+      error: null,
+      suggestion: null,
+      ...parsed,
+    };
+  }
+
+  // Generate helpful error message
+  const suggestion = generateSuggestion(branchName);
+
+  return {
+    valid: false,
+    error: `Branch name "${branchName}" does not follow CloudStream conventions`,
+    suggestion,
+    type: null,
+    client: null,
+    description: null,
+  };
+}
+
+/**
+ * Parse a valid branch name into components.
+ * @param {string} branchName - Valid branch name
+ * @returns {object} Parsed components
+ */
+function parseBranchName(branchName) {
+  if (branchName === 'main' || branchName === 'develop') {
+    return { type: branchName, client: null, description: null };
+  }
+
+  const parts = branchName.split('/');
+
+  if (parts.length === 2) {
+    // docs/description or chore/description
+    return {
+      type: parts[0],
+      client: null,
+      description: parts[1],
+    };
+  }
+
+  if (parts.length === 3) {
+    // feature/CLIENT/description
+    return {
+      type: parts[0],
+      client: parts[1],
+      description: parts[2],
+    };
+  }
+
+  return { type: null, client: null, description: null };
+}
+
+/**
+ * Generate a suggestion for an invalid branch name.
+ * @param {string} branchName - Invalid branch name
+ * @returns {string} Suggestion message
+ */
+function generateSuggestion(branchName) {
+  const parts = branchName.split('/');
+
+  if (parts.length === 1) {
+    return 'Try: feature/CSS/your-feature-name or docs/your-doc-name';
+  }
+
+  const type = parts[0].toLowerCase();
+
+  if (VALID_TYPES.includes(type)) {
+    if (CLIENT_REQUIRED_TYPES.includes(type) && parts.length === 2) {
+      return `${type}/ branches require a CLIENT ID: ${type}/CSS/${parts[1] || 'description'}`;
+    }
+  }
+
+  return 'Valid formats: feature/CLIENT/description, fix/CLIENT/description, docs/description, chore/description';
+}
+
+/**
+ * Convert a string to kebab-case.
+ * @param {string} str - Input string
+ * @returns {string} Kebab-case string
+ */
+function toKebabCase(str) {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '') // Remove special chars
+    .replace(/\s+/g, '-') // Replace spaces with hyphens
+    .replace(/-+/g, '-') // Remove consecutive hyphens
+    .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+}
+
+/**
+ * Create a properly formatted branch name.
+ * @param {string} type - Branch type (feature, fix, hotfix, docs, chore)
+ * @param {string|null} client - Client ID (required for feature, fix, hotfix)
+ * @param {string} description - Branch description
+ * @returns {string} Formatted branch name
+ * @throws {Error} If invalid type or missing required client
+ */
+function createBranchName(type, client, description) {
+  if (!VALID_TYPES.includes(type)) {
+    throw new Error(`Invalid branch type: ${type}. Valid types: ${VALID_TYPES.join(', ')}`);
+  }
+
+  const kebabDescription = toKebabCase(description);
+
+  if (CLIENT_REQUIRED_TYPES.includes(type)) {
+    if (!client) {
+      throw new Error(
+        `Client ID required for ${type} branches. Use: ${type}/CLIENT/${kebabDescription}`
+      );
+    }
+    return `${type}/${client.toUpperCase()}/${kebabDescription}`;
+  }
+
+  // docs and chore don't require client
+  return `${type}/${kebabDescription}`;
+}
+
+/**
+ * Get the current git branch name.
+ * @returns {string|null} Current branch name or null if not in a git repo
+ */
+function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Main CLI entry point.
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Branch Name Validator
+
+Usage:
+  node branch-name-validator.js <branch-name>  Validate a specific branch name
+  node branch-name-validator.js --current      Validate current git branch
+  node branch-name-validator.js --help         Show this help
+
+Valid branch formats:
+  feature/CLIENT/description   New feature (e.g., feature/CSS/add-login)
+  fix/CLIENT/description       Bug fix (e.g., fix/ACME/bug-123)
+  hotfix/CLIENT/description    Critical fix (e.g., hotfix/CSS/urgent)
+  docs/description             Documentation (e.g., docs/update-readme)
+  chore/description            Maintenance (e.g., chore/cleanup)
+  main                         Main branch
+  develop                      Development branch
+`);
+    process.exit(0);
+  }
+
+  let branchName;
+
+  if (args.includes('--current') || args.includes('-c')) {
+    branchName = getCurrentBranch();
+    if (!branchName) {
+      console.error('Error: Not in a git repository');
+      process.exit(1);
+    }
+  } else if (args.length > 0) {
+    branchName = args[0];
+  } else {
+    // Default to current branch
+    branchName = getCurrentBranch();
+    if (!branchName) {
+      console.error('Error: No branch name provided and not in a git repository');
+      process.exit(1);
+    }
+  }
+
+  const result = validateBranchName(branchName);
+
+  if (result.valid) {
+    console.log(`✓ Branch "${branchName}" is valid`);
+    if (result.type && result.type !== 'main' && result.type !== 'develop') {
+      console.log(`  Type: ${result.type}`);
+      if (result.client) console.log(`  Client: ${result.client}`);
+      if (result.description) console.log(`  Description: ${result.description}`);
+    }
+    process.exit(0);
+  } else {
+    console.error(`✗ ${result.error}`);
+    if (result.suggestion) {
+      console.error(`  Suggestion: ${result.suggestion}`);
+    }
+    process.exit(1);
+  }
+}
+
+// Export for testing
+module.exports = {
+  VALID_PATTERNS,
+  VALID_TYPES,
+  CLIENT_REQUIRED_TYPES,
+  isValidBranchName,
+  validateBranchName,
+  createBranchName,
+  toKebabCase,
+  getCurrentBranch,
+};
+
+// Run CLI if executed directly
+if (require.main === module) {
+  main();
+}

package/scripts/build.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Build script for @cloudstreamsoftware/claude-tools
+ * Creates the dist directory with entry point and copies necessary files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const DIST = path.join(ROOT, 'dist');
+
+// Ensure dist directory exists
+if (!fs.existsSync(DIST)) {
+  fs.mkdirSync(DIST, { recursive: true });
+}
+
+// Create dist/index.js entry point
+const indexContent = `/**
+ * @cloudstreamsoftware/claude-tools
+ * CloudStream Claude Code productivity tools
+ */
+
+'use strict';
+
+const path = require('path');
+
+// Export package paths for programmatic use
+module.exports = {
+  // Root directory of the installed package
+  root: path.resolve(__dirname, '..'),
+
+  // Paths to key directories
+  paths: {
+    hooks: path.resolve(__dirname, '..', 'hooks'),
+    scripts: path.resolve(__dirname, '..', 'scripts'),
+    skills: path.resolve(__dirname, '..', 'skills'),
+    agents: path.resolve(__dirname, '..', 'agents'),
+    config: path.resolve(__dirname, '..', 'config'),
+  },
+
+  // Get the hooks configuration
+  getHooksConfig: function() {
+    const hooksPath = path.join(this.paths.hooks, 'hooks.json');
+    return require(hooksPath);
+  },
+
+  // Get available skills
+  getSkills: function() {
+    const skillsDir = this.paths.skills;
+    if (!require('fs').existsSync(skillsDir)) return [];
+    return require('fs').readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  },
+
+  // Get available agents
+  getAgents: function() {
+    const agentsDir = this.paths.agents;
+    if (!require('fs').existsSync(agentsDir)) return [];
+    return require('fs').readdirSync(agentsDir)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.replace('.md', ''));
+  }
+};
+`;
+
+fs.writeFileSync(path.join(DIST, 'index.js'), indexContent);
+console.log('✓ Created dist/index.js');
+
+// Create dist/hooks directory and copy hooks.json
+const distHooks = path.join(DIST, 'hooks');
+if (!fs.existsSync(distHooks)) {
+  fs.mkdirSync(distHooks, { recursive: true });
+}
+
+const hooksSource = path.join(ROOT, 'hooks', 'hooks.json');
+if (fs.existsSync(hooksSource)) {
+  fs.copyFileSync(hooksSource, path.join(distHooks, 'hooks.json'));
+  console.log('✓ Copied hooks/hooks.json to dist/hooks/');
+}
+
+// Create dist/lib directory for any compiled utilities
+const distLib = path.join(DIST, 'lib');
+if (!fs.existsSync(distLib)) {
+  fs.mkdirSync(distLib, { recursive: true });
+}
+
+// Copy lib utilities to dist/lib
+const libSource = path.join(ROOT, 'scripts', 'lib');
+if (fs.existsSync(libSource)) {
+  const libFiles = fs.readdirSync(libSource).filter(f => f.endsWith('.js'));
+  libFiles.forEach(file => {
+    fs.copyFileSync(path.join(libSource, file), path.join(distLib, file));
+  });
+  console.log(`✓ Copied ${libFiles.length} lib files to dist/lib/`);
+}
+
+console.log('\n✅ Build complete!');
+console.log(`   Package: @cloudstreamsoftware/claude-tools`);
+console.log(`   Output:  ${DIST}`);