wiggum-cli 0.1.0

package/dist/templates/guides/PERFORMANCE.md.tmpl

@@ -0,0 +1,264 @@
+# Performance Patterns
+
+{{framework}} performance best practices for implementation phases.
+Reference when writing new components, data fetching, or optimizing existing code.
+
+## Critical: Eliminate Waterfalls
+
+The #1 performance killer. Sequential awaits add full network latency per request.
+
+### Bad: Sequential Fetches
+```typescript
+// 3 round trips = 3x latency
+const user = await getUser(id);
+const posts = await getPosts(user.id);
+const comments = await getComments(posts[0].id);
+```
+
+### Good: Parallel Fetches
+```typescript
+// 1 round trip for independent data
+const [user, posts, settings] = await Promise.all([
+  getUser(id),
+  getPosts(id),
+  getSettings(id),
+]);
+```
+
+### Good: Defer Awaits
+```typescript
+// Start fetch immediately, await when needed
+const dataPromise = fetchData(); // no await
+// ... do other work ...
+const data = await dataPromise; // await at usage
+```
+
+### Good: Suspense Boundaries
+```tsx
+// Show UI before data loads
+<Suspense fallback={<Skeleton />}>
+  <DataComponent /> {/* fetches inside */}
+</Suspense>
+```
+
+## Critical: Bundle Size
+
+Reduces Time to Interactive and Largest Contentful Paint.
+
+### Bad: Barrel Imports
+```typescript
+// Imports entire library, 200-800ms cold start penalty
+import { Button } from '@/components/ui';
+```
+
+### Good: Direct Imports
+```typescript
+// Import only what's needed
+import { Button } from '@/components/ui/button';
+```
+
+### Good: Lazy Load Heavy Components
+```typescript
+// Defer Monaco Editor (~300KB) until needed
+const Editor = dynamic(() => import('@/components/editor'), {
+  loading: () => <Skeleton />,
+  ssr: false,
+});
+```
+
+### Good: Defer Third-Party Scripts
+```typescript
+// Load analytics after hydration
+useEffect(() => {
+  import('posthog-js').then((posthog) => posthog.init(...));
+}, []);
+```
+
+## High: Server-Side Performance
+
+### Use React.cache() for Request Deduplication
+```typescript
+// Same data fetched by multiple components = 1 request
+import { cache } from 'react';
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } });
+});
+```
+
+### Minimize RSC Serialization
+```typescript
+// Bad: Pass entire object
+<ClientComponent user={user} /> // serializes all fields
+
+// Good: Pass only needed fields
+<ClientComponent name={user.name} avatar={user.avatar} />
+```
+
+### Use after() for Non-Blocking Work
+```typescript
+import { after } from 'next/server';
+
+export async function POST(request: Request) {
+  const data = await request.json();
+
+  // Respond immediately
+  after(async () => {
+    // Analytics, logging - doesn't block response
+    await trackEvent('form_submit', data);
+  });
+
+  return Response.json({ success: true });
+}
+```
+
+## Medium: Re-render Optimization
+
+### Defer useSearchParams
+```typescript
+// Bad: Subscribes entire component to URL changes
+function Page() {
+  const searchParams = useSearchParams(); // triggers re-render on any URL change
+  return <Child params={searchParams} />;
+}
+
+// Good: Read in child that needs it
+function Page() {
+  return <Child />; // no subscription here
+}
+function Child() {
+  const searchParams = useSearchParams(); // only this re-renders
+}
+```
+
+### Use Functional setState
+```typescript
+// Bad: Stale closure risk, recreates callback
+const increment = useCallback(() => {
+  setCount(count + 1);
+}, [count]);
+
+// Good: Always fresh, stable callback
+const increment = useCallback(() => {
+  setCount((c) => c + 1);
+}, []);
+```
+
+### Lazy Initialize Expensive State
+```typescript
+// Bad: Runs on every render
+const [data, setData] = useState(expensiveComputation());
+
+// Good: Runs only on mount
+const [data, setData] = useState(() => expensiveComputation());
+```
+
+### Use Transitions for Non-Urgent Updates
+```typescript
+const [isPending, startTransition] = useTransition();
+
+function handleSearch(query: string) {
+  // Urgent: update input immediately
+  setQuery(query);
+
+  // Non-urgent: can be interrupted
+  startTransition(() => {
+    setFilteredResults(filterResults(query));
+  });
+}
+```
+
+## Medium: Rendering Performance
+
+### Hoist Static JSX
+```typescript
+// Bad: Recreated every render
+function Component() {
+  const icon = <Icon size={24} />; // new object each time
+  return <Button icon={icon} />;
+}
+
+// Good: Created once
+const icon = <Icon size={24} />;
+function Component() {
+  return <Button icon={icon} />;
+}
+```
+
+### Use content-visibility for Long Lists
+```css
+.list-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px; /* estimated height */
+}
+```
+Skips layout/paint for off-screen items. 1000-item list renders 10x faster.
+
+### Prevent Hydration Mismatches
+```tsx
+// For theme/locale that differs server vs client
+// Use inline script to set data attribute before React hydrates
+<script>
+  {`document.documentElement.dataset.theme = localStorage.getItem('theme') || 'light'`}
+</script>
+```
+
+## Low-Medium: JavaScript Optimizations
+
+### Build Index Maps for Repeated Lookups
+```typescript
+// Bad: O(n) per lookup
+users.find((u) => u.id === id);
+
+// Good: O(1) per lookup
+const userMap = new Map(users.map((u) => [u.id, u]));
+userMap.get(id);
+```
+
+### Use Set for Membership Checks
+```typescript
+// Bad: O(n) per check
+const isSelected = selectedIds.includes(id);
+
+// Good: O(1) per check
+const selectedSet = new Set(selectedIds);
+const isSelected = selectedSet.has(id);
+```
+
+### Single-Pass for Min/Max
+```typescript
+// Bad: O(n log n)
+const latest = items.sort((a, b) => b.date - a.date)[0];
+
+// Good: O(n)
+const latest = items.reduce((max, item) =>
+  item.date > max.date ? item : max
+);
+```
+
+### Use .toSorted() to Avoid Mutation
+```typescript
+// Bad: Mutates original array (breaks React)
+items.sort((a, b) => a.name.localeCompare(b.name));
+
+// Good: Returns new sorted array
+items.toSorted((a, b) => a.name.localeCompare(b.name));
+```
+
+## Quick Reference
+
+| Issue | Solution |
+|-------|----------|
+| Sequential fetches | `Promise.all()` or defer awaits |
+| Large bundle | Direct imports, `next/dynamic` |
+| Duplicate requests | `React.cache()`, SWR |
+| Unnecessary re-renders | Functional setState, transitions |
+| Slow lists | `content-visibility: auto` |
+| Repeated lookups | Map/Set indexes |
+
+## When to Apply
+
+- **New components**: Check waterfall and bundle patterns
+- **Data fetching**: Use parallel fetches, React.cache()
+- **Performance issues**: Profile first, then apply relevant patterns
+- **Code review**: Flag sequential awaits and barrel imports

package/dist/templates/guides/SECURITY.md.tmpl

@@ -0,0 +1,100 @@
+# Security Review Checklist
+
+Red-team security review for each task. Check before committing.
+
+## Quick Scan (Every Task)
+
+Run through these checks for any code you've written or modified:
+
+### Input Validation
+- [ ] User inputs are validated and sanitized
+- [ ] File uploads check type, size, and content
+- [ ] URL parameters are validated before use
+- [ ] JSON/form data is schema-validated
+
+### Injection Prevention
+- [ ] SQL: Using parameterized queries (Supabase client handles this)
+- [ ] XSS: User content is escaped before rendering
+- [ ] Command injection: No shell commands with user input
+- [ ] Path traversal: File paths are validated, no `../` allowed
+
+### Authentication & Authorization
+- [ ] Protected routes check authentication
+- [ ] API endpoints verify user permissions
+- [ ] Sensitive actions require re-authentication
+- [ ] No secrets in client-side code
+
+### Data Exposure
+- [ ] API responses don't leak sensitive fields
+- [ ] Error messages don't expose internals
+- [ ] Logs don't contain PII or secrets
+- [ ] Database queries filter by user ownership
+
+## Deep Scan (Sensitive Features)
+
+For auth, payments, data export, admin features:
+
+### OWASP Top 10 Check
+| Risk | Check |
+|------|-------|
+| Injection | Parameterized queries, no dynamic code execution |
+| Broken Auth | Session handling, token expiry |
+| Sensitive Data | Encryption at rest/transit |
+| XXE | Disable external entities in XML parsers |
+| Broken Access | Row-level security, ownership checks |
+| Misconfig | No debug mode, secure headers |
+| XSS | Content-Security-Policy, output encoding |
+| Insecure Deserialization | Validate before deserialize |
+| Vulnerable Components | Check {{packageManager}} audit |
+| Logging | Audit trail, no sensitive data logged |
+
+### Supabase-Specific
+- [ ] RLS policies enabled on tables with user data
+- [ ] RLS policies test both SELECT and INSERT/UPDATE/DELETE
+- [ ] Service role key only used server-side
+- [ ] Anon key permissions are minimal
+
+### {{framework}}-Specific
+- [ ] Server actions validate input
+- [ ] API routes check authentication
+- [ ] No sensitive data in client components
+- [ ] Environment variables not exposed to client (no NEXT_PUBLIC_ for secrets)
+
+## Red Team Prompts
+
+Ask yourself:
+1. **Can I bypass auth?** Try accessing protected routes/APIs without login
+2. **Can I access other users' data?** Change IDs in requests
+3. **Can I inject malicious content?** Try `<script>`, SQL fragments, `../`
+4. **Can I cause a DoS?** Large payloads, infinite loops, resource exhaustion
+5. **Can I exfiltrate data?** Check what the API returns, console logs
+
+## Commands
+
+```bash
+# Check for vulnerable dependencies
+cd {{appDir}} && {{packageManager}} audit
+
+# Check for secrets in code (should return nothing)
+cd {{appDir}} && grep -r "sk_live\|password=\|secret=" --include="*.ts" --include="*.tsx" .
+
+# Check RLS policies
+# Use Supabase MCP: mcp__supabase__get_advisors with type: "security"
+```
+
+## When to Flag
+
+Stop and investigate if you find:
+- Direct SQL string concatenation
+- Dynamic code execution with user data
+- Hardcoded credentials or API keys
+- Missing authentication on sensitive endpoints
+- User IDs accepted from client without verification
+- File operations with user-controlled paths
+
+## Fixing Issues
+
+1. **Document** the vulnerability in the implementation plan
+2. **Fix** before committing (don't leave for later)
+3. **Test** the fix (try to exploit it)
+4. **Learn** - add to LEARNINGS.md if it's a new pattern

package/dist/templates/prompts/PROMPT.md.tmpl

@@ -0,0 +1,77 @@
+## Context
+Study @.ralph/AGENTS.md for commands and patterns.
+Study @.ralph/specs/$FEATURE.md for feature specification.
+Study @.ralph/specs/$FEATURE-implementation-plan.md for current tasks.
+{{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
+
+## Learnings
+Read @.ralph/LEARNINGS.md for patterns and anti-patterns from previous iterations.
+Apply relevant learnings to avoid repeating past mistakes.
+
+## Performance
+For data fetching, new components, or optimization tasks, reference @.ralph/guides/PERFORMANCE.md.
+Key patterns: parallel fetches, direct imports, React.cache(), lazy loading.
+
+## Search
+- Use `mgrep "query"` for codebase searches (patterns, implementations, usages)
+- Use Context7 MCP for library/framework documentation
+- Search codebase before assuming something doesn't exist
+
+## Task
+Pick the next incomplete task from the implementation plan.
+**Skip E2E tasks** (tasks starting with `E2E:`) - those are handled in a separate phase.
+Implement it following the patterns in AGENTS.md.
+Write tests for the implementation.
+
+## Validation
+After changes, ALL must pass:
+1. Run: `cd {{appDir}} && {{lintCommand}} -- --fix`
+2. Run: `cd {{appDir}} && {{typecheckCommand}}` (typecheck)
+3. Run: `cd {{appDir}} && {{testCommand}}`
+4. Run: `cd {{appDir}} && {{buildCommand}}`
+
+If any validation fails, fix the issue before proceeding.
+
+## Security Review
+Before committing, review your changes against @.ralph/guides/SECURITY.md:
+1. **Quick scan**: Input validation, injection prevention, auth checks, data exposure
+2. **Run**: `cd {{appDir}} && {{packageManager}} audit` (check for vulnerable dependencies)
+3. **Check**: `mcp__supabase__get_advisors` with type "security" (RLS policies)
+4. **Red team**: Can auth be bypassed? Can other users' data be accessed?
+
+Flag any security issues in the implementation plan and fix before committing.
+
+## Design Quality Check
+Before marking a UI task complete, verify against @.ralph/guides/FRONTEND.md:
+1. Uses design tokens (no hard-coded colors like `#fff` or `rgb()`)
+2. Has hover/focus/active states on interactive elements
+3. Responsive on mobile (test at 375px width)
+4. Empty/loading/error states handled
+5. Charts have titles, tooltips, and legends (if applicable)
+6. Consistent spacing using Tailwind scale
+
+If any check fails, fix before committing.
+
+## Completion
+When ALL validations pass:
+1. Update @.ralph/specs/$FEATURE-implementation-plan.md - mark task done with commit hash
+2. `git -C {{appDir}} add -A`
+3. `git -C {{appDir}} commit -m "type(scope): description"`
+4. `git -C {{appDir}} push origin feat/$FEATURE`
+
+## Learning Capture
+If this iteration revealed something useful, append to @.ralph/LEARNINGS.md:
+- A useful pattern -> Add under "## Patterns (What Works)"
+- A mistake/issue -> Add under "## Anti-Patterns (What to Avoid)"
+- Tool usage tip -> Add under "## Tool Usage"
+- Codebase convention -> Add under "## Codebase Conventions"
+
+Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
+
+## Rules
+- One task per iteration
+- Tests are mandatory - no task is complete without tests
+- Search codebase before assuming something doesn't exist
+- If blocked, document in implementation plan and move to next task
+- Use Supabase MCP for database operations
+- Use PostHog MCP for analytics queries

package/dist/templates/prompts/PROMPT_e2e.md.tmpl

@@ -0,0 +1,234 @@
+## Context
+Study @.ralph/AGENTS.md for commands and patterns.
+Study @.ralph/specs/$FEATURE.md for feature specification.
+Study @.ralph/specs/$FEATURE-implementation-plan.md for E2E test scenarios.
+{{#if frameworkVariant}}For detailed architecture, see @{{appDir}}/.claude/CLAUDE.md{{/if}}
+
+## Learnings
+Read @.ralph/LEARNINGS.md for E2E patterns and anti-patterns.
+Pay special attention to "E2E Pitfalls" section to avoid known issues.
+
+## Prerequisites
+Before E2E testing, verify:
+1. Build passes: `cd {{appDir}} && {{buildCommand}}`
+2. All unit tests pass: `cd {{appDir}} && {{testCommand}}`
+3. Clear cache if issues: `rm -rf {{appDir}}/.next`
+
+If either fails, fix issues before proceeding with E2E tests.
+
+## Task
+Execute automated E2E tests for the completed feature using Playwright MCP tools.
+
+### Step 1: Check Dev Server
+Verify dev server is running at http://localhost:3000. If not accessible, start it:
+```bash
+cd {{appDir}} && {{devCommand}} &
+```
+Wait ~10 seconds for server startup, then verify with a simple browser_navigate.
+
+### Step 1.5: Seed Test Data (if needed)
+
+Check if test scenarios require specific data volumes (e.g., pagination needs >10 rows).
+
+**Seeding with Supabase MCP:**
+```
+mcp__supabase__execute_sql
+query: "INSERT INTO table_name (survey_id, data, created_at)
+        SELECT '{survey_id}', '{"_test": true}'::jsonb, NOW() - (n || ' hours')::interval
+        FROM generate_series(1, 25) n;"
+```
+
+**Mark test data for cleanup:**
+- Add `"_test": true` to JSON data columns
+- Use unique utm_source: `e2e_${FEATURE}_${timestamp}`
+
+**Cleanup after tests:**
+```
+mcp__supabase__execute_sql
+query: "DELETE FROM table_name WHERE data->>'_test' = 'true';"
+```
+
+**If seeding is impractical:** Document in implementation plan that E2E was skipped but unit tests provide coverage.
+
+### Step 2: Parse E2E Test Scenarios
+Read E2E test scenarios from @.ralph/specs/$FEATURE-implementation-plan.md.
+Each scenario is marked with `- [ ] E2E:` prefix and follows this format:
+
+```
+- [ ] E2E: [Scenario name]
+  - **URL:** [starting URL]
+  - **Preconditions:** [setup needed]
+  - **Steps:**
+    1. [Action] -> [expected result]
+  - **Verify:** [final assertion]
+  - **Database check:** [optional SQL]
+```
+
+### Step 3: Execute Each Scenario
+For each E2E test scenario:
+
+1. **Navigate** to starting URL:
+   ```
+   mcp__plugin_playwright_playwright__browser_navigate
+   url: "http://localhost:3000/..."
+   ```
+
+2. **Capture page state** for element references:
+   ```
+   mcp__plugin_playwright_playwright__browser_snapshot
+   ```
+   This returns an accessibility tree with element refs (e.g., `button[3]`, `textbox[0]`).
+
+3. **Execute actions** using refs from snapshot:
+   - Click: `browser_click` with element description and ref
+   - Type: `browser_type` with ref, text, and optionally `submit: true`
+   - Fill form: `browser_fill_form` for multiple fields
+   - Select: `browser_select_option` for dropdowns
+   - Wait: `browser_wait_for` with text to appear/disappear
+
+4. **Verify results**:
+   - Call `browser_snapshot` to get current page state
+   - Check that expected text/elements are present in the snapshot
+   - Use `browser_wait_for` if async operations need time
+
+5. **On failure**:
+   - Take screenshot: `browser_take_screenshot`
+   - Check console: `browser_console_messages` for JS errors
+   - Document failure details
+
+### Step 4: Database Verification
+For scenarios with database checks, use Supabase MCP:
+```
+mcp__plugin_supabase_supabase__execute_sql
+project_id: [project ID]
+query: "SELECT * FROM survey_responses WHERE ..."
+```
+
+Verify returned data matches expected state.
+
+### Unique Test Data (for Parallel Execution)
+When creating test data, use unique identifiers to avoid conflicts with other loops:
+- Add feature-specific UTM params: `?utm_source=e2e_${FEATURE}_${timestamp}`
+- Use unique names/emails: `test_${FEATURE}_${timestamp}@example.com`
+- This ensures database queries find only this test's data
+
+### Step 5: Report Results
+Update @.ralph/specs/$FEATURE-implementation-plan.md for each scenario:
+
+**Passed:**
+```markdown
+- [x] E2E: scenario name - PASSED
+```
+
+**Failed:**
+```markdown
+- [ ] E2E: scenario name - FAILED: [brief reason]
+  - Error: [what went wrong]
+  - Screenshot: [if captured]
+  - Fix needed: [suggested action]
+```
+
+## Playwright MCP Tool Reference
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `browser_navigate` | Go to URL | `url` |
+| `browser_snapshot` | Get page state (use for assertions) | - |
+| `browser_click` | Click element | `element`, `ref` |
+| `browser_type` | Type into element | `element`, `ref`, `text`, `submit` |
+| `browser_fill_form` | Fill multiple fields | `fields[]` with name, type, ref, value |
+| `browser_select_option` | Select dropdown | `element`, `ref`, `values[]` |
+| `browser_wait_for` | Wait for text/time | `text`, `textGone`, `time` |
+| `browser_take_screenshot` | Capture visual state | `filename` (optional) |
+| `browser_console_messages` | Get JS console output | `level` (error/warning/info) |
+| `browser_press_key` | Press keyboard key | `key` (e.g., "Enter", "Tab") |
+| `browser_close` | Close browser/reset state | - |
+
+## Assertion Patterns
+
+### Text Verification
+```
+1. browser_snapshot -> get page content
+2. Check snapshot output for expected text strings
+3. If text not found, scenario fails
+```
+
+### Element State
+```
+1. browser_snapshot -> accessibility tree shows element states
+2. Check for: enabled/disabled, checked/unchecked, visible
+```
+
+### URL Verification
+```
+1. After navigation/action, snapshot shows current URL
+2. Verify URL contains expected path/params
+```
+
+### Database State
+```
+1. mcp__plugin_supabase_supabase__execute_sql with SELECT query
+2. Verify row count, column values match expectations
+```
+
+## Browser State Management
+
+- Use `browser_close` between unrelated scenarios to reset localStorage/cookies
+- Keep browser open for scenarios that test state persistence (e.g., duplicate submission)
+- Fresh browser state = clean localStorage, no prior submissions tracked
+
+## Error Recovery
+
+If a scenario fails:
+1. Document the failure with specific error details
+2. Note what fix is likely needed (code bug vs test spec issue)
+3. Continue with remaining scenarios
+4. At end, summary shows total passed/failed
+
+Failures will trigger a fix iteration in the loop.
+
+## Completion
+
+When all scenarios are executed:
+1. Update implementation plan with results for each scenario
+2. Update the Implementation Summary status to `[PASSED]` if all passed
+3. **Commit the updated implementation plan:**
+   ```bash
+   git -C {{appDir}} add -A && git -C {{appDir}} commit -m "test($FEATURE): E2E tests passed via Playwright"
+   ```
+4. **Push to remote:**
+   ```bash
+   git -C {{appDir}} push origin feat/$FEATURE
+   ```
+5. If all passed: signal ready for PR phase
+6. If any failed: failures documented, loop will retry after fix iteration
+
+## Troubleshooting
+
+### UI Changes Not Visible
+If code changes don't appear in the browser:
+1. Stop the dev server
+2. Clear cache: `rm -rf {{appDir}}/.next`
+3. Restart: `cd {{appDir}} && {{devCommand}}`
+4. Wait for full rebuild before testing
+
+### Stale Data
+- Clear browser storage: Use `browser_close` between scenarios
+- Check Supabase for stale test data from previous runs
+- Delete test data: `DELETE FROM table WHERE data->>'_test' = 'true'`
+
+## Rules
+- Always get a fresh `browser_snapshot` after actions before making assertions
+- Use `browser_wait_for` when waiting for async operations (form submission, API calls)
+- Take screenshots only on failures to avoid clutter
+- Verify database state for data-mutation features
+- Keep scenarios independent when possible
+- Document failures clearly so fix iteration knows what to address
+
+## Learning Capture
+If E2E testing revealed issues worth remembering, append to @.ralph/LEARNINGS.md:
+- Flaky test patterns -> Add under "## Anti-Patterns" > "E2E Pitfalls"
+- Useful Playwright techniques -> Add under "## Tool Usage"
+- Timing issues or race conditions -> Add under "## Anti-Patterns"
+
+Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`