apple-calendar-mcp: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

Source lives in src/, segmented into clean architecture rings so dependencies flow inward. Transport adapters sit in src/server/, the vendored Swift CLI binary (bin/event) is built from the vendor/event git submodule, and automation workflows stay under src/tools/. Shared helpers live in src/utils/ (including eventCli.ts — the wrapper around bin/event), while src/validation/ enforces Zod contracts on every reminder payload. Tests co-locate as *.test.ts beside subjects to keep TDD feedback immediate, and generated binaries rebuild instead of touching dist/.

Build, Test, and Development Commands

Run pnpm install to sync the locked dependency graph (and to build the vendored event CLI via the postinstall hook). Use pnpm dev for watch-mode TypeScript development without recompiling the Swift binary. Execute pnpm test to run the Jest suite through ts-jest and the __mocks__/eventCli.ts mock. Run pnpm exec biome check before commits to enforce formatting, linting, and import ordering, and rebuild the native helper with pnpm build:event whenever the vendor/event submodule pin moves.

Coding Style & Naming Conventions

Biome enforces two-space indentation, single quotes, and sorted imports across .ts files. Choose camelCase for variables and functions, PascalCase for classes, and reuse screaming snake constants from src/utils/constants.ts when system identifiers need emphasis. Prefer composition, dependency injection, and repository abstractions to keep outer layers independent of inner logic, and comment only to justify architectural trade-offs or business rules.

Testing Guidelines

Follow strict RED-GREEN-REFACTOR cycles by writing a failing Jest spec beside each new unit. Use the fixtures under src/__mocks__/ to stabilize reminder schema behavior and initialize shared state through src/test-setup.ts. Narrow prompt template changes by targeting pnpm test -- src/server/prompts.test.ts. Name specs <module>.test.ts for discoverability and prioritize schema and error-path coverage before happy paths.