@cubis/foundry 0.3.83 → 0.3.84

package/workflows/skills/javascript-best-practices/references/testing.md

@@ -1,253 +0,0 @@
-# Testing Reference
-
-## Test Runner Selection
-
-| Runner | Best For | Key Feature |
-| --- | --- | --- |
-| **Vitest** | Most projects, browser + Node | Vite-native, ESM-first, built-in coverage, UI mode |
-| **node:test** | Node-only, zero dependencies | Ships with Node, no install, fast startup |
-| **Deno.test** | Deno projects | Built into runtime, permissions-aware |
-| **Bun test** | Bun projects | Fastest startup, Jest-compatible API |
-
-## Vitest Setup and Configuration
-
-```javascript
-// vitest.config.js
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    globals: false,           // Explicit imports preferred
-    environment: 'node',      // or 'jsdom', 'happy-dom'
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'lcov'],
-      exclude: ['**/*.test.js', '**/test/**'],
-    },
-    testTimeout: 10_000,
-    hookTimeout: 15_000,
-  },
-});
-```
-
-### Writing Tests with Vitest
-
-```javascript
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { fetchUserProfile } from './user-service.js';
-
-describe('fetchUserProfile', () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-    vi.restoreAllMocks();
-  });
-
-  it('returns user data on success', async () => {
-    const mockResponse = { id: '1', name: 'Alice' };
-    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
-      new Response(JSON.stringify(mockResponse), { status: 200 })
-    );
-
-    const user = await fetchUserProfile('1');
-
-    expect(user).toEqual({ id: '1', name: 'Alice' });
-    expect(fetch).toHaveBeenCalledWith(
-      expect.stringContaining('/users/1'),
-      expect.any(Object)
-    );
-  });
-
-  it('throws on HTTP error', async () => {
-    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
-      new Response('Not Found', { status: 404 })
-    );
-
-    await expect(fetchUserProfile('999')).rejects.toThrow('HTTP 404');
-  });
-
-  it('respects abort signal', async () => {
-    const controller = new AbortController();
-    controller.abort();
-
-    await expect(
-      fetchUserProfile('1', { signal: controller.signal })
-    ).rejects.toThrow('aborted');
-  });
-
-  it('retries on transient failure', async () => {
-    const fetchSpy = vi.spyOn(globalThis, 'fetch')
-      .mockResolvedValueOnce(new Response('', { status: 503 }))
-      .mockResolvedValueOnce(new Response('', { status: 503 }))
-      .mockResolvedValueOnce(
-        new Response(JSON.stringify({ id: '1' }), { status: 200 })
-      );
-
-    // Advance timers through retry delays
-    const promise = fetchUserProfile('1');
-    await vi.advanceTimersByTimeAsync(2_000);
-    await vi.advanceTimersByTimeAsync(4_000);
-
-    const result = await promise;
-    expect(result.id).toBe('1');
-    expect(fetchSpy).toHaveBeenCalledTimes(3);
-  });
-});
-```
-
-## Node.js Built-in Test Runner
-
-```javascript
-import { describe, it, mock, before, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { buildUrl } from './url-utils.js';
-
-describe('buildUrl', () => {
-  it('combines base, path, and params', () => {
-    const result = buildUrl('https://api.example.com', '/users', { page: '2' });
-    assert.equal(result, 'https://api.example.com/users?page=2');
-  });
-
-  it('handles empty params', () => {
-    const result = buildUrl('https://api.example.com', '/health');
-    assert.equal(result, 'https://api.example.com/health');
-  });
-
-  it('encodes special characters', () => {
-    const result = buildUrl('https://api.example.com', '/search', {
-      q: 'hello world',
-    });
-    assert.match(result, /q=hello\+world|q=hello%20world/);
-  });
-});
-
-// Run: node --test src/**/*.test.js
-// Coverage: node --test --experimental-test-coverage src/**/*.test.js
-```
-
-## Mocking Strategies
-
-### Mock fetch (Vitest)
-
-```javascript
-// Global fetch mock with type-safe responses
-const mockFetch = (responses) => {
-  let callIndex = 0;
-  return vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
-    const resp = responses[callIndex++];
-    if (resp instanceof Error) throw resp;
-    return new Response(
-      JSON.stringify(resp.body),
-      { status: resp.status ?? 200, headers: resp.headers }
-    );
-  });
-};
-
-// Usage
-mockFetch([
-  { body: { users: [] }, status: 200 },
-  { body: { error: 'rate limited' }, status: 429 },
-]);
-```
-
-### Mock Timers
-
-```javascript
-// Vitest
-vi.useFakeTimers();
-const promise = retryWithBackoff(fn);
-await vi.advanceTimersByTimeAsync(5_000);
-const result = await promise;
-vi.useRealTimers();
-
-// Node.js test runner
-import { mock } from 'node:test';
-mock.timers.enable({ apis: ['setTimeout', 'setInterval'] });
-mock.timers.tick(5_000);
-mock.timers.reset();
-```
-
-### Mock File System
-
-```javascript
-// Use a virtual filesystem instead of mocking fs
-import { vol, fs } from 'memfs';
-
-beforeEach(() => {
-  vol.fromJSON({
-    '/app/config.json': JSON.stringify({ port: 3000 }),
-    '/app/data/users.csv': 'id,name\n1,Alice',
-  });
-});
-
-// Inject the mock fs into your module
-const config = await loadConfig({ fs });
-```
-
-## Testing Async Generators
-
-```javascript
-import { describe, it, expect } from 'vitest';
-
-describe('fetchAllPages', () => {
-  it('yields items from multiple pages', async () => {
-    const items = [];
-    for await (const item of fetchAllPages(mockUrl)) {
-      items.push(item);
-    }
-    expect(items).toHaveLength(30);
-    expect(items[0]).toHaveProperty('id');
-  });
-
-  it('stops on cancellation', async () => {
-    const controller = new AbortController();
-    const items = [];
-
-    for await (const item of fetchAllPages(mockUrl, { signal: controller.signal })) {
-      items.push(item);
-      if (items.length >= 5) controller.abort();
-    }
-    // Should not have fetched all pages
-    expect(items.length).toBeLessThanOrEqual(10); // One page max
-  });
-});
-```
-
-## Snapshot Testing
-
-```javascript
-import { expect, it } from 'vitest';
-
-it('renders the config correctly', () => {
-  const config = generateConfig({ env: 'production', region: 'us-east-1' });
-  expect(config).toMatchSnapshot();
-  // First run: creates .snap file
-  // Subsequent runs: compares against snapshot
-  // Update: vitest --update
-});
-
-// Inline snapshots (stored in the test file)
-it('formats error message', () => {
-  const msg = formatError(new Error('timeout'), '/api/users');
-  expect(msg).toMatchInlineSnapshot(`"Request to /api/users failed: timeout"`);
-});
-```
-
-## Cross-Runtime Test Execution
-
-```json
-{
-  "scripts": {
-    "test": "vitest run",
-    "test:node": "node --test src/**/*.test.js",
-    "test:deno": "deno test src/",
-    "test:bun": "bun test",
-    "test:all": "npm run test && npm run test:deno"
-  }
-}
-```
-
-Keep test utilities in a shared `test-utils.js` file and avoid runtime-specific test APIs in the utilities themselves.

package/workflows/skills/laravel/SKILL.md

@@ -1,66 +0,0 @@
----
-name: laravel
-description: "Use when building Laravel 11+ applications with Eloquent ORM, middleware pipelines, queue-driven jobs, event broadcasting, and API resources for JSON:API-style responses."
-license: MIT
-metadata:
-  author: cubis-foundry
-  version: "3.0"
-compatibility: Claude Code, Codex, GitHub Copilot
----
-
-# Laravel
-
-## Purpose
-
-Use when building Laravel 11+ applications with Eloquent ORM, middleware pipelines, queue-driven jobs, event broadcasting, and API resources for JSON:API-style responses.
-
-## When to Use
-
-- Building or extending Laravel REST APIs with Eloquent-backed resources.
-- Designing middleware stacks, request validation, and authorization gates.
-- Implementing queue-based job processing, event/listener pipelines, or scheduled tasks.
-- Reviewing Laravel code for N+1 queries, mass-assignment safety, and queue reliability.
-
-## Instructions
-
-1. **Confirm the Laravel and PHP baseline first** because version-specific features (e.g., Laravel 11 slim skeleton, PHP 8.2+ enums) determine which patterns are available and which are outdated.
-2. **Define Eloquent models with explicit fillable/guarded arrays and relationship methods** because mass-assignment vulnerabilities and missing relationships are the most common source of data-integrity bugs.
-3. **Use Eloquent API Resources and Resource Collections for all JSON responses** because leaking raw model attributes exposes internal schema details and makes versioning painful.
-4. **Eager-load relationships at the query level with `with()` or `load()`** because N+1 queries silently degrade performance and are hard to catch without tooling.
-5. **Place business logic in dedicated service classes, not in controllers or models** because fat controllers and fat models resist testing and create coupling between HTTP concerns and domain rules.
-6. **Write Form Request classes for all validation instead of inline `$request->validate()`** because Form Requests centralize authorization checks, custom messages, and complex conditional rules in a testable unit.
-7. **Compose middleware for cross-cutting concerns like rate limiting, CORS, and tenant scoping** because middleware keeps controllers focused on happy-path logic and makes policies reusable across routes.
-8. **Dispatch jobs to queues for any work exceeding 200ms wall-clock time** because synchronous heavy work blocks the HTTP response cycle and degrades user-perceived latency.
-9. **Implement retry, backoff, and `failed()` methods on every queued job** because transient failures in mail, payment, and third-party APIs are normal and jobs without retry logic silently drop work.
-10. **Use events and listeners for side effects that should not block the primary action** because decoupling side effects (notifications, audit logs, cache invalidation) makes the primary action easier to test and reason about.
-11. **Register authorization via Policies tied to models, not ad-hoc Gate closures** because Policies co-locate all authorization rules for a resource and integrate with `authorize()` and `can()` helpers automatically.
-12. **Use database transactions for multi-step writes and wrap them with `DB::transaction()`** because partial writes without transactions leave data in an inconsistent state that is expensive to recover from.
-13. **Write feature tests using `RefreshDatabase` and factory-seeded data** because feature tests that hit real routes with real middleware catch integration bugs that unit tests miss.
-14. **Run `php artisan model:show` and `route:list` as verification checkpoints** because these commands surface missing relationships, duplicate routes, and middleware gaps before code review.
-15. **Configure queue workers with Horizon or Supervisor for production reliability** because artisan queue:work without supervision silently dies on memory leaks and unhandled exceptions.
-16. **Pin dependencies with `composer.lock` and run `composer audit` in CI** because unpinned dependencies introduce supply-chain risk and audit catches known CVEs before deployment.
-
-## Output Format
-
-Provide implementation guidance, code examples, Artisan commands, and configuration snippets as appropriate to the task. Include migration snippets when schema changes are involved.
-
-## References
-
-Load on demand. Do not preload all reference files.
-
-| File | Load when |
-| --- | --- |
-| `references/eloquent.md` | You need Eloquent model patterns, relationships, scopes, accessors/mutators, or query optimization guidance. |
-| `references/middleware-routing.md` | You need middleware composition, route grouping, rate limiting, or request lifecycle guidance. |
-| `references/queues-events.md` | You need queue job design, retry/backoff strategies, event/listener wiring, or Horizon configuration. |
-| `references/testing.md` | You need feature test patterns, factory design, mocking external services, or Pest/PHPUnit integration. |
-| `references/security.md` | You need CSRF protection, authentication guards, authorization policies, encryption, or input sanitization. |
-
-## 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 build a Laravel API resource for orders with nested line items"
-- "Review my Laravel queue job for retry safety and failure handling"

package/workflows/skills/laravel/evals/assertions.md

@@ -1,21 +0,0 @@
-# Laravel Skill Assertions
-
-## Eval 1: API Resource with Eloquent Relationships
-
-| # | Assertion | Type | Expected Value | Rationale |
-|---|-----------|------|----------------|-----------|
-| 1 | Uses JsonResource | contains | `JsonResource` | API Resources are the canonical Laravel pattern for shaping JSON output. Raw model `toArray()` leaks schema internals. |
-| 2 | Eager-loads relationships | contains | `with(` | Eager loading with `with()` prevents N+1 queries when serializing related models through API Resources. |
-| 3 | Defines belongsTo | contains | `belongsTo` | The Order-to-Customer relationship must be explicitly defined on the model for Eloquent to resolve it. |
-| 4 | Defines hasMany | contains | `hasMany` | The Order-to-OrderItems relationship must be explicitly defined for nested resource serialization. |
-| 5 | Registers routes | contains | `Route::` | Route registration is required to expose the API Resource controller to HTTP clients. |
-
-## Eval 2: Queue-Based Job Processing
-
-| # | Assertion | Type | Expected Value | Rationale |
-|---|-----------|------|----------------|-----------|
-| 1 | Implements ShouldQueue | contains | `implements ShouldQueue` | The ShouldQueue interface is required for Laravel to dispatch the job to a queue driver instead of running it synchronously. |
-| 2 | Defines backoff | contains | `backoff` | Exponential or stepped backoff prevents thundering-herd retries against a failing third-party API. |
-| 3 | Implements failed() | contains | `failed(` | The `failed()` method is the designated hook for handling permanent failures after all retries are exhausted. |
-| 4 | Dispatches the job | contains | `dispatch(` | The job must be dispatched from the controller or service to enter the queue pipeline. |
-| 5 | Uses event dispatch | contains | `event(` | Post-payment side effects (notifications, audit logs) should be decoupled via events to keep the job focused. |

package/workflows/skills/laravel/evals/evals.json

@@ -1,66 +0,0 @@
-[
-  {
-    "name": "api-resource-with-eloquent-relationships",
-    "description": "Validate that the skill produces a correct Laravel API Resource backed by Eloquent relationships with eager loading and proper JSON structure.",
-    "prompt": "Create a Laravel 11 API resource for an Order model that belongs to a Customer and has many OrderItems. Each OrderItem belongs to a Product. Return nested JSON with customer name, order total, and line items with product name and quantity. Include the controller, resource classes, and route registration.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "JsonResource",
-        "description": "Must use Laravel API Resource (JsonResource) for response shaping."
-      },
-      {
-        "type": "contains",
-        "value": "with(",
-        "description": "Must eager-load relationships using with() to prevent N+1 queries."
-      },
-      {
-        "type": "contains",
-        "value": "belongsTo",
-        "description": "Must define belongsTo relationship on the Order model for Customer."
-      },
-      {
-        "type": "contains",
-        "value": "hasMany",
-        "description": "Must define hasMany relationship on the Order model for OrderItems."
-      },
-      {
-        "type": "contains",
-        "value": "Route::",
-        "description": "Must include route registration for the API resource endpoint."
-      }
-    ]
-  },
-  {
-    "name": "queue-based-job-processing",
-    "description": "Validate that the skill produces a robust queued job with retry logic, backoff, failure handling, and event-driven dispatch.",
-    "prompt": "Create a Laravel 11 queued job that processes a payment via a third-party API. The job should have exponential backoff, a maximum of 5 retries, a failed() method that notifies an admin, and be dispatched from a PaymentController after an order is created. Include the event/listener pattern for triggering post-payment side effects.",
-    "assertions": [
-      {
-        "type": "contains",
-        "value": "implements ShouldQueue",
-        "description": "Must implement ShouldQueue interface for async queue processing."
-      },
-      {
-        "type": "contains",
-        "value": "backoff",
-        "description": "Must define backoff strategy (exponential or array-based) for retry delays."
-      },
-      {
-        "type": "contains",
-        "value": "failed(",
-        "description": "Must implement failed() method for handling permanent job failures."
-      },
-      {
-        "type": "contains",
-        "value": "dispatch(",
-        "description": "Must dispatch the job from the controller or service layer."
-      },
-      {
-        "type": "contains",
-        "value": "event(",
-        "description": "Must use event dispatch for post-payment side effects decoupled from the job."
-      }
-    ]
-  }
-]

package/workflows/skills/laravel/examples/01-api-resource-with-relationships.md

@@ -1,180 +0,0 @@
-# Example: API Resource with Eloquent Relationships
-
-## Scenario
-
-Build a JSON API endpoint that returns orders with nested customer and line-item data. The response must avoid N+1 queries and hide internal database columns from the public contract.
-
-## Models
-
-```php
-// app/Models/Order.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Models;
-
-use Illuminate\Database\Eloquent\Factories\HasFactory;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
-use Illuminate\Database\Eloquent\Relations\HasMany;
-
-class Order extends Model
-{
-    use HasFactory;
-
-    protected $fillable = ['customer_id', 'status', 'total_cents'];
-
-    public function customer(): BelongsTo
-    {
-        return $this->belongsTo(Customer::class);
-    }
-
-    public function items(): HasMany
-    {
-        return $this->hasMany(OrderItem::class);
-    }
-}
-```
-
-```php
-// app/Models/OrderItem.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Models;
-
-use Illuminate\Database\Eloquent\Factories\HasFactory;
-use Illuminate\Database\Eloquent\Model;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
-
-class OrderItem extends Model
-{
-    use HasFactory;
-
-    protected $fillable = ['order_id', 'product_id', 'quantity', 'unit_price_cents'];
-
-    public function order(): BelongsTo
-    {
-        return $this->belongsTo(Order::class);
-    }
-
-    public function product(): BelongsTo
-    {
-        return $this->belongsTo(Product::class);
-    }
-}
-```
-
-## API Resources
-
-```php
-// app/Http/Resources/OrderItemResource.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Http\Resources;
-
-use Illuminate\Http\Request;
-use Illuminate\Http\Resources\Json\JsonResource;
-
-class OrderItemResource extends JsonResource
-{
-    public function toArray(Request $request): array
-    {
-        return [
-            'id'              => $this->id,
-            'product_name'    => $this->product->name,
-            'quantity'        => $this->quantity,
-            'unit_price'      => $this->unit_price_cents / 100,
-            'line_total'      => ($this->unit_price_cents * $this->quantity) / 100,
-        ];
-    }
-}
-```
-
-```php
-// app/Http/Resources/OrderResource.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Http\Resources;
-
-use Illuminate\Http\Request;
-use Illuminate\Http\Resources\Json\JsonResource;
-
-class OrderResource extends JsonResource
-{
-    public function toArray(Request $request): array
-    {
-        return [
-            'id'            => $this->id,
-            'status'        => $this->status,
-            'total'         => $this->total_cents / 100,
-            'customer'      => [
-                'id'   => $this->customer->id,
-                'name' => $this->customer->name,
-            ],
-            'items'         => OrderItemResource::collection($this->items),
-            'created_at'    => $this->created_at->toIso8601String(),
-        ];
-    }
-}
-```
-
-## Controller
-
-```php
-// app/Http/Controllers/Api/OrderController.php
-<?php
-
-declare(strict_types=1);
-
-namespace App\Http\Controllers\Api;
-
-use App\Http\Controllers\Controller;
-use App\Http\Resources\OrderResource;
-use App\Models\Order;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
-
-class OrderController extends Controller
-{
-    public function index(): AnonymousResourceCollection
-    {
-        $orders = Order::with(['customer', 'items.product'])
-            ->latest()
-            ->paginate(25);
-
-        return OrderResource::collection($orders);
-    }
-
-    public function show(Order $order): OrderResource
-    {
-        $order->load(['customer', 'items.product']);
-
-        return new OrderResource($order);
-    }
-}
-```
-
-## Route Registration
-
-```php
-// routes/api.php
-use App\Http\Controllers\Api\OrderController;
-use Illuminate\Support\Facades\Route;
-
-Route::middleware('auth:sanctum')->group(function () {
-    Route::apiResource('orders', OrderController::class)->only(['index', 'show']);
-});
-```
-
-## Key Decisions
-
-- **Eager loading**: `with(['customer', 'items.product'])` eliminates N+1 queries across three relationship levels.
-- **Resource isolation**: `OrderResource` and `OrderItemResource` control exactly which fields reach the client, decoupling the API contract from the database schema.
-- **Pagination**: `paginate(25)` prevents unbounded result sets. The resource collection automatically includes pagination metadata.
-- **Sanctum middleware**: Protects the endpoint. Replace with `auth:api` if using Passport.