@cubis/foundry 0.3.67 → 0.3.68

package/workflows/skills/php-pro/references/performance-and-deployment.md

@@ -0,0 +1,197 @@
+# Performance and Deployment
+
+## OPcache Configuration
+
+```ini
+; php.ini — production OPcache settings
+opcache.enable=1
+opcache.memory_consumption=256          ; MB, adjust per app size
+opcache.max_accelerated_files=20000     ; must be prime, covers most projects
+opcache.validate_timestamps=0           ; NEVER check file changes in production
+opcache.revalidate_freq=0               ; irrelevant when validate_timestamps=0
+
+; JIT compilation (PHP 8.0+)
+opcache.jit_buffer_size=128M
+opcache.jit=1255                        ; tracing JIT — best for long-running
+; Use 1205 for function-level JIT if tracing JIT causes issues
+
+; File cache for faster restarts
+opcache.file_cache='/tmp/opcache'
+opcache.file_cache_consistency_checks=0 ; skip in production
+```
+
+## Preloading (PHP 7.4+)
+
+```php
+// preload.php — loaded once at server startup, shared across all requests
+// Set in php.ini: opcache.preload=/app/preload.php
+// opcache.preload_user=www-data
+
+$files = [
+    // Framework core classes
+    __DIR__ . '/vendor/autoload.php',
+    // Heavily used domain classes
+    __DIR__ . '/src/Domain/Order.php',
+    __DIR__ . '/src/Domain/User.php',
+    __DIR__ . '/src/Service/OrderService.php',
+];
+
+foreach ($files as $file) {
+    if (file_exists($file)) {
+        opcache_compile_file($file);
+    }
+}
+
+// Composer autoload preloading (Laravel example)
+// require __DIR__ . '/vendor/autoload.php';
+// (new Illuminate\Foundation\PackageManifest(...))->preload();
+```
+
+## Profiling with Xdebug
+
+```ini
+; php.ini — profiling mode
+xdebug.mode=profile
+xdebug.output_dir=/tmp/xdebug-profiles
+xdebug.profiler_output_name=cachegrind.out.%R.%t
+
+; Trigger-based profiling (don't profile every request)
+xdebug.start_with_request=trigger
+; Add ?XDEBUG_PROFILE=1 to URL or set cookie
+```
+
+```bash
+# Analyze with KCachegrind/QCachegrind
+kcachegrind /tmp/xdebug-profiles/cachegrind.out.*.1234567890
+
+# Or use webgrind for browser-based analysis
+```
+
+## Profiling with Blackfire
+
+```bash
+# Install Blackfire probe + agent
+# Profile a specific request
+blackfire run php artisan my:command
+blackfire curl https://myapp.test/api/orders
+
+# Compare two profiles
+blackfire diff profile-1-uuid profile-2-uuid
+
+# Assertions in CI
+blackfire-player run scenarios.bkf --endpoint=https://staging.myapp.com
+```
+
+## Database Query Optimization
+
+```php
+// Avoid N+1 queries — eager load relations
+// BAD — N+1 queries
+$orders = Order::all();
+foreach ($orders as $order) {
+    echo $order->customer->name; // 1 query per order
+}
+
+// GOOD — eager loading
+$orders = Order::with('customer')->get(); // 2 queries total
+
+// Use query scope for reusable filters
+class Order extends Model
+{
+    public function scopeRecent(Builder $query): Builder
+    {
+        return $query->where('created_at', '>', now()->subDays(30));
+    }
+
+    public function scopeForCustomer(Builder $query, int $customerId): Builder
+    {
+        return $query->where('customer_id', $customerId);
+    }
+}
+
+// Usage: Order::recent()->forCustomer(42)->get();
+```
+
+## Caching Patterns
+
+```php
+// Cache-aside pattern
+public function getProduct(int $id): Product
+{
+    $cacheKey = "product:{$id}";
+
+    return Cache::remember($cacheKey, ttl: 3600, callback: function () use ($id) {
+        return $this->repository->findById($id)
+            ?? throw new ProductNotFoundException($id);
+    });
+}
+
+// Cache invalidation on write
+public function updateProduct(int $id, UpdateProductDto $dto): Product
+{
+    $product = $this->repository->update($id, $dto);
+    Cache::forget("product:{$id}");
+    Cache::tags(['products'])->flush(); // tag-based invalidation
+    return $product;
+}
+```
+
+## FrankenPHP / Swoole / RoadRunner
+
+```php
+// FrankenPHP worker mode — keep application in memory
+// frankenphp.yaml
+worker:
+    cmd: ["frankenphp", "php-server", "--worker", "public/index.php"]
+    watch:
+        - src/**/*.php
+
+// Swoole HTTP server (Laravel Octane)
+// Long-running process — beware of:
+// 1. Static/global state leaking between requests
+// 2. Memory leaks from uncollected references
+// 3. Database connections staying open
+
+// Reset state between requests
+protected function resetState(): void
+{
+    // Clear request-scoped caches
+    // Reset singleton instances that hold request state
+    // Flush buffered output
+}
+```
+
+## Deployment Checklist
+
+```bash
+# 1. Install production dependencies
+composer install --no-dev --optimize-autoloader --classmap-authoritative
+
+# 2. Clear and warm caches
+php artisan config:cache      # Laravel
+php artisan route:cache
+php artisan view:cache
+php artisan event:cache
+
+# 3. Run migrations
+php artisan migrate --force
+
+# 4. OPcache reset (after deploying new code)
+# Via SIGUSR2 to PHP-FPM, or cachetool:
+cachetool opcache:reset
+
+# 5. Verify
+php artisan about              # check config
+php artisan queue:monitor      # check workers
+```
+
+## Common Performance Anti-Patterns
+
+| Anti-pattern                 | Impact                      | Fix                                 |
+| ---------------------------- | --------------------------- | ----------------------------------- |
+| N+1 queries                  | O(n) DB calls per list      | Eager loading, joins                |
+| No OPcache                   | Parses PHP on every request | Enable with `validate_timestamps=0` |
+| Synchronous email sending    | Blocks request for 1-5s     | Queue with jobs/workers             |
+| `file_get_contents` for HTTP | No timeout, no retry        | Use Guzzle/Symfony HttpClient       |
+| Storing sessions in files    | Lock contention under load  | Redis/database sessions             |
+| Loading entire table         | Memory exhaustion           | Cursor/chunk processing             |

package/workflows/skills/php-pro/references/php84-strict-typing-checklist.md

@@ -0,0 +1,161 @@
+# PHP 8.4 Strict Typing Checklist
+
+## Strict types enforcement
+
+### File header
+
+Every PHP file must start with:
+
+```php
+<?php
+
+declare(strict_types=1);
+```
+
+- Without this declaration, PHP silently coerces types (e.g., `"123abc"` becomes `123`).
+- With strict types, type mismatches throw `TypeError` immediately.
+
+### Method signatures
+
+```php
+public function createUser(
+    string $name,
+    string $email,
+    ?int $teamId = null,
+): User {
+    // ...
+}
+```
+
+- Type every parameter, return value, and property. No untyped public APIs.
+- Use `?Type` for nullable parameters. Use `mixed` only when genuinely any type is accepted.
+- Use `void` return type when the function returns nothing.
+
+## PHP 8.4 type features
+
+### Enums
+
+```php
+enum Status: string {
+    case Active = 'active';
+    case Inactive = 'inactive';
+    case Suspended = 'suspended';
+}
+
+// Usage
+function setStatus(Status $status): void { /* ... */ }
+setStatus(Status::Active);
+```
+
+- Use backed enums (`string` or `int`) for values stored in databases or APIs.
+- Use pure enums when the enum is only used for type discrimination.
+- Enums can implement interfaces and use traits (without properties).
+
+### Readonly properties and classes
+
+```php
+readonly class UserDTO {
+    public function __construct(
+        public string $name,
+        public string $email,
+        public int $age,
+    ) {}
+}
+```
+
+- Use `readonly` for immutable data transfer objects and value objects.
+- Readonly properties can only be initialized once (in constructor or declaration).
+- Readonly classes make all properties implicitly readonly.
+
+### Union and intersection types
+
+```php
+function process(string|Stringable $input): int|float { /* ... */ }
+
+function handle(Countable&Iterator $collection): void { /* ... */ }
+```
+
+- Union types (`A|B`): value can be any of the listed types.
+- Intersection types (`A&B`): value must satisfy all listed types. Useful for requiring multiple interfaces.
+- DNF types (PHP 8.2+): combine union and intersection: `(A&B)|C`.
+
+## PHPStan configuration
+
+### Recommended `phpstan.neon`
+
+```neon
+parameters:
+    level: 8
+    paths:
+        - src
+        - tests
+    excludePaths:
+        - src/legacy/*
+    checkGenericClassInNonGenericObjectType: true
+    treatPhpDocTypesAsCertain: false
+    reportUnmatchedIgnoredErrors: true
+```
+
+- Start at level 5 for legacy codebases, target level 8+ for new code.
+- Use baseline file (`phpstan-baseline.neon`) to track pre-existing errors without blocking CI.
+- Run `phpstan analyze` in CI on every PR. Block merge on new errors.
+
+### PHPStan generics
+
+```php
+/**
+ * @template T
+ * @param class-string<T> $className
+ * @return T
+ */
+function create(string $className): object { /* ... */ }
+```
+
+- Use `@template` annotations for generic types until PHP has native generics.
+- Annotate collections: `@var array<string, User>` instead of `@var array`.
+
+## Composer security audit
+
+### CI pipeline
+
+```yaml
+steps:
+  - run: composer install --no-dev --prefer-dist
+  - run: composer audit --format=json
+  - run: composer outdated --direct --format=json
+```
+
+- `composer audit` checks installed packages against known vulnerabilities (Packagist advisory database).
+- Run on every CI build. Block deploys on critical/high severity findings.
+- `composer outdated --direct` shows only direct dependency updates needed.
+
+### Lock file hygiene
+
+- Always commit `composer.lock` for applications. Never commit it for libraries.
+- Run `composer validate --strict` in CI to catch manifest issues.
+- Update dependencies in small batches with test verification between updates.
+- Pin PHP version requirement in `composer.json`: `"php": ">=8.4 <8.5"`.
+
+## Error pattern: typed results
+
+```php
+readonly class Result {
+    private function __construct(
+        public readonly bool $ok,
+        public readonly mixed $value = null,
+        public readonly ?string $error = null,
+    ) {}
+
+    public static function success(mixed $value): self {
+        return new self(ok: true, value: $value);
+    }
+
+    public static function failure(string $error): self {
+        return new self(ok: false, error: $error);
+    }
+}
+```
+
+- Use result objects for expected failures (validation, not-found) instead of exceptions.
+- Exceptions remain for truly exceptional conditions (database down, file system errors).
+- This pattern works well with PHPStan generics: `Result<User>`.

package/workflows/skills/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/skills/playwright-e2e/SKILL.md

@@ -0,0 +1,66 @@
+---
+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: "1.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 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.
+
+## 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.
+
+### 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, or flake triage. |
+
+## 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"

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

@@ -0,0 +1,52 @@
+# 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.