coding-os 0.3.2__py3-none-any.whl

templates/nextjs/skills/nextjs-react/SKILL.md

@@ -0,0 +1,485 @@
+---
+name: nextjs-react
+tier: stack
+domain: [frontend]
+description: Use when creating or modifying React components, pages, layouts, or hooks in the Next.js frontend. Triggers on any .tsx/.ts file change under src/frontend/. Covers Server Component defaults, hydration safety, three-state async UI, error display mapping, localStorage SSR guards, and component extraction rules.
+globs: "src/frontend/**/*.{ts,tsx}"
+depends_on:
+  - clean-code
+  - frontend-fundamentals
+last_reviewed: "2026-05-11"
+
+---
+
+This skill enforces Next.js 16 App Router and React patterns. It `depends_on: [clean-code, frontend-fundamentals]` which are loaded transitively — `clean-code` gives universal code quality, `frontend-fundamentals` gives stack-agnostic UI patterns (three-state async, hydration, a11y, SEO). This skill adds ONLY Next.js-App-Router and React-version-specific layering on top.
+
+## Pre-Code Checklist
+
+Before writing or modifying any `.ts`/`.tsx` file:
+
+- [ ] Read `docs/engineering/frontend-rules.md`
+- [ ] If touching data fetching or rendering logic: read `docs/engineering/frontend-rendering-rules.md`
+- [ ] If touching design, layout, or styling: read `STYLE_GUIDE.md` + the relevant file in `docs/design/`
+- [ ] If touching API calls or error handling: read `docs/api-contracts/error-format.md`
+- [ ] Search the repo for existing components and hooks before creating new ones (use Grep/Glob)
+
+## 1. Server Components First
+
+Default to **Server Components**. Never add `'use client'` unless the component genuinely requires it.
+
+### When to use `'use client'`
+
+- Browser APIs (`window`, `document`, `navigator`, `localStorage`)
+- Event handlers (`onClick`, `onChange`, `onSubmit`)
+- React state or effects (`useState`, `useEffect`, `useReducer`, `useRef` with mutations)
+- Third-party client-only libraries (e.g., motion, chart libraries)
+
+### Correct — Server Component (default)
+
+```tsx
+// app/products/[slug]/page.tsx
+// No 'use client' — this is a Server Component
+import { getProduct } from "@/lib/api/products";
+import { ProductDetails } from "@/components/products/product-details";
+
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const product = await getProduct(slug);
+
+  return <ProductDetails product={product} />;
+}
+```
+
+### Correct — Client Component (only when needed)
+
+```tsx
+// components/products/add-to-cart-button.tsx
+"use client";
+
+import { useState } from "react";
+
+interface AddToCartButtonProps {
+  productId: string;
+  onAdd: (id: string) => void;
+}
+
+export function AddToCartButton({ productId, onAdd }: AddToCartButtonProps) {
+  const [isAdding, setIsAdding] = useState(false);
+
+  async function handleClick() {
+    setIsAdding(true);
+    try {
+      await onAdd(productId);
+    } finally {
+      setIsAdding(false);
+    }
+  }
+
+  return (
+    <button onClick={handleClick} disabled={isAdding}>
+      {isAdding ? "Adding..." : "Add to Cart"}
+    </button>
+  );
+}
+```
+
+### Wrong — Unnecessary client directive
+
+```tsx
+// BAD: 'use client' added for no reason — this is pure rendering
+"use client";
+
+export function ProductCard({ name, price }: { name: string; price: number }) {
+  return (
+    <div>
+      <h3>{name}</h3>
+      <p>${price}</p>
+    </div>
+  );
+}
+```
+
+## 2. Hydration Safety
+
+The server-rendered HTML must match the client's first render exactly. Mismatches cause hydration errors, layout flicker, and broken UI.
+
+### Rule
+
+`useState` initializers MUST return the **same value** on both server and client. For client-only values, initialize with `undefined` or `null` and set the real value in `useEffect`.
+
+### Correct — Client-only value via useEffect
+
+```tsx
+"use client";
+
+import { useState, useEffect } from "react";
+
+export function ViewportLabel() {
+  const [width, setWidth] = useState<number | undefined>(undefined);
+
+  useEffect(() => {
+    setWidth(window.innerWidth);
+
+    function handleResize() {
+      setWidth(window.innerWidth);
+    }
+    window.addEventListener("resize", handleResize);
+    return () => window.removeEventListener("resize", handleResize);
+  }, []);
+
+  if (width === undefined) {
+    return <span>Loading...</span>;
+  }
+
+  return <span>Viewport: {width}px</span>;
+}
+```
+
+### Wrong — Divergent initializer
+
+```tsx
+// BAD: Server renders 0, client renders window.innerWidth → hydration mismatch
+"use client";
+
+import { useState } from "react";
+
+export function ViewportLabel() {
+  const [width] = useState(() =>
+    typeof window !== "undefined" ? window.innerWidth : 0,
+  );
+
+  return <span>Viewport: {width}px</span>;
+}
+```
+
+### Wrong — Conditional rendering on typeof window
+
+```tsx
+// BAD: Server renders nothing, client renders content → hydration mismatch
+"use client";
+
+export function ClientOnlyBanner() {
+  if (typeof window === "undefined") return null;
+
+  return <div>Welcome, {window.navigator.userAgent}</div>;
+}
+```
+
+### Intentional sync setState
+
+When you intentionally call `setState` synchronously during render (e.g., to correct a mismatch), add an eslint-disable comment explaining why:
+
+```tsx
+// eslint-disable-next-line react-hooks/exhaustive-deps -- sync correction
+// for server/client value alignment on first client render
+```
+
+## 3. Three-State Async UI
+
+Every async operation that drives UI must handle **all three states**: loading, error, and empty/success. Never show stale data during a fetch. Never show a blank screen on error.
+
+### Correct — All three states
+
+```tsx
+"use client";
+
+import { useState, useEffect } from "react";
+import type { Product } from "@/types/product";
+
+export function ProductList({ categoryId }: { categoryId: string }) {
+  const [products, setProducts] = useState<Product[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function load() {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const res = await fetch(`/api/products?category=${categoryId}`);
+        if (!res.ok) throw new Error("Failed to load products");
+        const data: Product[] = await res.json();
+
+        if (!cancelled) {
+          setProducts(data);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : "Unexpected error");
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    load();
+    return () => { cancelled = true; };
+  }, [categoryId]);
+
+  // State 1: Loading
+  if (isLoading) {
+    return <ProductListSkeleton />;
+  }
+
+  // State 2: Error
+  if (error) {
+    return (
+      <div role="alert">
+        <p>Could not load products: {error}</p>
+        <button onClick={() => setError(null)}>Retry</button>
+      </div>
+    );
+  }
+
+  // State 3: Empty
+  if (products.length === 0) {
+    return <p>No products found in this category.</p>;
+  }
+
+  // State 4: Success with data
+  return (
+    <ul>
+      {products.map((p) => (
+        <li key={p.id}>{p.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Wrong — Missing states
+
+```tsx
+// BAD: No loading state, no error state, no empty state
+"use client";
+
+import { useState, useEffect } from "react";
+
+export function ProductList({ categoryId }: { categoryId: string }) {
+  const [products, setProducts] = useState([]);
+
+  useEffect(() => {
+    fetch(`/api/products?category=${categoryId}`)
+      .then((r) => r.json())
+      .then(setProducts);
+  }, [categoryId]);
+
+  return (
+    <ul>
+      {products.map((p) => (
+        <li key={p.id}>{p.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## 4. Error Display
+
+Never show raw server messages to users. Map API error codes to user-facing i18n keys.
+
+### Pattern
+
+```
+API error_code → i18n key: errors.<domain>.<ERROR_CODE>
+```
+
+### Correct — Mapped error display
+
+```tsx
+import { useTranslation } from "@/lib/i18n";
+
+const ERROR_KEY_MAP: Record<string, string> = {
+  PRODUCT_NOT_FOUND: "errors.products.PRODUCT_NOT_FOUND",
+  PRODUCT_UNAVAILABLE: "errors.products.PRODUCT_UNAVAILABLE",
+  INSUFFICIENT_FUNDS: "errors.payments.INSUFFICIENT_FUNDS",
+};
+
+function getErrorMessage(errorCode: string | undefined, t: (key: string) => string): string {
+  if (errorCode && ERROR_KEY_MAP[errorCode]) {
+    return t(ERROR_KEY_MAP[errorCode]);
+  }
+  return t("errors.generic.UNEXPECTED");
+}
+```
+
+### Error placement rules
+
+| Error Type | Display Method |
+|---|---|
+| Transient (network, timeout) | Toast notification with retry |
+| Form validation | Inline below the field |
+| Permission / auth | Redirect or full-page message |
+| Not found | Dedicated empty state or 404 page |
+
+### Wrong — Raw server message
+
+```tsx
+// BAD: Shows raw server error to user
+catch (err) {
+  setError(err.message); // "IntegrityError: duplicate key violates..."
+}
+```
+
+## 5. localStorage Pattern
+
+Accessing `localStorage` requires an SSR guard because it does not exist on the server.
+
+### Correct — Lazy initializer with SSR guard
+
+```tsx
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+
+function useLocalStorage<T>(key: string, fallback: T) {
+  const [value, setValue] = useState<T>(fallback);
+  const [isHydrated, setIsHydrated] = useState(false);
+
+  // Read from localStorage after mount (client only)
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(key);
+      if (stored !== null) {
+        setValue(JSON.parse(stored) as T);
+      }
+    } catch {
+      // localStorage unavailable or corrupted — keep fallback
+    }
+    setIsHydrated(true);
+  }, [key]);
+
+  // Write to localStorage on changes (after hydration)
+  const set = useCallback(
+    (next: T) => {
+      setValue(next);
+      try {
+        localStorage.setItem(key, JSON.stringify(next));
+      } catch {
+        // Storage full or unavailable — state still updates in memory
+      }
+    },
+    [key],
+  );
+
+  return [value, set, isHydrated] as const;
+}
+```
+
+### Rule: Always try/catch localStorage calls
+
+Every `localStorage.getItem` and `localStorage.setItem` call MUST be wrapped in `try/catch`. Storage can throw when full (`QuotaExceededError`), disabled by privacy settings, or unavailable in SSR. Never call `localStorage.setItem(...)` without a surrounding try/catch — even outside the `useLocalStorage` hook.
+
+### Wrong — Direct access in initializer
+
+```tsx
+// BAD: Crashes on server, hydration mismatch on client
+"use client";
+
+import { useState } from "react";
+
+function useLocalStorage<T>(key: string, fallback: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key); // ReferenceError on server
+    return stored ? JSON.parse(stored) : fallback;
+  });
+
+  return [value, setValue] as const;
+}
+```
+
+## 6. Component Extraction
+
+Never define a component inside another component. Inner components are recreated on every render, destroying state and DOM nodes.
+
+### Correct — Extracted above parent
+
+```tsx
+// components/products/product-card.tsx
+interface PriceBadgeProps {
+  price: number;
+  discount?: number;
+}
+
+function PriceBadge({ price, discount }: PriceBadgeProps) {
+  if (discount) {
+    return (
+      <span>
+        <s>${price}</s> ${price - discount}
+      </span>
+    );
+  }
+  return <span>${price}</span>;
+}
+
+interface ProductCardProps {
+  name: string;
+  price: number;
+  discount?: number;
+}
+
+export function ProductCard({ name, price, discount }: ProductCardProps) {
+  return (
+    <div>
+      <h3>{name}</h3>
+      <PriceBadge price={price} discount={discount} />
+    </div>
+  );
+}
+```
+
+### Wrong — Component defined inside parent
+
+```tsx
+// BAD: PriceBadge is recreated on every render of ProductCard
+export function ProductCard({ name, price, discount }: ProductCardProps) {
+  // This component is redefined every render — causes remount, lost state
+  function PriceBadge() {
+    if (discount) {
+      return (
+        <span>
+          <s>${price}</s> ${price - discount}
+        </span>
+      );
+    }
+    return <span>${price}</span>;
+  }
+
+  return (
+    <div>
+      <h3>{name}</h3>
+      <PriceBadge />
+    </div>
+  );
+}
+```
+
+## 7. Import and File Conventions
+
+- Use `@/` path aliases for all imports (never relative paths beyond `./`)
+- One exported component per file; filename matches export name in kebab-case
+- Co-locate test files: `component-name.test.tsx` next to `component-name.tsx`
+- Barrel exports (`index.ts`) only at feature boundaries, not per-component
+
+## Post-Code Checklist
+
+After writing or modifying any frontend code, verify all points before committing:
+
+- [ ] **Server-first:** No unnecessary `'use client'` directives
+- [ ] **Hydration-safe:** `useState` initializers return identical values on server and client
+- [ ] **Three-state UI:** Every async operation shows loading, error, and empty states
+- [ ] **Error mapping:** API errors mapped to i18n keys — no raw server messages shown
+- [ ] **localStorage guarded:** All `localStorage` access wrapped in SSR-safe pattern
+- [ ] **Components extracted:** No components defined inside other components
+- [ ] **Responsive verified:** Visual smoke test at 375px, 768px, and 1280px
+- [ ] **Lint passes:** `cd frontend && npm run lint` exits cleanly
+- [ ] **Build passes:** `cd frontend && npm run build` exits cleanly

templates/nextjs/skills/nextjs-react/references/anatomy.md

@@ -0,0 +1,116 @@
+<!-- domain:NEXTJS | layer:reference | ssot:true | updated:2026-04-29 -->
+# Next.js Anatomy
+
+> P: Canonical file map and entity recipes for the Next.js stack — agents read this BEFORE writing any frontend file.
+> R: Adding any `.ts` / `.tsx` file, or routing a frontend task.
+> S: Working on backend / mobile / ai-service code.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: [`src/templates/nextjs/scaffold-boundary.yaml`](../../../scaffold-boundary.yaml).
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Page route | `src/frontend/app/<segment>/page.tsx` | `page.tsx` (literal) | `@/components`, `@/lib` | Server Component default |
+| Layout | `src/frontend/app/<segment>/layout.tsx` | `layout.tsx` (literal) | `@/components` | Wraps child route |
+| Loading | `src/frontend/app/<segment>/loading.tsx` | `loading.tsx` (literal) | none | Streamed fallback |
+| Error | `src/frontend/app/<segment>/error.tsx` | `error.tsx` (literal) | none | Client component |
+| Not-found | `src/frontend/app/<segment>/not-found.tsx` | `not-found.tsx` | none | 404 surface |
+| Component | `src/frontend/components/<area>/<name>.tsx` | `kebab-case.tsx` | `@/lib`, peers | Server-first |
+| Client component | `src/frontend/components/<area>/<name>.client.tsx` | `<name>.client.tsx` | `@/lib` | `"use client"` |
+| Hook | `src/frontend/lib/hooks/use<Name>.ts` | `useFooBar.ts` | none cross-area | Pure React hook |
+| API helper | `src/frontend/lib/api/<resource>.ts` | `<resource>.ts` | `@/shared/types` | Server-only fetch |
+| Utility | `src/frontend/lib/utils/<name>.ts` | `kebab-case.ts` | none cross-area | Stack-agnostic |
+| Type module | `src/frontend/lib/types/<name>.ts` | `<name>.ts` | none | Frontend-shared types |
+| Test | `src/frontend/<…>.test.{ts,tsx}` | `<file>.test.tsx` | source under test | Colocated |
+| E2E | `src/frontend/e2e/<flow>.spec.ts` | `<flow>.spec.ts` | none | Playwright |
+| Style module | `src/frontend/components/<area>/<name>.module.css` | `<name>.module.css` | none | CSS Modules |
+
+## 3. Entity recipes
+
+### Add a new component
+
+- **Trigger:** "add a Foo component", "build a card / button / form".
+- **Files:**
+  1. `src/frontend/components/<area>/<name>.tsx`
+  2. `src/frontend/components/<area>/<name>.test.tsx`
+- **Steps:**
+  1. Server Component default; client only if uses hooks / state / browser API.
+  2. Author component with exported `interface <Name>Props`.
+  3. Author colocated test (Given/When/Then).
+  4. Re-export from `src/frontend/components/<area>/index.ts` only when cross-area imports needed.
+- **Generator:** [`src/scripts/new_component.py`](../scripts/new_component.py).
+
+### Add a new page / route
+
+- **Trigger:** "add /pricing page", "new route".
+- **Files:**
+  1. `src/frontend/app/<segment>/page.tsx`
+  2. `src/frontend/app/<segment>/loading.tsx` (recommended)
+  3. `src/frontend/app/<segment>/error.tsx` (when route fetches data)
+- **Steps:**
+  1. Decide segment hierarchy — share layouts via parent `layout.tsx`.
+  2. Server-fetch in `page.tsx`; never `useEffect` server-side.
+  3. Add `export const metadata`.
+  4. Wrap user-specific data in `<Suspense>` + `loading.tsx`.
+
+### Add a new hook
+
+- **Trigger:** "extract logic into a hook", "add useFoo".
+- **Files:**
+  1. `src/frontend/lib/hooks/use<Name>.ts`
+  2. `src/frontend/lib/hooks/use<Name>.test.ts`
+- **Steps:**
+  1. Hook MUST start with `use`; client-only.
+  2. Memoize stable values; expose typed return.
+  3. Test renders consumer with mocked deps.
+
+### Add a new API helper
+
+- **Trigger:** "add wrapper for X endpoint", "fetch user profile".
+- **Files:**
+  1. `src/frontend/lib/api/<resource>.ts` (Server-Component only)
+  2. `src/frontend/lib/api/<resource>.test.ts`
+- **Steps:**
+  1. `fetch` from a Server Component; auth via cookies.
+  2. Return parsed types; never raw `Response`.
+  3. Map errors to envelope from `src/shared/contracts/errors.ts`.
+  4. NEVER import from `src/frontend/components/`.
+
+### Add a new test
+
+- **Trigger:** every component / hook / helper requires a colocated test.
+- **Files:**
+  1. `<source>.test.{ts,tsx}` — same dir as source.
+- **Steps:**
+  1. Vitest or Jest per project config.
+  2. Author Given/When/Then; cover happy + ≥1 failure path.
+
+## 4. Conventions
+
+#### Naming
+
+- Files: `kebab-case.{ts,tsx,css}` — exception: special Next.js names (`page.tsx`, `layout.tsx`, …).
+- Components: `PascalCase` exported symbol.
+- Hooks: `useCamelCase` symbol; file `useCamelCase.ts`.
+- Constants: `SCREAMING_SNAKE_CASE`.
+- CSS Modules: `<component>.module.css` next to source.
+
+#### Test colocation
+
+Colocated. `users/user-card.tsx` ⇄ `users/user-card.test.tsx`. E2E lives under `src/frontend/e2e/`. No `__tests__/` mirror dirs.
+
+#### Dependency rules
+
+- ✓ `src/frontend/` may import from `src/shared/`, `src/shared/types/`, `src/shared/contracts/`.
+- ✗ `src/frontend/` may NOT import from `src/backend/`, `src/mobile/`, `src/ai-service/`.
+- ✓ `src/frontend/components/` may import from `src/frontend/lib/`.
+- ✗ `src/frontend/lib/` may NOT import from `src/frontend/components/` (one-way).
+- ✗ Server Components may NOT import client-only hooks.

templates/nextjs/skills/nextjs-react/scripts/new_component.py

@@ -0,0 +1,72 @@
+"""Generate a Next.js component scaffold per `references/anatomy.md`.
+
+PURPOSE:      Eliminate the per-component boilerplate path-decision so
+              every agent (claude / codex) emits the same shape.
+INPUT:        --area <segment>     — e.g. users, products
+              --name <kebab-case>  — file slug
+              [--client]           — emits `<name>.client.tsx` instead.
+              [--root <dir>]       — defaults to `src/frontend/`.
+OUTPUT:       Two files: `<area>/<name>.tsx` (or `.client.tsx`) +
+              `<area>/<name>.test.tsx`.
+DEPENDENCIES: stdlib only.
+NOTES:        Idempotent — refuses to overwrite existing files.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _pascal(name: str) -> str:
+    return "".join(part.capitalize() for part in name.split("-") if part)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--area", required=True)
+    parser.add_argument("--name", required=True)
+    parser.add_argument("--client", action="store_true")
+    parser.add_argument("--root", default="src/frontend")
+    args = parser.parse_args()
+
+    target_dir = Path(args.root) / "components" / args.area
+    target_dir.mkdir(parents=True, exist_ok=True)
+    suffix = ".client.tsx" if args.client else ".tsx"
+    component_path = target_dir / f"{args.name}{suffix}"
+    test_path = target_dir / f"{args.name}.test.tsx"
+
+    if component_path.exists() or test_path.exists():
+        print(f"ERROR: refuse to overwrite existing files in {target_dir}", file=sys.stderr)
+        return 1
+
+    pascal = _pascal(args.name)
+    body_header = "'use client';\n\n" if args.client else ""
+    component_path.write_text(
+        f"{body_header}export interface {pascal}Props {{\n"
+        f"  // TODO: define props\n"
+        f"}}\n\n"
+        f"export function {pascal}(_props: {pascal}Props) {{\n"
+        f'  return <div data-testid="{args.name}" />;\n'
+        f"}}\n",
+        encoding="utf-8",
+    )
+    test_path.write_text(
+        f"import {{ render, screen }} from '@testing-library/react';\n"
+        f"import {{ {pascal} }} from './{args.name}{'.client' if args.client else ''}';\n\n"
+        f"describe('{pascal}', () => {{\n"
+        f"  it('renders the {args.name} container', () => {{\n"
+        f"    render(<{pascal} />);\n"
+        f"    expect(screen.getByTestId('{args.name}')).toBeInTheDocument();\n"
+        f"  }});\n"
+        f"}});\n",
+        encoding="utf-8",
+    )
+    print(f"OK: wrote {component_path}")
+    print(f"OK: wrote {test_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())