@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/php-pro/references/testing-and-static-analysis.md

@@ -0,0 +1,235 @@
+# Testing and Static Analysis
+
+## PHPUnit Setup
+
+```php
+// tests/Unit/Service/OrderServiceTest.php
+declare(strict_types=1);
+
+namespace Tests\Unit\Service;
+
+use PHPUnit\Framework\TestCase;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+final class OrderServiceTest extends TestCase
+{
+    private OrderService $sut;
+    private OrderRepository&MockObject $repo;
+
+    protected function setUp(): void
+    {
+        $this->repo = $this->createMock(OrderRepository::class);
+        $this->sut = new OrderService($this->repo);
+    }
+
+    #[Test]
+    public function getOrder_existing_returns_order(): void
+    {
+        $expected = new Order(id: 1, product: 'Widget');
+        $this->repo
+            ->expects($this->once())
+            ->method('findById')
+            ->with(1)
+            ->willReturn($expected);
+
+        $result = $this->sut->getOrder(1);
+
+        $this->assertSame($expected, $result);
+    }
+
+    #[Test]
+    public function getOrder_missing_throws_not_found(): void
+    {
+        $this->repo->method('findById')->willReturn(null);
+
+        $this->expectException(OrderNotFoundException::class);
+        $this->sut->getOrder(999);
+    }
+}
+```
+
+## Data Providers
+
+```php
+#[DataProvider('discountData')]
+#[Test]
+public function calculates_discount(string $tier, int $years, float $expected): void
+{
+    $customer = new Customer(tier: $tier, years: $years);
+    $this->assertSame($expected, $this->sut->calculateDiscount($customer));
+}
+
+public static function discountData(): array
+{
+    return [
+        'gold 5+ years'  => ['gold', 6, 0.20],
+        'gold under 5'   => ['gold', 3, 0.15],
+        'silver'         => ['silver', 1, 0.10],
+        'standard'       => ['standard', 0, 0.0],
+    ];
+}
+```
+
+## Pest (Alternative Syntax)
+
+```php
+// tests/Feature/OrderApiTest.php
+use function Pest\Laravel\postJson;
+use function Pest\Laravel\assertDatabaseHas;
+
+it('creates an order with valid data', function () {
+    $response = postJson('/api/orders', [
+        'product' => 'Widget',
+        'quantity' => 3,
+    ]);
+
+    $response->assertCreated();
+    assertDatabaseHas('orders', ['product' => 'Widget']);
+});
+
+it('rejects orders with missing product', function () {
+    postJson('/api/orders', ['quantity' => 3])
+        ->assertUnprocessable()
+        ->assertJsonValidationErrors(['product']);
+});
+
+it('applies discount for bulk orders')
+    ->with([
+        [10, 0.05],
+        [50, 0.10],
+        [100, 0.15],
+    ])
+    ->expect(fn (int $qty, float $discount) =>
+        $this->service->calculateDiscount($qty)
+    )->toBe(fn (int $qty, float $discount) => $discount);
+```
+
+## Mocking External Dependencies
+
+```php
+// Mock HTTP client
+#[Test]
+public function fetches_weather_data(): void
+{
+    $httpClient = $this->createMock(HttpClientInterface::class);
+    $httpClient->method('request')
+        ->with('GET', 'https://api.weather.com/current')
+        ->willReturn(new MockResponse(json_encode(['temp' => 22.5])));
+
+    $service = new WeatherService($httpClient);
+    $weather = $service->getCurrent();
+
+    $this->assertSame(22.5, $weather->temperature);
+}
+
+// Prophecy-style mocking (alternative)
+public function prophecy_example(): void
+{
+    $repo = $this->prophesize(UserRepository::class);
+    $repo->findById(1)->willReturn(new User(id: 1, name: 'Alice'));
+    $repo->findById(1)->shouldBeCalledOnce();
+
+    $service = new UserService($repo->reveal());
+    $result = $service->getUser(1);
+
+    $this->assertSame('Alice', $result->name);
+}
+```
+
+## PHPStan Configuration
+
+```neon
+# phpstan.neon
+parameters:
+    level: 9  # maximum strictness
+    paths:
+        - src
+        - tests
+    excludePaths:
+        - src/Generated
+    treatPhpDocTypesAsCertain: false
+    reportUnmatchedIgnoredErrors: true
+
+    # Custom rules
+    ignoreErrors:
+        - '#Call to an undefined method Mockery#'  # test mocking
+
+includes:
+    - vendor/phpstan/phpstan-phpunit/extension.neon
+    - vendor/phpstan/phpstan-deprecation-rules/rules.neon
+    - vendor/phpstan/phpstan-strict-rules/rules.neon
+```
+
+## Psalm Configuration
+
+```xml
+<!-- psalm.xml -->
+<?xml version="1.0"?>
+<psalm
+    errorLevel="1"
+    resolveFromConfigFile="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+>
+    <projectFiles>
+        <directory name="src" />
+        <ignoreFiles>
+            <directory name="vendor" />
+        </ignoreFiles>
+    </projectFiles>
+
+    <plugins>
+        <pluginClass class="Psalm\PhpUnitPlugin\Plugin" />
+    </plugins>
+</psalm>
+```
+
+## CI Pipeline Test Commands
+
+```bash
+# Full test suite
+vendor/bin/phpunit --testdox
+
+# With coverage
+XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-clover coverage.xml
+
+# Static analysis
+vendor/bin/phpstan analyse --memory-limit=512M
+vendor/bin/psalm --no-cache
+
+# Code style
+vendor/bin/php-cs-fixer fix --dry-run --diff
+vendor/bin/phpcs --standard=PSR12 src/
+
+# Security audit
+composer audit
+
+# Typical CI order:
+# 1. composer install --no-dev=false
+# 2. php-cs-fixer (format check)
+# 3. phpstan/psalm (static analysis)
+# 4. phpunit (tests + coverage)
+# 5. composer audit (security)
+```
+
+## Test Organization
+
+```
+tests/
+├── Unit/                    # Fast, isolated, mocked dependencies
+│   ├── Service/
+│   │   └── OrderServiceTest.php
+│   ├── Domain/
+│   │   └── MoneyTest.php
+│   └── Validator/
+│       └── EmailValidatorTest.php
+├── Integration/             # Real database, real HTTP
+│   ├── Repository/
+│   │   └── OrderRepositoryTest.php
+│   └── Api/
+│       └── OrderApiTest.php
+├── Fixtures/                # Shared test data
+│   └── orders.json
+└── phpunit.xml
+```

package/workflows/powers/playwright-e2e/POWER.md

@@ -0,0 +1,85 @@
+````markdown
+---
+inclusion: manual
+name: playwright-e2e
+description: "Use when writing or reviewing browser end-to-end tests with Playwright, debugging flaky UI automation, validating auth or checkout flows, or tightening CI evidence with traces and web-first assertions."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "2.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Playwright E2E
+
+## Purpose
+
+Use when writing or reviewing browser end-to-end tests with Playwright, debugging flaky UI automation, validating auth or checkout flows, or tightening CI evidence with traces and web-first assertions. When Playwright MCP upstream is configured in Cubis Foundry, leverage browser automation tools for live page inspection, snapshot-based debugging, and interactive test development.
+
+## When to Use
+
+- Writing or refactoring Playwright browser tests for critical user journeys.
+- Debugging flaky E2E failures, locator instability, or auth state leakage in CI.
+- Choosing between fixtures, reusable helpers, and page-level abstractions.
+- Reviewing traces, screenshots, videos, and network activity to isolate browser failures.
+- Using Playwright MCP tools for live browser navigation, snapshot capture, and interactive element inspection during test development.
+
+## Instructions
+
+1. Choose the smallest browser journeys that actually protect revenue, auth, or release confidence.
+2. Prefer role, label, text, or explicit test-id locators over DOM-shape selectors.
+3. Keep tests isolated with deterministic data, reusable auth setup, and minimal hidden shared state.
+4. Use web-first assertions, traces, and network evidence before calling a test flaky.
+5. Leave CI with artifacts that explain the failure path instead of screenshots alone.
+
+### Playwright MCP tools
+
+When the Playwright upstream is configured in the Cubis Foundry MCP gateway, these tool categories are available for interactive browser automation:
+
+- **Navigation**: `browser_navigate`, `browser_go_back`, `browser_go_forward`, `browser_wait` — open pages, navigate history, wait for network idle.
+- **Snapshots**: `browser_snapshot` — capture an accessibility-tree snapshot of the current page for element inspection and locator discovery.
+- **Interaction**: `browser_click`, `browser_type`, `browser_select_option`, `browser_hover`, `browser_drag` — interact with page elements using accessibility refs from snapshots.
+- **Keyboard & files**: `browser_press_key`, `browser_file_upload` — press keys or upload files.
+- **Tabs**: `browser_tab_list`, `browser_tab_new`, `browser_tab_select`, `browser_tab_close` — manage browser tabs.
+- **Utilities**: `browser_console_messages`, `browser_generate_playwright_test`, `browser_network_requests`, `browser_install` — read console logs, generate test code, inspect network, install browsers.
+
+Use MCP tools during development to inspect live pages and generate locator-accurate test code. Use the Playwright test runner and CI pipeline for execution.
+
+### Baseline standards
+
+- Test user-visible behavior rather than component internals or CSS structure.
+- Avoid `waitForTimeout`; let locators, assertions, and explicit app signals do the waiting.
+- Reuse authenticated state only through deliberate setup, not test-to-test coupling.
+- Mock or route third-party dependencies you do not control.
+- Treat trace review as the default path for CI-only failures.
+
+### Constraints
+
+- Avoid xPath or fragile class-chain selectors when resilient contracts exist.
+- Avoid giant page-object hierarchies for short or single-owner flows.
+- Avoid browser suites that duplicate unit or integration checks with no added confidence.
+- Avoid marking tests flaky without a trace, reproduction note, and suspected instability source.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                          | Load when                                                                                                                                          |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/locator-trace-flake-checklist.md` | You need a deeper checklist for locator choice, auth setup, trace-driven debugging, retries, CI artifacts, flake triage, or MCP workflow patterns. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with playwright e2e best practices in this project"
+- "Review my playwright e2e implementation for issues"
+- "Use Playwright MCP to inspect the login page and generate test code"
+- "Check playwright upstream status and available browser tools"
+````

package/workflows/powers/playwright-e2e/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: playwright-e2e
+description: "Use when writing or reviewing browser end-to-end tests with Playwright, debugging flaky UI automation, validating auth or checkout flows, or tightening CI evidence with traces and web-first assertions."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "2.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Playwright E2E
+
+## Purpose
+
+Use when writing or reviewing browser end-to-end tests with Playwright, debugging flaky UI automation, validating auth or checkout flows, or tightening CI evidence with traces and web-first assertions. When Playwright MCP upstream is configured in Cubis Foundry, leverage browser automation tools for live page inspection, snapshot-based debugging, and interactive test development.
+
+## When to Use
+
+- Writing or refactoring Playwright browser tests for critical user journeys.
+- Debugging flaky E2E failures, locator instability, or auth state leakage in CI.
+- Choosing between fixtures, reusable helpers, and page-level abstractions.
+- Reviewing traces, screenshots, videos, and network activity to isolate browser failures.
+- Using Playwright MCP tools for live browser navigation, snapshot capture, and interactive element inspection during test development.
+
+## Instructions
+
+1. Choose the smallest browser journeys that actually protect revenue, auth, or release confidence.
+2. Prefer role, label, text, or explicit test-id locators over DOM-shape selectors.
+3. Keep tests isolated with deterministic data, reusable auth setup, and minimal hidden shared state.
+4. Use web-first assertions, traces, and network evidence before calling a test flaky.
+5. Leave CI with artifacts that explain the failure path instead of screenshots alone.
+
+### Playwright MCP tools
+
+When the Playwright upstream is configured in the Cubis Foundry MCP gateway, these tool categories are available for interactive browser automation:
+
+- **Navigation**: `browser_navigate`, `browser_go_back`, `browser_go_forward`, `browser_wait` — open pages, navigate history, wait for network idle.
+- **Snapshots**: `browser_snapshot` — capture an accessibility-tree snapshot of the current page for element inspection and locator discovery.
+- **Interaction**: `browser_click`, `browser_type`, `browser_select_option`, `browser_hover`, `browser_drag` — interact with page elements using accessibility refs from snapshots.
+- **Keyboard & files**: `browser_press_key`, `browser_file_upload` — press keys or upload files.
+- **Tabs**: `browser_tab_list`, `browser_tab_new`, `browser_tab_select`, `browser_tab_close` — manage browser tabs.
+- **Utilities**: `browser_console_messages`, `browser_generate_playwright_test`, `browser_network_requests`, `browser_install` — read console logs, generate test code, inspect network, install browsers.
+
+Use MCP tools during development to inspect live pages and generate locator-accurate test code. Use the Playwright test runner and CI pipeline for execution.
+
+### Baseline standards
+
+- Test user-visible behavior rather than component internals or CSS structure.
+- Avoid `waitForTimeout`; let locators, assertions, and explicit app signals do the waiting.
+- Reuse authenticated state only through deliberate setup, not test-to-test coupling.
+- Mock or route third-party dependencies you do not control.
+- Treat trace review as the default path for CI-only failures.
+
+### Constraints
+
+- Avoid xPath or fragile class-chain selectors when resilient contracts exist.
+- Avoid giant page-object hierarchies for short or single-owner flows.
+- Avoid browser suites that duplicate unit or integration checks with no added confidence.
+- Avoid marking tests flaky without a trace, reproduction note, and suspected instability source.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File                                          | Load when                                                                                                                                          |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `references/locator-trace-flake-checklist.md` | You need a deeper checklist for locator choice, auth setup, trace-driven debugging, retries, CI artifacts, flake triage, or MCP workflow patterns. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with playwright e2e best practices in this project"
+- "Review my playwright e2e implementation for issues"
+- "Use Playwright MCP to inspect the login page and generate test code"
+- "Check playwright upstream status and available browser tools"

package/workflows/powers/playwright-e2e/references/locator-trace-flake-checklist.md

@@ -0,0 +1,80 @@
+# Locator, Trace, and Flake Checklist
+
+Use this when Playwright is already the right tool and you need exact implementation guidance.
+
+## Locator priority
+
+1. Start with `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, or `getByTestId`.
+2. Add filtering or chaining before reaching for positional selectors.
+3. Use explicit test ids only for controls with unstable visible text or repeated semantics.
+4. Treat CSS or XPath selectors as last-resort escape hatches with a comment-worthy reason.
+
+## Test isolation
+
+- Keep each test able to run alone.
+- Build auth setup through fixtures, setup projects, or seeded state, not cross-test ordering.
+- Control database and network inputs for critical flows.
+- Stub or route third-party dependencies you do not own.
+
+## Assertion and waiting rules
+
+- Prefer `await expect(locator).to...` over manual `isVisible()`-style polling.
+- Wait on user-visible state changes, not arbitrary timers.
+- Use network or URL assertions only when they are part of the behavior you are protecting.
+- Do not normalize flakiness by increasing timeouts before understanding the wait condition.
+
+## Trace-driven debugging
+
+- Capture traces on first retry or on failure in CI.
+- When a test fails, inspect:
+  - timeline ordering
+  - actionability logs
+  - DOM snapshot at the failing step
+  - network calls and mocked routes
+  - console or page errors tied to the same flow
+- Add screenshots or videos only as supporting artifacts, not as the primary debugging surface.
+
+## Flake triage
+
+Check these in order:
+
+1. Locator ambiguity or unstable text.
+2. Hidden app loading state or optimistic UI race.
+3. Shared auth or storage state leakage.
+4. Server or mocked dependency nondeterminism.
+5. Environment-only timing differences in CI.
+
+## CI defaults
+
+- Keep retries low and intentional.
+- Upload traces for failed or retried tests.
+- Shard only after local determinism is solid.
+- Separate smoke-critical browser flows from broad exploratory suites.
+
+## MCP workflow patterns
+
+When Playwright MCP upstream is configured in the Cubis Foundry gateway:
+
+### Interactive test development
+
+1. Use `browser_navigate` to open the target page.
+2. Use `browser_snapshot` to capture the accessibility tree and discover locator targets.
+3. Interact with elements via `browser_click`, `browser_type`, `browser_select_option` using accessibility refs from the snapshot.
+4. Use `browser_generate_playwright_test` to produce test code from the recorded interactions.
+5. Refine generated tests with proper assertions, fixtures, and isolation.
+
+### Snapshot-based debugging
+
+- Take `browser_snapshot` at the failing step to compare the DOM state against expected locators.
+- Use `browser_console_messages` to capture console errors tied to the flow.
+- Use `browser_network_requests` to verify API calls and mocked routes.
+
+### Tab and navigation workflow
+
+- Use `browser_tab_new` and `browser_tab_select` to manage multi-tab flows (OAuth popups, payment redirects).
+- Use `browser_go_back` and `browser_go_forward` to test browser history behavior.
+
+### When to use MCP vs test runner
+
+- **MCP tools**: Interactive exploration, locator discovery, test code generation, debugging live pages during development.
+- **Test runner (`npx playwright test`)**: Execution, CI, parallel sharding, retries, reporting, and deterministic assertions.

package/workflows/powers/postgres/POWER.md

@@ -0,0 +1,67 @@
+````markdown
+---
+inclusion: manual
+name: postgres
+description: "Use when the task is specifically PostgreSQL: schema design with Postgres features, query plans, indexes, JSONB, extensions, partitioning, logical replication, or managed Postgres operational tradeoffs."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Postgres
+
+## Purpose
+
+Use when the task is specifically PostgreSQL: schema design with Postgres features, query plans, indexes, JSONB, extensions, partitioning, logical replication, or managed Postgres operational tradeoffs.
+
+## When to Use
+
+- The engine is PostgreSQL or a managed Postgres product.
+- The task depends on Postgres-specific features such as JSONB, partial indexes, CTEs, extensions, or partitioning.
+- You need Postgres-aware migration, replication, or query-plan guidance.
+
+## Instructions
+
+1. Confirm the Postgres variant, version, hosting model, and write/read shape.
+2. Choose the smallest Postgres-specific feature set that solves the real workload.
+3. Design indexes, constraints, and pagination from actual predicates and sort order.
+4. Validate migrations and operational impact, including replication, locks, or extension constraints.
+5. Re-check with `EXPLAIN` evidence and rollback notes before finalizing.
+
+### Baseline standards
+
+- Prefer plain relational design before reaching for JSONB or exotic features.
+- Treat `EXPLAIN`, lock behavior, and index cost as part of every non-trivial change.
+- Keep extension usage deliberate and portable only when portability matters.
+- Make write amplification, autovacuum, and migration blast radius explicit.
+
+### Constraints
+
+- Avoid using JSONB to avoid normal modeling without evidence.
+- Avoid adding indexes without predicate, join, or ordering evidence.
+- Avoid large blocking schema changes without a staged rollout.
+- Avoid treating every Postgres problem as a tuning problem instead of a workload-design problem.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/postgres-checklist.md` | You need a deeper Postgres checklist for indexes, JSONB, extensions, locking, partitioning, and migration safety. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with postgres best practices in this project"
+- "Review my postgres implementation for issues"
+````

package/workflows/powers/postgres/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: postgres
+description: "Use when the task is specifically PostgreSQL: schema design with Postgres features, query plans, indexes, JSONB, extensions, partitioning, logical replication, or managed Postgres operational tradeoffs."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Postgres
+
+## Purpose
+
+Use when the task is specifically PostgreSQL: schema design with Postgres features, query plans, indexes, JSONB, extensions, partitioning, logical replication, or managed Postgres operational tradeoffs.
+
+## When to Use
+
+- The engine is PostgreSQL or a managed Postgres product.
+- The task depends on Postgres-specific features such as JSONB, partial indexes, CTEs, extensions, or partitioning.
+- You need Postgres-aware migration, replication, or query-plan guidance.
+
+## Instructions
+
+1. Confirm the Postgres variant, version, hosting model, and write/read shape.
+2. Choose the smallest Postgres-specific feature set that solves the real workload.
+3. Design indexes, constraints, and pagination from actual predicates and sort order.
+4. Validate migrations and operational impact, including replication, locks, or extension constraints.
+5. Re-check with `EXPLAIN` evidence and rollback notes before finalizing.
+
+### Baseline standards
+
+- Prefer plain relational design before reaching for JSONB or exotic features.
+- Treat `EXPLAIN`, lock behavior, and index cost as part of every non-trivial change.
+- Keep extension usage deliberate and portable only when portability matters.
+- Make write amplification, autovacuum, and migration blast radius explicit.
+
+### Constraints
+
+- Avoid using JSONB to avoid normal modeling without evidence.
+- Avoid adding indexes without predicate, join, or ordering evidence.
+- Avoid large blocking schema changes without a staged rollout.
+- Avoid treating every Postgres problem as a tuning problem instead of a workload-design problem.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+Load on demand. Do not preload all reference files.
+
+| File | Load when |
+| --- | --- |
+| `references/postgres-checklist.md` | You need a deeper Postgres checklist for indexes, JSONB, extensions, locking, partitioning, and migration safety. |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with postgres best practices in this project"
+- "Review my postgres implementation for issues"

package/workflows/powers/postgres/references/postgres-checklist.md

@@ -0,0 +1,20 @@
+# Postgres Checklist
+
+Load this when PostgreSQL work needs deeper tactical guidance.
+
+## Modeling and indexes
+
+- Prefer ordinary relational design before JSONB or specialized extensions.
+- Choose indexes from actual predicates, joins, and ordering.
+- Keep pagination aligned to index shape.
+
+## Operations
+
+- Check lock behavior and migration blast radius.
+- Keep replication and failover posture visible when schema or extension usage changes.
+- Use staged rollouts for heavy DDL or large backfills.
+
+## Evidence
+
+- Use `EXPLAIN` or `EXPLAIN ANALYZE` when query behavior is in scope.
+- Make write amplification, vacuum impact, and rollback explicit.