wiggum-cli 0.2.2 → 0.2.5

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

@@ -23,6 +23,8 @@ export interface InitOptions {
   ai?: boolean;
   provider?: AIProvider;
   yes?: boolean;
+  /** Use agentic mode for deep codebase exploration */
+  agentic?: boolean;
 }
 
 /**
@@ -175,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(simpson.yellow(`─── 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...');

package/src/generator/templates.ts

@@ -39,7 +39,7 @@ export interface TemplateVariables {
   stylingVersion: string;
   stylingVariant: string;
 
-  // Commands (derived from package manager)
+  // Commands (derived from package manager or AI detected)
   devCommand: string;
   buildCommand: string;
   testCommand: string;
@@ -50,6 +50,16 @@ export interface TemplateVariables {
   // Paths
   appDir: string;
 
+  // AI Analysis (optional - populated when AI enhancement is used)
+  aiEntryPoints: string;
+  aiKeyDirectories: string;
+  aiNamingConventions: string;
+  aiImplementationGuidelines: string;
+  aiMcpEssential: string;
+  aiMcpRecommended: string;
+  aiMissedTechnologies: string;
+  hasAiAnalysis: string;
+
   // Custom variables
   [key: string]: string;
 }
@@ -93,6 +103,115 @@ function deriveCommands(packageManager: string): Pick<
   };
 }
 
+/**
+ * AI analysis template variables
+ */
+type AiTemplateVars = Pick<TemplateVariables,
+  'hasAiAnalysis' | 'aiEntryPoints' | 'aiKeyDirectories' | 'aiNamingConventions' |
+  'aiImplementationGuidelines' | 'aiMcpEssential' | 'aiMcpRecommended' | 'aiMissedTechnologies'
+>;
+
+/**
+ * Format AI analysis data for templates
+ */
+function formatAiAnalysisForTemplates(scanResult: ScanResult): AiTemplateVars {
+  // Check if this is an EnhancedScanResult with aiAnalysis
+  const aiAnalysis = (scanResult as { aiAnalysis?: {
+    projectContext?: {
+      entryPoints?: string[];
+      keyDirectories?: Record<string, string>;
+      namingConventions?: string;
+    };
+    commands?: Record<string, string>;
+    implementationGuidelines?: string[];
+    mcpServers?: {
+      essential?: string[];
+      recommended?: string[];
+    };
+    possibleMissedTechnologies?: string[];
+  } }).aiAnalysis;
+
+  if (!aiAnalysis) {
+    return {
+      hasAiAnalysis: '',
+      aiEntryPoints: '',
+      aiKeyDirectories: '',
+      aiNamingConventions: '',
+      aiImplementationGuidelines: '',
+      aiMcpEssential: '',
+      aiMcpRecommended: '',
+      aiMissedTechnologies: '',
+    };
+  }
+
+  // Format entry points as bullet list
+  const entryPoints = aiAnalysis.projectContext?.entryPoints || [];
+  const aiEntryPoints = entryPoints.length > 0
+    ? entryPoints.map(e => `- \`${e}\``).join('\n')
+    : '';
+
+  // Format key directories as table rows
+  const keyDirs = aiAnalysis.projectContext?.keyDirectories || {};
+  const aiKeyDirectories = Object.keys(keyDirs).length > 0
+    ? Object.entries(keyDirs).map(([dir, purpose]) => `| \`${dir}/\` | ${purpose} |`).join('\n')
+    : '';
+
+  // Naming conventions
+  const aiNamingConventions = aiAnalysis.projectContext?.namingConventions || '';
+
+  // Implementation guidelines as bullet list
+  const guidelines = aiAnalysis.implementationGuidelines || [];
+  const aiImplementationGuidelines = guidelines.length > 0
+    ? guidelines.map(g => `- ${g}`).join('\n')
+    : '';
+
+  // MCP servers
+  const aiMcpEssential = (aiAnalysis.mcpServers?.essential || []).join(', ');
+  const aiMcpRecommended = (aiAnalysis.mcpServers?.recommended || []).join(', ');
+
+  // Missed technologies
+  const aiMissedTechnologies = (aiAnalysis.possibleMissedTechnologies || []).join(', ');
+
+  return {
+    hasAiAnalysis: 'true',
+    aiEntryPoints,
+    aiKeyDirectories,
+    aiNamingConventions,
+    aiImplementationGuidelines,
+    aiMcpEssential,
+    aiMcpRecommended,
+    aiMissedTechnologies,
+  };
+}
+
+/**
+ * Extract AI-detected commands or fall back to derived commands
+ */
+function getCommands(
+  scanResult: ScanResult,
+  packageManager: string
+): Pick<TemplateVariables, 'devCommand' | 'buildCommand' | 'testCommand' | 'lintCommand' | 'typecheckCommand' | 'formatCommand'> {
+  // Check for AI-detected commands
+  const aiCommands = (scanResult as { aiAnalysis?: { commands?: Record<string, string> } }).aiAnalysis?.commands;
+
+  // Derive default commands from package manager
+  const derived = deriveCommands(packageManager);
+
+  if (!aiCommands) {
+    return derived;
+  }
+
+  // Use AI-detected commands where available, fall back to derived
+  return {
+    devCommand: aiCommands.dev || derived.devCommand,
+    buildCommand: aiCommands.build || derived.buildCommand,
+    testCommand: aiCommands.test || derived.testCommand,
+    lintCommand: aiCommands.lint || derived.lintCommand,
+    typecheckCommand: aiCommands.typecheck || derived.typecheckCommand,
+    formatCommand: aiCommands.format || derived.formatCommand,
+  };
+}
+
 /**
  * Extract template variables from scan result
  */
@@ -122,11 +241,24 @@ export function extractVariables(scanResult: ScanResult, customVars: Record<stri
   const stylingVersion = stack.styling?.version || DEFAULT_VARIABLES.stylingVersion!;
   const stylingVariant = stack.styling?.variant || DEFAULT_VARIABLES.stylingVariant!;
 
-  // Derive commands
-  const commands = deriveCommands(packageManager);
-
-  // Determine app directory
-  const appDir = frameworkVariant === 'app-router' || framework.toLowerCase().includes('next') ? 'app' : 'src';
+  // Get commands (AI-detected or derived)
+  const commands = getCommands(scanResult, packageManager);
+
+  // Extract AI analysis data
+  const aiData = formatAiAnalysisForTemplates(scanResult);
+
+  // Determine app directory - use AI entry points if available
+  let appDir = 'src';
+  if (frameworkVariant === 'app-router' || framework.toLowerCase().includes('next')) {
+    appDir = 'app';
+  } else if (aiData.aiEntryPoints) {
+    // Try to extract common directory from entry points
+    const entryPoints = (scanResult as { aiAnalysis?: { projectContext?: { entryPoints?: string[] } } })
+      .aiAnalysis?.projectContext?.entryPoints || [];
+    if (entryPoints.length > 0 && entryPoints[0].startsWith('src/')) {
+      appDir = 'src';
+    }
+  }
 
   return {
     projectName,
@@ -145,6 +277,7 @@ export function extractVariables(scanResult: ScanResult, customVars: Record<stri
     stylingVariant,
     appDir,
     ...commands,
+    ...aiData,
     ...customVars,
   };
 }

package/src/templates/guides/AGENTS.md.tmpl

@@ -3,7 +3,20 @@
 ## Stack
 {{framework}}{{#if frameworkVersion}} {{frameworkVersion}}{{/if}}{{#if frameworkVariant}} ({{frameworkVariant}}){{/if}}, TypeScript, {{styling || css}}{{#if unitTest}}, {{unitTest}}{{/if}}{{#if e2eTest}}, {{e2eTest}}{{/if}}
 
+{{#if aiEntryPoints}}## Entry Points
+{{aiEntryPoints}}
+
+{{/if}}
 ## Commands
+{{#if hasAiAnalysis}}
+| Action | Command |
+|--------|---------|
+| Dev | `{{devCommand}}` |
+| Build | `{{buildCommand}}` |
+| Test | `{{testCommand}}` |
+| Lint | `{{lintCommand}}` |
+| Typecheck | `{{typecheckCommand}}` |
+{{else}}
 All commands run from `{{appDir}}/` directory:
 
 | Action | Command |
@@ -16,19 +29,20 @@ All commands run from `{{appDir}}/` directory:
 | Typecheck | `cd {{appDir}} && {{typecheckCommand}}` |
 {{#if unitTest}}| Test | `cd {{appDir}} && {{testCommand}}` |
 | Test watch | `cd {{appDir}} && {{testCommand}} -- --watch` |{{/if}}
+{{/if}}
 
 ## Validation (run before commit)
 ```bash
-cd {{appDir}} && {{lintCommand}} -- --fix && {{typecheckCommand}}{{#if unitTest}} && {{testCommand}}{{/if}} && {{buildCommand}}
+{{lintCommand}} && {{typecheckCommand}}{{#if unitTest}} && {{testCommand}}{{/if}} && {{buildCommand}}
 ```
 
-## Security Review (run before commit)
-```bash
-cd {{appDir}} && {{packageManager}} audit                    # Check vulnerable dependencies
-```
-Then review changes against @.ralph/guides/SECURITY.md checklist.
-Use `mcp__supabase__get_advisors` with type "security" to check RLS policies.
+{{#if aiKeyDirectories}}## Project Structure
 
+| Directory | Purpose |
+|-----------|---------|
+{{aiKeyDirectories}}
+
+{{else}}
 ## Patterns
 - Pages: `{{appDir}}/app/` - Next.js App Router
 - Components: `{{appDir}}/components/` - see ui/, ai-elements/, survey-editor/
@@ -36,27 +50,30 @@ Use `mcp__supabase__get_advisors` with type "security" to check RLS policies.
 - Store: `{{appDir}}/store/` - State management
 - Server Actions: `{{appDir}}/app/actions.ts` and `{{appDir}}/app/actions/`
 - Libs: `{{appDir}}/lib/` - utilities and integrations
+{{/if}}
+
+{{#if aiImplementationGuidelines}}## Implementation Guidelines
+{{aiImplementationGuidelines}}
 
+{{/if}}
 ## Search Tools
 - **Codebase search**: Use `mgrep "query"` (preferred over Grep/Glob)
 - **Documentation lookup**: Use Context7 MCP for library/framework docs
 - **Web search**: Use `mgrep --web "query"` for general web lookups
 
 ## Code Rules
-- Explicit return types on functions
+{{#if aiNamingConventions}}- Naming: {{aiNamingConventions}}
+{{/if}}- Explicit return types on functions
 - No `any` - use `unknown` if truly unknown
 - Early returns over nested conditionals
 - Named exports, not default exports
 - Path alias `@/` maps to `{{appDir}}/` root
-- Follow patterns in existing components
+- Follow patterns in existing code
 - 2-space indentation, single quotes
-- PascalCase for components, `use` prefix for hooks
-- kebab-case for folder names (e.g., `survey-editor`)
 
 {{#if unitTest}}## Testing
 - Framework: {{unitTest}}{{#if unitTestVersion}} {{unitTestVersion}}{{/if}}
-- Test location: next to component as `*.test.tsx` or in `__tests__/`
-- Run: `cd {{appDir}} && {{testCommand}}`
+- Run: `{{testCommand}}`
 - Each feature task should include tests
 - Validation fails if tests fail
 {{/if}}
@@ -71,30 +88,30 @@ Use `mcp__supabase__get_advisors` with type "security" to check RLS policies.
 - After changes: validate, commit, push
 
 ## MCP Servers Available
-- **Supabase**: Query DB, manage migrations, generate types
+{{#if aiMcpEssential}}- **Essential**: {{aiMcpEssential}}
+{{/if}}{{#if aiMcpRecommended}}- **Recommended**: {{aiMcpRecommended}}
+{{/if}}- **Supabase**: Query DB, manage migrations, generate types
 - **PostHog**: Analytics, feature flags, experiments
 - **Playwright**: Browser automation for E2E testing
   - Navigate: `browser_navigate`, `browser_snapshot`
   - Interact: `browser_click`, `browser_type`, `browser_fill_form`
   - Verify: `browser_wait_for`, `browser_console_messages`
   - Debug: `browser_take_screenshot`
-- **Codex CLI** (shell command, not MCP): PR review
-  - Command: `echo "prompt" | codex exec --full-auto -`
-  - For reviews: `codex review --base main` (interactive mode)
-  - Location: `/opt/homebrew/bin/codex`
-  - Use for: code review, PR feedback before merge
 - **Context7**: Documentation lookup for libraries/frameworks
 
+{{#if aiMissedTechnologies}}## May Also Use
+{{aiMissedTechnologies}}
+
+{{/if}}
 ## Quick Triggers
 | Keywords | Action |
 |----------|--------|
 | type error, ts | Run typecheck |
-| lint, format | Run lint --fix and prettier |
+| lint, format | Run lint --fix |
 | deploy, build | Run full build |
-| error, debug | Check PostHog logs or console |
+| error, debug | Check logs or console |
 | database, table | Use Supabase MCP |
 | e2e, browser test | Use Playwright MCP |
 
 ## Detailed Docs
-- Architecture: `{{appDir}}/.claude/CLAUDE.md` - comprehensive codebase details
 - Frontend: `.ralph/guides/FRONTEND.md` - design patterns, component usage, quality checklist