Source lives in src/, segmented into clean architecture rings so dependencies flow inward. Transport adapters sit in src/server/, the Swift bridge lives in src/swift/, and automation workflows stay under src/tools/. Shared helpers live in src/utils/, 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/.
Run pnpm install to sync the locked dependency graph that coordinates TypeScript and Swift toolchains. Use pnpm dev for watch-mode development without recompiling Swift components. Execute pnpm test to run the Jest suite through ts-jest and mocks. Run pnpm exec biome check before commits to enforce formatting, linting, and import ordering, and rebuild native helpers with pnpm build:swift whenever AppleScript or Swift glue changes.
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.
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.
Craft conventional commits such as feat: add transport validator, keeping titles lowercase and under 50 characters. Ensure every commit leaves pnpm test and pnpm exec biome check green to maintain CI parity. PRs require actionable descriptions, verification command logs, and linked issues for traceability, and provide screenshots or logs when modifying transport flows or reminder outputs. Merge via merge commits only after CI and security checks pass.
Store secrets exclusively in .env.local and load them through typed contracts to avoid leaking reminder data. Grant macOS Reminders and Calendar permissions locally; the Swift bridge aborts before integration tests without them. Run pnpm audit --prod ahead of release branches to surface Swift toolchain CVEs, and stub external services via dependency injection instead of hardcoding tokens or calendar IDs.
macOS permissions for Reminders and Calendar are now automatically requested when needed. The Swift CLI (src/swift/EventKitCLI.swift) handles all permission checking and requesting using EKEventStore.authorizationStatus() following EventKit best practices. It checks permission status before operations:
- If authorized: proceeds directly
- If notDetermined: requests permission automatically
- If denied/restricted: returns clear error message
TypeScript handlers trust Swift layer's permission handling and do not duplicate permission checks. The Swift CLI automatically handles permission requests following EventKit best practices.