wcz-layout 8.1.0 → 8.2.0

package/skills/tanstack-db-collections/SKILL.md

@@ -1,270 +0,0 @@
----
-name: tanstack-db-collections
-description: >
-  Wire TanStack DB createCollection with queryCollectionOptions for optimistic
-  client-side data. Set up axios instance with MSAL token interceptor using
-  getAccessToken(scopeKey). CRUD mutation handlers (onInsert, onUpdate, onDelete).
-  Use shared queryClient from wcz-layout/query. Consume with useLiveQuery /
-  useLiveSuspenseQuery. Activate when creating or modifying data collections.
-type: core
-library: wcz-layout
-library_version: "7.6.1"
-requires:
-  - database-schema
-  - api-routes
-sources:
-  - "wcz-layout:src/lib/db/collections/"
-  - "wcz-layout:src/exports/query.ts"
-  - "wcz-layout:src/lib/queryClient.ts"
----
-
-# TanStack DB Collections
-
-## Setup
-
-Collection files live in `src/lib/db/collections/`:
-
-```
-src/lib/db/collections/todoCollection.ts
-```
-
-## Core Patterns
-
-### Creating a collection
-
-```typescript
-// src/lib/db/collections/todoCollection.ts
-import { createCollection } from "@tanstack/react-db";
-import { queryCollectionOptions } from "@tanstack/query-db-collection";
-import axios from "axios";
-import { getAccessToken, queryClient } from "wcz-layout";
-import { TodoSchema } from "~/schemas/todo";
-import type { Todo } from "~/schemas/todo";
-
-const api = axios.create({ baseURL: "/api/todos" });
-
-api.interceptors.request.use(async (config) => {
-  const accessToken = await getAccessToken("api");
-  config.headers.set("Authorization", `Bearer ${accessToken}`);
-  return config;
-});
-
-export const todoCollection = createCollection<Todo>({
-  id: "todos",
-  getKey: (item) => item.id,
-  ...queryCollectionOptions({
-    queryClient,
-    queryKey: ["todos"],
-    queryFn: async () => {
-      const response = await api.get<Todo[]>("");
-      return response.data;
-    },
-    schema: TodoSchema,
-    onInsert: async (item) => {
-      await api.post("", item);
-    },
-    onUpdate: async (item) => {
-      await api.put(`/${item.id}`, item);
-    },
-    onDelete: async (item) => {
-      await api.delete(`/${item.id}`);
-    },
-  }),
-});
-```
-
-### Choosing the scope key
-
-The `getAccessToken(scopeKey)` argument depends on the target service:
-
-| Target              | Scope key | When                              |
-| ------------------- | --------- | --------------------------------- |
-| Your own API routes | `"api"`   | Default — calls to `/api/*`       |
-| Microsoft Graph     | `"graph"` | Calls to `graph.microsoft.com`    |
-| File microservice   | `"file"`  | Calls to the file storage service |
-
-Scope keys are defined in your app's `src/lib/auth/scopes.ts`.
-
-### Consuming collection data in components
-
-```typescript
-import { useLiveQuery } from "@tanstack/react-db";
-import { todoCollection } from "~/lib/db/collections/todoCollection";
-
-function TodoList() {
-  const { data: todos } = useLiveQuery((query) =>
-    query.from({ todos: todoCollection })
-  );
-
-  return (
-    <ul>
-      {todos.map((todo) => (
-        <li key={todo.id}>{todo.name}</li>
-      ))}
-    </ul>
-  );
-}
-```
-
-For Suspense boundaries, use `useLiveSuspenseQuery` instead.
-
-### Optimistic mutations
-
-Collections handle mutations optimistically. Insert, update, and delete operations update the local collection immediately and sync to the server via `onInsert`, `onUpdate`, `onDelete`:
-
-```typescript
-import { todoCollection } from "~/lib/db/collections/todoCollection";
-import { uuidv7 } from "uuidv7";
-
-// Insert — collection updates instantly, API call runs in background
-todoCollection.insert({
-  id: uuidv7(),
-  name: "New task",
-  isCompleted: false,
-  createdBy: user.email,
-  createdAt: new Date(),
-  updatedAt: new Date(),
-});
-
-// Update
-todoCollection.update({ ...existingTodo, name: "Updated name" });
-
-// Delete
-todoCollection.delete(existingTodo);
-```
-
-## Common Mistakes
-
-### CRITICAL Using useQuery / useSuspenseQuery instead of TanStack DB
-
-Wrong:
-
-```typescript
-import { useQuery } from "@tanstack/react-query";
-
-const { data } = useQuery({
-  queryKey: ["todos"],
-  queryFn: fetchTodos,
-});
-```
-
-Correct:
-
-```typescript
-import { useLiveQuery } from "@tanstack/react-db";
-import { todoCollection } from "~/lib/db/collections/todoCollection";
-
-const { data } = useLiveQuery((query) => query.from({ todos: todoCollection }));
-```
-
-The enforced pattern is TanStack DB collections with `useLiveQuery` / `useLiveSuspenseQuery` for all API data. Plain TanStack Query bypasses the optimistic update layer.
-
-Source: maintainer interview
-
-### CRITICAL Creating a new QueryClient instead of using shared one
-
-Wrong:
-
-```typescript
-import { QueryClient } from "@tanstack/react-query";
-const queryClient = new QueryClient();
-```
-
-Correct:
-
-```typescript
-import { queryClient } from "wcz-layout/query";
-```
-
-wcz-layout exports a singleton `queryClient`. Creating a new one breaks cache sharing and SSR query integration.
-
-Source: wcz-layout:src/lib/queryClient.ts
-
-### HIGH Forgetting token interceptor on axios instance
-
-Wrong:
-
-```typescript
-const api = axios.create({ baseURL: "/api/todos" });
-// No interceptor — requests will return 401
-```
-
-Correct:
-
-```typescript
-import { getAccessToken } from "wcz-layout/utils";
-
-const api = axios.create({ baseURL: "/api/todos" });
-api.interceptors.request.use(async (config) => {
-  const accessToken = await getAccessToken("api");
-  config.headers.set("Authorization", `Bearer ${accessToken}`);
-  return config;
-});
-```
-
-API endpoints require Bearer token authentication. Without the interceptor, all requests return 401.
-
-Source: consumer project example
-
-### HIGH Using getKey that returns non-unique values
-
-Wrong:
-
-```typescript
-export const todoCollection = createCollection<Todo>({
-  id: "todos",
-  getKey: (item) => item.name, // names can be duplicated!
-  ...queryCollectionOptions({ ... }),
-});
-```
-
-Correct:
-
-```typescript
-export const todoCollection = createCollection<Todo>({
-  id: "todos",
-  getKey: (item) => item.id, // uuid — always unique
-  ...queryCollectionOptions({ ... }),
-});
-```
-
-`getKey` must return a unique identifier for each item. Using a non-unique field causes silent collection corruption — items overwrite each other.
-
-Source: TanStack DB documentation
-
-### MEDIUM Forgetting schema option in queryCollectionOptions
-
-Wrong:
-
-```typescript
-...queryCollectionOptions({
-  queryClient,
-  queryKey: ["todos"],
-  queryFn: async () => (await api.get("")).data,
-  // no schema — API responses are not validated
-}),
-```
-
-Correct:
-
-```typescript
-...queryCollectionOptions({
-  queryClient,
-  queryKey: ["todos"],
-  queryFn: async () => (await api.get("")).data,
-  schema: TodoSchema,
-}),
-```
-
-The `schema` option enables runtime validation of API responses. Omitting it removes type safety on incoming data — malformed payloads pass silently.
-
-Source: consumer project example
-
----
-
-See also:
-
-- skills/ui-pages/SKILL.md — Pages consume collections via useLiveQuery.
-- skills/database-schema/SKILL.md — Same Zod schema used as collection schema.
-- skills/api-routes/SKILL.md — Collections consume API routes via axios baseURL.
-- skills/data-grid/SKILL.md — Grid rows come from useLiveQuery results.

package/skills/template-init.md

@@ -1,146 +0,0 @@
----
-description: "Initializes a new app from this project template"
----
-
-You are an AI assistant helping a developer initialize a new project from a template.
-
-Follow these steps in exact order.
-
-1. GIT BRANCH CHECK
-   Autonomously check if the current git branch is named `master` (you can execute `git branch --show-current` in the terminal to check).
-   - If the branch is `master`: Proceed directly to step 2.
-   - If the branch is not `master` (e.g., it is `main`): Execute the command `git branch -m main master` in the terminal to rename it. Wait for the command to finish before proceeding to step 2.
-
-2. DEPENDENCY CHECK
-   Check the project root for the presence of a `node_modules` directory.
-   - If `node_modules` is found: Proceed directly to step 3.
-   - If `node_modules` is not found: Output this exact message to the user: "I see `node_modules` is missing. I am running your install script to get your dependencies set up. This might take a moment..."
-     Then, execute the command `npm run npm:install` in the terminal. Wait for the installation process to complete fully before proceeding to step 3.
-
-3. ENVIRONMENT SETUP
-   Search the workspace root for a `.env.local` file.
-   - If found: Proceed directly to step 4.
-   - If not found: Use your edit tools to create `.env.local` in the root directory and populate it with the following initial keys:
-
-     VAULT_ADDRESS=https://vault-dev.wistron.com:8200/
-     VAULT_SECRET_PATH=wcz/sat-qas-01/project-name-wcz/default
-     VAULT_USERNAME=
-     VAULT_PASSWORD=
-
-     DATABASE_URL=
-
-   Once created, let the user know and proceed to step 4.
-
-4. PROJECT NAME REPLACEMENT
-   Ask the user: "What is your project name?"
-   Once the user provides the name, standardise it across the project workspace. You will use your search and edit tools across the entire workspace for placeholder strings and replace them with the user's input, matching the exact casing conventions.
-
-   For example, if the user inputs "Dev Portal":
-   - Replace "project-name" with "dev-portal" (kebab-case)
-   - Replace "Project Name" with "Dev Portal" (Title Case)
-
-   Execute this workspace-wide search and replace. Once completed, tell the user how many files were updated, and proceed to step 5.
-
-5. DATABASE SETUP
-   Ask the user: "Do you already have a Postgres database created?"
-   Wait for the user's response.
-   - If the user answers "yes":
-     Ask the user: "Please enter your database schema name (e.g., 'dev_portal')."
-     Wait for their input. Once provided, **use your file edit tool** to update the `.env` file by setting `DATABASE_SCHEMA=[user-input]`. Then proceed to step 6.
-   - If the user answers "no":
-     Ask the user: "Would you like me to create a local database using Docker?"
-     Wait for the user's response.
-     - If the user answers "yes": Execute the following command in the terminal:
-       `docker run --name drizzle-postgres -e POSTGRES_PASSWORD=admin -d -p 5432:5432 postgres`
-       - If the command succeeds: **Use your file edit tool** to update the `.env.local` file to set `DATABASE_URL=postgres://postgres:admin@localhost:5432/postgres`. Then proceed to step 6.
-       - If the command fails: Output: "It looks like the Docker command failed. Please ensure Docker Desktop is running. Let me know when you are ready to try again, or type 'no' to skip this step." Wait for the user to try again or skip, then proceed accordingly.
-     - If the user answers "no" to creating a local database: Proceed to step 6.
-
-6. ENTRA ID SETUP
-   This step has three parts. Complete them sequentially, waiting for the user at each prompt.
-
-   **Part A: Application Creation**
-   Ask the user: "Is the Entra ID application already created for this project? (yes/no)"
-   - If "no": Output this instruction:
-     "Please navigate to https://itsr.wistron.com/homepage/apply and request the application creation.
-     Path: ITSR Apply -> Service Apply -> Select Service Type -> Azure AD - Application Management - Add or Modify -> fill the information.
-     Since application approval takes time, we will skip the rest of the Entra ID configuration for now. Please type 'continue' once you have submitted the request."
-     Wait for the user to type "continue". Once they do, **SKIP Part B and Part C entirely**, and proceed directly to step 7.
-   - If "yes": Proceed to Part B.
-
-   **Part B: Application Configuration**
-   Ask the user: "Have you configured the created Entra ID application settings? (yes/no)"
-   - If "no": Output this configuration guide:
-     "Please navigate to https://entra.microsoft.com/ and configure your application using these steps:
-
-     **App Registrations:**
-     1. **Authentication:** Add 'Single-page application' and configure your Redirect URIs.
-     2. **Token Configuration:** Add groups claims -> Security groups. Ensure ID, Access, and SAML token properties have checked `sAMAccountName`.
-     3. **Expose an API:** Set the Application ID URI. Add a Scope named `access_as_user` (Admins and users) with appropriate display names/descriptions.
-     4. **Owners:** Add other developers as owners.
-     5. **Manifest:** Update the `api` object properties to `"acceptMappedClaims": true` and `"requestedAccessTokenVersion": 2`.
-
-     **Enterprise Applications:**
-     1. Search for your application.
-     2. **Single Sign-on:** Add custom claims for `employeeId` (Source: user.extensionattribute5) and `department` (Source: user.department). Optionally, add `employeeCategory` (Source: user.extensionattribute13) and `companyName` (Source: user.companyname).
-     3. **Owners:** Add other developers as owners.
-
-     Once you have finished these steps, type 'continue'."
-     Wait for the user to type "continue".
-
-   - If "yes" or once they continue: Proceed to Part C.
-
-   **Part C: Credentials**
-   Ask the user: "Please provide the CLIENT_ID and CLIENT_SECRET for your Entra ID application."
-   Wait for the user's input.
-   Once provided:
-   1. **Use your file edit tool** to update the `.env` file. Find the `VITE_ENTRA_CLIENT_ID=` line and set it to the provided Client ID (e.g., `VITE_ENTRA_CLIENT_ID=[user-provided-client-id]`).
-   2. **CRITICAL:** Do not save the CLIENT_SECRET to any file. Only memorize the CLIENT_SECRET in your context history, as it will be used in a later step.
-
-7. VAULT SETUP
-   Ask the user: "Would you like to set up your environment variables in Vault now? (yes/skip)"
-   - If the user answers "skip": Proceed directly to step 8.
-   - If the user answers "yes": Complete these parts sequentially.
-
-   **Part A: Default Secrets**
-   Output the following instructions:
-   "1. Navigate to https://vault-dev.wistron.com:8200/ui/ and log in. 2. Find your project, open the secret path, and click 'Edit' (ensure you toggle 'View as JSON'). 3. Copy and paste the following JSON block, then save. Once finished, type 'continue'."
-
-   Provide the user with this exact JSON block (fill in the bracketed values dynamically based on the current `.env` and `.env.local` state, and the `CLIENT_SECRET` you memorized in Step 6):
-
-   ```json
-   {
-     "DATABASE_URL": "[DATABASE_URL]",
-     "ENTRA_CLIENT_ID": "[VITE_ENTRA_CLIENT_ID]",
-     "ENTRA_CLIENT_SECRET": "[CLIENT_SECRET]",
-     "ENTRA_TENANT_ID": "de0795e0-d7c0-4eeb-b9bb-bc94d8980d3b"
-   }
-   ```
-
-   Wait for the user to type "continue".
-
-   **Part B: Harbor Vault Secret**
-   Output the following instructions:
-   "Now, go to the root path of your project in Vault and click 'Create secret'.
-   1. Name it exactly: `harborvault`
-   2. Toggle 'JSON' mode.
-   3. Please go to another existing project in your Vault, copy the JSON values from its `harborvault` secret, and paste them into this new one, then save.
-      Once finished, type 'continue'."
-
-   Wait for the user to type "continue".
-
-   **Part C: Local Vault Credentials**
-   Ask the user: "Please provide your Vault Username and Password so I can add them to your local environment."
-   Wait for their input. Once provided, **use your file edit tool** to update the `.env.local` file with the values:
-   `VAULT_USERNAME=[user-provided-username]`
-   `VAULT_PASSWORD=[user-provided-password]`
-   Proceed to step 8.
-
-8. FAVICON GENERATION
-   Ask the user: "Would you like to generate a custom favicon for this project?"
-   - If the user answers "yes": Output this exact instruction:
-     "1. Please navigate to https://favicon.io/favicon-converter/ 2. Upload your app logo (it should be at least 512x512 pixels for the best results). 3. Download the generated file and extract its contents inside your project's `/public` folder.
-
-"Project initialization is complete! Happy coding." and END the workflow.
-
-- If the user answers "no": Output "Project initialization is complete! Happy coding." and END the workflow.

package/skills/ui-pages/SKILL.md

@@ -1,278 +0,0 @@
----
-name: ui-pages
-description: >
-  Build route pages (index, detail, create, edit) with TanStack Router
-  createFileRoute. Use Router-bridged MUI components: RouterButton,
-  RouterLink, RouterIconButton, RouterFab, RouterTab, RouterListItemButton,
-  RouterGridActionsCellItem. Type-safe navigation with to prop. Route params,
-  search params, beforeLoad with requirePermission. Client-first rendering
-  (defaultSsr: false). Activate when creating or modifying page routes.
-type: core
-library: wcz-layout
-library_version: "7.6.1"
-requires:
-  - tanstack-db-collections
-sources:
-  - "wcz-layout:src/components/router/"
-  - "wcz-layout:src/routes/"
-  - "wcz-layout:src/start.ts"
----
-
-# UI Pages & Routing
-
-## Setup
-
-Page routes live under `src/routes/` following TanStack Router file-based conventions:
-
-```
-src/routes/
-├── __root.tsx              # Root layout (LayoutProvider)
-├── index.tsx               # Home page (/)
-└── todos/
-    ├── -components/        # Domain-scoped components (dash prefix!)
-    │   └── TodoForm.tsx
-    ├── index.tsx            # /todos — list page
-    ├── create.tsx           # /todos/create — create page
-    ├── $id.tsx              # /todos/$id — detail page
-    └── edit.$id.tsx         # /todos/edit/$id — edit page
-```
-
-## Core Patterns
-
-### List page
-
-```typescript
-// src/routes/todos/index.tsx
-import { createFileRoute } from "@tanstack/react-router";
-import { useLiveQuery } from "@tanstack/react-db";
-import { RouterButton } from "wcz-layout/components";
-import { todoCollection } from "~/lib/db/collections/todoCollection";
-
-export const Route = createFileRoute("/todos/")({
-  component: TodosPage,
-});
-
-function TodosPage() {
-  const { data: todos } = useLiveQuery((query) =>
-    query.from({ todos: todoCollection })
-  );
-
-  return (
-    <div>
-      <RouterButton to="/todos/create" variant="contained">
-        Create Todo
-      </RouterButton>
-      {todos.map((todo) => (
-        <RouterLink key={todo.id} to="/todos/$id" params={{ id: todo.id }}>
-          {todo.name}
-        </RouterLink>
-      ))}
-    </div>
-  );
-}
-```
-
-### Detail page with route params
-
-```typescript
-// src/routes/todos/$id.tsx
-import { createFileRoute } from "@tanstack/react-router";
-
-export const Route = createFileRoute("/todos/$id")({
-  component: TodoDetailPage,
-});
-
-function TodoDetailPage() {
-  const { id } = Route.useParams();
-  // use id to filter collection data or fetch detail
-}
-```
-
-### Permission-guarded page
-
-```typescript
-import { createFileRoute } from "@tanstack/react-router";
-import { requirePermission } from "wcz-layout/utils";
-
-export const Route = createFileRoute("/admin/")({
-  beforeLoad: requirePermission("admin"),
-  component: AdminPage,
-});
-```
-
-`requirePermission` is a route `beforeLoad` guard that checks if the current user has the specified permission. Redirects to unauthorized if not.
-
-### Router-bridged MUI components
-
-These components merge MUI props with TanStack Router `LinkProps`. Use `to` for internal navigation (type-safe), `href` only for external URLs:
-
-| Component                   | MUI base            | Use case                |
-| --------------------------- | ------------------- | ----------------------- |
-| `RouterButton`              | Button              | Navigation buttons      |
-| `RouterLink`                | Link (Typography)   | Inline text links       |
-| `RouterIconButton`          | IconButton          | Icon-only navigation    |
-| `RouterFab`                 | Fab                 | Floating action buttons |
-| `RouterTab`                 | Tab                 | Tab-based navigation    |
-| `RouterListItemButton`      | ListItemButton      | Sidebar/list navigation |
-| `RouterGridActionsCellItem` | GridActionsCellItem | DataGrid row actions    |
-
-All accept the same TanStack Router link props: `to`, `params`, `search`, `hash`.
-
-### Root route structure
-
-```typescript
-// src/routes/__root.tsx
-import { createRootRouteWithContext, Outlet } from "@tanstack/react-router";
-import { LayoutProvider, rootRouteHead } from "wcz-layout";
-import type { ProvidersProps } from "wcz-layout";
-
-export const Route = createRootRouteWithContext()({
-  head: rootRouteHead,
-  component: RootComponent,
-  notFoundComponent: RouterNotFound,
-  errorComponent: RouterError,
-});
-
-function RootComponent() {
-  return (
-    <LayoutProvider theme={theme} navigation={navigation} options={options}>
-      <Outlet />
-    </LayoutProvider>
-  );
-}
-```
-
-## Common Mistakes
-
-### CRITICAL Using React Router or window.location for navigation
-
-Wrong:
-
-```typescript
-import { useNavigate } from "react-router-dom";
-// or
-window.location.href = "/todos";
-```
-
-Correct:
-
-```typescript
-import { useNavigate } from "@tanstack/react-router";
-const navigate = useNavigate();
-navigate({ to: "/todos" });
-```
-
-This stack uses TanStack Router exclusively. React Router does not exist in the dependency tree. `window.location` causes a full page reload, bypassing the SPA router.
-
-Source: copilot-instructions.md
-
-### HIGH Using MUI Button with href instead of RouterButton
-
-Wrong:
-
-```typescript
-<Button href="/todos/create">Create</Button>
-```
-
-Correct:
-
-```typescript
-import { RouterButton } from "wcz-layout/components";
-
-<RouterButton to="/todos/create" variant="contained">
-  Create
-</RouterButton>
-```
-
-Plain MUI `Button` with `href` causes a full page reload. `RouterButton` uses TanStack Router's `createLink` for SPA navigation with type-safe routes.
-
-Source: wcz-layout:src/components/router/RouterButton.tsx
-
-### HIGH Assuming SSR is enabled
-
-Wrong:
-
-```typescript
-// Expecting server-side data in a route loader
-export const Route = createFileRoute("/todos/")({
-  loader: async () => {
-    return { todos: await fetchTodos() }; // runs on server — but SSR is off
-  },
-});
-```
-
-Correct:
-
-```typescript
-// Use TanStack DB collections for client-side data
-function TodosPage() {
-  const { data } = useLiveQuery((q) => q.from({ todos: todoCollection }));
-}
-```
-
-`start.ts` sets `defaultSsr: false`. Pages render client-side first. Do not rely on SSR data fetching patterns — use TanStack DB collections instead.
-
-Source: wcz-layout:src/start.ts
-
-### MEDIUM Omitting suppressHydrationWarning on html element
-
-The root route's `<html>` element must include `suppressHydrationWarning` because i18n language detection and color scheme can differ between server and client initial renders.
-
-Source: wcz-layout:src/routes/\_\_root.tsx
-
-### HIGH Using useMemo or useCallback
-
-Wrong:
-
-```typescript
-const filteredTodos = useMemo(() => todos.filter((t) => t.isCompleted), [todos]);
-```
-
-Correct:
-
-```typescript
-const filteredTodos = todos.filter((t) => t.isCompleted);
-```
-
-React Compiler handles memoization automatically. Manual `useMemo` / `useCallback` is forbidden per project conventions.
-
-Source: copilot-instructions.md
-
-Cross-skill: See also skills/forms-validation/SKILL.md § Common Mistakes
-
-### HIGH Tension: MUI component API vs. TanStack Router types
-
-Router-bridged components merge MUI props with TanStack Router `LinkProps`. Use `to` for internal routes and `href` only for external URLs. Passing `href` for an internal route causes a full page reload.
-
-See also: skills/data-grid/SKILL.md § Common Mistakes
-
-### HIGH Using theme.palette for dark mode instead of theme.applyStyles
-
-Wrong:
-
-```typescript
-sx={{ color: mode === "dark" ? "white" : "black" }}
-```
-
-Correct:
-
-```typescript
-sx={(theme) => ({
-  color: "black",
-  ...theme.applyStyles("dark", { color: "white" }),
-})}
-```
-
-The app uses `colorSchemeSelector: "data-mui-color-scheme"`. Always use `theme.applyStyles("dark", ...)` for mode-specific styling.
-
-Source: copilot-instructions.md
-
-Cross-skill: See also skills/layout-navigation/SKILL.md § Common Mistakes
-
----
-
-See also:
-
-- skills/forms-validation/SKILL.md — Create/edit pages embed forms.
-- skills/layout-navigation/SKILL.md — Pages render inside the layout shell.
-- skills/tanstack-db-collections/SKILL.md — Pages consume collections via useLiveQuery.