@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/nextjs-developer/references/seo.md

@@ -0,0 +1,290 @@
+# SEO Implementation
+
+## Metadata API
+
+### Static Metadata
+
+```tsx
+// app/layout.tsx or app/page.tsx
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: {
+    default: "My App",
+    template: "%s | My App", // Child pages: "About | My App"
+  },
+  description: "A description of my app",
+  metadataBase: new URL("https://myapp.com"),
+  openGraph: {
+    title: "My App",
+    description: "A description of my app",
+    url: "https://myapp.com",
+    siteName: "My App",
+    images: [
+      {
+        url: "/og.png",
+        width: 1200,
+        height: 630,
+        alt: "My App",
+      },
+    ],
+    locale: "en_US",
+    type: "website",
+  },
+  twitter: {
+    card: "summary_large_image",
+    title: "My App",
+    description: "A description of my app",
+    images: ["/og.png"],
+  },
+  robots: {
+    index: true,
+    follow: true,
+    googleBot: {
+      index: true,
+      follow: true,
+      "max-video-preview": -1,
+      "max-image-preview": "large",
+      "max-snippet": -1,
+    },
+  },
+};
+```
+
+### Dynamic Metadata
+
+```tsx
+// app/blog/[slug]/page.tsx
+import type { Metadata } from "next";
+
+type Props = { params: { slug: string } };
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const post = await getPost(params.slug);
+
+  return {
+    title: post.title,
+    description: post.excerpt,
+    openGraph: {
+      title: post.title,
+      description: post.excerpt,
+      images: [post.coverImage],
+      type: "article",
+      publishedTime: post.publishedAt,
+      authors: [post.author.name],
+    },
+  };
+}
+```
+
+## Sitemap
+
+### Static Sitemap
+
+```tsx
+// app/sitemap.ts
+import type { MetadataRoute } from "next";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return [
+    {
+      url: "https://myapp.com",
+      lastModified: new Date(),
+      changeFrequency: "yearly",
+      priority: 1,
+    },
+    {
+      url: "https://myapp.com/about",
+      lastModified: new Date(),
+      changeFrequency: "monthly",
+      priority: 0.8,
+    },
+    {
+      url: "https://myapp.com/blog",
+      lastModified: new Date(),
+      changeFrequency: "weekly",
+      priority: 0.5,
+    },
+  ];
+}
+```
+
+### Dynamic Sitemap
+
+```tsx
+// app/sitemap.ts
+import type { MetadataRoute } from "next";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const posts = await db.post.findMany({
+    select: { slug: true, updatedAt: true },
+  });
+
+  const postUrls = posts.map((post) => ({
+    url: `https://myapp.com/blog/${post.slug}`,
+    lastModified: post.updatedAt,
+    changeFrequency: "weekly" as const,
+    priority: 0.6,
+  }));
+
+  return [
+    { url: "https://myapp.com", lastModified: new Date(), priority: 1 },
+    ...postUrls,
+  ];
+}
+```
+
+## Robots.txt
+
+```tsx
+// app/robots.ts
+import type { MetadataRoute } from "next";
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      {
+        userAgent: "*",
+        allow: "/",
+        disallow: ["/admin/", "/api/", "/private/"],
+      },
+    ],
+    sitemap: "https://myapp.com/sitemap.xml",
+  };
+}
+```
+
+## Structured Data (JSON-LD)
+
+```tsx
+// app/blog/[slug]/page.tsx
+export default async function BlogPost({
+  params,
+}: {
+  params: { slug: string };
+}) {
+  const post = await getPost(params.slug);
+
+  const jsonLd = {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    headline: post.title,
+    description: post.excerpt,
+    image: post.coverImage,
+    datePublished: post.publishedAt,
+    dateModified: post.updatedAt,
+    author: {
+      "@type": "Person",
+      name: post.author.name,
+    },
+  };
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
+      />
+      <article>
+        <h1>{post.title}</h1>
+        <div dangerouslySetInnerHTML={{ __html: post.content }} />
+      </article>
+    </>
+  );
+}
+```
+
+## Dynamic OG Images
+
+```tsx
+// app/api/og/route.tsx
+import { ImageResponse } from "next/og";
+
+export const runtime = "edge";
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const title = searchParams.get("title") ?? "My App";
+
+  return new ImageResponse(
+    <div
+      style={{
+        fontSize: 60,
+        background: "linear-gradient(to bottom, #1a1a2e, #16213e)",
+        color: "white",
+        width: "100%",
+        height: "100%",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        padding: 40,
+      }}
+    >
+      {title}
+    </div>,
+    { width: 1200, height: 630 },
+  );
+}
+
+// Reference in metadata
+export const metadata: Metadata = {
+  openGraph: {
+    images: ["/api/og?title=My+Page"],
+  },
+};
+```
+
+## Canonical URLs
+
+```tsx
+export const metadata: Metadata = {
+  alternates: {
+    canonical: "https://myapp.com/blog/my-post",
+    languages: {
+      "en-US": "https://myapp.com/en/blog/my-post",
+      "es-ES": "https://myapp.com/es/blog/my-post",
+    },
+  },
+};
+```
+
+## International SEO
+
+```tsx
+// app/[lang]/layout.tsx
+export async function generateStaticParams() {
+  return [{ lang: "en" }, { lang: "es" }, { lang: "fr" }];
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: { lang: string };
+}) {
+  return {
+    alternates: {
+      canonical: `https://myapp.com/${params.lang}`,
+      languages: {
+        en: "https://myapp.com/en",
+        es: "https://myapp.com/es",
+        fr: "https://myapp.com/fr",
+      },
+    },
+  };
+}
+```
+
+## SEO Checklist
+
+- [ ] Title and description on every page
+- [ ] Open Graph tags for social sharing
+- [ ] Twitter card meta tags
+- [ ] Sitemap generated and submitted
+- [ ] robots.txt configured
+- [ ] Structured data (JSON-LD) for content pages
+- [ ] Canonical URLs set
+- [ ] Dynamic OG images for key pages
+- [ ] Alt text on all images
+- [ ] Semantic HTML (h1-h6, article, nav, main)
+- [ ] Mobile-friendly (responsive)
+- [ ] Fast loading (Core Web Vitals passing)

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/nextjs-developer/references/server-actions.md

@@ -0,0 +1,259 @@
+# Server Actions
+
+## Overview
+
+Server Actions are async functions that run on the server, callable from both Server and Client Components. They replace traditional API routes for mutations.
+
+## Defining Server Actions
+
+### Inline (in Server Components)
+
+```tsx
+export default function Page() {
+  async function createPost(formData: FormData) {
+    "use server";
+    const title = formData.get("title") as string;
+    await db.post.create({ data: { title } });
+    revalidatePath("/posts");
+  }
+
+  return (
+    <form action={createPost}>
+      <input name="title" required />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+### Separate file (shareable across components)
+
+```tsx
+// app/actions.ts
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { redirect } from "next/navigation";
+import { z } from "zod";
+
+const CreatePostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+});
+
+export async function createPost(prevState: any, formData: FormData) {
+  const validated = CreatePostSchema.safeParse({
+    title: formData.get("title"),
+    content: formData.get("content"),
+  });
+
+  if (!validated.success) {
+    return { errors: validated.error.flatten().fieldErrors };
+  }
+
+  try {
+    await db.post.create({ data: validated.data });
+  } catch (e) {
+    return { message: "Failed to create post" };
+  }
+
+  revalidatePath("/posts");
+  redirect("/posts");
+}
+```
+
+## Form Handling with useActionState
+
+```tsx
+"use client";
+
+import { useActionState } from "react";
+import { createPost } from "./actions";
+
+export function CreatePostForm() {
+  const [state, formAction, isPending] = useActionState(createPost, {
+    errors: {},
+    message: "",
+  });
+
+  return (
+    <form action={formAction}>
+      <div>
+        <label htmlFor="title">Title</label>
+        <input id="title" name="title" required />
+        {state.errors?.title && (
+          <p className="text-red-500">{state.errors.title}</p>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="content">Content</label>
+        <textarea id="content" name="content" required />
+        {state.errors?.content && (
+          <p className="text-red-500">{state.errors.content}</p>
+        )}
+      </div>
+
+      {state.message && <p className="text-red-500">{state.message}</p>}
+
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Creating..." : "Create Post"}
+      </button>
+    </form>
+  );
+}
+```
+
+## Optimistic Updates
+
+```tsx
+"use client";
+
+import { useOptimistic } from "react";
+import { toggleLike } from "./actions";
+
+export function LikeButton({
+  isLiked,
+  count,
+}: {
+  isLiked: boolean;
+  count: number;
+}) {
+  const [optimistic, setOptimistic] = useOptimistic(
+    { isLiked, count },
+    (state, newIsLiked: boolean) => ({
+      isLiked: newIsLiked,
+      count: newIsLiked ? state.count + 1 : state.count - 1,
+    }),
+  );
+
+  return (
+    <form
+      action={async () => {
+        setOptimistic(!optimistic.isLiked);
+        await toggleLike();
+      }}
+    >
+      <button type="submit">
+        {optimistic.isLiked ? "❤️" : "🤍"} {optimistic.count}
+      </button>
+    </form>
+  );
+}
+```
+
+## Validation Patterns
+
+### With Zod
+
+```tsx
+"use server";
+
+import { z } from "zod";
+
+const UserSchema = z.object({
+  email: z.string().email("Invalid email"),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+  name: z.string().min(2, "Name must be at least 2 characters"),
+});
+
+export type FormState = {
+  errors?: Record<string, string[]>;
+  message?: string;
+  success?: boolean;
+};
+
+export async function registerUser(
+  prevState: FormState,
+  formData: FormData,
+): Promise<FormState> {
+  const validated = UserSchema.safeParse(Object.fromEntries(formData));
+
+  if (!validated.success) {
+    return { errors: validated.error.flatten().fieldErrors };
+  }
+
+  try {
+    await createUser(validated.data);
+    return { success: true, message: "Account created" };
+  } catch (e) {
+    if (e instanceof UniqueConstraintError) {
+      return { errors: { email: ["Email already exists"] } };
+    }
+    return { message: "Something went wrong" };
+  }
+}
+```
+
+## Security Best Practices
+
+```tsx
+"use server";
+
+import { auth } from "@/lib/auth";
+
+// Always verify authentication
+export async function deletePost(postId: string) {
+  const session = await auth();
+  if (!session) throw new Error("Unauthorized");
+
+  // Always verify authorization
+  const post = await db.post.findUnique({ where: { id: postId } });
+  if (post?.authorId !== session.user.id) throw new Error("Forbidden");
+
+  await db.post.delete({ where: { id: postId } });
+  revalidatePath("/posts");
+}
+
+// Never trust client input — always validate
+export async function updateProfile(formData: FormData) {
+  const session = await auth();
+  if (!session) throw new Error("Unauthorized");
+
+  // Validate and sanitize
+  const name = z.string().min(1).max(100).parse(formData.get("name"));
+
+  // Use session.user.id, never a client-provided userId
+  await db.user.update({
+    where: { id: session.user.id },
+    data: { name },
+  });
+}
+```
+
+## Revalidation After Mutations
+
+```tsx
+"use server";
+
+import { revalidatePath, revalidateTag } from "next/cache";
+
+export async function createPost(data: PostData) {
+  await db.post.create({ data });
+
+  // Revalidate specific path
+  revalidatePath("/posts");
+
+  // Revalidate by tag (for fetch-based caching)
+  revalidateTag("posts");
+
+  // Redirect after mutation
+  redirect("/posts");
+}
+```
+
+## Non-Form Usage
+
+```tsx
+"use client";
+
+import { publishPost } from "./actions";
+
+export function PublishButton({ postId }: { postId: string }) {
+  const handlePublish = async () => {
+    await publishPost(postId);
+  };
+
+  return <button onClick={handlePublish}>Publish</button>;
+}
+```