@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/scripts/hooks/session-start.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * SessionStart Hook - Load previous context on new session
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs when a new Claude session starts. Checks for recent session
+ * files and notifies Claude of available context to load.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const {
+  getSessionsDir,
+  getLearnedSkillsDir,
+  getClaudeDir,
+  findFiles,
+  ensureDir,
+  log,
+} = require('../lib/utils');
+const { getPackageManager, getSelectionPrompt } = require('../lib/package-manager');
+
+// Try to load recommendation engine
+let getSessionStartRecommendations = null;
+try {
+  const recEngine = require('../lib/recommendation-engine');
+  getSessionStartRecommendations = recEngine.getSessionStartRecommendations;
+} catch {
+  // Recommendation engine not available
+}
+
+async function main() {
+  const sessionsDir = getSessionsDir();
+  const learnedDir = getLearnedSkillsDir();
+
+  // Ensure directories exist
+  ensureDir(sessionsDir);
+  ensureDir(learnedDir);
+
+  // Check for recent session files (last 7 days)
+  const recentSessions = findFiles(sessionsDir, '*.tmp', { maxAge: 7 });
+
+  if (recentSessions.length > 0) {
+    const latest = recentSessions[0];
+    log(`[SessionStart] Found ${recentSessions.length} recent session(s)`);
+    log(`[SessionStart] Latest: ${latest.path}`);
+  }
+
+  // Check for learned skills
+  const learnedSkills = findFiles(learnedDir, '*.md');
+
+  if (learnedSkills.length > 0) {
+    log(`[SessionStart] ${learnedSkills.length} learned skill(s) available in ${learnedDir}`);
+  }
+
+  // Detect and report package manager
+  const pm = getPackageManager();
+  log(`[SessionStart] Package manager: ${pm.name} (${pm.source})`);
+
+  // If package manager was detected via fallback, show selection prompt
+  if (pm.source === 'fallback' || pm.source === 'default') {
+    log('[SessionStart] No package manager preference found.');
+    log(getSelectionPrompt());
+  }
+
+  // Load client context if available
+  const clientId = process.env.CLOUDSTREAM_CLIENT_ID;
+  const complianceMode = process.env.CLOUDSTREAM_COMPLIANCE_MODE || 'standard';
+
+  if (clientId) {
+    log(`[SessionStart] Client: ${clientId} | Compliance: ${complianceMode}`);
+  }
+
+  // Check for pre-compact context restoration
+  const contextFile = path.join(sessionsDir, 'pre-compact-context.json');
+  if (fs.existsSync(contextFile)) {
+    try {
+      const savedContext = JSON.parse(fs.readFileSync(contextFile, 'utf8'));
+      log(
+        `[SessionStart] Restored context: Client=${savedContext.activeClient}, Compliance=${savedContext.complianceMode}`
+      );
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  // Check if this is a first-time user (no sessions and no tutorial progress)
+  const milestonesFile = path.join(getClaudeDir(), 'onboarding', 'milestones.json');
+  const isFirstTime = recentSessions.length === 0 && !fs.existsSync(milestonesFile);
+
+  if (isFirstTime) {
+    log('');
+    log('Welcome to CloudStream Claude Code!');
+    log('');
+    log('Get started:');
+    log('  /onboard      - Interactive setup wizard (recommended)');
+    log('  /health-check - Verify your environment is configured correctly');
+    log('  /tutorial     - Interactive 15-lesson tutorial');
+    log('  /plan         - Plan a feature before coding');
+    log('');
+    log('Need help? Run /diagnose for troubleshooting');
+    log('Documentation: README.md, GETTING-STARTED.md');
+    log('');
+  }
+
+  // Check for tutorial progress
+  try {
+    const tutorialProgress = require('../lib/tutorial-progress');
+    if (tutorialProgress.hasProgress()) {
+      const progress = tutorialProgress.loadProgress();
+      if (!tutorialProgress.isComplete(progress)) {
+        const percent = tutorialProgress.getCompletionPercent(progress);
+        log(
+          `[SessionStart] Tutorial in progress: ${percent}% complete (${progress.completedLessons.length}/9 lessons)`
+        );
+        log(`[SessionStart] Resume with: /tutorial ${progress.currentLesson}`);
+      }
+    }
+  } catch {
+    // Tutorial module not available, skip
+  }
+
+  // Surface recommendations from cross-session analysis
+  await surfaceRecommendations();
+
+  process.exit(0);
+}
+
+/**
+ * Load aggregation config
+ */
+function loadAggregationConfig() {
+  const configPath = path.join(__dirname, '..', '..', 'config', 'aggregation.json');
+  try {
+    if (fs.existsSync(configPath)) {
+      return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+  } catch {
+    // Config not available
+  }
+  return { recommendations: { enabled: false } };
+}
+
+/**
+ * Surface recommendations at session start
+ */
+async function surfaceRecommendations() {
+  const config = loadAggregationConfig();
+
+  // Check if recommendations are enabled
+  if (!config.recommendations?.enabled || !config.recommendations?.showAtSessionStart) {
+    return;
+  }
+
+  // Check if recommendation engine is available
+  if (!getSessionStartRecommendations) {
+    return;
+  }
+
+  try {
+    const maxRecs = config.recommendations.maxAtSessionStart || 3;
+    const recommendations = getSessionStartRecommendations(maxRecs);
+
+    if (recommendations.length === 0) {
+      return;
+    }
+
+    log('');
+    log('[SessionStart] Insights from your recent sessions:');
+    log('');
+
+    for (const rec of recommendations) {
+      const emoji = rec.priority === 'high' ? '[!]' : rec.priority === 'medium' ? '[*]' : '[-]';
+
+      log(`  ${emoji} ${rec.title}`);
+      log(`      ${rec.message}`);
+
+      if (rec.action) {
+        log(`      Action: ${rec.action}`);
+      }
+      log('');
+    }
+
+    log('  Run /recommendations for full list');
+    log('');
+  } catch (err) {
+    // Don't block session start on recommendation errors
+    log(`[SessionStart] Could not load recommendations: ${err.message}`);
+  }
+}
+
+main().catch((err) => {
+  console.error('[SessionStart] Error:', err.message);
+  process.exit(0); // Don't block on errors
+});

package/scripts/hooks/skill-injector.js

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Injector Hook - Auto-Apply Relevant Skills
+ *
+ * This hook runs on PreToolUse (Edit, Write, Read) to detect relevant
+ * skills based on file context and inject them as guidance.
+ *
+ * Performance: Lightweight matching, only reads skill content for high-confidence matches.
+ *
+ * Hook Type: PreToolUse
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readStdinJson, log, output, readFile, getClaudeDir } = require('../lib/utils');
+const {
+  buildContext,
+  matchSkills,
+  formatMatchedSkills,
+  getSkillContent,
+  loadLearnedSkills,
+} = require('../lib/skill-matcher');
+const { loadSessionMemory, updateContext } = require('../lib/session-memory');
+
+// Cache to avoid re-matching for same file in same session
+const matchCache = new Map();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * Get cached match or compute new one
+ */
+function getCachedOrMatch(filePath, content) {
+  const cacheKey = `${filePath}:${content?.length || 0}`;
+
+  const cached = matchCache.get(cacheKey);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+    return cached.matches;
+  }
+
+  // Build context and match
+  const sessionMemory = loadSessionMemory();
+  const context = buildContext(filePath, content, {
+    complianceMode: sessionMemory.context?.complianceMode || null,
+    technologies: sessionMemory.context?.technologies || [],
+  });
+
+  const matches = matchSkills(context);
+
+  // Cache result
+  matchCache.set(cacheKey, {
+    matches,
+    timestamp: Date.now(),
+  });
+
+  // Update session context with detected technologies
+  if (context.technologies.size > 0) {
+    updateContext({
+      files: [filePath],
+      technologies: Array.from(context.technologies),
+    });
+  }
+
+  return matches;
+}
+
+/**
+ * Get the most important skill guidance to show
+ */
+function getKeyGuidance(match) {
+  const content = getSkillContent(match);
+  if (!content) return null;
+
+  // Extract key sections based on skill type
+  const lines = content.split('\n');
+  const keyLines = [];
+
+  let inKeySection = false;
+  const keySectionHeaders = [
+    /^#+\s*(critical|important|must|always|never|constraints?|limits?|warnings?)/i,
+    /^#+\s*(quick reference|key points|summary)/i,
+  ];
+
+  for (let i = 0; i < lines.length && keyLines.length < 10; i++) {
+    const line = lines[i];
+
+    // Check if entering a key section
+    if (keySectionHeaders.some((pattern) => pattern.test(line))) {
+      inKeySection = true;
+      keyLines.push(line);
+      continue;
+    }
+
+    // Check if leaving section (next header)
+    if (inKeySection && /^#+\s/.test(line) && !keySectionHeaders.some((p) => p.test(line))) {
+      inKeySection = false;
+      continue;
+    }
+
+    // Collect content from key sections
+    if (inKeySection && line.trim()) {
+      keyLines.push(line);
+    }
+
+    // Also collect bullet points that look important
+    if (/^[-*]\s*(CRITICAL|IMPORTANT|MUST|ALWAYS|NEVER|WARNING|CAUTION):/i.test(line)) {
+      keyLines.push(line);
+    }
+  }
+
+  if (keyLines.length === 0) {
+    // Fallback: first 5 non-empty lines after first header
+    let foundHeader = false;
+    for (const line of lines) {
+      if (/^#/.test(line)) {
+        foundHeader = true;
+        continue;
+      }
+      if (foundHeader && line.trim() && keyLines.length < 5) {
+        keyLines.push(line);
+      }
+    }
+  }
+
+  return keyLines.join('\n');
+}
+
+/**
+ * Format deprecation warning for a match
+ */
+function formatDeprecationWarning(match) {
+  if (!match.deprecation) return null;
+
+  let warning = `  [DEPRECATED] This skill is deprecated`;
+
+  if (match.deprecation.supersededBy) {
+    warning += ` - use "${match.deprecation.supersededBy}" instead`;
+  }
+
+  if (match.deprecation.reason) {
+    warning += `\n    Reason: ${match.deprecation.reason}`;
+  }
+
+  if (match.deprecation.migrationGuide) {
+    warning += `\n    Migration guide: ${match.deprecation.migrationGuide}`;
+  }
+
+  if (match.deprecation.removalTarget) {
+    warning += `\n    Removal target: ${match.deprecation.removalTarget}`;
+  }
+
+  return warning + '\n';
+}
+
+/**
+ * Format skill guidance for stderr output
+ */
+function formatSkillGuidance(matches) {
+  if (matches.length === 0) return null;
+
+  let output = '';
+
+  // Show matched skills summary
+  output += '[Skill] Relevant patterns detected:\n';
+
+  for (const match of matches) {
+    const confidence = Math.round(match.score * 100);
+    const typeLabel = match.type === 'learned' ? '(learned)' : '';
+    const versionLabel = match.version ? ` v${match.version}` : '';
+
+    output += `\n[Skill] ${match.skill}${versionLabel} ${typeLabel} - ${confidence}% match\n`;
+
+    // Show deprecation warning if deprecated
+    if (match.deprecation) {
+      const deprecationWarning = formatDeprecationWarning(match);
+      if (deprecationWarning) {
+        output += deprecationWarning;
+      }
+    }
+
+    // Get key guidance for high-confidence matches
+    if (match.score >= 0.6) {
+      const guidance = getKeyGuidance(match);
+      if (guidance) {
+        // Indent guidance
+        const indentedGuidance = guidance
+          .split('\n')
+          .map((line) => `  ${line}`)
+          .join('\n');
+        output += indentedGuidance + '\n';
+      }
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Check for anti-patterns from session memory
+ */
+function checkAntiPatterns(content) {
+  const sessionMemory = loadSessionMemory();
+  const warnings = [];
+
+  // Check against session anti-patterns
+  if (sessionMemory.antiPatterns) {
+    for (const antiPattern of sessionMemory.antiPatterns) {
+      if (antiPattern.name && content.includes(antiPattern.name)) {
+        warnings.push({
+          type: 'anti-pattern',
+          name: antiPattern.name,
+          avoidance: antiPattern.avoidance,
+        });
+      }
+    }
+  }
+
+  // Check against corrections (things we've been told not to do)
+  if (sessionMemory.corrections) {
+    for (const correction of sessionMemory.corrections) {
+      if (correction.original && correction.count >= 2) {
+        // Only warn for repeated corrections
+        if (content.toLowerCase().includes(correction.original.toLowerCase())) {
+          warnings.push({
+            type: 'previous-correction',
+            original: correction.original,
+            corrected: correction.corrected,
+            count: correction.count,
+          });
+        }
+      }
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Format anti-pattern warnings
+ */
+function formatAntiPatternWarnings(warnings) {
+  if (warnings.length === 0) return null;
+
+  let output = '\n[Learning] Potential issues detected based on session history:\n';
+
+  for (const warning of warnings) {
+    if (warning.type === 'anti-pattern') {
+      output += `  - Anti-pattern: "${warning.name}"\n`;
+      if (warning.avoidance) {
+        output += `    Instead: ${warning.avoidance}\n`;
+      }
+    } else if (warning.type === 'previous-correction') {
+      output += `  - Previously corrected (${warning.count}x): "${warning.original}"\n`;
+      if (warning.corrected) {
+        output += `    Preferred: ${warning.corrected}\n`;
+      }
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Main hook execution
+ */
+async function main() {
+  try {
+    const input = await readStdinJson();
+    const tool = input.tool;
+    const toolInput = input.tool_input || {};
+
+    // Get file path based on tool
+    let filePath = null;
+    let content = null;
+
+    if (tool === 'Edit') {
+      filePath = toolInput.file_path;
+      content = toolInput.new_string || '';
+    } else if (tool === 'Write') {
+      filePath = toolInput.file_path;
+      content = toolInput.content || '';
+    } else if (tool === 'Read') {
+      filePath = toolInput.file_path;
+      // For Read, we don't have content yet, but can still match on file path
+      content = '';
+    }
+
+    if (!filePath) {
+      output(JSON.stringify(input));
+      return;
+    }
+
+    // Skip for non-code files
+    const codeExtensions = ['.ts', '.tsx', '.js', '.jsx', '.ds', '.sql', '.py', '.md'];
+    const ext = path.extname(filePath);
+    if (!codeExtensions.includes(ext)) {
+      output(JSON.stringify(input));
+      return;
+    }
+
+    // Get matched skills
+    const matches = getCachedOrMatch(filePath, content);
+
+    // Format and output skill guidance
+    if (matches.length > 0) {
+      const guidance = formatSkillGuidance(matches);
+      if (guidance) {
+        log(guidance);
+      }
+    }
+
+    // Check for anti-patterns in content being written
+    if (content && (tool === 'Edit' || tool === 'Write')) {
+      const warnings = checkAntiPatterns(content);
+      if (warnings.length > 0) {
+        const warningOutput = formatAntiPatternWarnings(warnings);
+        if (warningOutput) {
+          log(warningOutput);
+        }
+      }
+    }
+
+    // Pass through input unchanged
+    output(JSON.stringify(input));
+  } catch (err) {
+    // On error, log but don't block
+    log(`[SkillInjector] Error: ${err.message}`);
+    output('{}');
+  }
+}
+
+// Run
+main();

package/scripts/hooks/suggest-compact.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Strategic Compact Suggester
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs on PreToolUse or periodically to suggest manual compaction at logical intervals
+ *
+ * Why manual over auto-compact:
+ * - Auto-compact happens at arbitrary points, often mid-task
+ * - Strategic compacting preserves context through logical phases
+ * - Compact after exploration, before execution
+ * - Compact after completing a milestone, before starting next
+ */
+
+const path = require('path');
+const { getTempDir, readFile, writeFile, log } = require('../lib/utils');
+
+async function main() {
+  // Track tool call count (increment in a temp file)
+  // Use a session-specific counter file based on PID from parent process
+  // or session ID from environment
+  const sessionId = process.env.CLAUDE_SESSION_ID || process.ppid || 'default';
+  const counterFile = path.join(getTempDir(), `claude-tool-count-${sessionId}`);
+  const threshold = parseInt(process.env.COMPACT_THRESHOLD || '50', 10);
+
+  let count = 1;
+
+  // Read existing count or start at 1
+  const existing = readFile(counterFile);
+  if (existing) {
+    count = parseInt(existing.trim(), 10) + 1;
+  }
+
+  // Save updated count
+  writeFile(counterFile, String(count));
+
+  // Suggest compact after threshold tool calls
+  if (count === threshold) {
+    log(
+      `[StrategicCompact] ${threshold} tool calls reached - consider /compact if transitioning phases`
+    );
+  }
+
+  // Suggest at regular intervals after threshold
+  if (count > threshold && count % 25 === 0) {
+    log(
+      `[StrategicCompact] ${count} tool calls - good checkpoint for /compact if context is stale`
+    );
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('[StrategicCompact] Error:', err.message);
+  process.exit(0);
+});