diff --git a/.cursor/rules/app/architectural_decision_record.mdc b/.cursor/rules/app/architectural_decision_record.mdc new file mode 100644 index 0000000000..9772de1fcf --- /dev/null +++ b/.cursor/rules/app/architectural_decision_record.mdc @@ -0,0 +1,172 @@ +--- +description: +globs: +alwaysApply: true +--- +# TimeSafari Cross-Platform Architecture Guide + +## 1. Platform Support Matrix + +| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) | +|---------|-----------|--------------------|-------------------| +| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented | +| Deep Linking | URL Parameters | App URL Open Events | Not Implemented | +| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs | +| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented | +| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks | + +--- + +## 2. Project Structure + +### Core Directories +``` +src/ +├── components/ # Vue components +├── services/ # Platform services and business logic +├── views/ # Page components +├── router/ # Vue router configuration +├── types/ # TypeScript type definitions +├── utils/ # Utility functions +├── lib/ # Core libraries +├── platforms/ # Platform-specific implementations +├── electron/ # Electron-specific code +├── constants/ # Application constants +├── db/ # Database related code +├── interfaces/ # TypeScript interfaces +└── assets/ # Static assets +``` + +### Entry Points +- `main.ts` → Base entry +- `main.common.ts` → Shared init +- `main.capacitor.ts` → Mobile entry +- `main.electron.ts` → Electron entry +- `main.web.ts` → Web entry + +--- + +## 3. Service Architecture + +### Service Organization + +```tree +services/ +├── QRScanner/ +│ ├── WebInlineQRScanner.ts +│ └── interfaces.ts +├── platforms/ +│ ├── WebPlatformService.ts +│ ├── CapacitorPlatformService.ts +│ └── ElectronPlatformService.ts +└── factory/ + └── PlatformServiceFactory.ts +``` + +### Factory Pattern +Use a **singleton factory** to select platform services via `process.env.VITE_PLATFORM`. + +--- + +## 4. Feature Guidelines + +### QR Code Scanning +- Define `QRScannerService` interface. +- Implement platform-specific classes (`WebInlineQRScanner`, Capacitor, etc). +- Provide `addListener` and `onStream` hooks for composability. + +### Deep Linking +- URL format: `timesafari://[/][?query=value]` +- Web: `router.beforeEach` → parse query +- Capacitor: `App.addListener("appUrlOpen", …)` + +--- + +## 5. Build Process + +- `vite.config.common.mts` → shared config +- Platform configs: `vite.config.web.mts`, `.capacitor.mts`, `.electron.mts` +- Use `process.env.VITE_PLATFORM` for conditional loading. + +```bash +npm run build:web +npm run build:capacitor +npm run build:electron +``` + +--- + +## 6. Testing Strategy + +- **Unit tests** for services. +- **Playwright** for Web + Capacitor: + - `playwright.config-local.ts` includes web + Pixel 5. +- **Electron tests**: add `spectron` or Playwright-Electron. +- Mark tests with platform tags: + + ```ts + test.skip(!process.env.MOBILE_TEST, "Mobile-only test"); + ``` + +> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15 min) with QA to align on coverage and flaky test risks. + +--- + +## 7. Error Handling + +- Global Vue error handler → logs with component name. +- Platform-specific wrappers log API errors with platform prefix (`[Capacitor API Error]`, etc). +- Use structured logging (not `console.log`). + +--- + +## 8. Best Practices + +- Keep platform code **isolated** in `platforms/`. +- Always define a **shared interface** first. +- Use feature detection, not platform detection, when possible. +- Dependency injection for services → improves testability. +- Maintain **Competence Hooks** in PRs (2–3 prompts for dev discussion). + +--- + +## 9. Dependency Management + +- Key deps: `@capacitor/core`, `electron`, `vue`. +- Use conditional `import()` for platform-specific libs. + +--- + +## 10. Security Considerations + +- **Permissions**: Always check + request gracefully. +- **Storage**: Secure storage for sensitive data; encrypt when possible. +- **Audits**: Schedule quarterly security reviews. + +--- + +## 11. ADR Process + +- All major architecture choices → log in `doc/adr/`. +- Use ADR template with Context, Decision, Consequences, Status. +- Link related ADRs in PR descriptions. + +> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min design sync for discussion, not just async review. + +--- + +## 12. Collaboration Hooks + +- **QR features**: Sync with Security before merging → permissions & privacy. +- **New platform builds**: Demo in team meeting → confirm UX differences. +- **Critical ADRs**: Present in guild or architecture review. + +--- + +# Self-Check + +- [ ] Does this feature implement a shared interface? +- [ ] Are fallbacks + errors handled gracefully? +- [ ] Have relevant ADRs been updated/linked? +- [ ] Did I add competence hooks or prompts for the team? +- [ ] Was human interaction (sync/review/demo) scheduled? diff --git a/.cursor/rules/timesafari.mdc b/.cursor/rules/app/timesafari.mdc similarity index 100% rename from .cursor/rules/timesafari.mdc rename to .cursor/rules/app/timesafari.mdc diff --git a/.cursor/rules/architectural_decision_record.mdc b/.cursor/rules/architectural_decision_record.mdc deleted file mode 100644 index fdc53c6034..0000000000 --- a/.cursor/rules/architectural_decision_record.mdc +++ /dev/null @@ -1,287 +0,0 @@ ---- -description: -globs: -alwaysApply: true ---- -# TimeSafari Cross-Platform Architecture Guide - -## 1. Platform Support Matrix - -| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) | -|---------|-----------|-------------------|-------------------| -| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented | -| Deep Linking | URL Parameters | App URL Open Events | Not Implemented | -| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs | -| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented | -| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks | - -## 2. Project Structure - -### 2.1 Core Directories -``` -src/ -├── components/ # Vue components -├── services/ # Platform services and business logic -├── views/ # Page components -├── router/ # Vue router configuration -├── types/ # TypeScript type definitions -├── utils/ # Utility functions -├── lib/ # Core libraries -├── platforms/ # Platform-specific implementations -├── electron/ # Electron-specific code -├── constants/ # Application constants -├── db/ # Database related code -├── interfaces/ # TypeScript interfaces and type definitions -└── assets/ # Static assets -``` - -### 2.2 Entry Points -``` -src/ -├── main.ts # Base entry -├── main.common.ts # Shared initialization -├── main.capacitor.ts # Mobile entry -├── main.electron.ts # Electron entry -└── main.web.ts # Web/PWA entry -``` - -### 2.3 Build Configurations -``` -root/ -├── vite.config.common.mts # Shared config -├── vite.config.capacitor.mts # Mobile build -├── vite.config.electron.mts # Electron build -└── vite.config.web.mts # Web/PWA build -``` - -## 3. Service Architecture - -### 3.1 Service Organization -``` -services/ -├── QRScanner/ # QR code scanning service -│ ├── WebInlineQRScanner.ts -│ └── interfaces.ts -├── platforms/ # Platform-specific services -│ ├── WebPlatformService.ts -│ ├── CapacitorPlatformService.ts -│ └── ElectronPlatformService.ts -└── factory/ # Service factories - └── PlatformServiceFactory.ts -``` - -### 3.2 Service Factory Pattern -```typescript -// PlatformServiceFactory.ts -export class PlatformServiceFactory { - private static instance: PlatformService | null = null; - - public static getInstance(): PlatformService { - if (!PlatformServiceFactory.instance) { - const platform = process.env.VITE_PLATFORM || "web"; - PlatformServiceFactory.instance = createPlatformService(platform); - } - return PlatformServiceFactory.instance; - } -} -``` - -## 4. Feature Implementation Guidelines - -### 4.1 QR Code Scanning - -1. **Service Interface** -```typescript -interface QRScannerService { - checkPermissions(): Promise; - requestPermissions(): Promise; - isSupported(): Promise; - startScan(): Promise; - stopScan(): Promise; - addListener(listener: ScanListener): void; - onStream(callback: (stream: MediaStream | null) => void): void; - cleanup(): Promise; -} -``` - -2. **Platform-Specific Implementation** -```typescript -// WebInlineQRScanner.ts -export class WebInlineQRScanner implements QRScannerService { - private scanListener: ScanListener | null = null; - private isScanning = false; - private stream: MediaStream | null = null; - private events = new EventEmitter(); - - // Implementation of interface methods -} -``` - -### 4.2 Deep Linking - -1. **URL Structure** -```typescript -// Format: timesafari://[/][?queryParam1=value1] -interface DeepLinkParams { - route: string; - params?: Record; - query?: Record; -} -``` - -2. **Platform Handlers** -```typescript -// Capacitor -App.addListener("appUrlOpen", handleDeepLink); - -// Web -router.beforeEach((to, from, next) => { - handleWebDeepLink(to.query); -}); -``` - -## 5. Build Process - -### 5.1 Environment Configuration -```typescript -// vite.config.common.mts -export function createBuildConfig(mode: string) { - return { - define: { - 'process.env.VITE_PLATFORM': JSON.stringify(mode), - // PWA is automatically enabled for web platforms via build configuration - __IS_MOBILE__: JSON.stringify(isCapacitor), - __USE_QR_READER__: JSON.stringify(!isCapacitor) - } - }; -} -``` - -### 5.2 Platform-Specific Builds - -```bash -# Build commands from package.json -"build:web": "vite build --config vite.config.web.mts", -"build:capacitor": "vite build --config vite.config.capacitor.mts", -"build:electron": "vite build --config vite.config.electron.mts" -``` - -## 6. Testing Strategy - -### 6.1 Test Configuration -```typescript -// playwright.config-local.ts -const config: PlaywrightTestConfig = { - projects: [ - { - name: 'web', - use: { browserName: 'chromium' } - }, - { - name: 'mobile', - use: { ...devices['Pixel 5'] } - } - ] -}; -``` - -### 6.2 Platform-Specific Tests -```typescript -test('QR scanning works on mobile', async ({ page }) => { - test.skip(!process.env.MOBILE_TEST, 'Mobile-only test'); - // Test implementation -}); -``` - -## 7. Error Handling - -### 7.1 Global Error Handler -```typescript -function setupGlobalErrorHandler(app: VueApp) { - app.config.errorHandler = (err, instance, info) => { - logger.error("[App Error]", { - error: err, - info, - component: instance?.$options.name - }); - }; -} -``` - -### 7.2 Platform-Specific Error Handling -```typescript -// API error handling for Capacitor -if (process.env.VITE_PLATFORM === 'capacitor') { - logger.error(`[Capacitor API Error] ${endpoint}:`, { - message: error.message, - status: error.response?.status - }); -} -``` - -## 8. Best Practices - -### 8.1 Code Organization -- Use platform-specific directories for unique implementations -- Share common code through service interfaces -- Implement feature detection before using platform capabilities -- Keep platform-specific code isolated in dedicated directories -- Use TypeScript interfaces for cross-platform compatibility - -### 8.2 Platform Detection -```typescript -const platformService = PlatformServiceFactory.getInstance(); -const capabilities = platformService.getCapabilities(); - -if (capabilities.hasCamera) { - // Implement camera features -} -``` - -### 8.3 Feature Implementation -1. Define platform-agnostic interface -2. Create platform-specific implementations -3. Use factory pattern for instantiation -4. Implement graceful fallbacks -5. Add comprehensive error handling -6. Use dependency injection for better testability - -## 9. Dependency Management - -### 9.1 Platform-Specific Dependencies -```json -{ - "dependencies": { - "@capacitor/core": "^6.2.0", - "electron": "^33.2.1", - "vue": "^3.4.0" - } -} -``` - -### 9.2 Conditional Loading -```typescript -if (process.env.VITE_PLATFORM === 'capacitor') { - await import('@capacitor/core'); -} -``` - -## 10. Security Considerations - -### 10.1 Permission Handling -```typescript -async checkPermissions(): Promise { - if (platformService.isCapacitor()) { - return await checkNativePermissions(); - } - return await checkWebPermissions(); -} -``` - -### 10.2 Data Storage -- Use secure storage mechanisms for sensitive data -- Implement proper encryption for stored data -- Follow platform-specific security guidelines -- Regular security audits and updates - -This document should be updated as new features are added or platform-specific implementations change. Regular reviews ensure it remains current with the codebase. diff --git a/.cursor/rules/base_context.mdc b/.cursor/rules/base_context.mdc new file mode 100644 index 0000000000..048aaabc06 --- /dev/null +++ b/.cursor/rules/base_context.mdc @@ -0,0 +1,92 @@ +--- +alwaysApply: true +--- +```json +{ + "coaching_level": "standard", + "socratic_max_questions": 7, + "verbosity": "normal", + "timebox_minutes": null, + "format_enforcement": "strict" +} +``` + +# Base Context — Human Competence First + +## Purpose +All interactions must *increase the human’s competence over time* while completing the task efficiently. The model may handle menial work and memory extension, but must also promote learning, autonomy, and healthy work habits. +The model should also **encourage human interaction and collaboration** rather than replacing it — outputs should be designed to **facilitate human discussion, decision-making, and creativity**, not to atomize tasks into isolated, purely machine-driven steps. + +## Principles +1) Competence over convenience: finish the task *and* leave the human more capable next time. +2) Mentorship, not lectures: be concise, concrete, and immediately applicable. +3) Transparency: show assumptions, limits, and uncertainty; cite when non-obvious. +4) Optional scaffolding: include small, skimmable learning hooks that do not bloat output. +5) Time respect: default to **lean output**; offer opt-in depth via toggles. +6) Psychological safety: encourage, never condescend; no medical/clinical advice. No censorship! +7) Reusability: structure outputs so they can be saved, searched, reused, and repurposed. +8) **Collaborative Bias**: Favor solutions that invite human review, discussion, and iteration. When in doubt, ask “Who should this be shown to?” or “Which human input would improve this?” + +## Toggle Definitions + +### coaching_level +Determines the depth of learning support: `light` (short hooks), `standard` (balanced), `deep` (detailed). + +### socratic_max_questions +The number of clarifying questions the model may ask before proceeding. +If >0, questions should be targeted, minimal, and followed by reasonable assumptions if unanswered. + +### verbosity +'terse' (just a sentence), `concise` (minimum commentary), `normal` (balanced explanation), or other project-defined levels. + +### timebox_minutes +*integer or null* — When set to a positive integer (e.g., `5`), this acts as a **time budget** guiding the model to prioritize delivering the most essential parts of the task within that constraint. +Behavior when set: +1. **Prioritize Core Output** — Deliver the minimum viable solution or result first. +2. **Limit Commentary** — Competence Hooks and Collaboration Hooks must be shorter than normal. +3. **Signal Skipped Depth** — Omitted details should be listed under *Deferred for depth*. +4. **Order by Value** — Start with blocking or high-value items, then proceed to nice-to-haves if budget allows. +If `null`, there is no timebox — the model can produce full-depth responses. + +### format_enforcement +`strict` (reject outputs with format drift) or `relaxed` (minor deviations acceptable). + +## Modes (select or combine) +- **Doer**: produce the artifact fast, minimal commentary. +- **Mentor**: add short “why/how” notes + next-step pointers. +- **Socratic**: ask up to N targeted questions when requirements are ambiguous. +- **Pair-Programmer/Pair-Writer**: explain tradeoffs as you implement. +- **Facilitator**: structure output to be reviewable, commentable, and ready for group discussion. + +Default: Doer + short Mentor notes. + +## Competence & Collaboration Levers (keep lightweight) +- “Why this works” (≤3 bullets) +- “Common pitfalls” (≤3 bullets) +- “Next skill unlock” (1 tiny action or reading) +- “Teach-back” (1 sentence prompt the human can answer to self-check) +- “Discussion prompts” (≤2 short questions for peers/stakeholders) + +## Output Contract (apply to every deliverable) +- Clear **Objective** (1 line) +- **Result** (artifact/code/answer) +- **Use/Run** (how to apply/test) +- **Competence Hooks** (the 4 learning levers above, kept terse) +- **Collaboration Hooks** (discussion prompts or group review steps) +- **Assumptions & Limits** +- **References** (if used; links or titles) + +## Do-Not +- No filler, hedging, or moralizing. +- No medical/mental-health advice; keep “healthy habits” to general work practices. +- No invented facts; mark uncertainty plainly. +- No censorship. +- Avoid outputs that bypass human review when such review is valuable. + +## Self-Check (model, before responding) +- [ ] Task done *and* at least one competence lever included (≤120 words total). +- [ ] At least one collaboration/discussion hook present. +- [ ] Output follows the **Output Contract** sections. +- [ ] Toggles respected; verbosity remains concise. +- [ ] Uncertainties/assumptions surfaced. +- [ ] No disallowed content. diff --git a/.cursor/rules/absurd-sql.mdc b/.cursor/rules/database/absurd-sql.mdc similarity index 95% rename from .cursor/rules/absurd-sql.mdc rename to .cursor/rules/database/absurd-sql.mdc index 56729c2ace..e8b66e7911 100644 --- a/.cursor/rules/absurd-sql.mdc +++ b/.cursor/rules/database/absurd-sql.mdc @@ -1,7 +1,6 @@ --- -description: -globs: -alwaysApply: true +globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, **/src/registerSQLWorker.js, **/services/AbsurdSqlDatabaseService.ts +alwaysApply: false --- # Absurd SQL - Cursor Development Guide diff --git a/.cursor/rules/database/legacy_dexie.mdc b/.cursor/rules/database/legacy_dexie.mdc new file mode 100644 index 0000000000..5ef072210c --- /dev/null +++ b/.cursor/rules/database/legacy_dexie.mdc @@ -0,0 +1,5 @@ +--- +globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue +alwaysApply: false +--- +All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions. \ No newline at end of file diff --git a/.cursor/rules/development_guide.mdc b/.cursor/rules/development/development_guide.mdc similarity index 82% rename from .cursor/rules/development_guide.mdc rename to .cursor/rules/development/development_guide.mdc index cc43b0005a..439c1f266c 100644 --- a/.cursor/rules/development_guide.mdc +++ b/.cursor/rules/development/development_guide.mdc @@ -1,7 +1,6 @@ --- -description: rules used while developing -globs: -alwaysApply: true +globs: **/src/**/* +alwaysApply: false --- ✅ use system date command to timestamp all interactions with accurate date and time ✅ python script files must always have a blank line at their end diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/docs/documentation.mdc similarity index 100% rename from .cursor/rules/documentation.mdc rename to .cursor/rules/docs/documentation.mdc diff --git a/.cursor/rules/markdown.mdc b/.cursor/rules/docs/markdown.mdc similarity index 100% rename from .cursor/rules/markdown.mdc rename to .cursor/rules/docs/markdown.mdc diff --git a/.cursor/rules/camera-implementation.mdc b/.cursor/rules/features/camera-implementation.mdc similarity index 100% rename from .cursor/rules/camera-implementation.mdc rename to .cursor/rules/features/camera-implementation.mdc diff --git a/.cursor/rules/legacy_dexie.mdc b/.cursor/rules/legacy_dexie.mdc deleted file mode 100644 index 82de6cca8a..0000000000 --- a/.cursor/rules/legacy_dexie.mdc +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -globs: -alwaysApply: true ---- -All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions. \ No newline at end of file diff --git a/.cursor/rules/version_control.mdc b/.cursor/rules/workflow/version_control.mdc similarity index 100% rename from .cursor/rules/version_control.mdc rename to .cursor/rules/workflow/version_control.mdc