From d341cf149a3c62630c95ef2b225e42b4a7100d28 Mon Sep 17 00:00:00 2001 From: Tyler Dane Date: Sun, 1 Mar 2026 19:59:43 -0800 Subject: [PATCH 1/2] chore(dependencies): clean up package.json and yarn.lock by removing unused dependencies - Removed several unused dependencies from package.json across multiple packages, including `posthog-js`, `process`, `uuid`, and others, to streamline the project. - Updated yarn.lock to reflect these removals, ensuring consistency in the dependency tree and improving overall project maintainability. --- package.json | 11 +--- packages/backend/package.json | 3 - packages/core/package.json | 1 - packages/web/package.json | 7 --- yarn.lock | 111 ---------------------------------- 5 files changed, 1 insertion(+), 132 deletions(-) diff --git a/package.json b/package.json index 6eda4d35b..a9a1fa16d 100644 --- a/package.json +++ b/package.json @@ -39,11 +39,7 @@ "@compass/backend": "*", "@compass/core": "*", "module-alias": "^2.2.2", - "posthog-js": "^1.259.0", - "process": "^0.11.10", - "source-map-support": "^0.5.20", - "tslib": "^2.4.0", - "uuid": "^9.0.0" + "tslib": "^2.4.0" }, "devDependencies": { "@babel/core": "^7.15.5", @@ -56,15 +52,12 @@ "@playwright/test": "^1.56.0", "@trivago/prettier-plugin-sort-imports": "^5.2.2", "@types/node-fetch": "^2.6.13", - "@types/uuid": "^9.0.0", "@typescript-eslint/eslint-plugin": "^8.0.0", "@typescript-eslint/parser": "^8.0.0", "babel-loader": "^9.1.0", "baseline-browser-mapping": "^2.9.11", - "buffer": "^6.0.3", "concurrently": "^8.0.1", "cross-env": "^7.0.3", - "crypto-browserify": "^3.12.0", "eslint": "^9.20.1", "eslint-config-prettier": "^8.3.0", "eslint-import-resolver-lerna": "^2.0.0", @@ -75,9 +68,7 @@ "husky": "^8.0.1", "jest": "^29.0.3", "lint-staged": "^15.2.10", - "path-browserify": "^1.0.1", "prettier": "^3.5.1", - "stream-browserify": "^3.0.0", "ts-node": "^10.9.1", "ts-node-dev": "^2.0.0", "typescript": "^5.1.6", diff --git a/packages/backend/package.json b/packages/backend/package.json index 91256c084..09b2a832a 100644 --- a/packages/backend/package.json +++ b/packages/backend/package.json @@ -28,16 +28,13 @@ "@ngrok/ngrok": "^1.5.1", "@shelf/jest-mongodb": "^4.1.4", "@types/cors": "^2.8.12", - "@types/debug": "^4.1.7", "@types/express": "^4.17.13", - "@types/gapi": "0.0.41", "@types/jest": "^29.0.0", "@types/lodash.mergewith": "^4.6.9", "@types/module-alias": "^2.0.1", "@types/morgan": "^1.9.4", "@types/node": "^22.13.10", "@types/supertest": "^6.0.3", - "alias-hq": "^6.1.0", "jest-environment-node": "^29.7.0", "socket.io-client": "^4.7.5", "supertest": "^7.1.0", diff --git a/packages/core/package.json b/packages/core/package.json index 462399d72..46a37df2f 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -7,7 +7,6 @@ "main": "", "devDependencies": { "@faker-js/faker": "^9.6.0", - "@types/eventemitter2": "^4.1.2", "@types/lodash.uniqby": "^4.7.9", "@types/tinycolor2": "^1.4.6", "typescript": "^5.1.6" diff --git a/packages/web/package.json b/packages/web/package.json index d124ed629..05bfc414a 100644 --- a/packages/web/package.json +++ b/packages/web/package.json @@ -7,7 +7,6 @@ "typings": "declaration.d.ts", "dependencies": { "@compass/core": "1.0.0", - "@dnd-kit/accessibility": "^3.1.1", "@dnd-kit/core": "^6.3.1", "@dnd-kit/modifiers": "^9.0.0", "@dnd-kit/utilities": "^3.2.2", @@ -25,7 +24,6 @@ "css-loader": "^6.3.0", "dayjs": "^1.10.7", "dexie": "^4.2.1", - "dexie-react-hooks": "^4.2.0", "fast-deep-equal": "^3.1.3", "html-webpack-plugin": "^5.6.4", "mini-css-extract-plugin": "^2.3.0", @@ -50,7 +48,6 @@ "style-loader": "^3.2.1", "styled-components": "^5.3.1", "supertokens-web-js": "^0.16.0", - "ts-keycode-enum": "^1.0.6", "uuid": "^9.0.0" }, "devDependencies": { @@ -62,16 +59,12 @@ "@tailwindcss/postcss": "^4.1.14", "@testing-library/jest-dom": "^5.16.5", "@testing-library/react": "^14.0.0", - "@testing-library/react-hooks": "^8.0.1", "@testing-library/user-event": "^14.4.3", "@types/jest": "^29.0.0", "@types/react": "^18.0.8", "@types/react-datepicker": "^4.1.7", "@types/react-dom": "^18.0.3", - "@types/react-redux": "^7.1.18", - "@types/react-select": "^5.0.1", "@types/styled-components": "^5.1.14", - "autoprefixer": "^10.4.21", "babel-jest": "^29.3.1", "babel-plugin-styled-components": "^2.0.2", "eslint-plugin-jest-dom": "^4.0.3", diff --git a/yarn.lock b/yarn.lock index 5b3cc7002..df97597d7 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2641,14 +2641,6 @@ lodash "^4.17.15" redent "^3.0.0" -"@testing-library/react-hooks@^8.0.1": - version "8.0.1" - resolved "https://registry.npmjs.org/@testing-library/react-hooks/-/react-hooks-8.0.1.tgz" - integrity sha512-Aqhl2IVmLt8IovEVarNDFuJDVWVvhnr9/GCU6UUnrYXwgDFF9h2L2o2P9KBni1AST5sT6riAyoukFLyjQUgD/g== - dependencies: - "@babel/runtime" "^7.12.5" - react-error-boundary "^3.1.0" - "@testing-library/react@^14.0.0": version "14.3.1" resolved "https://registry.npmjs.org/@testing-library/react/-/react-14.3.1.tgz" @@ -2830,13 +2822,6 @@ resolved "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz" integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w== -"@types/eventemitter2@^4.1.2": - version "4.1.2" - resolved "https://registry.npmjs.org/@types/eventemitter2/-/eventemitter2-4.1.2.tgz" - integrity sha512-yU7QvSKpbe62hidZQ/424Lnn40dnA5FUJqd6xS+U4BheJUHo/OzNpoixXKDbWKGbnvURqqkWIIIvTZvo8N0gzQ== - dependencies: - eventemitter2 "*" - "@types/express-serve-static-core@*", "@types/express-serve-static-core@^5.0.0": version "5.1.0" resolved "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.0.tgz" @@ -2876,11 +2861,6 @@ "@types/qs" "*" "@types/serve-static" "*" -"@types/gapi@0.0.41": - version "0.0.41" - resolved "https://registry.npmjs.org/@types/gapi/-/gapi-0.0.41.tgz" - integrity sha512-tmHO66z/f91JZCDqinj/nNvQEszsz/hBT4+MvCSKT5sDzl5Ld/oXZ8WaecCBjRLw2uWKUInUHM9MhEXWkOiNjw== - "@types/graceful-fs@^4.1.3": version "4.1.9" resolved "https://registry.npmjs.org/@types/graceful-fs/-/graceful-fs-4.1.9.tgz" @@ -3105,23 +3085,6 @@ resolved "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz" integrity sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ== -"@types/react-redux@^7.1.18": - version "7.1.34" - resolved "https://registry.npmjs.org/@types/react-redux/-/react-redux-7.1.34.tgz" - integrity sha512-GdFaVjEbYv4Fthm2ZLvj1VSCedV7TqE5y1kNwnjSdBOTXuRSgowux6J8TAct15T3CKBr63UMk+2CO7ilRhyrAQ== - dependencies: - "@types/hoist-non-react-statics" "^3.3.0" - "@types/react" "*" - hoist-non-react-statics "^3.3.0" - redux "^4.0.0" - -"@types/react-select@^5.0.1": - version "5.0.1" - resolved "https://registry.npmjs.org/@types/react-select/-/react-select-5.0.1.tgz" - integrity sha512-h5Im0AP0dr4AVeHtrcvQrLV+gmPa7SA0AGdxl2jOhtwiE6KgXBFSogWw8az32/nusE6AQHlCOHQWjP1S/+oMWA== - dependencies: - react-select "*" - "@types/react-transition-group@^4.4.0": version "4.4.12" resolved "https://registry.npmjs.org/@types/react-transition-group/-/react-transition-group-4.4.12.tgz" @@ -3274,11 +3237,6 @@ resolved "https://registry.npmjs.org/@types/use-sync-external-store/-/use-sync-external-store-0.0.3.tgz" integrity sha512-EwmlvuaxPNej9+T4v5AuBPJa2x2UOJVdjCtDHgcDqitUeOtjnJKJ+apYjVcAoBEMjKW1VVFGZLUb5+qqa09XFA== -"@types/uuid@^9.0.0": - version "9.0.8" - resolved "https://registry.npmjs.org/@types/uuid/-/uuid-9.0.8.tgz" - integrity sha512-jg+97EGIcY9AGHJJRaaPVgetKDsrTgbRjQ5Msgjh/DQKEFl0DtyRr/VCOyD1T2R1MNeWPK/u7JoGhlDZnKBAfA== - "@types/webidl-conversions@*": version "7.0.3" resolved "https://registry.npmjs.org/@types/webidl-conversions/-/webidl-conversions-7.0.3.tgz" @@ -3736,22 +3694,6 @@ ajv@~8.13.0: require-from-string "^2.0.2" uri-js "^4.4.1" -alias-hq@^6.1.0: - version "6.2.4" - resolved "https://registry.npmjs.org/alias-hq/-/alias-hq-6.2.4.tgz" - integrity sha512-6KGuO4XB3PbvTfP+WJEJR2dGMy6h0UyLa2/kZOeeD/UIrYoaUAQwKdLovYyCpgZErYD1d3zIuZh6GPMDADvF4g== - dependencies: - colors "^1.4.0" - get-tsconfig "^4.8.0" - glob "^7.2.3" - inquirer "^10.1.6" - jscodeshift "^0.16.1" - json5 "^2.2.3" - module-alias "^2.2.3" - node-fetch "^2.7.0" - open "^7.4.2" - vue-jscodeshift-adapter "^2.2.1" - ansi-escapes@^4.2.1, ansi-escapes@^4.3.2: version "4.3.2" resolved "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-4.3.2.tgz" @@ -3971,18 +3913,6 @@ asynckit@^0.4.0: resolved "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz" integrity sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q== -autoprefixer@^10.4.21: - version "10.4.21" - resolved "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.4.21.tgz" - integrity sha512-O+A6LWV5LDHSJD3LjHYoNi4VLsj/Whi7k6zG12xTYaU4cQ8oxQGckXNX8cRHK5yOZ/ppVHe0ZBXGzSV9jXdVbQ== - dependencies: - browserslist "^4.24.4" - caniuse-lite "^1.0.30001702" - fraction.js "^4.3.7" - normalize-range "^0.1.2" - picocolors "^1.1.1" - postcss-value-parser "^4.2.0" - available-typed-arrays@^1.0.7: version "1.0.7" resolved "https://registry.npmjs.org/available-typed-arrays/-/available-typed-arrays-1.0.7.tgz" @@ -4957,24 +4887,6 @@ cross-spawn@^7.0.1, cross-spawn@^7.0.3, cross-spawn@^7.0.6: shebang-command "^2.0.0" which "^2.0.1" -crypto-browserify@^3.12.0: - version "3.12.1" - resolved "https://registry.npmjs.org/crypto-browserify/-/crypto-browserify-3.12.1.tgz" - integrity sha512-r4ESw/IlusD17lgQi1O20Fa3qNnsckR126TdUuBgAu7GBYSIPvdNyONd3Zrxh0xCwA4+6w/TDArBPsMvhur+KQ== - dependencies: - browserify-cipher "^1.0.1" - browserify-sign "^4.2.3" - create-ecdh "^4.0.4" - create-hash "^1.2.0" - create-hmac "^1.1.7" - diffie-hellman "^5.0.3" - hash-base "~3.0.4" - inherits "^2.0.4" - pbkdf2 "^3.1.2" - public-encrypt "^4.0.3" - randombytes "^2.1.0" - randomfill "^1.0.4" - crypto-js@^4.1.1: version "4.2.0" resolved "https://registry.npmjs.org/crypto-js/-/crypto-js-4.2.0.tgz" @@ -5319,11 +5231,6 @@ detect-node@^2.0.4: resolved "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz" integrity sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g== -dexie-react-hooks@^4.2.0: - version "4.2.0" - resolved "https://registry.npmjs.org/dexie-react-hooks/-/dexie-react-hooks-4.2.0.tgz" - integrity sha512-u7KqTX9JpBQK8+tEyA9X0yMGXlSCsbm5AU64N6gjvGk/IutYDpLBInMYEAEC83s3qhIvryFS+W+sqLZUBEvePQ== - dexie@^4.2.1: version "4.2.1" resolved "https://registry.npmjs.org/dexie/-/dexie-4.2.1.tgz" @@ -9487,11 +9394,6 @@ pascal-case@^3.1.2: no-case "^3.0.4" tslib "^2.0.3" -path-browserify@^1.0.1: - version "1.0.1" - resolved "https://registry.npmjs.org/path-browserify/-/path-browserify-1.0.1.tgz" - integrity sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g== - path-exists@^3.0.0: version "3.0.0" resolved "https://registry.npmjs.org/path-exists/-/path-exists-3.0.0.tgz" @@ -10978,14 +10880,6 @@ stop-iteration-iterator@^1.0.0, stop-iteration-iterator@^1.1.0: es-errors "^1.3.0" internal-slot "^1.1.0" -stream-browserify@^3.0.0: - version "3.0.0" - resolved "https://registry.npmjs.org/stream-browserify/-/stream-browserify-3.0.0.tgz" - integrity sha512-H73RAHsVBapbim0tU2JwwOiXUj+fikfiaoYAKHF3VJfA0pe2BCzkhAHBlLG6REzE+2WNZcxOXjK7lkso+9euLA== - dependencies: - inherits "~2.0.4" - readable-stream "^3.5.0" - streamx@^2.15.0: version "2.23.0" resolved "https://registry.npmjs.org/streamx/-/streamx-2.23.0.tgz" @@ -11569,11 +11463,6 @@ ts-key-enum@^2.0.12: resolved "https://registry.npmjs.org/ts-key-enum/-/ts-key-enum-2.0.13.tgz" integrity sha512-zixs6j8+NhzazLUQ1SiFrlo1EFWG/DbqLuUGcWWZ5zhwjRT7kbi1hBlofxdqel+h28zrby2It5TrOyKp04kvqw== -ts-keycode-enum@^1.0.6: - version "1.0.6" - resolved "https://registry.npmjs.org/ts-keycode-enum/-/ts-keycode-enum-1.0.6.tgz" - integrity sha512-DF8+Cf/FJJnPRxwz8agCoDelQXKZWQOS/gnnwx01nZ106tPJdB3BgJ9QTtLwXgR82D8O+nTjuZzWgf0Rg4vuRA== - ts-node-dev@^2.0.0: version "2.0.0" resolved "https://registry.npmjs.org/ts-node-dev/-/ts-node-dev-2.0.0.tgz" From fbbdd2551a668e75f1c9095500bb0b6ab7d2b5f0 Mon Sep 17 00:00:00 2001 From: Tyler Dane Date: Sun, 1 Mar 2026 20:03:12 -0800 Subject: [PATCH 2/2] chore: remove AI-AGENT-GUIDE --- AI-AGENT-GUIDE.md | 434 ---------------------------------------------- 1 file changed, 434 deletions(-) delete mode 100644 AI-AGENT-GUIDE.md diff --git a/AI-AGENT-GUIDE.md b/AI-AGENT-GUIDE.md deleted file mode 100644 index 3bd91d7e0..000000000 --- a/AI-AGENT-GUIDE.md +++ /dev/null @@ -1,434 +0,0 @@ -# AI Agent Guide for Compass Calendar - -**A comprehensive guide for AI coding agents working on the Compass Calendar project** - -## ๐Ÿš€ Quick Start (60 seconds) - -```bash -# 1. Install dependencies (~3.5 minutes) -yarn install --frozen-lockfile --network-timeout 300000 - -# 2. Setup environment -cp packages/backend/.env.local.example packages/backend/.env - -# 3. Start development (frontend only) -yarn dev:web -# Open http://localhost:9080 - -# 4. Run tests -yarn test:core && yarn test:web - -# 5. Generate documentation -yarn docs:generate -``` - -## ๐Ÿ“š Essential Documentation - -### Primary Guides - -- **[README.md](./README.md)** - Project overview and "For AI Agents" section -- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines with AI agent-specific sections -- **[AGENTS.md](./AGENTS.md)** - Detailed development instructions and conventions -- **[ai-tools/README.md](./ai-tools/README.md)** - AI tooling documentation - -### Architecture Reference - -- **Monorepo Structure**: 4 packages (web, backend, core, scripts) -- **Type System**: TypeScript + Zod schemas for validation -- **State Management**: Redux (frontend) -- **API**: Express REST API with Supertokens authentication -- **Database**: MongoDB - -## ๐Ÿ› ๏ธ AI Tools Available - -### 1. API Documentation Generator - -```bash -yarn docs:generate -``` - -**Output**: `ai-tools/api-documentation.md` -**Purpose**: Auto-extracts all backend API endpoints with authentication requirements - -### 2. Type Reference Extractor - -```bash -yarn ts-node ai-tools/extract-types.ts -``` - -**Output**: `ai-tools/type-reference.md` -**Purpose**: Documents all TypeScript types, interfaces, and Zod schemas - -### 3. Code Health Auditor - -```bash -yarn audit:code-health -``` - -**Output**: Console report -**Purpose**: Analyzes codebase for issues, complexity metrics, and improvement areas - -### 4. Full AI Index - -```bash -yarn ai:index -``` - -**Purpose**: Runs documentation generators (API docs + type reference) - -### 5. Type Checker - -```bash -yarn type-check -``` - -**Purpose**: Full TypeScript type validation across all packages - -## ๐Ÿ“– Key Concepts - -### Module Aliases (ALWAYS USE THESE) - -```typescript -// โœ… Correct - Use aliases -import { foo } from '@compass/core' -import { bar } from '@web/common/utils' -import { baz } from '@core/types' - -// โŒ Wrong - No relative paths -import { foo } from '../../../core/src' -``` - -**Available Aliases**: - -- `@compass/backend` โ†’ `packages/backend/src` -- `@compass/core` โ†’ `packages/core/src` -- `@compass/scripts` โ†’ `packages/scripts/src` -- `@web/*` โ†’ `packages/web/src/*` -- `@core/*` โ†’ `packages/core/src/*` - -### Validation Pattern (ALWAYS USE ZOD) - -```typescript -import { z } from "zod"; - -// 1. Define schema -export const UserSchema = z.object({ - id: z.string(), - email: z.string().email(), -}); - -// 2. Export inferred type -export type User = z.infer; - -// 3. Use for validation -const user = UserSchema.parse(data); -``` - -### Testing Pattern (USE TESTING LIBRARY) - -```typescript -// โœ… Correct - Semantic queries and user interactions -const button = screen.getByRole('button', { name: /save/i }); -await user.click(button); - -// โŒ Wrong - Implementation details -const button = container.querySelector('.save-btn'); -``` - -## ๐Ÿ—๏ธ Architecture Overview - -### Backend (`@compass/backend`) - -``` -packages/backend/src/ -โ”œโ”€โ”€ auth/ # Google OAuth integration -โ”œโ”€โ”€ calendar/ # Calendar list and selection -โ”œโ”€โ”€ event/ # Event CRUD operations -โ”œโ”€โ”€ sync/ # Google Calendar sync logic -โ”œโ”€โ”€ user/ # User profile and metadata -โ”œโ”€โ”€ priority/ # Task priority management -โ”œโ”€โ”€ waitlist/ # Waitlist management -โ””โ”€โ”€ common/ # Shared utilities, middleware -``` - -**Key Files**: - -- `*routes.config.ts` - Route definitions -- `controllers/*.controller.ts` - Request handlers -- `services/*.service.ts` - Business logic -- `dao/*.dao.ts` - Database operations - -### Frontend (`@compass/web`) - -``` -packages/web/src/ -โ”œโ”€โ”€ views/ # React components by feature -โ”‚ โ”œโ”€โ”€ Calendar/ # Calendar view (day/week) -โ”‚ โ”œโ”€โ”€ Forms/ # Event forms -โ”‚ โ”œโ”€โ”€ Now/ # Focus mode -โ”‚ โ””โ”€โ”€ Root.tsx # Router configuration -โ”œโ”€โ”€ store/ # Redux state management -โ”‚ โ”œโ”€โ”€ calendar/ # Calendar state -โ”‚ โ”œโ”€โ”€ draft/ # Draft event state -โ”‚ โ”œโ”€โ”€ schema/ # Schema state -โ”‚ โ”œโ”€โ”€ settings/ # User settings -โ”‚ โ”œโ”€โ”€ sidebar/ # Sidebar state -โ”‚ โ”œโ”€โ”€ task/ # Task state -โ”‚ โ””โ”€โ”€ view/ # View state -โ”œโ”€โ”€ common/ # Shared utilities -โ””โ”€โ”€ hooks/ # Custom React hooks -``` - -**Key Patterns**: - -- Use Tailwind semantic colors: `bg-bg-primary` not `bg-blue-300` -- No barrel files (`index.ts`) - use named exports -- Redux for global state, local state for component-specific - -### Core (`@compass/core`) - -``` -packages/core/src/ -โ”œโ”€โ”€ types/ # TypeScript type definitions -โ”œโ”€โ”€ constants/ # Shared constants -โ”œโ”€โ”€ util/ # Utility functions -โ”‚ โ”œโ”€โ”€ date/ # Date/time utilities (dayjs) -โ”‚ โ””โ”€โ”€ event/ # Event utilities -โ”œโ”€โ”€ mappers/ # Data transformation -โ””โ”€โ”€ validators/ # Validation schemas -``` - -**Key Files**: - -- `types/**/*.types.ts` - Type definitions with Zod schemas -- `util/date/` - Date handling with dayjs and custom plugins -- `mappers/` - Transform between Compass and Google Calendar formats - -### Scripts (`@compass/scripts`) - -``` -packages/scripts/src/ -โ”œโ”€โ”€ commands/ # CLI commands (build, seed, delete) -โ”œโ”€โ”€ common/ # Shared CLI utilities -โ””โ”€โ”€ cli.ts # Command-line interface entry point -``` - -## ๐Ÿ” Authentication & Authorization - -### Supertokens Session Management - -- **Session validation**: `verifySession()` middleware -- **Google OAuth**: `requireGoogleConnectionSession` middleware -- **Dev-only**: `authMiddleware.verifyIsDev` middleware - -### API Endpoint Patterns - -```typescript -// Public endpoint (no auth) -this.app.route("/api/waitlist").post(controller.method); - -// Authenticated endpoint -this.app.route("/api/user/profile").all(verifySession()).get(controller.method); - -// Requires Google Calendar connection -this.app - .route("/api/event") - .all(verifySession()) - .post(requireGoogleConnectionSession, controller.create); -``` - -## ๐Ÿงช Testing Strategy - -### Test Commands - -```bash -yarn test:core # Core package tests (~2 seconds, 134 tests) -yarn test:web # Web package tests (~15 seconds) -yarn test:backend # Backend tests (~15 seconds) -yarn test:scripts # Scripts tests -yarn test # Full suite (avoid in restricted networks) -yarn test:e2e # Playwright E2E tests -``` - -### Writing Tests - -1. **Frontend**: Use Testing Library, semantic queries, user-event -2. **Backend**: Use Jest, mock external services -3. **Core**: Pure function tests, edge cases -4. **E2E**: Playwright for critical user flows - -## ๐Ÿ“ Git Workflow - -### Branch Naming - -```bash -feature/add-calendar-sync -bug/fix-auth-timeout -docs/update-api-docs -refactor/simplify-event-logic -``` - -### Commit Messages (Conventional Commits) - -```bash -feat(web): add calendar event creation modal -fix(backend): resolve authentication timeout -docs(readme): update AI agent instructions -refactor(core): simplify date utility functions -test(web): add tests for login flow -``` - -## ๐ŸŽฏ Common Tasks - -### Adding a New API Endpoint - -1. Define types in `packages/core/src/types/` -2. Create Zod schema for validation -3. Add route in `packages/backend/src/*/routes.config.ts` -4. Implement controller in `controllers/*.controller.ts` -5. Add service logic in `services/*.service.ts` -6. Add DAO if database access needed -7. Add JSDoc comments with `@auth`, `@body`, `@returns`, `@throws` -8. Write tests -9. Run `yarn docs:generate` to update API docs - -### Adding a New React Component - -1. Create component in `packages/web/src/views/[feature]/` -2. Use semantic Tailwind colors from `@theme` directive -3. Add TypeScript types (no `any`) -4. Write tests using Testing Library -5. Use Redux for global state, props for local -6. Follow naming conventions (`is` prefix for booleans) - -### Modifying Date Logic - -1. Use dayjs from `@core/util/date/dayjs` -2. Prefer custom plugin methods over manual manipulation -3. Always handle timezones explicitly -4. Add JSDoc with examples -5. Write comprehensive tests for edge cases - -## โšก Performance Tips - -- Use `yarn ai:index` to build documentation once, reference it -- Run targeted tests (`yarn test:core`) instead of full suite -- Use `yarn type-check` before committing -- Frontend works standalone - no backend needed for UI work - -## ๐Ÿ”ง Troubleshooting - -### Common Issues - -**Tests failing?** - -```bash -# Run packages individually -yarn test:core -yarn test:web -yarn test:backend -``` - -**Backend won't start?** - -- Missing env variables in `packages/backend/.env` -- Use web-only mode: `yarn dev:web` - -**Type errors?** - -```bash -yarn type-check -``` - -**Code style issues?** - -```bash -yarn prettier . --write -``` - -### Network Limitations - -- MongoDB binary downloads may fail in restricted networks -- Use individual test commands instead of full suite -- Frontend tests work without backend - -## ๐Ÿ“Š Code Quality Standards - -### Pre-Commit Checklist - -1. โœ… Code follows module alias conventions -2. โœ… All new code has tests -3. โœ… Types are defined with Zod schemas -4. โœ… JSDoc comments added for public APIs -5. โœ… `yarn prettier . --write` passes -6. โœ… `yarn type-check` passes -7. โœ… Relevant tests pass - -### Code Review Standards - -1. Changes are surgical and minimal -2. No introduction of `any` types -3. Error handling is comprehensive -4. Documentation is updated -5. No unrelated changes included - -## ๐ŸŒŸ Best Practices - -### DO โœ… - -- Use module aliases for imports -- Use Zod for all validation -- Write tests using semantic queries -- Add JSDoc to public APIs -- Follow conventional commit format -- Keep changes focused and minimal -- Run `yarn audit:code-health` before PRs - -### DON'T โŒ - -- Use relative imports -- Use `any` types (use `unknown` instead) -- Use `data-*` attributes in tests -- Use raw Tailwind colors (use semantic) -- Create barrel files (`index.ts`) -- Use `console.log` (use logger) -- Modify unrelated code - -## ๐Ÿ”— Resources - -### External References - -- **OpenAI Harness Engineering**: [https://openai.com/index/harness-engineering/](https://openai.com/index/harness-engineering/) -- **Loop Methodology**: [https://ghuntley.com/loop/](https://ghuntley.com/loop/) -- **Testing Library**: [https://testing-library.com/docs/react-testing-library/intro/](https://testing-library.com/docs/react-testing-library/intro/) -- **Zod Documentation**: [https://zod.dev/](https://zod.dev/) - -### Internal Documentation - -- **AI Workflow Examples**: [ai-tools/workflow-examples.md](./ai-tools/workflow-examples.md) -- **Generated API Docs**: [ai-tools/api-documentation.md](./ai-tools/api-documentation.md) -- **Type Reference**: [ai-tools/type-reference.md](./ai-tools/type-reference.md) - -## ๐Ÿ†˜ Getting Help - -1. **Check existing documentation** - README, AGENTS.md, CONTRIBUTING.md -2. **Run AI tools** - `yarn ai:index` for up-to-date docs -3. **Review workflow examples** - See `ai-tools/workflow-examples.md` -4. **Check GitHub issues** - Look for similar problems -5. **Create an issue** - Provide context and steps to reproduce - -## ๐Ÿ“ˆ Success Metrics - -An AI agent is successful when: - -- โœ… Changes are minimal and surgical -- โœ… All tests pass (core, web, backend) -- โœ… Type checking passes -- โœ… Code follows conventions -- โœ… Documentation is updated -- โœ… No regressions introduced -- โœ… Code is readable and maintainable - ---- - -**Remember**: The goal is to make safe, incremental improvements while maintaining high code quality and following established patterns. When in doubt, check the documentation, run the AI tools, and keep changes small and focused.