From 22667b38b82b3928b626fc65149865b1256c1827 Mon Sep 17 00:00:00 2001 From: KS Jannette Date: Sat, 1 Aug 2026 06:00:04 -0400 Subject: [PATCH] add agents.md --- agents.md | 42 +++++++++++++++++++++++ frontend/package.json | 77 +++++++++++++++++++++---------------------- 2 files changed, 80 insertions(+), 39 deletions(-) create mode 100644 agents.md diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..e046f9a --- /dev/null +++ b/agents.md @@ -0,0 +1,42 @@ +# AI Agent Instructions: Fullstack Vite 7 (React) + Express + TypeScript + npm + +You are an expert AI fullstack software engineer specialized in Vite 7, React, Express, TypeScript, and modern web architectures. Follow these rules strictly when modifying this codebase. + +## 1. Project Structure & Context +* **Frontend:** React SPA powered by Vite 7.x (Entry: `src/main.tsx` or client folder). +* **Backend:** Express Node.js application (Server entry: `server.ts` or server folder). +* **Package Manager:** npm (`package-lock.json` is the strict source of truth). +* **TypeScript Setup:** Strict Mode enabled independently across both environments. + +## 2. Express Backend TypeScript Rules +* **Typed Request/Response:** Explicitly type Express route handlers using native Express types: + ```typescript + import { Request, Response, NextFunction } from 'express'; + // Example for typed request bodies/params: + interface CreateUserBody { username: string; } + app.post('/user', (req: Request<{}, {}, CreateUserBody>, res: Response) => { ... }); + ``` +* **Async Error Catching:** Always wrap async middleware/route handlers in `try/catch` and pass errors to `next(err)`. Do not let unhandled promise rejections crash the Node process. +* **Shared Types:** If frontend and backend share types (e.g., API payloads, User models), place them in a shared directory or export them cleanly from the backend to prevent duplicating code. + +## 3. Frontend React + Vite Rules +* **Component Typings:** Use standard type inference or explicit return types (`function Component(): React.JSX.Element`). Avoid the legacy `React.FC`. +* **Strict Prop Types:** Every component must have an explicitly typed `interface` or `type` for its props. No implicit `any`. +* **Event Handlers:** Use exact React synthetic event types (e.g., `React.ChangeEvent`) instead of generic native events. +* **File Extensions:** Use `.tsx` exclusively for files containing JSX. Use `.ts` strictly for pure logic, hooks, or type definitions. + +## 4. Strict Code Quality & Native Guards +* **No `any`:** Never use `any`. Use `unknown` for unpredictable runtime data (like Express `req.body` or frontend `fetch` payloads). +* **No Validation Libraries:** Do not install Zod, TypeBox, or Yup. Write explicit, manual type predicate functions (`function isUser(obj: any): obj is User`) to safely validate runtime data incoming to both the server and client. +* **No Enums:** Avoid TypeScript `enum`. Use string-literal unions (`type Status = 'active' | 'pending'`) or `const StatusEnum = { ... } as const`. + +## 5. Verification & Workflow Commands +Before declaring a task complete, you must verify both environments compile flawlessly via npm: +* **Install Dependencies:** `npm install` +* **Type-Check Project:** Run the designated workspace or folder type-checking scripts (e.g., `npm run type-check` or `npx tsc --noEmit` across both roots). +* **Build Verification:** Run production build scripts (e.g., `npm run build`) to ensure both Express asset compilation and Vite bundling pass without error. + +## 6. How to Respond +* **Verify Types First:** Run type-checking commands automatically after modifying files to capture compilation breaks before presenting the solution. +* **Targeted Diffs:** Provide concise, targeted updates. Do not rewrite whole files if only a few lines change. +* **Self-Correct:** If a build command fails, read the compiler/Vite/Node logs, fix the root cause, and re-test before asking the user for help. diff --git a/frontend/package.json b/frontend/package.json index d761342..2ac6743 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -1,40 +1,39 @@ { - "name": "congruity-frontend", - "private": true, - "version": "0.1.0", - "type": "module", - "scripts": { - "dev": "vite", - "build": "tsc -b && vite build", - "lint": "eslint .", - "preview": "vite preview", - "test": "vitest run --config vitest.config.ts", - "test:watch": "vitest --config vitest.config.ts" - }, - "dependencies": { - "@tanstack/react-query": "^5.90.21", - "react": "^19.2.0", - "react-dom": "^19.2.0", - "react-router-dom": "^7.13.0" - }, - "devDependencies": { - "@eslint/js": "^9.39.1", - "@testing-library/jest-dom": "^6.9.1", - "@testing-library/react": "^16.3.2", - "@testing-library/user-event": "^14.6.1", - "@types/node": "^24.10.1", - "@types/react": "^19.2.7", - "@types/react-dom": "^19.2.3", - "@vitejs/plugin-react": "^5.1.1", - "eslint": "^9.39.1", - "eslint-plugin-react-hooks": "^7.0.1", - "eslint-plugin-react-refresh": "^0.4.24", - "globals": "^16.5.0", - "jsdom": "^28.0.0", - "typescript": "~5.9.3", - "typescript-eslint": "^8.48.0", - "vite": "^7.3.1", - "vitest": "^4.0.18" - } - } - \ No newline at end of file + "name": "kongruity-frontend", + "private": true, + "version": "0.1.0", + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc -b && vite build", + "lint": "eslint .", + "preview": "vite preview", + "test": "vitest run --config vitest.config.ts", + "test:watch": "vitest --config vitest.config.ts" + }, + "dependencies": { + "@tanstack/react-query": "^5.90.21", + "react": "^19.2.0", + "react-dom": "^19.2.0", + "react-router-dom": "^7.13.0" + }, + "devDependencies": { + "@eslint/js": "^9.39.1", + "@testing-library/jest-dom": "^6.9.1", + "@testing-library/react": "^16.3.2", + "@testing-library/user-event": "^14.6.1", + "@types/node": "^24.10.1", + "@types/react": "^19.2.7", + "@types/react-dom": "^19.2.3", + "@vitejs/plugin-react": "^5.1.1", + "eslint": "^9.39.1", + "eslint-plugin-react-hooks": "^7.0.1", + "eslint-plugin-react-refresh": "^0.4.24", + "globals": "^16.5.0", + "jsdom": "^28.0.0", + "typescript": "~5.9.3", + "typescript-eslint": "^8.48.0", + "vite": "^7.3.1", + "vitest": "^4.0.18" + } +} \ No newline at end of file