@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/playwright-expert/references/debugging-flaky.md

@@ -0,0 +1,150 @@
+# Debugging & Flaky Tests
+
+## Debugging Tools
+
+```typescript
+// Pause execution and open inspector
+await page.pause();
+
+// Enable step-by-step mode
+PWDEBUG=1 npx playwright test
+
+// Slow motion
+test.use({ launchOptions: { slowMo: 500 } });
+
+// Headed mode
+npx playwright test --headed
+```
+
+## Trace Viewer
+
+```bash
+# View trace from failed test
+npx playwright show-trace trace.zip
+
+# Generate trace always
+test.use({ trace: 'on' });
+
+# View in UI mode
+npx playwright test --ui
+```
+
+## Common Flaky Test Causes
+
+### 1. Race Conditions
+
+```typescript
+// ❌ Bad: Element may not exist yet
+await page.click('.submit-btn');
+
+// ✅ Good: Auto-waiting built in
+await page.getByRole('button', { name: 'Submit' }).click();
+```
+
+### 2. Animation/Transitions
+
+```typescript
+// ❌ Bad: Click during animation
+await page.click('.menu-item');
+
+// ✅ Good: Wait for stable state
+await page.getByRole('menuitem').click();
+await expect(page.getByRole('menu')).toBeVisible();
+```
+
+### 3. Network Timing
+
+```typescript
+// ❌ Bad: Assumes data loaded
+await page.goto('/dashboard');
+expect(await page.textContent('.user-name')).toBe('John');
+
+// ✅ Good: Wait for network
+await page.goto('/dashboard');
+await page.waitForResponse('**/api/user');
+await expect(page.getByTestId('user-name')).toHaveText('John');
+```
+
+### 4. Test Isolation
+
+```typescript
+// ❌ Bad: Tests share state
+test('test 1', async () => { /* creates user */ });
+test('test 2', async () => { /* assumes user exists */ });
+
+// ✅ Good: Each test is independent
+test.beforeEach(async ({ page }) => {
+  await page.request.post('/api/test/reset');
+});
+```
+
+## Proper Waiting
+
+```typescript
+// Wait for element state
+await expect(page.getByText('Success')).toBeVisible();
+await expect(page.getByRole('button')).toBeEnabled();
+await expect(page.getByRole('dialog')).toBeHidden();
+
+// Wait for navigation
+await page.waitForURL(/dashboard/);
+
+// Wait for response
+await page.waitForResponse(r => r.url().includes('/api/data'));
+
+// Wait for load state
+await page.waitForLoadState('networkidle');
+
+// AVOID arbitrary waits
+await page.waitForTimeout(3000); // ❌ BAD
+```
+
+## Retry Strategies
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  retries: process.env.CI ? 2 : 0,
+
+  // Retry only specific tests
+  expect: {
+    timeout: 10000, // Increase assertion timeout
+  },
+});
+
+// Per-test retry
+test('flaky test', async ({ page }) => {
+  test.info().annotations.push({ type: 'issue', description: 'Known flaky' });
+  // ...
+});
+```
+
+## Debugging Output
+
+```typescript
+// Console output
+test('debug test', async ({ page }) => {
+  page.on('console', msg => console.log(msg.text()));
+  page.on('pageerror', err => console.log(err.message));
+});
+
+// Screenshot on step
+await page.screenshot({ path: 'debug.png' });
+```
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `PWDEBUG=1` | Enable inspector |
+| `--headed` | Show browser |
+| `--ui` | UI mode |
+| `page.pause()` | Pause execution |
+| `show-trace` | View trace file |
+
+| Fix | Flaky Cause |
+|-----|-------------|
+| Auto-wait locators | Race conditions |
+| `waitForResponse` | Network timing |
+| Test isolation | Shared state |
+| Increase timeout | Slow operations |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/playwright-expert/references/page-object-model.md

@@ -0,0 +1,152 @@
+# Page Object Model
+
+## Basic Page Object
+
+```typescript
+// pages/LoginPage.ts
+import { Page, Locator } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel('Email');
+    this.passwordInput = page.getByLabel('Password');
+    this.submitButton = page.getByRole('button', { name: 'Log in' });
+    this.errorMessage = page.getByRole('alert');
+  }
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+
+  async getErrorMessage() {
+    return this.errorMessage.textContent();
+  }
+}
+```
+
+## Using Page Objects in Tests
+
+```typescript
+// tests/login.spec.ts
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+
+test('successful login redirects to dashboard', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+
+  await loginPage.goto();
+  await loginPage.login('user@test.com', 'password123');
+
+  await expect(page).toHaveURL(/dashboard/);
+});
+
+test('invalid credentials show error', async ({ page }) => {
+  const loginPage = new LoginPage(page);
+
+  await loginPage.goto();
+  await loginPage.login('user@test.com', 'wrongpassword');
+
+  await expect(loginPage.errorMessage).toBeVisible();
+});
+```
+
+## Custom Fixtures
+
+```typescript
+// fixtures.ts
+import { test as base } from '@playwright/test';
+import { LoginPage } from './pages/LoginPage';
+import { DashboardPage } from './pages/DashboardPage';
+
+type Fixtures = {
+  loginPage: LoginPage;
+  dashboardPage: DashboardPage;
+  authenticatedPage: Page;
+};
+
+export const test = base.extend<Fixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+
+  dashboardPage: async ({ page }, use) => {
+    await use(new DashboardPage(page));
+  },
+
+  authenticatedPage: async ({ page }, use) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login('user@test.com', 'password123');
+    await page.waitForURL(/dashboard/);
+    await use(page);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+## Using Fixtures
+
+```typescript
+// tests/dashboard.spec.ts
+import { test, expect } from '../fixtures';
+
+test('shows user profile', async ({ authenticatedPage, dashboardPage }) => {
+  await expect(dashboardPage.userProfile).toBeVisible();
+});
+```
+
+## Component Page Objects
+
+```typescript
+// components/NavBar.ts
+export class NavBar {
+  constructor(private page: Page) {}
+
+  readonly homeLink = () => this.page.getByRole('link', { name: 'Home' });
+  readonly profileLink = () => this.page.getByRole('link', { name: 'Profile' });
+  readonly logoutButton = () => this.page.getByRole('button', { name: 'Logout' });
+
+  async logout() {
+    await this.logoutButton().click();
+  }
+}
+
+// pages/DashboardPage.ts
+export class DashboardPage {
+  readonly navBar: NavBar;
+
+  constructor(private page: Page) {
+    this.navBar = new NavBar(page);
+  }
+}
+```
+
+## Quick Reference
+
+| Pattern | Purpose |
+|---------|---------|
+| Page Object | Encapsulate page interactions |
+| Fixture | Share setup across tests |
+| Component PO | Reusable UI components |
+| Locator methods | Lazy evaluation |
+
+| Best Practice | Reason |
+|---------------|--------|
+| Methods for actions | Readable tests |
+| Locators as getters | Lazy evaluation |
+| No assertions in PO | Flexibility |
+| Fixtures for setup | DRY, maintainable |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/playwright-expert/references/selectors-locators.md

@@ -0,0 +1,119 @@
+# Selectors & Locators
+
+## Selector Priority (Best to Worst)
+
+```typescript
+// 1. Role-based (BEST - accessible)
+await page.getByRole('button', { name: 'Submit' });
+await page.getByRole('textbox', { name: 'Email' });
+await page.getByRole('link', { name: 'Home' });
+await page.getByRole('heading', { level: 1 });
+
+// 2. Label/placeholder (good for forms)
+await page.getByLabel('Email address');
+await page.getByPlaceholder('Enter your email');
+
+// 3. Test ID (good for non-semantic elements)
+await page.getByTestId('user-avatar');
+await page.getByTestId('submit-button');
+
+// 4. Text content
+await page.getByText('Welcome back');
+await page.getByText(/welcome/i);  // Case insensitive
+
+// 5. CSS/XPath (AVOID - brittle)
+await page.locator('.submit-btn');  // Last resort
+await page.locator('#email-input');
+```
+
+## Role-Based Selectors
+
+```typescript
+// Buttons
+page.getByRole('button', { name: 'Submit' });
+page.getByRole('button', { name: /save/i });
+
+// Links
+page.getByRole('link', { name: 'Documentation' });
+
+// Inputs
+page.getByRole('textbox', { name: 'Username' });
+page.getByRole('checkbox', { name: 'Remember me' });
+page.getByRole('combobox', { name: 'Country' });
+
+// Navigation
+page.getByRole('navigation');
+page.getByRole('main');
+page.getByRole('banner');
+
+// Tables
+page.getByRole('row', { name: 'John Doe' });
+page.getByRole('cell', { name: 'Active' });
+```
+
+## Filtering Locators
+
+```typescript
+// Filter by text
+page.getByRole('listitem').filter({ hasText: 'Product A' });
+
+// Filter by child locator
+page.getByRole('listitem').filter({
+  has: page.getByRole('button', { name: 'Delete' })
+});
+
+// Filter by NOT having
+page.getByRole('listitem').filter({
+  hasNot: page.getByText('Sold out')
+});
+
+// Chain locators
+page.getByTestId('product-card').getByRole('button', { name: 'Buy' });
+```
+
+## Handling Multiple Elements
+
+```typescript
+// Get nth element (0-indexed)
+page.getByRole('listitem').nth(0);
+page.getByRole('listitem').first();
+page.getByRole('listitem').last();
+
+// Count elements
+const count = await page.getByRole('listitem').count();
+
+// Iterate
+for (const item of await page.getByRole('listitem').all()) {
+  console.log(await item.textContent());
+}
+```
+
+## Test IDs
+
+```html
+<!-- Add in HTML -->
+<button data-testid="submit-button">Submit</button>
+```
+
+```typescript
+// Configure custom attribute
+// playwright.config.ts
+use: {
+  testIdAttribute: 'data-test-id'
+}
+
+// Use in tests
+page.getByTestId('submit-button');
+```
+
+## Quick Reference
+
+| Locator | Best For |
+|---------|----------|
+| `getByRole()` | Buttons, links, inputs |
+| `getByLabel()` | Form fields |
+| `getByPlaceholder()` | Inputs without labels |
+| `getByTestId()` | Non-semantic elements |
+| `getByText()` | Static text |
+| `filter()` | Narrowing results |
+| `nth()` / `first()` | Multiple matches |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/postman/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: postman
+description: Automate API testing and collection management with Postman MCP using full-mode defaults and workspace-aware execution.
+---
+
+# Postman MCP Skill
+
+Use this skill when you need Postman workspace, collection, environment, or run operations through MCP.
+
+References:
+- [Full-Mode Setup](./references/full-mode-setup.md)
+- [Workspace Policy](./references/workspace-policy.md)
+- [Troubleshooting](./references/troubleshooting.md)
+
+## MCP-First Rule
+
+- Prefer Postman MCP tools for all Postman operations.
+- Use direct Postman server tools for actual Postman cloud work:
+  - direct server: `postman.<tool>`
+  - client-wrapped direct server: `mcp__postman__<tool>`
+- Treat Foundry `postman_*` tools as config helpers only:
+  - `postman_get_status`
+  - `postman_get_mode`
+  - `postman_set_mode`
+- Never default to raw Postman REST JSON payloads, Newman, or Postman CLI when MCP tools are available.
+- Do not use `postman.runMonitor` as an automatic fallback after `postman.runCollection` timeout or failure.
+- Only use monitor execution when the user explicitly asks for monitor-based cloud execution, scheduled monitoring, or monitor validation.
+- Recommend Postman CLI as the default secondary path when direct MCP execution fails.
+- If required Postman MCP tools are unavailable, report discovery/remediation steps first.
+
+## Setup Baseline
+
+1. Install with Postman enabled and explicit full mode (use the same scope as your current install):
+   - `cbx workflows install --platform <codex|antigravity|copilot> --scope <project|global> --bundle agent-environment-setup --postman --postman-mode full --mcp-runtime docker --mcp-fallback local --mcp-tool-sync --yes`
+2. Persist env aliases once (no per-session re-export):
+   - `cbx workflows config keys persist-env --service postman --scope global`
+3. Verify mode/config:
+   - `cbx workflows config --scope <project|global> --show`
+   - `cbx mcp tools sync --service postman --scope <project|global>`
+   - `cbx mcp tools list --service postman --scope <project|global>`
+
+## Preflight
+
+1. Read Postman status first:
+   - Call `postman_get_status` for mode/default-workspace/config state.
+2. Ensure mode is `full`:
+   - If not, call `postman_set_mode` with `mode: full`.
+3. Discover upstream tools:
+   - Confirm required direct Postman server tools exist before execution (for example workspaces/collections/runs).
+
+Execution rule:
+- For Postman requests, call the direct Postman server (`postman.<tool>` or `mcp__postman__<tool>`) instead of Foundry `postman_*` config tools.
+- If the user asks for API payload examples, provide them only as supplemental documentation after MCP execution guidance.
+
+Quota-safe rule:
+- If `postman.runCollection` times out or fails, stop and classify the error before choosing any fallback.
+- Never auto-convert a collection run failure into `postman.runMonitor`.
+- Recommend Postman CLI first for repeatable local reruns.
+
+## Default Workspace Policy
+
+Resolve workspace in this order:
+
+1. User-provided workspace ID.
+2. `postman_get_status.defaultWorkspaceId`.
+3. Auto-detect from workspace listing:
+   - If exactly one workspace exists, use it and state that choice.
+4. If multiple workspaces and no default:
+   - Ask user to choose one.
+   - Recommend persisting it with:
+     - `cbx workflows config --scope <project|global> --workspace-id <workspace-id>`
+
+When a Postman tool requires a workspace argument, always pass the resolved workspace ID explicitly.
+
+## Common Workflows
+
+### Collection Run
+
+1. Resolve workspace ID (policy above).
+2. Resolve `collectionId` and optional `environmentId`.
+3. Call Postman run tool (`postman.runCollection` or alias equivalent).
+4. Return a concise run summary:
+   - total requests
+   - passed/failed tests
+   - failing request/test names
+   - proposed fix path for failures
+
+## Failure Handling
+
+### Error Classification
+
+Classify failures before suggesting any fallback:
+
+- `limitBreachedError` or "breached monitoring usage limit":
+  - monitor quota exhaustion
+  - do not retry monitor runs
+  - recommend local Postman CLI execution
+  - tell the user to check the Postman monitoring usage dashboard
+- `429` or rate-limit response:
+  - Postman API rate limiting
+  - recommend backoff and a lower request burst
+  - do not reinterpret it as monitor quota
+- collection run timeout without quota/rate-limit signal:
+  - direct MCP runtime or tool timeout
+  - do not auto-convert to a monitor run
+  - recommend Postman CLI or a smaller-scope rerun
+
+### Quota Notes
+
+- Monitor usage is separate from Postman API rate limits.
+- Monitor usage is plan/billing usage and is consumed by request count, region count, and auth requests.
+- Monitor runtime caps are separate from monitor quota and do not imply quota remains available.
+
+If dynamic Postman tools are missing:
+
+1. Verify env alias expected by config is set.
+2. Resync catalog:
+   - `cbx mcp tools sync --service postman --scope <project|global>`
+   - `cbx mcp tools list --service postman --scope <project|global>`
+3. Recreate runtime if needed:
+   - `cbx mcp runtime up --scope <project|global> --name cbx-mcp --replace --port 3310 --skills-root ~/.agents/skills`
+
+## Security Notes
+
+- Use environment variables for secrets. Do not inline API keys.
+- Never print or persist raw key values in logs, docs, or responses.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/postman/references/full-mode-setup.md

@@ -0,0 +1,40 @@
+# Postman Full-Mode Setup
+
+Use CLI mode flags instead of manual `jq` edits.
+
+## Install/Upgrade with Full Mode
+
+```bash
+cbx workflows install \
+  --platform codex \
+  --scope <project|global> \
+  --bundle agent-environment-setup \
+  --postman \
+  --postman-mode full \
+  --mcp-runtime docker \
+  --mcp-fallback local \
+  --mcp-tool-sync \
+  --overwrite \
+  --yes
+```
+
+## Change Mode Later
+
+```bash
+cbx workflows config --scope <project|global> --platform codex --postman-mode full
+```
+
+This updates:
+- `cbx_config.json` Postman URL
+- managed Postman MCP definition under `.cbx/mcp/<platform>/postman.json`
+- platform MCP runtime target patch (when platform is resolvable)
+
+## Persist Env Aliases
+
+```bash
+cbx workflows config keys persist-env --service postman --scope global
+```
+
+Note:
+- `persist-env` writes CBX-managed aliases to `~/.cbx/credentials.env`.
+- Keep MCP target scope (`project` or `global`) aligned with the scope where you installed Postman integration.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/postman/references/troubleshooting.md

@@ -0,0 +1,69 @@
+# Postman MCP Troubleshooting
+
+## Only `postman_get_*` / `postman_set_mode` tools appear
+
+1. Confirm active env alias exists in shell (or persisted env file).
+2. Sync catalog in the same install scope:
+
+```bash
+cbx mcp tools sync --service postman --scope <project|global>
+cbx mcp tools list --service postman --scope <project|global>
+```
+
+3. Restart runtime if using Docker:
+
+```bash
+cbx mcp runtime up --scope <project|global> --name cbx-mcp --replace --port 3310
+```
+
+4. If dynamic Postman tools are still missing, do not fall back to manual JSON/CLI by default:
+   - report MCP tool discovery failure
+   - ask for remediation approval
+   - only use fallback if the user explicitly requests it
+
+## Client does not show dotted names
+
+Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
+
+## Missing API key at startup
+
+Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
+
+## Quota-safe execution
+
+Preferred path:
+
+1. Use direct Postman MCP collection execution first (`postman.runCollection` or equivalent).
+2. If that fails, stop and classify the error.
+3. Recommend Postman CLI as the safe default secondary path.
+4. Use monitor execution only when the user explicitly asks for monitor-based cloud execution.
+
+Do not auto-fallback from `runCollection` to `runMonitor`.
+
+## Error classification
+
+### `limitBreachedError` or "breached monitoring usage limit"
+
+- This is monitor quota exhaustion, not generic API failure.
+- Do not retry monitor runs.
+- Do not reinterpret it as an MCP auth issue.
+- Tell the user to check Postman monitoring usage and billing-period reset in the Postman dashboard.
+- Recommend Postman CLI as the next execution path.
+
+### `429` or rate-limited API response
+
+- This is Postman API rate limiting.
+- Reduce request burst, add backoff, and retry later.
+- Do not treat it as monitor quota exhaustion.
+
+### `runCollection` timeout without quota/rate-limit signal
+
+- Treat this as direct MCP/runtime timeout.
+- Do not auto-convert to monitor execution.
+- Recommend Postman CLI or a smaller-scope rerun.
+
+## Monitor usage facts
+
+- Monitor usage is separate from Postman API RPM limits.
+- Monitor usage is consumed by request count, region count, and auth requests.
+- Monitor runtime caps are separate from monitor quota and do not imply usage remains available.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/postman/references/workspace-policy.md

@@ -0,0 +1,20 @@
+# Workspace Default Policy
+
+Resolve workspace ID in this order:
+
+1. User-provided workspace ID in the request
+2. `postman_get_status` default workspace
+3. Auto-detected workspace when only one exists
+4. Explicit user selection when multiple workspaces exist
+
+## Persist Selected Workspace
+
+```bash
+cbx workflows config --scope global --workspace-id <workspace-id>
+```
+
+Clear workspace default:
+
+```bash
+cbx workflows config --scope global --clear-workspace-id
+```