create-simone-app 0.1.0

package/templates/api/variants/framework/express/test/errorHandler.test.ts

@@ -0,0 +1,89 @@
+import express from 'express'
+import request from 'supertest'
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import { HttpError } from '../src/lib/http-error'
+import { errorHandler } from '../src/middleware/errorHandler'
+import { validate } from '../src/middleware/validate'
+
+const app = express()
+app.use(express.json())
+app.get('/teapot', () => {
+  throw new HttpError(418, 'I am a teapot', { hot: true })
+})
+app.get('/boom', () => {
+  throw new Error('secret internals')
+})
+app.get(
+  '/echo/:id',
+  validate(
+    {
+      query: z.object({ n: z.coerce.number().int().min(1) }),
+      params: z.object({ id: z.uuid() }),
+    },
+    ({ query, params }, _req, res) => {
+      res.json({ n: query.n, id: params.id })
+    },
+  ),
+)
+app.post(
+  '/items',
+  validate(
+    { body: z.object({ name: z.string().min(1) }) },
+    ({ body }, _req, res) => {
+      res.status(201).json(body)
+    },
+  ),
+)
+app.use(errorHandler)
+
+describe('errorHandler', () => {
+  it('maps HttpError to its status and shape', async () => {
+    const res = await request(app).get('/teapot')
+    expect(res.status).toBe(418)
+    expect(res.body).toEqual({ error: 'I am a teapot', details: { hot: true } })
+  })
+
+  it('hides unknown errors behind 500', async () => {
+    const res = await request(app).get('/boom')
+    expect(res.status).toBe(500)
+    expect(res.body).toEqual({ error: 'Internal Server Error' })
+  })
+})
+
+describe('validate', () => {
+  const id = '6f1c8b2e-4a7d-4c1e-9b0a-2d3e4f5a6b7c'
+
+  it('passes typed query and params to the handler', async () => {
+    const res = await request(app).get(`/echo/${id}?n=3`)
+    expect(res.status).toBe(200)
+    expect(res.body).toEqual({ n: 3, id })
+  })
+
+  it('invalid query → 422 with details', async () => {
+    const res = await request(app).get(`/echo/${id}?n=0`)
+    expect(res.status).toBe(422)
+    expect(res.body.error).toBe('Invalid query')
+    expect(res.body.details).toEqual([
+      { path: 'n', message: expect.any(String) },
+    ])
+  })
+
+  it('invalid params → 422', async () => {
+    const res = await request(app).get('/echo/not-a-uuid?n=1')
+    expect(res.status).toBe(422)
+    expect(res.body.error).toBe('Invalid params')
+  })
+
+  it('invalid body → 422', async () => {
+    const res = await request(app).post('/items').send({ name: '' })
+    expect(res.status).toBe(422)
+    expect(res.body.error).toBe('Invalid body')
+  })
+
+  it('valid body → 201', async () => {
+    const res = await request(app).post('/items').send({ name: 'x' })
+    expect(res.status).toBe(201)
+  })
+})

package/templates/api/variants/framework/express/variant.json

@@ -0,0 +1,15 @@
+{
+  "dependencies": {
+    "cors": "^2.8.6",
+    "express": "5",
+    "helmet": "^8.3.0",
+    "pino": "^10.3.1",
+    "pino-http": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "pino-pretty": "^13.1.3"
+  },
+  "agents": ["framework-express"]
+}

package/templates/fe/base/.agents/skills/ai-rules/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: ai-rules
+description: Consult the company ai-rules mirrored in docs/ai-rules before writing code that they cover (test selectors, and in the FE template also stack, TanStack, shadcn, a11y). Use whenever a rule might apply.
+---
+
+# ai-rules
+
+1. `AGENTS.md` → "## ai-rules" table maps topic → `docs/ai-rules/<file>`. Read the relevant file section, not the whole file.
+2. The rules are company-wide and **read-only**: never edit `docs/ai-rules/*`. If a rule looks wrong, propose a change upstream and keep following it here.
+3. A deliberate deviation must be listed in `docs/agents/deviations.md` with the rule § and the reason, then `bun run agents:build`.
+4. `bun run rules:check` fails when the mirror drifted from upstream (`AI_RULES_PATH` or `~/Progetti/ai-rules`): run `bun run rules:sync` and commit `docs/ai-rules/` + `MANIFEST.json` in their own `chore(rules): sync ai-rules` commit.
+5. The "## Non-negotiables" digest in `AGENTS.md` must never contradict `docs/ai-rules/`; the full text wins.

package/templates/fe/base/.agents/skills/plan-feature/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: plan-feature
+description: Turn a feature request into TASK.md with small verifiable increments (one commit each). Use before writing code for anything bigger than a one-line fix.
+---
+
+# plan-feature
+
+1. Copy `TASK.md.template` to `TASK.md` (git-ignored).
+2. Fill **Goal** in one sentence and **Context** with the files that will change (read them first).
+3. Split into increments of ≤ 1 hour each. Each row: what, files, how to verify (a test name or a curl), commit subject in Conventional Commits.
+4. Ordering rule: schema → api → hook (queryOptions) → component → route, test-first when behaviour is clear (see `tdd-step`).
+5. Anything that would deviate from `docs/ai-rules/` goes into the **Deviations** section _before_ implementation.
+6. Show the plan and wait for confirmation only if a decision is not covered by `AGENTS.md`; otherwise start with increment 1.

package/templates/fe/base/.agents/skills/review-diff/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: review-diff
+description: Review the working-tree diff against AGENTS.md before committing. Use at the end of every increment or when asked "review".
+---
+
+# review-diff
+
+1. `git diff` and `git diff --staged`; read `AGENTS.md`.
+2. Run `bun run verify`; a red verify is finding #1.
+3. Walk the checklist in `.claude/agents/reviewer.md` (contracts, types, runtime, tests, openapi, generated files untouched).
+4. Report only violations, as `path:line — problem — fix`. No praise, no restating the diff.
+5. End with APPROVE / REQUEST CHANGES.

package/templates/fe/base/.agents/skills/tdd-step/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: tdd-step
+description: Execute one increment red → green → refactor → verify → commit. Use for every increment of TASK.md.
+---
+
+# tdd-step
+
+1. **Red**: write the failing test first. Hooks/API → `src/features/<f>/__tests__/*.test.tsx` with MSW handlers in `src/test/msw/handlers.ts`; pages → `renderApp('/route')` from `src/test/render.tsx`. Run `bunx vitest run <file>` and confirm it fails for the right reason.
+2. **Green**: minimal code. Data layer = `*.schema.ts` (zod) → `*.api.ts` (apiClient) → `use*.ts` (queryOptions factory); UI composes `src/components/ui/*` wrappers, every interactive element has `data-testid`.
+3. **Refactor** only what the new code touched. State that crosses routes goes in search params, not in a store.
+4. New shadcn component needed → `bunx shadcn@latest add <name>`, never hand-written.
+5. `bun run verify` must be green (typecheck, lint incl. a11y/testid rules, format, AGENTS check, coverage ≥80% on features). `bun run e2e` when a route changed.
+6. One commit: `type(scope): subject` in English, body in Italian explaining _why_. Show `git log --oneline -1`.
+7. Tick the increment in `TASK.md`.

package/templates/fe/base/.claude/agents/reviewer.md

@@ -0,0 +1,21 @@
+---
+name: reviewer
+description: Reviews a diff against AGENTS.md conventions and docs/ai-rules. Use after each increment, before committing.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You review the current diff (`git diff` + `git diff --staged`) of __NAME__. Read `AGENTS.md` first.
+
+Check, in this order, and report only violations with file:line and a one-line fix:
+
+1. `bun run verify` is green (run it). `bun run e2e` if routes or the users feature changed.
+2. Dogmas: HTTP only via `@/lib/apiClient`; state only via `@/stores`; `@base-ui/*` only in `components/ui`; shadcn components added via CLI, never edited; single `src/index.css`.
+3. `data-testid` on every interactive/stateful element, `feature-element-qualifier`, `{id}` suffix on repeated rows (docs/ai-rules/testing-selectors.md).
+4. a11y: `<caption>` + `aria-sort` on tables, `<nav aria-label>` on pagination, `aria-label` on icon-only buttons, no `<div onClick>`, focus ring never removed (docs/ai-rules/a11y.md, accessibility-legge-stanca.md).
+5. TanStack: `queryOptions` factory + key factory, table state in search params with `validateSearch`, `head.title` on every route.
+6. Types: no `any`, `@ts-ignore`, `enum`, `!`, `React.FC`, `forwardRef`; `import type` where possible.
+7. Tests: feature code has co-located `__tests__` with MSW; coverage stays ≥80% on `src/features`.
+8. Nothing edited by hand in `AGENTS.md`, `docs/ai-rules/`, `src/components/ui/`, `src/routeTree.gen.ts`.
+
+Finish with "APPROVE" or "REQUEST CHANGES" and, if changes, the commit message subject you would use.

package/templates/fe/base/.claude/hooks/format.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# PostToolUse hook: prettier + eslint --fix on the file just edited.
+# Reads $CLAUDE_FILE_PATH, falls back to the hook JSON on stdin. Exit 0 on anything not lintable.
+set -uo pipefail
+
+file="${CLAUDE_FILE_PATH:-}"
+if [ -z "$file" ] && [ ! -t 0 ]; then
+  file="$(bun -e 'const s = await Bun.stdin.text(); try { const j = JSON.parse(s); console.log(j.tool_input?.file_path ?? j.file_path ?? "") } catch { console.log("") }')"
+fi
+[ -n "$file" ] && [ -f "$file" ] || exit 0
+
+case "$file" in
+  *.ts|*.tsx|*.js|*.jsx|*.json|*.md|*.yaml|*.yml|*.css) ;;
+  *) exit 0 ;;
+esac
+
+cd "$(dirname "${BASH_SOURCE[0]}")/../.." || exit 0
+bunx prettier --write --log-level warn "$file" || true
+case "$file" in
+  *.ts|*.tsx|*.js|*.jsx) bunx eslint --fix --no-warn-ignored "$file" || true ;;
+esac
+exit 0

package/templates/fe/base/.claude/settings.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(bun run:*)",
+      "Bash(bun install:*)",
+      "Bash(bun add:*)",
+      "Bash(bunx vitest:*)",
+      "Bash(bunx eslint:*)",
+      "Bash(bunx prettier:*)",
+      "Bash(bunx tsc:*)",
+      "Bash(bunx playwright:*)",
+      "Bash(bunx shadcn:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ],
+    "deny": [
+      "Bash(git push:*)",
+      "Bash(rm -rf:*)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Edit(AGENTS.md)",
+      "Edit(docs/ai-rules/**)",
+      "Edit(src/components/ui/**)",
+      "Edit(src/routeTree.gen.ts)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "bash .claude/hooks/format.sh" }
+        ]
+      }
+    ]
+  }
+}

package/templates/fe/base/.codex/agents/reviewer.toml

@@ -0,0 +1,7 @@
+name = "reviewer"
+description = "Reviews the diff against AGENTS.md conventions and docs/ai-rules."
+instructions = """
+Read AGENTS.md, then `git diff` and `git diff --staged`. Run `bun run verify`.
+Report only violations as `path:line — problem — fix`, following the checklist in .claude/agents/reviewer.md.
+End with APPROVE or REQUEST CHANGES.
+"""

package/templates/fe/base/.codex/config.toml

@@ -0,0 +1,10 @@
+# Codex CLI project config. AGENTS.md is picked up natively; hooks in hooks.json mirror .claude/settings.json.
+model = "gpt-5-codex"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+
+[projects."."]
+trust_level = "trusted"
+
+[agents]
+reviewer = "agents/reviewer.toml"

package/templates/fe/base/.codex/hooks.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "apply_patch|write_file|edit_file",
+        "hooks": [
+          { "type": "command", "command": "bash .claude/hooks/format.sh" }
+        ]
+      }
+    ]
+  }
+}

package/templates/fe/base/.env.example

@@ -0,0 +1,2 @@
+# Dev: Vite proxies /api → http://localhost:4000 (see vite.config.ts)
+VITE_API_BASE_URL=/api

package/templates/fe/base/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run rules:check
+      - run: bun run verify
+      - run: bun run build
+
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bunx playwright install --with-deps chromium
+      - run: bun run e2e
+        env:
+          CI: 'true'
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report

package/templates/fe/base/.prettierignore

@@ -0,0 +1,14 @@
+node_modules
+dist
+coverage
+bun.lock
+docs/ai-rules
+AGENTS.md
+src/routeTree.gen.ts
+src/components/ui
+playwright-report
+test-results
+
+docs/agents/deviations.md
+docs/agents/fragments.json
+eslint.variants.json

package/templates/fe/base/.prettierrc

@@ -0,0 +1,20 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["@trivago/prettier-plugin-sort-imports"],
+  "importOrder": [
+    "^react",
+    "^@tanstack/(.*)$",
+    "<THIRD_PARTY_MODULES>",
+    "^@/(.*)$",
+    "^[./]"
+  ],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true
+}

package/templates/fe/base/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/fe/base/README.md

@@ -0,0 +1,37 @@
+# __NAME__
+
+React 19 + Vite 7 + TanStack Router/Query/Table + Tailwind v4 + shadcn (Base UI) frontend template. Consumes [`simone-api-template`](../simone-api-template) and is the `fe/base` pilot of the `create-simone-app` generator.
+
+## Quickstart
+
+```bash
+bun install
+cp .env.example .env
+bun run dev          # http://localhost:3000, /api proxied to the API on :4000
+bun run verify       # typecheck + lint + format + AGENTS check + tests (coverage ≥ 80% on src/features)
+bun run e2e          # Playwright (chromium), API mocked
+E2E_REAL_API=1 bun run e2e   # against simone-api-template on :4000
+```
+
+## What is inside
+
+- `/users`: server-side table (search, sort, pagination in the URL), skeleton / empty / error states, density toggle (Jotai), theme toggle (Zustand).
+- `src/lib/apiClient.ts`: single axios instance, `{ error, details }` → `ApiError`.
+- `src/features/users/`: zod schema → `getUserList` → `usersQueryOptions` → `UsersTable` / `UserSearch` / `UsersPage`, tests with MSW.
+- ESLint enforces the dogmas: forbidden libraries, `axios`/`zustand`/`jotai`/`@base-ui` only behind their seams, jsx-a11y `error` set, `data-testid` required on interactive elements (AST rule).
+
+## AI harness
+
+- `AGENTS.md` (generated from `docs/agents/*.md` via `bun run agents:build`) is the single source of conventions; `CLAUDE.md` just includes it. Fragments: `base`, `state-zustand`, `state-jotai`, `ui-base-ui`, `deviations`.
+- Company **ai-rules** mirrored read-only in `docs/ai-rules/` with `MANIFEST.json`; `bun run rules:check` fails on drift, `bun run rules:sync` refreshes from `$AI_RULES_PATH` (default `~/Progetti/ai-rules`).
+- Skills in `.agents/skills/` (Claude Code via the `.claude/skills` symlink, Codex): `ai-rules`, `plan-feature`, `tdd-step`, `review-diff`.
+- `.claude/settings.json`: permissions + PostToolUse hook `format.sh` (prettier + eslint --fix); `.codex/` mirrors hook and reviewer agent.
+- `TASK.md.template`: per-feature plan, one commit per increment.
+
+## Deviations from ai-rules
+
+See the `## Deviations from ai-rules` section of `AGENTS.md` (Base UI instead of Radix; Jotai alongside Zustand; `cn` package).
+
+## Scripts
+
+`dev` · `build` · `preview` · `test` · `test:watch` · `e2e` · `lint` · `lint:fix` · `format` · `format:check` · `typecheck` · `verify` · `rules:sync` · `rules:check` · `agents:build` · `agents:check`

package/templates/fe/base/TASK.md.template

@@ -0,0 +1,31 @@
+# Task: <title>
+
+## Goal
+
+<one sentence: what changes for the user>
+
+## Context
+
+- Files: <src/features/…, src/routes/…, src/test/msw/handlers.ts>
+- Related rules: <docs/ai-rules/… §…>
+
+## Increments
+
+| # | What | Files | Verify | Commit |
+|---|---|---|---|---|
+| 1 | | | `bunx vitest run src/features/…` | `feat(scope): …` |
+| 2 | | | | |
+
+## Definition of done
+
+- [ ] `bun run verify` green on every commit (coverage ≥80% on `src/features`)
+- [ ] `bun run e2e` green if a route changed
+- [ ] Every interactive/stateful element has a `data-testid`
+- [ ] Table/pagination/dialog a11y patterns from `docs/ai-rules/a11y.md`
+- [ ] `git log --oneline` shows one commit per increment
+
+## Deviations from ai-rules
+
+| Rule § | Deviation | Why |
+|---|---|---|
+| | | |

package/templates/fe/base/_gitignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+coverage
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+playwright-report
+test-results
+TASK.md

package/templates/fe/base/docs/agents/base.md

@@ -0,0 +1,69 @@
+# __NAME__
+
+React 19 + Vite 7 + TanStack (Router/Query/Table) + Tailwind v4 + shadcn frontend template.
+Consumes `simone-api-template` (`{ data, page, limit, total }`) and is the `fe/base` pilot of
+the `create-simone-app` generator. Standalone: no OIDC, no mkcert, no MFE, no error routes (not included on purpose).
+
+## Commands
+
+| Command                              | What                                                                                                           |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `bun run dev`                        | Vite on :3000 (strict), `/api` proxied to :4000                                                                |
+| `bun run verify`                     | typecheck + lint + format + AGENTS check + tests (coverage ≥80% on `src/features`) — green before every commit |
+| `bun run e2e`                        | Playwright chromium; API mocked unless `E2E_REAL_API=1`                                                        |
+| `bunx shadcn@latest add <name>`      | the only way to add a UI component                                                                             |
+| `bun run rules:sync` / `rules:check` | mirror ai-rules into `docs/ai-rules/` + `MANIFEST.json` / fail on drift                                        |
+| `bun run agents:build`               | regenerate this file from `docs/agents/*.md` (never edit AGENTS.md by hand)                                    |
+
+## Structure
+
+| Path                 | Role                                                                                                                     |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `src/routes/`        | file-based routes (`__root.tsx` skip link + nav + `<main id="main">`); `routeTree.gen.ts` is generated **and committed** |
+| `src/features/<f>/`  | `*.schema.ts` (zod), `*.api.ts` (apiClient), `use*.ts` (queryOptions), components, `__tests__/`                          |
+| `src/components/ui/` | shadcn output (never edit); `src/components/shared/` composed pieces (PageHeader, EmptyState, ErrorState)                |
+| `src/lib/`           | `apiClient.ts` (single axios), `env.ts` (zod on `import.meta.env`), `queryClient.ts`, `router.ts`, `utils.ts` (`cn`)     |
+| `src/stores/`        | Zustand store + Jotai atoms, exported only through `index.ts`                                                            |
+| `src/test/`          | `setup.ts`, `render.tsx` (`renderApp`, `renderWithQuery`), `msw/` handlers shared with e2e                               |
+| `e2e/`               | Playwright specs                                                                                                         |
+| `docs/ai-rules/`     | read-only mirror of company ai-rules (+ `MANIFEST.json`)                                                                 |
+| `docs/agents/`       | fragments concatenated into `AGENTS.md`                                                                                  |
+
+## Workflow
+
+1. Copy `TASK.md.template` → `TASK.md`, split into small increments.
+2. Per increment: failing test (MSW) → minimal code → `bun run verify` green → one Conventional Commit (English subject, Italian body explaining _why_).
+3. Never edit by hand: `docs/ai-rules/*`, `AGENTS.md`, `src/components/ui/*`, `src/routeTree.gen.ts`.
+
+## Non-negotiables
+
+Stack (core-rules §1): Vite 7, React 19, TanStack Router/Query/Table, Zustand, Tailwind v4, shadcn (neutral), RHF + Zod for forms, Axios via `apiClient`, Lucide, `@/` alias, port 3000, Bun, Vitest, ESLint 9 flat, Prettier + sort-imports.
+
+MUST
+
+- HTTP only through `@/lib/apiClient`; payloads validated with zod schemas in the feature.
+- `data-testid="feature-element-qualifier"` on every interactive/stateful element; repeated rows `feature-row-{id}`.
+- shadcn components only via `bunx shadcn@latest add`; primitives (`@base-ui/*`) only inside `components/ui`.
+- One CSS file: `src/index.css`. Semantic tokens (`bg-background`, `text-muted-foreground`), `cn()` for merging.
+- Cross-route state (page, sort, filters) in search params with `validateSearch`; server state in TanStack Query via `queryOptions` factories; client state only from `@/stores`.
+- Tables: `<caption>`, `th scope="col"` + `aria-sort`, sort control is a `<button>` with `aria-label`, pagination in `<nav aria-label>` with `aria-current`.
+- Every route sets `head.title`; skip link first focusable; icon-only buttons have `aria-label`.
+- TS strict + `noUncheckedIndexedAccess`; `interface` for props (`XxxProps`), `type` for unions, `as const` objects.
+
+MUST NOT
+
+- react-router, MUI/antd/chakra, styled-components/emotion, swr/redux, direct `axios`, `zustand`/`jotai` outside `src/stores` (all ESLint errors).
+- `any`, `@ts-ignore`, `enum`, non-null `!`, `React.FC`, `forwardRef`, `if (import.meta.env.MODE …)` branching.
+- `<div onClick>`/`<span onClick>`; `outline-none` without a `focus-visible:ring`; index as `key`; `dangerouslySetInnerHTML`.
+- Server data duplicated in a store; extra `.css` files; hand edits to generated files.
+
+## ai-rules
+
+| Topic                                                                            | File                                          |
+| -------------------------------------------------------------------------------- | --------------------------------------------- |
+| stack, React 19, TS, structure, Zustand, apiClient, vite.config, Prettier/ESLint | `docs/ai-rules/core-rules.md`                 |
+| Router (file-based, search params), Query (queryOptions), Table (server-side)    | `docs/ai-rules/tanstack-ecosystem.md`         |
+| shadcn setup, Tailwind, single `index.css`, a11y checklist                       | `docs/ai-rules/ui-shadcn.md`                  |
+| jsx-a11y config, skip link, focus on route change, tables, pagination            | `docs/ai-rules/a11y.md`                       |
+| `data-testid` naming, dynamic ids, Playwright usage                              | `docs/ai-rules/testing-selectors.md`          |
+| WCAG 2.2 AA baseline, Legge Stanca, `lang="it"`, Italian formats                 | `docs/ai-rules/accessibility-legge-stanca.md` |

package/templates/fe/base/e2e/users.spec.ts

@@ -0,0 +1,82 @@
+import { type Page, expect, test } from '@playwright/test'
+
+import { listUsers } from '../src/test/fixtures/users'
+
+// Default: the API is mocked with the same fixture/semantics as the unit tests.
+// E2E_REAL_API=1 → hit simone-api-template on :4000 through the Vite proxy.
+const REAL_API = process.env.E2E_REAL_API === '1'
+
+const mockApi = async (page: Page) => {
+  if (REAL_API) return
+  await page.route('**/api/users*', (route) =>
+    route.fulfill({ json: listUsers(new URL(route.request().url())) }),
+  )
+}
+
+test.describe('/users', () => {
+  test.beforeEach(async ({ page }) => {
+    await mockApi(page)
+    await page.goto('/users')
+  })
+
+  test('renders the first page of users', async ({ page }) => {
+    await expect(page).toHaveTitle(/Utenti/)
+    await expect(page.getByTestId('users-table')).toBeVisible()
+    await expect(page.getByTestId(/^user-row-/)).toHaveCount(20)
+    await expect(page.getByTestId('users-pagination-page-1')).toHaveAttribute(
+      'aria-current',
+      'page',
+    )
+  })
+
+  test('search narrows the list to the typed user', async ({ page }) => {
+    const firstRow = page.getByTestId(/^user-row-/).first()
+    const id = (await firstRow.getAttribute('data-testid'))?.replace(
+      'user-row-',
+      '',
+    )
+    const name = await firstRow.getByRole('cell').first().innerText()
+
+    await page.getByTestId('users-search-input').fill(name)
+    await expect(page).toHaveURL(/[?&]q=/)
+    await expect(page.getByTestId(`user-row-${id}`)).toBeVisible()
+    expect(await page.getByTestId(/^user-row-/).count()).toBeLessThan(20)
+  })
+
+  test('clicking a header toggles aria-sort and the URL', async ({ page }) => {
+    const nameHeader = page.getByTestId('users-table-sort-name')
+    await expect(nameHeader.locator('xpath=ancestor::th')).toHaveAttribute(
+      'aria-sort',
+      'ascending',
+    )
+
+    await nameHeader.click()
+    await expect(page).toHaveURL(/order=desc/)
+    await expect(nameHeader.locator('xpath=ancestor::th')).toHaveAttribute(
+      'aria-sort',
+      'descending',
+    )
+
+    await page.getByTestId('users-table-sort-email').click()
+    await expect(page).toHaveURL(/sort=email/)
+    await expect(
+      page.getByTestId('users-table-sort-email').locator('xpath=ancestor::th'),
+    ).toHaveAttribute('aria-sort', 'ascending')
+  })
+
+  test('pagination moves to page 2', async ({ page }) => {
+    await page.getByTestId('users-pagination-next-button').click()
+    await expect(page).toHaveURL(/page=2/)
+    await expect(page.getByTestId('users-pagination-page-2')).toHaveAttribute(
+      'aria-current',
+      'page',
+    )
+    await expect(page.getByTestId(/^user-row-/).first()).toBeVisible()
+  })
+
+  test('skip link is the first focusable element', async ({ page }) => {
+    await expect(page.getByTestId('users-table')).toBeVisible()
+    await page.keyboard.press('Tab')
+    await expect(page.getByTestId('skip-link')).toBeFocused()
+  })
+})