specweave 0.11.0 → 0.12.1

package/plugins/specweave/lib/hooks/git-diff-analyzer.ts

@@ -0,0 +1,269 @@
+/**
+ * Git Diff Analyzer
+ *
+ * Extracts modified files from git diff for reflection analysis
+ * Parses git diff output to get file changes, line counts, and content
+ *
+ * @module git-diff-analyzer
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs-extra';
+import path from 'path';
+import { GitDiffInfo } from './types/reflection-types';
+
+/**
+ * Execute git command safely
+ * @param command Git command to execute
+ * @param cwd Working directory (optional)
+ * @returns Command output as string
+ * @throws Error if command fails
+ */
+function executeGitCommand(command: string, cwd?: string): string {
+  try {
+    return execSync(command, {
+      cwd: cwd || process.cwd(),
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+  } catch (error: any) {
+    throw new Error(`Git command failed: ${command}. ${error.message}`);
+  }
+}
+
+/**
+ * Check if directory is a git repository
+ * @param dir Directory to check (defaults to cwd)
+ * @returns True if directory is in a git repository
+ */
+export function isGitRepository(dir: string = process.cwd()): boolean {
+  try {
+    executeGitCommand('git rev-parse --git-dir', dir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get list of modified files in the working directory
+ * Includes both staged and unstaged changes
+ *
+ * @param cwd Working directory (optional, defaults to process.cwd())
+ * @returns Array of file paths relative to git root
+ */
+export function getModifiedFilesList(cwd?: string): string[] {
+  if (!isGitRepository(cwd)) {
+    return [];
+  }
+
+  try {
+    // Get both staged and unstaged changes
+    const output = executeGitCommand('git diff --name-only HEAD', cwd);
+
+    if (!output.trim()) {
+      return [];
+    }
+
+    return output
+      .trim()
+      .split('\n')
+      .filter(file => file.length > 0)
+      .filter(file => !file.startsWith('.git/')); // Exclude .git directory
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Parse git diff numstat output to get line counts
+ * Format: <added>\t<removed>\t<filename>
+ *
+ * @param numstatOutput Output from git diff --numstat
+ * @returns Map of filename to {added, removed} counts
+ */
+export function parseNumstat(numstatOutput: string): Map<string, { added: number; removed: number }> {
+  const stats = new Map<string, { added: number; removed: number }>();
+
+  if (!numstatOutput.trim()) {
+    return stats;
+  }
+
+  const lines = numstatOutput.trim().split('\n');
+
+  for (const line of lines) {
+    const parts = line.split('\t');
+    if (parts.length < 3) continue;
+
+    const added = parts[0] === '-' ? 0 : parseInt(parts[0], 10);
+    const removed = parts[1] === '-' ? 0 : parseInt(parts[1], 10);
+    const filename = parts[2];
+
+    stats.set(filename, { added, removed });
+  }
+
+  return stats;
+}
+
+/**
+ * Get diff content for a specific file
+ * @param file File path relative to git root
+ * @param cwd Working directory (optional)
+ * @returns Diff content as string
+ */
+export function getFileDiff(file: string, cwd?: string): string {
+  if (!isGitRepository(cwd)) {
+    return '';
+  }
+
+  try {
+    // Get unified diff for the file
+    const output = executeGitCommand(`git diff HEAD -- "${file}"`, cwd);
+    return output;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Get current file content
+ * @param file File path (can be absolute or relative to cwd)
+ * @param cwd Working directory (optional)
+ * @returns File content as string, or empty string if file doesn't exist
+ */
+export function getFileContent(file: string, cwd?: string): string {
+  try {
+    const workingDir = cwd || process.cwd();
+    const absolutePath = path.isAbsolute(file) ? file : path.join(workingDir, file);
+
+    if (!fs.existsSync(absolutePath)) {
+      return '';
+    }
+
+    return fs.readFileSync(absolutePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Get modified files with diff information
+ * Main function for reflection analysis
+ *
+ * @param cwd Working directory (optional, defaults to process.cwd())
+ * @param maxFiles Maximum number of files to return (optional, defaults to 100)
+ * @returns Array of GitDiffInfo objects with file changes
+ */
+export function getModifiedFiles(
+  cwd?: string,
+  maxFiles: number = 100
+): GitDiffInfo[] {
+  if (!isGitRepository(cwd)) {
+    return [];
+  }
+
+  const workingDir = cwd || process.cwd();
+
+  // Get list of modified files
+  const modifiedFiles = getModifiedFilesList(workingDir);
+
+  if (modifiedFiles.length === 0) {
+    return [];
+  }
+
+  // Limit number of files to prevent overwhelming the analysis
+  const filesToAnalyze = modifiedFiles.slice(0, maxFiles);
+
+  // Get line count statistics
+  let numstatOutput = '';
+  try {
+    numstatOutput = executeGitCommand('git diff --numstat HEAD', workingDir);
+  } catch {
+    // If numstat fails, continue with empty stats
+  }
+
+  const stats = parseNumstat(numstatOutput);
+
+  // Build GitDiffInfo array
+  const result: GitDiffInfo[] = [];
+
+  for (const file of filesToAnalyze) {
+    const fileStat = stats.get(file) || { added: 0, removed: 0 };
+    const diffContent = getFileDiff(file, workingDir);
+
+    // Only include files with actual changes
+    if (fileStat.added > 0 || fileStat.removed > 0 || diffContent.length > 0) {
+      result.push({
+        file,
+        linesAdded: fileStat.added,
+        linesRemoved: fileStat.removed,
+        content: diffContent
+      });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get summary statistics for modified files
+ * Useful for reflection metadata
+ *
+ * @param modifiedFiles Array of GitDiffInfo objects
+ * @returns Summary with file count, total lines added/removed
+ */
+export function getModifiedFilesSummary(modifiedFiles: GitDiffInfo[]): {
+  count: number;
+  linesAdded: number;
+  linesRemoved: number;
+  totalChanges: number;
+} {
+  return {
+    count: modifiedFiles.length,
+    linesAdded: modifiedFiles.reduce((sum, file) => sum + file.linesAdded, 0),
+    linesRemoved: modifiedFiles.reduce((sum, file) => sum + file.linesRemoved, 0),
+    totalChanges: modifiedFiles.reduce(
+      (sum, file) => sum + file.linesAdded + file.linesRemoved,
+      0
+    )
+  };
+}
+
+/**
+ * Filter files by extension
+ * Useful for focusing reflection on specific file types
+ *
+ * @param modifiedFiles Array of GitDiffInfo objects
+ * @param extensions Array of file extensions (e.g., ['.ts', '.js'])
+ * @returns Filtered array of GitDiffInfo objects
+ */
+export function filterFilesByExtension(
+  modifiedFiles: GitDiffInfo[],
+  extensions: string[]
+): GitDiffInfo[] {
+  return modifiedFiles.filter(file => {
+    const ext = path.extname(file.file).toLowerCase();
+    return extensions.some(allowedExt => ext === allowedExt.toLowerCase());
+  });
+}
+
+/**
+ * Exclude files matching patterns
+ * Useful for excluding generated files, test files, etc.
+ *
+ * @param modifiedFiles Array of GitDiffInfo objects
+ * @param patterns Array of glob patterns to exclude
+ * @returns Filtered array of GitDiffInfo objects
+ */
+export function excludeFilesByPattern(
+  modifiedFiles: GitDiffInfo[],
+  patterns: string[]
+): GitDiffInfo[] {
+  return modifiedFiles.filter(file => {
+    return !patterns.some(pattern => {
+      // Simple pattern matching (supports * wildcard)
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      return regex.test(file.file);
+    });
+  });
+}

package/plugins/specweave/lib/hooks/invoke-translator-skill.ts

@@ -0,0 +1,264 @@
+/**
+ * Translator Skill Invocation Utility
+ *
+ * Provides programmatic invocation of the translator skill for automated translation.
+ * Used by hooks and CLI scripts to translate content without manual intervention.
+ *
+ * @see plugins/specweave/skills/translator/SKILL.md
+ * @see plugins/specweave/commands/translate.md
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import {
+  detectLanguage,
+  prepareTranslation,
+  postProcessTranslation,
+  getLanguageName,
+  type SupportedLanguage,
+} from '../../../../src/utils/translation.js';
+
+/**
+ * Translation result
+ */
+export interface TranslationResult {
+  success: boolean;
+  sourceLanguage: SupportedLanguage;
+  targetLanguage: SupportedLanguage;
+  originalContent: string;
+  translatedContent?: string;
+  error?: string;
+}
+
+/**
+ * Invokes translator skill to translate content
+ *
+ * This function integrates with the translator skill by:
+ * 1. Preparing translation prompt
+ * 2. Writing prompt to a temp file
+ * 3. Outputting instructions for Claude to process
+ * 4. Returning the translated content
+ *
+ * In an automated context (hooks), this provides clear instructions.
+ * In an interactive context, the translator skill can auto-activate.
+ *
+ * @param content - Content to translate
+ * @param sourceLang - Source language
+ * @param targetLang - Target language
+ * @returns Translation result
+ */
+export async function invokeTranslatorSkill(
+  content: string,
+  sourceLang: SupportedLanguage,
+  targetLang: SupportedLanguage = 'en'
+): Promise<TranslationResult> {
+  try {
+    // Prepare translation
+    const prepared = prepareTranslation(content, sourceLang, targetLang);
+
+    // For now, we use a practical approach:
+    // Output the translation request clearly so it can be processed
+
+    const result: TranslationResult = {
+      success: true,
+      sourceLanguage: sourceLang,
+      targetLanguage: targetLang,
+      originalContent: content,
+      translatedContent: await performTranslation(prepared.prompt, prepared.preserved),
+    };
+
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      sourceLanguage: sourceLang,
+      targetLanguage: targetLang,
+      originalContent: content,
+      error: errorMessage,
+    };
+  }
+}
+
+/**
+ * Performs the actual translation using Anthropic API
+ *
+ * PRODUCTION IMPLEMENTATION:
+ * 1. Checks for ANTHROPIC_API_KEY in environment
+ * 2. If available: Uses Anthropic API directly (fully automatic)
+ * 3. If not available: Provides clear instructions for manual translation
+ *
+ * @param prompt - Translation prompt
+ * @param preserved - Preserved content structure
+ * @returns Translated content
+ */
+async function performTranslation(
+  prompt: string,
+  preserved: any
+): Promise<string> {
+  // Extract content for processing
+  const contentMatch = prompt.match(/SOURCE DOCUMENT[^\n]*:\n---\n([\s\S]*?)\n---/);
+  const contentToTranslate = contentMatch ? contentMatch[1] : '';
+
+  // Check if ANTHROPIC_API_KEY is available
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+
+  if (apiKey) {
+    // Fully automatic translation using Anthropic API
+    console.log(`\n🤖 Translating via Anthropic API (Haiku model)...`);
+
+    try {
+      // Dynamic import of Anthropic SDK (allows graceful fallback if not installed)
+      const Anthropic = await import('@anthropic-ai/sdk').then(m => m.default);
+
+      const anthropic = new Anthropic({
+        apiKey,
+      });
+
+      const message = await anthropic.messages.create({
+        model: 'claude-3-haiku-20240307',
+        max_tokens: 8000,
+        messages: [
+          {
+            role: 'user',
+            content: prompt,
+          },
+        ],
+      });
+
+      // Extract translated content from response
+      const translatedContent = message.content[0].type === 'text'
+        ? message.content[0].text
+        : contentToTranslate;
+
+      console.log(`✅ Translation complete via API`);
+      console.log(`   Input tokens: ${message.usage.input_tokens}`);
+      console.log(`   Output tokens: ${message.usage.output_tokens}`);
+      console.log(`   Cost: ~$${((message.usage.input_tokens * 0.25 + message.usage.output_tokens * 1.25) / 1000000).toFixed(4)}\n`);
+
+      return postProcessTranslation(translatedContent, preserved);
+    } catch (error: any) {
+      console.error(`\n❌ API translation failed: ${error.message}`);
+      console.error(`   Falling back to manual translation instructions\n`);
+      // Fall through to manual instructions
+    }
+  }
+
+  // Fallback: Manual translation instructions
+  const isInteractive = process.env.CLAUDE_CODE_SESSION === 'true';
+
+  if (isInteractive) {
+    // In Claude Code environment, output translation request
+    console.log('\n' + '='.repeat(80));
+    console.log('🌐 TRANSLATION REQUEST (translator skill will auto-activate)');
+    console.log('='.repeat(80));
+    console.log(prompt);
+    console.log('='.repeat(80));
+    console.log('💡 Tip: Set ANTHROPIC_API_KEY for fully automatic translation\n');
+
+    return postProcessTranslation(
+      `<!-- ⚠️ TRANSLATION REQUESTED - Awaiting translator skill activation -->\n\n${contentToTranslate}`,
+      preserved
+    );
+  } else {
+    // Non-interactive environment - provide clear instructions
+    console.error('\n⚠️  AUTO-TRANSLATION REQUIRES ONE OF:');
+    console.error('   Option A (Recommended): Set ANTHROPIC_API_KEY environment variable');
+    console.error('   Option B: Run /specweave:translate <file-path>');
+    console.error('   Option C: Manually translate the content\n');
+
+    return postProcessTranslation(
+      `<!-- ⚠️ AUTO-TRANSLATION PENDING -->\n<!-- Set ANTHROPIC_API_KEY for automatic translation -->\n<!-- Or run: /specweave:translate to complete -->\n<!-- Original content below -->\n\n${contentToTranslate}`,
+      preserved
+    );
+  }
+}
+
+/**
+ * Translate a file using translator skill
+ *
+ * @param filePath - Path to file to translate
+ * @param targetLang - Target language
+ * @returns Translation result
+ */
+export async function translateFile(
+  filePath: string,
+  targetLang: SupportedLanguage = 'en'
+): Promise<TranslationResult & { filePath: string }> {
+  // Read file
+  if (!await fs.pathExists(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const content = await fs.readFile(filePath, 'utf-8');
+
+  // Detect source language
+  const detection = detectLanguage(content);
+  const sourceLang = detection.language;
+
+  // Check if already in target language
+  if (sourceLang === targetLang) {
+    return {
+      success: true,
+      filePath,
+      sourceLanguage: sourceLang,
+      targetLanguage: targetLang,
+      originalContent: content,
+      translatedContent: content,
+    };
+  }
+
+  // Translate
+  const result = await invokeTranslatorSkill(content, sourceLang, targetLang);
+
+  // Write back if successful
+  if (result.success && result.translatedContent) {
+    await fs.writeFile(filePath, result.translatedContent, 'utf-8');
+    console.log(`✅ Translated: ${filePath} (${getLanguageName(sourceLang)} → ${getLanguageName(targetLang)})`);
+  }
+
+  return {
+    ...result,
+    filePath,
+  };
+}
+
+/**
+ * Batch translate multiple files
+ *
+ * @param filePaths - Array of file paths
+ * @param targetLang - Target language
+ * @returns Array of translation results
+ */
+export async function batchTranslateFiles(
+  filePaths: string[],
+  targetLang: SupportedLanguage = 'en'
+): Promise<Array<TranslationResult & { filePath: string }>> {
+  const results: Array<TranslationResult & { filePath: string }> = [];
+
+  console.log(`\n🌐 Batch translating ${filePaths.length} file(s) to ${getLanguageName(targetLang)}...\n`);
+
+  for (const filePath of filePaths) {
+    try {
+      const result = await translateFile(filePath, targetLang);
+      results.push(result);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error(`❌ Failed to translate ${filePath}: ${errorMessage}`);
+      results.push({
+        success: false,
+        filePath,
+        sourceLanguage: 'unknown',
+        targetLanguage: targetLang,
+        originalContent: '',
+        error: errorMessage,
+      });
+    }
+  }
+
+  // Summary
+  const successful = results.filter(r => r.success).length;
+  console.log(`\n📊 Batch translation complete: ${successful}/${filePaths.length} files translated\n`);
+
+  return results;
+}

package/plugins/specweave/lib/hooks/prepare-reflection-context.ts

@@ -0,0 +1,178 @@
+/**
+ * Prepare Reflection Context
+ *
+ * Prepares context for reflection and saves to temp file
+ * Used by post-task-completion hook to prepare for reflection invocation
+ *
+ * @module prepare-reflection-context
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { createReflectionContext } from './run-self-reflection';
+import { getModifiedFilesSummary } from './git-diff-analyzer';
+
+/**
+ * Prepare reflection context and save to temp file
+ * This allows the hook to prepare data without actually invoking the agent
+ *
+ * @param incrementId Increment identifier
+ * @param taskId Task identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns Path to saved context file or null if reflection should be skipped
+ */
+export function prepareReflectionContext(
+  incrementId: string,
+  taskId: string,
+  projectRoot?: string
+): string | null {
+  try {
+    const context = createReflectionContext(incrementId, taskId, projectRoot);
+
+    // Check if reflection should run
+    if (!context.config.enabled || context.modifiedFiles.length === 0) {
+      return null;
+    }
+
+    // Create temp directory for reflection context
+    const rootDir = projectRoot || process.cwd();
+    const tempDir = path.join(rootDir, '.specweave', 'increments', incrementId, 'logs', 'reflections', '.temp');
+    fs.mkdirpSync(tempDir);
+
+    // Save context to temp file
+    const contextFile = path.join(tempDir, 'reflection-context.json');
+
+    const fileStats = getModifiedFilesSummary(context.modifiedFiles);
+
+    const contextData = {
+      incrementId: context.incrementId,
+      taskId: context.taskId,
+      modifiedFiles: context.modifiedFiles.map(f => ({
+        file: f.file,
+        linesAdded: f.linesAdded,
+        linesRemoved: f.linesRemoved
+        // Exclude diff content to save space
+      })),
+      fileSummary: {
+        count: fileStats.count,
+        linesAdded: fileStats.linesAdded,
+        linesRemoved: fileStats.linesRemoved
+      },
+      config: context.config,
+      timestamp: new Date().toISOString()
+    };
+
+    fs.writeJsonSync(contextFile, contextData, { spaces: 2 });
+
+    return contextFile;
+  } catch (error: any) {
+    console.error(`Failed to prepare reflection context: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Check if reflection context exists for an increment
+ *
+ * @param incrementId Increment identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns True if context file exists
+ */
+export function hasReflectionContext(
+  incrementId: string,
+  projectRoot?: string
+): boolean {
+  const rootDir = projectRoot || process.cwd();
+  const contextFile = path.join(
+    rootDir,
+    '.specweave',
+    'increments',
+    incrementId,
+    'logs',
+    'reflections',
+    '.temp',
+    'reflection-context.json'
+  );
+
+  return fs.existsSync(contextFile);
+}
+
+/**
+ * Read reflection context from file
+ *
+ * @param incrementId Increment identifier
+ * @param projectRoot Project root directory (optional)
+ * @returns Context data or null if not found
+ */
+export function readReflectionContext(
+  incrementId: string,
+  projectRoot?: string
+): any | null {
+  const rootDir = projectRoot || process.cwd();
+  const contextFile = path.join(
+    rootDir,
+    '.specweave',
+    'increments',
+    incrementId,
+    'logs',
+    'reflections',
+    '.temp',
+    'reflection-context.json'
+  );
+
+  if (!fs.existsSync(contextFile)) {
+    return null;
+  }
+
+  try {
+    return fs.readJsonSync(contextFile);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clear reflection context after reflection completes
+ *
+ * @param incrementId Increment identifier
+ * @param projectRoot Project root directory (optional)
+ */
+export function clearReflectionContext(
+  incrementId: string,
+  projectRoot?: string
+): void {
+  const rootDir = projectRoot || process.cwd();
+  const tempDir = path.join(
+    rootDir,
+    '.specweave',
+    'increments',
+    incrementId,
+    'logs',
+    'reflections',
+    '.temp'
+  );
+
+  if (fs.existsSync(tempDir)) {
+    fs.removeSync(tempDir);
+  }
+}
+
+// CLI entry point for hook integration
+if (require.main === module) {
+  const incrementId = process.argv[2];
+  const taskId = process.argv[3];
+
+  if (!incrementId || !taskId) {
+    console.error('Usage: node prepare-reflection-context.js <increment-id> <task-id>');
+    process.exit(1);
+  }
+
+  const contextFile = prepareReflectionContext(incrementId, taskId);
+
+  if (contextFile) {
+    console.log(`Reflection context prepared: ${contextFile}`);
+    console.log('✨ Reflection ready. Run /specweave:reflect to analyze your work.');
+  } else {
+    console.log('Reflection skipped (disabled or no changes).');
+  }
+}