wcz-layout 8.1.0 → 8.2.0

package/skills/routes/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: routes
+description: Understand and follow the project's file structure, route conventions, and colocated architecture when creating routes.
+---
+
+## First Step (required)
+
+Before generating route, always ask the user what permission should be required for access. Suggest `all`, `admin`, or a custom permission key.
+
+## Rules
+
+- Always include `requirePermission("permissionKey")` in the route's `beforeLoad` function to enforce access control; match the `permissionKey` with link in `__root.tsx`.
+- Use `Route.useRouteContext()` to access the authenticated user. This will be `null` if the route doesn't include `requirePermission`.
+- Use the route `loader` option to preload db collections. Preload only root-level collections.
+- Create and use `pendingComponent` for routes with suspense live queries.
+- Route names must always be kebab-case. Entity route names must always be plural.
+- If a feature contains only one route, create a single file route: `src/routes/libraries.tsx`
+- If a feature contains multiple related routes, create a folder: `src/routes/libraries/index.tsx`
+- Colocate route-specific components/hooks inside `routes/feature-name/-components` and `-hooks`. Root-level `components/` and `hooks/` are only for code shared across multiple routes.
+- After creating a new route, add a navigation item with a unique corresponding icon from `@mui/icons-material` in `__root.tsx`.
+
+## Base Project Structure
+
+```txt
+src/                           # client-first architecture
+├── components/                # shared components across multiple routes
+├── db-collections/            # tanstack-db collections
+├── hooks/                     # shared hooks across multiple routes
+├── lib/                       # contains isomorphic/shared logic usable by both client and server
+│   ├── auth/
+│   │   ├── permissions.ts
+│   │   └── scopes.ts
+│   ├── locales/
+│   │   ├── cs.json
+│   │   └── en.json
+│   └── schemas/               # shared zod schemas
+├── routes/                    # TanStack Router file-based routing
+│   ├── __root.tsx
+│   ├── index.tsx
+│   └── features/              # route group with multiple pages
+│       ├── -components/       # components specific to feature routes
+│       ├── -hooks/            # hooks specific to feature routes
+│       ├── index.tsx
+│       ├── create.tsx
+│       ├── edit.$id.tsx
+│       └── $id.tsx
+├── server/                    # server-only code
+│   ├── db/
+│   │   ├── migrations/
+│   │   ├── schemas/           # drizzle database schemas
+│   │   │   └── feature.ts
+│   │   └── index.ts           # drizzle db instance
+│   ├── middleware/
+│   │   └── databaseMiddleware.ts
+│   └── feature.ts             # server functions / api logic
+└── types/
+```
+
+## Examples
+
+```ts
+// imports
+import { useDialogs, useTranslation } from "wcz-layout/hooks";
+import { requirePermission, uuidv7 } from "wcz-layout/utils";
+
+// src/routes/books/create.tsx
+export const Route = createFileRoute("/books/create")({
+  component: RouteComponent,
+  beforeLoad: requirePermission("all"),
+  pendingComponent: BookFormSkeleton,
+  loader: () => {
+    libraryCollection.preload();
+  },
+});
+
+function RouteComponent() {
+  const { t } = useTranslation();
+  const { alert, confirm } = useDialogs();
+  const { user } = Route.useRouteContext();
+
+  // route component code...
+}
+
+// __root.tsx
+const { user } = Route.useRouteContext();
+
+const navigation: Navigation = [
+  {
+    kind: "item",
+    to: "/",
+    title: "Home",
+    icon: <Home />,
+    hidden: !user?.hasPermission("all"),
+  },
+  {
+    kind: "header",
+    title: "Documentation",
+  },
+  {
+    kind: "group",
+    title: "Components",
+    icon: <Widgets />,
+    children: [
+      {
+        kind: "item",
+        to: "/components/navigation",
+        title: "Navigation",
+        icon: <AccountTree />,
+      },
+      {
+        kind: "divider",
+      },
+      {
+        kind: "item",
+        to: "/components/forms",
+        title: "Forms",
+        icon: <Code />,
+      },
+    ],
+  },
+];
+```
+
+## Next Step (ask user after completion)
+
+- Create table with mui-x-data-grid for index route.
+- Create a form with TanStack Form inside `create` or `edit.$id` routes.

package/skills/server/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: server
+description: Create TanStack Start server functions or REST API routes using Drizzle ORM, Zod schemas and middleware.
+---
+
+## First Step (required)
+
+Before generating code, always ask the user whether the feature should be exposed as public REST API routes or implemented as internal TanStack Start server functions (recommended), and what permission should be required for access.
+
+## Rules
+
+- Follow the chain order for server functions: `inputValidator` → `middleware` → `handler`.
+- In middleware, always follow this order: `validationMiddleware` → `databaseMiddleware` → `authorizationMiddleware`.
+- Use `validationMiddleware` only in REST API routes (handler-level middleware). Server functions use `.inputValidator()` instead.
+- If permission is unknown, use `"all"`.
+- `databaseMiddleware` wraps the handler in a DB transaction.
+- Reuse schemas from `src/lib/schemas/`.
+
+## File Placement
+
+```
+src/server/actions/             — server functions
+src/routes/api/                 — REST API routes
+src/server/middleware/          — server middleware
+wcz-layout/middleware/          — shared middleware from npm package
+src/server/db/schemas/          — tables, enums, relations
+src/lib/schemas/                — Zod schemas
+src/lib/auth/permissions.ts     — permission keys
+```
+
+## Examples
+
+```ts
+// imports
+import { authorizationMiddleware, validationMiddleware } from "wcz-layout/middleware";
+import { databaseMiddleware } from "~/server/middleware/databaseMiddleware";
+
+// src/server/actions/books.ts
+export const selectBooks = createServerFn()
+  .middleware([databaseMiddleware, authorizationMiddleware("all")])
+  .handler(async ({ context }) => {
+    return await context.db.select().from(bookTable);
+  });
+
+export const insertBook = createServerFn({ method: "POST" })
+  .inputValidator(BookSchema)
+  .middleware([databaseMiddleware, authorizationMiddleware("admin")])
+  .handler(async ({ data, context }) => {
+    await context.db.insert(bookTable).values(data);
+  });
+
+export const updateBook = createServerFn({ method: "POST" })
+  .inputValidator(BookSchema)
+  .middleware([databaseMiddleware, authorizationMiddleware("admin")])
+  .handler(async ({ data, context }) => {
+    await context.db.update(bookTable).set(data).where(eq(bookTable.id, data.id));
+  });
+
+export const deleteBook = createServerFn({ method: "POST" })
+  .inputValidator(BookSchema.pick({ id: true }))
+  .middleware([databaseMiddleware, authorizationMiddleware("admin")])
+  .handler(async ({ data, context }) => {
+    await context.db.delete(bookTable).where(eq(bookTable.id, data.id));
+  });
+
+// src/routes/api/books/index.ts
+export const Route = createFileRoute("/api/books/")({
+  server: {
+    middleware: [databaseMiddleware],
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        GET: {
+          middleware: [authorizationMiddleware("all")],
+          handler: async ({ context }) => {
+            const items = await context.db.select().from(bookTable);
+            return Response.json(items);
+          },
+        },
+        POST: {
+          middleware: [validationMiddleware(BookSchema), authorizationMiddleware("admin")],
+          handler: async ({ context }) => {
+            const [response] = await context.db.insert(bookTable).values(context.data).returning();
+            return Response.json(response, { status: 201 });
+          },
+        },
+      }),
+  },
+});
+
+// src/routes/api/books/$id.ts
+export const Route = createFileRoute("/api/books/$id")({
+  server: {
+    middleware: [databaseMiddleware, authorizationMiddleware("admin")],
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        PUT: {
+          middleware: [validationMiddleware(BookSchema)],
+          handler: async ({ params, context }) => {
+            await context.db.update(bookTable).set(context.data).where(eq(bookTable.id, params.id));
+            return new Response(null, { status: 204 });
+          },
+        },
+        DELETE: async ({ params, context }) => {
+          await context.db.delete(bookTable).where(eq(bookTable.id, params.id));
+          return new Response(null, { status: 204 });
+        },
+      }),
+  },
+});
+```
+
+## Next Step (ask user after completion)
+
+- Generate TanStack DB Collection.

package/skills/start/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: start
+description: Initialize a new project from the standard template
+---
+
+# Project Initialization Orchestrator
+
+## Role
+
+You are an AI assistant helping a developer bootstrap a new project from this template.
+
+## Execution Rules
+
+- Execute steps in order. Read **only** the current step file.
+- Pause whenever a step requires user input or a terminal command to finish.
+- Do not skip ahead or batch multiple steps unless a step explicitly allows it.
+- When a step has branches (yes/no), follow only the matching branch.
+
+## Opening Message
+
+Begin every conversation with:
+
+> To make initialization flexible, you can choose:
+>
+> - ✅ **Full initialization** (recommended for new projects)
+> - ✅ **Partial / custom steps** (select specific steps below)
+
+Then list all steps by name so the user can pick.
+
+## Steps
+
+| #   | File                             | Summary                         |
+| --- | -------------------------------- | ------------------------------- |
+| 1   | `steps/01-git-setup.md`          | Configure remote and branch     |
+| 2   | `steps/02-dependency-check.md`   | Install npm dependencies        |
+| 3   | `steps/03-env-setup.md`          | Create `.env.local`             |
+| 4   | `steps/04-project-name-setup.md` | Replace placeholder names       |
+| 5   | `steps/05-database-setup.md`     | Postgres via Docker or existing |
+| 6   | `steps/06-entra-setup.md`        | Azure AD app registration       |
+| 7   | `steps/07-vault-setup.md`        | Vault secrets configuration     |
+| 8   | `steps/08-generate-favicon.md`   | Generate and replace favicon    |
+| 9   | `steps/09-commit.md`             | Commit and push to origin       |
+
+## Completion
+
+After step 9 succeeds, the workflow ends — no further action needed.

package/skills/start/steps/01-git-setup.md

@@ -0,0 +1,10 @@
+# Git Setup
+
+## Actions
+
+1. Run `git remote -v`.
+   - **No remote exists** → ask for the repository URL, then run `git remote add origin <url>`.
+   - **Remote exists** → continue.
+2. Run `git branch --show-current`.
+   - **Not `master`** → run `git branch -M master`.
+   - **Already `master`** → continue.

package/skills/start/steps/02-dependency-check.md

@@ -0,0 +1,11 @@
+# Dependency Check
+
+## Actions
+
+1. Check for a `node_modules` directory in the project root.
+   - **Exists** → continue.
+   - **Missing** → output exactly:
+
+     > I see `node_modules` is missing. I am running your install script to get your dependencies set up. This might take a moment...
+
+     Run `npm run vp:install` and **proceed immediately** without waiting for completion.

package/skills/start/steps/03-env-setup.md

@@ -0,0 +1,16 @@
+# Environment Setup
+
+## Actions
+
+1. Check for `.env.local` in the workspace root.
+   - **Exists** → continue.
+   - **Missing** → create `.env.local` with this exact content:
+
+```env
+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=
+```

package/skills/start/steps/04-project-name-setup.md

@@ -0,0 +1,14 @@
+# Project Name Setup
+
+## User Input
+
+Ask: **"What is your project name?"**
+
+## Actions
+
+Once provided, search-and-replace across the **entire workspace**:
+
+| Find           | Replace with                           |
+| -------------- | -------------------------------------- |
+| `project-name` | kebab-case version (e.g. `user-input`) |
+| `Project Name` | Title Case version (e.g. `User Input`) |

package/skills/start/steps/05-database-setup.md

@@ -0,0 +1,37 @@
+# Database Setup
+
+## User Input
+
+Ask: **"Do you already have a Postgres database created for this project? (yes/no)"**
+
+## Branch A — Existing database
+
+1. Ask: **"Please enter your database schema name (e.g. `dev_portal`)."**
+2. Update `.env.local` → set `DATABASE_SCHEMA=<user-input>`.
+
+## Branch B — No database
+
+Ask: **"Would you like me to create a local Postgres database using Docker? (yes/no)"**
+
+- **No** → continue to next step.
+- **Yes** → execute the Docker flow below.
+
+### Docker flow
+
+The container name is `<project-name>-postgres` where `<project-name>` is the kebab-case project name (read from the `name` field in `package.json`).
+
+1. Ensure the Docker daemon is running. If not, start Docker Desktop via terminal automatically.
+2. Auto-generate password.
+3. Discover occupied ports by listing **all** containers (including stopped) and pick the first port in **5432 → 5450** that does **not** appear in the output. If all ports are occupied, stop and inform the user.
+4. Run the container on the chosen port:
+
+```powershell
+docker run --name <project-name>-postgres -e POSTGRES_PASSWORD=<password> -d -p <PORT>:5432 postgres
+```
+
+- **Success** → continue.
+- **Error** → stop and show the full error to the user.
+
+5. Update `.env.local` → set `DATABASE_URL=postgres://postgres:<password>@localhost:<PORT>/postgres`.
+6. Output exactly:
+   > ✅ Local Postgres database created successfully on port [PORT]

package/skills/start/steps/06-entra-setup.md

@@ -0,0 +1,59 @@
+# Entra ID Setup
+
+Execute parts A → B → C sequentially. Pause for user input at each part.
+
+---
+
+## Part A — Application Creation
+
+Ask: **"Is the Entra ID application already created for this project? (yes/no)"**
+
+- **Yes** → proceed to Part B.
+- **No** → output exactly:
+
+> Please navigate to https://itsr.wistron.com/homepage/apply and request the application creation.
+> Actions: Select Service Type → Azure AD - Application Management - Add or Modify → Add Application → Add Applicant → Fill in application details → Submit → Submit.
+> Since approval takes time, we will skip the rest of Entra ID configuration for now. Please type 'done' once you have submitted the request.
+
+Wait for "done", then **skip Parts B and C** and continue to the next step.
+
+---
+
+## Part B — Application Configuration
+
+Ask: **"Have you configured the Entra ID application settings? (yes/no)"**
+
+- **Yes** → proceed to Part C.
+- **No** → output the full configuration guide:
+
+> Please navigate to https://entra.microsoft.com/ and configure your application:
+>
+> **Left navigation: App Registrations:**
+>
+> 1. Search for your application and open it.
+> 2. **Authentication:** Add 'Single-page application' and configure your Redirect URIs.
+> 3. **Token Configuration:** Add groups claims → Security groups. Ensure ID, Access, and SAML token properties have checked `sAMAccountName`.
+> 4. **Expose an API:** Set the Application ID URI. Add a Scope named `access_as_user` (Admins and users) with appropriate display names/descriptions.
+> 5. **Owners:** Add other developers as owners.
+> 6. **Manifest:** Update the `api` object: `"acceptMappedClaims": true` and `"requestedAccessTokenVersion": 2`.
+>
+> **Left navigation: Enterprise Applications:**
+>
+> 1. Search for your application and open it.
+> 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 "continue", then proceed to Part C.
+
+---
+
+## Part C — Credentials
+
+Ask: **"Please provide the CLIENT_ID and CLIENT_SECRET for your Entra ID application."**
+
+Once received:
+
+1. Update `.env.local` → set `VITE_ENTRA_CLIENT_ID=<CLIENT_ID>`.
+2. **CRITICAL**: Do **not** save `CLIENT_SECRET` to any file. Memorize it in context for use in the Vault Setup step only.

package/skills/start/steps/07-vault-setup.md

@@ -0,0 +1,56 @@
+# Vault Setup
+
+Ask: **"Would you like to set up your environment variables in Vault now? (yes/skip)"**
+
+- **Skip** → continue to next step.
+- **Yes** → execute parts A → B → C sequentially.
+
+---
+
+## Part A — Default Secrets
+
+Output:
+
+> 1. Navigate to https://vault-dev.wistron.com:8200/ui/ and log in.
+> 2. Find your project, open the "default" secret path, click 'Edit' (toggle 'View as JSON').
+> 3. Copy and paste the following JSON block, then save. When finished, type 'done'.
+
+Provide this JSON with values pulled from `.env.local` and the memorized `CLIENT_SECRET`:
+
+```json
+{
+  "DATABASE_URL": "[DATABASE_URL from .env.local]",
+  "ENTRA_CLIENT_ID": "[VITE_ENTRA_CLIENT_ID from .env.local]",
+  "ENTRA_CLIENT_SECRET": "[memorized CLIENT_SECRET]",
+  "ENTRA_TENANT_ID": "de0795e0-d7c0-4eeb-b9bb-bc94d8980d3b"
+}
+```
+
+Wait for "done".
+
+---
+
+## Part B — Harbor Vault Secret
+
+Output:
+
+> 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. 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 'done'.
+
+Wait for "done".
+
+---
+
+## Part C — Local Vault Credentials
+
+Ask: **"Please provide your Vault Username and Password so I can add them to your local environment."**
+
+Once received, update `.env.local`:
+
+- `VAULT_USERNAME=<username>`
+- `VAULT_PASSWORD=<password>`

package/skills/start/steps/08-generate-favicon.md

@@ -0,0 +1,15 @@
+# Favicon Generation
+
+Ask: **"Would you like to generate a custom favicon for this project? (yes/no)"**
+
+- **No** → continue to next step.
+- **Yes** → output:
+
+> 1. Navigate to https://favicon.io/favicon-converter/
+> 2. Upload your app logo (at least 512×512 pixels for best results).
+> 3. Download the generated `.zip` file and extract its contents.
+> 4. Replace everything inside your project's `/public` folder with those extracted files.
+>
+> Once you have finished replacing the files, type 'done'.
+
+Wait for "done".

package/skills/start/steps/09-commit.md

@@ -0,0 +1,15 @@
+# Initial Commit
+
+## Actions
+
+Run sequentially:
+
+```shell
+git add .
+git commit -m "initial project setup"
+git push -u origin master
+```
+
+Wait for completion. Once the push succeeds, output:
+
+> **✅ Project initialization is complete! Happy coding.**