@cubis/foundry 0.3.67 → 0.3.69

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-developer/steering/testing.md

@@ -1,329 +0,0 @@
-# Testing Next.js Applications
-
-## Testing Stack
-
-| Tool                      | Purpose                             |
-| ------------------------- | ----------------------------------- |
-| Jest / Vitest             | Unit tests, component tests         |
-| React Testing Library     | Component rendering and interaction |
-| Playwright                | E2E tests on real browsers          |
-| MSW (Mock Service Worker) | API mocking                         |
-
-## Project Setup
-
-### Vitest + React Testing Library
-
-```bash
-npm install -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom jsdom
-```
-
-```ts
-// vitest.config.ts
-import { defineConfig } from "vitest/config";
-import react from "@vitejs/plugin-react";
-
-export default defineConfig({
-  plugins: [react()],
-  test: {
-    environment: "jsdom",
-    setupFiles: ["./tests/setup.ts"],
-    globals: true,
-  },
-  resolve: {
-    alias: { "@": new URL("./src", import.meta.url).pathname },
-  },
-});
-```
-
-```ts
-// tests/setup.ts
-import "@testing-library/jest-dom/vitest";
-```
-
-### Playwright
-
-```bash
-npm install -D @playwright/test
-npx playwright install
-```
-
-```ts
-// playwright.config.ts
-import { defineConfig, devices } from "@playwright/test";
-
-export default defineConfig({
-  testDir: "./e2e",
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: "html",
-  use: {
-    baseURL: "http://localhost:3000",
-    trace: "on-first-retry",
-  },
-  projects: [
-    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
-    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
-    { name: "webkit", use: { ...devices["Desktop Safari"] } },
-    { name: "mobile", use: { ...devices["iPhone 14"] } },
-  ],
-  webServer: {
-    command: "npm run dev",
-    url: "http://localhost:3000",
-    reuseExistingServer: !process.env.CI,
-  },
-});
-```
-
-## Unit Testing
-
-### Testing Utility Functions
-
-```tsx
-// lib/utils.test.ts
-import { describe, it, expect } from "vitest";
-import { formatPrice, slugify } from "./utils";
-
-describe("formatPrice", () => {
-  it("should format cents to dollars", () => {
-    expect(formatPrice(1999)).toBe("$19.99");
-  });
-
-  it("should handle zero", () => {
-    expect(formatPrice(0)).toBe("$0.00");
-  });
-});
-
-describe("slugify", () => {
-  it("should convert to lowercase kebab-case", () => {
-    expect(slugify("Hello World")).toBe("hello-world");
-  });
-
-  it("should remove special characters", () => {
-    expect(slugify("Hello & World!")).toBe("hello-world");
-  });
-});
-```
-
-### Testing Server Actions
-
-```tsx
-// app/actions.test.ts
-import { describe, it, expect, vi } from "vitest";
-import { createPost } from "./actions";
-
-vi.mock("@/lib/db", () => ({
-  db: {
-    post: {
-      create: vi.fn().mockResolvedValue({ id: "1", title: "Test" }),
-    },
-  },
-}));
-
-describe("createPost", () => {
-  it("should create a post with valid data", async () => {
-    const formData = new FormData();
-    formData.set("title", "Test Post");
-    formData.set("content", "Test content");
-
-    const result = await createPost({}, formData);
-    expect(result.success).toBe(true);
-  });
-
-  it("should return errors for invalid data", async () => {
-    const formData = new FormData();
-    formData.set("title", ""); // Empty title
-
-    const result = await createPost({}, formData);
-    expect(result.errors?.title).toBeDefined();
-  });
-});
-```
-
-## Component Testing
-
-### Testing Server Components
-
-```tsx
-// components/ProductCard.test.tsx
-import { render, screen } from "@testing-library/react";
-import { ProductCard } from "./ProductCard";
-
-describe("ProductCard", () => {
-  const product = {
-    id: "1",
-    name: "Test Product",
-    price: 29.99,
-    image: "/test.jpg",
-  };
-
-  it("should render product name and price", () => {
-    render(<ProductCard product={product} />);
-    expect(screen.getByText("Test Product")).toBeInTheDocument();
-    expect(screen.getByText("$29.99")).toBeInTheDocument();
-  });
-
-  it("should render product image with alt text", () => {
-    render(<ProductCard product={product} />);
-    const img = screen.getByAltText("Test Product");
-    expect(img).toBeInTheDocument();
-  });
-});
-```
-
-### Testing Client Components with Interactions
-
-```tsx
-// components/Counter.test.tsx
-import { render, screen, fireEvent } from "@testing-library/react";
-import { Counter } from "./Counter";
-
-describe("Counter", () => {
-  it("should increment on click", () => {
-    render(<Counter initialCount={0} />);
-
-    const button = screen.getByRole("button", { name: /increment/i });
-    fireEvent.click(button);
-
-    expect(screen.getByText("1")).toBeInTheDocument();
-  });
-
-  it("should decrement on click", () => {
-    render(<Counter initialCount={5} />);
-
-    const button = screen.getByRole("button", { name: /decrement/i });
-    fireEvent.click(button);
-
-    expect(screen.getByText("4")).toBeInTheDocument();
-  });
-});
-```
-
-## E2E Testing with Playwright
-
-### Basic Navigation Test
-
-```tsx
-// e2e/navigation.spec.ts
-import { test, expect } from "@playwright/test";
-
-test("should navigate to about page", async ({ page }) => {
-  await page.goto("/");
-  await page.click("text=About");
-  await expect(page).toHaveURL("/about");
-  await expect(page.locator("h1")).toContainText("About");
-});
-```
-
-### Form Submission Test
-
-```tsx
-// e2e/contact.spec.ts
-import { test, expect } from "@playwright/test";
-
-test("should submit contact form", async ({ page }) => {
-  await page.goto("/contact");
-
-  await page.fill('[name="name"]', "John Doe");
-  await page.fill('[name="email"]', "john@example.com");
-  await page.fill('[name="message"]', "Hello!");
-  await page.click('button[type="submit"]');
-
-  await expect(page.locator(".success-message")).toBeVisible();
-});
-```
-
-### Authentication Flow
-
-```tsx
-// e2e/auth.spec.ts
-import { test, expect } from "@playwright/test";
-
-test.describe("Authentication", () => {
-  test("should login and redirect to dashboard", async ({ page }) => {
-    await page.goto("/login");
-    await page.fill('[name="email"]', "user@example.com");
-    await page.fill('[name="password"]', "password123");
-    await page.click('button[type="submit"]');
-
-    await expect(page).toHaveURL("/dashboard");
-    await expect(page.locator("nav")).toContainText("Welcome");
-  });
-
-  test("should show error for invalid credentials", async ({ page }) => {
-    await page.goto("/login");
-    await page.fill('[name="email"]', "wrong@example.com");
-    await page.fill('[name="password"]', "wrong");
-    await page.click('button[type="submit"]');
-
-    await expect(page.locator(".error")).toContainText("Invalid credentials");
-  });
-});
-```
-
-### Visual Regression
-
-```tsx
-// e2e/visual.spec.ts
-import { test, expect } from "@playwright/test";
-
-test("homepage visual regression", async ({ page }) => {
-  await page.goto("/");
-  await expect(page).toHaveScreenshot("homepage.png", {
-    maxDiffPixelRatio: 0.01,
-  });
-});
-```
-
-## API Mocking with MSW
-
-```tsx
-// tests/mocks/handlers.ts
-import { http, HttpResponse } from "msw";
-
-export const handlers = [
-  http.get("/api/products", () => {
-    return HttpResponse.json([
-      { id: "1", name: "Product 1", price: 19.99 },
-      { id: "2", name: "Product 2", price: 29.99 },
-    ]);
-  }),
-
-  http.post("/api/products", async ({ request }) => {
-    const body = await request.json();
-    return HttpResponse.json({ id: "3", ...body }, { status: 201 });
-  }),
-];
-
-// tests/mocks/server.ts
-import { setupServer } from "msw/node";
-import { handlers } from "./handlers";
-export const server = setupServer(...handlers);
-
-// tests/setup.ts
-import { server } from "./mocks/server";
-beforeAll(() => server.listen());
-afterEach(() => server.resetHandlers());
-afterAll(() => server.close());
-```
-
-## Running Tests
-
-```bash
-# Unit + component tests
-npm test
-npx vitest --run
-
-# E2E tests
-npx playwright test
-npx playwright test --ui          # Interactive UI mode
-npx playwright test --headed      # See browser
-npx playwright show-report        # View HTML report
-
-# Coverage
-npx vitest --coverage
-
-# Update snapshots
-npx playwright test --update-snapshots
-```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-react-expert/SKILL.md

@@ -1,15 +0,0 @@
----
-name: "nextjs-react-expert"
-description: "Compatibility alias skill. Deprecated: use react-best-practices."
-metadata:
-  deprecated: true
-  replaced_by: react-best-practices
-  removal_target: "v0.6.0"
-  alias_of: "react-best-practices"
----
-
-# nextjs-react-expert (Compatibility Alias)
-
-This skill is deprecated and kept for backward compatibility.
-
-Use `react-best-practices` for optimization/review workflows.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-react-expert/docs/1-async-eliminating-waterfalls.md

@@ -1,312 +0,0 @@
-# 1. Eliminating Waterfalls
-
-> **Impact:** CRITICAL
-> **Focus:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
-
----
-
-## Overview
-
-This section contains **5 rules** focused on eliminating waterfalls.
-
----
-
-## Rule 1.1: Defer Await Until Needed
-
-**Impact:** HIGH  
-**Tags:** async, await, conditional, optimization  
-
-## Defer Await Until Needed
-
-Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
-
-**Incorrect (blocks both branches):**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
-  const userData = await fetchUserData(userId)
-  
-  if (skipProcessing) {
-    // Returns immediately but still waited for userData
-    return { skipped: true }
-  }
-  
-  // Only this branch uses userData
-  return processUserData(userData)
-}
-```
-
-**Correct (only blocks when needed):**
-
-```typescript
-async function handleRequest(userId: string, skipProcessing: boolean) {
-  if (skipProcessing) {
-    // Returns immediately without waiting
-    return { skipped: true }
-  }
-  
-  // Fetch only when needed
-  const userData = await fetchUserData(userId)
-  return processUserData(userData)
-}
-```
-
-**Another example (early return optimization):**
-
-```typescript
-// Incorrect: always fetches permissions
-async function updateResource(resourceId: string, userId: string) {
-  const permissions = await fetchPermissions(userId)
-  const resource = await getResource(resourceId)
-  
-  if (!resource) {
-    return { error: 'Not found' }
-  }
-  
-  if (!permissions.canEdit) {
-    return { error: 'Forbidden' }
-  }
-  
-  return await updateResourceData(resource, permissions)
-}
-
-// Correct: fetches only when needed
-async function updateResource(resourceId: string, userId: string) {
-  const resource = await getResource(resourceId)
-  
-  if (!resource) {
-    return { error: 'Not found' }
-  }
-  
-  const permissions = await fetchPermissions(userId)
-  
-  if (!permissions.canEdit) {
-    return { error: 'Forbidden' }
-  }
-  
-  return await updateResourceData(resource, permissions)
-}
-```
-
-This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
-
----
-
-## Rule 1.2: Dependency-Based Parallelization
-
-**Impact:** CRITICAL  
-**Tags:** async, parallelization, dependencies, better-all  
-
-## Dependency-Based Parallelization
-
-For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
-
-**Incorrect (profile waits for config unnecessarily):**
-
-```typescript
-const [user, config] = await Promise.all([
-  fetchUser(),
-  fetchConfig()
-])
-const profile = await fetchProfile(user.id)
-```
-
-**Correct (config and profile run in parallel):**
-
-```typescript
-import { all } from 'better-all'
-
-const { user, config, profile } = await all({
-  async user() { return fetchUser() },
-  async config() { return fetchConfig() },
-  async profile() {
-    return fetchProfile((await this.$.user).id)
-  }
-})
-```
-
-**Alternative without extra dependencies:**
-
-We can also create all the promises first, and do `Promise.all()` at the end.
-
-```typescript
-const userPromise = fetchUser()
-const profilePromise = userPromise.then(user => fetchProfile(user.id))
-
-const [user, config, profile] = await Promise.all([
-  userPromise,
-  fetchConfig(),
-  profilePromise
-])
-```
-
-Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
-
----
-
-## Rule 1.3: Prevent Waterfall Chains in API Routes
-
-**Impact:** CRITICAL  
-**Tags:** api-routes, server-actions, waterfalls, parallelization  
-
-## Prevent Waterfall Chains in API Routes
-
-In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
-
-**Incorrect (config waits for auth, data waits for both):**
-
-```typescript
-export async function GET(request: Request) {
-  const session = await auth()
-  const config = await fetchConfig()
-  const data = await fetchData(session.user.id)
-  return Response.json({ data, config })
-}
-```
-
-**Correct (auth and config start immediately):**
-
-```typescript
-export async function GET(request: Request) {
-  const sessionPromise = auth()
-  const configPromise = fetchConfig()
-  const session = await sessionPromise
-  const [config, data] = await Promise.all([
-    configPromise,
-    fetchData(session.user.id)
-  ])
-  return Response.json({ data, config })
-}
-```
-
-For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
-
----
-
-## Rule 1.4: Promise.all() for Independent Operations
-
-**Impact:** CRITICAL  
-**Tags:** async, parallelization, promises, waterfalls  
-
-## Promise.all() for Independent Operations
-
-When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
-
-**Incorrect (sequential execution, 3 round trips):**
-
-```typescript
-const user = await fetchUser()
-const posts = await fetchPosts()
-const comments = await fetchComments()
-```
-
-**Correct (parallel execution, 1 round trip):**
-
-```typescript
-const [user, posts, comments] = await Promise.all([
-  fetchUser(),
-  fetchPosts(),
-  fetchComments()
-])
-```
-
----
-
-## Rule 1.5: Strategic Suspense Boundaries
-
-**Impact:** HIGH  
-**Tags:** async, suspense, streaming, layout-shift  
-
-## Strategic Suspense Boundaries
-
-Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
-
-**Incorrect (wrapper blocked by data fetching):**
-
-```tsx
-async function Page() {
-  const data = await fetchData() // Blocks entire page
-  
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <DataDisplay data={data} />
-      </div>
-      <div>Footer</div>
-    </div>
-  )
-}
-```
-
-The entire layout waits for data even though only the middle section needs it.
-
-**Correct (wrapper shows immediately, data streams in):**
-
-```tsx
-function Page() {
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <div>
-        <Suspense fallback={<Skeleton />}>
-          <DataDisplay />
-        </Suspense>
-      </div>
-      <div>Footer</div>
-    </div>
-  )
-}
-
-async function DataDisplay() {
-  const data = await fetchData() // Only blocks this component
-  return <div>{data.content}</div>
-}
-```
-
-Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
-
-**Alternative (share promise across components):**
-
-```tsx
-function Page() {
-  // Start fetch immediately, but don't await
-  const dataPromise = fetchData()
-  
-  return (
-    <div>
-      <div>Sidebar</div>
-      <div>Header</div>
-      <Suspense fallback={<Skeleton />}>
-        <DataDisplay dataPromise={dataPromise} />
-        <DataSummary dataPromise={dataPromise} />
-      </Suspense>
-      <div>Footer</div>
-    </div>
-  )
-}
-
-function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
-  const data = use(dataPromise) // Unwraps the promise
-  return <div>{data.content}</div>
-}
-
-function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
-  const data = use(dataPromise) // Reuses the same promise
-  return <div>{data.summary}</div>
-}
-```
-
-Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
-
-**When NOT to use this pattern:**
-
-- Critical data needed for layout decisions (affects positioning)
-- SEO-critical content above the fold
-- Small, fast queries where suspense overhead isn't worth it
-- When you want to avoid layout shift (loading → content jump)
-
-**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
-