@cubis/foundry 0.3.82 → 0.3.84

package/workflows/skills/remix/examples/01-basic-usage.md

@@ -1,212 +0,0 @@
-# Example: Blog with Nested Routes, Loaders, and Progressive Forms
-
-## Scenario
-
-A team is building a content blog with Remix v2. The blog has a layout with a sidebar listing categories, a post list page, individual post pages loaded from a database, and an edit page for authors. The edit form must work without JavaScript for accessibility and resilience. Route-level error boundaries should handle missing posts gracefully.
-
-## Prompt
-
-"Create a Remix v2 blog with nested routes. The /blog layout shows a category sidebar. /blog lists recent posts. /blog/$slug shows a post loaded from the database. /blog/$slug/edit has a form for updating the post title and body with server-side Zod validation. The edit form must work without JavaScript. Add ErrorBoundary for missing posts."
-
-## Expected Output
-
-### Route Files (Flat File Convention)
-
-```
-app/routes/
-  blog.tsx           # Layout: sidebar + Outlet
-  blog._index.tsx    # Post list
-  blog.$slug.tsx     # Post detail
-  blog.$slug.edit.tsx # Edit form
-```
-
-### Layout Route
-
-```tsx
-// app/routes/blog.tsx
-import { json, type LoaderFunctionArgs } from "@remix-run/node";
-import { Outlet, useLoaderData, NavLink } from "@remix-run/react";
-import { getCategories } from "~/models/category.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const categories = await getCategories();
-  return json({ categories });
-}
-
-export default function BlogLayout() {
-  const { categories } = useLoaderData<typeof loader>();
-
-  return (
-    <div className="blog-layout">
-      <aside className="sidebar">
-        <h2>Categories</h2>
-        <nav>
-          {categories.map((cat) => (
-            <NavLink key={cat.slug} to={`/blog?category=${cat.slug}`}>
-              {cat.name}
-            </NavLink>
-          ))}
-        </nav>
-      </aside>
-      <main>
-        <Outlet />
-      </main>
-    </div>
-  );
-}
-```
-
-### Post Detail with ErrorBoundary
-
-```tsx
-// app/routes/blog.$slug.tsx
-import { json, type LoaderFunctionArgs } from "@remix-run/node";
-import { useLoaderData, useRouteError, isRouteErrorResponse, Outlet } from "@remix-run/react";
-import { getPostBySlug } from "~/models/post.server";
-
-export async function loader({ params }: LoaderFunctionArgs) {
-  const post = await getPostBySlug(params.slug!);
-  if (!post) {
-    throw new Response("Post not found", { status: 404 });
-  }
-  return json({ post });
-}
-
-export default function PostDetail() {
-  const { post } = useLoaderData<typeof loader>();
-
-  return (
-    <article>
-      <h1>{post.title}</h1>
-      <time dateTime={post.publishedAt}>{post.publishedAt}</time>
-      <div dangerouslySetInnerHTML={{ __html: post.htmlContent }} />
-      <Outlet />
-    </article>
-  );
-}
-
-export function ErrorBoundary() {
-  const error = useRouteError();
-
-  if (isRouteErrorResponse(error) && error.status === 404) {
-    return (
-      <div className="error-container">
-        <h1>Post Not Found</h1>
-        <p>The post you are looking for does not exist or has been removed.</p>
-      </div>
-    );
-  }
-
-  return (
-    <div className="error-container">
-      <h1>Something went wrong</h1>
-      <p>An unexpected error occurred while loading this post.</p>
-    </div>
-  );
-}
-```
-
-### Edit Form with Progressive Enhancement
-
-```tsx
-// app/routes/blog.$slug.edit.tsx
-import { json, redirect, type ActionFunctionArgs, type LoaderFunctionArgs } from "@remix-run/node";
-import { Form, useActionData, useLoaderData, useNavigation } from "@remix-run/react";
-import { z } from "zod";
-import { getPostBySlug, updatePost } from "~/models/post.server";
-import { requireAuthor } from "~/utils/auth.server";
-
-const UpdatePostSchema = z.object({
-  title: z.string().min(1, "Title is required").max(200),
-  body: z.string().min(1, "Body is required"),
-});
-
-export async function loader({ params, request }: LoaderFunctionArgs) {
-  await requireAuthor(request);
-  const post = await getPostBySlug(params.slug!);
-  if (!post) {
-    throw new Response("Post not found", { status: 404 });
-  }
-  return json({ post });
-}
-
-export async function action({ params, request }: ActionFunctionArgs) {
-  await requireAuthor(request);
-  const formData = await request.formData();
-  const result = UpdatePostSchema.safeParse(Object.fromEntries(formData));
-
-  if (!result.success) {
-    return json(
-      { errors: result.error.flatten().fieldErrors },
-      { status: 400 }
-    );
-  }
-
-  await updatePost(params.slug!, result.data);
-  return redirect(`/blog/${params.slug}`);
-}
-
-export default function EditPost() {
-  const { post } = useLoaderData<typeof loader>();
-  const actionData = useActionData<typeof action>();
-  const navigation = useNavigation();
-  const isSubmitting = navigation.state === "submitting";
-
-  return (
-    <Form method="post">
-      <fieldset disabled={isSubmitting}>
-        <div>
-          <label htmlFor="title">Title</label>
-          <input
-            id="title"
-            name="title"
-            type="text"
-            defaultValue={post.title}
-            aria-invalid={actionData?.errors?.title ? true : undefined}
-            aria-describedby="title-error"
-          />
-          {actionData?.errors?.title && (
-            <p id="title-error" className="error">{actionData.errors.title[0]}</p>
-          )}
-        </div>
-
-        <div>
-          <label htmlFor="body">Body</label>
-          <textarea
-            id="body"
-            name="body"
-            rows={20}
-            defaultValue={post.body}
-            aria-invalid={actionData?.errors?.body ? true : undefined}
-            aria-describedby="body-error"
-          />
-          {actionData?.errors?.body && (
-            <p id="body-error" className="error">{actionData.errors.body[0]}</p>
-          )}
-        </div>
-
-        <button type="submit">
-          {isSubmitting ? "Saving..." : "Save Changes"}
-        </button>
-      </fieldset>
-    </Form>
-  );
-}
-
-export function ErrorBoundary() {
-  return (
-    <div className="error-container">
-      <h1>Error</h1>
-      <p>Could not load the edit form. You may not have permission to edit this post.</p>
-    </div>
-  );
-}
-```
-
-## Key Decisions
-
-- **Flat file routing** -- `blog.$slug.edit.tsx` uses dot-delimited nesting, the Remix v2 default. This keeps all route files in a single directory for easier navigation.
-- **`<Form method="post">`** -- works as a standard HTML form without JavaScript. When JS is available, Remix intercepts the submission for a client-side navigation with instant feedback.
-- **Server-side Zod validation** -- the action validates on the server because client-side validation is bypassable. Validation errors are returned as JSON and displayed next to the fields.
-- **`redirect()` on success** -- follows POST/Redirect/GET to prevent duplicate submissions on browser refresh.
-- **`throw new Response("...", { status: 404 })`** -- Remix catches thrown responses and renders the nearest ErrorBoundary with the status code, keeping the rest of the layout intact.

package/workflows/skills/remix/examples/02-advanced-usage.md

@@ -1,213 +0,0 @@
-# Example: Streaming Dashboard with Defer, Fetchers, and Resource Routes
-
-## Scenario
-
-A team is building an analytics dashboard with Remix v2. The dashboard loads user profile data instantly from cache and streams slow analytics data from an external API. A sidebar widget uses `useFetcher` to bookmark reports without navigating away. A resource route serves CSV exports. The team needs to handle analytics API failures without breaking the profile section.
-
-## Prompt
-
-"Create a Remix v2 analytics dashboard at /dashboard. Load user profile (fast, cached) and analytics summary (slow, 2-3s external API) with streaming. Show a loading skeleton for analytics. Handle analytics API failure gracefully. Add a fetcher-powered bookmark button for reports. Create a resource route at /dashboard/export.csv that streams a CSV download. Include proper TypeScript types and cache headers."
-
-## Expected Output
-
-### Streaming Loader with Defer
-
-```tsx
-// app/routes/dashboard.tsx
-import { defer, type LoaderFunctionArgs } from "@remix-run/node";
-import {
-  Await,
-  useLoaderData,
-  useFetcher,
-  Link,
-} from "@remix-run/react";
-import { Suspense } from "react";
-import { getUserProfile } from "~/models/user.server";
-import { getAnalyticsSummary } from "~/models/analytics.server";
-import { requireUserId } from "~/utils/auth.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-
-  // Await critical data, defer slow data
-  const user = await getUserProfile(userId);
-  const analytics = getAnalyticsSummary(userId); // NOT awaited — deferred
-
-  return defer(
-    { user, analytics },
-    {
-      headers: {
-        "Cache-Control": "private, max-age=60, stale-while-revalidate=300",
-      },
-    }
-  );
-}
-
-export function headers() {
-  return {
-    "Cache-Control": "private, max-age=60, stale-while-revalidate=300",
-  };
-}
-
-export default function Dashboard() {
-  const { user, analytics } = useLoaderData<typeof loader>();
-
-  return (
-    <div className="dashboard">
-      {/* Critical: renders immediately in HTML */}
-      <header>
-        <h1>Welcome, {user.name}</h1>
-        <p>{user.plan} plan — {user.projectCount} projects</p>
-      </header>
-
-      {/* Deferred: streams in after analytics API responds */}
-      <Suspense fallback={<AnalyticsSkeleton />}>
-        <Await resolve={analytics} errorElement={<AnalyticsError />}>
-          {(data) => (
-            <section className="analytics-grid">
-              <StatCard label="Page Views" value={data.pageViews} />
-              <StatCard label="Unique Visitors" value={data.uniqueVisitors} />
-              <StatCard label="Bounce Rate" value={`${data.bounceRate}%`} />
-              <StatCard label="Avg Session" value={`${data.avgSessionMinutes}m`} />
-              <ReportList reports={data.topReports} />
-            </section>
-          )}
-        </Await>
-      </Suspense>
-    </div>
-  );
-}
-
-function AnalyticsSkeleton() {
-  return (
-    <section className="analytics-grid">
-      {Array.from({ length: 4 }).map((_, i) => (
-        <div key={i} className="stat-card skeleton" aria-busy="true" />
-      ))}
-    </section>
-  );
-}
-
-function AnalyticsError() {
-  return (
-    <section className="analytics-error">
-      <p>Analytics data is temporarily unavailable. Your profile and projects are unaffected.</p>
-      <Link to="." reloadDocument>
-        Try again
-      </Link>
-    </section>
-  );
-}
-```
-
-### Fetcher-Powered Bookmark Button
-
-```tsx
-// app/components/BookmarkButton.tsx
-import { useFetcher } from "@remix-run/react";
-
-export function BookmarkButton({ reportId, isBookmarked }: {
-  reportId: string;
-  isBookmarked: boolean;
-}) {
-  const fetcher = useFetcher();
-
-  // Optimistic UI: use the pending form data if a submission is in flight
-  const optimisticBookmarked = fetcher.formData
-    ? fetcher.formData.get("bookmarked") === "true"
-    : isBookmarked;
-
-  return (
-    <fetcher.Form method="post" action="/dashboard/bookmark">
-      <input type="hidden" name="reportId" value={reportId} />
-      <input
-        type="hidden"
-        name="bookmarked"
-        value={String(!optimisticBookmarked)}
-      />
-      <button
-        type="submit"
-        aria-label={optimisticBookmarked ? "Remove bookmark" : "Add bookmark"}
-        disabled={fetcher.state === "submitting"}
-      >
-        {optimisticBookmarked ? "Bookmarked" : "Bookmark"}
-      </button>
-    </fetcher.Form>
-  );
-}
-```
-
-### Bookmark Action Route
-
-```tsx
-// app/routes/dashboard.bookmark.tsx
-import { json, type ActionFunctionArgs } from "@remix-run/node";
-import { requireUserId } from "~/utils/auth.server";
-import { toggleBookmark } from "~/models/bookmark.server";
-
-export async function action({ request }: ActionFunctionArgs) {
-  const userId = await requireUserId(request);
-  const formData = await request.formData();
-  const reportId = String(formData.get("reportId"));
-  const bookmarked = formData.get("bookmarked") === "true";
-
-  await toggleBookmark({ userId, reportId, bookmarked });
-  return json({ ok: true });
-}
-```
-
-### Resource Route for CSV Export
-
-```tsx
-// app/routes/dashboard.export[.csv].tsx
-import { type LoaderFunctionArgs } from "@remix-run/node";
-import { requireUserId } from "~/utils/auth.server";
-import { getAnalyticsExport } from "~/models/analytics.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-  const data = await getAnalyticsExport(userId);
-
-  const csv = [
-    "Date,Page Views,Unique Visitors,Bounce Rate",
-    ...data.rows.map(
-      (r) => `${r.date},${r.pageViews},${r.uniqueVisitors},${r.bounceRate}`
-    ),
-  ].join("\n");
-
-  return new Response(csv, {
-    headers: {
-      "Content-Type": "text/csv",
-      "Content-Disposition": 'attachment; filename="analytics-export.csv"',
-    },
-  });
-}
-```
-
-### Revalidation Control
-
-```tsx
-// app/routes/dashboard.tsx (additional export)
-import type { ShouldRevalidateFunctionArgs } from "@remix-run/react";
-
-export function shouldRevalidate({
-  formAction,
-  defaultShouldRevalidate,
-}: ShouldRevalidateFunctionArgs) {
-  // Only revalidate the dashboard loader when a bookmark action completes
-  // Skip revalidation for unrelated actions (e.g., logout, settings)
-  if (formAction?.startsWith("/dashboard")) {
-    return true;
-  }
-  return defaultShouldRevalidate;
-}
-```
-
-## Key Decisions
-
-- **`defer({ user, analytics })`** -- `user` is awaited (critical, renders in initial HTML), `analytics` is a bare promise (streamed after the external API responds). This sends the HTML shell in ~50ms instead of waiting 2-3s for the analytics API.
-- **`errorElement` on `<Await>`** -- analytics failures are caught by the Await's errorElement, not the route ErrorBoundary. The user profile and navigation remain functional.
-- **`useFetcher` for bookmarks** -- submits to `/dashboard/bookmark` without navigating away from the dashboard. The fetcher tracks submission state independently, enabling optimistic UI from `fetcher.formData`.
-- **Resource route with `[.csv]` escape** -- the brackets escape the dot in `export.csv`, making the file path `dashboard.export[.csv].tsx` which maps to the URL `/dashboard/export.csv`.
-- **`shouldRevalidate`** -- prevents re-fetching the slow analytics data when unrelated actions complete, reducing unnecessary server load.
-- **`stale-while-revalidate` cache headers** -- the dashboard serves stale content for up to 5 minutes while revalidating in the background, reducing origin server load for repeat visits.

package/workflows/skills/remix/references/loaders-actions.md

@@ -1,175 +0,0 @@
-# Loaders and Actions
-
-Load this when implementing data fetching, form mutations, server-side validation, revalidation control, or session-based data access.
-
-## Loaders
-
-Loaders run on the server for every GET request to a route. They receive the request and route params and return data for the component.
-
-### Basic Loader Pattern
-
-```tsx
-import { json, type LoaderFunctionArgs } from "@remix-run/node";
-import { useLoaderData } from "@remix-run/react";
-
-export async function loader({ request, params }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-  const post = await getPost(params.slug!);
-
-  if (!post) {
-    throw new Response("Not Found", { status: 404 });
-  }
-
-  return json({ post });
-}
-
-export default function PostPage() {
-  const { post } = useLoaderData<typeof loader>();
-  return <h1>{post.title}</h1>;
-}
-```
-
-- Loaders run in parallel for nested routes. A parent loader and child loader execute simultaneously, not sequentially.
-- `typeof loader` provides type inference. Never manually type `useLoaderData`.
-- Throw a `Response` to trigger the nearest `ErrorBoundary` with a status code.
-- Return `json()` for serialized data. The response is always serialized over the network.
-
-### Loader Headers and Caching
-
-```tsx
-export function headers({ loaderHeaders }: { loaderHeaders: Headers }) {
-  return {
-    "Cache-Control": loaderHeaders.get("Cache-Control") ?? "private, max-age=60",
-  };
-}
-
-export async function loader() {
-  const data = await getCachedData();
-  return json(data, {
-    headers: {
-      "Cache-Control": "public, max-age=300, stale-while-revalidate=600",
-    },
-  });
-}
-```
-
-## Actions
-
-Actions run on the server for non-GET requests (POST, PUT, PATCH, DELETE). They handle form mutations and return data or redirects.
-
-### Basic Action Pattern
-
-```tsx
-import { json, redirect, type ActionFunctionArgs } from "@remix-run/node";
-import { Form, useActionData } from "@remix-run/react";
-import { z } from "zod";
-
-const CreatePostSchema = z.object({
-  title: z.string().min(1, "Title is required").max(200),
-  body: z.string().min(1, "Body is required"),
-});
-
-export async function action({ request }: ActionFunctionArgs) {
-  const formData = await request.formData();
-  const result = CreatePostSchema.safeParse(Object.fromEntries(formData));
-
-  if (!result.success) {
-    return json(
-      { errors: result.error.flatten().fieldErrors, values: Object.fromEntries(formData) },
-      { status: 400 }
-    );
-  }
-
-  const post = await createPost(result.data);
-  return redirect(`/blog/${post.slug}`);
-}
-
-export default function NewPost() {
-  const actionData = useActionData<typeof action>();
-
-  return (
-    <Form method="post">
-      <input name="title" defaultValue={actionData?.values?.title} />
-      {actionData?.errors?.title && <p>{actionData.errors.title[0]}</p>}
-
-      <textarea name="body" defaultValue={actionData?.values?.body} />
-      {actionData?.errors?.body && <p>{actionData.errors.body[0]}</p>}
-
-      <button type="submit">Create Post</button>
-    </Form>
-  );
-}
-```
-
-### Action Conventions
-
-- Return `redirect()` on successful mutations to follow POST/Redirect/GET.
-- Return `json({ errors })` with status 400 on validation failure.
-- Preserve submitted values in the response so the form repopulates on error.
-- Always validate on the server. Client-side validation is optional and bypassable.
-- Use `formData.get("_action")` to distinguish between multiple actions in one form.
-
-## Revalidation
-
-After any action completes, Remix revalidates all active loaders by default.
-
-### Controlling Revalidation
-
-```tsx
-import type { ShouldRevalidateFunctionArgs } from "@remix-run/react";
-
-export function shouldRevalidate({
-  actionResult,
-  currentUrl,
-  nextUrl,
-  formAction,
-  formMethod,
-  defaultShouldRevalidate,
-}: ShouldRevalidateFunctionArgs) {
-  // Skip revalidation for this loader after actions on unrelated routes
-  if (formAction && !formAction.startsWith("/blog")) {
-    return false;
-  }
-
-  // Skip revalidation for GET navigations within the same parent
-  if (formMethod === "GET" && currentUrl.pathname === nextUrl.pathname) {
-    return false;
-  }
-
-  return defaultShouldRevalidate;
-}
-```
-
-- `shouldRevalidate` runs on the client after navigations and action completions.
-- Return `false` to prevent the loader from re-running.
-- Use this to avoid re-fetching expensive data (analytics, external APIs) after unrelated mutations.
-
-## Session Access in Loaders and Actions
-
-```tsx
-import { createCookieSessionStorage, redirect } from "@remix-run/node";
-
-const { getSession, commitSession, destroySession } =
-  createCookieSessionStorage({
-    cookie: {
-      name: "__session",
-      httpOnly: true,
-      maxAge: 60 * 60 * 24 * 7, // 7 days
-      path: "/",
-      sameSite: "lax",
-      secrets: [process.env.SESSION_SECRET!],
-      secure: process.env.NODE_ENV === "production",
-    },
-  });
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const session = await getSession(request.headers.get("Cookie"));
-  const userId = session.get("userId");
-
-  if (!userId) {
-    throw redirect("/login");
-  }
-
-  return json({ userId });
-}
-```