@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/performance-profiling/SKILL.md

@@ -1,143 +1,90 @@
 ---
 name: performance-profiling
-description: Performance profiling principles. Measurement, analysis, and optimization techniques.
-allowed-tools: Read, Glob, Grep, Bash
+description: "Use when measuring, analyzing, and optimizing application performance with Core Web Vitals, bundle analysis, runtime profiling, and lighthouse audits."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 
 # Performance Profiling
 
-> Measure, analyze, optimize - in that order.
+## Purpose
 
-## 🔧 Runtime Scripts
+Use when measuring, analyzing, and optimizing application performance with Core Web Vitals, bundle analysis, runtime profiling, and lighthouse audits.
 
-**Execute these for automated profiling:**
+## When to Use
 
-| Script | Purpose | Usage |
-|--------|---------|-------|
-| `scripts/lighthouse_audit.py` | Lighthouse performance audit | `python scripts/lighthouse_audit.py https://example.com` |
+- Measuring and improving Core Web Vitals (LCP, INP, CLS).
+- Analyzing bundle size, finding large dependencies, and code splitting.
+- Profiling runtime performance in browser Performance or Memory tabs.
+- Diagnosing performance bottlenecks (slow API, large payload, memory leak, layout thrash).
+- Planning performance optimization with measurement-first discipline.
 
----
-
-## 1. Core Web Vitals
-
-### Targets
-
-| Metric | Good | Poor | Measures |
-|--------|------|------|----------|
-| **LCP** | < 2.5s | > 4.0s | Loading |
-| **INP** | < 200ms | > 500ms | Interactivity |
-| **CLS** | < 0.1 | > 0.25 | Stability |
-
-### When to Measure
-
-| Stage | Tool |
-|-------|------|
-| Development | Local Lighthouse |
-| CI/CD | Lighthouse CI |
-| Production | RUM (Real User Monitoring) |
-
----
-
-## 2. Profiling Workflow
-
-### The 4-Step Process
-
-```
-1. BASELINE → Measure current state
-2. IDENTIFY → Find the bottleneck
-3. FIX → Make targeted change
-4. VALIDATE → Confirm improvement
-```
-
-### Profiling Tool Selection
+## Instructions
 
-| Problem | Tool |
-|---------|------|
-| Page load | Lighthouse |
-| Bundle size | Bundle analyzer |
-| Runtime | DevTools Performance |
-| Memory | DevTools Memory |
-| Network | DevTools Network |
+1. Baseline — measure current performance with Lighthouse, WebPageTest, or browser DevTools.
+2. Identify — find the biggest bottleneck using profiling data, not assumptions.
+3. Fix — apply targeted optimization for the measured bottleneck.
+4. Validate — re-measure to confirm improvement and check for regressions.
 
----
-
-## 3. Bundle Analysis
-
-### What to Look For
-
-| Issue | Indicator |
-|-------|-----------|
-| Large dependencies | Top of bundle |
-| Duplicate code | Multiple chunks |
-| Unused code | Low coverage |
-| Missing splits | Single large chunk |
-
-### Optimization Actions
-
-| Finding | Action |
-|---------|--------|
-| Big library | Import specific modules |
-| Duplicate deps | Dedupe, update versions |
-| Route in main | Code split |
-| Unused exports | Tree shake |
+### Core Web Vitals targets
 
----
-
-## 4. Runtime Profiling
+| Metric | Good    | Needs Improvement | Poor    |
+| ------ | ------- | ----------------- | ------- |
+| LCP    | < 2.5s  | 2.5s – 4.0s       | > 4.0s  |
+| INP    | < 200ms | 200ms – 500ms     | > 500ms |
+| CLS    | < 0.1   | 0.1 – 0.25        | > 0.25  |
 
-### Performance Tab Analysis
+### Baseline standards
 
-| Pattern | Meaning |
-|---------|---------|
-| Long tasks (>50ms) | UI blocking |
-| Many small tasks | Possible batching opportunity |
-| Layout/paint | Rendering bottleneck |
-| Script | JavaScript execution |
+- Always measure before optimizing — intuition is unreliable for performance.
+- Use real user metrics (RUM) alongside synthetic benchmarks.
+- Profile on representative hardware, not just developer machines.
+- Address the largest bottleneck first for maximum impact.
+- Verify optimizations don't introduce regressions elsewhere.
 
-### Memory Tab Analysis
+### Quick wins priority
 
-| Pattern | Meaning |
-|---------|---------|
-| Growing heap | Possible leak |
-| Large retained | Check references |
-| Detached DOM | Not cleaned up |
+| Priority | Action                           | Typical Impact            |
+| -------- | -------------------------------- | ------------------------- |
+| 1        | Enable compression (gzip/brotli) | 60-80% transfer reduction |
+| 2        | Lazy load below-fold images      | LCP improvement           |
+| 3        | Code split routes                | Initial load reduction    |
+| 4        | Set proper cache headers         | Repeat visit speed        |
+| 5        | Optimize images (WebP/AVIF)      | Transfer size reduction   |
 
----
+### Common bottlenecks by symptom
 
-## 5. Common Bottlenecks
+| Symptom           | Likely Cause                            | Investigation                      |
+| ----------------- | --------------------------------------- | ---------------------------------- |
+| Slow initial load | Large bundle, render-blocking resources | Bundle analysis, waterfall         |
+| Janky scrolling   | Layout thrash, paint storms             | Performance tab, layers panel      |
+| Memory growth     | Detached DOM, event listener leaks      | Memory tab, heap snapshots         |
+| Slow interaction  | Long tasks, main thread blocking        | Performance tab, long task markers |
 
-### By Symptom
+### Constraints
 
-| Symptom | Likely Cause |
-|---------|--------------|
-| Slow initial load | Large JS, render blocking |
-| Slow interactions | Heavy event handlers |
-| Jank during scroll | Layout thrashing |
-| Growing memory | Leaks, retained refs |
+- Never optimize without measuring first.
+- Never assume a change improved performance — always validate with data.
+- Never sacrifice correctness for performance.
+- Avoid premature optimization of code paths that aren't bottlenecks.
 
----
+## Output Format
 
-## 6. Quick Win Priorities
+Provide measurement data, identified bottlenecks with evidence, optimization recommendations, and before/after comparisons.
 
-| Priority | Action | Impact |
-|----------|--------|--------|
-| 1 | Enable compression | High |
-| 2 | Lazy load images | High |
-| 3 | Code split routes | High |
-| 4 | Cache static assets | Medium |
-| 5 | Optimize images | Medium |
+## References
 
----
+No reference files for this skill right now.
 
-## 7. Anti-Patterns
+## Scripts
 
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Guess at problems | Profile first |
-| Micro-optimize | Fix biggest issue |
-| Optimize early | Optimize when needed |
-| Ignore real users | Use RUM data |
+No helper scripts are required for this skill right now.
 
----
+## Examples
 
-> **Remember:** The fastest code is code that doesn't run. Remove before optimizing.
+- "Profile and optimize the Core Web Vitals for our landing page"
+- "Analyze our bundle and recommend code splitting strategy"
+- "Find and fix the memory leak in our real-time dashboard"

package/workflows/powers/php-pro/POWER.md

@@ -0,0 +1,116 @@
+````markdown
+---
+inclusion: manual
+name: php-pro
+description: "Use for modern PHP 8.4-era backend and application engineering with strict typing, framework-aware architecture, testing, and operational safety."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "2.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# PHP Pro
+
+## Purpose
+
+Use for modern PHP 8.4-era backend and application engineering with strict typing, framework-aware architecture, testing, and operational safety.
+
+## When to Use
+
+- Building or refactoring PHP services and applications.
+- Tightening typing, dependency boundaries, and package hygiene.
+- Improving request handling, background jobs, and test structure.
+
+## Instructions
+
+1. Confirm runtime, framework, and PHP version baseline.
+2. Enable strict typing and explicit contracts at module boundaries.
+3. Keep service, controller, and persistence responsibilities separate.
+4. Prefer deterministic Composer and test workflows.
+5. Validate with targeted tests and static analysis where available.
+
+### Baseline standards
+
+- Add `declare(strict_types=1);` to every PHP file. No exceptions.
+- Use typed properties, parameter types, and return types on all public methods.
+- Run PHPStan or Psalm at level 8+ in CI. Treat analysis failures as build failures.
+- Use PHP CS Fixer or PHP_CodeSniffer for consistent formatting.
+- Pin Composer dependencies to exact versions in `composer.lock`. Commit the lock file.
+
+### Type system
+
+- Use union types (`string|int`), intersection types (`Countable&Iterator`), and `never` return type where they add clarity.
+- Use enums (backed or pure) instead of string/int constants for fixed value sets.
+- Use readonly properties and readonly classes for immutable data transfer objects.
+- Prefer named arguments for functions with many optional parameters.
+- Use `null` as a return type only when null is a meaningful domain value — prefer exceptions or result objects for errors.
+
+### Architecture patterns
+
+- Separate request handling (controllers) from business logic (services) from persistence (repositories).
+- Use dependency injection (constructor injection preferred) — avoid `new` inside business logic.
+- Keep controllers thin: validate input, call service, return response. No business logic in controllers.
+- Use value objects for domain concepts (Money, Email, UserId) instead of primitive types.
+- Use interfaces at module boundaries. Concrete implementations are internal details.
+
+### Error handling
+
+- Use specific exception classes per failure domain (e.g., `UserNotFoundException`, `ValidationException`).
+- Catch exceptions at the boundary layer (controller, middleware) — not inside business logic unless recovery is possible.
+- Never catch `\Exception` or `\Throwable` silently. At minimum, log the exception.
+- Use result objects or typed return values instead of exceptions for expected failure paths (validation, not-found).
+
+### Testing
+
+- Use PHPUnit for unit and integration tests. Use Pest for more readable test syntax when the team prefers it.
+- Mock external dependencies (HTTP clients, databases, file systems) — test business logic in isolation.
+- Use data providers for parameterized tests instead of copy-paste test methods.
+- Run tests in CI with code coverage reporting. Target meaningful coverage, not 100%.
+- Use fixtures and factories for test data — never rely on production database state.
+
+### Composer and dependencies
+
+- Run `composer audit` in CI to catch known vulnerabilities.
+- Use `composer outdated` to identify stale dependencies. Update regularly.
+- Prefer well-maintained packages with active security patch records.
+- Use autoloading via `composer.json` PSR-4 — never use `require`/`include` for class loading.
+
+### Performance
+
+- Use OPcache in production with preloading for frequently used classes.
+- Profile with Xdebug or Blackfire before optimizing. Measure, don't guess.
+- Use connection pooling (Swoole, FrankenPHP, or external proxy) for high-concurrency workloads.
+- Cache expensive computations and database queries — invalidate on writes.
+
+### Constraints
+
+- Avoid `mixed` type as a lazy escape — use proper union types or generics (via PHPStan/Psalm).
+- Avoid `@` error suppression operator — handle errors explicitly.
+- Avoid global functions or static state for business logic — makes testing impossible.
+- Avoid concatenating SQL strings — use prepared statements or query builders.
+- Avoid storing sensitive data in plain-text config files — use environment variables or vault.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+| File                                          | Load when                                                                                                                 |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `references/php84-strict-typing-checklist.md` | Strict typing migration, enum patterns, readonly properties, PHPStan configuration, or Composer security audit is needed. |
+| `references/modern-php-features.md`           | You need enums, fibers, readonly classes, match expressions, named args, or first-class callable syntax.                  |
+| `references/testing-and-static-analysis.md`   | You need PHPUnit/Pest setup, data providers, mocking, PHPStan/Psalm config, or CI test pipeline patterns.                 |
+| `references/architecture-and-di.md`           | You need DI container patterns, service layers, repository design, or value object implementations.                       |
+| `references/performance-and-deployment.md`    | You need OPcache tuning, preloading, connection pooling, profiling with Xdebug/Blackfire, or FrankenPHP/Swoole setup.     |
+
+## 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 php pro best practices in this project"
+- "Review my php pro implementation for issues"
+````

package/workflows/powers/php-pro/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: php-pro
+description: "Use for modern PHP 8.4-era backend and application engineering with strict typing, framework-aware architecture, testing, and operational safety."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "2.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# PHP Pro
+
+## Purpose
+
+Use for modern PHP 8.4-era backend and application engineering with strict typing, framework-aware architecture, testing, and operational safety.
+
+## When to Use
+
+- Building or refactoring PHP services and applications.
+- Tightening typing, dependency boundaries, and package hygiene.
+- Improving request handling, background jobs, and test structure.
+
+## Instructions
+
+1. Confirm runtime, framework, and PHP version baseline.
+2. Enable strict typing and explicit contracts at module boundaries.
+3. Keep service, controller, and persistence responsibilities separate.
+4. Prefer deterministic Composer and test workflows.
+5. Validate with targeted tests and static analysis where available.
+
+### Baseline standards
+
+- Add `declare(strict_types=1);` to every PHP file. No exceptions.
+- Use typed properties, parameter types, and return types on all public methods.
+- Run PHPStan or Psalm at level 8+ in CI. Treat analysis failures as build failures.
+- Use PHP CS Fixer or PHP_CodeSniffer for consistent formatting.
+- Pin Composer dependencies to exact versions in `composer.lock`. Commit the lock file.
+
+### Type system
+
+- Use union types (`string|int`), intersection types (`Countable&Iterator`), and `never` return type where they add clarity.
+- Use enums (backed or pure) instead of string/int constants for fixed value sets.
+- Use readonly properties and readonly classes for immutable data transfer objects.
+- Prefer named arguments for functions with many optional parameters.
+- Use `null` as a return type only when null is a meaningful domain value — prefer exceptions or result objects for errors.
+
+### Architecture patterns
+
+- Separate request handling (controllers) from business logic (services) from persistence (repositories).
+- Use dependency injection (constructor injection preferred) — avoid `new` inside business logic.
+- Keep controllers thin: validate input, call service, return response. No business logic in controllers.
+- Use value objects for domain concepts (Money, Email, UserId) instead of primitive types.
+- Use interfaces at module boundaries. Concrete implementations are internal details.
+
+### Error handling
+
+- Use specific exception classes per failure domain (e.g., `UserNotFoundException`, `ValidationException`).
+- Catch exceptions at the boundary layer (controller, middleware) — not inside business logic unless recovery is possible.
+- Never catch `\Exception` or `\Throwable` silently. At minimum, log the exception.
+- Use result objects or typed return values instead of exceptions for expected failure paths (validation, not-found).
+
+### Testing
+
+- Use PHPUnit for unit and integration tests. Use Pest for more readable test syntax when the team prefers it.
+- Mock external dependencies (HTTP clients, databases, file systems) — test business logic in isolation.
+- Use data providers for parameterized tests instead of copy-paste test methods.
+- Run tests in CI with code coverage reporting. Target meaningful coverage, not 100%.
+- Use fixtures and factories for test data — never rely on production database state.
+
+### Composer and dependencies
+
+- Run `composer audit` in CI to catch known vulnerabilities.
+- Use `composer outdated` to identify stale dependencies. Update regularly.
+- Prefer well-maintained packages with active security patch records.
+- Use autoloading via `composer.json` PSR-4 — never use `require`/`include` for class loading.
+
+### Performance
+
+- Use OPcache in production with preloading for frequently used classes.
+- Profile with Xdebug or Blackfire before optimizing. Measure, don't guess.
+- Use connection pooling (Swoole, FrankenPHP, or external proxy) for high-concurrency workloads.
+- Cache expensive computations and database queries — invalidate on writes.
+
+### Constraints
+
+- Avoid `mixed` type as a lazy escape — use proper union types or generics (via PHPStan/Psalm).
+- Avoid `@` error suppression operator — handle errors explicitly.
+- Avoid global functions or static state for business logic — makes testing impossible.
+- Avoid concatenating SQL strings — use prepared statements or query builders.
+- Avoid storing sensitive data in plain-text config files — use environment variables or vault.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+| File                                          | Load when                                                                                                                 |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `references/php84-strict-typing-checklist.md` | Strict typing migration, enum patterns, readonly properties, PHPStan configuration, or Composer security audit is needed. |
+| `references/modern-php-features.md`           | You need enums, fibers, readonly classes, match expressions, named args, or first-class callable syntax.                  |
+| `references/testing-and-static-analysis.md`   | You need PHPUnit/Pest setup, data providers, mocking, PHPStan/Psalm config, or CI test pipeline patterns.                 |
+| `references/architecture-and-di.md`           | You need DI container patterns, service layers, repository design, or value object implementations.                       |
+| `references/performance-and-deployment.md`    | You need OPcache tuning, preloading, connection pooling, profiling with Xdebug/Blackfire, or FrankenPHP/Swoole setup.     |
+
+## 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 php pro best practices in this project"
+- "Review my php pro implementation for issues"

package/workflows/powers/php-pro/references/architecture-and-di.md

@@ -0,0 +1,239 @@
+# Architecture and Dependency Injection
+
+## Service Layer Pattern
+
+```php
+declare(strict_types=1);
+
+// Controller — thin, delegates to service
+final class OrderController
+{
+    public function __construct(
+        private readonly OrderService $orderService,
+    ) {}
+
+    public function create(Request $request): JsonResponse
+    {
+        $dto = CreateOrderDto::fromRequest($request);
+        $order = $this->orderService->create($dto);
+        return new JsonResponse(OrderResource::from($order), 201);
+    }
+}
+
+// Service — business logic, orchestrates domain objects
+final class OrderService
+{
+    public function __construct(
+        private readonly OrderRepository $orderRepository,
+        private readonly PricingService $pricingService,
+        private readonly EventDispatcher $events,
+    ) {}
+
+    public function create(CreateOrderDto $dto): Order
+    {
+        $price = $this->pricingService->calculate($dto->items);
+        $order = Order::create(
+            customerId: $dto->customerId,
+            items: $dto->items,
+            total: $price,
+        );
+
+        $this->orderRepository->save($order);
+        $this->events->dispatch(new OrderCreated($order));
+
+        return $order;
+    }
+}
+
+// Repository interface — persistence contract
+interface OrderRepository
+{
+    public function findById(int $id): ?Order;
+    public function save(Order $order): void;
+    /** @return list<Order> */
+    public function findByCustomer(int $customerId): array;
+}
+```
+
+## Value Objects
+
+```php
+// Type-safe wrappers with validation
+readonly class Email
+{
+    public function __construct(
+        public string $value,
+    ) {
+        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+            throw new \InvalidArgumentException("Invalid email: $value");
+        }
+    }
+
+    public function domain(): string
+    {
+        return substr($this->value, strpos($this->value, '@') + 1);
+    }
+
+    public function equals(self $other): bool
+    {
+        return strtolower($this->value) === strtolower($other->value);
+    }
+}
+
+readonly class Money
+{
+    public function __construct(
+        public int $amount,     // store in cents
+        public string $currency,
+    ) {
+        if ($amount < 0) throw new \DomainException('Amount cannot be negative');
+    }
+
+    public function add(self $other): self
+    {
+        if ($this->currency !== $other->currency) {
+            throw new \DomainException('Cannot add different currencies');
+        }
+        return new self($this->amount + $other->amount, $this->currency);
+    }
+
+    public function format(): string
+    {
+        return number_format($this->amount / 100, 2) . ' ' . $this->currency;
+    }
+}
+```
+
+## DI Container Patterns
+
+```php
+// Constructor injection (preferred)
+final class NotificationService
+{
+    public function __construct(
+        private readonly MailerInterface $mailer,
+        private readonly LoggerInterface $logger,
+        private readonly string $fromAddress, // primitive config via container
+    ) {}
+}
+
+// Interface binding (Laravel example)
+// AppServiceProvider
+$this->app->bind(OrderRepository::class, EloquentOrderRepository::class);
+$this->app->bind(MailerInterface::class, SmtpMailer::class);
+
+// Singleton binding for shared instances
+$this->app->singleton(CacheInterface::class, RedisCache::class);
+
+// Factory binding for complex construction
+$this->app->bind(PaymentGateway::class, function ($app) {
+    return new StripeGateway(
+        apiKey: config('services.stripe.secret'),
+        logger: $app->make(LoggerInterface::class),
+    );
+});
+
+// Symfony service configuration (services.yaml)
+// services:
+//     App\Service\OrderService:
+//         arguments:
+//             $fromAddress: '%env(MAIL_FROM)%'
+//     App\Repository\OrderRepository: '@App\Infrastructure\EloquentOrderRepository'
+```
+
+## DTOs and Request Validation
+
+```php
+// DTO with factory method from request
+readonly class CreateOrderDto
+{
+    /** @param list<OrderItemDto> $items */
+    public function __construct(
+        public int $customerId,
+        public array $items,
+        public ?string $notes = null,
+    ) {}
+
+    public static function fromRequest(Request $request): self
+    {
+        $validated = $request->validate([
+            'customer_id' => 'required|integer|exists:customers,id',
+            'items' => 'required|array|min:1',
+            'items.*.product_id' => 'required|integer|exists:products,id',
+            'items.*.quantity' => 'required|integer|min:1',
+            'notes' => 'nullable|string|max:500',
+        ]);
+
+        return new self(
+            customerId: $validated['customer_id'],
+            items: array_map(
+                fn (array $item) => new OrderItemDto(
+                    productId: $item['product_id'],
+                    quantity: $item['quantity'],
+                ),
+                $validated['items'],
+            ),
+            notes: $validated['notes'] ?? null,
+        );
+    }
+}
+```
+
+## Result Objects for Expected Failures
+
+```php
+// Instead of exceptions for validation/not-found
+readonly class Result
+{
+    private function __construct(
+        public bool $success,
+        public mixed $value = null,
+        public ?string $error = null,
+    ) {}
+
+    public static function ok(mixed $value): self
+    {
+        return new self(success: true, value: $value);
+    }
+
+    public static function fail(string $error): self
+    {
+        return new self(success: false, error: $error);
+    }
+}
+
+// Usage in service
+public function transfer(int $fromId, int $toId, Money $amount): Result
+{
+    $from = $this->accountRepo->findById($fromId);
+    if ($from === null) return Result::fail('Source account not found');
+
+    if ($from->balance->amount < $amount->amount) {
+        return Result::fail('Insufficient funds');
+    }
+
+    // ... perform transfer
+    return Result::ok($transaction);
+}
+```
+
+## Middleware Pattern
+
+```php
+// Middleware for cross-cutting concerns
+final class RateLimitMiddleware
+{
+    public function __construct(
+        private readonly RateLimiter $limiter,
+    ) {}
+
+    public function handle(Request $request, \Closure $next): Response
+    {
+        $key = $request->ip();
+        if (!$this->limiter->attempt($key, maxAttempts: 60, decayMinutes: 1)) {
+            return new JsonResponse(['error' => 'Too many requests'], 429);
+        }
+        return $next($request);
+    }
+}
+```