wiggum-cli 0.1.0

package/src/scanner/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Scanner Types
+ * Type definitions for the project scanner system
+ */
+
+/**
+ * Result of detecting a single technology/tool
+ */
+export interface DetectionResult {
+  /** Name of the detected technology (e.g., "Next.js", "pnpm") */
+  name: string;
+  /** Version if detectable from package.json */
+  version?: string;
+  /** Variant or additional context (e.g., "app-router" for Next.js) */
+  variant?: string;
+  /** Confidence score from 0-100 */
+  confidence: number;
+  /** Evidence that led to this detection (files found, deps matched) */
+  evidence: string[];
+}
+
+/**
+ * MCP detection result
+ */
+export interface MCPStack {
+  /** Detected MCP servers from config */
+  detected?: DetectionResult[];
+  /** Recommended MCP servers based on stack */
+  recommended?: string[];
+  /** Is this an MCP server project */
+  isProject?: boolean;
+  /** MCP project detection result (if it's an MCP server project) */
+  projectInfo?: DetectionResult;
+}
+
+/**
+ * Complete detected tech stack for a project
+ */
+export interface DetectedStack {
+  // ============ Core ============
+  /** Web framework (Next.js, React, Vue, etc.) */
+  framework?: DetectionResult;
+  /** Package manager (pnpm, yarn, npm, bun) */
+  packageManager?: DetectionResult;
+  /** Testing frameworks */
+  testing?: {
+    unit?: DetectionResult;
+    e2e?: DetectionResult;
+  };
+  /** Styling approach (Tailwind, CSS Modules, etc.) */
+  styling?: DetectionResult;
+
+  // ============ Data Layer ============
+  /** Database (Supabase, Firebase, MongoDB, PostgreSQL) */
+  database?: DetectionResult;
+  /** ORM (Prisma, Drizzle) */
+  orm?: DetectionResult;
+  /** API patterns (tRPC, GraphQL, TanStack Query, REST) - can have multiple */
+  api?: DetectionResult[];
+
+  // ============ Frontend ============
+  /** State management (Redux, Zustand, Jotai, Pinia, etc.) */
+  stateManagement?: DetectionResult;
+  /** UI component libraries (shadcn, Radix, MUI, etc.) - can have multiple */
+  uiComponents?: DetectionResult[];
+  /** Form handling and validation (React Hook Form, Zod, etc.) - can have multiple */
+  formHandling?: DetectionResult[];
+
+  // ============ Services ============
+  /** Auth provider (NextAuth, Clerk, Auth0, Supabase Auth) */
+  auth?: DetectionResult;
+  /** Analytics (PostHog, Mixpanel, Vercel Analytics, etc.) - can have multiple */
+  analytics?: DetectionResult[];
+  /** Payment provider (Stripe, Lemon Squeezy, Paddle) */
+  payments?: DetectionResult;
+  /** Email provider (Resend, SendGrid, Nodemailer) */
+  email?: DetectionResult;
+
+  // ============ Infrastructure ============
+  /** Deployment targets (Vercel, Netlify, Railway, Docker) - can have multiple */
+  deployment?: DetectionResult[];
+  /** Monorepo tools (Turborepo, Nx, pnpm workspaces, Lerna) */
+  monorepo?: DetectionResult;
+
+  // ============ MCP ============
+  /** MCP (Model Context Protocol) related detection */
+  mcp?: MCPStack;
+}
+
+/**
+ * Category of detector
+ */
+export type DetectorCategory =
+  // Core
+  | 'framework'
+  | 'packageManager'
+  | 'testing'
+  | 'styling'
+  // Data Layer
+  | 'database'
+  | 'orm'
+  | 'api'
+  // Frontend
+  | 'stateManagement'
+  | 'uiComponents'
+  | 'formHandling'
+  // Services
+  | 'auth'
+  | 'analytics'
+  | 'payments'
+  | 'email'
+  // Infrastructure
+  | 'deployment'
+  | 'monorepo'
+  // MCP
+  | 'mcp';
+
+/**
+ * Interface for a detector function
+ */
+export interface Detector {
+  /** Category this detector belongs to */
+  category: DetectorCategory;
+  /** Human-readable name */
+  name: string;
+  /** Run detection on a project directory */
+  detect: (projectRoot: string) => Promise<DetectionResult | DetectionResult[] | null>;
+}
+
+/**
+ * Options for the scanner
+ */
+export interface ScannerOptions {
+  /** Whether to include low-confidence results */
+  includeLowConfidence?: boolean;
+  /** Minimum confidence threshold (0-100) */
+  minConfidence?: number;
+}
+
+/**
+ * Result of a full project scan
+ */
+export interface ScanResult {
+  /** Path that was scanned */
+  projectRoot: string;
+  /** Detected tech stack */
+  stack: DetectedStack;
+  /** Time taken to scan in milliseconds */
+  scanTime: number;
+  /** Any errors encountered during scanning */
+  errors?: string[];
+}

package/src/templates/config/ralph.config.js.tmpl

@@ -0,0 +1,38 @@
+module.exports = {
+  name: '{{projectName}}',
+  stack: {
+    framework: {
+      name: '{{framework}}',
+      version: '{{frameworkVersion}}',
+      variant: '{{frameworkVariant}}',
+    },
+    packageManager: '{{packageManager}}',
+    testing: {
+      unit: '{{unitTest}}',
+      e2e: '{{e2eTest}}',
+    },
+    styling: '{{styling}}',
+  },
+  commands: {
+    dev: '{{devCommand}}',
+    build: '{{buildCommand}}',
+    test: '{{testCommand}}',
+    lint: '{{lintCommand}}',
+    typecheck: '{{typecheckCommand}}',
+  },
+  paths: {
+    root: '.ralph',
+    prompts: '.ralph/prompts',
+    guides: '.ralph/guides',
+    specs: '.ralph/specs',
+    scripts: '.ralph/scripts',
+    learnings: '.ralph/LEARNINGS.md',
+    agents: '.ralph/AGENTS.md',
+  },
+  loop: {
+    maxIterations: 10,
+    maxE2eAttempts: 5,
+    defaultModel: 'sonnet',
+    planningModel: 'opus',
+  },
+};

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

@@ -0,0 +1,100 @@
+# AGENTS.md
+
+## Stack
+{{framework}}{{#if frameworkVersion}} {{frameworkVersion}}{{/if}}{{#if frameworkVariant}} ({{frameworkVariant}}){{/if}}, TypeScript, {{styling || css}}{{#if unitTest}}, {{unitTest}}{{/if}}{{#if e2eTest}}, {{e2eTest}}{{/if}}
+
+## Commands
+All commands run from `{{appDir}}/` directory:
+
+| Action | Command |
+|--------|---------|
+| Dev | `cd {{appDir}} && {{devCommand}}` |
+| Build | `cd {{appDir}} && {{buildCommand}}` |
+| Lint | `cd {{appDir}} && {{lintCommand}}` |
+| Lint fix | `cd {{appDir}} && {{lintCommand}} -- --fix` |
+| Format | `cd {{appDir}} && {{formatCommand}}` |
+| Typecheck | `cd {{appDir}} && {{typecheckCommand}}` |
+{{#if unitTest}}| Test | `cd {{appDir}} && {{testCommand}}` |
+| Test watch | `cd {{appDir}} && {{testCommand}} -- --watch` |{{/if}}
+
+## Validation (run before commit)
+```bash
+cd {{appDir}} && {{lintCommand}} -- --fix && {{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.
+
+## Patterns
+- Pages: `{{appDir}}/app/` - Next.js App Router
+- Components: `{{appDir}}/components/` - see ui/, ai-elements/, survey-editor/
+- API: `{{appDir}}/app/api/` - streaming endpoints with tool calling
+- Store: `{{appDir}}/store/` - State management
+- Server Actions: `{{appDir}}/app/actions.ts` and `{{appDir}}/app/actions/`
+- Libs: `{{appDir}}/lib/` - utilities and integrations
+
+## 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
+- 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
+- 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}}`
+- Each feature task should include tests
+- Validation fails if tests fail
+{{/if}}
+
+## Secrets
+- Use `.env.local` for secrets, never commit API keys
+- Use `process.env.*` for all secrets
+
+## Git
+- Commits: `type(scope): description` (conventional commits)
+- Types: feat, fix, docs, refactor, test, chore
+- After changes: validate, commit, push
+
+## MCP Servers Available
+- **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
+
+## Quick Triggers
+| Keywords | Action |
+|----------|--------|
+| type error, ts | Run typecheck |
+| lint, format | Run lint --fix and prettier |
+| deploy, build | Run full build |
+| error, debug | Check PostHog 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