wcz-layout 7.6.0 → 7.6.2

package/skills/auth/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: auth
+description: >
+  MSAL/Entra ID authentication and AD-group authorization. Use
+  authorizationMiddleware(permissionKey) which includes authentication.
+  Configure permissions.ts and scopes.ts for type-safe keys via
+  virtual:wcz-layout. Client: getAccessToken(scopeKey). Server:
+  getAppToken(scopeKey), getTokenOnBehalfOf(userToken, scopeKey).
+  Route guards with requirePermission. Public routes via LayoutOptions.
+  serverFnAccessTokenMiddleware in start.ts. Activate when configuring
+  authentication, authorization, or token acquisition.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/middleware/authMiddleware.ts"
+  - "wcz-layout:src/lib/auth/msalClient.ts"
+  - "wcz-layout:src/lib/auth/msalServer.ts"
+  - "wcz-layout:src/lib/auth/permissions.ts"
+  - "wcz-layout:src/lib/auth/scopes.ts"
+---
+
+# Authentication & Authorization
+
+## Setup
+
+Two configuration files define the app's security surface. Both are consumed by the `viteWczLayout()` plugin via `virtual:wcz-layout` to generate TypeScript types:
+
+```typescript
+// src/lib/auth/permissions.ts
+export const permissions = {
+  admin: ["wcz-developers"],
+  all: ["wcz-all-employees", "wscz-all-employees"],
+} as const;
+// keyof typeof permissions → "admin" | "all"
+```
+
+```typescript
+// src/lib/auth/scopes.ts
+export const scopes = {
+  graph: ["User.Read"],
+  api: ["api://wistron.com/your-app/access_as_user"],
+} as const;
+// keyof typeof scopes → "graph" | "api"
+```
+
+Permission keys map to AD group names. A user has a permission if their JWT `groups` claim contains at least one group from the array.
+
+## Core Patterns
+
+### API route authorization
+
+```typescript
+import { authorizationMiddleware } from "wcz-layout/middleware";
+
+export const Route = createFileRoute("/api/todos")({
+  server: {
+    middleware: [authorizationMiddleware("all")],
+    handlers: createHandlers({
+      GET: async ({ context }) => {
+        // context.user is typed as User with hasPermission()
+        return Response.json(await context.db.select().from(todoTable));
+      },
+    }),
+  },
+});
+```
+
+`authorizationMiddleware(permissionKey)`:
+
+1. Verifies the JWT Bearer token (includes `authenticationMiddleware` internally)
+2. Builds a `User` object with `hasPermission(key)` method
+3. Returns 401 if token is invalid, 403 if user lacks the specified permission
+4. Injects `context.user: User`
+
+### Public (authentication-only) route
+
+For routes that need authentication but no specific permission:
+
+```typescript
+import { authenticationMiddleware } from "wcz-layout/middleware";
+
+export const Route = createFileRoute("/api/profile")({
+  server: {
+    middleware: [authenticationMiddleware()],
+    handlers: createHandlers({
+      GET: async ({ context }) => {
+        // context.user — any authenticated user
+        return Response.json(context.user);
+      },
+    }),
+  },
+});
+```
+
+For optional authentication (public endpoints that may have user context):
+
+```typescript
+middleware: [authenticationMiddleware({ optional: true })],
+// context.user is User | null
+```
+
+### Route-level permission guard
+
+```typescript
+import { requirePermission } from "wcz-layout/utils";
+
+export const Route = createFileRoute("/admin/")({
+  beforeLoad: requirePermission("admin"),
+  component: AdminPage,
+});
+```
+
+`requirePermission` runs in `beforeLoad` and redirects unauthorized users.
+
+### Client-side token acquisition
+
+```typescript
+import { getAccessToken } from "wcz-layout/utils";
+
+// In an axios interceptor or client-side code
+const token = await getAccessToken("api");
+```
+
+`getAccessToken` is a client-only function (uses MSAL `PublicClientApplication`). It acquires tokens silently and triggers interaction listeners on `InteractionRequiredAuthError`.
+
+### Server-side token acquisition
+
+```typescript
+import { getAppToken, getTokenOnBehalfOf } from "wcz-layout/utils";
+
+// App-only token (client credentials flow — no user context)
+const appToken = await getAppToken("graph");
+
+// On-behalf-of flow (exchange user token for downstream API token)
+const oboToken = await getTokenOnBehalfOf(userBearerToken, "graph");
+```
+
+Both are server-only functions using MSAL `ConfidentialClientApplication`.
+
+### Global server function middleware
+
+```typescript
+// src/start.ts
+import { serverFnAccessTokenMiddleware } from "wcz-layout/middleware";
+
+export const startInstance = createStart(() => ({
+  defaultSsr: false,
+  functionMiddleware: [serverFnAccessTokenMiddleware("api")],
+}));
+```
+
+`serverFnAccessTokenMiddleware` attaches the Bearer token to all server function calls globally. Without it, server functions won't include authorization headers.
+
+### Getting the current user
+
+```typescript
+import { getUser } from "wcz-layout/utils";
+
+// Isomorphic — works on client (returns User | null) and server (returns null)
+const user = getUser();
+```
+
+On the client, `getUser` reads the active MSAL account's ID token claims.
+
+## Common Mistakes
+
+### HIGH Chaining authenticationMiddleware before authorizationMiddleware
+
+Wrong:
+
+```typescript
+middleware: [authenticationMiddleware(), authorizationMiddleware("admin")],
+```
+
+Correct:
+
+```typescript
+middleware: [authorizationMiddleware("admin")],
+```
+
+`authorizationMiddleware` already composes `authenticationMiddleware` internally. Chaining both duplicates JWT verification.
+
+Source: maintainer interview
+
+Cross-skill: See also skills/api-routes/SKILL.md § Common Mistakes
+
+### CRITICAL Calling getAccessToken on the server
+
+Wrong:
+
+```typescript
+// In a server handler or serverFn
+const token = await getAccessToken("api");
+```
+
+Correct:
+
+```typescript
+// Server-side — use app token or OBO
+const token = await getAppToken("api");
+// or
+const token = await getTokenOnBehalfOf(userToken, "api");
+```
+
+`getAccessToken` is `createClientOnlyFn` — it uses MSAL `PublicClientApplication` which only exists in the browser. Calling it on the server throws.
+
+Source: wcz-layout:src/lib/auth/msalClient.ts
+
+### HIGH Forgetting serverFnAccessTokenMiddleware in start.ts
+
+Wrong:
+
+```typescript
+// src/start.ts
+export const startInstance = createStart(() => ({
+  defaultSsr: false,
+  // Missing functionMiddleware
+}));
+```
+
+Correct:
+
+```typescript
+// src/start.ts
+export const startInstance = createStart(() => ({
+  defaultSsr: false,
+  functionMiddleware: [serverFnAccessTokenMiddleware("api")],
+}));
+```
+
+Without `serverFnAccessTokenMiddleware`, server function calls won't include the Authorization header, causing 401 errors.
+
+Source: wcz-layout:src/start.ts
+
+### MEDIUM Using string literals for permission/scope keys
+
+Wrong:
+
+```typescript
+authorizationMiddleware("superadmin"); // not in permissions.ts → compile error
+getAccessToken("custom-api"); // not in scopes.ts → compile error
+```
+
+Correct:
+
+```typescript
+// First add to permissions.ts / scopes.ts, then use the typed key
+authorizationMiddleware("admin");
+getAccessToken("api");
+```
+
+Permission and scope keys are typed from the `as const` exports via `virtual:wcz-layout`. Using arbitrary strings causes TypeScript compile errors.
+
+Source: wcz-layout:src/types/wcz-layout.d.ts
+
+### HIGH Missing Entra redirect URI configuration
+
+The MSAL `redirectUri` defaults to `"/"`. The Entra app registration must include this exact redirect URI, or the authentication flow fails silently with a redirect error.
+
+Source: wcz-layout:src/routes/runbook/entra-id.tsx
+
+---
+
+See also:
+
+- skills/api-routes/SKILL.md — Every API route uses authorizationMiddleware.
+- skills/layout-navigation/SKILL.md — publicRoutes bypass auth; permission guards need auth context.

package/skills/data-grid/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: data-grid
+description: >
+  MUI X DataGrid Premium with wcz-layout helpers. ChipInputCell for chip
+  rendering in cells (getLabel for complex objects). EditableColumnHeader
+  for pencil icon headers. RouterGridActionsCellItem for type-safe row
+  action navigation. Column definitions with renderCell/renderHeader.
+  Feed rows from useLiveQuery collection data. Activate when building
+  data tables or grids.
+type: composition
+library: wcz-layout
+library_version: "7.6.1"
+requires:
+  - tanstack-db-collections
+  - ui-pages
+sources:
+  - "wcz-layout:src/components/data-grid/ChipInputCell.tsx"
+  - "wcz-layout:src/components/data-grid/EditableColumnHeader.tsx"
+  - "wcz-layout:src/components/router/RouterGridActionsCellItem.tsx"
+---
+
+# Data Grid
+
+## Setup
+
+Install `@mui/x-data-grid-premium` (peer dependency). Use `DataGridPremium`, not the community `DataGrid`.
+
+## Core Patterns
+
+### Basic data grid with collection data
+
+```typescript
+import { DataGridPremium, type GridColDef } from "@mui/x-data-grid-premium";
+import { useLiveQuery } from "@tanstack/react-db";
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+import type { Todo } from "~/schemas/todo";
+
+const columns: GridColDef<Todo>[] = [
+  { field: "name", headerName: "Name", flex: 1 },
+  { field: "isCompleted", headerName: "Completed", type: "boolean", width: 120 },
+  { field: "createdAt", headerName: "Created", type: "dateTime", width: 180 },
+];
+
+function TodoGrid() {
+  const { data: todos } = useLiveQuery((query) =>
+    query.from({ todos: todoCollection })
+  );
+
+  return (
+    <DataGridPremium
+      rows={todos}
+      columns={columns}
+      getRowId={(row) => row.id}
+      autoHeight
+    />
+  );
+}
+```
+
+### Row actions with RouterGridActionsCellItem
+
+```typescript
+import { RouterGridActionsCellItem } from "wcz-layout/components";
+import EditIcon from "@mui/icons-material/Edit";
+import DeleteIcon from "@mui/icons-material/Delete";
+import type { GridColDef } from "@mui/x-data-grid-premium";
+
+const columns: GridColDef<Todo>[] = [
+  { field: "name", headerName: "Name", flex: 1 },
+  {
+    field: "actions",
+    type: "actions",
+    width: 100,
+    getActions: (params) => [
+      <RouterGridActionsCellItem
+        key="edit"
+        icon={<EditIcon />}
+        label="Edit"
+        to="/todos/edit/$id"
+        params={{ id: params.row.id }}
+      />,
+      <RouterGridActionsCellItem
+        key="delete"
+        icon={<DeleteIcon />}
+        label="Delete"
+        onClick={() => handleDelete(params.row)}
+        showInMenu
+      />,
+    ],
+  },
+];
+```
+
+`RouterGridActionsCellItem` wraps MUI's `GridActionsCellItem` with TanStack Router's `createLink` for type-safe SPA navigation.
+
+### ChipInputCell for array/tag columns
+
+```typescript
+import { ChipInputCell } from "wcz-layout/components";
+import type { GridColDef } from "@mui/x-data-grid-premium";
+
+const columns: GridColDef<Todo>[] = [
+  {
+    field: "tags",
+    headerName: "Tags",
+    flex: 1,
+    renderCell: (params) => <ChipInputCell params={params} />,
+  },
+];
+```
+
+For complex objects (not plain strings), provide `getLabel`:
+
+```typescript
+renderCell: (params) => (
+  <ChipInputCell
+    params={params}
+    getLabel={(item) => item.displayName}
+    slotProps={{ size: "small", color: "primary" }}
+  />
+),
+```
+
+`ChipInputCell` renders a horizontal scrollable stack of `Chip` components. It handles both scalar and array values automatically.
+
+### EditableColumnHeader
+
+```typescript
+import { EditableColumnHeader } from "wcz-layout/components";
+
+const columns: GridColDef<Todo>[] = [
+  {
+    field: "name",
+    headerName: "Name",
+    flex: 1,
+    editable: true,
+    renderHeader: (params) => <EditableColumnHeader {...params} />,
+  },
+];
+```
+
+Renders the column header text with a trailing pencil (Edit) icon to visually indicate editable columns. Purely visual — no interaction.
+
+## Common Mistakes
+
+### HIGH Using DataGrid instead of DataGridPremium
+
+Wrong:
+
+```typescript
+import { DataGrid } from "@mui/x-data-grid";
+```
+
+Correct:
+
+```typescript
+import { DataGridPremium } from "@mui/x-data-grid-premium";
+```
+
+The library peer-depends on `@mui/x-data-grid-premium`. Using the community `DataGrid` loses Premium features like column grouping, row grouping, tree data, and aggregation.
+
+Source: package.json peerDependencies
+
+### HIGH Using GridActionsCellItem instead of RouterGridActionsCellItem
+
+Wrong:
+
+```typescript
+import { GridActionsCellItem } from "@mui/x-data-grid-premium";
+
+<GridActionsCellItem
+  icon={<EditIcon />}
+  label="Edit"
+  onClick={() => navigate({ to: `/todos/${id}` })}
+/>
+```
+
+Correct:
+
+```typescript
+import { RouterGridActionsCellItem } from "wcz-layout/components";
+
+<RouterGridActionsCellItem
+  icon={<EditIcon />}
+  label="Edit"
+  to="/todos/edit/$id"
+  params={{ id }}
+/>
+```
+
+Plain `GridActionsCellItem` doesn't support TanStack Router navigation. `RouterGridActionsCellItem` wraps it with `createLink` for type-safe routing without manual `onClick` + `navigate`.
+
+Source: wcz-layout:src/components/router/RouterGridActionsCellItem.tsx
+
+### MEDIUM Not passing getLabel to ChipInputCell for complex objects
+
+Wrong:
+
+```typescript
+// params.value is Array<{ id: string; name: string }>
+<ChipInputCell params={params} />
+// Renders [object Object] chips
+```
+
+Correct:
+
+```typescript
+<ChipInputCell
+  params={params}
+  getLabel={(item) => item.name}
+/>
+```
+
+`ChipInputCell` defaults `getLabel` to identity (value as-is). For objects, you must provide `getLabel` to extract the display string.
+
+Source: wcz-layout:src/components/data-grid/ChipInputCell.tsx
+
+### HIGH Tension: MUI component API vs. TanStack Router types
+
+`RouterGridActionsCellItem` merges MUI grid action props with TanStack Router `LinkProps`. Use `to` + `params` for internal navigation. Using `onClick` + `navigate` bypasses the type-safe link and router prefetching.
+
+See also: skills/ui-pages/SKILL.md § Common Mistakes
+
+---
+
+See also:
+
+- skills/tanstack-db-collections/SKILL.md — Grid rows come from useLiveQuery results.
+- skills/ui-pages/SKILL.md — Grid pages follow the same routing patterns.

package/skills/database-schema/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: database-schema
+description: >
+  Design PostgreSQL tables with Drizzle ORM pgTable and derive Zod validation
+  schemas via createSelectSchema from drizzle-orm/zod. Covers uuid primary keys,
+  column types, Zod refinements (trim, min, max), and type inference. Drizzle
+  tables live in src/lib/db/schemas/, Zod schemas in src/schemas/. Activate
+  when creating or modifying database tables or validation schemas.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/lib/db/schemas/"
+  - "wcz-layout:src/schemas/"
+  - "drizzle-orm:docs/zod.md"
+---
+
+# Database Schema Design
+
+## Setup
+
+Database schema files live in two directories:
+
+```
+src/lib/db/schemas/todo.ts       # Drizzle pgTable definition
+src/schemas/todo.ts              # Zod schema derived from the table
+```
+
+## Core Patterns
+
+### Drizzle table definition
+
+```typescript
+// src/lib/db/schemas/todo.ts
+import { boolean, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const todoTable = pgTable("todos", {
+  id: uuid().primaryKey(),
+  name: text().notNull(),
+  description: text(),
+  isCompleted: boolean().notNull().default(false),
+  createdBy: text().notNull(),
+  createdAt: timestamp().notNull().defaultNow(),
+  updatedAt: timestamp().notNull().defaultNow(),
+});
+```
+
+All tables use `uuid().primaryKey()`. IDs are generated client-side with `uuidv7()`.
+
+### Deriving Zod schema from Drizzle
+
+```typescript
+// src/schemas/todo.ts
+import { createSelectSchema } from "drizzle-orm/zod";
+import { todoTable } from "~/lib/db/schemas/todo";
+
+export const TodoSchema = createSelectSchema(todoTable, {
+  name: (schema) => schema.trim().min(1),
+  description: (schema) => schema.trim().nullish(),
+});
+
+export type Todo = typeof TodoSchema._type;
+```
+
+`createSelectSchema` generates a Zod schema matching the table columns. The second argument lets you refine individual fields — add `.trim()`, `.min()`, `.max()`, or replace the schema entirely.
+
+### Insert schema for mutations
+
+```typescript
+// src/schemas/todo.ts
+import { createInsertSchema } from "drizzle-orm/zod";
+
+export const TodoInsertSchema = createInsertSchema(todoTable, {
+  name: (schema) => schema.trim().min(1),
+});
+```
+
+Use `createInsertSchema` when you need a schema for insert operations that omits fields with defaults (like `id`, `createdAt`).
+
+### Type inference
+
+```typescript
+import type { InferSelectModel, InferInsertModel } from "drizzle-orm";
+import { todoTable } from "~/lib/db/schemas/todo";
+
+type Todo = InferSelectModel<typeof todoTable>;
+type NewTodo = InferInsertModel<typeof todoTable>;
+```
+
+Prefer the Zod `_type` for runtime-validated types. Use Drizzle inference types when you need the raw DB shape without validation.
+
+## Common Mistakes
+
+### CRITICAL Writing Zod schemas manually instead of deriving from Drizzle
+
+Wrong:
+
+```typescript
+import { z } from "zod";
+
+export const TodoSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().trim().min(1),
+  isCompleted: z.boolean(),
+});
+```
+
+Correct:
+
+```typescript
+import { createSelectSchema } from "drizzle-orm/zod";
+import { todoTable } from "~/lib/db/schemas/todo";
+
+export const TodoSchema = createSelectSchema(todoTable, {
+  name: (schema) => schema.trim().min(1),
+});
+```
+
+Manual Zod schemas drift from the database when columns are added or renamed. `createSelectSchema` keeps them in sync automatically.
+
+Source: maintainer interview
+
+### HIGH Placing schema files in wrong directory
+
+Wrong:
+
+```
+src/lib/db/schemas/todo.ts      # Contains both pgTable AND Zod schema
+```
+
+Correct:
+
+```
+src/lib/db/schemas/todo.ts      # Only pgTable definition
+src/schemas/todo.ts             # Zod schema derived from the table
+```
+
+Drizzle table definitions and Zod validation schemas live in separate directories. Mixing them in one file violates the project structure convention.
+
+Source: consumer project structure
+
+### HIGH Forgetting uuid primary key convention
+
+Wrong:
+
+```typescript
+import { serial, pgTable, text } from "drizzle-orm/pg-core";
+
+export const todoTable = pgTable("todos", {
+  id: serial().primaryKey(),
+  name: text().notNull(),
+});
+```
+
+Correct:
+
+```typescript
+import { uuid, pgTable, text } from "drizzle-orm/pg-core";
+
+export const todoTable = pgTable("todos", {
+  id: uuid().primaryKey(),
+  name: text().notNull(),
+});
+```
+
+All tables use `uuid().primaryKey()`. IDs are generated client-side with `uuidv7()` for optimistic inserts through TanStack DB collections.
+
+Source: consumer project example
+
+### HIGH Tension: Type safety vs. rapid prototyping
+
+Deriving Zod schemas from Drizzle tables and wiring them through forms requires more setup than quick `useState` + manual validation. Always use the enforced pattern — `createSelectSchema` + `useLayoutForm` — even for simple forms.
+
+See also: skills/forms-validation/SKILL.md § Core Patterns
+
+---
+
+See also:
+
+- skills/api-routes/SKILL.md — Schemas feed into validationMiddleware(Schema).
+- skills/tanstack-db-collections/SKILL.md — Same Zod schema used as collection schema option.
+- skills/forms-validation/SKILL.md — Zod schemas used as form validators.