@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/next-cache-components/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: next-cache-components
+description: "Use only for Next.js 16 Cache Components and PPR implementation (use cache, cacheLife, cacheTag, updateTag, Suspense boundaries)."
+---
+
+# Cache Components (Next.js 16+)
+
+Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.
+
+## Enable Cache Components
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+}
+
+export default nextConfig
+```
+
+This replaces the old `experimental.ppr` flag.
+
+---
+
+## Three Content Types
+
+With Cache Components enabled, content falls into three categories:
+
+### 1. Static (Auto-Prerendered)
+
+Synchronous code, imports, pure computations - prerendered at build time:
+
+```tsx
+export default function Page() {
+  return (
+    <header>
+      <h1>Our Blog</h1>  {/* Static - instant */}
+      <nav>...</nav>
+    </header>
+  )
+}
+```
+
+### 2. Cached (`use cache`)
+
+Async data that doesn't need fresh fetches every request:
+
+```tsx
+async function BlogPosts() {
+  'use cache'
+  cacheLife('hours')
+
+  const posts = await db.posts.findMany()
+  return <PostList posts={posts} />
+}
+```
+
+### 3. Dynamic (Suspense)
+
+Runtime data that must be fresh - wrap in Suspense:
+
+```tsx
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <>
+      <BlogPosts />  {/* Cached */}
+
+      <Suspense fallback={<p>Loading...</p>}>
+        <UserPreferences />  {/* Dynamic - streams in */}
+      </Suspense>
+    </>
+  )
+}
+
+async function UserPreferences() {
+  const theme = (await cookies()).get('theme')?.value
+  return <p>Theme: {theme}</p>
+}
+```
+
+---
+
+## `use cache` Directive
+
+### File Level
+
+```tsx
+'use cache'
+
+export default async function Page() {
+  // Entire page is cached
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Component Level
+
+```tsx
+export async function CachedComponent() {
+  'use cache'
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Function Level
+
+```tsx
+export async function getData() {
+  'use cache'
+  return db.query('SELECT * FROM posts')
+}
+```
+
+---
+
+## Cache Profiles
+
+### Built-in Profiles
+
+```tsx
+'use cache'                    // Default: 5m stale, 15m revalidate
+```
+
+```tsx
+'use cache: remote'           // Platform-provided cache (Redis, KV)
+```
+
+```tsx
+'use cache: private'          // For compliance, allows runtime APIs
+```
+
+### `cacheLife()` - Custom Lifetime
+
+```tsx
+import { cacheLife } from 'next/cache'
+
+async function getData() {
+  'use cache'
+  cacheLife('hours')  // Built-in profile
+  return fetch('/api/data')
+}
+```
+
+Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`
+
+### Inline Configuration
+
+```tsx
+async function getData() {
+  'use cache'
+  cacheLife({
+    stale: 3600,      // 1 hour - serve stale while revalidating
+    revalidate: 7200, // 2 hours - background revalidation interval
+    expire: 86400,    // 1 day - hard expiration
+  })
+  return fetch('/api/data')
+}
+```
+
+---
+
+## Cache Invalidation
+
+### `cacheTag()` - Tag Cached Content
+
+```tsx
+import { cacheTag } from 'next/cache'
+
+async function getProducts() {
+  'use cache'
+  cacheTag('products')
+  return db.products.findMany()
+}
+
+async function getProduct(id: string) {
+  'use cache'
+  cacheTag('products', `product-${id}`)
+  return db.products.findUnique({ where: { id } })
+}
+```
+
+### `updateTag()` - Immediate Invalidation
+
+Use when you need the cache refreshed within the same request:
+
+```tsx
+'use server'
+
+import { updateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: FormData) {
+  await db.products.update({ where: { id }, data })
+  updateTag(`product-${id}`)  // Immediate - same request sees fresh data
+}
+```
+
+### `revalidateTag()` - Background Revalidation
+
+Use for stale-while-revalidate behavior:
+
+```tsx
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function createPost(data: FormData) {
+  await db.posts.create({ data })
+  revalidateTag('posts')  // Background - next request sees fresh data
+}
+```
+
+---
+
+## Runtime Data Constraint
+
+**Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`.
+
+### Solution: Pass as Arguments
+
+```tsx
+// Wrong - runtime API inside use cache
+async function CachedProfile() {
+  'use cache'
+  const session = (await cookies()).get('session')?.value  // Error!
+  return <div>{session}</div>
+}
+
+// Correct - extract outside, pass as argument
+async function ProfilePage() {
+  const session = (await cookies()).get('session')?.value
+  return <CachedProfile sessionId={session} />
+}
+
+async function CachedProfile({ sessionId }: { sessionId: string }) {
+  'use cache'
+  // sessionId becomes part of cache key automatically
+  const data = await fetchUserData(sessionId)
+  return <div>{data.name}</div>
+}
+```
+
+### Exception: `use cache: private`
+
+For compliance requirements when you can't refactor:
+
+```tsx
+async function getData() {
+  'use cache: private'
+  const session = (await cookies()).get('session')?.value  // Allowed
+  return fetchData(session)
+}
+```
+
+---
+
+## Cache Key Generation
+
+Cache keys are automatic based on:
+- **Build ID** - invalidates all caches on deploy
+- **Function ID** - hash of function location
+- **Serializable arguments** - props become part of key
+- **Closure variables** - outer scope values included
+
+```tsx
+async function Component({ userId }: { userId: string }) {
+  const getData = async (filter: string) => {
+    'use cache'
+    // Cache key = userId (closure) + filter (argument)
+    return fetch(`/api/users/${userId}?filter=${filter}`)
+  }
+  return getData('active')
+}
+```
+
+---
+
+## Complete Example
+
+```tsx
+import { Suspense } from 'react'
+import { cookies } from 'next/headers'
+import { cacheLife, cacheTag } from 'next/cache'
+
+export default function DashboardPage() {
+  return (
+    <>
+      {/* Static shell - instant from CDN */}
+      <header><h1>Dashboard</h1></header>
+      <nav>...</nav>
+
+      {/* Cached - fast, revalidates hourly */}
+      <Stats />
+
+      {/* Dynamic - streams in with fresh data */}
+      <Suspense fallback={<NotificationsSkeleton />}>
+        <Notifications />
+      </Suspense>
+    </>
+  )
+}
+
+async function Stats() {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('dashboard-stats')
+
+  const stats = await db.stats.aggregate()
+  return <StatsDisplay stats={stats} />
+}
+
+async function Notifications() {
+  const userId = (await cookies()).get('userId')?.value
+  const notifications = await db.notifications.findMany({
+    where: { userId, read: false }
+  })
+  return <NotificationList items={notifications} />
+}
+```
+
+---
+
+## Migration from Previous Versions
+
+| Old Config | Replacement |
+|-----------|-------------|
+| `experimental.ppr` | `cacheComponents: true` |
+| `dynamic = 'force-dynamic'` | Remove (default behavior) |
+| `dynamic = 'force-static'` | `'use cache'` + `cacheLife('max')` |
+| `revalidate = N` | `cacheLife({ revalidate: N })` |
+| `unstable_cache()` | `'use cache'` directive |
+
+---
+
+## Limitations
+
+- **Edge runtime not supported** - requires Node.js
+- **Static export not supported** - needs server
+- **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache`
+
+For request-time randomness outside cache:
+
+```tsx
+import { connection } from 'next/server'
+
+async function DynamicContent() {
+  await connection()  // Defer to request time
+  const id = crypto.randomUUID()  // Different per request
+  return <div>{id}</div>
+}
+```
+
+Sources:
+- [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components)
+- [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/next-upgrade/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: next-upgrade
+description: "Use only for upgrading Next.js versions with official migration guides and codemods; includes dependency/version planning and upgrade validation."
+metadata:
+  argument-hint: "[target-version]"
+---
+
+# Upgrade Next.js
+
+Upgrade the current project to the latest Next.js version following official migration guides.
+
+## Instructions
+
+1. **Detect current version**: Read `package.json` to identify the current Next.js version and related dependencies (React, React DOM, etc.)
+
+2. **Fetch the latest upgrade guide**: Use WebFetch to get the official upgrade documentation:
+   - Codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
+   - Version-specific guides (adjust version as needed):
+     - https://nextjs.org/docs/app/guides/upgrading/version-16 
+     - https://nextjs.org/docs/app/guides/upgrading/version-15
+     - https://nextjs.org/docs/app/guides/upgrading/version-14
+
+3. **Determine upgrade path**: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).
+
+4. **Run codemods first**: Next.js provides codemods to automate breaking changes:
+   ```bash
+   npx @next/codemod@latest <transform> <path>
+   ```
+   Common transforms:
+   - `next-async-request-api` - Updates async Request APIs (v15)
+   - `next-request-geo-ip` - Migrates geo/ip properties (v15)
+   - `next-dynamic-access-named-export` - Transforms dynamic imports (v15)
+
+5. **Update dependencies**: Upgrade Next.js and peer dependencies together:
+   ```bash
+   npm install next@latest react@latest react-dom@latest
+   ```
+
+6. **Review breaking changes**: Check the upgrade guide for manual changes needed:
+   - API changes (e.g., async params in v15)
+   - Configuration changes in `next.config.js`
+   - Deprecated features being removed
+
+7. **Update TypeScript types** (if applicable):
+   ```bash
+   npm install @types/react@latest @types/react-dom@latest
+   ```
+
+8. **Test the upgrade**:
+   - Run `npm run build` to check for build errors
+   - Run `npm run dev` and test key functionality

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

@@ -0,0 +1,59 @@
+---
+name: "nextjs-developer"
+displayName: "Next.js Developer"
+description: "Use for implementing/refactoring Next.js App Router features, React Server Components/Actions, SEO, and production architecture."
+license: MIT
+metadata:
+  version: "2.0.0"
+  domain: "frontend"
+  role: "specialist"
+  stack: "nextjs"
+  baseline: "Next.js 16 + React 19"
+---
+
+# Next.js Developer
+
+## Scope
+
+- Primary skill for App Router implementation and refactors.
+- Not for version migration playbooks (`next-upgrade`) or cache-components-only tuning (`next-cache-components`).
+
+## When to use
+
+- Building routes/layouts/loading/error boundaries.
+- Implementing server components and server actions.
+- Designing data fetching/revalidation strategy.
+- Improving SEO and web vitals.
+
+## Core workflow
+
+1. Define rendering mode per route (static/dynamic/streaming).
+2. Keep server/client component boundaries explicit.
+3. Implement data access with caching semantics by intent.
+4. Add forms/actions with validation and auth checks.
+5. Verify perf, accessibility, and error handling.
+
+## Baseline standards
+
+- Default to Server Components; opt into client components only when needed.
+- Keep server-only code out of client bundles.
+- Use route-level loading/error states.
+- Use metadata API and structured data for SEO.
+- Measure Core Web Vitals and act on regressions.
+
+## Avoid
+
+- Unnecessary client hydration.
+- Mixing auth-sensitive logic into client-only paths.
+- Overusing global revalidation when targeted invalidation is possible.
+
+## Reference files
+
+- `references/app-router.md`
+- `references/server-components.md`
+- `references/server-actions.md`
+- `references/data-fetching.md`
+- `references/performance.md`
+- `references/seo.md`
+- `references/deployment.md`
+- `references/testing.md`

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-developer/references/app-router.md

@@ -0,0 +1,218 @@
+# App Router Architecture
+
+## File Conventions
+
+| File            | Purpose                                                 |
+| --------------- | ------------------------------------------------------- |
+| `layout.tsx`    | Shared UI, persists across navigations, wraps children  |
+| `template.tsx`  | Like layout but re-mounts on navigation (new instance)  |
+| `page.tsx`      | Unique UI for a route, makes route publicly accessible  |
+| `loading.tsx`   | Loading UI using Suspense boundary                      |
+| `error.tsx`     | Error boundary for the segment                          |
+| `not-found.tsx` | 404 UI for the segment                                  |
+| `route.ts`      | API endpoint (cannot coexist with page.tsx in same dir) |
+
+## Layout Patterns
+
+```tsx
+// Root layout — required, wraps entire app
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+
+// Nested layout — wraps a segment and its children
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">{children}</main>
+    </div>
+  );
+}
+```
+
+### Layout Rules
+
+- Root layout must contain `<html>` and `<body>` tags
+- Layouts do NOT re-render when navigating between child routes
+- Layouts cannot access `pathname` — use `usePathname()` in a Client Component
+- Data fetched in a layout is NOT passed to children — fetch in each segment
+
+## Route Groups
+
+Group routes without affecting the URL structure using `(folderName)`:
+
+```
+app/
+├── (marketing)/
+│   ├── layout.tsx      # Marketing layout
+│   ├── about/page.tsx  # /about
+│   └── blog/page.tsx   # /blog
+├── (shop)/
+│   ├── layout.tsx      # Shop layout
+│   ├── products/page.tsx  # /products
+│   └── cart/page.tsx      # /cart
+└── layout.tsx          # Root layout
+```
+
+Use cases:
+
+- Different layouts for different sections
+- Organizing routes by team or feature
+- Opting specific segments into a layout
+
+## Parallel Routes
+
+Render multiple pages simultaneously in the same layout using named slots (`@folder`):
+
+```tsx
+// app/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  team: React.ReactNode;
+}) {
+  return (
+    <>
+      {children}
+      {analytics}
+      {team}
+    </>
+  );
+}
+```
+
+```
+app/
+├── layout.tsx
+├── page.tsx
+├── @analytics/
+│   └── page.tsx
+└── @team/
+    └── page.tsx
+```
+
+### Parallel Route Rules
+
+- Slots are NOT route segments — `@analytics` doesn't affect the URL
+- Each slot can have its own `loading.tsx` and `error.tsx`
+- Use `default.tsx` in slots to handle unmatched routes
+
+## Intercepting Routes
+
+Intercept a route to show it in the current layout while preserving context:
+
+| Convention | Matches       |
+| ---------- | ------------- |
+| `(.)`      | Same level    |
+| `(..)`     | One level up  |
+| `(..)(..)` | Two levels up |
+| `(...)`    | From root     |
+
+```
+app/
+├── feed/
+│   ├── page.tsx
+│   └── (..)photo/[id]/page.tsx  # Intercepts /photo/[id] from /feed
+└── photo/
+    └── [id]/page.tsx            # Full page when accessed directly
+```
+
+Common pattern: modal on click, full page on direct URL or refresh.
+
+## Dynamic Routes
+
+```tsx
+// app/blog/[slug]/page.tsx — dynamic segment
+export default function Post({ params }: { params: { slug: string } }) {
+  return <h1>{params.slug}</h1>;
+}
+
+// app/shop/[...categories]/page.tsx — catch-all
+// Matches /shop/a, /shop/a/b, /shop/a/b/c
+export default function Category({
+  params,
+}: {
+  params: { categories: string[] };
+}) {
+  return <div>{params.categories.join(" > ")}</div>;
+}
+
+// app/shop/[[...categories]]/page.tsx — optional catch-all
+// Also matches /shop (without segments)
+```
+
+## Static Generation for Dynamic Routes
+
+```tsx
+// Generate static params at build time
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+
+// dynamicParams = false → return 404 for unknown params
+export const dynamicParams = false;
+```
+
+## Route Handlers (API Routes)
+
+```tsx
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(request: NextRequest) {
+  const posts = await db.post.findMany();
+  return NextResponse.json(posts);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const post = await db.post.create({ data: body });
+  return NextResponse.json(post, { status: 201 });
+}
+```
+
+### Route Handler Rules
+
+- Cannot coexist with `page.tsx` in the same route segment
+- Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+- `GET` handlers are cached by default when not using `Request` object
+- Use `NextRequest` for access to cookies, headers, URL search params
+
+## Middleware
+
+```tsx
+// middleware.ts (at project root)
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  // Auth check
+  const token = request.cookies.get("token");
+  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+};
+```