solvdex 1.0.0

package/hooks/session-start.ts

@@ -0,0 +1,159 @@
+// hooks/session-start.ts
+import {
+  wikiExists,
+  searchWiki,
+  DEFAULT_CATEGORIES,
+  SessionStartOutput,
+  SearchResult,
+  validateSessionStartInput,
+  ValidationError,
+  SessionStartContext
+} from '../src/index.js';
+
+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);
+}
+
+export async function onSessionStart(context: unknown): Promise<SessionStartOutput | null> {
+  try {
+    // Validate input first
+    const validatedContext = validateSessionStartInput(context);
+    const { projectRoot, taskDescription, filePaths } = validatedContext;
+
+    if (!wikiExists(projectRoot)) {
+      return null;
+    }
+
+    if (!taskDescription) {
+      return null;
+    }
+
+    // Check which categories might be relevant based on keywords
+    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 || relevantCategories.length > 0) {
+      const entries = searchResults.map(r => ({
+        title: r.entry.frontmatter.title,
+        category: r.entry.category,
+        path: r.entry.path
+      }));
+
+      const categories = relevantCategories.length > 0
+        ? relevantCategories
+        : [...new Set(searchResults.map(r => r.entry.category))];
+
+      // Output for Claude Code hook integration (user-facing console logs)
+      if (searchResults.length > 0) {
+        console.log(`\u{1F4DA} Solvdex: Found ${searchResults.length} relevant entries`);
+        for (const r of searchResults.slice(0, 3)) {
+          console.log(`  - ${r.entry.frontmatter.title} (${r.entry.category})`);
+        }
+      }
+
+      // Structured output for Claude Code (includes both old and new format for backward compatibility)
+      const output: SessionStartOutput = {
+        // Old format (for backward compatibility)
+        type: 'wiki_context',
+        message: searchResults.length > 0
+          ? `Wiki: Found ${searchResults.length} relevant entries`
+          : `Wiki: Check ${categories.join(', ')} for related knowledge`,
+        categories,
+        entries: entries.length > 0 ? entries : undefined,
+        // New format (Claude Code integration)
+        continue: true,
+        hookSpecificOutput: {
+          type: 'wiki_context',
+          message: searchResults.length > 0
+            ? `Found ${searchResults.length} wiki entries`
+            : `Relevant categories: ${categories.join(', ')}`,
+          categories,
+          entries: entries.length > 0 ? entries.slice(0, 3) : undefined
+        },
+        additionalContext: searchResults.length > 0
+          ? formatEntriesForContext(searchResults.slice(0, 3))
+          : undefined
+      };
+
+      // Output JSON marker + JSON (MUST be last output)
+      console.log('\n__HOOK_OUTPUT__');
+      console.log(JSON.stringify(output));
+
+      return output;
+    }
+
+    return null;
+  } catch (error) {
+    // Handle validation errors separately
+    if (error instanceof ValidationError) {
+      console.error(`[Solvdex] Invalid input: ${error.message}`);
+      return null;
+    }
+    // Graceful degradation - log error but don't crash
+    console.error(`[Solvdex] Error in session-start hook: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    return null;
+  }
+}
+
+function isRelevantCategory(task: string, category: string): boolean {
+  const categoryKeywords = CATEGORY_KEYWORDS[category] || [];
+  const taskLower = task.toLowerCase();
+  return categoryKeywords.some(kw => taskLower.includes(kw));
+}
+
+/**
+ * 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}\n\n${e.content.substring(0, 300)}...`;
+  }).join('\n\n');
+}
+
+export default onSessionStart;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "solvdex",
+  "version": "1.0.0",
+  "description": "Knowledge management system for Claude Code - auto-captures and retrieves project solutions",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/",
+    "skills/",
+    "hooks/",
+    "scripts/",
+    "README.md"
+  ],
+  "keywords": ["claude-code", "wiki", "knowledge-base", "documentation"],
+  "author": "duc.do",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest watch",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "glob": "^10.3.10",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0",
+    "eslint": "^8.55.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.0",
+    "@typescript-eslint/parser": "^6.13.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/error-lookup.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""
+Solvdex PostToolUseFailure hook - looks up solutions for errors
+"""
+import json
+import sys
+import subprocess
+import os
+from pathlib import Path
+
+def main():
+    try:
+        # Read input from stdin
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        print(f"Error parsing input: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Extract context
+    project_root = input_data.get("cwd", os.getcwd())
+    error_message = input_data.get("errorMessage", "")
+    tool_name = input_data.get("toolName", "")
+
+    # Call Node.js hook implementation
+    plugin_root = Path(__file__).parent.parent
+    hook_script = plugin_root / "dist" / "hooks" / "error-lookup.js"
+
+    if not hook_script.exists():
+        # Silent fail if not built yet
+        sys.exit(0)
+
+    try:
+        # Prepare context for TypeScript hook
+        context = {
+            "projectRoot": project_root,
+            "errorMessage": error_message,
+            "toolName": tool_name
+        }
+
+        # Call the compiled TypeScript hook
+        result = subprocess.run(
+            ["node", str(hook_script)],
+            input=json.dumps(context),
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        # Output result to stdout (will be shown to user)
+        if result.stdout:
+            print(result.stdout, end='')
+
+        # Exit with same code
+        sys.exit(result.returncode)
+
+    except subprocess.TimeoutExpired:
+        print("Hook timed out", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error executing hook: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/scripts/post-task.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""
+Solvdex Stop hook - offers to capture knowledge after task completion
+"""
+import json
+import sys
+import subprocess
+import os
+from pathlib import Path
+
+def main():
+    try:
+        # Read input from stdin
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        print(f"Error parsing input: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Extract context
+    project_root = input_data.get("cwd", os.getcwd())
+
+    # Call Node.js hook implementation
+    plugin_root = Path(__file__).parent.parent
+    hook_script = plugin_root / "dist" / "hooks" / "post-task.js"
+
+    if not hook_script.exists():
+        # Silent fail if not built yet
+        sys.exit(0)
+
+    try:
+        # Prepare context for TypeScript hook
+        context = {
+            "projectRoot": project_root
+        }
+
+        # Call the compiled TypeScript hook
+        result = subprocess.run(
+            ["node", str(hook_script)],
+            input=json.dumps(context),
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        # Output result to stdout (will be shown to user)
+        if result.stdout:
+            print(result.stdout, end='')
+
+        # Exit with same code
+        sys.exit(result.returncode)
+
+    except subprocess.TimeoutExpired:
+        print("Hook timed out", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error executing hook: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/scripts/prompt-enrich.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""
+Solvdex UserPromptSubmit hook - enriches prompts with relevant wiki context
+"""
+import json
+import sys
+import subprocess
+import os
+from pathlib import Path
+
+def main():
+    try:
+        # Read input from stdin
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        print(f"Error parsing input: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Extract context
+    project_root = input_data.get("cwd", os.getcwd())
+    prompt = input_data.get("prompt", "")
+    file_paths = input_data.get("filePaths", [])
+
+    # Call Node.js hook implementation
+    plugin_root = Path(__file__).parent.parent
+    hook_script = plugin_root / "dist" / "hooks" / "prompt-enrich.js"
+
+    if not hook_script.exists():
+        # Silent fail if not built yet
+        sys.exit(0)
+
+    try:
+        # Prepare context for TypeScript hook
+        context = {
+            "projectRoot": project_root,
+            "prompt": prompt,
+            "filePaths": file_paths
+        }
+
+        # Call the compiled TypeScript hook
+        result = subprocess.run(
+            ["node", str(hook_script)],
+            input=json.dumps(context),
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        # Output result to stdout (will be shown to user)
+        if result.stdout:
+            print(result.stdout, end='')
+
+        # Exit with same code
+        sys.exit(result.returncode)
+
+    except subprocess.TimeoutExpired:
+        print("Hook timed out", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error executing hook: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/scripts/session-start.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""
+Solvdex SessionStart hook - surfaces relevant wiki entries at session start
+"""
+import json
+import sys
+import subprocess
+import os
+from pathlib import Path
+
+def main():
+    try:
+        # Read input from stdin
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        print(f"Error parsing input: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Extract context
+    project_root = input_data.get("cwd", os.getcwd())
+    task_description = input_data.get("taskDescription", "")
+    file_paths = input_data.get("filePaths", [])
+
+    # Call Node.js hook implementation
+    plugin_root = Path(__file__).parent.parent
+    hook_script = plugin_root / "dist" / "hooks" / "session-start.js"
+
+    if not hook_script.exists():
+        # Silent fail if not built yet
+        sys.exit(0)
+
+    try:
+        # Prepare context for TypeScript hook
+        context = {
+            "projectRoot": project_root,
+            "taskDescription": task_description,
+            "filePaths": file_paths
+        }
+
+        # Call the compiled TypeScript hook
+        result = subprocess.run(
+            ["node", str(hook_script)],
+            input=json.dumps(context),
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        # Output result to stdout (will be shown to user)
+        if result.stdout:
+            print(result.stdout, end='')
+
+        # Exit with same code
+        sys.exit(result.returncode)
+
+    except subprocess.TimeoutExpired:
+        print("Hook timed out", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error executing hook: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/skills/wiki/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: wiki
+description: Project knowledge wiki - stores and retrieves solutions, patterns, and gotchas across 7 development domains. Use when managing project knowledge, searching for solutions, or capturing learnings.
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Solvdex
+
+Project knowledge management with 7 specialized categories for capturing solutions, patterns, and learnings.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/wiki init` | Create `.wiki/` structure |
+| `/wiki add` | Save current solution |
+| `/wiki search <query>` | Full-text search |
+| `/wiki browse` | List entries |
+| `/wiki status` | Show basic stats |
+| `/wiki stats` | Detailed analytics with usage tracking |
+| `/wiki validate` | Check for issues |
+| `/wiki scan` | Generate stubs from project |
+| `/wiki flag <entry>` | Mark needs review |
+| `/wiki fix <entry>` | Update flagged entry |
+| `/wiki export [file]` | Export wiki to JSON |
+| `/wiki import <file>` | Import from export file |
+| `/wiki test-trigger <pattern> <text>` | Test trigger patterns |
+
+## Agents
+
+| Command | Description |
+|---------|-------------|
+| `/wiki explore <query>` | Deep search agent - finds relevant knowledge across all categories |
+| `/wiki capture` | Capture agent - extracts knowledge from conversation and creates entries |
+
+## Quick Start
+
+1. Initialize: `/wiki init`
+2. Scan project: `/wiki scan`
+3. Search: `/wiki search timeout error`
+
+## Categories
+
+| Category | Purpose |
+|----------|---------|
+| `issues/` | Bug fixes, error solutions |
+| `patterns/` | Reusable code patterns |
+| `gotchas/` | Pitfalls, traps |
+| `testing/` | Test strategies, mocks |
+| `docs/` | Documentation templates |
+| `security/` | Auth, vulnerabilities |
+| `performance/` | Optimizations, profiling |
+
+## Confidence (0-100)
+
+- **80+** - Verified, used multiple times
+- **50-79** - Worked once or partially verified
+- **20-49** - Stub or unverified
+
+Run `/wiki status` to see wiki health.

package/skills/wiki-add/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: wiki-add
+description: Add current solution or knowledge to the Solvdex wiki. Analyzes conversation context and creates a structured entry.
+argument-hint: [--category=<cat>]
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Add Solvdex Entry
+
+Capture current solution or knowledge as a wiki entry.
+
+## Process
+
+1. Analyze recent conversation context
+2. Determine category (or use provided)
+3. Extract:
+   - Problem/situation
+   - Solution/decision
+   - Related files
+   - Tags
+4. Generate entry using category template
+5. Save to `.wiki/<category>/`
+6. Show confirmation
+
+## Categories
+
+| Category | Use For |
+|----------|---------|
+| issues | Bug fixes, error solutions |
+| patterns | Reusable code patterns |
+| gotchas | Pitfalls, traps |
+| testing | Test strategies, mocks |
+| docs | Documentation templates |
+| security | Auth, vulnerabilities |
+| performance | Optimizations, profiling |
+
+## Implementation
+
+```typescript
+import { createEntry, wikiExists, getTemplate, CONFIDENCE } from 'solvdex';
+
+const projectRoot = process.cwd();
+
+if (!wikiExists(projectRoot)) {
+  console.log('No wiki found. Run `/wiki init` first.');
+  return;
+}
+
+// Analyze conversation context to extract:
+// - What problem was solved
+// - What solution was applied
+// - What files were involved
+// - Relevant tags
+
+const analysis = analyzeConversationContext();
+
+const category = args.category || analysis.suggestedCategory;
+const template = getTemplate(category);
+
+const entry = createEntry(projectRoot, {
+  category,
+  title: analysis.title,
+  tags: analysis.tags,
+  content: {
+    [template[0].heading]: analysis.problem,
+    [template[1].heading]: analysis.cause || analysis.context,
+    [template[2].heading]: analysis.solution,
+  },
+  trigger: analysis.errorPattern,
+  confidence: CONFIDENCE.MEDIUM, // 50 - needs verification
+  autoCapture: false
+});
+
+console.log(`Wiki: Saved "${entry.frontmatter.title}" to ${category}/`);
+console.log('');
+console.log(`Path: ${entry.path}`);
+console.log(`Tags: ${entry.frontmatter.tags.join(', ')}`);
+console.log(`Confidence: ${entry.frontmatter.confidence}`);
+```
+
+## Output
+
+```
+Wiki: Saved "Drizzle Enum Migration Fix" to issues/
+
+Path: issues/drizzle-enum-migration-fix.md
+Tags: drizzle, database, migration, enum
+Confidence: 50
+```