@cubis/foundry 0.3.67 → 0.3.69

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

@@ -1,360 +0,0 @@
----
-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

@@ -1,51 +0,0 @@
----
-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/references/app-router.md

@@ -1,218 +0,0 @@
-# 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*"],
-};
-```