start-vibing 4.4.0 → 4.4.2

package/template/.claude/skills/e2e-audit/DESIGN.md

@@ -1,294 +0,0 @@
-# E2E Audit Infrastructure - Design Specification
-
-## Objective
-
-Build a comprehensive E2E testing system for the Hakutaku Dashboard that:
-
-1. **Discovers every interactive element** on every page (links, buttons, inputs, modals, dropdowns, tabs, tooltips, toasts)
-2. **Auto-generates page specs** documenting all elements found per page
-3. **Produces fixed `.spec.ts` Playwright test files** that run standalone (`bun run test:e2e`) without AI
-4. **Validates UX/UI** — inputs, sanitization, notifications, tooltips, styles, toasts
-5. **Tests security** — XSS, RBAC across 4 roles, console leaks, security headers
-6. **Detects dead code** — unused/unreachable elements via static + dynamic analysis
-7. **Supports agent-driven updates** — agent re-audits and updates test files when app changes
-
-## Scope
-
-- **Desktop only** (1280px+) — no mobile/tablet for now
-- **All pages** — 25 pages across dashboard, auth, and public routes
-- **All roles** — OWNER, ADMIN, MANAGER, MEMBER + unauthenticated
-- **Public** — committed to git, no .gitignore
-
----
-
-## 1. Playwright Infrastructure
-
-### Config
-
-- `playwright.config.ts` at project root
-- Desktop viewport: `1280x720`
-- Base URL: `http://localhost:3000`
-- `fullyParallel: true` for speed
-- `trace: 'on-first-retry'` for CI debugging
-- `screenshot: 'only-on-failure'`
-- Test directory: `tests/e2e/`
-- Output: `test-results/`
-
-### Auth Fixtures
-
-Reusable `storageState` per role:
-
-```
-tests/e2e/
-├── fixtures/
-│   ├── auth.ts          # Auth setup — generates storageState per role
-│   ├── base.ts          # Extended test fixture with page helpers
-│   └── storage/         # Generated auth state files (gitignored)
-│       ├── owner.json
-│       ├── admin.json
-│       ├── manager.json
-│       └── member.json
-├── pages/               # Page Object Models
-├── specs/               # Test spec files
-└── utils/               # Shared test utilities
-```
-
-### Test Tags
-
-| Tag | Purpose |
-|-----|---------|
-| `@smoke` | Critical path — must pass on every PR |
-| `@regression` | Full suite — runs on main merges |
-| `@security` | Security-specific tests |
-| `@a11y` | Accessibility checks |
-| `@ux` | UX/UI validation (toasts, tooltips, styles) |
-
----
-
-## 2. Page Spec Template
-
-Each page gets a structured spec document in `docs/e2e-audit/page-specs/`:
-
-```markdown
-# Page: [Name]
-Route: /dashboard/[route]
-Auth Required: yes/no
-Minimum Role: MEMBER/MANAGER/ADMIN/OWNER
-
-## Interactive Elements
-
-### Navigation
-- [ ] Link: "Home" → /dashboard/home
-- [ ] Link: "Knowledge" → /dashboard/knowledge
-
-### Buttons
-- [ ] Button: "Create New" → opens modal
-- [ ] Button: "Delete" → confirmation dialog
-
-### Inputs
-- [ ] Input: "Search" (text, placeholder: "Search...")
-- [ ] Select: "Filter by" (options: All, Active, Archived)
-
-### Modals/Dialogs
-- [ ] Modal: "Create Item" (trigger: "Create New" button)
-  - Input: "Name" (required)
-  - Input: "Description" (optional)
-  - Button: "Save" → POST + toast
-  - Button: "Cancel" → closes modal
-
-### Toasts/Notifications
-- [ ] Success: "Item created successfully"
-- [ ] Error: "Failed to create item"
-
-### Tooltips
-- [ ] Tooltip: "Info icon" → "This is a tooltip"
-
-### States
-- [ ] Empty state: "No items found"
-- [ ] Loading state: skeleton/spinner
-- [ ] Error state: error message display
-```
-
----
-
-## 3. E2E Audit Skill Architecture
-
-The skill (`/.claude/skills/e2e-audit/SKILL.md`) instructs agents to:
-
-1. **Crawl** — Navigate to each page, capture all interactive elements
-2. **Generate page spec** — Write structured spec to `docs/e2e-audit/page-specs/`
-3. **Generate test file** — Write `.spec.ts` to `tests/e2e/specs/`
-4. **Generate page object** — Write POM to `tests/e2e/pages/`
-5. **Validate** — Run tests via Playwright, fix failures
-6. **Report** — Write results to `docs/e2e-audit/reports/`
-
-### Agent Workflow
-
-```
-DISCOVER → SPEC → IMPLEMENT → VALIDATE → REPORT
-```
-
-- **DISCOVER**: Use Playwright MCP to navigate page, snapshot DOM, list all actionable elements
-- **SPEC**: Write page spec markdown documenting every element found
-- **IMPLEMENT**: Generate POM + test spec from the page spec
-- **VALIDATE**: Run `bunx playwright test <file>` and fix any failures
-- **REPORT**: Record pass/fail counts, coverage gaps, findings
-
----
-
-## 4. Research-Oriented Testing Agent
-
-Each page audit follows a 4-phase approach:
-
-### Phase 1: RESEARCH
-- Check OWASP Top 10 for relevant vulnerabilities
-- Research common issues with the page's tech (e.g., file upload XSS, chat injection)
-- Look up library-specific CVEs and edge cases
-
-### Phase 2: DISCOVER
-- Navigate to page via Playwright MCP
-- Snapshot DOM to enumerate all elements
-- Identify: links, buttons, inputs, selects, modals, dropdowns, tabs, tooltips
-- Capture initial state, loading states, empty states, error states
-
-### Phase 3: GENERATE
-- Write page spec markdown
-- Write Page Object Model class
-- Write test spec with assertions for:
-  - Navigation (all links resolve correctly)
-  - Interactions (buttons, modals, forms work)
-  - Validation (required fields, error messages)
-  - UX (toasts appear, tooltips show, styles correct)
-  - Security (XSS in inputs, RBAC enforcement)
-
-### Phase 4: DOCUMENT
-- Record all findings
-- Flag missing test-ids
-- Flag accessibility issues
-- Flag security concerns
-
----
-
-## 5. Security Testing
-
-### Layer 1: Passive (Every Page)
-- `page.on('console')` — capture and assert no sensitive data leaks
-- Response header checks: `X-Frame-Options`, `X-Content-Type-Options`, `Strict-Transport-Security`
-- No stack traces in error responses
-
-### Layer 2: RBAC Matrix
-- Test each page with all 4 roles + unauthenticated
-- Verify unauthorized access redirects to `/unauthorized` or `/auth`
-- Verify UI elements show/hide based on permissions
-
-### Layer 3: Active (Targeted)
-- XSS payloads in text inputs (`<script>`, `<img onerror>`, `javascript:`)
-- Verify dialog listeners don't fire (no XSS execution)
-- IDOR checks on ID-based routes (`/knowledge/[id]`, `/chat/[id]`)
-- CSRF token presence on mutations
-
----
-
-## 6. Dead Code Detection
-
-### Static Analysis
-- `knip` for unused exports, files, dependencies
-- Run: `bunx knip --reporter json > docs/e2e-audit/reports/dead-code-static.json`
-
-### Dynamic Analysis
-- Playwright coverage API to track which code executes during tests
-- Compare covered vs total to identify unreachable code paths
-- Output: `docs/e2e-audit/reports/dead-code-dynamic.json`
-
----
-
-## 7. Documentation Output
-
-```
-docs/e2e-audit/
-├── DESIGN.md              # This file
-├── page-specs/            # Per-page element inventories
-│   ├── dashboard-home.md
-│   ├── dashboard-knowledge.md
-│   ├── dashboard-chat.md
-│   └── ...
-├── reports/               # Audit results
-│   ├── master-audit.md    # Summary of all findings
-│   ├── security-report.md # Security-specific findings
-│   ├── coverage-gaps.md   # Missing test coverage
-│   └── dead-code.md       # Unused code findings
-└── runbook.md             # How to run, update, and maintain tests
-```
-
----
-
-## 8. All Pages to Audit
-
-### Dashboard (Authenticated)
-| # | Page | Route | Min Role |
-|---|------|-------|----------|
-| 1 | Home | `/dashboard/home` | MEMBER |
-| 2 | Knowledge List | `/dashboard/knowledge` | MEMBER |
-| 3 | Knowledge Detail | `/dashboard/knowledge/[id]` | MEMBER |
-| 4 | Chat | `/dashboard/chat` | MEMBER |
-| 5 | Integrations List | `/dashboard/integrations` | MEMBER |
-| 6 | Integration Detail | `/dashboard/integrations/[id]` | MEMBER |
-| 7 | New Integration | `/dashboard/integrations/new` | MANAGER |
-| 8 | Integration Success | `/dashboard/integrations/success` | MEMBER |
-| 9 | Teams | `/dashboard/teams` | MEMBER |
-| 10 | Profile | `/dashboard/profile` | MEMBER |
-| 11 | Admin | `/dashboard/admin` | ADMIN |
-| 12 | Billing | `/dashboard/billing` | OWNER |
-| 13 | Ontology | `/dashboard/ontology` | MEMBER |
-| 14 | Transcripts List | `/dashboard/transcripts` | MEMBER |
-| 15 | Transcript Detail | `/dashboard/transcripts/[id]` | MEMBER |
-| 16 | Transcript Document | `/dashboard/transcripts/documents/[id]` | MEMBER |
-
-### Auth
-| # | Page | Route |
-|---|------|-------|
-| 17 | Login/Landing | `/` |
-| 18 | Desktop Auth | `/auth/desktop` |
-| 19 | Auth Error | `/auth/error` |
-| 20 | Logout | `/auth/logout` |
-| 21 | OAuth Popup Callback | `/auth/popup-callback` |
-| 22 | Integration Callback Success | `/auth/integration/callback/success` |
-| 23 | Integration Callback Error | `/auth/integration/callback/error` |
-
-### Other
-| # | Page | Route |
-|---|------|-------|
-| 24 | Unauthorized | `/unauthorized` |
-| 25 | Free Trial | `/freetrial` |
-
----
-
-## 9. Running Tests
-
-```bash
-# Run all E2E tests
-bun run test:e2e
-
-# Run specific tag
-bunx playwright test --grep @smoke
-
-# Run specific page
-bunx playwright test tests/e2e/specs/dashboard-home.spec.ts
-
-# Run with UI mode
-bunx playwright test --ui
-
-# Run with trace viewer
-bunx playwright show-trace test-results/trace.zip
-```
-
----
-
-## 10. Maintenance
-
-When the app changes:
-1. Agent re-runs discovery on affected pages
-2. Compares new elements with existing page spec
-3. Updates page spec, POM, and test file
-4. Runs tests to validate
-5. Updates reports with new findings

package/template/.claude/skills/e2e-audit/e2e/fixtures/auth.setup.ts

@@ -1,70 +0,0 @@
-import fs from 'fs'
-import { test as setup } from '@playwright/test'
-import { STORAGE_STATE } from './auth'
-
-/**
- * Auth setup — captures storage state for each role.
- *
- * If a storage state file already contains a session-token cookie,
- * the setup SKIPS that role to avoid overwriting a valid session.
- *
- * To refresh sessions:
- *   1. Delete the storage files in tests/e2e/fixtures/storage/
- *   2. Log in manually at http://localhost:3000
- *   3. Run `bunx playwright test --project=setup`
- */
-
-function hasValidSession(filePath: string): boolean {
-	try {
-		const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'))
-		return data.cookies?.some(
-			(c: { name: string }) => c.name === 'session-token'
-		)
-	} catch {
-		return false
-	}
-}
-
-setup('authenticate as owner', async ({ page }) => {
-	if (hasValidSession(STORAGE_STATE.owner)) {
-		// eslint-disable-next-line no-console
-		console.log('Owner session already valid, skipping setup')
-		return
-	}
-	await page.goto('/dashboard/home')
-	await page.waitForURL(/dashboard/, { timeout: 15000 }).catch(() => {})
-	await page.context().storageState({ path: STORAGE_STATE.owner })
-})
-
-setup('authenticate as admin', async ({ page }) => {
-	if (hasValidSession(STORAGE_STATE.admin)) {
-		// eslint-disable-next-line no-console
-		console.log('Admin session already valid, skipping setup')
-		return
-	}
-	await page.goto('/dashboard/home')
-	await page.waitForURL(/dashboard/, { timeout: 15000 }).catch(() => {})
-	await page.context().storageState({ path: STORAGE_STATE.admin })
-})
-
-setup('authenticate as manager', async ({ page }) => {
-	if (hasValidSession(STORAGE_STATE.manager)) {
-		// eslint-disable-next-line no-console
-		console.log('Manager session already valid, skipping setup')
-		return
-	}
-	await page.goto('/dashboard/home')
-	await page.waitForURL(/dashboard/, { timeout: 15000 }).catch(() => {})
-	await page.context().storageState({ path: STORAGE_STATE.manager })
-})
-
-setup('authenticate as member', async ({ page }) => {
-	if (hasValidSession(STORAGE_STATE.member)) {
-		// eslint-disable-next-line no-console
-		console.log('Member session already valid, skipping setup')
-		return
-	}
-	await page.goto('/dashboard/home')
-	await page.waitForURL(/dashboard/, { timeout: 15000 }).catch(() => {})
-	await page.context().storageState({ path: STORAGE_STATE.member })
-})

package/template/.claude/skills/e2e-audit/e2e/fixtures/auth.ts

@@ -1,21 +0,0 @@
-import path from 'path'
-import { fileURLToPath } from 'url'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-const STORAGE_DIR = path.join(__dirname, 'storage')
-
-/**
- * Auth storage state paths per role.
- *
- * The actual auth setup tests live in auth.setup.ts.
- * This file only exports the storage state paths and role type.
- */
-export const STORAGE_STATE = {
-	owner: path.join(STORAGE_DIR, 'owner.json'),
-	admin: path.join(STORAGE_DIR, 'admin.json'),
-	manager: path.join(STORAGE_DIR, 'manager.json'),
-	member: path.join(STORAGE_DIR, 'member.json'),
-}
-
-export type UserRole = keyof typeof STORAGE_STATE

package/template/.claude/skills/e2e-audit/e2e/fixtures/base.ts

@@ -1,90 +0,0 @@
-import { test as base, expect, type Page } from '@playwright/test'
-import { STORAGE_STATE, type UserRole } from './auth'
-
-type ApiError = {
-	url: string
-	status: number
-	method: string
-	statusText: string
-}
-
-type Fixtures = {
-	authenticatedPage: Page
-	role: UserRole
-	apiErrors: ApiError[]
-}
-
-/**
- * Endpoints that return errors due to missing env vars (e.g., Stripe),
- * not actual application bugs. These are excluded from automatic failure reporting.
- */
-const IGNORED_API_PATTERNS = [
-	/\/api\/billing\//,
-	/ontology\.getGraph/,
-	/ontology\.getEntityTypes/,
-]
-
-/**
- * Extended test fixture with pre-authenticated page and API error tracking.
- *
- * Usage:
- *   import { test, expect } from '../fixtures/base'
- *   test('my test', async ({ authenticatedPage }) => { ... })
- *
- * Default role is 'owner'. Override per-describe:
- *   test.use({ role: 'member' })
- *
- * API errors (4xx, 5xx) are automatically tracked and reported in test failures.
- * Env-dependent endpoints (billing, etc.) are excluded — see IGNORED_API_PATTERNS.
- * Access via `apiErrors` fixture for explicit assertions.
- */
-export const test = base.extend<Fixtures>({
-	role: ['owner', { option: true }],
-
-	authenticatedPage: async ({ browser, role }, use) => {
-		const context = await browser.newContext({
-			storageState: STORAGE_STATE[role],
-			viewport: { width: 1280, height: 720 },
-		})
-		const page = await context.newPage()
-		await use(page)
-		await context.close()
-	},
-
-	apiErrors: async ({ authenticatedPage }, use) => {
-		const errors: ApiError[] = []
-
-		authenticatedPage.on('response', (response) => {
-			const status = response.status()
-			if (status >= 400) {
-				const url = response.url()
-				if (url.includes('/api/') || url.includes('/v1/')) {
-					const path = url.replace(/^https?:\/\/[^/]+/, '')
-					const isIgnored = IGNORED_API_PATTERNS.some((p) => p.test(path))
-					if (!isIgnored) {
-						errors.push({
-							url: path,
-							status,
-							method: response.request().method(),
-							statusText: response.statusText(),
-						})
-					}
-				}
-			}
-		})
-
-		await use(errors)
-
-		if (errors.length > 0) {
-			const report = errors
-				.map((e) => `  ${e.method} ${e.url} → ${e.status} ${e.statusText}`)
-				.join('\n')
-			expect(
-				errors,
-				`API errors detected during test:\n${report}`,
-			).toHaveLength(0)
-		}
-	},
-})
-
-export { expect }

package/template/.claude/skills/e2e-audit/e2e/fixtures/storage/admin.json

@@ -1,50 +0,0 @@
-{
-  "cookies": [
-    {
-      "name": "session-token",
-      "value": "594120f0-6282-43d8-ba54-aeb6f65f9098",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776952153.911341,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "csrf-token",
-      "value": "398b6e02b0b7171f76c0733b02ebf0dbd1c92b52c544d53cfc644b2ef3acbc90%7C2ea44d71177afdfd46dc06f295164ae67743b12c8164a058f786ae3fdf12d330",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776918372.994304,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "NEXT_LOCALE",
-      "value": "pt-BR",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1807043134.189633,
-      "httpOnly": false,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "callback-url",
-      "value": "http%3A%2F%2Flocalhost%3A3000",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776348335.004668,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": [
-    {
-      "origin": "http://localhost:3000",
-      "localStorage": []
-    }
-  ]
-}

package/template/.claude/skills/e2e-audit/e2e/fixtures/storage/manager.json

@@ -1,50 +0,0 @@
-{
-  "cookies": [
-    {
-      "name": "session-token",
-      "value": "594120f0-6282-43d8-ba54-aeb6f65f9098",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776952153.911341,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "csrf-token",
-      "value": "398b6e02b0b7171f76c0733b02ebf0dbd1c92b52c544d53cfc644b2ef3acbc90%7C2ea44d71177afdfd46dc06f295164ae67743b12c8164a058f786ae3fdf12d330",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776918372.994304,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "NEXT_LOCALE",
-      "value": "pt-BR",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1807043134.189633,
-      "httpOnly": false,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "callback-url",
-      "value": "http%3A%2F%2Flocalhost%3A3000",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776348335.004668,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": [
-    {
-      "origin": "http://localhost:3000",
-      "localStorage": []
-    }
-  ]
-}

package/template/.claude/skills/e2e-audit/e2e/fixtures/storage/member.json

@@ -1,50 +0,0 @@
-{
-  "cookies": [
-    {
-      "name": "session-token",
-      "value": "594120f0-6282-43d8-ba54-aeb6f65f9098",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776952153.911341,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "csrf-token",
-      "value": "398b6e02b0b7171f76c0733b02ebf0dbd1c92b52c544d53cfc644b2ef3acbc90%7C2ea44d71177afdfd46dc06f295164ae67743b12c8164a058f786ae3fdf12d330",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776918372.994304,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "NEXT_LOCALE",
-      "value": "pt-BR",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1807043134.189633,
-      "httpOnly": false,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "callback-url",
-      "value": "http%3A%2F%2Flocalhost%3A3000",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776348335.004668,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": [
-    {
-      "origin": "http://localhost:3000",
-      "localStorage": []
-    }
-  ]
-}

package/template/.claude/skills/e2e-audit/e2e/fixtures/storage/owner.json

@@ -1,50 +0,0 @@
-{
-  "cookies": [
-    {
-      "name": "session-token",
-      "value": "594120f0-6282-43d8-ba54-aeb6f65f9098",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776952153.911341,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "csrf-token",
-      "value": "398b6e02b0b7171f76c0733b02ebf0dbd1c92b52c544d53cfc644b2ef3acbc90%7C2ea44d71177afdfd46dc06f295164ae67743b12c8164a058f786ae3fdf12d330",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776918372.994304,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "NEXT_LOCALE",
-      "value": "pt-BR",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1807043134.189633,
-      "httpOnly": false,
-      "secure": false,
-      "sameSite": "Lax"
-    },
-    {
-      "name": "callback-url",
-      "value": "http%3A%2F%2Flocalhost%3A3000",
-      "domain": "localhost",
-      "path": "/",
-      "expires": 1776348335.004668,
-      "httpOnly": true,
-      "secure": false,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": [
-    {
-      "origin": "http://localhost:3000",
-      "localStorage": []
-    }
-  ]
-}