wiggum-cli 0.2.1 → 0.2.3

package/src/ai/prompts.ts

@@ -4,6 +4,7 @@
  */
 
 import type { ScanResult, DetectedStack } from '../scanner/types.js';
+import { RIPGREP_SKILL } from './tools.js';
 
 /**
  * Format the detected stack for inclusion in prompts
@@ -87,20 +88,52 @@ export function formatStackForPrompt(stack: DetectedStack): string {
 }
 
 /**
- * System prompt for codebase analysis
+ * System prompt for codebase analysis (agentic mode)
  */
-export const SYSTEM_PROMPT = `You are an expert software architect analyzing a codebase to provide insights for AI-assisted development.
+export const SYSTEM_PROMPT_AGENTIC = `You are an expert codebase analyst with tools to explore the project.
 
-Your role is to:
-1. Analyze the detected tech stack and provide deeper insights
-2. Identify architectural patterns and coding conventions
-3. Suggest improvements to the detection results
-4. Recommend MCP servers that would benefit this project
-5. Generate custom prompt suggestions for AI coding assistants
+Your goal is to thoroughly understand the codebase structure and produce actionable configuration for AI-assisted development.
 
-Be concise and actionable. Focus on practical insights that help developers work more effectively with AI tools.
+## Exploration Strategy
+1. First, list the root directory to understand project structure
+2. Read package.json to understand scripts and dependencies
+3. Search for key patterns: entry points, routes, components, tests
+4. Identify naming conventions by examining existing files
+5. Look for existing documentation (.md files, README)
 
-Respond in valid JSON format only.`;
+## Tools Available
+You have these tools to explore the codebase:
+- searchCode: Search using ripgrep patterns
+- readFile: Read file contents
+- listDirectory: List directory structure
+- getPackageInfo: Get package.json info
+
+${RIPGREP_SKILL}
+
+## Output Requirements
+After exploration, output valid JSON with:
+- projectContext: entry points, key directories, naming conventions
+- commands: test, lint, build, dev commands from package.json
+- implementationGuidelines: short actionable rules (5-10 words each, max 7)
+- mcpServers: essential and recommended servers
+- possibleMissedTechnologies: technologies that might be in use
+
+Be concise. Focus on WHAT TO DO, not what exists.`;
+
+/**
+ * System prompt for codebase analysis (simple mode - no tools)
+ */
+export const SYSTEM_PROMPT = `You are analyzing a codebase to help configure AI-assisted development tools.
+
+Your goal is to produce SHORT, ACTIONABLE output that helps AI coding assistants work effectively on this codebase.
+
+Rules:
+- Output valid JSON only
+- Be extremely concise (5-10 words per item max)
+- Focus on WHAT TO DO, not what exists
+- Include specific file paths and commands
+- Max 5-7 items per array
+- No explanations, just actionable rules`;
 
 /**
  * Create the codebase analysis prompt
@@ -108,49 +141,48 @@ Respond in valid JSON format only.`;
 export function createAnalysisPrompt(scanResult: ScanResult): string {
   const stackInfo = formatStackForPrompt(scanResult.stack);
 
-  return `Analyze this codebase and provide enhanced insights.
+  return `Analyze this codebase for AI-assisted development configuration.
 
-Project Root: ${scanResult.projectRoot}
+Project: ${scanResult.projectRoot}
 
 Detected Stack:
 ${stackInfo || 'No technologies detected'}
 
-Based on this stack, provide analysis in the following JSON format:
+Respond with this JSON structure (keep values SHORT - 5-10 words max per item):
 {
-  "frameworkInsights": {
-    "variant": "more specific variant if detectable (e.g., 'app-router', 'pages-router', 'spa', 'ssr')",
-    "confidence": "high/medium/low",
-    "notes": "any additional observations about framework usage"
+  "projectContext": {
+    "entryPoints": ["src/index.ts", "src/server.ts"],
+    "keyDirectories": {
+      "src/routes": "API route handlers",
+      "src/models": "Database models"
+    },
+    "namingConventions": "camelCase files, PascalCase components"
   },
-  "architecturalPatterns": [
-    {
-      "pattern": "pattern name",
-      "confidence": "high/medium/low",
-      "evidence": "why you think this pattern is used"
-    }
-  ],
-  "codingConventions": [
-    {
-      "convention": "convention name",
-      "suggestion": "how to follow this convention"
-    }
-  ],
-  "recommendedMcpServers": [
-    {
-      "name": "server name",
-      "reason": "why this would be useful"
-    }
-  ],
-  "customPromptSuggestions": [
-    "Specific prompt suggestions tailored to this codebase"
+  "commands": {
+    "test": "npm test",
+    "lint": "npm run lint",
+    "typecheck": "npm run typecheck",
+    "build": "npm run build",
+    "dev": "npm run dev"
+  },
+  "implementationGuidelines": [
+    "Run npm test after every change",
+    "Use Zod for request validation",
+    "Place routes in src/routes/<resource>.ts",
+    "Follow error pattern in src/utils/errors.ts"
   ],
-  "additionalDetections": {
-    "possibleMissed": ["technologies that might be in use but weren't detected"],
-    "refinements": ["suggestions to improve existing detections"]
-  }
+  "mcpServers": {
+    "essential": ["filesystem", "git"],
+    "recommended": ["docker", "postgres"]
+  },
+  "possibleMissedTechnologies": ["Redis", "WebSockets"]
 }
 
-Only include sections where you have meaningful insights. Keep responses focused and actionable.`;
+Important:
+- implementationGuidelines should be short rules (not analysis prompts)
+- Include actual file paths from this project
+- Infer commands from package.json patterns
+- Max 5-7 items per array`;
 }
 
 /**

package/src/ai/tools.ts

@@ -0,0 +1,278 @@
+/**
+ * AI Tools Module
+ * Defines tools the AI agent can use to explore the codebase
+ */
+
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/**
+ * Create tools for codebase exploration
+ */
+export function createExplorationTools(projectRoot: string) {
+  return {
+    /**
+     * Search code using ripgrep patterns
+     */
+    searchCode: tool({
+      description: `Search the codebase using ripgrep. Use this to find:
+- Function/class definitions: pattern="^(def|function|class) NAME", fileType="py"
+- Symbol usage: pattern="\\bSymbolName\\b" (word boundaries critical!)
+- Imports: pattern="^import.*module", fileType="ts"
+- File patterns: pattern="pattern", glob="*.tsx"
+
+Tips:
+- Use fileType for filtering (py, js, ts, rust, go)
+- Use \\b for word boundaries to avoid partial matches
+- Use literal=true for exact strings (faster)
+- Always use word boundaries when searching symbols`,
+      inputSchema: zodSchema(z.object({
+        pattern: z.string().describe('The regex pattern to search for'),
+        fileType: z.string().optional().describe('File type filter (py, js, ts, etc.)'),
+        glob: z.string().optional().describe('Glob pattern like "*.tsx" or "src/**/*.ts"'),
+        literal: z.boolean().optional().describe('Use literal search (faster for exact strings)'),
+        context: z.number().optional().describe('Lines of context (default 0)'),
+        maxResults: z.number().optional().describe('Max results to return (default 50)'),
+      })),
+      execute: async ({ pattern, fileType, glob, literal, context, maxResults }) => {
+        try {
+          const args: string[] = [];
+
+          if (literal) args.push('-F');
+          if (fileType) args.push('-t', fileType);
+          if (glob) args.push('-g', glob);
+          if (context) args.push('-C', String(context));
+
+          args.push('--max-count', String(maxResults || 50));
+          args.push('--no-heading');
+          args.push('--line-number');
+          args.push('--');
+          args.push(pattern);
+          args.push(projectRoot);
+
+          // Use spawnSync instead of execSync for safety (no shell injection)
+          const result = spawnSync('rg', args, {
+            encoding: 'utf-8',
+            maxBuffer: 1024 * 1024,
+            timeout: 30000,
+          });
+
+          if (result.error) {
+            return `Search error: ${result.error.message}`;
+          }
+
+          if (result.status === 1) {
+            return 'No matches found';
+          }
+
+          if (result.status !== 0) {
+            return `Search error: ${result.stderr || 'Unknown error'}`;
+          }
+
+          // Convert absolute paths to relative
+          const lines = result.stdout.split('\n').map(line => {
+            if (line.startsWith(projectRoot)) {
+              return line.replace(projectRoot + '/', '');
+            }
+            return line;
+          });
+
+          return lines.slice(0, 100).join('\n');
+        } catch (error: unknown) {
+          const errMsg = error instanceof Error ? error.message : String(error);
+          return `Search error: ${errMsg}`;
+        }
+      },
+    }),
+
+    /**
+     * Read a file's contents
+     */
+    readFile: tool({
+      description: 'Read the contents of a file. Use relative paths from project root.',
+      inputSchema: zodSchema(z.object({
+        path: z.string().describe('Relative path to the file from project root'),
+        startLine: z.number().optional().describe('Start line (1-indexed)'),
+        endLine: z.number().optional().describe('End line (inclusive)'),
+      })),
+      execute: async ({ path: filePath, startLine, endLine }) => {
+        try {
+          // Prevent path traversal
+          const normalizedPath = filePath.replace(/\.\./g, '');
+          const fullPath = join(projectRoot, normalizedPath);
+
+          if (!fullPath.startsWith(projectRoot)) {
+            return 'Invalid path: cannot access files outside project';
+          }
+
+          if (!existsSync(fullPath)) {
+            return `File not found: ${filePath}`;
+          }
+
+          const stat = statSync(fullPath);
+          if (stat.isDirectory()) {
+            return `Path is a directory, not a file: ${filePath}`;
+          }
+
+          if (stat.size > 100000) {
+            return `File too large (${stat.size} bytes). Use startLine/endLine to read a portion.`;
+          }
+
+          const content = readFileSync(fullPath, 'utf-8');
+          const lines = content.split('\n');
+
+          if (startLine || endLine) {
+            const start = (startLine || 1) - 1;
+            const end = endLine || lines.length;
+            return lines.slice(start, end).join('\n');
+          }
+
+          return content;
+        } catch (error) {
+          const errMsg = error instanceof Error ? error.message : String(error);
+          return `Error reading file: ${errMsg}`;
+        }
+      },
+    }),
+
+    /**
+     * List directory contents
+     */
+    listDirectory: tool({
+      description: 'List contents of a directory. Shows files and subdirectories.',
+      inputSchema: zodSchema(z.object({
+        path: z.string().describe('Relative path to the directory (use "." for project root)'),
+        recursive: z.boolean().optional().describe('List recursively (default false)'),
+        maxDepth: z.number().optional().describe('Max depth for recursive listing (default 2)'),
+      })),
+      execute: async ({ path: dirPath, recursive, maxDepth }) => {
+        try {
+          // Prevent path traversal
+          const normalizedPath = dirPath.replace(/\.\./g, '');
+          const fullPath = join(projectRoot, normalizedPath);
+
+          if (!fullPath.startsWith(projectRoot)) {
+            return 'Invalid path: cannot access directories outside project';
+          }
+
+          if (!existsSync(fullPath)) {
+            return `Directory not found: ${dirPath}`;
+          }
+
+          const stat = statSync(fullPath);
+          if (!stat.isDirectory()) {
+            return `Path is not a directory: ${dirPath}`;
+          }
+
+          const results: string[] = [];
+          const depth = maxDepth || 2;
+
+          function scanDir(dir: string, currentDepth: number): void {
+            if (currentDepth > depth) return;
+
+            const entries = readdirSync(dir, { withFileTypes: true });
+
+            for (const entry of entries) {
+              // Skip common ignored directories
+              if (['node_modules', '.git', 'dist', 'build', '.next', '__pycache__'].includes(entry.name)) {
+                continue;
+              }
+
+              const relativePath = relative(projectRoot, join(dir, entry.name));
+              const prefix = entry.isDirectory() ? '📁 ' : '📄 ';
+              results.push(prefix + relativePath);
+
+              if (recursive && entry.isDirectory() && currentDepth < depth) {
+                scanDir(join(dir, entry.name), currentDepth + 1);
+              }
+            }
+          }
+
+          scanDir(fullPath, 1);
+          return results.slice(0, 200).join('\n');
+        } catch (error) {
+          const errMsg = error instanceof Error ? error.message : String(error);
+          return `Error listing directory: ${errMsg}`;
+        }
+      },
+    }),
+
+    /**
+     * Get package.json info including scripts
+     */
+    getPackageInfo: tool({
+      description: 'Get package.json contents including scripts, dependencies, and metadata.',
+      inputSchema: zodSchema(z.object({
+        field: z.string().optional().describe('Specific field to get (scripts, dependencies, etc.)'),
+      })),
+      execute: async ({ field }) => {
+        try {
+          const pkgPath = join(projectRoot, 'package.json');
+
+          if (!existsSync(pkgPath)) {
+            return 'No package.json found';
+          }
+
+          const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+
+          if (field) {
+            return JSON.stringify(pkg[field], null, 2) || `Field "${field}" not found`;
+          }
+
+          // Return relevant parts
+          return JSON.stringify({
+            name: pkg.name,
+            scripts: pkg.scripts,
+            dependencies: Object.keys(pkg.dependencies || {}),
+            devDependencies: Object.keys(pkg.devDependencies || {}),
+          }, null, 2);
+        } catch (error) {
+          const errMsg = error instanceof Error ? error.message : String(error);
+          return `Error reading package.json: ${errMsg}`;
+        }
+      },
+    }),
+  };
+}
+
+/**
+ * Ripgrep skill reference for the AI agent
+ */
+export const RIPGREP_SKILL = `
+## ripgrep Code Search Skill
+
+### Essential Patterns
+
+**Find definitions:**
+- Python functions: pattern="^def \\w+\\(", fileType="py"
+- JS/TS functions: pattern="^(export )?(function|const) \\w+", fileType="ts"
+- Classes: pattern="^class \\w+", fileType="py"
+
+**Find symbol usage (CRITICAL: use word boundaries):**
+- Exact word: pattern="\\bSymbolName\\b"
+- Literal string: pattern="exact.string", literal=true
+
+**Find imports:**
+- ES imports: pattern="^import.*from", fileType="ts"
+- CommonJS: pattern="require\\(", fileType="js"
+
+**File type options:**
+- py (Python)
+- js (JavaScript)
+- ts (TypeScript)
+- rust (Rust)
+- go (Go)
+
+**Performance tips:**
+1. Always use fileType when possible
+2. Use literal=true for exact strings
+3. Use \\b for word boundaries (prevents partial matches)
+4. Keep maxResults reasonable
+
+**Word boundaries are critical:**
+- WITHOUT: pattern="log" matches "logger", "blogger", "catalog"
+- WITH: pattern="\\blog\\b" matches only "log"
+`;

package/src/commands/init.ts

@@ -17,11 +17,14 @@ import * as prompts from '@clack/prompts';
 import pc from 'picocolors';
 import fs from 'fs';
 import path from 'path';
+import { simpson, sectionHeader, drawLine } from '../utils/colors.js';
 
 export interface InitOptions {
   ai?: boolean;
   provider?: AIProvider;
   yes?: boolean;
+  /** Use agentic mode for deep codebase exploration */
+  agentic?: boolean;
 }
 
 /**
@@ -53,7 +56,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
 
   // Display scan results
   console.log('');
-  console.log(pc.cyan('--- Scan Results ---'));
+  console.log(simpson.yellow('─── Scan Results ───'));
   console.log(formatScanResult(scanResult));
   console.log('');
 
@@ -84,7 +87,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
     // If no API key found, prompt for one
     if (!hasKey) {
       console.log('');
-      console.log(pc.yellow('No API key found for AI enhancement.'));
+      console.log(simpson.pink('No API key found for AI enhancement.'));
       console.log('');
 
       // Ask which provider to use
@@ -174,13 +177,31 @@ export async function initCommand(options: InitOptions): Promise<void> {
       const selectedModel = modelChoice as string;
       const modelLabel = modelOptions.find(m => m.value === selectedModel)?.label || selectedModel;
 
+      // Ask about agentic mode (deep exploration)
+      let useAgentic = options.agentic;
+      if (useAgentic === undefined && !options.yes) {
+        const wantAgentic = await prompts.confirm({
+          message: 'Enable deep codebase exploration? (AI will search files and directories)',
+          initialValue: true,
+        });
+
+        if (prompts.isCancel(wantAgentic)) {
+          logger.info('Initialization cancelled');
+          return;
+        }
+
+        useAgentic = wantAgentic;
+      }
+
       console.log('');
-      console.log(pc.cyan(`--- AI Enhancement (${provider} / ${modelLabel}) ---`));
+      const modeLabel = useAgentic ? 'agentic' : 'simple';
+      console.log(simpson.yellow(`─── AI Enhancement (${provider} / ${modelLabel} / ${modeLabel}) ───`));
 
       const aiEnhancer = new AIEnhancer({
         provider,
         model: selectedModel,
         verbose: true,
+        agentic: useAgentic,
       });
 
       spinner.start('Running AI analysis...');
@@ -236,7 +257,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
     spinner.stop('Configuration files generated');
 
     console.log('');
-    console.log(pc.cyan('--- Generation Results ---'));
+    console.log(simpson.yellow('─── Generation Results ───'));
     console.log(formatGenerationResult(generationResult));
 
     if (generationResult.success) {

package/src/utils/colors.ts

@@ -0,0 +1,95 @@
+/**
+ * Simpson Color Palette
+ * Custom ANSI color utilities for the CLI
+ */
+
+/**
+ * Simpson color palette hex values
+ */
+export const SIMPSON_COLORS = {
+  blue: '#2f64d6',
+  yellow: '#f8db27',
+  brown: '#9c5b01',
+  white: '#ffffff',
+  pink: '#ff81c1',
+} as const;
+
+/**
+ * Convert hex to RGB
+ */
+function hexToRgb(hex: string): { r: number; g: number; b: number } {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  if (!result) {
+    return { r: 255, g: 255, b: 255 };
+  }
+  return {
+    r: parseInt(result[1], 16),
+    g: parseInt(result[2], 16),
+    b: parseInt(result[3], 16),
+  };
+}
+
+/**
+ * Create ANSI escape code for foreground color from hex
+ */
+function fgHex(hex: string): string {
+  const { r, g, b } = hexToRgb(hex);
+  return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+/**
+ * Reset ANSI escape code
+ */
+const reset = '\x1b[0m';
+
+/**
+ * Simpson color functions for terminal output
+ */
+export const simpson = {
+  yellow: (text: string): string => `${fgHex(SIMPSON_COLORS.yellow)}${text}${reset}`,
+  blue: (text: string): string => `${fgHex(SIMPSON_COLORS.blue)}${text}${reset}`,
+  brown: (text: string): string => `${fgHex(SIMPSON_COLORS.brown)}${text}${reset}`,
+  white: (text: string): string => `${fgHex(SIMPSON_COLORS.white)}${text}${reset}`,
+  pink: (text: string): string => `${fgHex(SIMPSON_COLORS.pink)}${text}${reset}`,
+};
+
+/**
+ * Box drawing characters
+ */
+export const box = {
+  topLeft: '┌',
+  topRight: '┐',
+  bottomLeft: '└',
+  bottomRight: '┘',
+  horizontal: '─',
+  vertical: '│',
+};
+
+/**
+ * Draw a horizontal line
+ */
+export function drawLine(width: number = 50): string {
+  return simpson.brown(box.horizontal.repeat(width));
+}
+
+/**
+ * Draw a box around text
+ */
+export function drawBox(text: string, padding: number = 1): string {
+  const paddedText = ' '.repeat(padding) + text + ' '.repeat(padding);
+  const width = paddedText.length;
+
+  const top = simpson.brown(box.topLeft + box.horizontal.repeat(width) + box.topRight);
+  const middle = simpson.brown(box.vertical) + paddedText + simpson.brown(box.vertical);
+  const bottom = simpson.brown(box.bottomLeft + box.horizontal.repeat(width) + box.bottomRight);
+
+  return `${top}\n${middle}\n${bottom}`;
+}
+
+/**
+ * Section header with horizontal lines
+ */
+export function sectionHeader(title: string): string {
+  const line = drawLine(50);
+  return `\n${line}\n${simpson.yellow(title)}\n${line}`;
+}

package/src/utils/header.ts

@@ -1,15 +1,32 @@
 import cfonts from 'cfonts';
+import { simpson, drawBox, SIMPSON_COLORS } from './colors.js';
 
 /**
- * Display the RALPH ASCII header in Simpson yellow
+ * Display the RALPH ASCII header with welcome box
  */
 export function displayHeader(): void {
-  cfonts.say('RALPH', {
+  // Welcome box like Claude Code
+  const welcomeText = simpson.pink('*') + ' Welcome to ' + simpson.yellow('Ralph') + '🍩';
+  console.log('');
+  console.log(drawBox(welcomeText, 2));
+  console.log('');
+
+  // ASCII art logo in Simpson yellow
+  cfonts.say('WIGGUM CLI', {
     font: 'block',
-    colors: ['#FED90F'],
+    colors: [SIMPSON_COLORS.yellow],
     letterSpacing: 1,
     lineHeight: 1,
-    space: true,
+    space: false,
     maxLength: 0,
   });
 }
+
+/**
+ * Display a minimal header (for subcommands)
+ */
+export function displayMinimalHeader(): void {
+  console.log('');
+  console.log(simpson.yellow('Ralph') + simpson.brown(' │ ') + 'AI-powered loop development');
+  console.log('');
+}