@sudobility/testomniac_runner 0.0.128

package/plans/POLLING.md

@@ -0,0 +1,569 @@
+# Plan: Scanner-to-API Migration (Polling Architecture)
+
+## Context
+
+The scanner currently shares a Postgres database directly with the API, causing tight schema coupling. Both projects maintain separate Drizzle schema definitions — any column change requires coordinated updates in both repos. This plan migrates to a clean architecture where the scanner calls the API via HTTP, and the API is the sole DB owner.
+
+**Outcome**: Scanner becomes a stateless HTTP client. API exposes fine-grained REST endpoints. All request/response types are defined in `@sudobility/testomniac_types` so both projects share a single contract. DB code is removed from the scanner entirely.
+
+**Post-modification workflow**: After modifying `testomniac_types`, run `/testomniac_app/scripts/push_all.sh` to publish and propagate changes.
+
+---
+
+## Phase 1: Define Shared Types in `testomniac_types`
+
+Add request/response types for every scanner API endpoint. Both `testomniac_api` and `testomniac_runner` import these types — no inline type definitions in either project.
+
+**File to modify**: `~/projects/testomniac_types/src/index.ts`
+
+### New types to add:
+
+```typescript
+// --- Runs ---
+interface PendingRunResponse {
+  id: number;
+  appId: number;
+  sizeClass: string;
+  status: string;
+}
+
+interface UpdateRunPhaseRequest {
+  phase: string;
+}
+
+interface UpdateRunStatsRequest {
+  pagesFound?: number;
+  pageStatesFound?: number;
+  actionsCompleted?: number;
+}
+
+interface UpdatePhaseDurationRequest {
+  field: string;
+  durationMs: number;
+}
+
+interface CompleteRunRequest {
+  aiSummary?: string;
+  totalDurationMs?: number;
+}
+
+// --- Pages ---
+interface FindOrCreatePageRequest {
+  appId: number;
+  url: string;
+}
+
+interface PageResponse {
+  id: number;
+  appId: number;
+  url: string;
+  routeKey: string | null;
+  requiresLogin: boolean | null;
+  createdAt: string | null;
+}
+
+interface MarkRequiresLoginRequest {
+  pageId: number;
+}
+
+// --- Page States ---
+interface FindPageStateRequest {
+  pageId: number;
+  sizeClass: string;
+  hashes: PageHashes;
+}
+
+interface CreatePageStateRequest {
+  pageId: number;
+  sizeClass: string;
+  hashes: PageHashes;
+  screenshotPath?: string;
+  rawHtmlPath?: string;
+  contentText?: string;
+}
+
+interface PageStateResponse {
+  id: number;
+  pageId: number;
+  sizeClass: string;
+  htmlHash: string | null;
+  normalizedHtmlHash: string | null;
+  textHash: string | null;
+  actionableHash: string | null;
+  createdByActionId: number;
+  screenshotPath: string | null;
+  rawHtmlPath: string | null;
+  contentText: string | null;
+  capturedAt: string | null;
+}
+
+// --- Actionable Items ---
+interface InsertActionableItemsRequest {
+  pageStateId: number;
+  items: ActionableItem[];
+}
+
+interface ActionableItemResponse {
+  id: number;
+  pageStateId: number;
+  stableKey: string | null;
+  selector: string | null;
+  tagName: string | null;
+  role: string | null;
+  actionKind: string | null;
+  accessibleName: string | null;
+  disabled: boolean | null;
+  visible: boolean | null;
+  x: number | null;
+  y: number | null;
+  width: number | null;
+  height: number | null;
+  attributesJson: unknown;
+}
+
+// --- Actions ---
+interface CreateActionRequest {
+  runId: number;
+  type: string;
+  actionableItemId?: number;
+  startingPageStateId?: number;
+  targetPageId?: number;
+  sizeClass: string;
+  personaId?: number;
+  useCaseId?: number;
+  inputValue?: string;
+}
+
+interface CompleteActionRequest {
+  targetPageId?: number;
+  targetPageStateId?: number;
+  durationMs?: number;
+  consoleLog?: string;
+  networkLog?: string;
+  screenshotBefore?: string;
+  screenshotAfter?: string;
+}
+
+interface ActionResponse {
+  id: number;
+  runId: number;
+  type: string;
+  actionableItemId: number;
+  startingPageStateId: number;
+  targetPageId: number;
+  targetPageStateId: number;
+  personaId: number;
+  useCaseId: number;
+  inputValue: string | null;
+  status: string;
+  sizeClass: string;
+  durationMs: number | null;
+  screenshotBefore: string | null;
+  screenshotAfter: string | null;
+  consoleLog: string | null;
+  networkLog: string | null;
+  startedAt: string | null;
+  executedAt: string | null;
+}
+
+// --- Personas / Use Cases / Input Values ---
+interface CreatePersonaRequest {
+  appId: number;
+  name: string;
+  description: string;
+}
+
+interface PersonaResponse {
+  id: number;
+  appId: number;
+  name: string;
+  description: string | null;
+  createdAt: string | null;
+}
+
+interface CreateUseCaseRequest {
+  personaId: number;
+  name: string;
+  description: string;
+}
+
+interface UseCaseResponse {
+  id: number;
+  personaId: number;
+  name: string;
+  description: string | null;
+  createdAt: string | null;
+}
+
+interface CreateInputValueRequest {
+  useCaseId: number;
+  fieldSelector: string;
+  fieldName: string;
+  value: string;
+}
+
+interface InputValueResponse {
+  id: number;
+  useCaseId: number;
+  fieldSelector: string;
+  fieldName: string | null;
+  value: string;
+  createdAt: string | null;
+}
+
+// --- Forms ---
+interface InsertFormRequest {
+  pageStateId: number;
+  form: FormInfo;
+  formType?: string;
+}
+
+interface FormResponse {
+  id: number;
+  pageStateId: number;
+  selector: string;
+  action: string | null;
+  method: string | null;
+  submitSelector: string | null;
+  fieldCount: number | null;
+  formType: string | null;
+  fieldsJson: unknown;
+  createdAt: string | null;
+}
+
+// --- Test Cases ---
+interface InsertTestCaseRequest {
+  runId: number;
+  testCase: TestCase;
+}
+
+interface TestCaseResponse {
+  id: number;
+  runId: number;
+  name: string;
+  testType: string;
+  sizeClass: string;
+  suiteTags: string[];
+  pageId: number;
+  personaId: number;
+  useCaseId: number;
+  priority: string;
+  actionsJson: unknown;
+  generatedAt: string | null;
+}
+
+// --- Test Runs ---
+interface CreateTestRunRequest {
+  testCaseId: number;
+  runId: number;
+  screen: string;
+}
+
+interface CompleteTestRunRequest {
+  status: string;
+  durationMs: number;
+  errorMessage?: string;
+  screenshotPath?: string;
+  consoleLog?: string;
+  networkLog?: string;
+}
+
+interface TestRunResponse {
+  id: number;
+  testCaseId: number;
+  runId: number;
+  screen: string;
+  status: string;
+  durationMs: number | null;
+  errorMessage: string | null;
+  screenshotPath: string | null;
+  consoleLog: string | null;
+  networkLog: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+}
+
+// --- Issues ---
+interface CreateIssueRequest {
+  runId: number;
+  actionId?: number;
+  testCaseId?: number;
+  testRunId?: number;
+  type: string;
+  description: string;
+  reproductionSteps: unknown[];
+  consoleLog?: string;
+  networkLog?: string;
+  screenshotPath?: string;
+  pageId?: number;
+  pageStateId?: number;
+}
+
+interface IssueResponse {
+  id: number;
+  runId: number;
+  actionId: number;
+  testCaseId: number;
+  testRunId: number;
+  type: string;
+  description: string;
+  reproductionSteps: unknown;
+  consoleLog: string | null;
+  networkLog: string | null;
+  screenshotPath: string | null;
+  pageId: number;
+  pageStateId: number;
+  createdAt: string | null;
+}
+
+// --- AI Usage ---
+interface RecordAiUsageRequest {
+  runId: number;
+  phase: string;
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  purpose?: string;
+}
+
+// --- Report Emails ---
+interface CreateReportEmailRequest {
+  runId: number;
+  userEmail: string;
+  deepLinkToken: string;
+}
+
+// --- Components ---
+interface SaveComponentRequest {
+  appId: number;
+  sizeClass: string;
+  component: {
+    name: string;
+    selector: string;
+    hash: string;
+    canonicalPageStateId: number;
+    instances: Array<{
+      pageStateId: number;
+      isIdentical: boolean;
+      hash: string;
+    }>;
+  };
+}
+
+// --- Apps ---
+interface AppResponse {
+  id: number;
+  projectId: number;
+  name: string;
+  baseUrl: string | null;
+  normalizedBaseUrl: string;
+  createdAt: string | null;
+}
+```
+
+**After modifying**: Run `~/projects/testomniac_app/scripts/push_all.sh` to publish the updated types package.
+
+---
+
+## Phase 2: Add Scanner Tables to API
+
+The API currently only has entity-related tables. All scanner tables need to be added.
+
+**Files to modify:**
+- `~/projects/testomniac_api/src/db/schema.ts` — add Drizzle schema definitions for all scanner tables
+- `~/projects/testomniac_api/src/db/index.ts` — add `CREATE TABLE IF NOT EXISTS` statements in `initDatabase()`
+
+**Tables to add** (matching the scanner's existing schema exactly):
+projects, apps, runs, pages, page_states, actionable_items, actions, personas, use_cases, input_values, forms, components, component_instances, test_cases, test_runs, issues, ai_usage, report_emails
+
+All tables go under the `testomniac` schema (same as existing tables). Use the scanner's `src/db/schema.ts` as the source of truth for column definitions.
+
+---
+
+## Phase 3: API Key Middleware for Scanner Auth
+
+**File to create**: `~/projects/testomniac_api/src/middleware/scannerAuth.ts`
+
+```
+Check X-Scanner-Key header against SCANNER_API_KEY env var.
+Missing or invalid key → 401.
+```
+
+**File to modify**: `~/projects/testomniac_api/.env.example` — add `SCANNER_API_KEY=`
+
+---
+
+## Phase 4: Firebase Auth + Entity Access Control on GET Endpoints
+
+**File to create**: `~/projects/testomniac_api/src/middleware/projectAccess.ts`
+
+Logic:
+1. Load project by ID from URL param
+2. If project has no `entityId` → allow (anyone can view unclaimed projects)
+3. If project has `entityId`:
+   a. Require Firebase auth (user must be logged in)
+   b. Check if user is associated with that entity using `entityHelpers.members.isMember(entityId, userId)`
+   c. For personal entities: `isMember` returns true for the owner
+   d. For organization entities: `isMember` returns true for any active member (which covers member entities)
+   e. If not a member → 403
+
+This reuses the `@sudobility/entity_service` `isMember()` method which already handles both personal and organization entity types.
+
+---
+
+## Phase 5: REST Endpoints in API
+
+### 5a. Public endpoint (no auth)
+
+**File to create**: `~/projects/testomniac_api/src/routes/scan.ts`
+
+| Method | Path | Request Type | Response Type |
+|--------|------|-------------|---------------|
+| POST | `/api/v1/scan` | `CreateScanRequest` | `BaseResponse<CreateScanResponse>` |
+
+Creates project + app + run + initial navigate action. Uses existing types already in `testomniac_types`.
+
+### 5b. Scanner-facing endpoints (API key auth)
+
+**File to create**: `~/projects/testomniac_api/src/routes/scanner.ts`
+
+All wrapped with `scannerAuthMiddleware`. All request/response bodies use types from `@sudobility/testomniac_types`.
+
+| Method | Path | Request Type | Response Type |
+|--------|------|-------------|---------------|
+| GET | `/scanner/runs/pending` | — | `BaseResponse<PendingRunResponse \| null>` |
+| PATCH | `/scanner/runs/:id/phase` | `UpdateRunPhaseRequest` | `BaseResponse<void>` |
+| PATCH | `/scanner/runs/:id/stats` | `UpdateRunStatsRequest` | `BaseResponse<void>` |
+| PATCH | `/scanner/runs/:id/phase-duration` | `UpdatePhaseDurationRequest` | `BaseResponse<void>` |
+| PATCH | `/scanner/runs/:id/complete` | `CompleteRunRequest` | `BaseResponse<void>` |
+| GET | `/scanner/apps/:id` | — | `BaseResponse<AppResponse>` |
+| POST | `/scanner/pages` | `FindOrCreatePageRequest` | `BaseResponse<PageResponse>` |
+| PATCH | `/scanner/pages/:id/requires-login` | — | `BaseResponse<void>` |
+| GET | `/scanner/pages?appId=X` | — | `BaseResponse<PageResponse[]>` |
+| POST | `/scanner/page-states` | `CreatePageStateRequest` | `BaseResponse<PageStateResponse>` |
+| GET | `/scanner/page-states/match` | query: pageId, sizeClass, hashes | `BaseResponse<PageStateResponse \| null>` |
+| POST | `/scanner/actionable-items` | `InsertActionableItemsRequest` | `BaseResponse<ActionableItemResponse[]>` |
+| GET | `/scanner/actionable-items?pageStateId=X` | — | `BaseResponse<ActionableItemResponse[]>` |
+| POST | `/scanner/actions` | `CreateActionRequest` | `BaseResponse<ActionResponse>` |
+| GET | `/scanner/actions/next?runId=X&sizeClass=Y` | — | `BaseResponse<ActionResponse \| null>` |
+| PATCH | `/scanner/actions/:id/start` | — | `BaseResponse<void>` |
+| PATCH | `/scanner/actions/:id/complete` | `CompleteActionRequest` | `BaseResponse<void>` |
+| GET | `/scanner/actions/open-count?runId=X&sizeClass=Y` | — | `BaseResponse<{count: number}>` |
+| GET | `/scanner/actions/chain/:id` | — | `BaseResponse<ActionResponse[]>` |
+| POST | `/scanner/personas` | `CreatePersonaRequest` | `BaseResponse<PersonaResponse>` |
+| GET | `/scanner/personas?appId=X` | — | `BaseResponse<PersonaResponse[]>` |
+| POST | `/scanner/use-cases` | `CreateUseCaseRequest` | `BaseResponse<UseCaseResponse>` |
+| GET | `/scanner/use-cases?personaId=X` | — | `BaseResponse<UseCaseResponse[]>` |
+| POST | `/scanner/input-values` | `CreateInputValueRequest` | `BaseResponse<InputValueResponse>` |
+| GET | `/scanner/input-values?useCaseId=X` | — | `BaseResponse<InputValueResponse[]>` |
+| POST | `/scanner/forms` | `InsertFormRequest` | `BaseResponse<FormResponse>` |
+| GET | `/scanner/forms?pageStateId=X` | — | `BaseResponse<FormResponse[]>` |
+| POST | `/scanner/test-cases` | `InsertTestCaseRequest` | `BaseResponse<TestCaseResponse>` |
+| GET | `/scanner/test-cases?runId=X` | — | `BaseResponse<TestCaseResponse[]>` |
+| POST | `/scanner/test-runs` | `CreateTestRunRequest` | `BaseResponse<TestRunResponse>` |
+| PATCH | `/scanner/test-runs/:id/complete` | `CompleteTestRunRequest` | `BaseResponse<void>` |
+| POST | `/scanner/issues` | `CreateIssueRequest` | `BaseResponse<IssueResponse>` |
+| GET | `/scanner/issues?runId=X` | — | `BaseResponse<IssueResponse[]>` |
+| POST | `/scanner/ai-usage` | `RecordAiUsageRequest` | `BaseResponse<void>` |
+| POST | `/scanner/report-emails` | `CreateReportEmailRequest` | `BaseResponse<void>` |
+| POST | `/scanner/components` | `SaveComponentRequest` | `BaseResponse<void>` |
+
+### 5c. User-facing GET endpoints (Firebase auth + project access)
+
+**File to create**: `~/projects/testomniac_api/src/routes/projects.ts`
+
+| Method | Path | Response Type |
+|--------|------|---------------|
+| GET | `/projects/:id` | `BaseResponse<ProjectSummaryResponse>` |
+| GET | `/projects/:id/runs` | `BaseResponse<RunDetailResponse[]>` |
+| GET | `/runs/:id` | `BaseResponse<RunDetailResponse>` |
+| GET | `/runs/:id/issues` | `BaseResponse<IssueResponse[]>` |
+| GET | `/runs/:id/test-cases` | `BaseResponse<TestCaseResponse[]>` |
+| GET | `/runs/:id/test-runs` | `BaseResponse<TestRunResponse[]>` |
+
+**File to modify**: `~/projects/testomniac_api/src/routes/index.ts` — mount all new routers
+
+---
+
+## Phase 6: Refactor Scanner to Use HTTP Client
+
+### 6a. Create API client
+
+**File to create**: `~/projects/testomniac_runner/src/api/client.ts`
+
+A typed HTTP client that:
+- Uses `TESTOMNIAC_API_URL` as base URL
+- Sends `X-Scanner-Key` header with `SCANNER_API_KEY`
+- Exposes methods matching every scanner endpoint
+- All methods use types from `@sudobility/testomniac_types` for request params and return types
+- Unwraps `BaseResponse<T>` and throws on error responses
+
+### 6b. Replace DB calls with API calls
+
+**Files to modify** (replace `import * as xxxRepo from "../db/repositories/xxx"` with `import { apiClient } from "../api/client"`):
+
+| Scanner File | DB Repos Used | Replacement |
+|-------------|---------------|-------------|
+| `src/index.ts` | runs, apps | `apiClient.getPendingRun()`, `apiClient.getApp()`, `apiClient.updateRunPhase()`, `apiClient.completeRun()` |
+| `src/orchestrator.ts` | projects, apps, runs, testCases, reportEmails | All corresponding `apiClient.*` methods |
+| `src/scanner/mouse-scanner.ts` | pages, pageStates, actionableItems, actions, runs | All corresponding `apiClient.*` methods |
+| `src/ai/analyzer.ts` | personas (createPersona, createUseCase, createInputValue) | `apiClient.createPersona()`, etc. |
+| `src/scanner/input-scanner.ts` | personas (getPersonasByApp, getUseCasesByPersona, getInputValuesByUseCase) | `apiClient.getPersonas()`, etc. |
+| `src/generation/generator.ts` | pages (getPagesByApp) | `apiClient.getPages()` |
+| `src/runner/worker-pool.ts` | testRuns, issues | `apiClient.createTestRun()`, `apiClient.completeTestRun()`, `apiClient.createIssue()` |
+| `src/ai/token-tracker.ts` | aiUsage | `apiClient.recordAiUsage()` |
+
+### 6c. Update scanner config
+
+**File to modify**: `src/config/index.ts`
+- Remove `databaseUrl`
+- Add `apiUrl` (from `TESTOMNIAC_API_URL`, default `http://localhost:8027`)
+- Add `scannerApiKey` (from `SCANNER_API_KEY`)
+
+**File to modify**: `.env.example`
+- Remove `DATABASE_URL`
+- Add `TESTOMNIAC_API_URL=http://localhost:8027`
+- Add `SCANNER_API_KEY=`
+
+### 6d. Delete DB code
+
+**Delete entirely**:
+- `src/db/` directory (connection.ts, schema.ts, repositories/*)
+- `drizzle.config.ts`
+
+**Remove from `package.json` dependencies**:
+- `drizzle-orm`
+- `drizzle-kit`
+- `postgres`
+
+---
+
+## Phase 7: Verification
+
+1. **Type check**: `bun run build` in `testomniac_types` — all new types compile
+2. **API tests**: Start API, verify:
+   - `POST /api/v1/scan` creates project + app + run + action
+   - Scanner endpoints return 401 without `X-Scanner-Key`
+   - Scanner endpoints work with correct key
+   - User GET endpoints enforce entity access control
+3. **Scanner tests**: Start scanner with `TESTOMNIAC_API_URL` + `SCANNER_API_KEY`:
+   - Polls `GET /scanner/runs/pending` on interval
+   - Picks up and completes a scan via API calls
+4. **End-to-end**: Submit URL → scanner polls → scan completes → GET results with Firebase token
+5. **Negative tests**:
+   - Invalid scanner API key → 401
+   - User not in entity → 403 on project GET
+   - No entity on project → anyone can GET
+
+---
+
+## Execution Order
+
+1. **Phase 1** (testomniac_types) → run `push_all.sh`
+2. **Phase 2** (API schema + tables)
+3. **Phase 3** (API scanner auth middleware)
+4. **Phase 4** (API project access middleware)
+5. **Phase 5** (API endpoints)
+6. **Phase 6** (scanner refactor)
+7. **Phase 7** (verification)