.cursorrules

# Zero In - AI Coding Agent Instructions

## Top Instructions

- Be extremely concise and sacrifice grammar for the sake of concision
- Following TDD when adding new features, ONE test → ONE implementation → repeat
- Avoid comments if code or function names are self-explanatory. Comment only for non-obvious logic.

## Project Overview

Zero In is a focus productivity tool with three platforms:

- **Browser Extension** (Chrome/Edge): Timer + website blocker using WXT framework (Vue 3, TypeScript)
- **Mobile App** (iOS/Android): React Native with Expo, native app blocking via Screen Time API (iOS) and UsageStats/Overlays (Android)
- **Firebase Backend**: Firestore for user data sync, Firebase Auth

This is a Yarn 4 monorepo with workspaces (`apps/*`, `packages/*`).

## Architecture Patterns

### Domain-Driven Design (Global)

The project follows DDD principles across all packages:

- **Domain Logic** (`src/domain/`): Pure business logic, framework-agnostic.
  - Dependencies injected via constructor.
  - `static createFake()` methods are MANDATORY for testing.
  - NO platform-specific imports (e.g., no `chrome.*`, no `react-native`).
- **Infrastructure** (`src/infra/`): Platform adapters.
  - format: `*Service` interface + `*Impl` or platform-specific implementation.
  - `createFake()` methods for test isolation.
- **Entry Points/UI**:
  - Extension: `apps/extension/src/entrypoints/`
  - Mobile: `apps/mobile/app/`

### Shared Package (`@zero-in/shared`)

Located in `packages/shared/`, this package MUST be used for all logic shared between Extension and Mobile.

- **`domain/`**:
  - `schedules/`: Scheduling logic (schema, serialization, validation).
  - `time/`: `Time` class and helpers.
  - `timer-based-blocking/`: Timer logic.
- **`infra/`**:
  - `storage/`: Shared storage interfaces and Firebase implementations (`FirestoreAppStorage`).
- **`utils/`**: Shared helpers.

### Mobile App Structure (`apps/mobile`)

Expo-based React Native app:

- **Routing**: File-based routing in `app/`.
- **Modules**: Custom native modules in `modules/`.
  - `modules/app-blocker`: Native implementation of app blocking (ScreenTime API / Android Native).
- **Domain/Infra**:
  - Uses `@zero-in/shared` for core logic.
  - `apps/mobile/domain/`: Mobile-specific domain logic not yet shared.
  - `apps/mobile/infra/`: Mobile-specific adapters (e.g., `ReactNativeFirestoreAdapter`).

## Code Style & Conventions

### TypeScript

- **Strict Mode**: Enabled.
- **Explicit Types**: Prefer explicit types.
- **Async/Await**: properly await all promises.
- **Imports**:
  - Extension: `@/*` -> `apps/extension/src/*`
  - Shared: `@zero-in/shared/*` -> `packages/shared/src/*`
  - Mobile: Relative imports or configured aliases.

### Dependency Injection (Strict)

All Domain Services MUST follow this pattern:

```typescript
export class MyService {
  constructor(private deps: { dep1: Dep1; dep2: Dep2 }) {}

  static createFake(overrides = {}) {
    return new MyService({
      dep1: new FakeDep1(),
      dep2: new FakeDep2(),
      ...overrides
    })
  }
}
```

### Storage Service Pattern

All storage services implement `StorageService<T>`:

```typescript
export interface StorageService<T> {
  get(): Promise<T | null>
  save(data: T): Promise<void>
}
```

Implementations must handle serialization/deserialization internally.

## Testing Strategy

### Unit Tests

- **Location**: `*.spec.ts` alongside source files.
- **Tool**: Vitest.
- **Execution**: Run tests via terminal commands/scripts (e.g., `yarn test:unit`, `yarn test:integration`), NOT via VS Code Test Runner.
- **Mocks**: STRICTLY use `createFake()` implementations. NO MOCKING LIBRARIES (jest.mock, etc) for domain logic.
- **Timers**: Use `vi.useFakeTimers()` for time-dependent tests.

### Integration Tests

- **Location**: `*.integration.spec.ts`.
- **Environment**: Firebase Emulators.
- **Command**: `yarn test:integration` (in extension).

### E2E Tests (Extension)

- **Command**: `yarn build-and-e2e` (builds CI version then runs tests).
- **Note**: Always ensure the extension is built via `build:ci` (which sets emulator flags) before running `test:e2e`. The `build-and-e2e` script handles this safety.

## File Organization

### Extension (`apps/extension/src`)

- `domain/`: Business logic.
- `infra/`: Browser APIs (Storage, Alarms, Tabs).
- `entrypoints/`: UI (Popup, Options, Content Scripts).
- `service-workers/`: Background processes.

### Mobile (`apps/mobile`)

- `app/`: Expo Router pages.
- `modules/`: Native modules (Kotlin/Swift).
- `domain/`: Mobile-specific domain.
- `infra/`: React Native implementations of shared interfaces.

## Special Notes

1.  **Shared Logic**: Logic should be moved to `@zero-in/shared` **only if** it is used (or expected to be used) by both Extension and Mobile. Platform-specific domain logic can stay in its respective package.
2.  **No Direct Native Calls in Domain**: Domain code must never call `chrome.*` or `Module.*` directly. Wrap in an Interface in `domain/` and implement in `infra/`.
3.  **Native Modules**: Changes to `modules/` require rebuilding the native app.

## Agent Behavior

- You are encouraged to set `SafeToAutoRun: true` for all read-only commands (ls, cat, grep, etc.) to minimize interruptions.
- NOTE: This file is symlinked by `.github/copilot-instructions.md`.