refactor(cursor-rules): reorganize rules into logical directory structure

Restructure .cursor/rules from flat organization to hierarchical categories: - app/: application-specific rules (timesafari, architectural decisions) - database/: database-related rules (absurd-sql, legacy dexie) - development/: development workflow rules - docs/: documentation standards and markdown rules - features/: feature-specific implementation rules (camera) - workflow/: version control and workflow rules Add base_context.mdc for shared context across all rule categories. Improves maintainability and discoverability of cursor rules.
2025-08-16 08:38:25 +00:00
parent 328ac0f14b
commit 303f1bc565
11 changed files with 270 additions and 296 deletions
--- a/.cursor/rules/app/architectural_decision_record.mdc
+++ 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://<route>[/<param>][?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?  
--- a/.cursor/rules/app/timesafari.mdc
+++ b/.cursor/rules/app/timesafari.mdc
--- a/.cursor/rules/architectural_decision_record.mdc
+++ b/.cursor/rules/architectural_decision_record.mdc
@@ -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<boolean>;
  requestPermissions(): Promise<boolean>;
  isSupported(): Promise<boolean>;
  startScan(): Promise<void>;
  stopScan(): Promise<void>;
  addListener(listener: ScanListener): void;
  onStream(callback: (stream: MediaStream | null) => void): void;
  cleanup(): Promise<void>;
 }
 ```
 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://<route>[/<param>][?queryParam1=value1]
 interface DeepLinkParams {
  route: string;
  params?: Record<string, string>;
  query?: Record<string, string>;
 }
 ```
 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<boolean> {
  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.
--- a/.cursor/rules/base_context.mdc
+++ 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.
--- a/.cursor/rules/database/absurd-sql.mdc
+++ b/.cursor/rules/database/absurd-sql.mdc
@@ -1,7 +1,6 @@
 ---
-description: 
+globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, **/src/registerSQLWorker.js, **/services/AbsurdSqlDatabaseService.ts
-globs: 
+alwaysApply: false
 alwaysApply: true
 ---
 # Absurd SQL - Cursor Development Guide
--- a/.cursor/rules/database/legacy_dexie.mdc
+++ b/.cursor/rules/database/legacy_dexie.mdc
@@ -1,6 +1,5 @@
 ---
-description: 
+globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue
-globs: 
+alwaysApply: false
 alwaysApply: true
 ---
 All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions.
--- a/.cursor/rules/development/development_guide.mdc
+++ b/.cursor/rules/development/development_guide.mdc
@@ -1,7 +1,6 @@
 ---
-description: rules used while developing
+globs: **/src/**/*
-globs: 
+alwaysApply: false
 alwaysApply: true
 ---
 ✅ 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
--- a/.cursor/rules/docs/documentation.mdc
+++ b/.cursor/rules/docs/documentation.mdc
--- a/.cursor/rules/docs/markdown.mdc
+++ b/.cursor/rules/docs/markdown.mdc
--- a/.cursor/rules/features/camera-implementation.mdc
+++ b/.cursor/rules/features/camera-implementation.mdc
--- a/.cursor/rules/workflow/version_control.mdc
+++ b/.cursor/rules/workflow/version_control.mdc