From 5ba07ed6d823e8b469384195730d7c103c8b3c15 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 26 Feb 2026 17:19:51 +0000 Subject: [PATCH 1/3] docs(config): add cursor cloud specific instructions to AGENTS.md --- AGENTS.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2417a0804..b7807519c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ Always reference these instructions first and fallback to search or bash command - **CRITICAL**: The backend requires external service credentials (Google OAuth, Supertokens, MongoDB) to run properly - **Web Development** (RECOMMENDED for coding): - - `yarn dev:web` - Takes ~10 seconds to build. Serves on + - `yarn dev:web` - Takes ~10 seconds to build. Serves on - Frontend works standalone without backend services - **Backend Development** (requires full setup): - `yarn dev:backend` - Fails without proper .env configuration @@ -115,7 +115,7 @@ packages/core/src/ ```bash # Required for backend to start -BASEURL=http://localhost:3000/api +BASEURL=[REDACTED] GOOGLE_CLIENT_ID=YOUR_GOOGLE_OAUTH_CLIENT_ID GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_OAUTH_SECRET SUPERTOKENS_URI=YOUR_SUPERTOKENS_INSTANCE_URL @@ -144,7 +144,7 @@ TZ=Etc/UTC 1. **Start Development**: `yarn dev:web` (frontend only, always works) 2. **Run Tests**: `yarn test:core && yarn test:web` (skips problematic backend tests) 3. **Check Code Style**: `yarn prettier . --write` -4. **Manual Validation**: Open and verify login page loads +4. **Manual Validation**: Open and verify login page loads ### Styling @@ -273,3 +273,26 @@ The repository includes Husky hooks that will: - Run `yarn prettier . --write` on pre-push (ensures consistent formatting) **ALWAYS** ensure your commits pass these checks before pushing. + +## Cursor Cloud specific instructions + +### Node.js Version + +This project requires Node.js >= 24.0.0. The update script installs it via `nvm`. After the update script runs, `nvm use 24` is needed in each new shell session (the update script handles `nvm alias default 24`). + +### Running Services + +- **Web frontend** (`yarn dev:web`): Works standalone on port 9080 with demo/mock data, no backend needed. This is the primary development target in cloud environments. +- **Backend** (`yarn dev:backend`): Requires real Google OAuth, SuperTokens, and MongoDB credentials in `packages/backend/.env`. Will not start without them. + +### Testing + +- Run `yarn test:core`, `yarn test:web`, and `yarn test:backend` individually. All three pass in cloud environments. +- `yarn test` (full suite) also works because `@shelf/jest-mongodb` downloads a MongoDB memory server binary; this succeeds as long as `fastdl.mongodb.org` is reachable. +- Lint: `yarn prettier . --check` (or `--write` to auto-fix). + +### Gotchas + +- The `.env.local.example` file is at `packages/backend/.env.local.example` (not `.env.example`). The update script copies it to `packages/backend/.env` if the `.env` file doesn't already exist. +- Webpack dev server warns about a missing `.env.local` file; this is harmless — it falls back to `process.env`. +- Husky pre-push hook runs `yarn prettier . --write`, which can modify files. Ensure working tree is clean or committed before pushing. From 594ef909192463d873b04d0e406d74069a84363b Mon Sep 17 00:00:00 2001 From: Tyler Dane Date: Fri, 27 Feb 2026 11:15:52 -0800 Subject: [PATCH 2/3] docs(AGENTS): update development instructions in AGENTS.md for clarity and best practices --- .cursorrules/development.md | 2 +- AGENTS.md | 33 ++++++++++++++------------------- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/.cursorrules/development.md b/.cursorrules/development.md index c5487e895..45f48492a 100644 --- a/.cursorrules/development.md +++ b/.cursorrules/development.md @@ -22,7 +22,7 @@ yarn install --frozen-lockfile --network-timeout 300000 ### Environment Configuration ```bash -cp packages/backend/.env.example packages/backend/.env +cp packages/backend/.env.local.example packages/backend/.env ``` Edit `packages/backend/.env` with your credentials. diff --git a/AGENTS.md b/AGENTS.md index b7807519c..218fd2c97 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,6 +7,7 @@ Always reference these instructions first and fallback to search or bash command 1. When working in `packages/web`, follow React best practices and idiomatic patterns 2. When working in `packages/backend` or `packages/core`, follow Node.js best practices and idiomatic patterns 3. Always use module aliased paths for imports when importing Compass modules. +4. Prefer the simplest solution to a problem over the more complex solutions. ## Working Effectively @@ -18,13 +19,11 @@ Always reference these instructions first and fallback to search or bash command ### Development Servers -- **CRITICAL**: The backend requires external service credentials (Google OAuth, Supertokens, MongoDB) to run properly -- **Web Development** (RECOMMENDED for coding): - - `yarn dev:web` - Takes ~10 seconds to build. Serves on +- **Web Development**: + - yarn dev:web - Takes ~10 seconds to build. Serves on http://localhost:9080/ - Frontend works standalone without backend services -- **Backend Development** (requires full setup): +- **Backend Development**: - `yarn dev:backend` - Fails without proper .env configuration - - Needs: Google Cloud OAuth credentials, Supertokens account, MongoDB connection ### Testing @@ -37,16 +36,14 @@ Always reference these instructions first and fallback to search or bash command #### Running Tests -- **Core tests**: `yarn test:core` - Takes ~2 seconds. NEVER CANCEL. Always tests pass. -- **Web tests**: `yarn test:web` - Takes ~15 seconds. NEVER CANCEL. All tests pass -- **Full test suite**: `yarn test` - Takes ~18 seconds but FAILS in restricted environments due to MongoDB binary download from fastdl.mongodb.org - - Use individual package tests instead: `yarn test:core` and `yarn test:web` -- **DO NOT** attempt to test login functionality without proper backend setup +- **Core tests**: `yarn test:core`. +- **Web tests**: `yarn test:web`. +- **Full test suite**: `yarn test`. - **ALWAYS** run `yarn test:core` and `yarn test:web` and `yarn test:backend` after making changes +- **DO NOT** attempt to test login functionality without proper backend setup ### Building -- **CLI Tool**: `yarn cli --help` - Takes ~3 seconds. Lists all available commands. - **Web Build**: `yarn cli build web --environment staging --clientId "test-client-id"` - **Node Build**: `yarn cli build nodePckgs --environment staging` - Both builds require valid environment configuration @@ -74,7 +71,7 @@ This is a Typescript project with a monorepo structure. ### Key Files & Directories -``` +```text packages/backend/src/ ├── auth/ # Google OAuth integration ├── calendar/ # Google Calendar API @@ -115,7 +112,7 @@ packages/core/src/ ```bash # Required for backend to start -BASEURL=[REDACTED] +BASEURL=http://localhost:3000/api GOOGLE_CLIENT_ID=YOUR_GOOGLE_OAUTH_CLIENT_ID GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_OAUTH_SECRET SUPERTOKENS_URI=YOUR_SUPERTOKENS_INSTANCE_URL @@ -144,7 +141,7 @@ TZ=Etc/UTC 1. **Start Development**: `yarn dev:web` (frontend only, always works) 2. **Run Tests**: `yarn test:core && yarn test:web` (skips problematic backend tests) 3. **Check Code Style**: `yarn prettier . --write` -4. **Manual Validation**: Open and verify login page loads +4. **Manual Validation**: Open and verify login page loads ### Styling @@ -155,8 +152,6 @@ TZ=Etc/UTC ### CI/CD Integration - GitHub Actions runs `yarn install` and `yarn test` -- Tests fail in CI due to MongoDB network restrictions (known limitation) -- Linting and build validation happens in CI pipeline ## Troubleshooting @@ -278,18 +273,18 @@ The repository includes Husky hooks that will: ### Node.js Version -This project requires Node.js >= 24.0.0. The update script installs it via `nvm`. After the update script runs, `nvm use 24` is needed in each new shell session (the update script handles `nvm alias default 24`). +This project requires Node.js >= 24.0.0. ### Running Services - **Web frontend** (`yarn dev:web`): Works standalone on port 9080 with demo/mock data, no backend needed. This is the primary development target in cloud environments. - **Backend** (`yarn dev:backend`): Requires real Google OAuth, SuperTokens, and MongoDB credentials in `packages/backend/.env`. Will not start without them. -### Testing +### Cursor Testing - Run `yarn test:core`, `yarn test:web`, and `yarn test:backend` individually. All three pass in cloud environments. - `yarn test` (full suite) also works because `@shelf/jest-mongodb` downloads a MongoDB memory server binary; this succeeds as long as `fastdl.mongodb.org` is reachable. -- Lint: `yarn prettier . --check` (or `--write` to auto-fix). +- Lint: `yarn prettier . --write` to auto-fix. ### Gotchas From af65c03cbab9d688e62229783b683b3a66291750 Mon Sep 17 00:00:00 2001 From: Tyler Dane Date: Fri, 27 Feb 2026 11:22:55 -0800 Subject: [PATCH 3/3] docs(AGENTS): expand development instructions in AGENTS.md with detailed quick start guide, module aliases, and troubleshooting tips --- AGENTS.md | 134 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 91 insertions(+), 43 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 218fd2c97..6ef8405cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,53 @@ # Compass Calendar Development Instructions -Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. +Primary instructions for AI agents and developers in the Compass monorepo. + +## Quick Start + +1. `yarn install --frozen-lockfile --network-timeout 300000` (takes ~3.5 min, do not cancel) +2. `cp packages/backend/.env.local.example packages/backend/.env` +3. `yarn dev:web` (frontend on http://localhost:9080/) + +## Table of Contents + +- [Compass Calendar Development Instructions](#compass-calendar-development-instructions) + - [Quick Start](#quick-start) + - [Table of Contents](#table-of-contents) + - [Key Guidelines](#key-guidelines) + - [Module Aliases](#module-aliases) + - [Working Effectively](#working-effectively) + - [Initial Setup](#initial-setup) + - [Development Servers](#development-servers) + - [Testing](#testing) + - [Writing Tests in `@compass/web`](#writing-tests-in-compassweb) + - [Running Tests](#running-tests) + - [Building](#building) + - [Linting](#linting) + - [Validation](#validation) + - [Project Structure](#project-structure) + - [Packages Overview](#packages-overview) + - [Key Files \& Directories](#key-files--directories) + - [Environment Requirements](#environment-requirements) + - [Required for Full Development](#required-for-full-development) + - [Optional Services](#optional-services) + - [Critical Environment Variables (backend/.env)](#critical-environment-variables-backendenv) + - [Common Tasks \& Timing](#common-tasks--timing) + - [Repository Operations](#repository-operations) + - [Development Workflow](#development-workflow) + - [Styling](#styling) + - [CI/CD Integration](#cicd-integration) + - [Troubleshooting](#troubleshooting) + - [Common Issues](#common-issues) + - [Network Limitations](#network-limitations) + - [Workarounds](#workarounds) + - [Package Scripts Reference](#package-scripts-reference) + - [Root Level Commands](#root-level-commands) + - [Naming Conventions](#naming-conventions) + - [Branch Naming \& Commit Message Conventions](#branch-naming--commit-message-conventions) + - [Semantic Branch Naming](#semantic-branch-naming) + - [Semantic Commit Messages](#semantic-commit-messages) + - [Pre-commit Validation](#pre-commit-validation) + - [Gotchas](#gotchas) ## Key Guidelines @@ -9,13 +56,27 @@ Always reference these instructions first and fallback to search or bash command 3. Always use module aliased paths for imports when importing Compass modules. 4. Prefer the simplest solution to a problem over the more complex solutions. +## Module Aliases + +Use these aliases instead of relative paths: + +- **Backend, scripts, core** (see root `package.json` `_moduleAliases`): + - `@compass/backend` → `packages/backend/src` + - `@compass/core` → `packages/core/src` + - `@compass/scripts` → `packages/scripts/src` +- **Web** (see `packages/web/tsconfig.json` paths): + - `@web/*` → `packages/web/src/*` + - `@core/*` → `packages/core/src/*` + +Example: `import { foo } from '@compass/core'` not `import { foo } from '../../../core'` + ## Working Effectively ### Initial Setup - Install dependencies: `yarn install --frozen-lockfile --network-timeout 300000` - - Takes ~3.5 minutes. NEVER CANCEL. Set timeout to 10+ minutes. -- Copy environment template: `cp packages/backend/.env.example packages/backend/.env` + - Takes ~3.5 minutes. Set timeout to 10+ minutes. +- Copy environment template: `cp packages/backend/.env.local.example packages/backend/.env` ### Development Servers @@ -27,20 +88,23 @@ Always reference these instructions first and fallback to search or bash command ### Testing -### Writing Tests in `@compass/web` +Run `yarn test:core`, `yarn test:web`, and `yarn test:backend` after making changes. Use `yarn test:scripts` for scripts package tests. Avoid `yarn test` (full suite) in restricted network environments—MongoDB binary download may fail. + +#### Writing Tests in `@compass/web` - Write tests the way a user would use the application by using the DOM and user interactions with `@testing-library/user-event` rather than internal implementation details of React components. - Do NOT use `data-` attributes or CSS selectors to locate elements. Use semantic locators and roles instead. - When writing tests, avoid mocking as much as possible. - Where mocking is inevitable, use spies to sub out specific module functions before attempting to mock the whole module. +- **DO NOT** attempt to test login functionality without proper backend setup. #### Running Tests -- **Core tests**: `yarn test:core`. -- **Web tests**: `yarn test:web`. -- **Full test suite**: `yarn test`. -- **ALWAYS** run `yarn test:core` and `yarn test:web` and `yarn test:backend` after making changes -- **DO NOT** attempt to test login functionality without proper backend setup +- **Core tests**: `yarn test:core` +- **Web tests**: `yarn test:web` +- **Backend tests**: `yarn test:backend` +- **Scripts tests**: `yarn test:scripts` +- **Full test suite**: `yarn test` (may fail if MongoDB binary download is blocked) ### Building @@ -50,7 +114,7 @@ Always reference these instructions first and fallback to search or bash command ### Linting -- `yarn prettier . --write` - Takes ~15 seconds. NEVER CANCEL. +- `yarn prettier . --write` - Takes ~15 seconds. ## Validation @@ -129,17 +193,18 @@ TZ=Etc/UTC ### Repository Operations -- `yarn install` - 3.5 minutes (NEVER CANCEL, set 10+ minute timeout) -- `yarn test:core` - 2 seconds (all pass) -- `yarn test:web` - 15 seconds (all pass) -- `yarn test:backend` - 15 seconds (all pass) -- `yarn dev:web` - 10 seconds to start (always works) -- `yarn cli --help` - 3 seconds (shows available commands) +- `yarn install` - 3.5 minutes +- `yarn test:core` - ~2 seconds (all pass) +- `yarn test:web` - ~15 seconds (all pass) +- `yarn test:backend` - ~15 seconds (all pass) +- `yarn test:scripts` - scripts package tests +- `yarn dev:web` - ~10 seconds to start +- `yarn cli --help` - ~3 seconds (shows available commands) ### Development Workflow 1. **Start Development**: `yarn dev:web` (frontend only, always works) -2. **Run Tests**: `yarn test:core && yarn test:web` (skips problematic backend tests) +2. **Run Tests**: `yarn test:core && yarn test:web` (add `&& yarn test:backend` when credentials available) 3. **Check Code Style**: `yarn prettier . --write` 4. **Manual Validation**: Open and verify login page loads @@ -157,10 +222,8 @@ TZ=Etc/UTC ### Common Issues -- **MongoDB download failures**: Use `yarn test:core` and `yarn test:web` instead of `yarn test` -- **Backend won't start**: Missing environment variables, use web-only development -- **Build timeouts**: All build operations need 10+ minute timeouts -- **Test failures**: Expected in restricted network environments +- **Test failures**: Run `yarn test:core`, `yarn test:web`, and `yarn test:backend` individually to narrow the scope of the failure +- **Backend won't start**: Missing environment variables in `packages/backend/.env`, use web-only development (`yarn dev:web`) ### Network Limitations @@ -183,6 +246,8 @@ TZ=Etc/UTC - `yarn test` - Run all tests (fails in restricted environments) - `yarn test:core` - Run core package tests only - `yarn test:web` - Run web package tests only +- `yarn test:backend` - Run backend package tests only +- `yarn test:scripts` - Run scripts package tests only Always prioritize frontend development with `yarn dev:web` when backend services are unavailable. @@ -195,9 +260,9 @@ Always prioritize frontend development with `yarn dev:web` when backend services ### Semantic Branch Naming -**ALWAYS** create branches following this pattern based on the GitHub issue: +**ALWAYS** create branches following this pattern: -- `type/action-issue-number` (e.g., `copilot/fix-spinner`, `feature/add-form`, `bug/fix-auth`) +- `type/action[-issue-number]` (e.g., `feature/add-form`, `bug/fix-auth`, `bug/fix-auth-123`) **Branch Type Prefixes:** @@ -269,25 +334,8 @@ The repository includes Husky hooks that will: **ALWAYS** ensure your commits pass these checks before pushing. -## Cursor Cloud specific instructions - -### Node.js Version - -This project requires Node.js >= 24.0.0. - -### Running Services - -- **Web frontend** (`yarn dev:web`): Works standalone on port 9080 with demo/mock data, no backend needed. This is the primary development target in cloud environments. -- **Backend** (`yarn dev:backend`): Requires real Google OAuth, SuperTokens, and MongoDB credentials in `packages/backend/.env`. Will not start without them. - -### Cursor Testing - -- Run `yarn test:core`, `yarn test:web`, and `yarn test:backend` individually. All three pass in cloud environments. -- `yarn test` (full suite) also works because `@shelf/jest-mongodb` downloads a MongoDB memory server binary; this succeeds as long as `fastdl.mongodb.org` is reachable. -- Lint: `yarn prettier . --write` to auto-fix. - -### Gotchas +## Gotchas -- The `.env.local.example` file is at `packages/backend/.env.local.example` (not `.env.example`). The update script copies it to `packages/backend/.env` if the `.env` file doesn't already exist. -- Webpack dev server warns about a missing `.env.local` file; this is harmless — it falls back to `process.env`. +- Environment: Copy from `packages/backend/.env.local.example` to `packages/backend/.env` (there is no `.env.example`). +- Webpack dev server warns about a missing `.env.local` file; this is harmless—it falls back to `process.env`. - Husky pre-push hook runs `yarn prettier . --write`, which can modify files. Ensure working tree is clean or committed before pushing.