@cubis/foundry 0.3.83 → 0.3.84

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/t3-stack/examples/01-crud-router-with-auth.md

@@ -1,166 +0,0 @@
-# Example: CRUD tRPC Router with Authentication
-
-## Scenario
-
-A team is building a project management app with the T3 Stack. They need a tRPC router for managing tasks that belong to projects. Tasks have a title, description, status (TODO, IN_PROGRESS, DONE), priority, and are assigned to a user. Only authenticated users can create, update, or delete tasks. Users can only modify tasks within projects they own.
-
-## Prompt
-
-"Create a tRPC router for tasks in my T3 Stack app. Tasks belong to projects and are assigned to users. I need list (with filters), getById, create, update status, and delete. Only project owners should be able to modify tasks."
-
-## Expected Output
-
-### Prisma Schema Addition
-
-```prisma
-model Task {
-  id          String     @id @default(cuid())
-  title       String
-  description String?
-  status      TaskStatus @default(TODO)
-  priority    Int        @default(0)
-  projectId   String
-  project     Project    @relation(fields: [projectId], references: [id], onDelete: Cascade)
-  assigneeId  String?
-  assignee    User?      @relation(fields: [assigneeId], references: [id])
-  createdAt   DateTime   @default(now())
-  updatedAt   DateTime   @updatedAt
-}
-
-enum TaskStatus {
-  TODO
-  IN_PROGRESS
-  DONE
-}
-```
-
-### tRPC Router
-
-```typescript
-// src/server/api/routers/task.ts
-import { z } from "zod";
-import { createTRPCRouter, protectedProcedure } from "~/server/api/trpc";
-import { TRPCError } from "@trpc/server";
-
-const taskStatusEnum = z.enum(["TODO", "IN_PROGRESS", "DONE"]);
-
-export const taskRouter = createTRPCRouter({
-  list: protectedProcedure
-    .input(
-      z.object({
-        projectId: z.string().cuid(),
-        status: taskStatusEnum.optional(),
-        assigneeId: z.string().cuid().optional(),
-        cursor: z.string().cuid().optional(),
-        limit: z.number().min(1).max(100).default(20),
-      }),
-    )
-    .query(async ({ ctx, input }) => {
-      const tasks = await ctx.db.task.findMany({
-        where: {
-          projectId: input.projectId,
-          ...(input.status && { status: input.status }),
-          ...(input.assigneeId && { assigneeId: input.assigneeId }),
-        },
-        take: input.limit + 1,
-        cursor: input.cursor ? { id: input.cursor } : undefined,
-        orderBy: [{ priority: "desc" }, { createdAt: "desc" }],
-        include: { assignee: { select: { id: true, name: true, image: true } } },
-      });
-
-      let nextCursor: string | undefined;
-      if (tasks.length > input.limit) {
-        const next = tasks.pop();
-        nextCursor = next?.id;
-      }
-
-      return { tasks, nextCursor };
-    }),
-
-  create: protectedProcedure
-    .input(
-      z.object({
-        projectId: z.string().cuid(),
-        title: z.string().min(1).max(200),
-        description: z.string().max(2000).optional(),
-        priority: z.number().int().min(0).max(4).default(0),
-        assigneeId: z.string().cuid().optional(),
-      }),
-    )
-    .mutation(async ({ ctx, input }) => {
-      // Verify the caller owns the project
-      const project = await ctx.db.project.findUnique({
-        where: { id: input.projectId },
-        select: { ownerId: true },
-      });
-
-      if (!project || project.ownerId !== ctx.session.user.id) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "Only the project owner can create tasks.",
-        });
-      }
-
-      return ctx.db.task.create({ data: input });
-    }),
-
-  updateStatus: protectedProcedure
-    .input(
-      z.object({
-        taskId: z.string().cuid(),
-        status: taskStatusEnum,
-      }),
-    )
-    .mutation(async ({ ctx, input }) => {
-      const task = await ctx.db.task.findUnique({
-        where: { id: input.taskId },
-        include: { project: { select: { ownerId: true } } },
-      });
-
-      if (!task) {
-        throw new TRPCError({ code: "NOT_FOUND", message: "Task not found." });
-      }
-
-      if (task.project.ownerId !== ctx.session.user.id) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "Only the project owner can update tasks.",
-        });
-      }
-
-      return ctx.db.task.update({
-        where: { id: input.taskId },
-        data: { status: input.status },
-      });
-    }),
-
-  delete: protectedProcedure
-    .input(z.object({ taskId: z.string().cuid() }))
-    .mutation(async ({ ctx, input }) => {
-      const task = await ctx.db.task.findUnique({
-        where: { id: input.taskId },
-        include: { project: { select: { ownerId: true } } },
-      });
-
-      if (!task) {
-        throw new TRPCError({ code: "NOT_FOUND", message: "Task not found." });
-      }
-
-      if (task.project.ownerId !== ctx.session.user.id) {
-        throw new TRPCError({
-          code: "FORBIDDEN",
-          message: "Only the project owner can delete tasks.",
-        });
-      }
-
-      return ctx.db.task.delete({ where: { id: input.taskId } });
-    }),
-});
-```
-
-## Key Decisions
-
-- **Cursor-based pagination** over offset — more efficient for large datasets and avoids skip-count drift.
-- **Ownership check at the project level** — tasks inherit access control from their parent project.
-- **`include` for assignee** — returns enough user info for the UI without exposing sensitive fields.
-- **Priority as integer 0-4** — simpler than enums, easy to sort, maps to UI labels (None, Low, Medium, High, Critical).

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/t3-stack/examples/02-server-component-data-fetching.md

@@ -1,108 +0,0 @@
-# Example: Server Component Data Fetching with tRPC
-
-## Scenario
-
-A dashboard page needs to display the current user's projects with task counts. The page is a React Server Component that should fetch data on the server without a client-side round-trip. The page also has a client component sidebar that needs to subscribe to real-time updates.
-
-## Prompt
-
-"Show me how to fetch tRPC data in a Next.js App Router server component and hydrate it for a client component that needs the same data."
-
-## Expected Output
-
-### Server-side tRPC Caller Setup
-
-```typescript
-// src/trpc/server.ts
-import "server-only";
-import { createHydrationHelpers } from "@trpc/react-query/rsc";
-import { headers } from "next/headers";
-import { cache } from "react";
-import { createCaller, type AppRouter } from "~/server/api/root";
-import { createTRPCContext } from "~/server/api/trpc";
-import { createQueryClient } from "./query-client";
-
-const getQueryClient = cache(createQueryClient);
-
-const caller = createCaller(async () => {
-  const heads = new Headers(await headers());
-  heads.set("x-trpc-source", "rsc");
-  return createTRPCContext({ headers: heads });
-});
-
-export const { trpc: api, HydrateClient } = createHydrationHelpers<AppRouter>(
-  caller,
-  getQueryClient,
-);
-```
-
-### Server Component (Dashboard Page)
-
-```typescript
-// src/app/dashboard/page.tsx
-import { api, HydrateClient } from "~/trpc/server";
-import { ProjectList } from "./_components/project-list";
-import { Sidebar } from "./_components/sidebar";
-
-export default async function DashboardPage() {
-  // Server-side fetch — no network round-trip
-  const projects = await api.project.listMine();
-
-  // Prefetch for client components that need the same data
-  void api.project.listMine.prefetch();
-
-  return (
-    <HydrateClient>
-      <div className="flex h-screen">
-        <Sidebar />
-        <main className="flex-1 overflow-auto p-6">
-          <h1 className="mb-6 text-2xl font-bold">My Projects</h1>
-          <ProjectList initialProjects={projects} />
-        </main>
-      </div>
-    </HydrateClient>
-  );
-}
-```
-
-### Client Component (with React Query)
-
-```typescript
-// src/app/dashboard/_components/sidebar.tsx
-"use client";
-
-import { api } from "~/trpc/react";
-
-export function Sidebar() {
-  // Uses prefetched data from the server — no loading state on first render
-  const { data: projects } = api.project.listMine.useQuery(undefined, {
-    refetchInterval: 30_000, // Poll for updates every 30s
-  });
-
-  return (
-    <aside className="w-64 border-r bg-gray-50 p-4">
-      <h2 className="mb-4 text-sm font-semibold uppercase text-gray-500">
-        Projects
-      </h2>
-      <ul className="space-y-2">
-        {projects?.map((project) => (
-          <li key={project.id} className="rounded-md px-3 py-2 hover:bg-gray-100">
-            <span className="text-sm font-medium">{project.name}</span>
-            <span className="ml-2 text-xs text-gray-400">
-              {project._count.tasks} tasks
-            </span>
-          </li>
-        ))}
-      </ul>
-    </aside>
-  );
-}
-```
-
-## Key Decisions
-
-- **`HydrateClient` wrapper** — dehydrates server-fetched data into the HTML so client components can use it without a second fetch.
-- **`void api.project.listMine.prefetch()`** — prefetches into the query cache but does not block rendering. The sidebar picks up the cached data.
-- **Server component does direct call, client component does `useQuery`** — same data, different access patterns. Server gets it synchronously; client gets cache + refetch.
-- **`refetchInterval: 30_000`** — lightweight polling for near-real-time without WebSocket complexity. Suitable for dashboards where 30-second staleness is acceptable.
-- **Tailwind utility classes throughout** — consistent with T3 Stack defaults. No CSS modules or styled-components needed.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/t3-stack/references/auth-strategies.md

@@ -1,191 +0,0 @@
-# Auth Strategies
-
-Load this when configuring NextAuth.js/Auth.js providers, callbacks, session strategies, or wiring authentication into the tRPC context in a T3 Stack application.
-
-## NextAuth.js configuration
-
-```typescript
-// src/server/auth.ts
-import { PrismaAdapter } from "@auth/prisma-adapter";
-import { type GetServerSidePropsContext } from "next";
-import { getServerSession, type NextAuthOptions } from "next-auth";
-import GoogleProvider from "next-auth/providers/google";
-import GitHubProvider from "next-auth/providers/github";
-import CredentialsProvider from "next-auth/providers/credentials";
-import { db } from "~/server/db";
-
-export const authOptions: NextAuthOptions = {
-  adapter: PrismaAdapter(db),
-  providers: [
-    GoogleProvider({
-      clientId: process.env.GOOGLE_CLIENT_ID!,
-      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-    }),
-    GitHubProvider({
-      clientId: process.env.GITHUB_CLIENT_ID!,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-    }),
-  ],
-  callbacks: {
-    session: ({ session, user }) => ({
-      ...session,
-      user: { ...session.user, id: user.id, role: user.role },
-    }),
-  },
-  pages: {
-    signIn: "/auth/signin",
-    error: "/auth/error",
-  },
-  secret: process.env.NEXTAUTH_SECRET,
-};
-
-export const getServerAuthSession = (ctx: {
-  req: GetServerSidePropsContext["req"];
-  res: GetServerSidePropsContext["res"];
-}) => getServerSession(ctx.req, ctx.res, authOptions);
-```
-
-- Always use `PrismaAdapter` to persist accounts, sessions, and verification tokens in the database.
-- Reference environment variables for all secrets — never hardcode OAuth credentials.
-- Extend the session callback to include `user.id` and any custom fields (role, tenantId) that downstream code needs.
-
-## Session strategies
-
-### Database sessions (default with adapter)
-
-- Sessions stored in the `Session` table via Prisma.
-- Best for: applications that need server-side session revocation.
-- Session lookup hits the database on every request.
-- The `session` callback receives `user` (the database row), not `token`.
-
-### JWT sessions
-
-```typescript
-export const authOptions: NextAuthOptions = {
-  adapter: PrismaAdapter(db),
-  session: { strategy: "jwt", maxAge: 30 * 24 * 60 * 60 },
-  callbacks: {
-    jwt: ({ token, user }) => {
-      if (user) {
-        token.id = user.id;
-        token.role = user.role;
-      }
-      return token;
-    },
-    session: ({ session, token }) => ({
-      ...session,
-      user: { ...session.user, id: token.id as string, role: token.role as string },
-    }),
-  },
-};
-```
-
-- Best for: serverless deployments where database connection overhead is a concern.
-- The `jwt` callback fires on sign-in and every session check. Attach user data there.
-- The `session` callback receives `token` (not `user`) when using JWT strategy.
-- Combine with database adapter: OAuth accounts are still persisted, but session state lives in the JWT.
-
-## Wiring auth into tRPC context
-
-```typescript
-// src/server/api/trpc.ts
-import { getServerSession } from "next-auth";
-import { authOptions } from "~/server/auth";
-
-export const createTRPCContext = async (opts: { headers: Headers }) => {
-  const session = await getServerSession(authOptions);
-  return { db, session, ...opts };
-};
-```
-
-- The session is fetched once during context creation and shared across all procedures in a single request.
-- Never call `getServerSession` inside individual procedures — it wastes database lookups.
-- The context type is inferred by tRPC, so `ctx.session` is automatically typed.
-
-## Protecting procedures
-
-```typescript
-const enforceUserIsAuthed = t.middleware(({ ctx, next }) => {
-  if (!ctx.session?.user) {
-    throw new TRPCError({ code: "UNAUTHORIZED" });
-  }
-  return next({
-    ctx: { session: { ...ctx.session, user: ctx.session.user } },
-  });
-});
-
-export const protectedProcedure = t.procedure.use(enforceUserIsAuthed);
-```
-
-- The middleware narrows `ctx.session.user` from `User | undefined` to `User`.
-- Downstream procedures access `ctx.session.user.id` without null checks.
-- Stack additional middleware for role-based access (admin, owner, member).
-
-## Prisma schema for auth
-
-```prisma
-model User {
-  id            String    @id @default(cuid())
-  name          String?
-  email         String?   @unique
-  emailVerified DateTime?
-  image         String?
-  role          String    @default("member")
-  accounts      Account[]
-  sessions      Session[]
-}
-
-model Account {
-  id                String  @id @default(cuid())
-  userId            String
-  type              String
-  provider          String
-  providerAccountId String
-  refresh_token     String? @db.Text
-  access_token      String? @db.Text
-  expires_at        Int?
-  token_type        String?
-  scope             String?
-  id_token          String? @db.Text
-  session_state     String?
-  user              User    @relation(fields: [userId], references: [id], onDelete: Cascade)
-  @@unique([provider, providerAccountId])
-}
-
-model Session {
-  id           String   @id @default(cuid())
-  sessionToken String   @unique
-  userId       String
-  expires      DateTime
-  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
-}
-
-model VerificationToken {
-  identifier String
-  token      String   @unique
-  expires    DateTime
-  @@unique([identifier, token])
-}
-```
-
-- These models are required by `PrismaAdapter`. Field names must match exactly.
-- Add custom fields (like `role`) to the `User` model and expose them through callbacks.
-- `onDelete: Cascade` on Account and Session ensures cleanup when a user is deleted.
-
-## Auth.js v5 migration notes
-
-Auth.js v5 (the successor to NextAuth.js v4) changes the API surface:
-
-- Import from `@auth/core` and `@auth/nextjs` instead of `next-auth`.
-- Configuration uses `NextAuth()` function returning `{ handlers, auth, signIn, signOut }`.
-- Middleware-based route protection replaces `getServerSession` in many patterns.
-- The Prisma adapter import changes to `@auth/prisma-adapter`.
-
-If the project uses Auth.js v5, confirm the import paths before generating code. The configuration shape differs significantly from v4.
-
-## Common pitfalls
-
-- **Missing NEXTAUTH_URL in production**: NextAuth uses this to construct callback URLs. Omitting it causes OAuth redirect failures.
-- **Forgetting to extend session type**: TypeScript will not know about `session.user.id` unless you augment the `Session` type in `next-auth.d.ts`.
-- **Using `useSession` in server components**: `useSession` is a client hook. Use `getServerSession` on the server.
-- **Not handling the `signIn` callback for new users**: If you need to run custom logic on first sign-in (like creating a default workspace), use the `signIn` event or callback.

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/t3-stack/references/prisma-t3-patterns.md

@@ -1,242 +0,0 @@
-# Prisma T3 Patterns
-
-Load this when writing Prisma schemas, queries, relations, or configuring the Prisma client singleton in a T3 Stack application.
-
-## Singleton Prisma client
-
-```typescript
-// src/server/db.ts
-import { PrismaClient } from "@prisma/client";
-
-const createPrismaClient = () =>
-  new PrismaClient({
-    log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
-  });
-
-const globalForPrisma = globalThis as unknown as {
-  prisma: ReturnType<typeof createPrismaClient> | undefined;
-};
-
-export const db = globalForPrisma.prisma ?? createPrismaClient();
-
-if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = db;
-```
-
-- Next.js hot-reload in development creates a new module scope on every change.
-- Without the global cache, each reload creates a new PrismaClient, exhausting database connections.
-- In production, the module is loaded once, so the global fallback is never used.
-- Enable query logging only in development to debug slow queries.
-
-## Schema design conventions
-
-```prisma
-generator client {
-  provider = "prisma-client-js"
-}
-
-datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
-
-model User {
-  id        String   @id @default(cuid())
-  email     String   @unique
-  name      String?
-  image     String?
-  role      String   @default("member")
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  projects  Project[]
-  tasks     Task[]
-
-  // NextAuth relations
-  accounts  Account[]
-  sessions  Session[]
-}
-
-model Project {
-  id          String   @id @default(cuid())
-  name        String
-  description String?
-  ownerId     String
-  owner       User     @relation(fields: [ownerId], references: [id], onDelete: Cascade)
-  tasks       Task[]
-  createdAt   DateTime @default(now())
-  updatedAt   DateTime @updatedAt
-
-  @@index([ownerId])
-}
-```
-
-- Use `cuid()` for IDs — URL-safe, collision-resistant, and sortable.
-- Always add `createdAt` and `updatedAt` to every model.
-- Add `@@index` on foreign key columns used in WHERE clauses and JOINs.
-- Use `onDelete: Cascade` when child records should be removed with the parent.
-
-## Query patterns for tRPC procedures
-
-### Paginated list with cursor
-
-```typescript
-const tasks = await ctx.db.task.findMany({
-  where: {
-    projectId: input.projectId,
-    ...(input.status && { status: input.status }),
-  },
-  take: input.limit + 1,
-  cursor: input.cursor ? { id: input.cursor } : undefined,
-  orderBy: { createdAt: "desc" },
-  include: {
-    assignee: { select: { id: true, name: true, image: true } },
-  },
-});
-
-let nextCursor: string | undefined;
-if (tasks.length > input.limit) {
-  const next = tasks.pop();
-  nextCursor = next?.id;
-}
-
-return { tasks, nextCursor };
-```
-
-- Fetch `limit + 1` to determine if a next page exists without a separate count query.
-- Use `include` with `select` to fetch related data without exposing all fields.
-- Cursor pagination outperforms offset pagination for large datasets.
-
-### Single record with ownership check
-
-```typescript
-const project = await ctx.db.project.findUnique({
-  where: { id: input.projectId },
-  select: { ownerId: true },
-});
-
-if (!project) {
-  throw new TRPCError({ code: "NOT_FOUND", message: "Project not found." });
-}
-
-if (project.ownerId !== ctx.session.user.id) {
-  throw new TRPCError({ code: "FORBIDDEN", message: "Not your project." });
-}
-```
-
-- Use `select` to fetch only the fields needed for the check — do not load the entire record.
-- Separate NOT_FOUND from FORBIDDEN to give the client actionable error information.
-
-### Transactional multi-step mutations
-
-```typescript
-const result = await ctx.db.$transaction(async (tx) => {
-  const project = await tx.project.create({
-    data: { name: input.name, ownerId: ctx.session.user.id },
-  });
-
-  await tx.task.create({
-    data: {
-      title: "Getting started",
-      projectId: project.id,
-      assigneeId: ctx.session.user.id,
-    },
-  });
-
-  return project;
-});
-```
-
-- Use `$transaction` with the interactive callback (not the array form) for multi-step logic.
-- The `tx` client shares the same connection and rolls back all operations if any step throws.
-- Never mix `ctx.db` and `tx` inside the transaction callback — use `tx` exclusively.
-
-## Relation patterns
-
-### One-to-many
-
-```prisma
-model Project {
-  id    String @id @default(cuid())
-  tasks Task[]
-}
-
-model Task {
-  id        String  @id @default(cuid())
-  projectId String
-  project   Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
-
-  @@index([projectId])
-}
-```
-
-### Many-to-many with explicit junction
-
-```prisma
-model Tag {
-  id    String      @id @default(cuid())
-  name  String      @unique
-  tasks TaskTag[]
-}
-
-model TaskTag {
-  taskId String
-  tagId  String
-  task   Task @relation(fields: [taskId], references: [id], onDelete: Cascade)
-  tag    Tag  @relation(fields: [tagId], references: [id], onDelete: Cascade)
-
-  @@id([taskId, tagId])
-}
-```
-
-- Explicit junction tables are preferred over implicit many-to-many for T3 apps because they allow adding metadata (e.g., `assignedAt`, `assignedBy`).
-
-## Prisma with environment validation
-
-```typescript
-// src/env.js
-import { createEnv } from "@t3-oss/env-nextjs";
-import { z } from "zod";
-
-export const env = createEnv({
-  server: {
-    DATABASE_URL: z.string().url(),
-    NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
-  },
-  runtimeEnv: {
-    DATABASE_URL: process.env.DATABASE_URL,
-    NODE_ENV: process.env.NODE_ENV,
-  },
-});
-```
-
-- Validate DATABASE_URL at build time so that a missing connection string fails fast.
-- Use `z.string().url()` to catch malformed connection strings before Prisma tries to connect.
-
-## Connection pooling for serverless
-
-```
-# Pooled connection for queries (PgBouncer or Prisma Accelerate)
-DATABASE_URL="postgresql://user:pass@pooler.example.com:6543/mydb?pgbouncer=true"
-
-# Direct connection for migrations (bypasses the pooler)
-DIRECT_URL="postgresql://user:pass@db.example.com:5432/mydb"
-```
-
-```prisma
-datasource db {
-  provider  = "postgresql"
-  url       = env("DATABASE_URL")
-  directUrl = env("DIRECT_URL")
-}
-```
-
-- Serverless functions create a new connection per invocation — pooling is mandatory.
-- Prisma uses `directUrl` for migrations and `url` for runtime queries.
-- PgBouncer in transaction mode requires `?pgbouncer=true` to disable prepared statements.
-
-## Common pitfalls
-
-- **N+1 queries**: Using `findUnique` in a loop instead of `findMany` with `where: { id: { in: ids } }`.
-- **Missing indexes**: Prisma does not auto-create indexes on foreign keys. Add `@@index` explicitly.
-- **Stale client after migration**: Run `prisma generate` after every schema change to regenerate the client.
-- **Raw SQL bypassing type safety**: Use `$queryRaw` with tagged templates and `Prisma.sql` for parameterized queries.