@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/php-best-practices/references/type-system.md

@@ -1,307 +0,0 @@
-# PHP Type System Reference
-
-## Strict Types Enforcement
-
-### declare(strict_types=1)
-
-Without strict types, PHP silently coerces arguments:
-
-```php
-<?php
-// Without strict_types — silent coercion
-function addInts(int $a, int $b): int { return $a + $b; }
-echo addInts("3", "4"); // 7 — string silently converted to int
-echo addInts("3.9", "4"); // 7 — decimal part silently truncated!
-
-// With strict_types — TypeError thrown
-<?php declare(strict_types=1);
-echo addInts("3", "4"); // TypeError: must be int, string given
-```
-
-Strict types applies to the **calling file**, not the declaring file. Every file must have the declaration.
-
-### Automation
-
-```json
-// PHP CS Fixer configuration
-{
-    "rules": {
-        "declare_strict_types": true
-    }
-}
-```
-
-## Type Declaration Reference
-
-### Scalar types
-
-| Type | Description | Example |
-| --- | --- | --- |
-| `int` | Integer | `function count(): int` |
-| `float` | Floating point | `function average(): float` |
-| `string` | String | `function name(): string` |
-| `bool` | Boolean | `function isActive(): bool` |
-
-### Special types
-
-| Type | Description | Use when |
-| --- | --- | --- |
-| `void` | No return value | Side-effect methods |
-| `never` | Never returns (throws/exits) | Error handlers, redirects |
-| `null` | Null value | Standalone: `function reset(): null` |
-| `mixed` | Any type | Avoid — defeats analysis |
-| `self` | Current class | Return type in fluent interfaces |
-| `static` | Late static bound | Factory methods in inheritance |
-| `parent` | Parent class | Overridden method delegation |
-
-### Compound types
-
-```php
-<?php declare(strict_types=1);
-
-// Union type — either type
-function parseId(string|int $id): string { /* ... */ }
-
-// Intersection type — must satisfy both
-function processCollection(Countable&Iterator $items): void { /* ... */ }
-
-// Nullable — shorthand for Type|null
-function findUser(string $id): ?User { /* ... */ }
-
-// DNF type (PHP 8.2+)
-function handle((Stringable&Countable)|string $input): string { /* ... */ }
-```
-
-## Readonly Properties and Classes
-
-### Readonly properties
-
-```php
-<?php declare(strict_types=1);
-
-class UserId
-{
-    public readonly string $value;
-
-    public function __construct(string $value)
-    {
-        if (trim($value) === '') {
-            throw new \InvalidArgumentException('UserId cannot be empty');
-        }
-        $this->value = $value;
-        // After construction, $this->value cannot be reassigned
-    }
-}
-```
-
-### Constructor promotion with readonly
-
-```php
-<?php declare(strict_types=1);
-
-readonly class Coordinate
-{
-    public function __construct(
-        public float $latitude,
-        public float $longitude,
-    ) {
-        if ($latitude < -90 || $latitude > 90) {
-            throw new \RangeException("Invalid latitude: {$latitude}");
-        }
-        if ($longitude < -180 || $longitude > 180) {
-            throw new \RangeException("Invalid longitude: {$longitude}");
-        }
-    }
-
-    public function distanceTo(self $other): float
-    {
-        // Haversine formula
-        $dlat = deg2rad($other->latitude - $this->latitude);
-        $dlon = deg2rad($other->longitude - $this->longitude);
-        $a = sin($dlat / 2) ** 2 +
-             cos(deg2rad($this->latitude)) * cos(deg2rad($other->latitude)) *
-             sin($dlon / 2) ** 2;
-        return 6371 * 2 * atan2(sqrt($a), sqrt(1 - $a));
-    }
-}
-```
-
-### Readonly class rules
-
-- All properties are implicitly readonly.
-- Cannot have untyped properties (all must have type declarations).
-- Cannot use `static` properties.
-- Dynamic properties are forbidden.
-
-## PHPStan Generics
-
-PHP's native type system lacks generics. PHPStan fills the gap with annotations.
-
-### Generic classes
-
-```php
-<?php declare(strict_types=1);
-
-/**
- * @template T
- */
-final class TypedCollection
-{
-    /** @var list<T> */
-    private array $items = [];
-
-    /**
-     * @param T $item
-     */
-    public function add(mixed $item): void
-    {
-        $this->items[] = $item;
-    }
-
-    /**
-     * @return T
-     * @throws \UnderflowException
-     */
-    public function first(): mixed
-    {
-        if ($this->items === []) {
-            throw new \UnderflowException('Collection is empty');
-        }
-        return $this->items[0];
-    }
-
-    /**
-     * @template U
-     * @param callable(T): U $mapper
-     * @return TypedCollection<U>
-     */
-    public function map(callable $mapper): self
-    {
-        $result = new self();
-        foreach ($this->items as $item) {
-            $result->add($mapper($item));
-        }
-        return $result;
-    }
-}
-
-// Usage — PHPStan tracks the type parameter
-/** @var TypedCollection<User> */
-$users = new TypedCollection();
-$users->add(new User('Alice')); // OK
-$users->add(new Order());       // PHPStan error: Order is not User
-
-$names = $users->map(fn(User $u) => $u->name); // TypedCollection<string>
-```
-
-### Generic interfaces
-
-```php
-<?php declare(strict_types=1);
-
-/**
- * @template TEntity of object
- * @template TId
- */
-interface RepositoryInterface
-{
-    /** @param TId $id */
-    public function findById(mixed $id): ?object;
-
-    /** @param TEntity $entity */
-    public function save(object $entity): void;
-}
-
-/**
- * @implements RepositoryInterface<User, UserId>
- */
-class UserRepository implements RepositoryInterface
-{
-    public function findById(mixed $id): ?User { /* ... */ }
-    public function save(object $entity): void { /* ... */ }
-}
-```
-
-## PHPStan Configuration
-
-### Level descriptions
-
-| Level | Checks |
-| --- | --- |
-| 0 | Basic checks, unknown classes, wrong arguments |
-| 1 | Possibly undefined variables, unknown methods on `$this` |
-| 2-3 | Unknown methods on all expressions, return types |
-| 4-5 | Dead code, always-true/false conditions |
-| 6 | Missing typehints |
-| 7 | Union types resolved |
-| 8 | Method calls on nullable types |
-| 9 (max) | Mixed type restrictions |
-
-### Recommended configuration
-
-```neon
-# phpstan.neon.dist
-parameters:
-    level: 9
-    paths:
-        - src
-    excludePaths:
-        - src/Legacy/*
-    tmpDir: .phpstan-cache
-    checkMissingIterableValueType: true
-    checkGenericClassInNonGenericObjectType: true
-    reportUnmatchedIgnoredErrors: true
-```
-
-### Baseline for legacy code
-
-```bash
-# Generate baseline of existing errors to fix incrementally
-vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon
-
-# Include baseline in config
-includes:
-    - phpstan-baseline.neon
-```
-
-## Type Narrowing
-
-### instanceof narrowing
-
-```php
-<?php declare(strict_types=1);
-
-function processPayment(PaymentMethod $method): PaymentResult
-{
-    return match (true) {
-        $method instanceof CreditCard => processCreditCard($method),
-        $method instanceof BankTransfer => processBankTransfer($method),
-        $method instanceof DigitalWallet => processDigitalWallet($method),
-        default => throw new \UnexpectedValueException(
-            'Unknown payment method: ' . $method::class
-        ),
-    };
-}
-```
-
-### Assert functions for PHPStan
-
-```php
-<?php declare(strict_types=1);
-
-/**
- * @phpstan-assert !null $value
- * @throws \RuntimeException
- */
-function assertNotNull(mixed $value, string $message = ''): void
-{
-    if ($value === null) {
-        throw new \RuntimeException($message ?: 'Unexpected null value');
-    }
-}
-
-$user = $repository->findById($id);
-assertNotNull($user, "User {$id} not found");
-// PHPStan knows $user is non-null after this line
-echo $user->name;
-```

package/workflows/skills/playwright-persistent-browser/SKILL.md

@@ -1,79 +0,0 @@
----
-name: playwright-persistent-browser
-description: "Use when implementing persistent browser sessions in Playwright: long-running browser contexts, cookie and session persistence, authentication state serialization, multi-tab coordination, or debugging browser lifecycle issues."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: "Claude Code, Codex, GitHub Copilot"
----
-
-# Playwright Persistent Browser
-
-## Purpose
-
-You are a specialist for building and maintaining persistent browser sessions in Playwright. Standard Playwright tests create and destroy browser contexts for each test, which is correct for isolation. But some scenarios require long-lived sessions — scraping workflows, monitoring dashboards, authenticated crawls, or multi-step workflows where context must survive across operations.
-
-This skill exists because persistent browser management introduces failure modes that ephemeral tests never encounter: cookie expiration, session invalidation, memory leaks, stale DOM references, and context corruption. Handling these requires specific patterns that are not covered by standard test-writing skills.
-
-## When to Use
-
-- Building scraping or monitoring tools that maintain browser sessions for hours or days
-- Implementing authentication state that persists across test runs or workflow steps
-- Managing multi-tab browser sessions where tabs share cookies and storage
-- Serializing and restoring browser state (cookies, localStorage, sessionStorage)
-- Debugging memory leaks or performance degradation in long-running browser instances
-- Building browser-based automation workflows (not just tests) that need session continuity
-
-## Instructions
-
-1. **Clarify the session lifecycle** — Determine how long the browser session must live (minutes, hours, days) and what triggers session start and end, because the persistence strategy differs dramatically between a 5-minute auth reuse and a 24-hour monitoring session.
-
-2. **Choose the persistence layer** — Decide between `storageState` (cookies + localStorage), full browser context persistence, or external session stores. Load `references/state-management.md` for the decision matrix, because choosing the wrong layer wastes effort on problems that do not exist for your use case.
-
-3. **Configure browser context creation** — Set up the browser context with appropriate options (viewport, locale, permissions, proxy) and document every option, because persistent contexts amplify misconfiguration — a wrong viewport set once affects every subsequent operation.
-
-4. **Implement authentication persistence** — Load `references/authentication.md` and implement the auth flow once, then serialize the state for reuse. This matters because repeating login in every workflow step wastes time and triggers rate limits or account lockouts.
-
-5. **Serialize session state** — Save cookies, localStorage, and sessionStorage to a JSON file or external store after authentication completes. Use `browserContext.storageState()` for the standard case, because manual cookie extraction misses HttpOnly cookies that the browser manages internally.
-
-6. **Restore session state** — On subsequent runs, create the browser context with the saved `storageState` and verify the session is still valid before proceeding, because expired tokens in a restored state produce confusing failures that look like application bugs.
-
-7. **Handle session expiration** — Implement a validity check (e.g., hit a `/me` endpoint or check for a login redirect) after restoring state. If the session expired, re-authenticate and re-serialize, because persistent sessions will eventually expire and your automation must recover without human intervention.
-
-8. **Manage multi-tab coordination** — Load `references/browser-contexts.md` for tab management patterns. Tabs within a context share cookies and storage, but each tab has independent navigation state. Coordinate carefully because race conditions between tabs are the most common source of persistent session bugs.
-
-9. **Implement state checkpointing** — For long-running sessions, periodically save state snapshots so that a crash or restart can resume from the last checkpoint rather than starting over. This matters because a 6-hour workflow that crashes at hour 5 with no checkpoint wastes 5 hours of compute.
-
-10. **Configure resource cleanup** — Set up page and context cleanup to prevent memory leaks. Close pages that are no longer needed, clear caches periodically, and monitor memory usage. Load `references/performance.md` because Chromium's memory usage grows without bound if you never close pages.
-
-11. **Add debug instrumentation** — Load `references/debugging.md` and add console log forwarding, request logging, and screenshot-on-error hooks. Persistent sessions are harder to debug than ephemeral tests because the failure context accumulates over time and is not captured by standard test reporters.
-
-12. **Handle browser crashes gracefully** — Implement reconnection logic that detects when the browser process dies and restarts it with the last saved state. Browsers crash — especially long-running ones — and your automation must recover automatically.
-
-13. **Test the persistence layer** — Write tests that serialize state, kill the browser, restore state in a new browser, and verify the session is intact. This proves the persistence works end-to-end, because untested persistence code always has edge cases (missing cookies, expired tokens, corrupted storage).
-
-14. **Configure CI for persistent workflows** — If the persistent session runs in CI, configure longer timeouts, artifact collection for state files, and health checks. Standard CI timeout defaults (10 minutes) will kill long-running sessions.
-
-15. **Document session topology** — Draw a diagram or write a table showing: what state is persisted, where it is stored, how long it lives, and what triggers refresh. Future maintainers need this because persistent session bugs are nearly impossible to diagnose without understanding the state lifecycle.
-
-## Output Format
-
-Deliver:
-
-1. **Session manager module** — TypeScript/JavaScript class that encapsulates browser launch, state serialization, restoration, and cleanup
-2. **Authentication flow** — Login implementation with state export
-3. **State files** — JSON schema for the persisted state, with comments explaining each field
-4. **Recovery logic** — Error handling for expired sessions, browser crashes, and corrupt state
-5. **Configuration** — `playwright.config.ts` or equivalent with persistence-specific settings
-6. **Lifecycle diagram** — Text-based diagram showing session states and transitions
-
-## References
-
-| File | Load when |
-| --- | --- |
-| `references/browser-contexts.md` | Creating or managing browser contexts, multi-tab sessions, or context isolation |
-| `references/state-management.md` | Choosing persistence strategies or serializing/restoring browser state |
-| `references/authentication.md` | Implementing login flows, token management, or auth state reuse |
-| `references/debugging.md` | Debugging long-running sessions, memory leaks, or session corruption |
-| `references/performance.md` | Optimizing memory usage, managing resource cleanup, or monitoring browser health |

package/workflows/skills/playwright-persistent-browser/evals/assertions.md

@@ -1,57 +0,0 @@
-# Assertions Reference — playwright-persistent-browser
-
-## Eval 001: Persistent Authentication Session
-
-### Assertion 1 — storageState API usage
-- **Type**: contains
-- **What**: Output must include `storageState`
-- **Why**: Playwright's `storageState()` method captures cookies (including HttpOnly), localStorage, and origin-scoped storage in a single call. Manual cookie extraction via `context.cookies()` misses HttpOnly cookies, which are the primary session mechanism for most web applications.
-
-### Assertion 2 — State file existence check
-- **Type**: contains
-- **What**: Output must include `existsSync`
-- **Why**: The persistence flow has two branches: fresh login (no saved state) and restoration (saved state exists). Without checking for the state file, the implementation either always logs in (defeating persistence) or always tries to restore (crashes on first run).
-
-### Assertion 3 — Error handling
-- **Type**: contains
-- **What**: Output must include `catch` for error handling
-- **Why**: Persistent sessions introduce failure modes that ephemeral tests do not have: expired tokens, corrupt JSON files, changed cookie domains, revoked sessions. Without error handling, any of these silently produces wrong behavior or crashes.
-
-### Assertion 4 — Accessible locators
-- **Type**: contains
-- **What**: Output must use `getByLabel` for form inputs
-- **Why**: Login forms are the most refactored UI component in any application. Role-based and label-based locators survive redesigns. CSS-based locators break on every login page update.
-
-### Assertion 5 — JSON serialization
-- **Type**: contains
-- **What**: Output must reference `json` for state persistence
-- **Why**: JSON is the standard format for `storageState` output. It is human-readable (debuggable), version-controllable, and parseable without custom deserialization logic.
-
----
-
-## Eval 002: Multi-Tab State Management
-
-### Assertion 1 — Tab creation via newPage
-- **Type**: contains
-- **What**: Output must use `newPage` to create tabs
-- **Why**: `context.newPage()` creates a new tab within the existing browser context. This is the only way to share cookies and storage between tabs. Using `browser.newPage()` creates a new context, which defeats the purpose.
-
-### Assertion 2 — Single context usage
-- **Type**: contains
-- **What**: Output must reference `context` for shared state
-- **Why**: All tabs must share the same browser context for cookie and storage sharing. Multiple contexts would create isolated sessions, making the tabs unable to share authentication state.
-
-### Assertion 3 — Resource cleanup
-- **Type**: contains
-- **What**: Output must include `close` for cleanup
-- **Why**: Long-running multi-tab sessions accumulate memory. Each page retains DOM state, network caches, and JavaScript heap. Without closing unused pages or cycling resources, Chromium's memory usage grows without bound — typically 50-200MB per tab.
-
-### Assertion 4 — Async coordination
-- **Type**: contains
-- **What**: Output must use `async` patterns
-- **Why**: Tabs operate independently and concurrently. Synchronous coordination would serialize tab operations, defeating the purpose of multi-tab architecture. Async patterns (Promise.all, async generators) allow tabs to work in parallel while coordinating at specific sync points.
-
-### Assertion 5 — Multiple page management
-- **Type**: contains
-- **What**: Output must manage multiple `page` references
-- **Why**: Each tab is a separate Playwright Page object with its own navigation state, event listeners, and DOM. The implementation must track which page handles which responsibility to avoid sending commands to the wrong tab.

package/workflows/skills/playwright-persistent-browser/evals/evals.json

@@ -1,78 +0,0 @@
-[
-  {
-    "id": "playwright-persistent-browser-eval-001",
-    "name": "Persistent authentication session with state serialization",
-    "description": "Verifies that the skill produces a correct persistent auth session implementation with state serialization, restoration, and expiration handling.",
-    "input": "Implement a persistent browser session that logs into a web application (email + password form), saves the authentication state to a JSON file, and restores it on subsequent runs. If the saved session has expired, re-authenticate automatically. The app uses HttpOnly cookies for session management.",
-    "assertions": [
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "storageState",
-        "description": "Must use Playwright's storageState API to serialize cookies including HttpOnly cookies that manual extraction would miss"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "existsSync",
-        "description": "Must check for existing state file before deciding whether to perform fresh login or restore saved state"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "catch",
-        "description": "Must include error handling for expired sessions, corrupt state files, or failed restoration attempts"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "getByLabel",
-        "description": "Must use accessible locators for the login form interaction rather than CSS selectors"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "json",
-        "description": "Must serialize state to JSON format for persistence across runs"
-      }
-    ]
-  },
-  {
-    "id": "playwright-persistent-browser-eval-002",
-    "name": "Multi-tab state management with shared context",
-    "description": "Verifies that the skill correctly implements multi-tab browser sessions where tabs share authentication state but maintain independent navigation, with proper cleanup to prevent memory leaks.",
-    "input": "Create a multi-tab Playwright session where 3 tabs share the same authenticated browser context. Tab 1 monitors a dashboard, tab 2 processes a queue of items, and tab 3 collects logs. Tabs share cookies but navigate independently. Include memory management to prevent leaks from long-running tab usage.",
-    "assertions": [
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "newPage",
-        "description": "Must use context.newPage() to create multiple tabs within the same browser context for cookie sharing"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "context",
-        "description": "Must operate within a single browser context so that all tabs share cookies and storage"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "close",
-        "description": "Must include page/resource cleanup logic to prevent memory leaks in long-running sessions"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "async",
-        "description": "Must use async patterns for coordinating independent tab operations without blocking"
-      },
-      {
-        "type": "contains",
-        "target": "output",
-        "value": "page",
-        "description": "Must manage multiple page references with distinct roles (monitor, processor, logger)"
-      }
-    ]
-  }
-]