rsc-universal 0.1.1

package/skills/nextjs/references/security.md

@@ -0,0 +1,239 @@
+# Next.js security — auth, CSRF, XSS, CSP, env, SSRF
+
+Deep dive behind the "Security" section of `SKILL.md`. Next.js-specific layer; complements the
+generic `../secure-coding/SKILL.md` rather than duplicating it. Sources: authjs.dev
+session-management/protecting, the Next.js security model docs.
+
+## Auth on every Server Action / Route Handler / DAL
+
+The load-bearing rule: middleware/`proxy.ts` is a coarse redirect, **not** a security boundary. The
+real boundary is an `auth()` check inside every Server Action, every Route Handler, and a Data
+Access Layer that every read/write goes through.
+
+```ts
+// app/admin/actions.ts — guarded action: authenticate, authorize, then mutate
+"use server";
+import { z } from "zod";
+import { auth } from "@/auth";
+import { db } from "@/lib/db";
+
+const BanSchema = z.object({ userId: z.string().uuid() });
+
+export async function banUser(input: z.infer<typeof BanSchema>) {
+  const session = await auth();
+  if (!session?.user) return { status: "error", message: "Not authenticated" } as const;
+  if (session.user.role !== "admin") return { status: "error", message: "Forbidden" } as const;
+
+  const parsed = BanSchema.safeParse(input);
+  if (!parsed.success) return { status: "error", message: "Invalid input" } as const;
+
+  await db.user.update({ where: { id: parsed.data.userId }, data: { banned: true } });
+  return { status: "ok" } as const;
+}
+```
+
+```ts
+// lib/dal.ts — the Data Access Layer: every read goes through a session check
+import { cache } from "react";
+import { redirect } from "next/navigation";
+import { auth } from "@/auth";
+import { db } from "@/lib/db";
+
+export const requireUser = cache(async () => {
+  const session = await auth();
+  if (!session?.user) redirect("/login");
+  return session.user;
+});
+
+export async function getMyProjects() {
+  const user = await requireUser(); // re-checks the session here, not just in middleware
+  return db.project.findMany({ where: { ownerId: user.id } });
+}
+```
+
+## CSRF
+
+Server Actions are same-origin POSTs. Defense: SameSite cookies (`lax`) plus Next.js's built-in
+`Origin`/`Host` comparison, which rejects cross-origin action requests. Configure trusted origins
+explicitly, and never expose a mutation as an unauthenticated GET.
+
+```ts
+// next.config.ts — restrict which origins may invoke Server Actions
+import type { NextConfig } from "next";
+const config: NextConfig = {
+  experimental: {
+    serverActions: { allowedOrigins: ["app.example.com", "*.example.com"] },
+  },
+};
+export default config;
+```
+
+## XSS
+
+Avoid `dangerouslySetInnerHTML`. React escapes by default — opting out reintroduces XSS. If you must
+render HTML (e.g. sanitized CMS content), sanitize it **on the server** with DOMPurify first, and
+never interpolate user input into `<script>` tags or URLs.
+
+```tsx
+// Bad: raw user/CMS HTML straight into the DOM
+<div dangerouslySetInnerHTML={{ __html: post.body }} />;
+
+// Good: sanitize on the server before it reaches the client
+import DOMPurify from "isomorphic-dompurify";
+const clean = DOMPurify.sanitize(post.body, { ALLOWED_TAGS: ["p", "a", "strong", "em", "ul", "li"] });
+<div dangerouslySetInnerHTML={{ __html: clean }} />;
+```
+
+```tsx
+// Bad: user input in an href can be a javascript: URL
+<a href={user.website}>Site</a>;
+// Good: validate the scheme first
+const safe = /^https?:\/\//.test(user.website) ? user.website : "#";
+<a href={safe} rel="noopener noreferrer">Site</a>;
+```
+
+## Env exposure
+
+`NEXT_PUBLIC_*` variables are **inlined into the client bundle** at build time — anyone can read
+them. Keep secrets in plain (server-only) env vars and guard secret modules with `import "server-only"`.
+
+| Variable form             | Visible in browser? | Use for                          |
+| ------------------------- | ------------------- | -------------------------------- |
+| `DATABASE_URL`, `API_KEY` | No (server only)    | secrets, DB, server-to-server    |
+| `NEXT_PUBLIC_*`           | Yes (inlined)       | public, non-secret config only   |
+
+```ts
+// lib/payments.ts — fails the build if this module is ever pulled into a client bundle
+import "server-only";
+
+const STRIPE_KEY = process.env.STRIPE_SECRET_KEY!; // never NEXT_PUBLIC_*
+export async function charge(amount: number) {
+  /* server-to-server call using STRIPE_KEY */
+}
+```
+
+Proxy a third-party API through a Route Handler so the key never leaves the server:
+
+```ts
+// app/api/quote/route.ts — the browser calls this; the key stays server-side
+import { NextResponse } from "next/server";
+export async function GET() {
+  const res = await fetch("https://api.vendor.com/quote", {
+    headers: { Authorization: `Bearer ${process.env.VENDOR_KEY}` },
+  });
+  return NextResponse.json(await res.json());
+}
+```
+
+## SSRF
+
+A Route Handler that fetches a **user-supplied URL** must allowlist host + scheme, block
+internal/metadata ranges (`169.254.169.254`, `localhost`, RFC1918), and not follow redirects to
+internal hosts.
+
+```ts
+// Bad: fetches whatever URL the user sends — can hit the cloud metadata endpoint
+export async function GET(req: Request) {
+  const target = new URL(req.url).searchParams.get("url")!;
+  return Response.json(await (await fetch(target)).json()); // ✗ SSRF
+}
+```
+
+```ts
+// Good: allowlist host + scheme, reject internal ranges, disable redirects
+const ALLOWED_HOSTS = new Set(["images.example.com", "cdn.example.com"]);
+const BLOCKED = [/^127\./, /^10\./, /^192\.168\./, /^169\.254\./, /^172\.(1[6-9]|2\d|3[01])\./];
+
+export async function GET(req: Request) {
+  const raw = new URL(req.url).searchParams.get("url");
+  if (!raw) return Response.json({ error: "missing url" }, { status: 400 });
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return Response.json({ error: "invalid url" }, { status: 400 });
+  }
+  if (url.protocol !== "https:") return Response.json({ error: "https only" }, { status: 400 });
+  if (!ALLOWED_HOSTS.has(url.hostname)) return Response.json({ error: "host not allowed" }, { status: 400 });
+  if (BLOCKED.some((re) => re.test(url.hostname))) return Response.json({ error: "blocked range" }, { status: 400 });
+
+  const res = await fetch(url, { redirect: "error" }); // do not follow redirects
+  return Response.json(await res.json());
+}
+```
+
+## Security headers / CSP
+
+Set a nonce-based Content Security Policy in `proxy.ts` (v16) / `middleware.ts` (v15), pass the
+nonce to `<Script nonce>`, and add the standard hardening headers.
+
+```ts
+// proxy.ts (v16) — generate a per-request nonce and set the CSP
+import { NextRequest, NextResponse } from "next/server";
+
+export function proxy(req: NextRequest) {
+  const nonce = Buffer.from(crypto.randomUUID()).toString("base64");
+  const csp = [
+    `default-src 'self'`,
+    `script-src 'self' 'nonce-${nonce}' 'strict-dynamic'`,
+    `style-src 'self' 'unsafe-inline'`,
+    `img-src 'self' data: https:`,
+    `frame-ancestors 'none'`,
+    `object-src 'none'`,
+    `base-uri 'self'`,
+  ].join("; ");
+
+  const headers = new Headers(req.headers);
+  headers.set("x-nonce", nonce);
+
+  const res = NextResponse.next({ request: { headers } });
+  res.headers.set("Content-Security-Policy", csp);
+  res.headers.set("Strict-Transport-Security", "max-age=63072000; includeSubDomains; preload");
+  res.headers.set("X-Content-Type-Options", "nosniff");
+  res.headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+  return res;
+}
+```
+
+```tsx
+// read the nonce in a layout and pass it to any inline script
+import { headers } from "next/headers";
+import Script from "next/script";
+
+export default async function Layout({ children }: { children: React.ReactNode }) {
+  const nonce = (await headers()).get("x-nonce") ?? undefined;
+  return (
+    <>
+      {children}
+      <Script id="analytics" nonce={nonce} strategy="afterInteractive">
+        {`/* inline analytics bootstrap */`}
+      </Script>
+    </>
+  );
+}
+```
+
+## Cookies
+
+Set session cookies `httpOnly`, `secure`, `sameSite: "lax"`. Rotate the session on any privilege
+change (login, role elevation, password change) to prevent fixation.
+
+```ts
+import { cookies } from "next/headers";
+
+export async function setSession(token: string) {
+  (await cookies()).set("session", token, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: 60 * 60 * 24 * 7,
+  });
+}
+```
+
+## See Also
+
+Complements `../secure-coding/SKILL.md` (generic). This file is the Next.js-specific layer; for the
+auth wiring and DAL pattern in context see the "Auth" section of `../nextjs/SKILL.md` and
+`data-and-caching.md`.

package/skills/nextjs/references/testing.md

@@ -0,0 +1,290 @@
+# Testing Next.js — Vitest 3, RTL, MSW 2, Playwright
+
+Deep dive behind the "Verify" workflow. The core reality: **async Server Components are not
+reliably renderable in jsdom**, so unit-test the data/logic functions and Server Actions, and cover
+rendered pages with Playwright e2e.
+
+## Stack & config
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+  test: {
+    environment: "jsdom",
+    globals: true,
+    setupFiles: ["./vitest.setup.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "html"],
+      thresholds: { lines: 80, functions: 80, branches: 75, statements: 80 },
+    },
+  },
+});
+```
+
+```ts
+// vitest.setup.ts
+import "@testing-library/jest-dom/vitest";
+import { cleanup } from "@testing-library/react";
+import { afterEach } from "vitest";
+
+afterEach(() => cleanup());
+```
+
+In unit tests you must mock Next's request-bound modules — `next/navigation` (`useRouter`,
+`redirect`, `notFound`) and `next/headers` (`cookies`, `headers`) — because they have no real
+request context under Vitest:
+
+```ts
+import { vi } from "vitest";
+vi.mock("next/navigation", () => ({
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn() }),
+  redirect: vi.fn(),
+  notFound: vi.fn(),
+}));
+```
+
+## RTL behavior testing
+
+Query by **role/label first**; `getByTestId` is the last resort. Create `userEvent` once per test;
+use async `findBy`/`waitFor` for anything that appears after an interaction.
+
+```tsx
+// test-utils.tsx — render wrapper with the app providers
+import { render, type RenderOptions } from "@testing-library/react";
+import { type ReactElement, type ReactNode } from "react";
+import { ThemeCtx } from "@/components/theme";
+
+function Providers({ children }: { children: ReactNode }) {
+  return <ThemeCtx value="light">{children}</ThemeCtx>;
+}
+
+export function renderWithProviders(ui: ReactElement, options?: RenderOptions) {
+  return render(ui, { wrapper: Providers, ...options });
+}
+export * from "@testing-library/react";
+```
+
+```tsx
+// signup-form.test.tsx
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { expect, test, vi } from "vitest";
+import { renderWithProviders } from "./test-utils";
+import { SignupForm } from "@/app/signup/form";
+
+vi.mock("@/app/signup/actions", () => ({
+  signup: vi.fn(async () => ({ status: "error", fieldErrors: { email: "Already registered" } })),
+}));
+
+test("shows a field error returned by the action", async () => {
+  const user = userEvent.setup();
+  renderWithProviders(<SignupForm />);
+  await user.type(screen.getByLabelText(/email/i), "taken@example.com");
+  await user.type(screen.getByLabelText(/password/i), "longenough");
+  await user.click(screen.getByRole("button", { name: /sign up/i }));
+  expect(await screen.findByText(/already registered/i)).toBeInTheDocument();
+});
+```
+
+## MSW 2
+
+MSW 2 uses `http` + `HttpResponse` (the old `rest` API is gone). Fail loudly on unmocked requests.
+
+```ts
+// mocks/server.ts
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+
+export const handlers = [
+  http.get("https://api.example.com/products", () =>
+    HttpResponse.json([{ id: "p1", name: "Widget" }]),
+  ),
+];
+export const server = setupServer(...handlers);
+```
+
+```ts
+// vitest.setup.ts (append)
+import { afterAll, afterEach, beforeAll } from "vitest";
+import { server } from "./mocks/server";
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+```ts
+// per-test override: force the products endpoint to 500
+import { http, HttpResponse } from "msw";
+import { server } from "./mocks/server";
+
+server.use(
+  http.get("https://api.example.com/products", () =>
+    HttpResponse.json({ error: "boom" }, { status: 500 }),
+  ),
+);
+```
+
+## Testing Server Actions
+
+`"use server"` files run server-side — test the **function**, not a rendered tree. Call it with a
+`FormData`, mock `auth()` and the DB, and assert the typed result plus that invalidation fired.
+
+```ts
+// signup.action.test.ts
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@/lib/db", () => ({
+  db: { user: { findUnique: vi.fn(async () => null), create: vi.fn(async () => ({ id: "u1" })) } },
+}));
+vi.mock("next/cache", () => ({ revalidateTag: vi.fn() }));
+
+import { signup } from "@/app/signup/actions";
+import { db } from "@/lib/db";
+
+function fd(obj: Record<string, string>) {
+  const f = new FormData();
+  for (const [k, v] of Object.entries(obj)) f.set(k, v);
+  return f;
+}
+
+describe("signup action", () => {
+  it("returns field errors for invalid input", async () => {
+    const res = await signup({ status: "idle" }, fd({ email: "nope", password: "x" }));
+    expect(res.status).toBe("error");
+    expect(res.fieldErrors?.email).toBeDefined();
+  });
+
+  it("creates the user on valid input", async () => {
+    const res = await signup({ status: "idle" }, fd({ email: "a@b.com", password: "longenough" }));
+    expect(res.status).toBe("ok");
+    expect(db.user.create).toHaveBeenCalledOnce();
+  });
+});
+```
+
+For an action that mutates and revalidates, also `expect(revalidateTag).toHaveBeenCalledWith("posts")`.
+
+## Testing Route Handlers
+
+Import the exported `GET`/`POST` and invoke with a real `Request`; assert status and JSON.
+
+```ts
+// route.test.ts
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("@/auth", () => ({ auth: vi.fn(async () => ({ user: { id: "u1" } })) }));
+vi.mock("@/lib/db", () => ({
+  db: { project: { create: vi.fn(async () => ({ id: "p1", name: "X" })) } },
+}));
+
+import { POST } from "@/app/api/projects/route";
+
+describe("POST /api/projects", () => {
+  it("creates a project (201)", async () => {
+    const req = new Request("http://localhost/api/projects", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "X" }),
+    });
+    const res = await POST(req as never);
+    expect(res.status).toBe(201);
+    expect(await res.json()).toMatchObject({ project: { id: "p1" } });
+  });
+});
+```
+
+## RSC caveat
+
+**Async Server Components are NOT reliably renderable in jsdom.** Do not snapshot or `render()` an
+`async function Page()`. Instead: unit-test the data functions it calls (e.g. `getProject`), unit-test
+its client islands in isolation, and assert the composed, rendered page through Playwright e2e.
+
+## Playwright e2e
+
+```ts
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  use: { baseURL: "http://localhost:3000" },
+  webServer: {
+    command: "next build && next start",
+    url: "http://localhost:3000",
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+});
+```
+
+```ts
+// e2e/rename.spec.ts — login → submit a form action → assert the revalidated UI
+import { expect, test } from "@playwright/test";
+
+test("renaming a project updates the list", async ({ page }) => {
+  await page.goto("/login");
+  await page.getByLabel(/email/i).fill("user@example.com");
+  await page.getByLabel(/password/i).fill("password123");
+  await page.getByRole("button", { name: /sign in/i }).click();
+
+  await page.goto("/projects/p1");
+  await page.getByLabel(/project name/i).fill("Renamed");
+  await page.getByRole("button", { name: /save/i }).click();
+  await expect(page.getByRole("heading", { name: "Renamed" })).toBeVisible();
+});
+```
+
+```ts
+// stub network at the browser level when needed
+await page.route("**/api/notifications", (route) =>
+  route.fulfill({ json: { count: 0 } }),
+);
+```
+
+```ts
+// e2e/a11y.spec.ts — accessibility smoke with @axe-core/playwright
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+test("home page has no critical a11y violations", async ({ page }) => {
+  await page.goto("/");
+  const results = await new AxeBuilder({ page }).analyze();
+  expect(results.violations.filter((v) => v.impact === "critical")).toEqual([]);
+});
+```
+
+## Coverage targets & commands
+
+| Layer                       | Target | Tooling          |
+| --------------------------- | ------ | ---------------- |
+| Utilities / pure functions  | ≥ 90%  | Vitest           |
+| Hooks                       | ≥ 85%  | Vitest + RTL     |
+| Presentational components   | ≥ 80%  | Vitest + RTL     |
+| Container / stateful comps  | ≥ 70%  | Vitest + RTL     |
+| Pages (RSC) & full flows    | e2e    | Playwright       |
+
+```bash
+vitest run                 # unit + integration, once
+vitest run --coverage      # with v8 coverage thresholds
+playwright test            # e2e (builds + starts the app via webServer)
+```
+
+## Anti-patterns
+
+- `container.querySelector(...)` instead of role/label queries — tests implementation, not behavior.
+- Asserting render counts or internal state — brittle; assert what the user sees.
+- Mocking React itself — mock the network (MSW) and the DB/`auth` modules instead.
+- Ignoring `act(...)` warnings — they signal an unawaited update; fix with `findBy`/`waitFor`.
+- Snapshotting an RSC page — async Server Components are not jsdom-renderable; use Playwright.
+
+## See Also
+
+- `react.md` — the components and hooks under test.
+- `data-and-caching.md` — the Server Actions and data functions these tests target.

package/skills/nextjs/scripts/verify.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# verify.sh — Next.js App Router project gate.
+#
+# Usage:
+#   bash scripts/verify.sh            # run from the Next.js project root
+#
+# What it does (in order): ESLint -> tsc --noEmit -> Vitest -> next build.
+# Each tool is detected; if it is not installed/resolvable, it is skipped with a
+# yellow warning (NOT a failure). Exits non-zero only on a real tool failure.
+#
+# Side effects: the lint / type-check / test steps are read-only. The final
+# `next build` WRITES the `.next/` output directory (and may write `tsconfig.json`
+# / `next-env.d.ts` defaults) — it is not a pure read-only step. It performs no
+# installs and no network mutations. Safe to re-run.
+#
+# Portability: targets stock macOS bash 3.2. We avoid `mapfile`, never expand a
+# possibly-empty array under `set -u`, and degrade gracefully when a tool is
+# missing. `set -e` is intentionally NOT used (each check handles its own exit
+# code); `set -u` is on, with arrays initialised before use.
+
+set -u
+
+# --- colors (only when stdout is a TTY) -----------------------------------
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+# Space-separated list (portable to bash 3.2; avoids empty-array expansion under set -u).
+skips=""
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s\n' "${YELLOW}SKIP: $1${RESET}"; skips="${skips}${skips:+ }$2"; return 0; }
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- resolve a package runner from the lockfile ----------------------------
+RUN=""
+if [ -f pnpm-lock.yaml ] && have pnpm; then
+  RUN="pnpm exec"
+elif [ -f yarn.lock ] && have yarn; then
+  RUN="yarn"
+elif [ -f package-lock.json ] && have npm; then
+  RUN="npm exec --"
+elif have npx; then
+  RUN="npx --no-install"
+fi
+
+run_bin() {
+  # run_bin <bin-name> <args...> : true if the bin is resolvable and runs
+  bin="$1"; shift
+  if have "$bin"; then "$bin" "$@"; return $?; fi
+  if [ -x "node_modules/.bin/$bin" ]; then "node_modules/.bin/$bin" "$@"; return $?; fi
+  if [ -n "$RUN" ]; then $RUN "$bin" "$@"; return $?; fi
+  return 127
+}
+
+bin_available() {
+  bin="$1"
+  have "$bin" && return 0
+  [ -x "node_modules/.bin/$bin" ] && return 0
+  return 1
+}
+
+# Detect the installed Next.js MAJOR version from package.json (best-effort,
+# bash-3.2 safe: no jq, no node required). Echoes a bare integer, or nothing.
+next_major() {
+  [ -f node_modules/next/package.json ] || return 0
+  # grep the "version": "x.y.z" line, then strip to the leading major integer.
+  ver="$(grep -m1 '"version"' node_modules/next/package.json 2>/dev/null \
+         | sed -e 's/.*"version"[^0-9]*//' -e 's/[^0-9].*//')"
+  [ -n "$ver" ] && printf '%s' "$ver"
+}
+
+# --- 1. ESLint -------------------------------------------------------------
+# `next lint` was REMOVED in Next.js 16 (and `next build` no longer lints).
+# So the fallback to `next lint` is only valid on v15 and earlier — on v16+ a
+# missing eslint must be a SKIP, never a FAIL (a v16 repo cannot pass a command
+# that no longer exists).
+if bin_available eslint; then
+  printf '%s\n' "Running ESLint..."
+  if run_bin eslint .; then ok "eslint"; else fail "eslint"; fi
+else
+  nxmajor="$(next_major)"
+  if bin_available next && [ -n "$nxmajor" ] && [ "$nxmajor" -lt 16 ] 2>/dev/null; then
+    printf '%s\n' "Running next lint... (eslint not resolvable; Next.js < 16 fallback)"
+    if run_bin next lint; then ok "next lint"; else fail "next lint"; fi
+  elif bin_available next && [ -n "$nxmajor" ]; then
+    warn "eslint not resolvable; next lint removed in Next.js ${nxmajor} — skipping lint" "eslint"
+  else
+    warn "eslint not resolvable — skipping lint" "eslint"
+  fi
+fi
+
+# --- 2. TypeScript ---------------------------------------------------------
+if bin_available tsc && [ -f tsconfig.json ]; then
+  printf '%s\n' "Running tsc --noEmit..."
+  if run_bin tsc --noEmit; then ok "tsc --noEmit"; else fail "tsc --noEmit"; fi
+else
+  warn "tsc or tsconfig.json missing — skipping type check" "tsc"
+fi
+
+# --- 3. Vitest -------------------------------------------------------------
+# Only treat the repo as having Vitest unit tests when a vitest config exists OR
+# `*.test.*` files exist. Playwright e2e uses `*.spec.*` (typically under e2e/),
+# which Vitest must NOT pick up — so `.spec.*` files alone do not trigger Vitest.
+has_tests=false
+if ls vitest.config.* vitest.workspace.* >/dev/null 2>&1; then
+  has_tests=true
+elif find . \( -name node_modules -o -name .next -o -name dist \) -prune -o \
+       -name '*.test.*' -print 2>/dev/null | grep -q .; then
+  has_tests=true
+fi
+if bin_available vitest && [ "$has_tests" = true ]; then
+  printf '%s\n' "Running vitest run..."
+  if run_bin vitest run; then ok "vitest"; else fail "vitest"; fi
+else
+  warn "vitest or unit tests (vitest.config.* / *.test.*) not present — skipping unit tests" "vitest"
+fi
+
+# --- 4. next build (slow; WRITES .next/; run last) -------------------------
+if bin_available next; then
+  printf '%s\n' "Running next build... (writes .next/; Turbopack is the default builder on Next.js 16)"
+  if run_bin next build; then ok "next build"; else fail "next build"; fi
+else
+  warn "next not resolvable — skipping build" "next build"
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\n'
+if [ -n "$skips" ]; then
+  printf '%s\n' "${YELLOW}skipped: ${skips}${RESET}"
+fi
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}verify.sh: $failures check(s) failed${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}verify.sh: all runnable checks passed${RESET}"
+exit 0