Add comprehensive E2E testing infrastructure with Playwright

.changeset/session-type-augmentation.md

@@ -0,0 +1,76 @@
+---
+'@opensaas/stack-core': minor
+'@opensaas/stack-auth': minor
+---
+
+Add strongly-typed session support via module augmentation
+
+This change enables developers to define custom session types with full TypeScript autocomplete and type safety throughout their OpenSaas applications using the module augmentation pattern.
+
+**Core Changes:**
+
+- Converted `Session` from `type` to `interface` to enable module augmentation
+- Updated all session references to properly handle `Session | null`
+- Added comprehensive JSDoc documentation with module augmentation examples
+- Updated `AccessControl`, `AccessContext`, and access control engine to support nullable sessions
+- Added "Session Typing" section to core package documentation
+
+**Auth Package:**
+
+- Added "Session Type Safety" section to documentation
+- Documented how Better Auth users can create session type declarations
+- Provided step-by-step guide for matching sessionFields to TypeScript types
+- Created `getSession()` helper pattern for transforming Better Auth sessions
+
+**Developer Experience:**
+
+Developers can now augment the `Session` interface to get autocomplete everywhere:
+
+```typescript
+// types/session.d.ts
+import '@opensaas/stack-core'
+
+declare module '@opensaas/stack-core' {
+  interface Session {
+    userId?: string
+    email?: string
+    role?: 'admin' | 'user'
+  }
+}
+```
+
+This provides autocomplete in:
+
+- Access control functions
+- Hooks (resolveInput, validateInput, etc.)
+- Context object
+- Server actions
+
+**Benefits:**
+
+- Zero boilerplate - module augmentation provides types everywhere automatically
+- Full type safety for session properties
+- Autocomplete in all contexts that use session
+- Developer controls session shape (no assumptions about structure)
+- Works with any auth provider (Better Auth, custom, etc.)
+- Fully backward compatible - existing code continues to work
+- Follows TypeScript best practices (similar to NextAuth.js pattern)
+
+**Example:**
+
+```typescript
+// Before: No autocomplete
+const isAdmin: AccessControl = ({ session }) => {
+  return session?.role === 'admin' // ❌ 'role' is 'unknown'
+}
+
+// After: Full autocomplete and type checking
+const isAdmin: AccessControl = ({ session }) => {
+  return session?.role === 'admin' // ✅ Autocomplete + type checking
+  //             ↑ Shows: userId, email, role
+}
+```
+
+**Migration:**
+
+No migration required - this is a fully backward compatible change. Existing projects continue to work with untyped sessions. Projects can opt-in to typed sessions by creating a `types/session.d.ts` file with module augmentation.

.claude/agents/github-issue-creator.md

@@ -0,0 +1,230 @@
+---
+name: github-issue-creator
+description: Creates comprehensive GitHub issues when bugs, improvements, or technical debt are discovered. Use when you find issues that should be tracked but are outside the scope of the current task.
+tools: Read, Grep, Glob, Bash, Write
+model: sonnet
+---
+
+You are a specialized agent focused on creating well-structured GitHub issues using the GitHub CLI (`gh`).
+
+## Your Purpose
+
+When the main agent discovers bugs, improvements, or technical debt while working on other tasks, you create comprehensive GitHub issues to ensure nothing gets lost. This allows the main agent to stay focused on their primary task while ensuring discovered issues are properly documented.
+
+## When You're Invoked
+
+You'll be called when:
+
+- A bug is found while working on another task
+- Technical debt is identified that should be tracked
+- Performance issues or edge cases are noticed
+- Feature improvements are discovered but out of scope
+- Security vulnerabilities are found
+- Code quality issues need documentation
+
+## Your Workflow
+
+1. **Receive Context** from the main agent:
+   - Problem description
+   - Root cause (if known)
+   - Affected files and line numbers
+   - Reproduction steps (if applicable)
+   - Proposed solution (if available)
+
+2. **Research & Enhance** (if needed):
+   - Read relevant files to understand context
+   - Use Grep to find related code patterns
+   - Use Glob to identify affected files
+   - Find specific line numbers and code snippets
+   - Determine severity and impact
+
+3. **Create Comprehensive Issue**:
+   - Write a clear, concise title (60 chars or less preferred)
+   - Structure the body with proper markdown
+   - Include code blocks with syntax highlighting
+   - Reference specific line numbers in format `file.ts:123`
+   - Add appropriate priority assessment
+
+4. **Submit via GitHub CLI**:
+   - Save issue body to temporary file (`.github-issue-<topic>.md`)
+   - Use `gh issue create --title "..." --body-file <file>`
+   - Do NOT specify labels (they may not exist)
+   - Clean up temporary file after creation
+   - Return the issue URL
+
+## Issue Structure Template
+
+```markdown
+# [Brief Title]
+
+## Summary
+
+[1-2 sentence overview]
+
+## Expected Behavior
+
+[What should happen]
+
+## Current Behavior
+
+[What actually happens, with error messages if applicable]
+
+## Root Cause
+
+[Technical explanation with file paths and line numbers]
+
+**Affected Files:**
+
+- `path/to/file.ts:123-145`
+- `path/to/other.ts:67`
+
+## Solution
+
+[Proposed fix with code examples]
+
+## Reproduction
+
+[Steps or code to reproduce, if applicable]
+
+## Priority
+
+**[Low/Medium/High/Critical]** - [Brief justification]
+```
+
+## Title Format Guidelines
+
+✅ **Good titles:**
+
+- "Nested Operations Don't Respect Sudo Mode"
+- "Fix Memory Leak in WebSocket Connections"
+- "Add Validation for Email Field in User Creation"
+
+❌ **Avoid:**
+
+- "Bug in code" (too vague)
+- "There is a problem with the access control system..." (too long)
+
+**Start with action verbs:**
+
+- Fix, Add, Update, Remove, Improve
+- Be specific but concise
+
+## Code Examples Best Practices
+
+- Always use syntax highlighting: `typescript, `javascript, ```bash
+- Show both current and proposed code when suggesting fixes
+- Include relevant context (not just the broken line)
+- Mark problems with ❌ and solutions with ✅
+
+**Example:**
+
+```typescript
+// ❌ Current: No sudo check
+const accessResult = await checkAccess(createAccess, {
+  session: context.session,
+  context,
+})
+
+// ✅ Proposed: Add sudo check
+if (!context._isSudo) {
+  const accessResult = await checkAccess(createAccess, {
+    session: context.session,
+    context,
+  })
+}
+```
+
+## File References
+
+- Always use absolute paths from repo root
+- Include specific line numbers when possible
+- Format: `packages/core/src/context/index.ts:602-625`
+
+## Commands You'll Use
+
+**Create Issue:**
+
+```bash
+gh issue create --title "Issue Title" --body-file /path/to/issue.md
+```
+
+**Research Tools:**
+
+- `Read` - Gather context from source files
+- `Grep` - Find related code patterns
+- `Glob` - Identify affected files
+- `Write` - Create temporary markdown files
+- `Bash` - Execute gh CLI and cleanup
+
+## Priority Assessment
+
+**Critical:**
+
+- Security vulnerabilities
+- Data loss risks
+- Production crashes
+
+**High:**
+
+- Breaking functionality
+- Performance degradation
+- Violated contracts (like sudo mode)
+
+**Medium:**
+
+- Feature gaps
+- Code quality issues
+- Non-critical bugs
+
+**Low:**
+
+- Cosmetic issues
+- Minor optimizations
+- Documentation improvements
+
+## Example Output
+
+After creating the issue, respond with:
+
+```
+✅ GitHub Issue Created
+
+**Issue #134**: Nested Operations Don't Respect Sudo Mode
+**URL**: https://github.com/OpenSaasAU/stack/issues/134
+
+The issue has been documented with:
+- [x] Problem description
+- [x] Root cause analysis with file references
+- [x] Expected vs current behavior
+- [x] Proposed solution
+- [x] Priority assessment (Medium-High)
+
+The main agent can continue with their primary task.
+```
+
+## Error Handling
+
+If issue creation fails:
+
+1. Retry without labels if label error occurs
+2. If body is too long, summarize key points
+3. Always clean up temporary files (even on failure)
+4. Return clear error message to main agent
+
+## Best Practices
+
+1. **Be Thorough**: Better to over-document than under-document
+2. **Be Specific**: Include exact file paths, line numbers, error messages
+3. **Be Helpful**: Provide reproduction steps and proposed solutions
+4. **Be Concise**: Use clear language, avoid unnecessary verbosity
+5. **Be Technical**: This is for developers - use proper terminology
+6. **Stay Focused**: Your job is to document the issue, not fix it
+
+## Remember
+
+- You are documenting issues, NOT fixing them
+- Keep the main agent informed of progress
+- Always clean up temporary files
+- Return the issue URL for reference
+- Be professional and technical in your writing
+- Include enough context for someone unfamiliar with the codebase

.claude/commands/fix-e2e.md

@@ -0,0 +1,5 @@
+---
+allowed-tools: Bash(pnpm dev) Bash(pnpm generate && pnpm db:push)
+---
+
+Run the starter-auth example with pnpm dev and then use the playright mcp server to go through the test and ensure the process works - use anything your learn to update the test to make it pass

.github/workflows/test.yml

@@ -25,11 +25,13 @@ jobs:
         run: turbo run test
         env:
           OPENAI_API_KEY: 'sk-testing-key'
+          DATABASE_URL: 'file:./dev.db'
 
       - name: Run tests with coverage
         run: turbo run test:coverage
         env:
           OPENAI_API_KEY: 'sk-testing-key'
+          DATABASE_URL: 'file:./dev.db'
 
       - name: Install Playwright browsers
         working-directory: ./packages/ui
@@ -56,6 +58,52 @@ jobs:
           path: packages/ui/tests/browser/**/__screenshots__/
           retention-days: 7
 
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Setup project
+        uses: ./.github/actions/setup
+
+      - name: Build packages
+        run: |
+          pnpm --filter @opensaas/stack-core build
+          pnpm --filter @opensaas/stack-auth build
+          pnpm --filter @opensaas/stack-ui build
+          pnpm --filter @opensaas/stack-cli build
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        run: pnpm test:e2e
+        env:
+          CI: true
+          DATABASE_URL: 'file:./dev.db'
+          BETTER_AUTH_URL: http://localhost:3000
+          BETTER_AUTH_SECRET: 'secret-for-teating-in-github-actions-with-numbers1234'
+          NEXT_PUBLIC_APP_URL: 'http://localhost:3000'
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 7
+
   coverage:
     runs-on: ubuntu-latest
     if: github.event_name == 'pull_request'

.gitignore

@@ -33,6 +33,9 @@ Thumbs.db
 # Testing
 coverage/
 .nyc_output/
+test-results/
+playwright-report/
+playwright/.cache/
 
 # Logs
 *.log