@cubis/foundry 0.3.82 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/antigravity/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 });
-}
-```

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/remix/references/progressive-enhancement.md

@@ -1,159 +0,0 @@
-# Progressive Enhancement
-
-Load this when implementing optimistic UI, useFetcher, useNavigation, pending states, or forms that must work without JavaScript.
-
-## The Progressive Enhancement Model
-
-Remix forms work as standard HTML forms by default. When JavaScript loads, Remix enhances them with client-side navigation, pending UI, and optimistic updates. This means every form works without JavaScript and gets better with it.
-
-### Standard Form (Works Without JS)
-
-```tsx
-import { Form } from "@remix-run/react";
-
-// <Form> renders a <form> in HTML. Without JS, it submits normally.
-// With JS, Remix intercepts the submission for a client-side navigation.
-export default function ContactForm() {
-  return (
-    <Form method="post" action="/contact">
-      <input name="email" type="email" required />
-      <textarea name="message" required />
-      <button type="submit">Send</button>
-    </Form>
-  );
-}
-```
-
-## useNavigation for Pending UI
-
-`useNavigation` tracks the state of the current page navigation (not fetcher submissions).
-
-```tsx
-import { Form, useNavigation } from "@remix-run/react";
-
-export default function SubmitForm() {
-  const navigation = useNavigation();
-  const isSubmitting = navigation.state === "submitting";
-  const isLoading = navigation.state === "loading";
-
-  return (
-    <Form method="post">
-      <input name="title" disabled={isSubmitting} />
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? "Saving..." : "Save"}
-      </button>
-    </Form>
-  );
-}
-```
-
-### Navigation States
-
-| State | Meaning |
-| --- | --- |
-| `idle` | No navigation in progress |
-| `submitting` | A form is being submitted (action is running) |
-| `loading` | Loaders are running after action completes or after a link click |
-
-### Accessing Pending Form Data
-
-```tsx
-const navigation = useNavigation();
-
-// Access the form data being submitted for optimistic UI
-if (navigation.state === "submitting") {
-  const pendingTitle = navigation.formData?.get("title");
-  // Render the pending title optimistically
-}
-```
-
-## useFetcher for Non-Navigation Mutations
-
-`useFetcher` submits to an action without changing the URL. Use it for inline edits, toggles, and background operations.
-
-```tsx
-import { useFetcher } from "@remix-run/react";
-
-function LikeButton({ postId, liked }: { postId: string; liked: boolean }) {
-  const fetcher = useFetcher();
-
-  // Optimistic: use pending data if available, fall back to server data
-  const optimisticLiked = fetcher.formData
-    ? fetcher.formData.get("liked") === "true"
-    : liked;
-
-  return (
-    <fetcher.Form method="post" action="/api/like">
-      <input type="hidden" name="postId" value={postId} />
-      <input type="hidden" name="liked" value={String(!optimisticLiked)} />
-      <button type="submit" aria-pressed={optimisticLiked}>
-        {optimisticLiked ? "Unlike" : "Like"}
-      </button>
-    </fetcher.Form>
-  );
-}
-```
-
-### Fetcher States
-
-| State | Meaning |
-| --- | --- |
-| `idle` | No fetcher operation in progress |
-| `submitting` | The fetcher is submitting to an action |
-| `loading` | The fetcher is revalidating after the action completed |
-
-### Multiple Independent Fetchers
-
-Each `useFetcher()` call creates an independent instance. Multiple fetchers can be in-flight simultaneously without interfering.
-
-```tsx
-function TaskList({ tasks }) {
-  return tasks.map((task) => <TaskRow key={task.id} task={task} />);
-}
-
-function TaskRow({ task }) {
-  const fetcher = useFetcher(); // Each row has its own fetcher
-
-  return (
-    <fetcher.Form method="post" action="/api/tasks/toggle">
-      <input type="hidden" name="taskId" value={task.id} />
-      <button>{task.done ? "Undo" : "Complete"}</button>
-    </fetcher.Form>
-  );
-}
-```
-
-## useFetcher for Data Loading
-
-`useFetcher` can also load data without navigation, useful for search-as-you-type and comboboxes.
-
-```tsx
-function CitySearch() {
-  const fetcher = useFetcher<typeof loader>();
-
-  return (
-    <div>
-      <fetcher.Form method="get" action="/api/cities">
-        <input
-          name="q"
-          type="search"
-          onChange={(e) => fetcher.submit(e.currentTarget.form)}
-        />
-      </fetcher.Form>
-      {fetcher.data?.cities.map((city) => (
-        <p key={city.id}>{city.name}</p>
-      ))}
-    </div>
-  );
-}
-```
-
-## Choosing Between Form, useFetcher, and useSubmit
-
-| Use case | Tool | Reason |
-| --- | --- | --- |
-| Full-page form submission | `<Form>` | Triggers navigation, updates URL, enables back button |
-| Inline edit / toggle / like | `useFetcher` | No URL change, no scroll reset, independent state |
-| Programmatic submission | `useSubmit` | Form submission from a click handler or effect |
-| Search / filter | `<Form method="get">` | Updates URL search params, works with back button |
-| Autocomplete / typeahead | `useFetcher` with `GET` | Loads data without URL change or history entry |

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/remix/references/resource-routes.md

@@ -1,177 +0,0 @@
-# Resource Routes
-
-Load this when implementing API endpoints, webhooks, file downloads, image generation, RSS feeds, sitemaps, or any route that returns non-HTML responses.
-
-## What Are Resource Routes?
-
-A resource route is a route module that exports a `loader` or `action` but no `default` component. It serves raw responses (JSON, CSV, XML, binary) at a URL without rendering HTML.
-
-Resource routes share the same file naming, authentication, session handling, and deployment infrastructure as UI routes.
-
-## Common Resource Route Patterns
-
-### JSON API Endpoint
-
-```tsx
-// app/routes/api.posts.tsx — GET /api/posts
-import { json, type LoaderFunctionArgs } from "@remix-run/node";
-import { requireApiKey } from "~/utils/auth.server";
-import { getPosts } from "~/models/post.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  await requireApiKey(request);
-
-  const url = new URL(request.url);
-  const page = parseInt(url.searchParams.get("page") ?? "1", 10);
-  const limit = parseInt(url.searchParams.get("limit") ?? "20", 10);
-
-  const { posts, total } = await getPosts({ page, limit });
-
-  return json(
-    { data: posts, meta: { page, limit, total } },
-    {
-      headers: {
-        "Cache-Control": "public, max-age=60",
-      },
-    }
-  );
-}
-```
-
-### CSV File Download
-
-```tsx
-// app/routes/reports.export[.csv].tsx — GET /reports/export.csv
-import type { LoaderFunctionArgs } from "@remix-run/node";
-import { requireUserId } from "~/utils/auth.server";
-import { getReportData } from "~/models/report.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const userId = await requireUserId(request);
-  const data = await getReportData(userId);
-
-  const csv = [
-    "Date,Revenue,Orders",
-    ...data.map((row) => `${row.date},${row.revenue},${row.orders}`),
-  ].join("\n");
-
-  return new Response(csv, {
-    headers: {
-      "Content-Type": "text/csv; charset=utf-8",
-      "Content-Disposition": 'attachment; filename="report.csv"',
-    },
-  });
-}
-```
-
-The bracket escape `[.csv]` in the filename makes the route URL `/reports/export.csv` instead of treating the dot as a route separator.
-
-### Webhook Receiver
-
-```tsx
-// app/routes/webhooks.stripe.tsx — POST /webhooks/stripe
-import type { ActionFunctionArgs } from "@remix-run/node";
-import Stripe from "stripe";
-import { handleStripeEvent } from "~/services/stripe.server";
-
-export async function action({ request }: ActionFunctionArgs) {
-  const payload = await request.text();
-  const signature = request.headers.get("stripe-signature");
-
-  if (!signature) {
-    return new Response("Missing signature", { status: 400 });
-  }
-
-  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
-  let event: Stripe.Event;
-
-  try {
-    event = stripe.webhooks.constructEvent(
-      payload,
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-  } catch {
-    return new Response("Invalid signature", { status: 400 });
-  }
-
-  await handleStripeEvent(event);
-  return new Response("OK", { status: 200 });
-}
-```
-
-### RSS Feed
-
-```tsx
-// app/routes/rss[.]xml.tsx — GET /rss.xml
-import type { LoaderFunctionArgs } from "@remix-run/node";
-import { getRecentPosts } from "~/models/post.server";
-
-export async function loader({ request }: LoaderFunctionArgs) {
-  const posts = await getRecentPosts(20);
-  const baseUrl = new URL(request.url).origin;
-
-  const rss = `<?xml version="1.0" encoding="UTF-8"?>
-<rss version="2.0">
-  <channel>
-    <title>My Blog</title>
-    <link>${baseUrl}</link>
-    <description>Latest blog posts</description>
-    ${posts
-      .map(
-        (post) => `
-    <item>
-      <title>${escapeXml(post.title)}</title>
-      <link>${baseUrl}/blog/${post.slug}</link>
-      <pubDate>${new Date(post.publishedAt).toUTCString()}</pubDate>
-      <description>${escapeXml(post.excerpt)}</description>
-    </item>`
-      )
-      .join("")}
-  </channel>
-</rss>`;
-
-  return new Response(rss, {
-    headers: {
-      "Content-Type": "application/rss+xml; charset=utf-8",
-      "Cache-Control": "public, max-age=3600",
-    },
-  });
-}
-
-function escapeXml(str: string): string {
-  return str
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-```
-
-### Health Check
-
-```tsx
-// app/routes/api.healthcheck.tsx — GET /api/healthcheck
-import { json } from "@remix-run/node";
-import { prisma } from "~/db.server";
-
-export async function loader() {
-  try {
-    await prisma.$queryRaw`SELECT 1`;
-    return json({ status: "ok", database: "connected" });
-  } catch {
-    return json(
-      { status: "error", database: "disconnected" },
-      { status: 503 }
-    );
-  }
-}
-```
-
-## Key Considerations
-
-- **No default export** -- if you accidentally add a default component export, the route becomes a UI route and Remix renders HTML with the component.
-- **Same auth patterns** -- resource routes have access to `request.headers`, cookies, and sessions. Use the same authentication helpers as UI routes.
-- **Caching** -- resource routes benefit from `Cache-Control` headers because they often serve static-ish data (feeds, reports, images).
-- **CORS** -- if the resource route serves a cross-origin API, add CORS headers in the loader response and handle `OPTIONS` preflight in a separate `action` or `loader` check.
-- **Rate limiting** -- resource routes exposed as APIs should include rate limiting because they are more likely to be called programmatically.

package/workflows/workflows/agent-environment-setup/platforms/antigravity/skills/remix/references/routing-conventions.md

@@ -1,78 +0,0 @@
-# Routing Conventions
-
-Load this when designing route hierarchies, using flat file naming, pathless routes, layout routes, or migrating from Remix v1 to v2 conventions.
-
-## Flat File Routing (Remix v2 Default)
-
-Remix v2 uses dot-delimited flat file naming. All route files live in `app/routes/` without folder nesting.
-
-### Naming Rules
-
-| File name | URL path | Parent layout |
-| --- | --- | --- |
-| `_index.tsx` | `/` | `root.tsx` |
-| `about.tsx` | `/about` | `root.tsx` |
-| `blog.tsx` | `/blog` (layout) | `root.tsx` |
-| `blog._index.tsx` | `/blog` (index) | `blog.tsx` |
-| `blog.$slug.tsx` | `/blog/:slug` | `blog.tsx` |
-| `blog.$slug.edit.tsx` | `/blog/:slug/edit` | `blog.$slug.tsx` |
-| `blog_.archive.tsx` | `/blog/archive` | `root.tsx` (trailing `_` opts out of layout) |
-| `_auth.tsx` | (no URL segment, layout only) | `root.tsx` |
-| `_auth.login.tsx` | `/login` | `_auth.tsx` |
-| `_auth.register.tsx` | `/register` | `_auth.tsx` |
-
-### Key Conventions
-
-- **Dots (`.`) create nesting** -- `blog.$slug.tsx` is a child of `blog.tsx`.
-- **Trailing underscore (`_`) opts out of the parent layout** -- `blog_.archive.tsx` does not nest inside `blog.tsx`.
-- **Leading underscore (`_`) creates a pathless layout** -- `_auth.tsx` wraps `_auth.login.tsx` and `_auth.register.tsx` without adding a URL segment.
-- **`$param` creates a dynamic segment** -- `blog.$slug.tsx` matches `/blog/anything`.
-- **`_index.tsx` is the index route** -- renders when the parent URL matches exactly with no additional segments.
-- **Brackets escape special characters** -- `sitemap[.]xml.tsx` matches `/sitemap.xml`.
-
-### Layout Routes vs Index Routes
-
-A layout route (`blog.tsx`) renders when any child matches. It must include `<Outlet />` to render child content. An index route (`blog._index.tsx`) renders when the parent URL matches exactly.
-
-```tsx
-// app/routes/blog.tsx -- Layout route
-import { Outlet } from "@remix-run/react";
-
-export default function BlogLayout() {
-  return (
-    <div className="blog-layout">
-      <Sidebar />
-      <main>
-        <Outlet /> {/* Child routes render here */}
-      </main>
-    </div>
-  );
-}
-```
-
-### Route Module Exports
-
-Every route module can export these:
-
-| Export | Purpose |
-| --- | --- |
-| `loader` | Server-side GET data fetching |
-| `action` | Server-side non-GET mutations |
-| `default` | React component to render |
-| `ErrorBoundary` | Error UI for this route segment |
-| `meta` | `<title>` and `<meta>` tags |
-| `headers` | HTTP response headers |
-| `links` | `<link>` tags for stylesheets and preloads |
-| `handle` | Arbitrary data for `useMatches()` |
-| `shouldRevalidate` | Control when the loader re-runs |
-
-### Resource Routes
-
-A route module that exports a `loader` or `action` but no `default` component is a resource route. It serves raw data (JSON, CSV, images) at a URL without rendering HTML.
-
-```tsx
-// app/routes/api.healthcheck.tsx -- Resource route
-export async function loader() {
-  return new Response("OK", { status: 200 });
-}
-```