@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/playwright-persistent-browser/references/authentication.md

@@ -1,250 +0,0 @@
-# Authentication
-
-Load this reference when implementing login flows, managing auth tokens, or reusing authentication state across tests or workflow steps.
-
-## Authentication Flow Patterns
-
-### Form-based login
-
-The most common pattern. Fill credentials, submit, wait for redirect.
-
-```typescript
-async function loginWithForm(page: Page, email: string, password: string) {
-  await page.goto('https://app.com/login');
-  await page.getByLabel('Email').fill(email);
-  await page.getByLabel('Password').fill(password);
-  await page.getByRole('button', { name: 'Sign in' }).click();
-  await page.waitForURL('**/dashboard');
-}
-```
-
-### OAuth / SSO redirect flow
-
-OAuth flows redirect to a third-party provider. Handle the full redirect chain.
-
-```typescript
-async function loginWithOAuth(page: Page) {
-  await page.goto('https://app.com/login');
-  await page.getByRole('button', { name: 'Sign in with Google' }).click();
-
-  // Now on Google's login page
-  await page.waitForURL('**/accounts.google.com/**');
-  await page.getByLabel('Email or phone').fill(process.env.GOOGLE_EMAIL!);
-  await page.getByRole('button', { name: 'Next' }).click();
-  await page.getByLabel('Enter your password').fill(process.env.GOOGLE_PASSWORD!);
-  await page.getByRole('button', { name: 'Next' }).click();
-
-  // Wait for redirect back to app
-  await page.waitForURL('**/app.com/dashboard');
-}
-```
-
-### API-based authentication
-
-Bypass the UI entirely by calling the auth API directly:
-
-```typescript
-async function loginViaAPI(context: BrowserContext, email: string, password: string) {
-  const response = await context.request.post('https://app.com/api/auth/login', {
-    data: { email, password },
-  });
-
-  const { token } = await response.json();
-
-  // Set the token as a cookie
-  await context.addCookies([{
-    name: 'auth_token',
-    value: token,
-    domain: 'app.com',
-    path: '/',
-    httpOnly: true,
-    secure: true,
-    sameSite: 'Lax',
-    expires: Math.floor(Date.now() / 1000) + 86400,
-  }]);
-}
-```
-
-API login is faster and more reliable than UI login. Use it when:
-- The auth API is stable and documented
-- You do not need to test the login UI itself
-- You want tests to be independent of login page changes
-
-### Multi-factor authentication
-
-MFA complicates automation. Strategies:
-
-| MFA type | Automation approach |
-| --- | --- |
-| TOTP (authenticator app) | Generate codes with `otplib` library using the secret key |
-| SMS/Email OTP | Use a test account with MFA disabled, or mock the OTP endpoint |
-| Push notification | Cannot automate; use a test account with MFA disabled |
-| Hardware key (FIDO2) | Cannot automate; use a test account with MFA disabled |
-
-```typescript
-import { authenticator } from 'otplib';
-
-async function handleTOTP(page: Page, secret: string) {
-  const otp = authenticator.generate(secret);
-  await page.getByLabel('Verification code').fill(otp);
-  await page.getByRole('button', { name: 'Verify' }).click();
-}
-```
-
-## Global Setup Authentication
-
-Authenticate once before all tests and share the state:
-
-```typescript
-// global-setup.ts
-import { chromium, FullConfig } from '@playwright/test';
-
-async function globalSetup(config: FullConfig) {
-  const browser = await chromium.launch();
-  const context = await browser.newContext();
-  const page = await context.newPage();
-
-  await page.goto('https://app.com/login');
-  await page.getByLabel('Email').fill(process.env.TEST_EMAIL!);
-  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
-  await page.getByRole('button', { name: 'Sign in' }).click();
-  await page.waitForURL('**/dashboard');
-
-  // Save state for all tests to reuse
-  await context.storageState({ path: 'playwright/.auth/user.json' });
-  await browser.close();
-}
-
-export default globalSetup;
-```
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  globalSetup: require.resolve('./global-setup'),
-  projects: [
-    {
-      name: 'authenticated',
-      use: { storageState: 'playwright/.auth/user.json' },
-    },
-    {
-      name: 'unauthenticated',
-      use: { storageState: { cookies: [], origins: [] } },
-    },
-  ],
-});
-```
-
-## Token Refresh Handling
-
-Long-running sessions encounter token expiration. Handle refresh proactively.
-
-### Intercepting 401 responses
-
-```typescript
-context.on('response', async (response) => {
-  if (response.status() === 401 && !response.url().includes('/auth/')) {
-    console.warn('Session expired, triggering refresh');
-    await refreshToken(context);
-  }
-});
-
-async function refreshToken(context: BrowserContext) {
-  const response = await context.request.post('https://app.com/api/auth/refresh');
-  if (response.ok()) {
-    // New cookies are set automatically by the response
-    await context.storageState({ path: 'auth-state.json' });
-    console.log('Token refreshed and state saved');
-  } else {
-    throw new Error('Token refresh failed — full re-authentication required');
-  }
-}
-```
-
-### Proactive refresh
-
-Refresh before the token expires rather than reacting to 401s:
-
-```typescript
-function scheduleRefresh(context: BrowserContext, tokenExpiresInMs: number) {
-  // Refresh at 80% of token lifetime
-  const refreshAfter = tokenExpiresInMs * 0.8;
-
-  setTimeout(async () => {
-    await refreshToken(context);
-    // Schedule the next refresh
-    scheduleRefresh(context, tokenExpiresInMs);
-  }, refreshAfter);
-}
-```
-
-## Multi-Role Authentication
-
-Test different user roles by maintaining separate state files:
-
-```typescript
-// global-setup.ts
-const roles = [
-  { name: 'admin', email: 'admin@test.com', password: 'admin-pass' },
-  { name: 'editor', email: 'editor@test.com', password: 'editor-pass' },
-  { name: 'viewer', email: 'viewer@test.com', password: 'viewer-pass' },
-];
-
-async function globalSetup() {
-  const browser = await chromium.launch();
-
-  for (const role of roles) {
-    const context = await browser.newContext();
-    const page = await context.newPage();
-    await loginWithForm(page, role.email, role.password);
-    await context.storageState({ path: `playwright/.auth/${role.name}.json` });
-    await context.close();
-  }
-
-  await browser.close();
-}
-```
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  projects: [
-    {
-      name: 'admin-tests',
-      use: { storageState: 'playwright/.auth/admin.json' },
-      testMatch: '**/admin/**',
-    },
-    {
-      name: 'editor-tests',
-      use: { storageState: 'playwright/.auth/editor.json' },
-      testMatch: '**/editor/**',
-    },
-  ],
-});
-```
-
-## Credential Security
-
-| Practice | Do | Do not |
-| --- | --- | --- |
-| Store credentials | Environment variables, CI secrets | Hardcoded in code or config |
-| State files | `.gitignore` the auth state directory | Commit state files to version control |
-| Test accounts | Dedicated test accounts with minimal permissions | Shared personal accounts |
-| CI secrets | GitHub/GitLab encrypted secrets | Plain text in CI config |
-
-```gitignore
-# .gitignore
-playwright/.auth/
-*.auth.json
-state/*.json
-```
-
-## Debugging Authentication Issues
-
-| Symptom | Likely cause | Fix |
-| --- | --- | --- |
-| Tests fail with 401 after restore | Session expired between runs | Add validation check before using state |
-| Login works locally, fails in CI | Different cookie domain or secure flag | Match CI base URL to cookie domain |
-| Intermittent auth failures | Race condition in token refresh | Serialize refresh calls with a mutex |
-| MFA prompt appears unexpectedly | Test account MFA was enabled | Use a dedicated test account with MFA off |
-| Cookies not saved | Domain mismatch (`.app.com` vs `app.com`) | Check cookie domain in state file |

package/workflows/workflows/agent-environment-setup/platforms/gemini/skills/playwright-persistent-browser/references/browser-contexts.md

@@ -1,253 +0,0 @@
-# Browser Contexts
-
-Load this reference when creating or managing browser contexts, coordinating multi-tab sessions, or configuring context isolation.
-
-## Context Architecture
-
-Playwright's hierarchy:
-
-```
-Browser (single process)
-  └── BrowserContext (isolated session — cookies, storage, cache)
-        ├── Page (tab 1)
-        ├── Page (tab 2)
-        └── Page (tab 3)
-```
-
-- **Browser**: One Chromium/Firefox/WebKit process. Expensive to create. Reuse across contexts.
-- **BrowserContext**: Isolated session. Tabs within a context share cookies, localStorage, sessionStorage, and cache. Contexts do not share state with each other.
-- **Page**: A single tab or popup. Has its own navigation history, DOM, and JavaScript execution context.
-
-## Creating Contexts
-
-### Default context
-
-```typescript
-const browser = await chromium.launch();
-const context = await browser.newContext();
-const page = await context.newPage();
-```
-
-### Context with options
-
-```typescript
-const context = await browser.newContext({
-  viewport: { width: 1280, height: 720 },
-  locale: 'en-US',
-  timezoneId: 'America/New_York',
-  geolocation: { latitude: 40.7128, longitude: -74.006 },
-  permissions: ['geolocation'],
-  userAgent: 'Custom User Agent',
-  httpCredentials: { username: 'user', password: 'pass' },
-  ignoreHTTPSErrors: true,
-  proxy: { server: 'http://proxy.example.com:8080' },
-});
-```
-
-### Context from saved state
-
-```typescript
-const context = await browser.newContext({
-  storageState: 'state.json',
-});
-```
-
-## Multi-Tab Patterns
-
-### Creating tabs
-
-```typescript
-const page1 = await context.newPage();
-const page2 = await context.newPage();
-const page3 = await context.newPage();
-
-// All three tabs share cookies set by any one of them
-await page1.goto('https://app.com/login');
-// After login on page1, page2 and page3 are also authenticated
-```
-
-### Tab identification
-
-Track which page handles which role:
-
-```typescript
-const tabs = new Map<string, Page>();
-tabs.set('dashboard', await context.newPage());
-tabs.set('editor', await context.newPage());
-tabs.set('preview', await context.newPage());
-
-// Access by role
-const dashboard = tabs.get('dashboard')!;
-await dashboard.goto('https://app.com/dashboard');
-```
-
-### Handling popups
-
-When a page opens a new tab (via `target="_blank"` or `window.open`):
-
-```typescript
-const [popup] = await Promise.all([
-  context.waitForEvent('page'),
-  page.getByRole('link', { name: 'Open in new tab' }).click(),
-]);
-
-await popup.waitForLoadState();
-console.log('Popup URL:', popup.url());
-```
-
-### Closing tabs safely
-
-```typescript
-// Close a specific tab
-await page2.close();
-
-// Close all tabs except one
-const pages = context.pages();
-for (const p of pages) {
-  if (p !== page1) await p.close();
-}
-```
-
-## Context Isolation
-
-### Why isolation matters
-
-Each context has completely separate:
-- Cookies (including HttpOnly and Secure)
-- localStorage and sessionStorage per origin
-- Cache (HTTP cache, service worker cache)
-- Permissions (geolocation, notifications)
-- Credentials (HTTP auth)
-
-This means:
-- Logging in on context A does not affect context B
-- Clearing cache on context A does not affect context B
-- Permission grants on context A do not affect context B
-
-### When to use multiple contexts
-
-| Scenario | Single context | Multiple contexts |
-| --- | --- | --- |
-| Tabs that share auth | Yes | No |
-| Testing two users simultaneously | No | Yes |
-| Isolation between test cases | No | Yes |
-| Simulating a logged-in and guest view | No | Yes |
-
-### Multi-user pattern
-
-```typescript
-const adminContext = await browser.newContext({
-  storageState: 'admin-state.json',
-});
-const userContext = await browser.newContext({
-  storageState: 'user-state.json',
-});
-
-const adminPage = await adminContext.newPage();
-const userPage = await userContext.newPage();
-
-// Admin and user see different things on the same URL
-await adminPage.goto('https://app.com/settings');
-await userPage.goto('https://app.com/settings');
-```
-
-## Persistent Contexts
-
-For tools that need to preserve browser profile data (extensions, bookmarks, history):
-
-```typescript
-// Launch with a persistent user data directory
-const context = await chromium.launchPersistentContext('/path/to/user-data-dir', {
-  headless: false,
-  viewport: { width: 1280, height: 720 },
-});
-
-const page = context.pages()[0] || await context.newPage();
-```
-
-Persistent contexts:
-- Save cookies, cache, and history to disk automatically
-- Survive browser restarts
-- Support browser extensions
-- Cannot use `storageState` option (state is in the user data dir)
-
-### Cleanup for persistent contexts
-
-```typescript
-// The user data directory accumulates data over time
-// Clean it periodically for long-running automations
-import * as fs from 'fs';
-
-function cleanUserDataDir(dir: string) {
-  const cacheDir = path.join(dir, 'Default', 'Cache');
-  if (fs.existsSync(cacheDir)) {
-    fs.rmSync(cacheDir, { recursive: true });
-  }
-}
-```
-
-## Event Handling
-
-### Context-level events
-
-```typescript
-// Listen for new pages (tabs/popups)
-context.on('page', (page) => {
-  console.log('New page opened:', page.url());
-});
-
-// Listen for requests across all pages
-context.on('request', (request) => {
-  console.log('Request:', request.method(), request.url());
-});
-
-// Listen for responses across all pages
-context.on('response', (response) => {
-  console.log('Response:', response.status(), response.url());
-});
-
-// Listen for console messages across all pages
-context.on('console', (msg) => {
-  console.log('Console:', msg.type(), msg.text());
-});
-```
-
-### Context-level route interception
-
-Routes registered on the context apply to all pages:
-
-```typescript
-await context.route('**/api/auth/refresh', (route) =>
-  route.fulfill({ status: 200, body: '{"token": "refreshed"}' })
-);
-
-// This mock applies to page1, page2, page3, and any future pages
-```
-
-## Resource Management
-
-### Memory per context
-
-Each context consumes approximately 20-50 MB of base memory, plus the memory of each page. For long-running applications:
-
-- Close pages you no longer need
-- Limit the number of concurrent pages
-- Monitor memory with CDP (Chrome DevTools Protocol)
-
-### Context limits
-
-There is no hard limit on contexts per browser, but each context starts additional renderer processes. Practical limit: 10-20 contexts per browser on a standard CI machine (4 GB RAM).
-
-### Graceful shutdown
-
-```typescript
-async function shutdown(browser: Browser) {
-  const contexts = browser.contexts();
-  for (const ctx of contexts) {
-    // Save state before closing
-    await ctx.storageState({ path: `state-${contexts.indexOf(ctx)}.json` });
-    await ctx.close();
-  }
-  await browser.close();
-}
-```