solvdex 1.0.0

package/hooks/post-task.ts

@@ -0,0 +1,309 @@
+// hooks/post-task.ts
+import {
+  wikiExists,
+  createEntry,
+  generateStubContent,
+  WikiEntry,
+  CONFIDENCE,
+  PostTaskOutput
+} from '../src/index.js';
+
+interface TaskContext {
+  projectRoot: string;
+  taskDescription: string;
+  outcome: 'success' | 'failure';
+  errorEncountered?: string;
+  errorResolved?: boolean;
+  filesModified?: string[];
+  userConfirmation?: string;
+  codeChanges?: string; // For detecting workarounds
+  actionHistory?: string[];  // For repeated_pattern detection
+}
+
+// Default enabled signals (can be overridden by future config)
+const DEFAULT_SIGNALS = [
+  'error_resolved',
+  'user_confirmation',
+  'explicit_save',
+  'repeated_pattern',
+  'workaround_applied'
+];
+
+export async function onPostTask(context: TaskContext): Promise<PostTaskOutput | null> {
+  try {
+    const { projectRoot } = context;
+
+    if (!wikiExists(projectRoot)) {
+      return null;
+    }
+
+    // Check signals
+    const signal = detectSignal(context, DEFAULT_SIGNALS);
+
+    if (!signal) {
+      return null;
+    }
+
+    // Extract entry details
+    const entryDetails = extractEntryDetails(context, signal);
+
+    // Check for duplicates before creating (but don't block on it)
+    let isDuplicate = false;
+    try {
+      const { checkDuplicate } = await import('../src/index.js');
+      const dupCheck = await checkDuplicate(
+        projectRoot,
+        entryDetails.title,
+        entryDetails.tags,
+        entryDetails.category
+      );
+      isDuplicate = dupCheck.isDuplicate;
+
+      if (isDuplicate) {
+        console.log(`📚 Solvdex: Skipping duplicate "${entryDetails.title}"`);
+        console.log(`   Similar to: "${dupCheck.matchedEntry?.frontmatter.title}"`);
+        return null;
+      }
+    } catch {
+      // Duplicate check failure is non-critical, proceed with creation
+    }
+
+    // Create entry
+    const entry = createEntry(projectRoot, {
+      category: entryDetails.category,
+      title: entryDetails.title,
+      tags: entryDetails.tags,
+      content: entryDetails.content,
+      trigger: entryDetails.trigger,
+      autoCapture: true,
+      stub: true,
+      source: `auto-capture:${signal}`
+    });
+
+    // Output for Claude Code Stop hook integration (user-facing console logs)
+    console.log(`📚 Solvdex: Captured "${entry.frontmatter.title}"`);
+    console.log(`   Category: ${entry.category}`);
+    console.log(`   Signal: ${signal}`);
+
+    // Structured output for Claude Code (includes both old and new format for backward compatibility)
+    const output: PostTaskOutput = {
+      // Old format (for backward compatibility)
+      type: 'wiki_captured',
+      message: `Wiki: Saved "${entry.frontmatter.title}" to ${entry.category}/`,
+      entry,
+      signal,
+      // New format (Claude Code integration)
+      continue: true,
+      hookSpecificOutput: {
+        type: 'entry_captured',
+        message: `Captured "${entry.frontmatter.title}" to ${entry.category}/`,
+        entryPath: entry.path
+      },
+      additionalContext: formatEntryForContext(entry, signal)
+    };
+
+    // Output JSON marker + JSON (MUST be last output)
+    console.log('\n__HOOK_OUTPUT__');
+    console.log(JSON.stringify(output));
+
+    return output;
+  } catch (error) {
+    // Graceful degradation - log error but don't crash
+    console.error(`[Solvdex] Error in post-task hook: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    return null;
+  }
+}
+
+/**
+ * Detects if similar actions have been performed 3+ times.
+ * Returns the repeated action if found.
+ */
+function detectRepeatedPattern(actionHistory: string[]): string | null {
+  if (!actionHistory || actionHistory.length < 3) {
+    return null;
+  }
+
+  // Count occurrences of each action
+  const counts: Record<string, number> = {};
+  for (const action of actionHistory) {
+    const normalized = action.toLowerCase().trim();
+    counts[normalized] = (counts[normalized] || 0) + 1;
+  }
+
+  // Find action repeated 3+ times
+  for (const [action, count] of Object.entries(counts)) {
+    if (count >= 3) {
+      return action;
+    }
+  }
+
+  return null;
+}
+
+function detectSignal(context: TaskContext, enabledSignals: string[]): string | null {
+  // Signal 1: Error resolved
+  if (
+    enabledSignals.includes('error_resolved') &&
+    context.errorEncountered &&
+    context.errorResolved &&
+    context.outcome === 'success'
+  ) {
+    return 'error_resolved';
+  }
+
+  // Signal 2: User confirmation
+  if (
+    enabledSignals.includes('user_confirmation') &&
+    context.userConfirmation &&
+    isPositiveConfirmation(context.userConfirmation)
+  ) {
+    return 'user_confirmation';
+  }
+
+  // Signal 3: Explicit save request
+  if (
+    enabledSignals.includes('explicit_save') &&
+    context.userConfirmation &&
+    isExplicitSaveRequest(context.userConfirmation)
+  ) {
+    return 'explicit_save';
+  }
+
+  // Signal 4: Repeated pattern
+  if (enabledSignals.includes('repeated_pattern') && context.actionHistory) {
+    const repeatedAction = detectRepeatedPattern(context.actionHistory);
+    if (repeatedAction) {
+      return 'repeated_pattern';
+    }
+  }
+
+  // Signal 5: Workaround applied (detect HACK/WORKAROUND comments)
+  if (
+    enabledSignals.includes('workaround_applied') &&
+    context.codeChanges &&
+    hasWorkaroundMarkers(context.codeChanges)
+  ) {
+    return 'workaround_applied';
+  }
+
+  return null;
+}
+
+function isPositiveConfirmation(text: string): boolean {
+  const positivePatterns = [
+    'that fixed it',
+    'works now',
+    'perfect',
+    'that worked',
+    'thank you',
+    'great',
+    'awesome',
+    'solved'
+  ];
+
+  const textLower = text.toLowerCase();
+  return positivePatterns.some(p => textLower.includes(p));
+}
+
+function isExplicitSaveRequest(text: string): boolean {
+  const savePatterns = [
+    'save this to wiki',
+    'remember this',
+    'add to wiki',
+    'wiki this',
+    'document this'
+  ];
+
+  const textLower = text.toLowerCase();
+  return savePatterns.some(p => textLower.includes(p));
+}
+
+function hasWorkaroundMarkers(codeChanges: string): boolean {
+  const workaroundPatterns = [
+    /\/\/\s*(HACK|WORKAROUND|TODO|FIXME):/i,
+    /\/\*\s*(HACK|WORKAROUND|TODO|FIXME):/i,
+    /#\s*(HACK|WORKAROUND|TODO|FIXME):/i
+  ];
+
+  return workaroundPatterns.some(pattern => pattern.test(codeChanges));
+}
+
+function extractEntryDetails(context: TaskContext, signal: string) {
+  // Determine category based on signal and task keywords (7 categories)
+  let category = 'issues'; // default
+
+  if (signal === 'error_resolved') {
+    category = 'issues';
+  } else if (signal === 'workaround_applied') {
+    category = 'gotchas';
+  } else if (signal === 'repeated_pattern') {
+    category = 'patterns';
+  } else if (context.taskDescription) {
+    const task = context.taskDescription.toLowerCase();
+
+    // Testing signals
+    if (task.includes('test') || task.includes('mock') || task.includes('fixture')) {
+      category = 'testing';
+    }
+    // Documentation signals
+    else if (task.includes('document') || task.includes('readme') || task.includes('guide')) {
+      category = 'docs';
+    }
+    // Security signals
+    else if (task.includes('auth') || task.includes('security') || task.includes('permission')) {
+      category = 'security';
+    }
+    // Performance signals
+    else if (task.includes('slow') || task.includes('optimize') || task.includes('performance')) {
+      category = 'performance';
+    }
+    // Pattern signals
+    else if (task.includes('pattern') || task.includes('reusable')) {
+      category = 'patterns';
+    }
+    // Gotcha signals
+    else if (task.includes('careful') || task.includes('avoid') || task.includes('pitfall')) {
+      category = 'gotchas';
+    }
+  }
+
+  // Generate title from task or error
+  const title = context.errorEncountered
+    ? `Fix: ${context.errorEncountered.substring(0, 50)}`
+    : context.taskDescription?.substring(0, 50) || 'Auto-captured entry';
+
+  // Extract tags from context
+  const tags: string[] = [];
+  if (context.filesModified) {
+    // Add file extension tags
+    const extensions = new Set(
+      context.filesModified
+        .map(f => f.split('.').pop())
+        .filter(Boolean)
+    );
+    tags.push(...Array.from(extensions) as string[]);
+  }
+  if (signal) {
+    tags.push(`auto:${signal}`);
+  }
+
+  // Generate stub content
+  const stubContent = generateStubContent(category);
+
+  return {
+    category,
+    title: title.replace(/[^\w\s-]/g, '').trim(),
+    tags,
+    content: stubContent,
+    trigger: context.errorEncountered
+  };
+}
+
+/**
+ * Formats a captured entry into a readable context string for Claude Code.
+ */
+function formatEntryForContext(entry: WikiEntry, signal: string): string {
+  return `## Captured Entry: ${entry.frontmatter.title}\nCategory: ${entry.category}\nSignal: ${signal}\nPath: ${entry.path}\n\n${entry.content.substring(0, 300)}...`;
+}
+
+export default onPostTask;

package/hooks/prompt-enrich.ts

@@ -0,0 +1,162 @@
+// hooks/prompt-enrich.ts
+import { wikiExists, searchWiki, PromptEnrichOutput, SearchResult } from '../src/index.js';
+
+/**
+ * Hook input from Claude Code's UserPromptSubmit event.
+ */
+interface HookInput {
+  projectRoot: string;
+  prompt: string;
+  filePaths?: string[];
+}
+
+/**
+ * Category keywords for detecting relevant wiki categories from prompt.
+ */
+const CATEGORY_KEYWORDS: Record<string, string[]> = {
+  issues: ['error', 'fix', 'bug', 'broken', 'fails', 'crash', 'exception'],
+  patterns: ['pattern', 'template', 'reusable', 'design', 'approach'],
+  gotchas: ['careful', 'watch out', 'pitfall', 'gotcha', 'trap', 'avoid'],
+  testing: ['test', 'mock', 'fixture', 'assert', 'spec', 'coverage'],
+  docs: ['document', 'readme', 'guide', 'tutorial', 'api docs'],
+  security: ['auth', 'token', 'vulnerability', 'permission', 'csrf', 'xss', 'injection'],
+  performance: ['slow', 'optimize', 'memory', 'latency', 'benchmark', 'profiling']
+};
+
+/**
+ * Path hints for detecting relevant categories from file paths.
+ */
+const PATH_HINTS: Record<string, string[]> = {
+  testing: ['test', 'spec', 'fixture', 'mock', '__tests__'],
+  docs: ['doc', 'readme', 'wiki', 'guide'],
+  security: ['auth', 'secret', 'cred', 'permission'],
+  performance: ['perf', 'bench', 'profile', 'optim']
+};
+
+/**
+ * UserPromptSubmit hook - enriches prompts with relevant wiki context.
+ * Outputs to stdout for Claude Code to include in context.
+ */
+export async function onPromptEnrich(input: HookInput): Promise<PromptEnrichOutput | null> {
+  try {
+    const { projectRoot, prompt, filePaths } = input;
+
+    if (!wikiExists(projectRoot)) {
+      return null;
+    }
+
+    // Detect relevant categories from prompt keywords
+    const relevantCategories = detectRelevantCategories(prompt, filePaths || []);
+
+    // Search wiki for relevant entries
+    const searchResults = await searchWiki(projectRoot, { query: prompt });
+
+    if (searchResults.length === 0 && relevantCategories.length === 0) {
+      return null;
+    }
+
+    // Format entries for output
+    const entries = searchResults.slice(0, 5).map(r => ({
+      title: r.entry.frontmatter.title,
+      category: r.entry.category,
+      path: r.entry.path,
+      confidence: r.entry.frontmatter.confidence
+    }));
+
+    // Record usage for matched entries
+    if (entries.length > 0) {
+      try {
+        const { recordEntryUsage } = await import('../src/index.js');
+        for (const entry of entries) {
+          recordEntryUsage(projectRoot, entry.path);
+        }
+      } catch {
+        // Usage tracking failure is non-critical
+      }
+    }
+
+    // Output for Claude Code hook integration (user-facing console logs)
+    if (entries.length > 0) {
+      console.log(`\u{1F4DA} Solvdex: Found ${entries.length} relevant entries for your task:`);
+      for (const entry of entries.slice(0, 3)) {
+        console.log(`  - ${entry.title} (${entry.category}, confidence: ${entry.confidence})`);
+      }
+      if (entries.length > 3) {
+        console.log(`  ... and ${entries.length - 3} more`);
+      }
+    } else if (relevantCategories.length > 0) {
+      console.log(`\u{1F4DA} Solvdex: Check ${relevantCategories.join(', ')} for related knowledge`);
+    }
+
+    // Structured output for Claude Code (includes both old and new format for backward compatibility)
+    const output: PromptEnrichOutput = {
+      // Old format (for backward compatibility)
+      type: 'wiki_context',
+      message: entries.length > 0
+        ? `Found ${entries.length} relevant wiki entries`
+        : `Relevant categories: ${relevantCategories.join(', ')}`,
+      entries,
+      // New format (Claude Code integration)
+      continue: true,
+      hookSpecificOutput: {
+        type: 'context_added',
+        message: entries.length > 0
+          ? `Found ${entries.length} relevant wiki entries`
+          : `Relevant categories: ${relevantCategories.join(', ')}`,
+        entryCount: entries.length
+      },
+      additionalContext: entries.length > 0
+        ? formatEntriesForContext(searchResults.slice(0, 5))
+        : undefined
+    };
+
+    // Output JSON marker + JSON (MUST be last output)
+    console.log('\n__HOOK_OUTPUT__');
+    console.log(JSON.stringify(output));
+
+    return output;
+  } catch (error) {
+    // Graceful degradation - log error but don't crash
+    console.error(`[Solvdex] Error in prompt-enrich hook: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    return null;
+  }
+}
+
+/**
+ * Detects relevant categories based on prompt keywords and file paths.
+ */
+function detectRelevantCategories(prompt: string, filePaths: string[]): string[] {
+  const detected: Set<string> = new Set();
+  const promptLower = prompt.toLowerCase();
+
+  // Check keywords in prompt
+  for (const [category, keywords] of Object.entries(CATEGORY_KEYWORDS)) {
+    if (keywords.some(kw => promptLower.includes(kw))) {
+      detected.add(category);
+    }
+  }
+
+  // Check path hints
+  for (const filePath of filePaths) {
+    const pathLower = filePath.toLowerCase();
+    for (const [category, hints] of Object.entries(PATH_HINTS)) {
+      if (hints.some(hint => pathLower.includes(hint))) {
+        detected.add(category);
+      }
+    }
+  }
+
+  return Array.from(detected);
+}
+
+/**
+ * Formats search results into a readable context string for Claude Code.
+ */
+function formatEntriesForContext(results: SearchResult[]): string {
+  return results.map(r => {
+    const e = r.entry;
+    return `## ${e.frontmatter.title} (${e.category})\nConfidence: ${e.frontmatter.confidence}\nTags: ${e.frontmatter.tags.join(', ')}\n\n${e.content.substring(0, 300)}...`;
+  }).join('\n\n');
+}
+
+export default onPromptEnrich;

package/hooks/session-start-cli.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// CLI wrapper for session-start hook
+import { wikiExists, searchWiki, DEFAULT_CATEGORIES } from '../src/index.js';
+
+interface SessionStartInput {
+  projectRoot: string;
+  taskDescription?: string;
+  filePaths?: string[];
+}
+
+const CATEGORY_KEYWORDS: Record<string, string[]> = {
+  issues: ['error', 'fix', 'bug', 'broken', 'fails', 'crash', 'exception', 'trouble'],
+  patterns: ['pattern', 'template', 'reusable', 'design', 'approach', 'best practice'],
+  gotchas: ['careful', 'watch out', 'pitfall', 'gotcha', 'trap', 'avoid', 'never'],
+  testing: ['test', 'mock', 'fixture', 'assert', 'spec', 'coverage', 'jest', 'vitest'],
+  docs: ['document', 'readme', 'guide', 'tutorial', 'api docs', 'documentation'],
+  security: ['auth', 'token', 'vulnerability', 'permission', 'csrf', 'xss', 'injection', 'security'],
+  performance: ['slow', 'optimize', 'memory', 'latency', 'benchmark', 'profiling', 'performance']
+};
+
+const CATEGORY_PATH_HINTS: Record<string, string[]> = {
+  testing: ['test', 'spec', 'fixture', 'mock', '__tests__'],
+  docs: ['doc', 'readme', 'wiki', 'guide', 'docs'],
+  security: ['auth', 'secret', 'cred', 'permission', 'security'],
+  performance: ['perf', 'bench', 'profile', 'optim']
+};
+
+function detectCategoryFromPaths(paths: string[]): string[] {
+  const detected: Set<string> = new Set();
+  for (const filePath of paths) {
+    const pathLower = filePath.toLowerCase();
+    for (const [category, hints] of Object.entries(CATEGORY_PATH_HINTS)) {
+      if (hints.some(hint => pathLower.includes(hint))) {
+        detected.add(category);
+      }
+    }
+  }
+  return Array.from(detected);
+}
+
+function isRelevantCategory(task: string, category: string): boolean {
+  const categoryKeywords = CATEGORY_KEYWORDS[category] || [];
+  const taskLower = task.toLowerCase();
+  return categoryKeywords.some(kw => taskLower.includes(kw));
+}
+
+async function main() {
+  try {
+    // Read JSON from stdin
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const inputData: SessionStartInput = JSON.parse(Buffer.concat(chunks).toString());
+
+    const { projectRoot, taskDescription, filePaths } = inputData;
+
+    if (!wikiExists(projectRoot) || !taskDescription) {
+      process.exit(0);
+    }
+
+    // Check which categories might be relevant
+    const relevantCategories: string[] = [];
+    for (const category of DEFAULT_CATEGORIES) {
+      if (isRelevantCategory(taskDescription, category)) {
+        relevantCategories.push(category);
+      }
+    }
+
+    // Also check paths for category hints
+    if (filePaths && filePaths.length > 0) {
+      const pathCategories = detectCategoryFromPaths(filePaths);
+      for (const cat of pathCategories) {
+        if (!relevantCategories.includes(cat)) {
+          relevantCategories.push(cat);
+        }
+      }
+    }
+
+    // Search wiki for relevant entries
+    const searchResults = await searchWiki(projectRoot, { query: taskDescription });
+
+    if (searchResults.length > 0) {
+      console.log(`📚 Solvdex: Found ${searchResults.length} relevant entries`);
+      for (const r of searchResults.slice(0, 3)) {
+        console.log(`  - ${r.entry.frontmatter.title} (${r.entry.category})`);
+      }
+    }
+
+    process.exit(0);
+  } catch (error) {
+    process.exit(0); // Silent fail
+  }
+}
+
+main();